任务台账 haruri03/dsh-todo-ledger

dsh-todo-ledger

仓库：https://github.com/haruri03/dsh-todo-ledger

一个宿主级 DSH 插件，把 todo ledger 工作流变成常驻提示词段落、一组原生工具，以及存放在仓库 _todo/ 目录里的上下文。

它要解决的失败场景是：规则写在技能或 AGENTS.md 里，模型忘了读，任务列表每轮都得重写：

| 之前 | 本插件 |
| 规则写在 AGENTS.md / 技能里，模型不读就失效 | 宿主级 systemPrompt.section 在每个会话的每一步都在，没有需要记住的加载步骤 |
| 系统 todo_write 列表每轮被覆盖，进度丢失 | 权威状态存放在仓库的 _todo/ 文件里，跨会话、跨压缩都能存活 |
| 上下文只存在于对话历史，压缩后就没了 | todo_checkpoint / todo_note 把结论和下一步写进 _todo/context/，每次组装提示词时注入快照 |
| 模型得自己拼 shell 命令 | 11 个原生工具，带 schema 校验和可读的错误信息 |

文件格式与外部 todo 命令行完全兼容：插件和原命令行都能写同一个仓库，也都能对它跑 doctor。

安装（手动）

二选一：

人工：把这个目录复制到 $HOME/.dsh/profiles/<profile>/node_modules/dsh-todo-ledger，然后在配置档的 cordis.patch.yml 末尾追加这一行：

- insert:
- id: todo-ledger
name: './lib/index.js'

智能体：运行 plugin_manager install_bundle --target "<path-to-plugin>"。

从 Git 安装

当仓库根目录就是包本身（含 package.json 和 dsh.bundle）时，可以直接从 Git URL 安装：

plugin_manager install_bundle --target "git+https://github.com/haruri03/dsh-todo-ledger.git"

人工操作也有同样的入口：Web 插件页面的「Add plugin」，或者命令行：

dsh plugin --profile <profile> add "git+https://github.com/haruri03/dsh-todo-ledger.git"

也接受 npm 包名和 tarball URL。要更新，就卸载重装，或者等上游发版。

安装完成后，每个新会话都会带上 [todo-ledger · cross-session tasks and context] 提示词段落，工具列表里也会多出：

todo_list / todo_add / todo_show / todo_status / todo_complete / todo_archive / todo_note / todo_checkpoint / todo_snapshot / todo_doctor / todo_init

无需重启。

目录结构

位于仓库根目录内（即包含 _todo/ 的目录；已经用 todo/ 的仓库照常可用，插件两个名字都认）：

_todo/
├── todo.md queue: - [status] slug
├── tasks.md index: - [status] slug — title → details ├── tasks/<slug>.md 详情：目标 / 子任务 / 验收 / 进度 / 阻塞 / 文件 ├── archived/<slug>.md 已完成 + ## Delivery record（含签核原话） ├── AGENTS.md todo_init 生成的目录说明 └── context/ 本插件新增 ├── now.md 当前目标 / 下一步 / 关键文件（由 todo_checkpoint 覆盖写入） └── log.md 只追加的日志（自动工具轨迹 + todo_note）

状态有 todo / doing / blocked / review，没有 done。review 表示工作已完成，等待负责人签核。关闭任务必须同时提供 evidence 和 signoff（负责人本人的原话），两者都不能省略。这是 todo 台账工作流的硬性规则。

工具

| 工具 | 用途 |
| todo_list | 列出任务和状态（可筛选）；开始工作前先调用 |
| todo_show | 查看单个任务的详情 |
| todo_add | 创建任务（slug 唯一，用 kebab-case） |
| todo_status | 修改状态，并同步任务 frontmatter、索引和队列 |
| todo_complete | 关闭并归档任务；需要 evidence + signoff |
| todo_archive | 放弃任务；额外需要 reason |
| todo_note | 追加到 context/log.md；带 slug 时插入该任务 ## Progress 段末尾（首次写入会移除占位符）；带 state 时在同一次调用中推进状态机 |
| todo_checkpoint | 覆盖写入 context/now.md：当前目标 / 下一步 / 关键文件 |
| todo_snapshot | 只读：返回将要注入提示词的快照（检查台账是否过期） |
| todo_doctor | 双向一致性检查；返回错误和警告 |
| todo_init | 创建 _todo/ 骨架（仅在用户要求时） |

每个工具都接受可选的 root，因此可以操作工作区之外的仓库：

todo_doctor { root: "<repo-root>" }。

上下文如何留存

1. 每次组装系统提示词时，插件向上查找会话工作目录最近的 _todo/，并注入：
- 台账最后写入：N 前（context/log.md、tasks.md、now.md 中最新的 mtime）；
- 会话过期度：自上次 todo_ 写入以来发生了多少次工具调用，其中多少次是写入；写入达到 3 次及以上会加 ⚠，提醒智能体先更新台账；
- 任务总数（四种状态）、待签核项（附 (Nd) 等待天数）和 blocked 的 slug；
- doing 任务的进度：任务 ## Progress 段最后一行真实内容（≤80 字符）；没有进度时整行省略；状态 2 天以上未变会标 state Nd unchanged；模板占位符会被过滤掉；
- context/now.md 的正文和最近 6 条日志。
2. 每轮结束时（agent/turn-stopping），插件按轮次统计写入类操作边界。达到 3 条或更多时，它追加一条事实日志（工具调用 / 写入 / 状态变更），不编造语义。如果这一轮只写了笔记、从未推进状态，日志会写明状态机没有推进。它刻意不从最后一次 todo_ 写入开始计数，因为结尾的 todo_note 会重置计数器，掩盖掉「改了很多文件却只留一条笔记」的一轮。
3. todo_checkpoint 记录结论，不记录长摘录；todo_note 记录小发现；写入会自动追加一条轨迹。
4. 压缩之后、新会话或 DSH 重启之后，下一条提示词仍然携带快照，工作可以继续。
5. 没有 _todo/ 目录时，插件只注入规则并提示 todo_init；它绝不会自行创建目录。

尚未解决的另一半：语义摘要仍由模型撰写。插件把「账本已过期」变成可见的事实和一个 ⚠，而不是替模型编造结论。

配置

cordis.patch.yml 里这一行可以调整：

- id: todo-ledger
name: './lib/index.js'
config:
root: "<repo-root>" # optional: pin the repository root
sectionOrder: 180 # prompt section order, default 180
maxSnapshotChars: 4000 # snapshot size limit, default 4000

不设 root 时，插件从会话工作目录向上查找 _todo/tasks.md；找不到就用 TODO_ROOT 环境变量。

验证

node test/smoke.mjs

覆盖范围：提示词段落注册与快照渲染、全部 11 个工具的 schema、完整的 init → add → status → note → checkpoint → doctor → complete/archive 流程，以及拒绝没有 signoff 的关闭操作。当 TODO_CLI 指向外部 todo.js 时，测试还会验证 list/doctor 的互操作性。

卸载

plugin_manager remove_bundle --target dsh-todo-ledger

插件只移除自己的注册项；_todo/ 目录（含 context/）原样保留。