PerryLink/dsh-plugin-guide

DeepSeek Harness 插件開發（dsh-plugin-guide）

依據官方資料開發 DeepSeek Harness 插件。本技能是工作流程與約束清單；事實細節一律引用知識庫原文，不憑記憶編造。所有「必須/不得」條款來自官方倉庫 AGENTS.md、docs/ 與文檔站，衝突時以官方原文為準。

知識庫位置（依序尋找，使用第一個存在的）

本技能與知識庫隨同一目錄分發（本 SKILL.md 所在目錄即知識庫根），路徑均為相對路徑；單獨複製本檔案而不帶 guide/、references/ 時依回退路徑尋找：

1. 本檔案同目錄：./guide/（綜合指南+速查表+文檔連結索引）、./references/（調研報告與官方文檔全文副本 references/official-docs/docs/）、./downloads/（原始下載物，可選）
2. 本機主副本：D:\deepseek-harness\Project\Plugins\dsh-plugin-guide\（範例路徑，請依本機實際安裝位置調整）
3. 官方倉庫 checkout：D:\deepseek-harness\（docs/、vendor/cordis/、packages/、examples/）
4. 線上：https://github.com/deepseek-ai/deepseek-harness 、 https://deepseek-harness.github.io/deepseek-harness/develop/basic/ 、 https://github.com/cordiverse/cordis

下文相對路徑預設相對上述第 1 條（本技能檔案所在目錄）。

開發前置（第一步必做）

1. 若未讀過 Cordis 概念：讀 references/official-docs/docs/cordis-primer.md（5 個概念，5 分鐘）；需要動手跟練時執行 references/official-docs/docs/cordis-tutorial/ 01-07（無 API key 亦可執行）。
2. 打開 guide/quick-reference.md（契約速查）+ guide/plugin-dev-guide.md（完整路徑）。官方/社群文檔 URL 對照見 guide/links.md。
3. 確認目標擴展點：讀 references/official-docs/docs/architecture.md 的「Where new behavior goes」表與 references/official-docs/docs/cookbook/extension-cookbook.md 的 feature→mechanism 表——新行為必須掛到已文件化的擴展點，不得修改 agent-loop。

必須遵守的插件契約（官方紅線，逐條核對）

• 插件 = 模組匯出 name + apply(ctx, config)（+可選 inject: string[]）；依賴的服務在 apply 前就緒；依賴服務消失會自動卸載、恢復後自動重新載入。
• 註冊即 effect：一切貢獻走 ctx.effect() / ctx.on() / 服務 register()（傳回 disposer）；絕不手動 removeListener/clearInterval 式收尾。
• waterfall 監聽器必須呼叫 next()；不呼叫 = 故意短路（攔截語意）。emit/waterfall/parallel/serial/bail 語意見速查表。
• 模型可見 ⟺ 已記錄：進入模型請求的一切必須能從會話日誌重建；新增模型可見輸入必須新增 SessionEventMap 會話事件。
• 型別安全事件/服務用 declaration merging（declare module '@deepseek-ai/cordis'）；事件文檔標註 @mode。
• 設定用 Schemastery Schema<Config>（禁止普通物件）；非法設定在載入期響亮失敗；不得硬編碼可調參數（判斷：cordis.yml 能否修改）。
• 工具走 defineTool：execute 只傳回 output.schema 宣告的規範 JSON 值；尊重 exec.signal；人類可讀內容放 output.render；UI 卡片 presenter 是純函式（禁止 I/O/時鐘/隨機）。
• 可替換能力按三層接縫設計：Service Definition / Provider / Consumer；不提前拆解。
• 打包：bundle 清單 "dsh":{"bundle":{"patch":"..."}}；覆蓋按 id 整行替換 config；!!js（雙驚嘆號）；git 安裝需要 prepare 腳本與使用者側 allowBuilds，發布 npm/tarball 免建置許可。

依任務類型的開發路徑

（以下路徑均在 references/official-docs/ 下，為官方文檔全文副本）

• 新工具：docs/user/develop/basic/tool.md（教學）→ docs/cookbook/adding-a-tool.md（完整契約：參數驗證、規範值、背景任務 ctx.jobs、策略鉤子、Code Mode、UI 卡片）→ 參考實作 packages/shell/tool-bash（本機 checkout）。
• 新服務/能力：docs/user/develop/framework/service.md + docs/user/develop/practice/（三層拆分完整程式碼）。
• 攔截/策略/hook：docs/cookbook/extension-cookbook.md（permission-gate 範例）+ docs/event-producer-consumer.md（完整事件矩陣）。
• 新 LLM 提供商：docs/user/develop/practice/llm-adapter.md（StreamChunk 協定）。
• UI/會話節點：docs/cookbook/adding-a-conversation-node.md + docs/subsystems/session.md、client-modules.md。
• 打包/發布：docs/user/develop/basic/publish.md（bundle/profile、層順序、git 安裝陷阱）。
• 查服務/事件精確簽名：docs/subsystems/*.md 生成式 Cordis API 區 + docs/cordis-api/*；不要自造第二份靜態清單。站點 URL ↔ 本地副本對照見 guide/links.md，社群連結完整清單見 references/community-ecosystem.md。
• 參考社群實作與實測陷阱：references/community-ecosystem.md、references/community-repo-deep-dive.md（15 個開發倉庫深讀）、downloads/community-repos/（完整原始碼副本，需先執行 scripts/download-community-repos.ps1 產生）。社群已確認的機制變化（如 repository-plugin 0811 移除、bundle vs 純 cordis 雙通道）與 20 個實測陷阱（cordis 雙副本/tsconfig 三件套/多幀 zstd/Windows junction 等）在 guide/plugin-dev-guide.md §7。

驗證（交付前）

• 載入驗證：dsh --profile <name> --dump-config 檢查 patch 行是否生效；啟動日誌無 FAILED。
• 行為驗證：Web UI 或 dsh --profile headless "…" 實測；工具傳回/模型可見文字即行為，改動必須重新測試。
• 倉庫內改動額外走：型別檢查、目標包測試、keyless snapshot（模型/產品可見行為必須有組裝後轉錄快照）、雙語文檔成對、Agent Note（非平凡變更同 PR）。
• 獨立插件包：pnpm pack 後試裝到乾淨 profile 驗證（含 lib/ 建置產物）。

知識庫維護（需要時）

• 同步官方文檔副本：pwsh -File ./scripts/sync-official-docs.ps1 [-Checkout <deepseek-harness checkout>]──只同步 git 已追蹤檔案（未追蹤草稿與未推送提交不會進來），並重新整理 references/official-docs/SNAPSHOT.md；README 的「最後核驗」日期與提交號引用 SNAPSHOT.md，不要手動修改。漂移驗證：pwsh -File ./scripts/verify-kit.ps1 -Checkout <checkout>。
• 重新整理線上資料：pwsh -File ./scripts/download-sources.ps1；重新整理社群倉庫：pwsh -File ./scripts/download-community-repos.ps1（兩個腳本冪等，產出進 ./downloads/）。主題清單計數重核：pwsh -File ./scripts/gen-topic-snapshot.ps1 -OutDir <dir> -MaxPages 20（GitHub Search API q=topic:dsh-plugin；分頁上限 1000 條，去重數與 API total_count 都要記錄進 sources.md §D.2）。
• 安裝/重新整理 agent 技能副本：pwsh -File ./scripts/install-skill.ps1 -Target <skill目錄>（跳過 downloads/ 與 .github/，逐位元組驗證）。
• 衝突裁決：與官方文檔衝突時以 references/official-docs/（官方倉庫原文）為準。

邊界

• 本技能是「指引 + 約束 + 資料索引」，不是腳本/清單的機械執行；精確 API 以生成式參考為準。
• 不得修改知識庫外的 harness 倉庫檔案，除非使用者明確要求；vendor/ 與 .agents/notes/archived/ 唯讀。
• 引用 downloads/ 內容前先確認其存在（該目錄不入 git，需依上文腳本產生）；awesome-dsh-plugins 的歸檔僅供本地參考，不得隨倉庫再分發（其上游宣告內部使用約束，見 NOTICE.md）。