进度记分板 svgop/dsh-rich-tracking

dsh-rich-tracking

进度记分板，给 DeepSeek Harness 用 —— 一块停靠在 todo 胶囊下方的看板，每行显示实时百分比，百分比来自工件事实；检查点由宿主抓取 git 真实状态；操作员鞭策动作会作为带归属的指令，落到智能体的下一步。

进度记分板：停在 todo 胶囊下方的百分比看板——每行百分比来自工件事实，检查点由宿主抓取 git 真实状态，pursue/align/dismiss 直接鞭策到 agent 的下一步。

flowchart LR
A[tracking_writewhole-board replace] --> B{Board projection}
B --> C[Dock pill below todopercent disc + rows]
C -->|pursue / align| D[Instruction lands inagent's next step]
C -->|checkpoint| E[Host captures git+ frozen rows]
E --> C2[Before/after strip+2 commits · 48%→62%]
F[8 steps or 6k tokens stale] -->|pre-step reminder| A

安装

dsh plugin --profile web add dsh-rich-tracking

重启 dsh web 进程 —— tracking_write 和 tracking_checkpoint 就对每个智能体预设可用，看板会渲染在会话停靠区（顺序 5：todo 胶囊下方、目标栏上方）。

当前版本要求 DeepSeek Harness >=0.1.2-alpha.1。宿主先通过核心 ctx.sessionEventTypes 能力注册 tracking/write、tracking/checkpoint 和 tracking/decision，持久化读取器再解释历史。这样 tracking 记录既持久又可重放，同时保留 harness 对无活跃属主事件类型的 fail-closed 行为。注册归插件 fiber 所有，所以卸载或 HMR 会连同 tracking 解释器一起移除准入能力。

语法

todos 是微观计划（本轮）；tracking 是任务记分板（跨轮）。 看板刻意不在 turn/start 时重置 —— 波次、里程碑、跨会话目标都会保留，直到每行都是 100，或者你手动 dismiss。

行与百分比的诚实性

每行是 {id, label, percent, status?, note?, evidence?, items?, detail?, sources?}：

- percent = 该行所属工件中（此刻成立的验收项）/（总数） —— 计划复选框、已落地回执、已验证回读。绝不是印象。
- 每行只要 percent >= 1，就必须带 evidence 指明依据（路径 + 已检查/总数）。校验会拒绝没有 evidence 的百分比 —— schema 强制了操作员口中的「不靠感觉」。
- percent: 100 要求每一项都已勾选，且所属回执存在。100% 的行会变暗，但保持可见，直到整块看板完成。
- items（可选，1-20）：该行的验收清单 [{ label, done }] —— 在看板上点击该行即可就地展开。已完成项灰显并加删除线；未完成项保持主色可读。有 items 时，percent 必须等于 round(done/total × 100)；校验会拒绝不一致，所以可见清单永远加得出显示的百分比。
- 总完成度按条目加权：每个条目算一个单位；没有条目的行按 percent/100 折算成一个单位。如果所有行都没有条目，结果就正好等于各行百分比的四舍五入均值——老看板沿用原来的算法。
- 行：1-12 行（建议 3-7 行），使用稳定的 ascii id（如 w2-fleet），方便检查点和操作引用。

行记录 ——「?」对话框

看板备注只有一行；详情才是这一行完整故事的所在。每一行可以带：

- detail（可选，≤ 4000 字符，纯文本/markdown）：这一行的完整记录——已完成事项的摘要、待办事项的细节、关键决策、待解问题、调研到的竞品知识。只要这一行的故事有变化，就及时更新。
- sources（可选，最多 12 个参考链接/路径）：竞品文档、调研摘要、凭据。HTTP(S) 链接会渲染成可点击。

点行上的 ? 按钮（悬停操作，最左侧）打开该行的记录对话框：状态行、最新备注、证据依据、以 markdown 渲染的详情、带完成/未完成符号的验收清单，以及可点击的来源列表。它是这一行的完整索引——200 字符的备注装不下的东西都在这里。

Scout —— 竞品调研的分发

Scout 按钮（胶囊形标题栏，所有行都完成时隐藏）让智能体跑一轮调研分发：每个未完成的行配一个后台子代理，各自针对该行的问题研究 3-6 个竞品或同类实现——每个竞品做法有何不同、采用什么方案、关键取舍是什么、哪些地方做对了而我们还没做到——返回精简后的发现。下发的指令要求产出可留存的摘要（.docs/digest/、.docs/research/——没写下来的调研等于没发生），然后执行一次 tracking_write，把调研过的每一行的 detail + sources 补充完整。Scout 是看板层面的对应物，对应 rich-questions 的 Push：先调研，再把知识折回来，百分比不抬高——调研是上下文，不是进度。

检查点 —— 凭据，不是叙述

tracking_checkpoint 让宿主抓取 git 分支/HEAD/脏状态，外加冻结的看板。模型从不手打 git 事实。看板显示前后对比条：+2 commits · overall 48% → 62% · W2 fleet 30% → 55%。

操作员操作（鞭子）

按行和全看板：?（该行的完整记录对话框）、Pursue（把这一行设为下一个焦点）、Delegate（把这一行交给后台子代理）、Scout（竞品调研分发）、Align（从产物重新推导每个百分比——测谎环节）、Checkpoint、Dismiss。Pursue/delegate/scout/align 会作为带归属的指令进入智能体的下一步（运行时 steer，空闲时 followup）；dismiss 是一条安静的备注——之后任何带真实状态的 tracking_write 都会让已 dismiss 的看板复活，因为真相胜过终局。
Delegate 会给智能体发一份自包含的委派简报：该行的标签、百分比、带完成标记的条目清单、证据和备注，外加这些要求——启动一个后台子代理，具备读写权限，严格限定在该行的任务和子任务范围内；子代理维护自己的 tracking_write 看板（限定到该任务，每完成一步更新百分比）；报告返回后，把可验证的凭据（提交、测试结果、文件路径）回填到父行。

Play 模式——自动接取最高价值的工作

胶囊头部有一个 ▶/⏸ 按钮。play 开启时（绿色、脉动），每次 turn/end 都会触发自动接取：看板按价值比给待办行排序（活跃行优先——势头很重要——再按百分比降序：百分比最高 = 最接近完成 = 最容易摘的果子），点名胜出者，并发送一条 followup，告诉智能体现在就去做。此后每轮结束都会重复这个循环，直到暂停、看板被关闭，或所有行都到 100。关闭看板会自动暂停。

/track——强制账本同步

/track（可选 /track <message>）是 /plan 家族里的宿主命令：它把完整账本加上追踪准则注入智能体的下一步，作为用户可见的消息——每一行都带百分比、状态、条目标记、证据和备注，后面跟着重新推导指令（读取指定的产物——文档、代码、凭据、用户上下文——按已勾选/总数重算百分比，修正过时的条目和文字，写入修正后的看板）。还没有看板时，它注入创建指令。尾随的消息作为操作者自己的话一并带上。存在活动看板时，每次用户提交也会在该轮第一步附带一行看板提醒（只要组装里已有更丰富的追踪上下文——一次 /track 同步、一条鞭策指令，或一条过时提醒——就去重）。

活账本的节奏

公告会教这条与步骤绑定的职责：每完成一个任务/步骤/待办，只要产物的真实状态变了，就调用 tracking_write——刷新百分比和条目标记；底层细节一变，就更新行文字（标签、备注、证据、条目）。看板始终描述当前现实，而不是里程碑快照。

刷新循环

智能体干活时看板会变旧。连续 8 个助手步骤或 6k 输出 token 没有 tracking_write 之后，下一次模型请求会带上一条带标签的提醒，点名过时的行。每轮一次；看板被关闭或已完成时不发。

对比

| 能力 | todo_write | goal bar | rich-questions | rich-tracking |
| 生命周期 | 每轮 | 任务（服务） | 每次工具调用 | 任务（会话事件） |
| 进度信号 | 状态计数 | 阶段标签 | 已答/总数 | 每行 % + 总体，绑定证据 |
| 操作者动作 | 无 | 暂停/恢复/编辑 | 回答/重掷/推送 | ?/pursue/delegate/scout/align/checkpoint/play/pause + /track |
| 智能体鞭策 | 说明 | 收尾上下文 | 预检指令 | 预步骤刷新 + 行动指令 |
| 证据绑定 | 无 | 目标文本 | 来源/洞察 | 逐行证据 + git 捕获的检查点 |
| 位置 | dock 0 | dock 10 | composer 座位 | dock 5 |

面板的 UI 语法

胶囊复刻内置 TodoPanel 的精确语法：折叠高度 36px、原生状态字形（活跃时是渐变旋转环，完成时是圆圈对勾，待办时是虚线圆环），并且——从 v0.1.1 起——出血行：行列表贴着卡片边缘铺满，行与行之间用 1px 细线分隔（不再有悬浮的圆角小块），悬停和选中底色横跨整行宽度，头部操作组（对齐 · 检查点 · 关闭 · 折叠箭头）在胶囊右缘分段，全高单元格由竖细线分隔。行可点击展开，查看条目清单；条目清单完成时变灰并加删除线。UI 支持英文和简体中文。

架构

src/host.js Node 半边——tracking_write + tracking_checkpoint 工具、 'tracking' 会话投影（不重置轮次）、必需会话事件注册、 agent/pre-step 刷新提醒 + 每轮面板提醒、/track 命令、回环围栏的 /api/rich-tracking/action 路由（pursue/delegate/scout/ align/dismiss/checkpoint）。仅用 Node 内置模块。
src/tracking-engine.js 纯引擎——面板校验（自修复消息、条目计算）、投影折叠、 wire 视图、百分比计算、账本渲染、scout 扇出简报。仅宿主端。
23 个 node:test 用例：npm test。
src/client.bundle.js 浏览器半边——dock 面板：百分比圆盘胶囊、出血行（悬停显示操作和条目清单）、分段头部操作、检查点前后条带、行「?」记录对话框（详情 markdown + 可点击来源）、工具提示。仅用 React + 客户端原语。
cordis.patch.yml 插入插件行的 bundle 补丁。

状态即会话事件（tracking/write、tracking/checkpoint、tracking/decision）——持久化、重载和分叉都走现有 JSONL 日志；客户端通过投影 wire 订阅。插件活跃期间，宿主向核心会话服务注册这些必需的外部事件类型。分叉继承面板并独立演化。

更新如何流动

不刷新、不轮询：tracking_write 追加一条会话事件 → 投影重新计算 → dock 在 todo 面板所用的同一条通道上收到新视图。智能体一写入，看板立刻更新——鞭子也一样：按下 pursue/align 会追加一条决策，并把指令送到智能体的下一步（运行中为 steer，空闲时为 followup，忽略时为静默注入），在转录里渲染成带归属的上下文节点，而不是伪造的用户消息。

许可证

MIT