前言¶

在 DSH（DeepSeek Harness）里做长对话时，主界面往往只有文本与工具调用；若想在同一会话旁增加一点氛围反馈，又不改输入框、不弹新面板，通常得自己写前端插槽、再接音频管线。古筝池塘插件走的是另一条路：输入区下方一颗按钮，子会话按内置乐理手册写谱，宿主离线合成 wav 入队，右下角透明水层只跟声音起伏，四角穿透、不接事件，原对话一字不动。

下面按定位、能力、安装与用法说明 shabe222/dsh-guzheng-pond（工作流类，MIT，当前包版本 0.3.0）。

这是什么¶

dsh-guzheng-pond 由维护者 shabe222 发布，挂在 DSH 社区目录 skillhub.cn/plugins/shabe222/dsh-guzheng-pond。

一句话：点按钮 → 当前对话派出子会话读乐理、写「琴语言」谱面 → 宿主调用渲染器在 headless Chrome 里合成 wav → 客户端播放，水层随响起伏；再点可暂停。整套交互只有两个触点：按钮与水，不弹窗、不加配置面板。

核心功能¶

端到端流程¶

你点输入框下方按钮后，大致链路如下（与 README 一致）：

你点输入框下面那颗按钮
        │
        ▼
   当前对话派出一个子会话
        │
        ├─ 读 pond_knowledge()   ← 工具自带的中国音乐 know-how
        ├─ 按「琴语言」写谱
        └─ 交回 pond_play(score)
                │
                ▼
        离线渲染成 wav → 入队
                │
                ▼
        右下角那汪水跟着响，再点一下暂停

水是纯装饰层，不影响原有对话与事件传递。

代码结构（便于排查）¶

子会话工具与 HTTP 接口¶

工具（子会话可见）：

• pond_knowledge — 读乐理手册全文，子会话第一步应调用。
• pond_play — 交谱面，同步渲染，返回时长、自查报告、技法统计。

宿主 /api/pond：

琴语言（谱面格式）¶

子会话输出极简记谱，例如：

@from 坐在窗边,风进来了
@to 合好窗扣,回到桌前
@turn 4
| 6/800 5/900 3/850 2/800 3/950 1/1000 ,3400
| 2/850 6/800 5/900 3/950 1/850 2/1000 ,3600
@2800

要点：1 2 3 5 6 为五声音级（无 4、7）；/800 为时值毫秒；句首行必须有 |，否则解析器会静默跳过该行。完整语法见包内 renderer/tray/knowledge/QLANG.md。插件在 0 句时会打回，不进入渲染。

安装与启用¶

插件以当前 DSH 进程权限运行，安装前建议阅读仓库源码与 MIT 许可证。社区目录与 DeepSeek / 幻方无官方从属关系，属「一切皆插件」生态中的独立条目。

前置¶

• DSH 0.1.x 或 0.2.x
• Node.js ≥ 18（须为本机 真 node，不能是 Electron 内嵌解释器）
• 本机 Chrome 或 Edge（渲染器借 Web Audio 离线合成）

步骤¶

1. 装渲染器依赖

cd renderer
npm install

渲染器仅依赖 playwright-core（约 15MB，不含浏览器）。

2. 装插件本体

npm pack
dsh plugin --profile web add ./dsh-guzheng-pond-0.3.0.tgz

dsh plugin add 只写入 profile 的 dependencies；还需在 dsh.profile.bundles 中加上包名。本地开发可用 link: 绝对路径，例如：

{
  "dependencies": {
    "dsh-guzheng-pond": "link:/path/to/dsh-guzheng-pond"
  },
  "dsh": {
    "profile": {
      "bundles": ["...", "dsh-guzheng-pond"]
    }
  }
}

装好后重启 DSH 进程。

3. 验证

curl --noproxy '*' http://127.0.0.1:3080/api/pond/state

返回 200 且 "knowledge": true 表示手册与宿主均就绪。若为 knowledge: false，多为找不到 renderer/tray/knowledge/CORE.md；404 则检查启动日志中的 plugin tree failed to load。

配置项¶

可在 profile 的 cordis.patch.yml 中按 id guzheng-pond 覆盖（覆盖既有挂载配置，不是新增挂载）：

- id: guzheng-pond
  config:
    projectDir: /path/to/my-guzheng
    nodeExe: C:/Program Files/nodejs/node.exe
    servePort: 8792
    maxQueue: 24

DSH 自身是 Electron，process.execPath 不是 node。用错会导致渲染子进程 silently 挂住。探测顺序：配置 → GUZHENG_POND_NODE → 常见路径 → PATH 中的 node。可选环境变量还有 GUZHENG_CHROME、GUZHENG_SERVE_PORT。

典型用法¶

在 DSH 里¶

1. 完成安装与 bundles 配置并重启。
2. 在对话输入区下方点池塘按钮，由子会话调用 pond_knowledge 后写谱并 pond_play。
3. 等待入队（README 记载单首渲染约 20–60 秒），右下角水层随播放起伏；再点可暂停。

不装 DSH，只跑渲染器¶

cd renderer
npm install

# 终端 1
npm run serve

# 终端 2
npm run render
# → out/demo.wav

自定义谱：写入 dev/xxx.js（导出 TEXT），然后：

node dev/render-qin.mjs xxx.js my-song.wav

适用场景与注意¶

适合： 希望在 Web 版 DSH 对话旁增加轻量氛围、又愿意接受「五声体、离线慢渲」约束的开发者；子会话编曲演示工作流类插件如何挂工具、API 与客户端插槽。

限制（README 明确）：

• 只支持五声音阶，谱面出现 4 或 7 会解析失败。
• Windows 上浏览器路径枚举更完整；macOS/Linux 建议设 GUZHENG_CHROME。
• 采样约 29 个音，缺音退化到邻近音高。
• 改 index.js 需冷启 DSH；改 client.js 刷新页面即可。profile 与包内 cordis.patch.yml 勿重复 insert 同插件。

开发踩坑： 包内 patch 的 name 只能写包名，不能写 ./node_modules/... 路径，否则整棵插件树可能 ERR_MODULE_NOT_FOUND。

卸载：从 dsh.profile.bundles 去掉包名 → dsh plugin --profile web remove dsh-guzheng-pond → 重启。

结尾¶

dsh-guzheng-pond 把「子会话读手册写谱 → headless 渲 wav → 队列播放 + 透明水 UI」收成一颗按钮，主对话协议不变。若要核对安装命令、接口与琴语言细节，以仓库 README 为准。

• 社区目录：https://www.skillhub.cn/plugins/shabe222/dsh-guzheng-pond
• 源码与文档：https://github.com/shabe222/dsh-guzheng-pond