dsh-treekeeper

中文 | English

面向 Windows 的 DSH 进程树对账与治理插件。它把当前宿主进程树与可用任务账本并列，把每个进程归属到创建它的任务，标出未归属与孤儿进程，并提供受保护的整树终止。

功能

• 采样当前 DSH 宿主的进程树，启动器的其他子进程不归入该树。
• 把每个进程归属到创建它的任务，并检测重复命令、孤儿进程与长时间运行的插件子进程。
• 对照任务账本与根 session 的 subagent 子代理树，其他 session 的子代理树不读取。
• 受保护的整树终止（taskkill /T /F），条件列在安全与边界的终止护栏表中。
• 从命令行中的 node_modules 路径识别进程所属插件，findings 与终止操作历史写入记录文件。
• DSH 宿主子进程分区默认收起，数量显示在标题上。
• 面板头部显示宿主类型，取自宿主进程的可执行路径与命令行，进程环境不作为判据。
• 桌面应用自身的 Electron 进程在未归属分区内单列为一个进程组，组内成员各自保留命令行、进程号、内存与运行时长。
• finding 的置信度分三档：exact 由宿主进程树归属支撑，可作为树杀目标；indicative 有真实的进程事实而归属链较弱或缺失（降级采样，或上一个宿主留下的幸存进程）；inferred 只由启发式规则得出，不可作为目标。
• 页面左下的 dsh-mini-utility-dock launcher 打开全局面板，会话标题栏打开面板并聚焦该 session，侧栏会话行显示该 session 已缓存的事实。

安装

# 从 npm 安装并注册到 web profile（推荐）
dsh plugin --profile web add dsh-treekeeper

# 仅安装 npm package
npm install dsh-treekeeper

# 或从 GitHub 安装
dsh plugin --profile web add github:xswt442-cmd/dsh-treekeeper

• npm install 只安装 package，不注册 DSH profile。
• 重启 DSH Web 后生效。

会话范围

Subagent 分区有三种状态：

| 状态 | 含义 | | --- | --- | | available | 显示根 session 的完整子代理树 | | root-required | 没有可用的根 session | | unavailable | 当前 DSH 构建未提供 subagents 能力 |

会话标题栏入口的根 session 是该行的 sessionId，全局面板入口取当前选中的 session。

面板加载一次快照后，可归属到具体 session 的事实进入客户端缓存：

| 缓存内容 | 归属依据 | | --- | --- | | 子代理数、运行中数、读取异常数 | 响应的 subagentRoot 与其子代理行 | | 运行中 job 数 | 账本行的 ownerSession | | finding 数 | 账本关联填入的 ownership.session |

宿主进程清单、未归属进程与无主 job 无法归属到 session，不进入缓存。

侧栏会话行读取这份缓存：空闲行的前导格显示一个图标，悬浮卡片显示一行摘要与「在 TreeKeeper 中查看此会话」的入口。该 session 没有缓存时前导格留空，卡片入口仍然可用；两者只读取缓存，不发起宿主读取。

配置

配置仅在当前进程中生效，重启后恢复默认值。

| 字段 | 默认值 | 取值范围 | 作用 | | --- | ---: | --- | --- | | pollMs | 0 | 0（按请求采样）或 2000–600000 ms | 后台采样间隔 | | allowKill | true | 布尔值 | 受保护的进程树终止开关 | | extraWhitelistPids | [] | PID 数组 | 额外受保护的 PID |

安全与边界

| 项 | 边界 | | --- | --- | | 平台 | 仅支持 Windows | | 非 Windows | 报告 unsupported_platform | | 采样降级 | CIM 不可用时降级为只读采样，归属与终止禁用 | | 浏览器凭据 | DSH 0.1.0-rc.7+ 复用 Connection 的签名 cookie | | 准入：宿主有 Connection | 由 Connection 的 Host/Origin 校验与签名 cookie 决定 | | 准入：宿主无 Connection | 由本插件守卫按 TCP 对端地址、Fetch Metadata、Origin 与 loopback Host 判定 | | 写操作 | 仅接受 POST | | 远端可达 | 宿主配置 trustedHosts 且监听 0.0.0.0 时，持有有效浏览器会话的远端可调用包括 kill 在内的接口 | | 准入收窄 | 本插件不额外收窄宿主的 Connection 准入，终止护栏在该情形下同样适用 | | 遍历取消 | 页面关闭、刷新被替代或 HTTP 断开时，进行中的 subagent 子代理树遍历收到取消信号 |

终止护栏：

| 护栏 | 规则 | | --- | --- | | 激活 | 第一次点击激活按钮，6 秒内有效 | | 确认 | 第二次点击弹出浏览器确认框 | | 快照 | 要求 15 秒内的完整快照 | | 身份核对 | 请求进入时按快照核对 PID 创建时间 | | 执行前复核 | 重新采样，再核对一次创建时间 | | 归属 | 仅归属根为 DSH 宿主的进程可终止，未归属进程只用于排查 | | 不可终止 | 系统关键进程、当前宿主、启动链与 extraWhitelistPids | | 白名单 | 额外白名单 PID 只作为排查用的归属根，其子进程可见但不可终止 | | 受保护子进程 | 终止前即时采样的树含任一受保护 PID 时，整个操作被拒绝 |

即时采样之后新出现的受保护子进程无法排除。

• Jobs 与 OS 进程之间没有稳定的 PID 映射。
• 命令行匹配只用于排查，不触发自动操作。
• Findings 与终止结果写入 $DSH_HOME/treekeeper/history.jsonl。

开发

提交前运行：

npm test
npm run docs:check
npm pack --dry-run

License

MIT