前言¶
在 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 → 入隊
│
▼
右下角那汪水跟着響，再點一下暫停
水是純裝飾層，不影響原有對話與事件傳遞。
代碼結構（便於排查）¶
| 部分 | 路徑 | 作用 |
|---|---|---|
| 宿主插件 | index.js |
cordis 插件：註冊 pond_knowledge / pond_play、/api/pond/*、派子會話 |
| 客戶端 | client.js |
shell.overlay 放水，conversation.composer.dock 放按鈕 |
| 水層 | assets/water.js、assets/gl-water.js |
從 /api/pond/asset/ 加載 |
| 渲染器 | renderer/ |
琴語言解析 + Web Audio，headless Chrome 離線渲 wav |
| 樂理手冊 | renderer/tray/knowledge/ |
子會話寫譜依據 |
子會話工具與 HTTP 接口¶
工具（子會話可見）：
pond_knowledge— 讀樂理手冊全文，子會話第一步應調用。pond_play— 交譜面，同步渲染，返回時長、自查報告、技法統計。
宿主 /api/pond：
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /state |
隊列、項目路徑、手冊是否讀到 |
| POST | /task |
{sessionId, idea} → 派子會話編曲 |
| POST | /submit |
{title, score} → 直接交譜，同步返回渲染結果 |
| POST | /queue |
{op:'played', id} → 播完出隊 |
| GET | /audio/<id>.wav |
音頻流 |
| GET | /asset/<name> |
水層資源 |
琴語言（譜面格式）¶
子會話輸出極簡記譜，例如：
@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
| 鍵 | 默認 | 說明 |
|---|---|---|
projectDir |
<包根>/renderer |
渲染器與知識手冊根目錄 |
nodeExe |
""（自動探測） |
跑渲染用的真 node |
servePort |
8792 |
靜態服務端口 |
maxQueue |
24 |
隊列上限，超出丟棄最舊 |
DSH 自身是 Electron，process.execPath 不是 node。用錯會導致渲染子進程 silently 掛住。探測順序：配置 → GUZHENG_POND_NODE → 常見路徑 → PATH 中的 node。可選環境變量還有 GUZHENG_CHROME、GUZHENG_SERVE_PORT。
典型用法¶
在 DSH 裏¶
- 完成安裝與
bundles配置並重啓。 - 在對話輸入區下方點池塘按鈕，由子會話調用
pond_knowledge後寫譜並pond_play。 - 等待入隊（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 爲準。
