前言¶

在 DeepSeek Harness（DSH）里同时开多个 workspace、主对话和 subagent 时，侧栏通常只列会话，不会把 agent 谱系摊开。想确认「某个 subagent 在跑什么、挂在哪一层、下次定时什么时候到」，往往要逐个会话切进去看。Activity 类面板要么占用面积大，要么和当前 rc 版本对不上。Agent Tree 是社区维护的 DSH Web 客户端插件，用一张常驻右下角的小卡片，把 workspace → 对话 → subagent（及更深层）的实时状态画成树形，并补上待办交互、定时任务倒计时和本机 claude/codex 进程等观测信息。

这是什么¶

Agent Tree（npm 包名 dsh-plugin-agent-tree）由 yuna78 维护，分类为客户端插件。它在 DSH Web 页面注入一张 288px 宽的浮动卡（空闲时收成胶囊，不会消失），用类似 git log --graph 的连接线展示 dsh → workspace → 对话 → subagent → 孙代理；只保留正在干活或有定时任务的分支，避免卡片无限变长。数据走 DSH 客户端公开的 UI 契约，不 patch 宿主、不读数据库；本机多实例与外部 CLI 由插件宿主半部通过 ps、lsof 等只读方式发现。

目录页：skillhub.cn/plugins/yuna78/dsh-agent-tree
源码与文档：github.com/yuna78/dsh-agent-tree（MIT）

核心功能¶

树形结构与层级¶

• 顶层并列 dsh 实例与本机 claude / codex（及 Claude 桌面版等识别到的节点），各自向下展开 workspace、对话、subagent。
• 用 ├─、└─、│ 缩进；▾ / ▸ 折叠。颜色表示层级：顶层对话绿点、第 2 层 subagent 蓝点、更深层紫点、已结束灰点。
• 每行右侧显示模型短标签（来自会话投影 modelSelection，next → lastUsed）；subagent 无独立记录时继承上级，悬停有说明。

胶囊与窗口头¶

• 空闲时收成胶囊，例如 🌳 Agent Tree Dock 加可选计数：琥珀「N 待处理」、绿色 🤖N（在跑）、⏰N（定时）；非零才显示。点击或 Enter / Space 展开，可拖动；位置记在 localStorage（dsh-agent-tree:pos）。
• 卡片顶栏（Agent Tree Dock）：状态副行（待处理 · 在跑 · 定时）、换皮肤、检查更新（仅点击时向 npm registry 只读 GET）、最小化。

待办与定时¶

• pendingInteraction 为 question / approval / plan-review 的会话：琥珀色行、待答 / 待批 / 待审 徽标，排在在跑会话之前（避免「没在跑就从列表消失」）。
• 定时任务读 Automation 的 schedule.catalog()（服务 remote.schedule，命名空间未挂载时用 ctx.get 兜底）；间歇工作的会话即使当前未跑也会列出，右侧显示 ⏱ 倒计时。

多 DSH 实例与本机外部 agent¶

• 同时运行多个 dsh web --port 30xx 时，其他实例上仍在干活或待拍板的会话会出现在卡上，每个实例一个顶层节点（如 dsh :3083）；点行可在新标签打开对应实例。发现方式为本机 ps + lsof，走本地文件，无需跨实例鉴权。
• 宿主半部只读接口 GET /local/dsh-agent-tree/processes：识别本机 claude / codex CLI 及 Claude 桌面版主进程等，与 dsh 同级展示；codex 行名优先取自 rollout 首条真实用户消息，子线程按 parent_thread_id 从 ~/.codex/sessions/**/rollout-*.jsonl 还原。除用户主动点「检查更新」外，插件不联网、不外发会话内容。

交互与其它¶

• 点任意一行：subagentAddress(id) + uiWorkspace.openSession()，subagent 可直达其对话。
• 内置六套皮肤（默认 / 樱花 / 鲸鱼娘等），可经 window.__DSH_AGENT_TREE_SKINS__ 扩展，见仓库 皮肤指南。
• macOS 可选 npm run dock 将同一张卡片以透明置顶浮窗显示（见 桌面浮窗指南）。

卡高随内容自适应，最多约 48 行；底部有会话 / 子代理 / 运行中数量自检，live 表示接入了官方实时状态流。

安装与启用¶

前置与 DSH 运行时一致：Node.js ^22.19 或 ≥24，pnpm 10+，DSH ≥ 0.2.0-rc.2 且 < 0.3（README 写明 0.2.0-rc.2 与 0.2.1-rc.2 已实测）。

下面用独立 profile 安装并启动：

# 1) 建一个专用 profile（也可以装到现有的 web profile）
dsh --profile agent-tree --from-default-profile web

# 2) 从 npm 安装
dsh plugin --profile agent-tree add dsh-plugin-agent-tree

# 3) 启动
dsh --profile agent-tree --port 13090

装到已有 profile：

dsh plugin --profile web add dsh-plugin-agent-tree

从 GitHub 源码安装（适合改代码）：

dsh plugin --profile web add "github:yuna78/dsh-agent-tree"

装完后必须重启一次 dsh（宿主半部注册了进程接口），浏览器硬刷新（Cmd/Ctrl + Shift + R）。卸载与排查见仓库 安装与配置。

典型用法¶

1. 打开 DSH Web，看右下角胶囊或展开后的 Agent Tree Dock。
2. 优先处理顶部的琥珀色「待答 / 待批 / 待审」行；绿色/蓝/紫点行表示各层 agent 在跑或刚结束的状态。
3. 需要跳转时点击对应行，会打开该会话（含 subagent）。
4. 多开端口时展开 dsh :端口 节点，查看其它实例上仍在运行的分支；本机 codex/claude 在顶层与 dsh 并列。
5. 窗口头转圈按钮手动检查 npm 最新版；有新版会给出可复制升级命令，结果缓存约 30 分钟。

界面元素对照表见 GitHub README「怎么用」 与 使用手册。

适用场景与注意¶

适合经常在 DSH 里跑主 agent + subagent、或同时开多个 Web 端口、并在本机还有 claude/codex CLI 的开发者：用一张小卡统一看「谁在跑、在哪一层、用什么模型、定时何时触发、哪里需要你拍板」。

请注意：

• 插件以当前 DSH 进程的用户权限运行；宿主半部会执行只读的 ps、lsof 并读取本机会话与 codex rollout 等路径。安装前应阅读源码与 MIT 许可证，确认可接受其数据范围（README「外部进程监控：范围与边界」一节有说明）。
• 引擎约束见 package.json：dsh peer 为 >=0.2.0-rc.2 <0.3.0；与更高或更低主版本是否兼容需自行对照 DSH 发行说明。
• 社区目录 skillhub.cn 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 生态本身是「一切皆插件」的思路，本插件是其中一条可观测性补充。

结尾¶

Agent Tree 不替代 DSH 侧栏，而是补 agent 谱系与跨实例、跨 CLI 的一屏视图：288px 常驻、有活展开、无活收成胶囊。若要安装命令、皮肤与桌面浮窗细节，以仓库 README 与 docs/ 为准。

• 目录页：https://www.skillhub.cn/plugins/yuna78/dsh-agent-tree
• GitHub：https://github.com/yuna78/dsh-agent-tree