前言¶
在 DSH 里用 dsh web pet 时，状态气泡通常只反映智能体「此刻」在做什么：思考、调工具、回合结束。长任务做到九成和刚起步，在宠物上看起来差不多，因为宠物本身没有「还剩多少」这一层信息。
dsh-pet-progress（维护者 Elefseus，社区分类：趣味换装）是挂在宠物旁边的进度伴侣插件：它读取会话里已有的 todo/write、goal/change 等事件，把完成比例折进宠物上方的气泡；没有待办或目标时，则退回一行纯活动说明，而不是硬凑百分比。
这是什么¶
一句话：把智能体写入会话的待办列表与目标轮次，汇总成宠物状态气泡里的进度（或当前活动行）。
- 仓库：Elefseus/dsh-pet-progress
- 目录页：skillhub.cn 插件条目
- 许可证：MIT（见仓库 README）
- 当前 package 版本：
0.1.0（以package.json为准）
插件通过宠物的插件接缝（announce、registerPanelAction、session/event）工作，属于 host-only，不向客户端单独打 bundle。
核心功能¶
气泡里会出现什么¶
待办或目标变化时，宠物上方会出现一行小气泡，典型情况如下（与 README 一致）：
| 情况 | 气泡表现 |
|---|---|
| 待办列表，一项进行中 | 3/7 · 43%，标题为该项任务 |
| 多项同时进行 | 同上比例，列出最多三项任务名，其余用 +N |
| 待办全部完成 | 绿色「任务全部完成」，约 10 秒后消失 |
| 长期目标、无待办 | 如 2/8 轮（目标轮次预算） |
| 目标完成 | 绿色「目标完成」，短暂显示 |
| 目标被阻塞 | 显示阻塞原因，替代进度数字 |
| 既无待办也无目标 | 无百分比的一行：思考（正在思考）、最近输出（最近输出）、或当前工具用途（当前过程） |
多会话同时打开时，最近活跃的会话占用气泡。常显气泡在最后一次进度更新约 30 秒后会淡出；「完成」类瞬间提示只宣布一次，并保留约 10 秒以免被下一轮输出立刻盖掉。
查看完整待办¶
气泡只有一行。在宠物面板上点 进度，完整待办列表会写入 dsh 日志，便于核对。
行为原则（README 中的 Good to know）¶
- 不夸大进度：无法识别的待办状态按未完成计；若一整次写入都不可读，则保留上一次有效信息。
- 不猜测任务名：只展示实际进行中的项（最多三个，每项截断至 32 字符），多项并行用
+N，不会随便挑一个冒充「当前工作」。 - 只读会话事件算百分比，不按运行时长推断；没有待办/目标时显示活动行。
- 无任务列表时，跟随模型流式输出与工具说明（例如
正在调用 read：progress.ts），而不只写「正在调工具」。
安装与启用¶
安装使用插件完整 GitHub URL（不要用 github:owner/repo 形式拼接）：
dsh plugin add https://github.com/Elefseus/dsh-pet-progress
若使用命名 profile，将命令中的 add 前加上 profile 参数，例如：
dsh plugin --profile <name> add https://github.com/Elefseus/dsh-pet-progress
必须先安装 dsh web pet（peer：@linxin666/dsh-pet >=0.4.0）。未安装时插件仍会加载，但不会发布任何内容，dsh 日志里会有说明，不会因此崩溃。
安装后 重启 DSH：bundle 仅在启动时读取，不重启不会挂载。智能体下次写入待办或启动目标后，气泡会自动出现，无需单独开关。
环境要求¶
| 组件 | 版本 |
|---|---|
| DSH | >=0.1.7-rc.1 |
@linxin666/dsh-pet |
>=0.4.0（peer） |
| Node | ^22.19.0 \|\| >=24.0.0 |
较旧的宠物若未暴露上述三条接缝，插件无法完整绑定。
可选配置¶
插件入口为 Cordis 风格的 apply：
apply(ctx, { enabled?: boolean, heartbeatMs?: number })
enabled: false 时不挂载任何内容；heartbeatMs 默认 10000。淡出时长与同时跟踪的会话数可在源码 src/progress.ts 中调整 PROGRESS_TTL_MS、MAX_TRACKED_SESSIONS（改后需按仓库说明重建 lib/）。
典型用法¶
对普通用户，流程就是：装好 pet → 装上本插件 → 重启 DSH → 照常让智能体写待办或 goal。无需额外 API 调用。
需要从代码侧理解时，插件使用与宠物相同的三条接缝：
| 接缝 | 用途 |
|---|---|
ctx.on('session/event', …) |
读取 todo/write、goal/change 及回合/步骤/工具/消息事件 |
ctx.pet.announce(…) |
发布进度气泡 |
ctx.pet.registerPanelAction(…) |
注册面板上的「进度」按钮 |
服务侧可通过 ctx.pet 访问宠物能力。
更新已安装插件示例（README Development 节）：
dsh plugin --profile desktop up dsh-pet-progress
固定 tag 安装：
dsh plugin --profile desktop add "https://github.com/Elefseus/dsh-pet-progress#<tag>"
本地开发可将 checkout 以 file: 依赖写入 profile 的 package.json，并在 dsh.profile.bundles 中加入 dsh-pet-progress，然后重启应用（路径含非 ASCII 时用 file:// URL）。
适用场景与注意¶
适合谁：已经在用 dsh web pet、希望长任务时一眼看到「做了多少」而不是只看当前一步的 DSH / 智能体开发者。
权限与安全：与其它 DSH 插件一样，本插件在 当前 dsh 进程权限 下运行，会订阅会话事件并向宠物 UI 发布内容。安装前请自行查看 源码 与 MIT 许可证，确认符合你的环境策略。社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。
生态背景：DSH 奉行「一切皆插件」；本仓库是宠物的伴生插件，通过接缝扩展而非直接改 pet 本体，设计说明见仓库 docs/DESIGN.md。
结尾¶
dsh-pet-progress 把会话里已有的待办与目标折成宠物上的进度气泡，并在没有列表时诚实地显示当前活动行，补上「还剩多少」这一维。若你已在用桌面宠物，一条官方安装命令加上重启即可试用。
- 目录页：https://www.skillhub.cn/plugins/Elefseus/dsh-pet-progress
- GitHub：https://github.com/Elefseus/dsh-pet-progress
