前言¶
在 DeepSeek Harness（DSH）里跑 agent 时，任务清单往往通过官方的 todo_write 写在会话投影里。清单在后台更新，但 Web 界面默认没有一块始终可见、又能一眼看出「做到哪了」的区域。你要么翻对话找 agent 刚写的计划，要么心里记「已完成几项、当前在做哪条」。
dsh-plan-progress-pill 是社区维护的客户端 overlay 插件，在 DSH Web UI 右上角（窄屏时落到底部）挂一个可折叠的「计划与进度胶囊」：数据直接来自官方 todos 投影，agent 每更新一次清单，浮窗会跟着刷新。下面介绍它做什么、怎么装、怎么用。
这是什么¶
- 名称：
dsh-plan-progress-pill（npm 包名同） - 维护者：darkzhexue
- 分类：客户端（
dsh.client，平台web） - 许可证：MIT
- 一句话：在 DSH Web UI 叠加层上显示可收纳的会话计划与进度胶囊，展示当前会话 todo 列表、已完成数量与当前任务。
插件不替代 todo_write，也不改服务端逻辑；它只读取宿主暴露的 todos 会话投影并渲染 UI。当前会话没有任务清单时会自动隐藏。
生态上，DSH 强调「一切皆插件」；SkillHub 目录页 是社区站点，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
数据来源与刷新¶
- 数据源是官方
todo_write写入的todos会话投影（turn/start时清空、turn/end保留完成清单）。 - Agent 每更新一次任务清单，浮窗立即刷新。
胶囊与完整任务卡两态¶
- 折叠（胶囊）：进度环、当前进行中任务摘要、
已完成 n/m；点击胶囊或箭头可展开。 - 展开：完整任务列表；再点收起。收起状态按标签页记在
sessionStorage。 - 完整任务视图：每项带状态（已完成 / 进行中 / 待处理）、进度条、完成百分比与「全部完成」状态。
布局与跟随会话¶
- 位置在运行时对齐会话头部（标签行）下沿，尽量不盖住右上角工具按钮；窗口宽度 ≤720px 时自动落到底部。
- 随当前会话切换；无清单时不占位。
- 颜色使用宿主主题 token（
--dsw-alias-*），亮/暗主题与桌面端、Web 端一致。
宿主依赖¶
插件依赖 DSH 提供的 slots、locale、uiSession 等客户端服务，以及 todo_write 的 todos 投影。package.json 中声明的客户端注入包括 @deepseek-ai/dsh-client-locale、@deepseek-ai/dsh-client-ui-slots、@deepseek-ai/dsh-client-ui-session、@deepseek-ai/dsh-client-ui-conversation。
安装与启用¶
README 写明：npm 包 dsh-plan-progress-pill 尚在发布流程中，推荐从源码或预构建包安装。安装前请自行查看 GitHub 仓库 源码与 MIT 许可证；插件在当前 DSH 进程权限下作为客户端 bundle 加载，与任何社区插件一样，安装前应确认你信任维护者与代码内容。
方式一：Release 预构建包（无需本地构建）
- 在 Releases 下载
dsh-plan-progress-pill.tgz并解压。 - 桌面版打开「插件」页面 → 安装 bundle → 选择解压后的目录；或使用 dsh CLI 安装该本地目录。
- 刷新会话页，右上角应出现胶囊。
方式二：已有插件目录时
若你已通过其他方式取得仓库目录（例如自行下载源码归档），同样用「安装 bundle」或 CLI 指向该目录即可。
修改插件代码后，README 要求先 remove_bundle 再 install_bundle，并刷新页面。
典型用法¶
- 按上一节完成安装并刷新 DSH 会话页。
- 在会话中让 agent 使用官方
todo_write维护任务清单（创建、更新状态、标记完成等）。 - 观察右上角胶囊：默认收起时看当前任务与
n/m；需要核对全文时展开列表。 - 切换会话时浮窗跟随；若该会话没有
todos投影，浮窗不显示。
无需额外配置项；README 未列出独立配置文件，行为由宿主 todos 与 UI 主题 token 决定。
兼容性与适用场景¶
兼容性（README 已验证）
- DSH Web 端与桌面版，已验证版本
0.2.1-rc.2。 - 需要宿主提供上述客户端服务与
todo_write的todos投影。
适合谁
- 经常在 DSH Web / 桌面 UI 里跑长任务、依赖 agent 维护 todo 清单的开发者。
- 希望在主界面固定位置看到「计划 + 进度」，而不是只在对话流里偶尔看到清单更新的用户。
注意
- 没有
todo_write或会话无清单时，插件不会显示内容，这是预期行为。 - 窄屏下浮窗在底部，布局与桌面宽屏略有不同。
- 社区目录星标等信息以站点为准；撰写时 GitHub 星标为 0，不代表功能缺失，仅作索引参考。
结尾¶
dsh-plan-progress-pill 把官方 todos 投影做成右上角可折叠的进度胶囊，不挡控件、跟会话走、主题随宿主。若你已在用 DSH 的 todo_write，装好后刷新页面，让 agent 更新一次任务清单即可验证。
- 目录页：https://www.skillhub.cn/plugins/darkzhexue/dsh-plan-progress-pill
- 源码与说明：https://github.com/darkzhexue/dsh-plan-progress-pill
