dsh-subagent-workspace-ui

dsh plugin --profile web add dsh-subagent-workspace-ui

DSH 子代理工作区管理器

[English](README.md) | 中文

<p align="center"> <img src="https://raw.githubusercontent.com/miuzel/dsh-subagent-ui/main/docs/banner.png" alt="DSH 子代理工作区管理器 —— 子代理管理器与实时浮窗" width="100%"> </p>

<p align="center"> <a href="https://www.npmjs.com/package/dsh-subagent-workspace-ui"><img src="https://img.shields.io/npm/v/dsh-subagent-workspace-ui?style=flat-square&label=npm&color=cb3837" alt="npm 版本"></a> <a href="https://www.npmjs.com/package/dsh-subagent-workspace-ui"><img src="https://img.shields.io/npm/dm/dsh-subagent-workspace-ui?style=flat-square&label=downloads&color=cb3837" alt="npm 下载量"></a> <a href="LICENSE"><img src="https://img.shields.io/npm/l/dsh-subagent-workspace-ui?style=flat-square&label=license&color=green" alt="许可证"></a> <a href="https://awesome-dsh-plugin.com"><img src="https://img.shields.io/badge/awesome--dsh--plugin-listed-2f6feb?style=flat-square" alt="已收录于 awesome-dsh-plugin（聚合索引，非官方 curated 列表）"></a> <a href="#兼容性"><img src="https://img.shields.io/badge/DSH-%3E%3D0.1.5--rc.3-2f6feb?style=flat-square" alt="dsh 宿主版本范围：0.1.5-rc.3 起"></a> </p>

面向 DeepSeek Harness Web 的子代理管理插件。插件在会话标题栏提供一个紧凑的 🧩 子代理 active/total 入口，用于搜索、筛选、分组、排序、查看和批量归档当前运行时已发现的子代理。

当前发布版本：v1.9.1 —— 完整历史见 CHANGELOG.zh.md（中文，回溯至 v1.0.1）与 CHANGELOG.md（English）。

安装

从 npm 安装已发布的包到 DSH Web profile：

dsh plugin --profile web add dsh-subagent-workspace-ui

升级到最新发布版本：

dsh plugin --profile web add dsh-subagent-workspace-ui@latest
# 或者等价地：
dsh plugin --profile web update dsh-subagent-workspace-ui

卸载：

dsh plugin --profile web remove dsh-subagent-workspace-ui

dsh plugin --profile <name> <参数…> 会把参数转发给该 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 进程，然后刷新：

http://127.0.0.1:3080

如果之前在 $DSH_HOME/profiles/web/cordis.patch.yml 中手动禁用了 ui-subagent，那条配置属于用户所有，插件不会覆盖、也不会依赖它——可以保留。

要在本地 checkout 上开发而不是用 npm 发布版？见[本地 checkout（贡献者）](#本地-checkout贡献者)。

主要功能

范围：标题栏入口、工作区与会话

• 标题栏入口显示活跃数 / 总数与活动动画点，不打开面板也能看到运行状态。
• 默认选择当前工作区。
• 默认选择当前主会话；即使当前页面已经进入某个子代理，会话管理器仍然以最上层主会话为基准。
• 工作区下拉框支持：
• 当前工作区
• 全部工作区
• 具体工作区列表
• 会话下拉框支持：
• 全部会话
• 当前工作区内的会话
• 当前会话标记
• 支持通过 id: 前缀单独搜索 Session ID，例如：

  id: graph:g-a92e1406

普通搜索不会把 Session ID 或父会话 ID 当作搜索字段。

搜索、排序与分组

• 普通搜索匹配子代理名称、标题和工作区名称。
• 支持按以下方式排序：
• 最近活跃
• 名字
• 类型
• “最近活跃”优先使用 DSH 提供的 updatedAt。
• 最近进入运行状态的子代理会被记录，即使运行结束后仍会保持靠前显示。
• 支持以下分组：
• 按会话
• 按工作区
• 按分类
• 按类型
• 不分组
• 按会话分组时，分组标题显示“工作区 · 会话名称”，卡片中不再重复显示相同的归属信息。
• 活跃子代理单独置顶，并可折叠。

分类标签

内置分类包括：

• 全部
• 其他
• 审计
• 测试
• 实现
• 规划

分类标签会显示当前数量，超过 99 个显示为 99+。

用户可以创建自定义正则分类。自定义分类支持：

• 标签内显示数量。
• 未选中时不显示选中高亮。
• 删除前确认。
• 删除按钮与分类名称处于同一个标签框内。

一次性子代理名称后显示紧凑标签：

⚡ 一次性

可继续子代理不显示额外类型标签。

过滤与隐藏

支持以下过滤与个性化选项：

• 隐藏一次性
• 隐藏长期未活跃
• 显示已隐藏
• 显示活跃浮窗
• 子代理背景色自定义：可开启/关闭子代理会话的独立背景色，支持分别配置深色主题与浅色主题下的背景色，进入子代理时一目了然。
• 重置筛选

隐藏是插件本地状态，只在列表不显示子代理，不会删除 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/d

…(truncated)