dsh-todo-ledger：持久化任务清单与跨会话上下文插件

前言¶

在 DeepSeek Harness（DSH）开发中，规则写在 AGENTS.md 或 skill 里，模型有时会忽略；任务列表在对话历史中，每次会话重置后进度就丢失；上下文仅存在于历史记录，压缩后会消失。这些场景下，智能体容易忘记任务状态、重复写入或遗漏关键步骤。

dsh-todo-ledger 是一个 host-level 插件，把 todo ledger 工作流转化为驻留的 prompt section、一组原生工具，以及存储在仓库 _todo/ 目录中的权威状态。它让任务清单和上下文持久化，并通过 11 个原生工具保证状态同步和可读的错误信息。

这是什么¶

dsh-todo-ledger 是 DeepSeek Harness 的一个插件，维护者为 haruri03。它将 todo ledger 工作流转化为：
- 每个会话都存在的 prompt section，无需加载步骤
- 存储在仓库 _todo/ 目录中的权威任务状态
- 11 个原生工具，支持 schema 验证和清晰错误提示

该插件与外部 todo CLI 兼容，两者可以读写同一个仓库，并共同运行 doctor 检查。

核心功能¶

1. 目录结构与状态¶

插件在仓库根目录创建 _todo/ 目录（优先），同时支持 legacy todo/ 目录。目录结构如下：

_todo/
├── todo.md              queue: `- [status] slug`
├── tasks.md             index: `- [status] **slug** — title → [details](tasks/slug.md)`
├── tasks/<slug>.md      details: goal / subtasks / acceptance / progress / blockers / files
├── archived/<slug>.md   completed + ## Delivery record (includes sign-off quote)
├── AGENTS.md            directory notes generated by todo_init
└── context/             added by this plugin
    ├── now.md           current goal / next step / key files (overwritten by todo_checkpoint)
    └── log.md           append-only log (automatic tool trace + todo_note)

任务状态包括 todo、doing、blocked、review，没有 done。review 意味着工作完成，等待所有者确认。关闭任务需要同时提供 evidence 和 signoff（所有者的原话），二者不能省略。

2. 11 个原生工具¶

工具	用途
`todo_list`	列出任务和状态（可选过滤），开始工作前调用
`todo_show`	展示单个任务的详情
`todo_add`	创建任务（唯一 kebab-case slug）
`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`	只读：返回将注入 prompt 的快照（检查 ledger 是否过期）
`todo_doctor`	双向一致性检查，返回错误和警告
`todo_init`	创建 `_todo/` 骨架（仅在用户请求时）

所有工具都支持可选的 root 参数，可在工作区之外的操作仓库。

3. 可视化面板¶

插件提供两个面板来查看 ledger：
- 侧边栏面板：只读浏览，仅 review 任务有“接受”按钮，点击后归档任务并记录面板点击为 evidence 和 signoff
- 浮动面板：可拖拽、可调整大小的悬浮窗口，支持折叠各状态组，跟随主机主题

面板通过右侧边栏的指南胶囊打开，是可选的，不会主动注入到布局中。

安装与启用¶

手动安装¶

将插件目录复制到 $HOME/.dsh/profiles/<profile>/node_modules/dsh-todo-ledger
在该 profile 的 cordis.patch.yml 中追加以下内容：

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

Git 安装¶

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

npm 安装¶

plugin_manager install_bundle --target "dsh-todo-ledger"

CLI 安装¶

dsh plugin --profile <profile> add dsh-todo-ledger

安装完成后，每个新会话都会携带 [todo-ledger · cross-session tasks and context] prompt section，工具列表增加上述 11 个工具，无需重启。

典型用法¶

初始化¶

todo_init

这会在仓库根目录创建 _todo/ 骨架和 AGENTS.md 目录说明。

创建任务¶

todo_add "fix authentication bug"

更改状态¶

todo_status "fix authentication bug" doing

记录进度与检查一致性¶

todo_note "fix authentication bug" "Applied patch to handle expired tokens"
todo_doctor

设置当前目标¶

todo_checkpoint "Implement token refresh logic in auth service"

完成任务¶

todo_complete "fix authentication bug" "evidence: fixed by patch..." "signoff: I verified the fix works on production"

适用场景与注意¶

该插件适合需要持久化任务状态和跨会话上下文的场景，如长期项目、多轮对话任务、需要反复确认的工作流。它通过仓库级别的目录存储，确保状态不因会话重置而丢失。

插件以当前 DSH 进程权限运行，安装前应检查源码与许可证（MIT）。建议在项目根目录运行 todo_doctor 确保目录结构与工具调用一致。

总结¶

dsh-todo-ledger 通过 prompt section、原生工具和仓库级存储，解决了规则遗忘、任务进度丢失和上下文压缩后消失的问题。它提供 11 个工具、可视化面板和与外部 CLI 的兼容性，适合需要严格状态管理和交付记录的工作流。

插件目录：https://www.skillhub.cn/plugins/haruri03/dsh-todo-ledger
GitHub：https://github.com/haruri03/dsh-todo-ledger