前言¶
在 DSH 里让 agent 跑长任务时，一个常见问题是看不清它此刻在做什么：目标进行到第几轮、哪些 subagent 在跑、workflow 到了哪个阶段、后台任务有没有失败。这些信息分散在会话的不同位置，不开日志就得来回切换查看。
dsh-agent-pill 解决的是这个可见性问题：把当前会话的关键活动浓缩成右上角一颗状态胶囊，需要细节时再用快捷键展开悬浮面板。下面按功能、架构、安装与用法的顺序介绍。
这是什么¶
dsh-agent-pill 是 mozhuanzuojing 维护的 DSH web 插件，MIT 许可证，当前版本 0.14.8。一句话定位：ZCode 风格的 agent 活动胶囊（右上角状态胶囊）+ 悬浮摘要面板，Ctrl+Alt+P 切换。
插件分两半：
- host 半：聚合当前会话的 Goal / Subagents / Agent 状态 / workflow 运行 / 后台任务，经
/pill/api暴露带完整控制动词的 JSON API。 - client 半：右上角浮动胶囊 + 锚定胶囊的 tooltip 式悬浮面板，内含 goal 卡片、workflow 历史（步骤与观察文件）、subagent 树、任务列表（输出 / kill）。
核心功能¶
胶囊与悬浮面板¶
1、Ctrl+Alt+P 切换面板，点击胶囊同样有效。
2、面板是锚定胶囊的轻量 popover，不是固定右侧抽屉：会在四个视口边缘间翻转以保持完整可见，高约 70vh 内部滚动，点击外部、Esc 或再按快捷键关闭。
3、宽度自适应（v0.9.0）：ResizeObserver 驱动，在 320–520px 内夹紧并以视口为上限；diff 行保持 white-space: pre 不换行。
4、胶囊可拖拽到任意屏幕边缘，位置持久化到 localStorage，窗口缩放时仍夹紧在视口内。
5、主题跟随 DSH：配色由 CSS 变量驱动，响应 <body data-ds-dark-theme> 信号，白色 / 暗色（moon night）即时切换，含跟随操作系统的 system 模式。
6、分区折叠：Goal / Agent / Subagents / Jobs 分区头可点击折叠，状态存 localStorage；v0.13.0 起默认展开。
7、空状态隐藏（v0.6.0）：没有目标的 Goal、没有子节点的 Subagents、没有条目的 Jobs、没有事件的 Activity 整体隐藏——只显示存在的内容。
8、详情层（v0.7.0）：点击 workflow 运行或 subagent 行，在弹层内推入新的详情层（头部有返回按钮）；目标消失时自动返回，会话切换时重置。subagent 详情含身份、模式、计时、终止状态和停止控制。
Goal 卡片与 workflow 历史¶
- Goal 卡片显示目标、阶段、轮数、经过时间与激活状态，带轮数进度条（
roundsStarted / maxGoalRounds）。 - workflow 历史（v0.4.0）：最近 5 次运行的有界环。每次运行可展开看步骤（每次
agent()调用的 seq / label / phase / outcome）与运行期间观察的文件（来自 host 的fs/observed流，去重后按运行归因）。已结束的运行保留详情，直到被新运行替换。 - 步骤与 subagent 关联（v0.6.0）：步骤行通过 childId 关联 subagent 行，显示子代理时长与终止颜色。
- 文件 diff（v0.8.0 / v0.9.0）：workflow 文件 chips 打开文件详情层，展示结果时行级 diff（来自
dsh-tool-fs的 tool/result meta，区分新文件 / 编辑 / 覆盖）加复制路径按钮；v0.9.0 起文件列表内联展开 diff，每文件带 +N/-N 徽标，默认仅变更行，可切换含上下文。 - 活动时间线（v0.9.0）：Activity 分区流式显示最近主机事件——工具调用与完成、文件活动（按路径合并计数）、workflow 阶段变化、subagent 起止、goal 变化，40 条有界环。
Subagent 树与后台任务¶
- Subagent 树按深度缩进，每行显示运行时长与终止 stop reason，失败为红色。时间戳来自 host 的
subagent/start/subagent/end事件。 - 后台任务渲染为单条步骤条目（状态、输出摘要、计时）；jobs 没有结构化步骤，因此不做文件提取。任务列表支持查看输出与 kill 终止。
实时状态与通知¶
- 胶囊摘要（v0.3.0）：目标经过时间加实时徽标——运行中 subagent、运行中任务、活动 workflow（
wf徽标，tooltip 里带当前阶段）、失败任务（红色）。 - 实时工具名（v0.5.0）：运行中会话的 in-flight 工具名显示在胶囊条与 tooltip，
tool/result后清除。 - 工具时长（v0.6.0）：
tool/call与tool/result配对显示，如⛭ write · 0s、✓ edit done · 12s。DSH 串行执行工具，单个 in-flight 槽位即可完成配对。 - 实时胶囊标签（v0.8.0）：胶囊文本优先显示运行中 workflow 的 name·phase，回退到当前工具名，再回退到
AGENT。 - 排队消息（v0.5.0）：
agent/inbox事件维护每会话排队数，胶囊显示q徽标。 - 完成通知（v0.5.0）：workflow 结束、后台任务失败、目标完成时各触发一次浏览器通知。权限为惰性请求；页面刷新时登记已结束 id，但不重放通知。
- 空闲长轮询（v0.8.0）：全部空闲时客户端停在 host 长轮询
POST /pill/api/poll（30s 上限），而不是每 1.5s 轮询；有活动即唤醒并恢复节奏。
会话内的文件记录（v0.14.x）¶
- turn-tail 文件行（
conversation.chat.turnTail）：会话里每条用户指令下方显示该指令处理的文件，带 +N/-N 徽标、内联 diff（仅变更行 / 含上下文可切换）和复制路径按钮。 - 忙碌时胶囊显示「第N轮 · 动作」。
历史说明：早期的 Usage 区块（token 压力 / 成本估算）与 Sessions fleet 视图已在 v0.12.0 移除，插件现在只显示当前会话存在的内容。
架构：契约单源与领域模块¶
v0.14.8 的架构调整围绕可测性与 AI 可导航性，把 host 半的编排模块按领域拆开：
1、契约单源：src/contract.ts 是 /pill JSON API 的 wire 契约单一事实源，host 与 client 都从它 import。此前 host 内联视图（GoalWireView / SubagentWireView）与 client 的 api.ts（PillGoal / PillState 等）是两份手写镜像，host 改字段会静默让 client 类型失效；现在 host 契约一改，client 编译期即报错。
2、领域深模块：src/goal-tracker.ts（goal 投影）、src/git-status.ts（纯解析与 TTL 缓存分离）、src/usage-snapshot.ts（token-meter + context-window）、src/subagents.ts（subagent 后代树）、src/jobs.ts（后台任务列表）各自带注入 seam，可单测；src/index.ts 回归薄 seam 接线加方法分发。
安装与启用¶
本文写作时抓取到的 README 与 package.json 中没有给出安装命令原文，这里不做拼接，请以仓库 README 为准：https://github.com/mozhuanzuojing/dsh-agent-pill
依赖方面可对照 package.json 核实：
- peerDependencies：
@deepseek-ai/cordis^4.0.2；@deepseek-ai/dsh-agent、@deepseek-ai/dsh-client-store、@deepseek-ai/dsh-goal、@deepseek-ai/dsh-jobs、@deepseek-ai/dsh-session、@deepseek-ai/dsh-subagent、@deepseek-ai/dsh-web-app均 ^0.1.2-rc.1；react/react-dom^18.2.0。 - package.json 的
dsh字段声明这是 web 平台插件，客户端注入@deepseek-ai/dsh-client-store。
日常用法¶
1、Ctrl+Alt+P 或点击胶囊切换摘要面板。
2、拖拽胶囊到屏幕任意边缘，位置跨刷新保留于 localStorage。
3、点击 Goal / Agent / Subagents / Jobs 分区头折叠或展开。
4、点击 workflow 运行或 subagent 行推入详情层，用头部返回按钮返回。
5、workflow 文件 chips 展开行级 diff，默认仅变更行，可切换带上下文，附复制路径按钮。
6、后台任务行内查看输出摘要，需要时 kill 终止。
适用场景与注意¶
适合长期跑 goal / workflow / 后台任务、想在不离开当前界面的情况下掌握 agent 进度的 DSH web 用户。如果你此前靠翻日志判断 agent 行为，Activity 时间线和 turn-tail 文件行会把“改了什么、走到哪”直接呈现在界面上。
注意：
1、插件以当前 dsh 进程的权限运行，host 半会聚合会话状态并暴露 /pill/api。安装前请检查源码与许可证（MIT），确认可接受再启用。
2、浏览器通知权限是首次触发时惰性请求的；刷新页面后已结束的事件不会重放通知。
3、Usage / Sessions 相关展示已在 v0.12.0 移除，按旧版本介绍找入口会落空。
小结¶
dsh-agent-pill 把 DSH 会话的活动状态压缩成一颗常驻胶囊和一个悬浮面板：不打开任何东西也能看到 agent 在做什么，展开后 goal、workflow、subagent、后台任务与文件 diff 都在手边。MIT 许可证，当前版本 0.14.8。
- 目录页：https://www.skillhub.cn/plugins/mozhuanzuojing/dsh-agent-pill
- GitHub：https://github.com/mozhuanzuojing/dsh-agent-pill
补充一句生态背景：DSH 的理念是「一切皆插件」，这类可见性工具适合按需加装；skillhub.cn 是社区维护的独立插件目录，与 DeepSeek / 幻方没有官方从属关系。
