CLI 与本机 MCP

让同一台电脑上的 Agent 通过 CLI 或兼容 MCP 适配器读写浏览器里打开的作品。 当前 main 工作区的新入口是设置 → AI →「CLI」→「连接 CLI」；一次网站授权后自动重连。 CLI 面向 AI，通过 gandi --help、gandi guide start 与 gandi tools 按需查询，不要求阅读新手教程。 新连接实现尚未发布 npm 或部署线上；本页下方旧配对码界面与截图仅描述兼容 MCP 路径，不是新的正常 CLI 流程。

打开方式#

顶栏齿轮 →「AI」→「本机 MCP」，在这一页的最上面。

启动本机 MCP#

MCP 进程是编辑器仓库里的 scripts/gandi-mcp.mjs，也可以用 npm run mcp 启动。它是一个 stdio MCP 服务器， 通常把它配置进 AI 工具的 MCP 服务器列表，由 AI 工具启动。

进程启动后在标准错误输出里打印一行：

[Gandi MCP] Port: 17394; in the editor open Settings > AI > Local MCP; pairing code: <48 位十六进制>

• 端口固定为 127.0.0.1:17394，只接受本机连接。
• 配对码存在本机用户目录的文件里，进程重启后不变。要换一个码，带 --new-code 启动，或删掉那个文件。
• 同一时间只能有一个编辑器页配对。另一个页再来配对会被拒绝。
• 17394 端口已被占用（多半是另一个 MCP 进程还开着）时，进程启动失败并说明原因。
• 它不提供读写电脑文件的工具，能动的只有已配对的这个作品。

配对#

把配对码填进「配对码」一栏，按回车或点击「连接」。配对成功时弹出通知「已连接本机 MCP」。

编辑器会记住配对码（只存在这个浏览器里），下次打开编辑器时自动连上，不用再填。MCP 进程还没启动也可以先填：编辑器会等它，启动后自动连上。

连接失败时的原因：

配对被拒、连接断开时右上角会弹出通知，不在设置页里也能看到；断开后又自动连上时，再弹一次「已连接本机 MCP」。 打开编辑器时的自动连接失败不弹通知。

关闭设置对话框不会断开连接。刷新编辑器页后会用记住的配对码自动连回去。

顶栏标记#

配对后，顶栏右区出现一枚带绿点的「MCP」标记；重连期间绿点变为黄色。点击标记直接打开「设置 → AI」并 落到「本机 MCP」。未连接时顶栏不显示任何东西。

安装 Gandi CLI（独立本机桥）#

main 工作区提供 @gandi/cli 本地安装预览包；尚未发布到 npm。 从 gandi-gui-3.0/ 安装 npm install -g ./packages/gandi-cli，用 gandi start 幂等启动后台服务； gandi stop 停止连接但不撤销授权，gandi connect 保留前台调试模式。npm 发布后才能使用注册表安装命令。

线上 HTTPS 编辑器点击「连接 CLI」，由用户在本机授权页确认准确网站来源及作品/扩展/联网权限。 网站专用凭据保存在该网站浏览器存储，本机只存哈希；后续请求不依赖跨站 cookie。浏览器可能另需本机网络访问许可， 不绕过权限、混合内容或 CSP 限制。同源脚本/XSS 可读取网站凭据，只在可信网站授权；清除网站数据或换浏览器需重新授权。 同机本地 HTTP 127.0.0.1 编辑器保留 cookie 兼容授权。Agent 使用 gandi editors、gandi use ID、gandi doctor、gandi bind。

原有 npm run mcp 保留薄 stdio 适配器与独立配对兼容路径；配对码不是正常 CLI 流程。

CLI 的短命令调用的是同一编辑器工具：Agent 能按角色目录拆成多个 .js 积木页和文件夹，逐文件读取 版本、写入、检查、运行、查看舞台；gandi extensions 关键词 可按需搜索当前远端扩展服务的目录， gandi extension ID 可以按准确 ID只读查询另外一批 CCW 社区素材集市扩展。集市没有已验证的 完整列表接口；不能把「没有搜到」说成「所有扩展都没有」。主动搜索不需许可；安装扩展会执行代码， 已一次授权的网站连接复用明确授权，兼容未授权连接仍单独审批。CLI 适用于浏览器与 Agent 在同一台电脑的情况，网页可以来自线上 HTTPS 站点。

执行安全与按需契约#

CLI 和 MCP 共享运行时工具契约：gandi tools [关键词] 返回/过滤参数 JSON schema、副作用、绑定、审批和版本要求；gandi guide start|project|variables|testing|assertions 离线可读，项目操作范例与浏览器复用同一份，其余依赖当前 schema 的 topic 从已配对编辑器读取。gandi <命令> --help 提供具体参数帮助。未知参数不会静默忽略。

• CLI gandi bind、MCP bind_project 显式绑定当前桥 session。换工程后必须重新绑定，不能在写入时自动绑定。
• 浏览器所有请求还绑定工程 generation；作品开始清空时立即失效，审批/异步准备后和实际提交前重检。断线、超时、取消会清理待审批请求并阻止后续提交。
• 已发生的副作用不能由取消自动撤回：扩展已经开始执行第三方代码或已经提交的写入必须如实报告。第三方执行不是安全沙箱。
• 可取消的扩展加载目前仅接受自包含全局注册 bundle；原生 import/export、import.meta、动态模块图等以 E_EXTENSION_MODULE 明确拒绝，不声称保留这些图的相对或 bare-import 语义。请先把扩展打成自包含脚本；不会退回存在晚到执行风险的远程 <script src>。
• CLI/MCP 整份还原先校验字节、保存备份，再返回 accepted: true, completed: false；该响应入发送队列后才开始工程替换。完成后重新绑定，通过 runner_status.projectReplacements 的 operationId 查询完成/失败结果。加载中的普通工具仍关闭，不把接收回执说成还原成功。UI 还原按钮仍等待实际完成。
• VFS 版本包括隐藏积木输入、实体身份和相关变量依赖；实际同步提交边界执行 CAS。回滚和按轮撤销逐文件重查权限，只恢复仍是本批写后版本的状态。外部改动、撤权或不支持身份保持恢复的删除会 skip 并给出原因，不覆盖人类修改。
• 审批按请求排队，换工程和取消会结束原等待。注释 DSL、快捷添加、CLI/MCP 均经过扩展安装确认与作品权限检查；check 保持只读。
• 正常运行默认后台舞台；真实舞台 runner: 'host-stage' 需要绑定、编辑权限且逐帧核对工程。
• 可用 GANDI_CLI_HTTP_PORT / GANDI_CLI_WS_PORT 与 GANDI_CLI_ENDPOINT 配置测试端点。生产浏览器来源默认允许 loopback 及 https://gandi.kuke.ink，其它主机需显式 GANDI_CLI_ALLOWED_ORIGINS。测试使用随机端口。

CLI 实测后的验证用法#

• 新建角色先 gandi files --kind sprite 读取实际场景段，再按 gandi guide project 新建 sprite.json；返回后使用带 ID 后缀的真实目录，不猜路径。变量优先用 DSL 声明，或读取/合并 ID-keyed 的 variables.json；check 不会创建声明，重复声明不会重置现值。
• read 返回 revision 依赖名称，E_CONFLICT 带 expected/actual rev 和发生变化的分项；分项是有界缓存中的哈希比对，缓存失效标记 unknown。CAS 仍包括完整隐藏状态/共享变量，不能盲换 rev 强写。
• 按 nominal frame 推进的模拟时间覆盖 timer/wait/glide/deltaTime/物理/粒子；执行耗时仍是真实 ms，不覆盖音频/网络/第三方自行读墙钟。默认暂停保留线程，greenFlag:false 续跑；stopAfter:true 停止线程，不等于可续暂停。细节看 gandi guide testing。
• 键盘/鼠标输入 frame 从每次调用的 0 开始，在对应帧前注入；鼠标坐标为舞台中心坐标。点击需要分帧按下/松开，越界帧和同帧矛盾输入明确报错；setup 是受控状态，不是正常操作证据。
• 自动验收用 check/assert/run --strict-exit：语义失败 exit 2，stdout 仍完整，stderr 为 E_VERIFICATION_FAILED；默认保持旧行为 exit 0。assert 表达式不是 JS/JSONPath，写法看 gandi guide assertions。
• view --output stage.png 真实编码 PNG，.jpg/.jpeg 为 JPEG；MIME、base64、文件签名与扩展名一致才落盘。截图是 renderer-only，不包含变量/列表 monitor DOM 或编辑器 UI；气泡依 renderer 能力，返回 describes 说明范围。
• blocks control wait --paged --limit 10 --offset 0 多词搜索安装 schema 的类别/操作码/DSL名/中英文；分页有 total/hasMore/nextOffset，旧未分页调用仍为数组。
• 后台造型预热不再等待隐藏 iframe 的 rAF，逐帧让出走消息任务。runner_status.progress 提供加载/编译/skin 进度；响应超时为 E_RUNNER_TIMEOUT 并包含阶段，不再无证据称为程序失控。

AI 能做什么#

工具清单由 MCP 进程提供给 AI 工具，主要几类：

• 读：列出和读取作品的虚拟文件（积木页、造型、声音、装配等）、作品大纲、搜索、积木写法说明。
• 写：写文件、打补丁、装扩展。
• 跑：运行作品、读变量和角色状态、断言、查看舞台和造型的图像、读诊断。默认在看不见的后台舞台上 进行，不占用编辑器里的舞台。
• 撤销：AI 的修改按轮记录，可以整轮撤销；开始新一轮时先存一个还原点。

在多人协作里，AI 的改动按配对者本人的权限检查，并实时同步给房间里的人。

相关#

• 设置
• AI 服务商 —— 同一页下面的「服务商」
• 还原点
• 多人协作