只读排障工具 dsh-plugin-lab/dsh-plugin-debugging

dsh-plugin-debugging

Let your DSH agent inspect and fix its own runtime
让 DSH 智能体自检自修它身处的运行时

Per-version changes → Releases

English · 简体中文

改了东西却没生效？在 DSH 里，这通常只有三种情况：

- 配置：每次改动都会重新读取，所以改完立刻生效。前提是 profile 里挂载了 hmr；没有 hmr，任何改动都会退化成必须重启。
- 宿主代码：进程只在启动时加载一次代码，所以改完要重启。
- 前端资源：浏览器按指纹替换资源，所以改完要热重载或刷新。

这个插件让智能体判断你属于哪种情况，以及接下来该做什么。

它能做什么

安装后，智能体会得到一组工具和一份技能文档。技能按需加载，你用斜杠命令调用它。

工具

只读 —— 不会改动宿主上的任何东西。

| 工具 | 参数 | 作用 | Web | 桌面端 |
| dsh_list_instances | port | 列出本机正在运行的 DSH 宿主。只有未认证的 GET / 返回的正是 DSH 响应体时，这个端口才算 DSH。「探测不到」和「不是 DSH」分开上报。 | ✓ | ✓ |
| dsh_check_auth | host、port | 区分「未运行」和「未认证」。 | ✓ | ✓ |
| dsh_diagnose_plugin_load | package、port、dshHome | 检查插件是否真的加载：bundle 成员关系、挂载形式、loader 树，并把实测证据和推断证据分开。 | ✓ | ✓ |
| dsh_check_effect_mode | change：config / bundle-added / host-code / client-code、alreadyInDependencies、dshHome | 判断改动是即时生效、需要重启，还是需要热重载。它直接探测运行中的 profile，不靠猜。 | ✓ | ✗ |
| dsh_dump_config | profile、dshHome | 展示 profile 解析成了什么：合成后的树，以及解释它的诊断信息。 | ✓ | ✗ |
| dsh_sign_cookie | host、port、maxAgeDays、dshHome | 为浏览器会话 cookie 签名，让脚本或命令行客户端能访问你自己的 DSH 实例。 | ✓ | ✓ |

会改变状态 —— 前两个会替换代码，或结束你正在调试的宿主。

| 工具 | 参数 | 作用 | Web | Desktop |
| dsh_hot_reload | entryId / module / serverName 三者中恰好一个，外加 dryRun | 把已挂载的 entry 换成磁盘上的最新代码，无需重启。失败时回滚。 | ✓ | ✓ |
| dsh_restart | reason、delayMs、dryRun、force | 改动确实需要时，重启这个宿主。默认关闭。 | ✓ | ✗ |

表格按你实际使用的顺序排列，所以两张表只在一处分开：它们是否改变任何东西。最后一列是按载体划分的可用性；原因见 平台支持。

三个常见陷阱：

- dsh_check_auth 返回 401 不代表会话过期。 不带 cookie 的请求永远得到 401，所以 auth probe 的 401 只能证明服务在运行、且要求认证。要区分「会话仍然有效」和「authority 不对」，你必须在浏览器里打开那个 host:port。旧 cookie 在同一端口重启后仍然可用；只有端口变了才会产生 401。
- dsh_hot_reload 可能泄漏。 框架不跟踪的资源——比如 timer 或 socket——在替换后会悄悄泄漏。
- dsh_restart 在下面有单独一节。

背后的技能文档

技能文档位于 skills/dsh-plugin-debugging/SKILL.md，完整记录了安装形式、凭据获取、进程识别和隔离实例背后的推理过程。

工具只是加速器；如果工具输出与技能文档冲突，以技能文档为准。

安装

从 Plugins 页面安装：

打开 Plugins 页面，点击右上角的 Add plugin，输入 dsh-plugin-debugging，然后安装。

从 npm 安装：

dsh plugin --profile web add dsh-plugin-debugging

从源码安装：

bash
git clone https://github.com/dsh-plugin-lab/dsh-plugin-debugging.git
cd dsh-plugin-debugging
pnpm install && pnpm run build
dsh plugin --profile web add "$PWD"

注意：

- 不要跳过 pnpm install：用 link: 方式安装时，依赖来自仓库本身；跳过这一步，插件会显示为未运行，并报 ERR_MODULE_NOT_FOUND。
- 重启后生效：安装完成后重启 dsh --profile web。
- link: 和 dsh.bundle 是两回事：link: 只决定改源码后是否需要重新安装；patch 层是否生效，取决于包有没有声明 dsh.bundle。

环境要求：

Node >= 20，且 DSH 版本满足 package.json 中的范围。

维护规则：

profile 的 dependency 和 bundle list 由 dsh plugin add 管理，不要手动编辑。不要在 $DSH_HOME 下创建包，也不要在 profile 目录里运行包管理器。

安全与边界

除 dsh_restart 外，这些工具从不重启进程、从不改写 profile、从不写入宿主数据。测试会强制这条规则：只要有任何写入指向宿主数据路径（profiles / sessions / storages / logs / cache / attachments / backups / integrations / mcp / settings.yaml / .credentials.yaml …），或者把 DSH_HOME 本身当作目标，pnpm run test 就会失败。

唯一的写入例外是本插件自己的命名空间 $DSH_HOME/<package name>/：只要求 $DSH_HOME 下第一层目录与包名完全一致，再往下不受限制。

各工具触碰的范围：

- 只读，不发请求：dsh_check_effect_mode、dsh_diagnose_plugin_load、dsh_dump_config。它们只读实例已有的文件，不产出凭据。
- 只读，发送 HTTP：dsh_check_auth 连接你指定的 host:port；dsh_list_instances 只探测回环端口。两者都不发送凭据。
- 只触碰运行中的模块树：dsh_hot_reload，不杀任何进程。
- 读取本地签名密钥：dsh_sign_cookie，为你自己的实例签 cookie。它不发请求，且 cookie 值故意不返回。
- 结束宿主：dsh_restart，这里唯一不可逆的操作。

dsh_restart

dsh_restart 是唯一不可逆的操作：它会结束你正在调试的宿主。默认关闭，运行它要通过三道关卡：

1. 四项检查：是否处于重启循环、是否有其他会话或任务正忙、bundle 表是否可读、启动命令能否确定。force 只覆盖「会话正忙」这一关；其余三项无法绕过。
2. 单独的审批检查：先读取审批策略，只有策略为 ask 时才询问你。never 表示禁用提示词，所以在 never 下询问会被拒绝；必须先读取策略，再决定是否询问。
3. 写入 marker 前的单独检查：这个插件自己的命名空间不在默认文件沙箱内，所以写入时显式使用 danger-full-access。

三项结果都会写进工具输出。 dryRun 会跑完每一道关卡，但不写入任何内容。

[!IMPORTANT]
仅限 Windows，且仅当宿主以 Web 进程方式启动。 在 Desktop 应用里，它会在写入任何内容之前拒绝执行：请从托盘退出，然后重新启动。

重启之后会发生什么：

- 新宿主读取 marker，唤醒其中列出的每个会话，并在每个会话里留一条备注。
- 这条备注是回顾，不是「请继续」：重启在何时被请求、宿主停机了多久、marker 最终如何。
- 你输入的 reason 只出现在发起重启的那个会话里；其他会话收到同样的回顾，但不带 reason。

平台支持

基于端口的进程识别设计为跨平台；目前只在 Windows 上做过真机实测。具体来说：

- 找不到可用命令时：它报告「无法检查」，而不是「没有监听者」。这是两个相反的结论。
- 较弱的回退方案：它们可能发现「有人在监听」，却识别不出进程；这种情况报告为未识别，而不是「没有监听者」。

其余部分与平台无关。dsh_restart 需要 Windows 并且宿主以 Web 进程方式启动：在 Desktop 应用里，宿主是 Electron 外壳的子进程，没有任何面向插件的通道能重新拉起那个外壳。如果你能在 Linux 或 macOS 上试一次真正的重新拉起，请到 #44 告诉我们——这个缺口正是该 issue 要解决的。

配置

字段

这些字段在 profile 组合中配置本插件。enableRestart 在本插件卡片上的 Plugins 页面也有一个开关。

| 字段 | 默认值 | 含义 |
| enableRestart | false | 是否允许运行 dsh_restart。立即生效，无需重启宿主。 |
| dshHome | $DSH_HOME，否则 <home>/.dsh | 实例存放 profiles、日志和凭据的位置。 |
| profile | $DSH_PROFILE，否则为默认 profile | 工具检查哪个 profile。 |
| port | 0 | 要探测的宿主端口；0 表示自动查找监听端口。 |
| timeoutMs | 60000 | 快速工作的超时预算：读一个文件、跑一条命令，或做一次 HTTP 探测。 |
| schemaDumpTimeoutMs | 240000 | 运行 --dump-config-schema 的超时预算（实测 10.2–15.7 s；负载下 32 s）。 |

这两个预算如何推导，以及传输层为什么必须在宿主的工具截止时间之前过期 → docs/ARCHITECTURE.md §5.1。
调试另一个实例

什么时候需要： 你在调试一个实例，但证据在另一个实例上——另一个 profile，或者另一个 DSH_HOME。

哪些工具接受 dshHome： dsh_dump_config、dsh_check_effect_mode、dsh_diagnose_plugin_load、dsh_sign_cookie。路径解析和启动的 dsh 子进程都用你传入的 home，输出会说明实际读取的是哪一个（dshHomeSource: tool-argument）。以参数传入的值，绝不会被悄悄报告成配置的默认值。

哪些不接受，为什么：

- dsh_check_auth：它回答的是某个 host:port 的认证状态，而且已经有 host / port。
- dsh_list_instances：它只做发现，能给的就只有一个 host:port。
- dsh_hot_reload：它替换的是当前进程内存里的模块，跨不到另一个实例。
- dsh_restart：它杀掉自己所在的主机，所以没有「另一个实例」可以指向。

一个坑： 发现类工具只能给出 host:port，没有任何东西把它映射到对应的 DSH_HOME；所以你得自己提供 dshHome。因此，dsh_diagnose_plugin_load 把答案分成两半：磁盘证据来自你传入的 home，loader 树那一半只反映当前进程。

License

MIT。

Contributing

Bug 和需求请提到仓库的 Issues。

维护者的文档地图 → AGENTS.md。