# DSH 子代理工作区管理器
[English](README.md) | **中文**
面向 DeepSeek Harness Web 的子代理管理插件。插件在会话标题栏提供一个紧凑的 `🧩 子代理 active/total` 入口，用于搜索、筛选、分组、排序、查看和批量归档当前运行时已发现的子代理。
当前发布版本：**v1.9.1** —— 完整历史见 [`CHANGELOG.zh.md`](https://github.com/miuzel/dsh-subagent-ui/blob/HEAD/CHANGELOG.zh.md)（中文，回溯至 v1.0.1）与 [`CHANGELOG.md`](https://github.com/miuzel/dsh-subagent-ui/blob/HEAD/CHANGELOG.md)（English）。
## 安装
从 npm 安装已发布的包到 DSH Web profile：
```bash
dsh plugin --profile web add dsh-subagent-workspace-ui
```
升级到最新发布版本：
```bash
dsh plugin --profile web add dsh-subagent-workspace-ui@latest
# 或者等价地：
dsh plugin --profile web update dsh-subagent-workspace-ui
```
卸载：
```bash
dsh plugin --profile web remove dsh-subagent-workspace-ui
```
`dsh plugin --profile <参数…>` 会把参数转发给该 profile 内的 pnpm，因此 `add` / `update` / `remove` 等子命令按常规语义生效。**不需要 `--allow-build`**：发布 tarball 内含预构建的 `lib/`，且本包没有安装期生命周期脚本。
插件 bundle 会自动加载 [`cordis.patch.yml`](cordis.patch.yml)：安装期间插入管理器，并且**只遮蔽一个 slot**——用 `priority: -1` 的**标题位遮蔽**占用 `conversation.session.header.lineage`，从而让 DSH 自带的 `ui-subagent` 血统下拉保持不可见。自带 `ui-subagent` 插件本身**保持启用**（本插件不再整体禁用它），因为新版「在侧边栏打开」按钮正是复用它提供的 `subagentchat` 右侧栏标签页。该遮蔽渲染的是会话标题而不是空内容，所以子代理会话标题不会消失。卸载插件后，这层 bundle patch 会被移除，宿主的 `ui-subagent` 设置从未被改动，恢复如初。请重启现有的 `dsh web` 进程，然后刷新：
```text
http://127.0.0.1:3080
```
如果之前在 `$DSH_HOME/profiles/web/cordis.patch.yml` 中手动禁用了 `ui-subagent`，那条配置属于用户所有，插件不会覆盖、也不会依赖它——可以保留。
要在本地 checkout 上开发而不是用 npm 发布版？见[本地 checkout（贡献者）](#本地-checkout贡献者)。
## 主要功能
### 范围：标题栏入口、工作区与会话
- 标题栏入口显示活跃数 / 总数与活动动画点，不打开面板也能看到运行状态。
- 默认选择当前工作区。
- 默认选择当前主会话；即使当前页面已经进入某个子代理，会话管理器仍然以最上层主会话为基准。
- 工作区下拉框支持：
- 当前工作区
- 全部工作区
- 具体工作区列表
- 会话下拉框支持：
- 全部会话
- 当前工作区内的会话
- 当前会话标记
- 支持通过 `id:` 前缀单独搜索 Session ID，例如：
```text
id: graph:g-a92e1406
```
普通搜索不会把 Session ID 或父会话 ID 当作搜索字段。
### 搜索、排序与分组
- 普通搜索匹配子代理名称、标题和工作区名称。
- 支持按以下方式排序：
- 最近活跃
- 名字
- 类型
- “最近活跃”优先使用 DSH 提供的 `updatedAt`。
- 最近进入运行状态的子代理会被记录，即使运行结束后仍会保持靠前显示。
- 支持以下分组：
- 按会话
- 按工作区
- 按分类
- 按类型
- 不分组
- 按会话分组时，分组标题显示“工作区 · 会话名称”，卡片中不再重复显示相同的归属信息。
- 活跃子代理单独置顶，并可折叠。
### 分类标签
内置分类包括：
- 全部
- 其他
- 审计
- 测试
- 实现
- 规划
分类标签会显示当前数量，超过 99 个显示为 `99+`。
用户可以创建自定义正则分类。自定义分类支持：
- 标签内显示数量。
- 未选中时不显示选中高亮。
- 删除前确认。
- 删除按钮与分类名称处于同一个标签框内。
一次性子代理名称后显示紧凑标签：
```text
⚡ 一次性
```
可继续子代理不显示额外类型标签。
### 过滤与隐藏
支持以下过滤与个性化选项：
- 隐藏一次性
- 隐藏长期未活跃
- 显示已隐藏
- 显示活跃浮窗
- **子代理背景色自定义**：可开启/关闭子代理会话的独立背景色，支持分别配置深色主题与浅色主题下的背景色，进入子代理时一目了然。
- 重置筛选
隐藏是插件本地状态，只在列表不显示子代理，不会删除 DSH 会话或工作区文件。默认情况下：
- 列表不显示已隐藏子代理。
- 标题栏入口的总数和活跃数扣除已隐藏子代理。
- 勾选“隐藏一次性”后，入口按钮统计也会扣除一次性子代理。
- 卡片右侧提供 **👁 隐藏** / **🙈 取消隐藏** 按钮。
### 暂停、继续与一键暂停
- **浮窗一键暂停**：活跃子代理浮窗头部提供“⏸ 一键暂停”按钮，点击并二次确认后批量暂停所有活跃的可继续子代理。
- **浮窗单项暂停**：浮窗内每个正在运行的可继续子代理卡片均有“⏸ 暂停”按钮，点击确认后暂停该子代理。
- **管理面板单项暂停**：列表和活跃分组中的每个运行中可继续子代理均有“⏸ 暂停”按钮。
- **管理面板一键暂停**：“活跃子代理”折叠分组头部右侧提供“⏸ 一键暂停”按钮，支持一键暂停全部活跃子代理。
- **继续已结束的子代理**：已结束（非运行中）的可继续子代理行在操作区显示“▶ 继续”，点击后向该子代理发送一条**本地化**的继续指令（中文界面「继续」、英文界面 “continue”），让它接着跑。运行中与一次性子代理的行不显示该按钮；宿主没有该能力时**按钮不渲染**（纯能力探测，从不比较版本号）。管理器面板本身就在父会话 header 里，所以“父会话 agent 必须存活”这一前提在正常使用下天然满足；父会话不可用时只在控制台告警，不会把异常抛给用户。
### 批量操作与永久删除
点击结果统计右侧的“批量操作”进入批量模式。批量模式下：
- 整张子代理卡片都变为选择区域。
- 点击卡片任意位置即可选中或取消选中。
- 复选框支持普通选择和 Shift 连续选择。
- 不会跳转到子代理会话。
- 隐藏单个操作按钮。
- 已隐藏项显示 `已隐藏` 标签。
- “完成”按钮使用高亮样式，点击后退出批量模式。
可用批量操作：
- 全选当前筛选结果。
- 清空选择。
- 选择 N 小时以前的子代理。
- 批量隐藏 / 批量取消隐藏 / 一键全部隐藏。
- **批量删除**：将选中的子代理永久从磁盘、投影缓存、工作区索引和内存会话中彻底销毁。
- **一键删除全部**：一键彻底清理当前视图中的所有子代理。
单项卡片在非批量模式下也提供 **🗑 删除** 按钮，点击确认后彻底销毁。所有删除操作完全由人类用户在 UI 侧主动操作，子代理不会也不需要耗费时间去感知或调用工具。
### 实时活动与流式输出
当 DSH 会话 API 提供绑定会话与实时事件时，卡片底部会显示实时活动：
- 最新两行模型文本或思考文本。
- 正在运行的工具调用，例如 `Read`、`Bash`（优先显示工具说明或目标文件名）。
- 最近完成的工具调用及成功/失败状态。
- 上下文注入，例如 `skill-catalog` 或插件系统提示。
- 命令状态。
实时输出具有金属光泽扫光动效；子代理结束后保留最后显示快照，并变为灰色。输出区域最多显示两行，避免持续滚动导致内容难以阅读。
**每个运行中的子代理都有自己的实时流（dsh 0.1.6-alpha.2 起）**：宿主 `sessions.binding(id)` 的契约是「借用已被保留的绑定，不创建保留」，而官方客户端里唯一保留会话的是主会话视图——它只保留**当前选中**的那一个。因此插件改为自己成为保留者：`sessions.retain(target, { source: 'subagentWorkspaceUi' })` 拿到 `SessionReference`，用 `reference.binding` 取 `session` / `eventSource`，不再依赖「是否被选中」。
保留是有界且成对释放的：
- **浮窗常驻**：浮窗显示期间，对其中每个运行中的子代理各保留一个引用。
- **面板仅可见行**：管理面板只对当前筛选/分组后**实际渲染出来**的运行中行保留，打开面板不会去加载全部历史子代理。
- **上限 8**：浮窗优先，其次按最近活动优先；超出上限的运行中行按快照显示（仍有用量等持久信息）。
- **成对释放**：行不再渲染、子代理转为非运行态、浮窗/面板关闭或插件卸载时调用 `release()`；重复释放幂等。
**兼容两个 API 代际（自动探测）**：
- dsh **0.1.6-alpha.2** 起：自己 `retain`（`reference.binding.eventSource` 原始 `SessionEvent` 事件流）；宿主未提供 `retain` 时回退借用式 `binding(id)`。
- dsh **0.1.2-alpha.2**：`binding.eventSource`（原始 `SessionEvent` 事件流）推导实时输出。
- dsh **0.1.1-rc.2** 及更早：回退 `session.getSnapshot().chat.legacy`（对话快照）路径。
按能力探测自动切换（不判版本号），向前兼容，老版本行为不变；两条路径都拿不到绑定时，界面回退到持久化摘要。
已结束的行还会用状态点区分结束方式：**正常结束为空心绿环，异常结束（⏸ 停止/aborted、error、blocked、max-tokens 等）为实心红点**，hover 显示「正常结束 / 异常结束」文字（zh+en）。判定只读子代理自身的公共只读投影 `subagentTiming.lastTurnCompleted`（宿主仅在 `turn/end` 写入、`turn/start` 删除）；宿主不提供该投影时**保持原样**，绝不把“未知”显示成“正常”，运行中的行保持原绿点。
### 外部代理（Claude Code / Codex）
- **可见**：`@deepseek-ai/dsh-subagent-claude-code` / `@deepseek-ai/dsh-subagent-codex` 添加的子代理会出现在面板里，标注「外部代理」并跟上宿主如实上报的引擎名（`Claude Code`、`Codex`；插件不认识的 provider 原样显示其 id）。头部计数一并算入。
- **为什么需要专门处理**：这类子代理以 `mode: 'external'` 记入 catalog，**根本没有本地会话**，所以面板原本那套「从会话摘要取行」的路径永远造不出它们；它们的行由父会话 catalog 合成。
- **状态是测出来的，不是猜的**：宿主对它们的 `activity` 是写死的 `'inactive'`（去找一个不存在的会话），唯一诚实的信号是 `subagent/start` / `subagent/end` 这对事件。因此测不到边沿时不显示「已结束」，而是显示「状态不可得」——**宁可说不知道，也不假报结束**。
- **可停止**：运行中提供「⏹ 停止」，走宿主路由自行解析该次运行（浏览器不指定父会话）；被中止的委派会如实告知模型。
### 打开与查看子代理
- **精确地址打开**：点击卡片把子代理打开到主对话区，地址为 `{ parentSessionId, childSessionId, mode }`；批量模式下卡片整体变为选择区域，归档控件不会触发跳转。降级顺序见「打开子代理会话的三级能力探测」。
- **`◫` 在右侧边栏打开**：不离开主对话即可把子代理开成 DSH 自带的 `subagentchat` 标签页；纯能力探测，且按行、按次解析。详见「在右侧边栏打开子代理（`◫` 按钮）」。
- **类型与模型**：`provider/model`（宿主发布时附推理档位）只读宿主公开投影，类型与模型各自独立降级；不新增任何 RPC，也不提供模型切换入口。详见「类型与模型（只读投影）」。
- **行内用量**：卡片详情行与浮窗共用同一行 `↑ 计费输入 (未缓存…) / ↓ 输出 · 命中 n% · tps · 轮数 · 步数`，口径与官方 composer 页脚一致；完整信息（总量、各分桶、命中率、速度、模型/工具/首字耗时）在原生 `title` tooltip 中。
### 子代理会话内预览提示词
- 子代理收到的提示词往往是一整篇结构化 markdown（任务书、评审要求、核查清单）。因此子会话里每条用户消息在官方操作行多一个 `原文` / `预览` 切换：`预览` 把该消息的原始文本**按 markdown 渲染**成块，`原文` 一键切回官方渲染；「原文」按钮固定在块**右上角**（折叠时旁边还有「展开」）。两态切换不产生布局跳动，点开预览时只在块**原本不在视野内**才把它的顶部滚入视野。
- 渲染器**完全自研、只创建文本节点**：标题、嵌套有序/无序列表、粗体斜体、行内代码、带语言标注的围栏代码、嵌套引用块，以及目标为 `http(s)` 或相对路径的链接。不引第三方 markdown 库、不用 `dangerouslySetInnerHTML`、不用 `innerHTML`，因此注入的 `