前言¶
DSH 里跑多智能体时，Lead 派出成员，成员再派孙代理。层数一多，人脑就记不住谁派生了谁：排查问题时盯着某个成员的输出，其实要往上找它的父会话才知道上下文从哪来。现有的办法是翻日志、手动对照 session 列表，效率不高。
dsh-agent-tree 解决的就是这件事：它读取会话快照里的 parentSessionId，把多层代理关系画成一棵实时树，并附带团队焦点、真状态点和模型路由中心。维护者为 ruaruaTon，分类属于工作流，来源是 GitHub 仓库，许可证 MIT，当前版本 0.4.5，仓库星标为 0，属于比较新的项目。
下面按「能做什么 → 安装 → 配置 → 数据原理 → 边界」的顺序介绍。
一、核心功能¶
1. 代际树¶
按会话快照的 parentSessionId 建树，层级没有上限，成员、孙代理、重孙代理都会挂到对应父节点下。这一层用的是 client 侧数据，不需要宿主事件，构建成本低。
2. 两种视图¶
- 宽容器（中心面板 ≥ 760px）渲染横向组织树，卡片加连接线；
- 窄容器（右栏页签）自动切成缩进列表；
- 拖动分栏会实时切换视图，不需要重启或刷新。
3. 真状态点¶
host 半订阅 agent/created 与 agent/status 事件，并结合 agents 的即时活性：🔵活跃、🟢已结束、🟡待命、⚪沉睡、🔴失败。事件缺失时会降级为按活跃时间推断，面板不会因此空白。
4. 团队焦点与只看活跃¶
多团队并行时默认锁定最新派出的团队，可以用下拉一键切换，焦点视图支持 1.5× 放大。默认折叠 2 小时无活动的沉睡叶枝，也可以一键展开全量。
5. 模型路由中心（可选增强）¶
需要 dsh-plugin-subagent-director。开启后有两件事：
- 孙代理默认模型可热配置，写入 subagent-director 设置后立即生效；白名单模式开启时会自动收敛到授权路由。
- 孙代理节点挂上实际运行路由的标签，读取 session 的 request/header，走的是官方通道。
另有团队覆盖层，依赖 @nanmicoder/dsh-agent-teams，提供团队名册、任务计数和成员模型路由，点 💬 可直接跳到成员会话。
二、安装与启用¶
插件市场¶
在 DSH 里走「插件 → 添加插件」，搜索 dsh-agent-tree，或把仓库地址粘进添加框即可。
npm 方式¶
dsh plugin --profile <你的profile> add dsh-agent-tree
安装后重启一次 DSH，侧边栏出现「代际树」图标即表示成功。
环境要求¶
DeepSeek Harness >= 0.2.1-rc.2，README 记录在 0.2.1-rc.5 Desktop / Windows 上实测。两个可选增强不装也能正常使用，面板会自动降级。
三、想看到孙代理，两道闸要打开¶
孙代理（成员的子代理）默认被两道闸拦住，面板要显示它们需要同时满足：
subagent:
maxDepth: 2
- id: agent-teams
memberMaxDepth: 1
对应两处配置：
- 宿主深度：插件 → 子智能体 → 限制，
maxDepth≥ 2（或在cordis.patch.yml里写subagent.maxDepth: 2）。 - 团队成员派生权限：agent-teams 的
memberMaxDepth: 1，写在cordis.patch.yml的- id: agent-teams条目里。
改完需要重启一次 DSH。
四、数据从哪里来¶
| 数据 | 来源 | 说明 |
|---|---|---|
| 血缘树 | 会话快照 parentSessionId（client 侧） |
无需宿主事件，稳定低风险 |
| 团队 / 成员 / 路由 | .agent-teams/*/team.json（host 半读取） |
成员 id 即会话 id，可直接跳转 |
| 真状态 | agent/created + agent/status 事件 + agents 即时活性（host 半订阅） |
事件仅本进程内，重启后旧会话自动降级为时间推断 |
| 孙代实际路由 | subagent-director 桥接 subagentModel（session request/header） |
官方可观测性同源 |
| 模型目录 | 宿主模型目录（三级回退读取） | 与任务看板同款 |
数据源不止一个，排查显示问题时可以先定位是快照缺失还是事件缺失。
五、故障排除¶
- 启动失败弹窗：只点「Exit」，不要点 Disable third-party plugins。把
%APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*.log附到 issue 上。 - 面板空白 / 没有图标：改过 client.js 之后要重启一次；同时确认 bundles 里有
agent-tree。 - 团队覆盖层提示 cwd 缺失：当前根会话的快照没有工作区字段，血缘树不受影响。
六、适用场景与注意¶
适合已经在 DSH 里跑多智能体、层级至少到成员一层，并且希望在界面上而不是日志里看到代理关系的人。如果只有一层 Lead → 成员，这个面板带来的增量有限。
安装前应该自己读一遍源码。插件以当前 DSH 进程的权限运行，其中自带的 cordis.patch.yml 会修改宿主运行时行为。许可证是 MIT，使用和修改都比较自由。
已知边界：模型路由中心的写入依赖 subagent-director 桥接。在 headless 环境或未安装该插件时，该区块只显示降级提示，其余功能不受影响。
结尾¶
dsh-agent-tree 没有引入新的代理调度逻辑，只是把已有的会话快照和宿主事件投影成一棵可交互的树。分层一深，这层可见性的提升会比较明显。
- GitHub：https://github.com/ruaruaTon/dsh-agent-tree
- 插件目录页：https://www.skillhub.cn/plugins/ruaruaTon/dsh-agent-tree
