todo

轻量三态任务清单 — pending / in_progress / completed。支持 session 持久化、状态栏、双列 widget、/todos TUI 视图，以及延迟 steer 驱动任务推进。

设计定位

维度	todo	goal
状态机	刻意无约束，任意状态自由流转（含反向）	7 态状态机 + 强制任务分解
持久化	复用 Pi 的 toolResult entry（不调用 appendEntry）	appendEntry 主动写入
定位	多步骤工作的临时进度追踪	持久化目标驱动循环

in_progress 非强制，pending → completed 直接跳转合法。

安装

pi install npm:@zhushanwen/pi-todo

todo tool

Action 与参数

action	参数	必填	行为
list	—	—	返回全部 todo
add	texts: string[]	是	批量追加，自动分配连续 ID，初始 status=pending
update	id + status 或 text；或 updates: Array<{id, status?, text?}>	id 必填	updates[] 优先于 single 的 id/status/text
delete	ids: number[]	是	批量删除；部分 id 缺失则整体拒绝（原子性）
clear	—	—	清空全部，重置 nextId=1 和完成态标记

• status 枚举：pending / in_progress / completed
• add 不接受 status（恒为 pending），不存在 verifyTexts（那是 goal 的概念）

错误处理约定

handler 失败直接 throw new Error()，不返回错误成功模式（见 CLAUDE.md「Tool 设计」）。常见错误：

触发	错误信息
add 缺 texts	add requires texts parameter (non-empty array)
update 缺 id	update requires id parameter
update 缺 status 和 text	update requires at least status or text parameter
update text 空串	text cannot be empty string
update status 非法	status only accepts pending / in_progress / completed
update/delete id 不存在	Todo #N not found
delete 缺 ids	delete requires ids parameter (non-empty array)

Steer 机制（延迟注入）

todo 的核心驱动力是「延迟一拍」的 steer：

agent_end 设置 pendingSteerMessage
        → 下一 turn 的 before_agent_start 消费（用户不可见，display:false）

四个子机制（handlers.ts，阈值常量硬编码）：

机制	触发	行为
auto-clear	全部 completed 后再过 2 轮	自动清空 todos + 重置标记
completion-steer	首次全部 completed	注入「检查交付质量」steer（一次性，completionSteered 防重）
stall 检测	无 todo 活动达 5 轮	注入极简 reminder（仅下一个任务），整个 session 只触发一次
reminder	无 todo 活动达 2 轮	温和 reminder

agent_end 内短路顺序：completion-steer 不短路（继续往下），auto-clear / stall / reminder 各自短路 return。详见 ARCHITECTURE.md。

持久化机制

todo 扩展自己不调用 appendEntry。状态快照随 Pi 框架自动记录的 toolResult entry 落盘：

1. 每次 todo tool 调用，execute 返回的 details.todos / details.nextId 被 Pi 自动序列化为一条 toolResult entry
2. session_start / session_tree 时，reconstructState 回放最后一条 todo toolResult 重建状态
3. 回放后 splice 掉更早的 todo toolResult（entry GC，从后往前删避免索引漂移）
4. 向后兼容：migrateTodo 把旧五态（verifying→in_progress、failed→pending）和极旧的 done:boolean 降级映射到三态

三层渲染

层	触发	规则
status line	每次 tool execute / session 恢复	空列表不显示；全完成 ✓ c/t（绿）；否则 ☑ c/t
widget（侧边）	有 todo 时	≤8 项单列；≥9 项双列（规避 Pi 的 10 行 widget 截断）
tool result	tool 返回时	collapsed 显示前 5 项 + ... N more；expanded 全显示

命令

/todos — 进入只读 TUI 视图（TodoListComponent，固定双列布局）。Escape / Ctrl+C 关闭。需 interactive mode。

文件结构

todo/
├── index.ts              # 工厂入口（re-export src/index.ts）
├── PLAN.md               # [SUPERSEDED] v2 历史计划，保留作决策记录
├── ARCHITECTURE.md       # 架构详图（文件依赖 + steer 时序 + 事件流）
└── src/
    ├── index.ts          # 工厂入口（创建 state + 注册 tool/command/event）
    ├── state.ts          # TodoSessionState 会话状态接口 + 工厂
    ├── model.ts          # 纯函数数据层（类型/迁移/addTodos/updateTodos/format/buildGui）
    ├── tool.ts           # todo tool 注册 — 5 action + execute dispatcher
    ├── handlers.ts       # 5 事件处理器 + reconstructState + steer 四机制
    ├── render.ts         # status line / widget / tool result 三层渲染
    ├── component.ts      # /todos 的 TodoListComponent TUI 组件
    ├── commands.ts       # /todos 命令注册
    └── __tests__/        # 单测（model 纯函数 + widget 布局 + agent_end 数据条件）