在 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
