DSH 任务账本与实际运行的操作系统进程之间常出现偏差。可能是进程泄漏，也可能是孤儿进程，亦或是归属关系不清晰。dsh-treekeeper 旨在解决这些问题。它对账 DSH 任务账本与 OS 进程树，定位归属、检测泄漏并安全治理。
安装与启用¶
安装该插件会将它注册到指定的 DSH profile 中。
dsh plugin --profile web add dsh-treekeeper
安装后需要重启 DSH Web 才能生效。
核心功能¶
该插件提供以下功能：
- 进程采样与归属：采样当前 DSH 宿主的进程树，把每个进程归属到创建它的任务。同时检测重复命令、孤儿进程与长时间运行的插件子进程。
- 会话对账：对照任务账本与根 session 的 subagent 子代理树，识别进程与任务的关系。
- 安全治理：提供受保护的整树终止功能。
- 插件识别：从命令行中的
node_modules路径识别进程所属插件。 - 面板展示：
- DSH 宿主子进程分区默认收起，数量显示在标题上。
- 面板头部显示宿主类型（取自宿主进程的可执行路径与命令行，不依赖环境变量）。
- 桌面应用自身的 Electron 进程在未归属分区内单列为一个进程组。
- Finding 置信度：finding 的置信度分三档（
exact、indicative、inferred），用于辅助判断终止目标。
配置¶
配置仅在当前进程中生效，重启后恢复默认值。
| 字段 | 默认值 | 取值范围 | 作用 |
|---|---|---|---|
pollMs |
0 |
0（按请求采样）或 2000–600000 ms |
后台采样间隔 |
allowKill |
true |
布尔值 | 受保护的进程树终止开关 |
extraWhitelistPids |
[] |
PID 数组 | 额外受保护的 PID |
典型用法¶
- 打开面板：点击页面左下的
dsh-mini-utility-docklauncher 打开全局面板。也可以通过会话标题栏打开面板并聚焦该 session。 - 查看缓存：查看会话已缓存的事实。
- 终止操作：通过身份核对确认终止目标。
安全与边界¶
平台与降级¶
- 平台限制：仅支持 Windows。在非 Windows 平台会报告
unsupported_platform。 - CIM 降级：CIM（Windows Management Instrumentation）不可用时，插件会降级为只读采样，归属与终止功能将被禁用。
访问控制¶
- 凭据复用：DSH 0.1.0-rc.7+ 版本复用 Connection 的签名 cookie。
- 准入规则：
- 宿主有 Connection：由 Connection 的 Host/Origin 校验与签名 cookie 决定。
- 宿主无 Connection：由本插件守卫按 TCP 对端地址、Fetch Metadata、Origin 与 loopback Host 判定。
- 远端可达：宿主配置
trustedHosts且监听0.0.0.0时，持有有效浏览器会话的远端可调用包括kill在内的接口。 - 写入限制：仅接受 POST 请求。
终止护栏¶
为了防止误杀，终止操作设有以下护栏：
- 激活：第一次点击激活按钮，6 秒内有效。
- 确认：第二次点击弹出浏览器确认框。
- 快照：要求 15 秒内的完整快照。
- 身份核对：请求进入时按快照核对 PID 创建时间。
- 执行前复核：终止前重新采样，再核对一次创建时间。
- 归属限制：仅归属根为 DSH 宿主的进程可终止，未归属进程只用于排查。
- 不可终止列表：系统关键进程、当前宿主、启动链与
extraWhitelistPids中的 PID 不可终止。 - 白名单限制：额外白名单 PID 只作为排查用的归属根，其子进程可见但不可终止。
- 受保护子进程：终止前即时采样的树含任一受保护 PID 时，整个操作被拒绝。
限制说明¶
- PID 映射：Jobs 与 OS 进程之间没有稳定的 PID 映射。
- 命令行匹配：命令行匹配只用于排查，不触发自动操作。
- 日志记录：Findings 与终止结果写入
$DSH_HOME/treekeeper/history.l。
总结¶
dsh-treekeeper 是一个专注于进程树对账与安全治理的工具。它通过严格的准入校验和多层护栏，确保在清理泄漏或孤儿进程时不会影响系统关键服务或当前任务。对于需要精细化管理 DSH 进程环境的场景，该插件提供了必要的可视化与控制能力。
- 目录页：dsh-treekeeper
- GitHub 仓库：xswt442-cmd/dsh-treekeeper
