@zhushanwen/pi-todo 0.8.6 → 0.8.7

package/README.md

@@ -1,14 +1,14 @@
 # todo
 
-轻量三态任务清单 — `pending` / `in_progress` / `completed`。支持 session 持久化、状态栏、双列 widget、`/todos` TUI 视图，以及延迟 steer 驱动任务推进。
+轻量三态任务清单 — `pending` / `in_progress` / `completed`。支持 session 持久化、状态栏、单双列自适应 widget、`/todos` TUI 视图，以及延迟 steer 驱动任务推进。
 
 ## 设计定位
 
 | 维度 | todo | goal |
 |------|------|------|
-| 状态机 | **刻意无约束**，任意状态自由流转（含反向） | 7 态状态机 + 强制任务分解 |
+| 状态机 | **刻意无约束**，任意状态自由流转（含反向） | 6 态状态机（active/paused/blocked/complete/budget_limited/cancelled） |
 | 持久化 | 复用 Pi 的 toolResult entry（不调用 appendEntry） | appendEntry 主动写入 |
-| 定位 | 多步骤工作的临时进度追踪 | 持久化目标驱动循环 |
+| 定位 | 多步骤工作的临时进度追踪 | 持久化目标驱动循环（完成需逐条对照 successCriteria） |
 
 `in_progress` 非强制，`pending → completed` 直接跳转合法。
 
@@ -28,10 +28,10 @@ pi install npm:@zhushanwen/pi-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 的概念）
+- `add` 不接受 `status`（恒为 pending），不存在 `verifyTexts`（goal 侧的对应概念是 `successCriteria`）
+- 全部 completed 后由 **auto-clear 机制**延迟 2 轮自动清空并重置 `nextId=1`（无手动 clear action）
 
 ### 错误处理约定
 
@@ -42,11 +42,13 @@ handler 失败**直接 `throw new Error()`**，不返回错误成功模式（见
 | `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` `text` 空串 | `text cannot be empty or whitespace-only` |
 | `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)` |
 
+schema 为扁平 `Type.Object`（OpenAI 兼容）：字段全 Optional，缺失必填与双形陷阱（`text`/`texts`、`id`/`ids`）由 handler 运行时校验兜底。
+
 ## Steer 机制（延迟注入）
 
 todo 的核心驱动力是「延迟一拍」的 steer：
@@ -56,25 +58,22 @@ agent_end 设置 pendingSteerMessage
         → 下一 turn 的 before_agent_start 消费（用户不可见，display:false）
 ```
 
-四个子机制（handlers.ts，阈值常量硬编码）：
+两个子机制（handlers.ts）：
 
 | 机制 | 触发 | 行为 |
 |------|------|------|
-| **auto-clear** | 全部 completed 后再过 2 轮 | 自动清空 todos + 重置标记 |
 | **completion-steer** | 首次全部 completed | 注入「检查交付质量」steer（一次性，`completionSteered` 防重） |
-| **stall 检测** | 无 todo 活动达 5 轮 | 注入极简 reminder（仅下一个任务），整个 session 只触发一次 |
-| **reminder** | 无 todo 活动达 2 轮 | 温和 reminder |
+| **auto-clear** | 全部 completed 后再过 2 轮 | 自动清空 todos + 重置标记 |
 
-`agent_end` 内短路顺序：completion-steer **不短路**（继续往下），auto-clear / stall / reminder 各自短路 return。详见 `ARCHITECTURE.md`。
+`agent_end` 内：completion-steer **不短路**（继续往下），auto-clear 命中（`handled`）则短路 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` 降级映射到三态
+2. `session_start` / `session_tree` 时，`reconstructState` 回放**最后一条** todo toolResult 重建状态（纯读——Pi 的 getEntries 返回 filter-copy，splice 无效，不做 entry GC）
+3. 向后兼容：`migrateTodo` 把旧五态（`verifying→in_progress`、`failed→pending`）和极旧的 `done:boolean` 降级映射到三态
 
 ## 三层渲染
 
@@ -93,16 +92,15 @@ todo 扩展**自己不调用 `appendEntry`**。状态快照随 Pi 框架自动
 ```
 todo/
 ├── index.ts              # 工厂入口（re-export src/index.ts）
-├── PLAN.md               # [SUPERSEDED] v2 历史计划，保留作决策记录
 ├── ARCHITECTURE.md       # 架构详图（文件依赖 + steer 时序 + 事件流）
 └── src/
-    ├── index.ts          # 工厂入口（创建 state + 注册 tool/command/event）
+    ├── index.ts          # 工厂入口（创建 state + 注册 tool/command/event + makeRefreshDisplay）
     ├── state.ts          # TodoSessionState 会话状态接口 + 工厂
     ├── model.ts          # 纯函数数据层（类型/迁移/addTodos/updateTodos/format/buildGui）
-    ├── tool.ts           # todo tool 注册 — 5 action + execute dispatcher
-    ├── handlers.ts       # 5 事件处理器 + reconstructState + steer 四机制
+    ├── tool.ts           # todo tool 注册 — 4 action + execute dispatcher
+    ├── handlers.ts       # 5 事件处理器 + reconstructState + steer 双机制（autoClear/completion）
     ├── render.ts         # status line / widget / tool result 三层渲染
     ├── component.ts      # /todos 的 TodoListComponent TUI 组件
     ├── commands.ts       # /todos 命令注册
-    └── __tests__/        # 单测（model 纯函数 + widget 布局 + agent_end 数据条件）
+    └── __tests__/        # 单测（model 纯函数 + widget 布局 + steer/回放 + schema/detector/prompt 回归）
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "description": "AI-driven todo list for Pi — stateful task management with session persistence and /todos command.",
   "type": "module",
   "main": "src/index.ts",
@@ -29,8 +29,8 @@
     "vitest": "^4.1.8"
   },
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.7.0",
-    "@zhushanwen/pi-extension-logger": "0.3.1"
+    "@xyz-agent/extension-protocol": "0.8.0",
+    "@zhushanwen/pi-extension-logger": "0.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",

package/src/__tests__/tool-detectors.test.ts

@@ -4,10 +4,10 @@
 // verify the Correct/error STRINGS exist; these exercise the actual throw logic of
 // handleAdd/handleDelete, so a refactor cannot silently drop the dual-form detection.
 //
-// Note: the schema layer (TodoParams, additionalProperties:false) already rejects
-// dual-form payloads before they reach the handler in production. These handler-level
-// tests are defense-in-depth — they ensure the handler ALSO throws clearly if called
-// directly (e.g. by another extension bypassing schema validation).
+// Note: since the schema was flattened to a single Type.Object (OpenAI compat), all
+// fields are Optional at the schema layer — dual-form payloads now REACH the handler
+// in production, and these handler-level checks are the actual enforcement point
+// (schema.test.ts pins that Value.Check passes for dual-form payloads).
 //
 // handleAdd/handleDelete were exported specifically to enable these tests.
 

package/src/__tests__/tool-prompt.test.ts

@@ -1,5 +1,6 @@
 // 提示词质量回归：todo tool 的 description 与 runtime 纠错文案必须是
-// "弱模型友好"的——条件必填字段在 schema 层强约束（见 schema.test.ts），双形陷阱
+// "弱模型友好"的——条件必填字段（add 缺 texts、delete 缺 ids）在 handler 运行时校验
+// （schema 扁平化后字段全 Optional，见 tool.ts 头注释），双形陷阱
 // （text/texts、id/ids）的 throw 要带 Correct 纠错正例让模型自我纠正。
 //
 // 本测试用源码文本断言锁定这些约束，防止后续重构把纠错文案删掉或弱化。读源码而非

package/src/commands.ts

@@ -15,7 +15,7 @@ import { TodoListComponent } from "./component";
 /** 注册 /todos 命令到 pi */
 export function registerTodosCommand(pi: ExtensionAPI, state: TodoSessionState): void {
 	pi.registerCommand("todos", {
-		description: "View all todos for the current branch",
+		description: "View all todos for the current session",
 		handler: async (_args: string | undefined, ctx: ExtensionCommandContext) => {
 			if (!ctx.hasUI) {
 				ctx.ui.notify("/todos requires interactive mode", "error");

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * Todo Extension — 轻量三态任务清单（pending / in_progress / completed）。
  *
- * 设计定位：刻意不做状态机约束（与 goal 扩展的 7 态对立），状态自由流转；
+ * 设计定位：刻意不做状态机约束（与 goal 扩展的 6 态状态机对立），状态自由流转；
  * 状态持久化复用 Pi 自动记录的 toolResult entry（非 appendEntry）；
  * 通过 agent_end → before_agent_start 的延迟 steer 驱动任务推进。
  *

package/src/model.ts

@@ -113,10 +113,6 @@ export function buildGui(todos: Todo[]): GuiRenderResult {
 	);
 }
 
-export function getDisplayStatus(t: Todo): string {
-	return migrateTodo(t).status;
-}
-
 // ── Add 逻辑 ─────────────────────────────────────────
 
 export interface AddResult {

package/src/render.ts

@@ -6,7 +6,6 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 import {
-	getDisplayStatus,
 	type Todo,
 	type TodoDetails,
 } from "./model";
@@ -42,7 +41,7 @@ function fixedWidth(text: string, width: number): string {
 export function renderStatusText(todoList: Todo[], th: Theme): string {
 	if (todoList.length === 0) return "";
 
-	const completed = todoList.filter((t) => getDisplayStatus(t) === "completed").length;
+	const completed = todoList.filter((t) => t.status === "completed").length;
 	const total = todoList.length;
 
 	if (completed === total) {
@@ -113,7 +112,7 @@ export function renderWidgetLines(
 
 	const width = termWidth ?? (process.stdout.columns || FALLBACK_TERM_WIDTH);
 	const lines: string[] = [];
-	const completed = todoList.filter((t) => getDisplayStatus(t) === "completed").length;
+	const completed = todoList.filter((t) => t.status === "completed").length;
 	const total = todoList.length;
 
 	lines.push(th.fg("accent", "\u2611") + th.fg("muted", ` ${completed}/${total}`));
@@ -142,7 +141,7 @@ function buildTodoListText(todoList: Todo[], options: { expanded: boolean }, the
 	let listText = theme.fg("muted", `${todoList.length} todos:`);
 	const display = options.expanded ? todoList : todoList.slice(0, MAX_COLLAPSED_ITEMS);
 	for (const t of display) {
-		const status = getDisplayStatus(t);
+		const status = t.status;
 		const mark =
 			status === "completed"
 				? theme.fg("success", "\u2713")