前言¶
在 DeepSeek Harness (DSH) 的開發中，管理智能體運行的知識庫健康度、上下文注入以及導航邏輯往往需要編寫大量重複的鉤子邏輯。直接在各個插件中抓取原始 hook 容易造成依賴混亂和狀態管理困難。
@catheadowl/dsh-extras 是一套 DSH 插件套件，旨在通過封裝常用的 DSH 鉤子提供可組合的基礎框架，並附帶 Markdown 工具和路由功能，解決文檔維護和上下文管理的問題。
這是什麼¶
這是一套由 CatheadOwl 維護的 DSH 插件集合，通過 dsh plugin add 命令一次性安裝。它將兩個常用鉤子封裝爲服務接口（ctx.gates 和 ctx.enrichment），而不是讓每個插件都直接抓取底層 hook，從而提供結構化的質量門控、上下文豐富、Markdown 文件重命名以及知識庫路由能力。
核心功能¶
該套件包含四個獨立可切換的模塊：
- 質量門控框架 (gates)：在回合結束時自動運行。開發者通過
ctx.gates接口註冊門控邏輯。模塊 ID 爲gates。 - 上下文豐富框架 (enrichment)：在
agent/pre-step階段運行。它是一個提供者註冊表，將路徑提及轉換爲有預算限制的相關上下文。模塊 ID 爲enrichment。 - Markdown 工具 (markdown)：提供
md_rename工具（移動 Markdown 文件並重寫所有內部鏈接）以及doc-link門控，並內置了鏈接事務庫。模塊 ID 爲markdown。 - 知識路由工具 (routes)：提供
any_nav工具（在 Markdown 知識庫上創建路由視圖）以及麪包屑相關提供者。模塊 ID 爲routes。
安裝與啓用¶
安裝需要 dsh CLI，所有運行時依賴由 DSH 主機提供。
dsh plugin add @catheadowl/dsh-extras
安裝後，所有模塊作爲一個組合行（composition row）出現。你可以通過禁用特定行來獨立控制模塊，而無需影響其他模塊。
配置與使用¶
禁用模塊¶
通過配置層禁用特定模塊：
- id: gates
disabled: true
配置 Enrichment 超時¶
enrichment 模塊支持配置超時參數：
- id: enrichment
config:
providerTimeoutMs: 2000
totalTimeoutMs: 5000
renderBudgetChars: 4000
Gates 安全閥配置¶
gates 模塊包含一個安全閥配置項 maxConsecutiveBlocks（默認值爲 3）。當連續塊數耗盡時，門控會降級爲通過，這僅作爲安全閥，而非正確性保證。
開發與測試¶
若需進行二次開發或驗證代碼，可使用以下命令：
# 從倉庫根目錄運行
pnpm run build # 構建四個模塊庫及客戶端包
pnpm run test:gates # 運行門控模塊的單元測試
pnpm run verify:package-face # 驗證導出接口
注意事項¶
- 運行環境：該插件依賴 DSH CLI，且所有運行時依賴由主機提供。
- 狀態隔離：各模塊之間無共享狀態，可以獨立禁用，互不影響。
- Web 配置限制：Web 配置頁面目前僅支持 gates 和 enrichment 模塊。
- 文檔語言：項目根 README 爲雙語（英語 + 中文），模塊文檔和深度文檔以中文優先。
- 版本管理：模塊的增刪通過包版本升級和
dsh plugin update實現。
