dsh-gandi

dsh-gandi

让 DSH 的 agent 在你正在用的 Gandi（共创世界 Gandi IDE 桌面版）里做 Scratch 项目： 写脚本、画造型、加声音、跑起来、看截图，然后接着改。

它不修改 Gandi 本身，也不往你的项目里塞看不见的东西——只是在旁边操作它， 就像另一个坐在电脑前的人。

它不碰你的云端作品。 Gandi 的编辑器开的是你账号里的在线作品；这个插件只把项目 导出成本地 .sb3，不会替你保存或发布云端版本。要接着改就 gandi_save， 下次 gandi_open 读回来。

---

它能做什么

对 agent 说一句「用 gandi 工具做个接苹果的小游戏」，它就会自己开工： 开一个编辑器页签 → 新建项目 → 画苹果和篮子 → 写脚本 → 按键测试 → 看舞台截图 → 发现问题再改。

具体一点，它能：

• 写脚本：用 Scratch 自己的积木方言（可读的 XML），支持自定义积木和脚本注释。
• 用扩展：音乐、画笔、文字朗读、3D、AI…… 先把扩展载入编辑器，它的积木就能像自带积木一样写。 每个积木的输入名和下拉菜单都是从编辑器里读出来的，所以不会写出"看起来对、跑起来没反应"的积木。
• 画美术：造型和背景直接写 SVG；也可以给位图。
• 加声音：给个音高和时长就合成一个（上滑＝跳跃/得分，下滑＝失败，游戏音效基本就这两种）。
• 建变量、列表、角色，改名字、摆位置、调大小。
• 真的跑起来：点绿旗、推进 N 秒、返回坐标和变量值，还能截图给模型"看"。
• 模拟键盘和鼠标：这是测游戏唯一靠谱的办法——按住空格键，看小人有没有动。 按键可以安排在跑到第几秒按下，所以"按住会走、松开就停"一次就能测完。
• 不打开 Gandi 也能改文件：手上有个 .sb3，可以直接读它、改它、存回去。

快速开始

# 1. 装进你要用的 profile（两个都装也可以）
dsh plugin --profile dsh-tui add https://github.com/yee114514/dsh-gandi
dsh plugin --profile web     add https://github.com/yee114514/dsh-gandi

# 2. 告诉插件 Gandi 装在哪（也可以写进配置文件，如下）
$env:GANDI_APP_PATH = 'E:\Gandi\Gandi.exe'

# 3. 重启 DSH

装完可以用 dsh --profile <profile> --dump-config 确认配置里真的出现了 gandi 这一行。第一次安装如果中途断网，可能会静默回滚（配置文件不变）， 重跑一次即可。

改完代码要重启 DSH 才生效。 宿主面插件不支持热重载。

前置条件

插件通过 Chrome DevTools 协议连进编辑器，所以 Gandi 必须带调试端口启动。 gandi_launch 会替你加这个参数，也会替你开一个编辑器页签。

两个必须知道的坑

1. Gandi 启动后停在"我的作品"列表页，没有编辑器。 编辑器是单独一个页面， 只有开了作品才存在。所以 gandi_status 里会看到 editor tab: none——这不是错误， 任何别的 gandi_* 调用都会先要一个页签。

2. 一个没带调试端口启动的 Gandi，永远连不上——而且插件不会去关它。 Chromium 的调试服务只在进程启动时创建，运行期没有开关能补上。所以：

• 插件不会替你关掉已经开着的 Gandi，也不会在旁边再拉一个（那是两个窗口）；

• 它会报错并告诉你出路。最省事的一条是用带端口的快捷方式启动：

  gandi_launch {launcher: true}
  

  这会在你的开始菜单里放一个 Gandi (DSH attachable)（用户级、不需要管理员、 删掉即恢复）。以后从它打开 Gandi，模型就能直接用你已经开着的那个窗口， 不会再有"关掉再拉起"。 如果你想让现有那个桌面图标也带上端口，明确要求一次即可： gandi_launch {patchShortcuts: true}（它会逐个报告改了哪几个、原来是什么参数）。

• 确实需要重启当前那个 Gandi 时，gandi_launch {restart: true}：插件用 CloseMainWindow（等于点窗口的 ✕，App 有机会问你要不要保存）礼貌关闭，再启动带端口的。 不会 taskkill，没保存的东西不会跟着没。

编辑器要联网、要登录。断网或没登录时页签开出来是空的， gandi_launch 会等到超时并告诉你原因。

想自己启动的话：

Gandi.exe --remote-debugging-port=9222

你能看见模型在做什么

Gandi 的窗口里是"一个 shell + 一堆视图"：项目浏览器（主页）是一个视图，每个作品是 另一个视图，同一时刻只有一个在屏幕上。插件打开的编辑器视图一定在最前面， 所以正常情况下你点开 Gandi 就能看着模型改积木、加造型、跑项目。

两条边界，都是刻意的：

• 绝不抢你的焦点。 Gandi 被别的窗口挡住时，插件什么都不做（不会把它弹到最前）。 你切回 Gandi 时，编辑器就是当前那个视图。
• 如果你在 Gandi 里点了主页（或点了自己的作品标签），那些是有标签的视图， 而插件的编辑器没有标签；下一次真正改东西之前，插件会把编辑器切回最前—— 这一步不重新加载、不丢状态（切不动时才会重建视图并把工程整体搬过去，那种情况会在 工具输出里明确写一行 NOTE，因为 undo 历史会没）。 gandi_status 里的 editor on screen: 一行随时告诉你当前是哪种状态。

配置

写进 profile 的 cordis.patch.yml（$DSH_HOME/profiles/<profile>/cordis.patch.yml）：

- id: gandi
  config:
    appPath: 'E:\Gandi\Gandi.exe'
    port: 9222
    autoLaunch: true

每个键都有默认值，都可以省略。因为"Gandi 装在哪"是机器级事实、在两个 profile 里 写两遍很烦，所以也支持环境变量覆盖：

工具一览

写脚本前可以先 gandi_apply 加 dryRun: true：只检查不落地（给 path 时还会把改动 套到副本上按编辑器的读法验一遍）。会让项目打不开的脚本会被拒绝应用，免得留下半个坏项目。

用扩展积木

扩展就是编辑器「添加扩展」里那些类别。它的积木在载入之前不存在，所以顺序是固定的：

gandi_extension {action: "load", id: "music"}     # 载入，并把方言打出来
gandi_apply {xml: "…<block type=\"music_playDrumForBeats\">…"}

gandi_extension 的输出里带着这个扩展每个积木的 opcode、输入名、下拉 shadow 类型和字段名， 照着写就行。三条规则：

• opcode 带扩展 id 前缀（music_restForBeats、pen_penDown）——前缀就是"编辑器要载入谁"。
• 下拉的字段名不一定等于菜单名：music_menu_DRUM 用 DRUM，pen_menu_colorParam 用 colorParam。 从 gandi_extension 的输出里抄，别按名字猜。
• 没载入就写它的积木，gandi_apply 会拒绝并告诉你该载入哪一个（而不是写出一个跑起来没反应的积木）。 只改文件（给 path）时没有编辑器可问，积木按名字写进文件、扩展记进文档，编辑器打开时自己载入。

载入扩展是编辑器自己的动作（和用户点「添加扩展」同一条路），所以载入后工具箱里也会出现这个类别， 用户能自己拖这些积木。

整个库都能用：逐个载入实测过，编辑器目录里 89 个未禁用的扩展成功了 88 个 （唯一失败的 whiteBoard 是编辑器自己载不动它——手点「添加扩展」也是同样的错）。

注意：有几个扩展是"设备类"的（GandiKamera、faceSensing、视频侦测…）。 只要载入它们，编辑器就会打开摄像头/麦克风——不需要真的去用那些积木，而且编辑器不会主动关。 gandi_extension {action:'list'} 会给这些 id 打 [uses a device] 标记；插件在载入后会主动把设备关掉， 并在结果里说明刚才开了什么。你自己在 Gandi 里点「添加扩展」时同样会发生这件事。

运行是确定的：30 帧/秒

gandi_run 跑的时候会暂停编辑器自己的步进循环，只由插件按 1000 / currentStepTime 的真实节奏推进。所以同样的命令跑两次结果一致，也和 Gandi 窗口在不在前台无关。

这一条曾经是错的，而且错得很隐蔽：用户点过一次绿旗之后，编辑器自己那个 30 Hz 的循环 （runtime.frameLoop，setInterval 驱动 runtime._step）还在跑，插件再推进 30 次， 项目一秒就走了 60 帧——前台翻倍、后台正常。一次真实交付就是按这个"实测 60 fps" 把物理常数调快的。node tools/e2e.mjs 里有一条守着它（循环体带 wait 0 的计数器， 一秒应该数到约 30）。

测交互的正确姿势

按键要按在项目跑起来之后。先按键再点绿旗是不行的——绿旗会停掉所有脚本并清空按键状态。 所以用 gandi_run 的 input：

gandi_run {seconds: 1, input: [{atSeconds: 0, key: 'space', isDown: true}]}

想测"按住会走、松开就停"，把两条都写进同一次运行：

gandi_run {seconds: 1, input: [
  {atSeconds: 0,   key: 'space', isDown: true},
  {atSeconds: 0.5, key: 'space', isDown: false}
]}

两种用法

两种方式用同一套脚本格式，所以「读出来 → 改 → 写回去 → 打开看」是一条完整通路。

路径默认限制在会话工作目录内；要写到外面得显式开 allowOutsideWorkspace。

排错

当前限制

• 云变量没做。
• 扩展能用，但 Gandi 的"插件"体系（插件设置里填 URL 加载 JS）没做，也不打算做： 那是改编辑器的路子，本项目只在外面驱动它。
• 扩展要显式载入：插件不会因为你写了一个 music_* 积木就偷偷替你载入（gandi_apply 会拒绝并告诉 你该载入哪个）。载入是编辑器自己的动作，所以会出现在工具箱里——用户也能自己拖这些积木。 载入状态按页签算，换作品要重新载入；载入过的扩展不会因此写进工程，只有真的用了它的积木才会。
• 它不是 Gandi 的插件。 不会出现在 Gandi 的插件设置里，也不改 Gandi 的界面或代码—— 它是从外面通过调试端口驱动编辑器，所以 Gandi 得开着、并且带调试端口。
• 不发布到 npm，所以不能按包名安装，要指定路径： dsh plugin --profile <p> add E:/dsh-gandi。 （顺带说明：dsh plugin 本身就是把参数转发给 profile 目录里的 pnpm，没有额外的插件市场。）
• 只在 dsh-tui 和 web 上验证过，没在 desktop surface 上验证。
• 「新建角色」的实现是"复制一个已有角色，再把脚本、私有变量和造型清空换成你给的"， 所以项目里至少要有一个角色可复制——这就是新建项目会自带一个起始角色的原因。
• 每次连上编辑器要等约 10 秒：Gandi 启动时总要载入一个默认项目，插件得等它载完 才能安全地换成你的项目。这不是可以省掉的等待。
• 插件打开的编辑器视图没有标签。 Gandi 的标签栏只登记它自己开的作品，所以那个视图 不能靠点标签回来；插件靠"切回最前"（见《你能看见模型在做什么》）保证它在你眼前， 但如果你在 Gandi 里关掉它（没有标签，正常也点不到），下一次调用会再开一个。
• 绝不抢窗口焦点：Gandi 在别的窗口后面时，你在切回去之前看不到进度。 这是用户的显式选择，不是没做。
• 一个没带调试端口的 Gandi 无法接管（Chromium 的限制），插件只会拒绝并说明， 不会替用户关掉它。
• 载入设备类扩展会开摄像头/麦克风（见《用扩展积木》）。插件载入后会主动关掉并如实报告， 但"要不要载入"这件事本身是你（或模型）决定的——列目录时会标出来。
• whiteBoard 这个库内扩展在这台编辑器上载不动（编辑器自己抛 manifest 错）， 手点「添加扩展」也一样。其余 88 个实测都能载入。

卸载

dsh plugin --profile dsh-tui remove dsh-gandi
dsh plugin --profile web     remove dsh-gandi

删掉即可完全还原：它不写应用数据目录，不改 Gandi，也不打包任何 Scratch 美术资源 （起始造型和背景都是插件自己画的几行 SVG）。

唯一一处例外是你自己要求的那次：gandi_launch {launcher: true} 会在 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Gandi (DSH attachable).lnk 放一个快捷方式， gandi_launch {patchShortcuts: true} 会改已有快捷方式的参数。删掉那个 .lnk （用 patchShortcuts 的话，把参数里多出来的 --remote-debugging-port=… 去掉）就回到原样。

---

想改这个插件

开发相关的约定、上游陷阱、怎么跑测试、怎么加新工具，都写在 AGENTS.md 里；Gandi 侧的实测结论（含出处）在 docs/gandi-spike.md。这两份是给改代码的 agent 看的， 这份 README 是给人看的。

一句话版本：

node --test                 # 单元测试
node tools/e2e.mjs          # 验收测试（会驱动真的编辑器）