运行时诊断 xu-kai-quan/dsh-tool-diagnose

dsh-tool-diagnose

一个 DeepSeek Harness Cordis 插件（不是技能——见 插件 vs 技能），对外暴露一个面向模型的 diagnose 工具，底层是可扩展的检查注册表 ctx.diagnostics。症状表式的技能只会告诉智能体该跑哪条 shell 命令、怎么读输出；这个插件则自己动手做内省，在进程内部、针对实时的 Cordis 状态执行——并且允许其他插件贡献更多检查，方式和本包自带的 checks.ts 一样。

安装

如果你用 DSH 网页界面：

dsh plugin --profile web add dsh-tool-diagnose

如果你在终端里跑一次性任务（dsh --profile headless "some task"）：

dsh plugin --profile headless add dsh-tool-diagnose

web 和 headless 是 DSH 开箱自带的名字，对应上面两条命令——你平时用哪个，就把 --profile web / --profile headless 换成哪个词。不需要提前做任何设置；两者第一次使用时都会自动初始化。

用的是自定义配置档名，而不是 web/headless？

「配置档」就是 $DSH_HOME/profiles/<name>/ 下的一个文件夹（$DSH_HOME 默认是 ~/.dsh）。如果你建过自己的具名配置档，就在 --profile 后面写那个文件夹的名字。看看你已经有哪些：

ls "$DSH_HOME/profiles" # macOS/Linux
dir $env:DSH_HOME\profiles # PowerShell

然后，在会话里说：「Use the diagnose tool to check why the bash_run tool isn't showing up.」从 GitHub 源码安装的替代方案见 状态，想在不装进配置档的情况下改代码，见 本地试跑。

目录结构

src/
registry.ts # ctx.diagnostics: DiagnosticRegistry Service — registerCheck/list/run checks.ts # createCheck FACTORIES (2 always-on) + optional checks (4, service-gated) index.ts # the plugin: mounts the registry, calls each factory, registers the diagnose tool tests/ registry.spec.ts # registry mechanics + the closure-vs-passed-ctx regression test checks.spec.ts # credential-format / approval-policy branches + the index.ts wiring regression test checks-integration.spec.ts # all 6 checks against real Loader/ToolRuntime/SessionStore/etc. cordis.patch.yml # the bundle layer a profile applies when it lists this package package.json # declares dsh.bundle, pointing at cordis.patch.yml

这些检查到底做什么

每一项都读取真实、已经发布的服务——没有凭空捏造的 API。其中两项始终注册（它们只需要 ctx.tools，本插件已经依赖它，或者除 ctx.diagnostics 本身之外什么都不需要）；另外四个只有在部署中实际挂载了对应服务时才注册（见可选检查）。

- plugin-fiber-state 读取 ctx.loader.entries() —— 也就是 @deepseek-ai/dsh-host-plugin-inventory 投射到 Web UI 的同一个原语 —— 并报告每个匹配条目的 enabled/disabled 状态和 fiber 阶段（pending/loading/active/failed/unloading/无）。这是手动运行 dsh --profile <name> --dump-config 再用眼睛读的实时版本。（它和下面其他可选检查一样，由 ctx.loader 门控，尽管这里的描述出于 token 开销的考虑把它和「始终开启」的那一对归在一起 —— 见 index.ts。）
- tool-visibility 调用 ctx.tools.get(name)，告诉你某个工具是否已注册且在全局作用域中可见，还是不存在（从未注册、所属插件加载失败，或被作用域限制排除）。

调用工具时可选传入 target（具体含义随检查而异：插件模块名子串、工具名、凭据引用名或会话 id）；省略它则得到每项检查未过滤的完整视图。

可选检查（服务门控）

每一项都依赖 dsh-base 通常提供、但特殊部署可能未挂载的服务；index.ts 把每一项都注册在自己的 ctx.inject([...]) 里，所以缺少某个服务的部署仍能得到其他所有检查，而不是整个插件加载失败。

- credential-resolution（需要 ctx.credentials）—— 通过 ctx.credentials.describe() 解析凭据引用（例如 DEEPSEEK_API_KEY）：是否已配置/来源/可写，绝不返回值本身，遵循该接缝自己的准则。
- approval-policy（需要 ctx.approval、ctx.sessions）—— 报告部署默认的审批策略（"ask"/"never"），或在给定 session-id 目标时报告某个会话的覆盖值。
- token-pressure（需要 ctx.tokenMeter、ctx.sessions）—— 测量实时会话当前的 totalTokens（请求/响应压力）对比 surfaceTokens（固定启发式总量），适用于「为什么压缩还没运行」这类症状。
- subagent-tree（需要 ctx.subagents）—— 展平某个会话的后代子代理树，报告数量、最大深度，以及注册表无法解释的任何后代（corrupt/unavailable）。

扩展它：第三方检查

任何其他插件都可以依赖本插件并注册更多检查。检查是一个工厂，闭包捕获自己已经限定作用域的 ctx —— 在 ctx.inject 回调里构造它，需要什么服务就注入什么，不要提前构造成独立对象（至于这个区别为何至关重要，见审计说明）：

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-extra-diagnostics'

export function apply(ctx: Context) {ts
ctx.inject(['diagnostics' / , 'whateverServiceThisCheckNeeds' /], (ctx) => {
ctx.diagnostics.registerCheck({
id: 'my-check',
description: 'What this check looks at and what target means for it.',
run(target) {
// read ctx (closed over above) here — never accept ctx as a run() parameter
return []
},
})
})
}

销毁该插件的 fiber 会自动注销它的检查项——registerCheck 会返回注销函数，但你很少需要直接调用它；卸载时 Cordis 会替你调用。

在本地试用

如果你想在本地检出上折腾，而不是安装已发布的包（后者见上面的 Install）： sh
pnpm dsh plugin --profile demo add /path/to/dsh-tool-diagnose
dsh --profile demo --dump-config # confirm the "diagnose-tool" row is present
dsh --profile demo

在 Windows 上，如果你想改用 --patch 覆盖层直接指向 src/index.ts（教程里那种本地文件写法），做一次快速的源码启动测试，那么模块的 name 必须是 file:/// URL，不能写成裸的 D:/... 路径——Node 的 ESM 加载器会拒绝后者，报 ERR_UNSUPPORTED_ESM_URL_SCHEME。

插件 vs 技能

如果你想要一份可移植、免构建、复制进 ~/.agents/skills/ 就能用的症状对照表，让任何 DSH 会话都能读取，那它是技能，不是插件——见 Discussion #1739 里的原始分享，本插件的方法论正是从那里借鉴的（尤其是把知识锚定到某个具体的 dsh 版本）。两者配合得很好：技能可以告诉智能体「先调用 diagnose 工具，再拿它的发现对照这张表」，而不是让它自己跑 shell 命令、自己解析输出。

状态

- [x] 已发布到 GitHub，公开，带 dsh-plugin 话题标签。
- [x] LICENSE 已填上真实的版权持有人。
- [x] 已发布到 npm，包名 dsh-tool-diagnose——
见上面的 Install。直接从 GitHub 源码安装也行（dsh plugin --profile <name> add github:xu-kai-quan/dsh-tool-diagnose，注意下面的构建脚本坑），而且它跟踪的是 master，不是 npm 上最后打标签的发布版。

如果你 fork 或扩展这个项目：

1. 对照你实际构建/测试所用的版本，确认依赖版本——这个骨架固定的是脚手架搭建时能拿到的版本：@deepseek-ai/cordis@4.0.1、 @deepseek-ai/cordis-plugin-loader@1.0.2、@deepseek-ai/schemastery@3.18.1，以及 @deepseek-ai/dsh-tools/dsh-credentials/dsh-user-approval/dsh-token-meter/dsh-session/ dsh-subagent 全部为 0.1.0-rc.5（dsh 系列版本同步推进）。
2. 发布预构建产物（npm publish，或 pnpm pack 加 tarball），不要指望安装器允许 git 安装时跑 prepare 脚本，除非你希望用户主动选择开启。
3. 打 tag 发版之前，先跑 npm install && npm test && npm run build；另外，按下面「审计记录」说的，至少要在真实的 dsh 进程里真正启动一次。这个包自己的 bug，在走到这一步之前，测试套件根本看不见。
4. 写真正的检查——这里附带的六个只是有用的起点，不是上限；你本来会写成 Skill 症状行的那些机制链，都改成 DiagnosticCheck，让它真正去读实时状态，而不是描述该怎么做。先 grep 目标包的 README，找出它的 ctx.<key> 服务面，这个包的检查就是这么建起来的。

审计记录

完整测试套件（22 个测试全过）没抓到的两个真实 bug

这两个都只有把插件放进真实的 dsh --profile headless 进程里跑起来、让智能体真的去调 diagnose 工具，才能发现——在此之前，所有单元测试和集成测试都干干净净地通过，而工具要么没注册，要么已经坏了。

1. defineTool 的 output.schema DSL 写错了。 dsh-tools 的 ValueSchemaSpec 用属性自己身上的 required: true 来标记可选/必填，跟 parameters 一致——不是在对象节点上再放一个普通 JSON Schema 的 required: [...] 数组。错误写法在 tsc 下编译得好好的，跟上面几行（正确的）parameters 块看起来一模一样，但 defineTool() 一执行就抛 JsonSchemaError: schema.items.required is not supported by the value schema DSL——而这发生在插件加载阶段，于是整个 diagnose 工具悄无声息地注册失败，不崩溃、不打日志，所有配置档都一样。
2. ctx 引用存下来、再经另一个服务的 this.ctx 交回来，就失效了。 原来的注册表设计把 ctx（或 this.ctx）捕获一次，之后传给每个检查的 run(ctx, target)。用隔离的复现脚本对着真实的 @deepseek-ai/cordis 4.0.1 运行时验证过：某个作用域能访问哪些注入服务（ctx.approval、ctx.tools，甚至静态 inject 声明的依赖），是按精确的上下文引用来授予的；一旦把这个引用当普通值存进另一个 Service 实例、之后在别的方法里通过 this.ctx 读回来，授权就不会跟着走——会抛 cannot get property "X" without inject，不管原来的授权是静态的，还是来自嵌套的 ctx.inject()。修法：DiagnosticCheck.run 干脆不要 ctx 参数；每个检查都是工厂（createCheck(ctx)），在构造时就闭包捕获自己作用域的 ctx，注册表只调 check.run(target)。

tests/registry.spec.ts 和 tests/checks.spec.ts 现在都带了 bug #2 的回归测试（检查注册的作用域比之后调用 run() 的作用域更深）；套件里没有任何东西直接回归测试 bug #1（一个类型检查能过、但形状写错的 output.schema）——如果你动那个 schema，还是得真正启动插件，别只信 npm test。

这样端到端验证了什么，还带了一次真实模型调用

对着真实的 dsh --profile headless 启动（没有 mock，没有假货，依赖都是 npm 真实安装的）：diagnose 工具出现在模型的工具列表里；不带 target 调用时，它返回 plugin-fiber-state 的真实结果（4 行真实的已禁用插件：cordis-plugin-hmr、dsh-bash-sandbox、dsh-tool-bash、dsh-skill-badge）和 approval-policy 的真实结果（"ask"，真实的部署默认值）；带 target: 'DEEPSEEK_API_KEY' 调用时，credential-resolution 正确报告它已配置（来源：file，可写），没有泄露值；带 target: 'write' 调用时，tool-visibility 正确报告它已注册且可见。credentials、approval、sessions、tokenMeter、subagents 原来都挂载在 headless 配置档里——只有 loader 的 gating 曾是真正的可移植性隐患，现在它和其他四个一样处理了。

逐项单元测试技巧，方便你以后继续扩展

- plugin-fiber-state：ctx.plugin(Loader) + ctx.loader.builtins.<name> = fn + ctx.loader.create({ name })——和 dsh-host-plugin-inventory 自己的测试套件用的是同一套 harness，避免任何真实的文件/模块解析。
- tool-visibility：直接 new ToolRuntime(ctx)——但它的构造函数会同步读取 ctx.systemPrompt，所以必须先 await ctx.plugin(SystemPrompt, {})，否则构造会抛 Cannot read properties of undefined (reading 'tools')。dsh-tools 自己的 code-mode.spec.ts 也有同样的前置条件。
- token-pressure / approval-policy：直接 new SessionStore(ctx) + new TokenMeter(ctx) / new ApprovalService(ctx, config)，然后 ctx.sessions.create() 拿到一个活跃会话——不需要持久化或智能体循环，因为 measure() 和 overrideOf() 直接接收会话对象，而不是通过服务读回来。
- subagent-tree：直接 new SessionStore(ctx) + new SessionProjectionRegistry(ctx) + new SubagentRuntime(ctx)。如果 sessionProjections 没挂载，listDescendants() 在任何候选扫描之前就会抛 SubagentError——哪怕会话没有任何子节点也一样——所以这个服务不能跳过，即使这里测的是最简单的空树场景。

一个真实的依赖声明 bug，单独发现并修复了

@deepseek-ai/dsh-credentials 曾在 peerDependenciesMeta 里被短暂标为 optional，但 checks.ts 对它做了硬值导入 credentialRef——所以无论凭证检查是否注册，模块导入都会在加载时失败，和「optional」矛盾。dsh-user-approval、dsh-token-meter、dsh-subagent 才是真正的可选：它们只通过 import type {} 副作用导入被引用，TypeScript 会擦除这些导入，包缺失时没有运行时可导入会失败。

仍未覆盖 subagent-tree 的非平凡分支（真正的后代，或者 corrupt/unavailable 诊断条目）没有测试覆盖——要走到这些分支，需要真实子代理服务商和一个已启动的子进程（完整测试装置的体量见 harness 仓库里的 packages/subagent/subagent/tests/list-children.spec.ts：JSONL 持久化、mock LLM 适配器、真实的 spawn/fork 服务商）。平凡的空树路径已有覆盖，并且上面那个实时启动测试也独立确认过。