在 DeepSeek Harness (DSH) 的開發與調試過程中，瞭解 Cordis 狀態（如插件加載狀態、工具可見性、憑證配置等）通常需要通過運行 Shell 命令或手動閱讀配置文件來完成。傳統的 Skill 更多扮演“症狀表”的角色，告訴智能體該運行什麼命令以及如何解析輸出。dsh-tool-diagnose 插件改變了這一模式，它作爲一個 Cordis 插件，在進程內部運行自省，直接暴露一個面向模型的 diagnose 工具。
前言¶
該插件旨在解決開發者需要實時、精確地檢查 DSH 運行時狀態的問題。不同於依賴外部腳本或 Skill，它通過 ctx.diagnostics 註冊表提供了一套可擴展的檢查機制。這使得智能體可以直接在對話中調用診斷工具，獲取關於插件狀態、工具可用性、憑證解析、審批策略、令牌壓力以及子代理樹的實時數據。
安裝與啓用¶
安裝過程需要指定一個已存在的 Profile。DSH 默認提供 web 和 headless 兩個 Profile，分別對應 Web UI 和命令行單次任務場景。
- Web UI 環境：
dsh plugin --profile web add dsh-tool-diagnose
- Headless 終端環境：
dsh plugin --profile headless add dsh-tool-diagnose
如果你的環境使用了自定義 Profile（即 $DSH_HOME/profiles/<name>/ 目錄），請將 --profile 後的參數替換爲你的 Profile 名稱。
核心功能¶
插件的核心在於 ctx.diagnostics 服務。它包含一組檢查項，部分檢查項依賴於特定的服務（如 ctx.credentials、ctx.approval 等），如果依賴服務未掛載，插件會自動跳過相應的檢查，而不會導致整體插件加載失敗。
支持的檢查項包括：
- plugin-fiber-state：讀取
ctx.loader.entries()，報告插件條目的啓用/禁用狀態以及 Fiber 階段（pending/loading/active/failed/unloading）。 - tool-visibility：調用
ctx.tools.get(name)，確認工具是否在全局範圍內註冊或可見。 - credential-resolution：通過
ctx.credentials.describe()解析憑證引用（如DEEPSEEK_API_KEY），僅返回配置/來源/可寫狀態，不泄露實際密鑰。 - approval-policy：報告部署的默認審批策略（”ask”/”never”），或特定會話的覆蓋策略。
- token-pressure：對比
totalTokens（請求/響應壓力）與surfaceTokens（固定啓發式總數），用於排查壓縮未運行的原因。 - subagent-tree：扁平化會話的子代理樹，報告數量、最大深度及無法解析的後代。
典型用法¶
在對話中調用 diagnose 工具時，可以提供一個可選的 target 參數，用於過濾檢查範圍。target 的具體含義取決於不同的檢查項：
- plugin-fiber-state：插件模塊名稱的子串。
- tool-visibility：工具名稱。
- credential-resolution：憑證引用名稱。
- subagent-tree：會話 ID。
示例：檢查 bash_run 工具爲何未顯示
智能體可以發起如下調用：
調用 diagnose 工具，target 爲 "bash_run"，以檢查工具可見性。
系統將返回相關的檢查結果，幫助定位是工具未註冊、插件加載失敗還是作用域限制。
擴展機制¶
dsh-tool-diagnose 的設計允許其他插件依賴並擴展其檢查功能。檢查項本質上是一個閉包在 ctx 上的工廠函數。第三方插件可以在其自身的 apply 函數中，通過 ctx.inject 依賴 diagnostics 服務並註冊新的檢查。
第三方插件擴展示例：
import type { Context } from '@deepseek-ai/cordis'
export const name = 'my-extra-diagnostics'
export function apply(ctx: Context) {
ctx.inject(['diagnostics'], (ctx) => {
ctx.diagnostics.registerCheck({
id: 'my-check',
description: '檢查特定業務邏輯的狀態',
run(target) {
// 在此處讀取閉包捕獲的 ctx
// 不要將 ctx 作爲 run() 的參數傳入
return []
},
})
})
}
插件與 Skill 的區別¶
此插件是 Cordis 插件，而非 Skill。它運行在 DSH 進程內部，直接訪問內存中的服務狀態。與之相對的是，Skill 是可移植的、無構建步驟的腳本，通常用於告訴智能體運行外部命令。兩者可以配合使用：Skill 可以指示智能體先調用 diagnose 工具，再根據工具返回的表格數據進行判斷。
資源鏈接¶
- GitHub 倉庫: https://github.com/xu-kai-quan/dsh-tool-diagnose
- NPM 包: dsh-tool-diagnose
- 社區目錄: https://www.skillhub.cn/plugins/xu-kai-quan/dsh-tool-diagnose
