前言¶

在 DeepSeek Harness（DSH）里做 Scratch 类创作，常见做法是改 .sb3 压缩包里的 JSON，或手写积木 XML。前者难对齐编辑器语义，后者缺少「跑起来、看舞台、再改」的闭环。共创世界 Gandi IDE 桌面版本身是完整的 Scratch 编辑器，但普通自动化很难像人一样点绿旗、拖积木、载入扩展。

下面介绍社区插件 dsh-gandi（维护者 yee114514）：它不修改 Gandi，也不往工程里塞隐藏内容，而是通过 Chrome DevTools 协议（CDP）连进正在运行的编辑器，给 agent 一组 gandi_* 工具；同时支持不打开 Gandi 时直接读写 .sb3。插件当前版本 0.0.1，许可证 MIT，在 SkillHub 目录 分类为「客户端」，GitHub 星标为 0。

这是什么¶

dsh-gandi 的定位是：让 DSH 的 agent 在你正在用的 Gandi 里完成 Scratch 项目——写脚本、画造型、加声音、跑起来、看截图，然后接着改。插件把在线作品导出为本地 .sb3 供 agent 修改；不会替你保存或发布云端版本。要持久化改动用 gandi_save，下次用 gandi_open 读回。

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

核心功能¶

对着编辑器操作¶

• 写脚本：用 Scratch 可读的积木 XML，支持自定义积木和脚本注释。
• 扩展：音乐、画笔、文字朗读、3D、AI 等；先 gandi_extension 载入，积木的输入名和下拉菜单从编辑器读取，避免「看起来对、跑起来没反应」。
• 美术与音频：造型/背景可写 SVG 或位图；声音可按音高和时长合成。
• 工程结构：建变量、列表、角色，改名字、摆位置、调大小。
• 运行与观测：点绿旗、按固定帧率推进、返回坐标和变量值；可附舞台截图（模型需能看图片，否则截图会降级为写到路径由你自行读取）。
• 输入模拟：在 gandi_run 的 input 里按秒安排按键/鼠标，用于测「按住走、松开停」等交互。

离线改 .sb3¶

手上已有 .sb3 时，可用 gandi_inspect {path}、gandi_apply {path} 读写，无需打开 Gandi。画造型、加声音、跑项目等仍需要编辑器运行时。

编辑权与可见性¶

多人或人机共用时，插件有 lease（空闲约 60 秒后让出，可 gandi_lease 或 force: true）。Gandi 窗口里插件打开的编辑器视图会置前，但不抢系统焦点；你在 Gandi 里切回主页时，下次改工程前插件会把编辑器视图切回最前（不丢状态，极端情况重建视图会在工具输出里注明）。

安装与启用¶

安装命令以 README 为准（可装进 dsh-tui 或 web profile，或两个都装）：

# 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；宿主面插件不支持热重载。

也可在 profile 的 cordis.patch.yml（$DSH_HOME/profiles/<profile>/cordis.patch.yml）中写入：

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

常用配置键可用环境变量覆盖：GANDI_APP_PATH、GANDI_PORT（默认 9222）、GANDI_AUTO_LAUNCH 等；完整表格见仓库 README。

前置条件¶

两个常见情况：

1. Gandi 停在「我的作品」列表、gandi_status 显示 editor tab: none——正常，其它 gandi_* 会先开编辑器页签。
2. 已打开的 Gandi 没有调试端口时永远连不上，且插件不会替你关掉它。省事做法：gandi_launch {launcher: true} 在开始菜单创建 Gandi (DSH attachable) 快捷方式；或 gandi_launch {patchShortcuts: true} 改现有桌面图标；需重启当前实例时用 gandi_launch {restart: true}（礼貌关闭，非 taskkill）。

手动启动示例：

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

典型用法¶

扩展积木¶

扩展积木在载入前不存在，顺序固定：

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

opcode 带扩展 id 前缀；下拉字段名以 gandi_extension 输出为准。未载入就写对应积木时，gandi_apply 会拒绝并提示先载入哪一个。设备类扩展（摄像头/麦克风）在 gandi_extension {action:'list'} 中会标 [uses a device]；载入后插件会主动关设备并在结果里说明。

测交互¶

按键须在绿旗之后生效，用 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}
]}

工具入口¶

出问题先看 gandi_status。常用工具包括：gandi_launch（就绪/快捷方式/重启）、gandi_new / gandi_open / gandi_save、gandi_apply（可 dryRun: true）、gandi_run / gandi_observe / gandi_screenshot、gandi_merge（合并另一份 .sb3 的角色）等。完整列表见 GitHub README。

写脚本前 gandi_apply 加 dryRun: true 可只校验；会导致项目打不开的脚本会被拒绝应用。路径默认限制在会话工作目录，写到外面需配置 allowOutsideWorkspace: true。

适用场景与注意¶

适合：希望在 DSH 对话里让 agent 在真实 Gandi 编辑器中迭代 Scratch 作品；或已有 .sb3 需要 agent 批量改脚本/XML 再回编辑器验证。

注意：

• 插件以当前 DSH 进程权限运行，安装前请自行查看 源码 与 MIT 许可证。
• 它不碰你的云端作品；云端保存与发布仍须你在 Gandi 里操作。
• DSH 生态是「一切皆插件」；SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-gandi 把 Gandi 变成 agent 可驱动的 Scratch 工作台：CDP 连 live 编辑器，外加离线 .sb3 工具链，并强调可运行、可截图、可模拟按键的验证闭环。目录页：https://www.skillhub.cn/plugins/yee114514/dsh-gandi；仓库：https://github.com/yee114514/dsh-gandi。