前言¶

在 DSH（DeepSeek Harness）里做智能体，常见做法是加面板、改布局或插一堆工具入口。若你只想在不改变原有对话阅读体验的前提下，让模型根据乐理知识写谱并本地出音频，再把播放反馈叠在界面上，wuyetong-dev 维护的工作流插件 dsh-guzheng-pond 走的是另一条路：输入框下方一个按钮，右下角一汪可拖动、穿透事件的水，谱面由子会话按内置手册完成，再离线渲染成 wav 入队播放。水是装饰层，原有对话一个字都不受影响。

下面按定位、能力、安装、用法与限制说明如何接入与验证。

这是什么¶

• 名称：dsh-guzheng-pond（npm 包名一致，当前资料版本 0.3.0）
• 维护者：wuyetong-dev
• 分类：工作流（社区目录：SkillHub 插件页）
• 许可证：MIT

插件给 DSH 增加「点按钮 → 子会话读乐理手册编曲 → 交谱面 → headless Chrome 离线合成 wav → 客户端队列播放，水层随声音起涟漪」的闭环。整套对外只有两种交互：一个按钮、一汪水；不弹窗、不加面板、不改对话正文。

核心功能¶

端到端流程¶

点击输入框下方按钮后，当前对话会派出子会话，大致路径如下：

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

架构分工¶

子会话可见工具¶

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

HTTP 接口（宿主 /api/pond）¶

安装与启用¶

插件以后台与 DSH 同进程权限运行；安装前请自行查阅仓库源码与 MIT 许可证。社区目录站点与 DeepSeek / 幻方无官方从属关系，按「一切皆插件」的 DSH 生态自行选型即可。

0. 前置¶

• DSH 0.1.x 或 0.2.x
• Node.js ≥ 18（须为系统 真 node，不能误用 Electron 内嵌环境，见下文 nodeExe）
• 本机已安装 Chrome 或 Edge（渲染器借浏览器 Web Audio 做离线合成）

1. 安装渲染器依赖¶

cd renderer
npm install

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

2. 安装插件本体¶

资料中的安装方式为打包后写入 profile（勿凭包名自行拼接 dsh plugin add github:owner/repo）：

npm pack                                    # 得到 dsh-guzheng-pond-0.3.0.tgz
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。

典型用法¶

界面上¶

1. 在对话 composer 下方点按钮，触发子会话按手册用「琴语言」写谱并渲染。
2. 音频入队后右下角水层随声起伏；再点可暂停。水层可拖动，四角穿透，不接点击事件。

琴语言（谱面）要点¶

子会话产出的是极简记谱，例如：

@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。
• 每句行首必须有 |，否则解析器会静默跳过该行。
• 完整语法见包内 renderer/tray/knowledge/QLANG.md。

不装 DSH 时单独跑渲染器¶

cd renderer
npm install

# 终端 1
npm run serve                 # http://127.0.0.1:8792

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

自定义谱：写到 dev/xxx.js（导出 TEXT），再执行：

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

配置与运维注意¶

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

- id: guzheng-pond
  config:
    projectDir: /path/to/my-guzheng      # 默认 <包根>/renderer/
    nodeExe: C:/Program Files/nodejs/node.exe
    servePort: 8792
    maxQueue: 24

DSH 自身是 Electron，process.execPath 不是 node。未配置 nodeExe 时插件会依次尝试 GUZHENG_POND_NODE、常见路径与 PATH 中的 node；找不到会明确报错。环境变量示例：

GUZHENG_POND_NODE=/usr/local/bin/node
GUZHENG_CHROME=/usr/bin/google-chrome
GUZHENG_SERVE_PORT=8792

开发时：改 index.js 须冷启 DSH（HMR 跳过 node_modules）；改 client.js 刷新页面即可。包内 cordis.patch.yml 的 name 只能是包名；profile 侧勿重复 insert，避免挂两份导致插件树异常。

适用场景与限制¶

适合：希望在 Web 版 DSH 对话流里做「模型作曲 + 本地可信渲染 + 极简 UI」、且接受五声音阶与传统记谱约束的团队或个人。

限制（README 已写明）：

• 只支持五声音阶，谱面出现 4 或 7 会解析失败。
• Windows 浏览器路径探测最全；macOS/Linux 建议设 GUZHENG_CHROME。
• 单首渲染约 20–60 秒；采样约 29 个音，缺音退化到邻近音高。

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

结尾¶

dsh-guzheng-pond 把编曲、离线 wav 与角落水声反馈收成「一个按钮 + 一汪水」的工作流，对话正文保持原样。更多细节与源码见 GitHub 仓库，目录索引见 SkillHub 插件页。