@zhushanwen/pi-todo 0.3.0 → 0.4.1

package/README.md

@@ -1,45 +1,108 @@
 # todo
 
-轻量级 AI 任务清单 — 三态（pending / in_progress / completed），支持 session 持久化、状态栏、批量操作。
+轻量三态任务清单 — `pending` / `in_progress` / `completed`。支持 session 持久化、状态栏、双列 widget、`/todos` TUI 视图，以及延迟 steer 驱动任务推进。
 
-## 功能
+## 设计定位
 
-- **三态任务**：`pending` → `in_progress` → `completed`
-- **批量操作**：add / update / delete / clear
-- **Session 持久化**：任务状态保存在 session entries 中，重启后恢复
-- **状态栏**：底部显示任务进度（如 `2/5 done`）
-- **自动清理**：所有任务完成后自动清空
+| 维度 | todo | goal |
+|------|------|------|
+| 状态机 | **刻意无约束**，任意状态自由流转（含反向） | 7 态状态机 + 强制任务分解 |
+| 持久化 | 复用 Pi 的 toolResult entry（不调用 appendEntry） | appendEntry 主动写入 |
+| 定位 | 多步骤工作的临时进度追踪 | 持久化目标驱动循环 |
+
+`in_progress` 非强制，`pending → completed` 直接跳转合法。
 
 ## 安装
 
 ```bash
-# symlink 方式（开发推荐）
-ln -s /path/to/xyz-pi-extensions-workspace/main/packages/todo \
-      ~/.pi/agent/extensions/todo
-
-# npm 方式（正式）
 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` 降级映射到三态
+
+## 三层渲染
 
-AI 可调用 `todo` 工具：
+| 层 | 触发 | 规则 |
+|----|------|------|
+| **status line** | 每次 tool execute / session 恢复 | 空列表不显示；全完成 `✓ c/t`（绿）；否则 `☑ c/t` |
+| **widget**（侧边） | 有 todo 时 | ≤8 项单列；≥9 项双列（规避 Pi 的 10 行 widget 截断） |
+| **tool result** | tool 返回时 | collapsed 显示前 5 项 + `... N more`；expanded 全显示 |
 
-| Action | 说明 |
-|--------|------|
-| `list` | 查看所有 todo |
-| `add` | 批量添加 todo |
-| `update` | 更新 todo（状态/文本） |
-| `delete` | 批量删除 |
-| `clear` | 清空所有 |
+## 命令
 
-用户命令：`/todos` 交互式面板。
+`/todos` — 进入只读 TUI 视图（`TodoListComponent`，固定双列布局）。Escape / Ctrl+C 关闭。需 interactive mode。
 
 ## 文件结构
 
 ```
 todo/
-├── index.ts
+├── index.ts              # 工厂入口（re-export src/index.ts）
+├── PLAN.md               # [SUPERSEDED] v2 历史计划，保留作决策记录
+├── ARCHITECTURE.md       # 架构详图（文件依赖 + steer 时序 + 事件流）
 └── src/
-    └── index.ts    # 入口 — 工具、命令、事件、状态栏
+    ├── 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 数据条件）
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "AI-driven todo list for Pi — stateful task management with session persistence and /todos command.",
   "type": "module",
   "main": "src/index.ts",
@@ -24,6 +24,9 @@
   "devDependencies": {
     "vitest": "^4.1.8"
   },
+  "dependencies": {
+    "@xyz-agent/extension-protocol": "^0.2.0"
+  },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",

package/src/__tests__/gui.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+
+import { buildGui, type Todo } from "../model";
+
+describe("buildGui", () => {
+	it("maps 4 statuses to list-tree with correct icons", () => {
+		const todos: Todo[] = [
+			{ id: 1, text: "pending task", status: "pending" },
+			{ id: 2, text: "active task", status: "in_progress" },
+			{ id: 3, text: "done task", status: "completed" },
+			{ id: 4, text: "cancelled task", status: "cancelled" },
+		];
+		const gui = buildGui(todos);
+		expect(gui.v).toBe(1);
+		expect(gui.component.type).toBe("list-tree");
+		const items = gui.component.props.items;
+		expect(items).toHaveLength(4);
+		// pending → dot, no status（guiResult 的 stripUndefined 删除 undefined 键）
+		expect(items[0]).toMatchObject({ icon: "dot", label: "#1: pending task", depth: 0 });
+		expect(items[0]).not.toHaveProperty("status");
+		// in_progress → circle, running
+		expect(items[1]).toMatchObject({ icon: "circle", label: "#2: active task", status: "running", depth: 0 });
+		// completed → check, done
+		expect(items[2]).toMatchObject({ icon: "check", label: "#3: done task", status: "done", depth: 0 });
+		// cancelled → cross, failed
+		expect(items[3]).toMatchObject({ icon: "cross", label: "#4: cancelled task", status: "failed", depth: 0 });
+	});
+
+	it("empty todos → empty list-tree", () => {
+		const gui = buildGui([]);
+		expect(gui.component.props.items).toEqual([]);
+	});
+
+	it("isVerification todo still maps correctly", () => {
+		const todos: Todo[] = [{ id: 1, text: "verify", status: "pending", isVerification: true }];
+		const gui = buildGui(todos);
+		expect(gui.component.props.items[0]).toMatchObject({ icon: "dot", label: "#1: verify" });
+	});
+});

package/src/__tests__/steer.test.ts

@@ -0,0 +1,254 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	buildBeforeAgentStartMessage,
+	buildMinimalReminder,
+	handleAutoClear,
+	handleCompletionSteer,
+	handleReminder,
+	handleStallDetection,
+	reconstructState,
+} from "../handlers";
+import type { Todo } from "../model";
+import { createTodoSessionState, type TodoSessionState } from "../state";
+
+// ── helpers ─────────────────────────────────────────
+
+function makeState(todos: Todo[], overrides: Partial<TodoSessionState> = {}): TodoSessionState {
+	const s = createTodoSessionState();
+	s.todos = todos;
+	Object.assign(s, overrides);
+	return s;
+}
+
+function todoEntry(todos: Todo[], nextId: number) {
+	return {
+		type: "message",
+		message: { role: "toolResult", toolName: "todo", details: { todos, nextId } },
+	};
+}
+
+function makeCtx(entries: unknown[]) {
+	return {
+		sessionManager: { getEntries: () => entries },
+	} as unknown as Parameters<typeof reconstructState>[1];
+}
+
+// ── completion steer ────────────────────────────────
+
+describe("handleCompletionSteer", () => {
+	it("sets one-shot steer when all completed", () => {
+		const s = makeState([{ id: 1, text: "a", status: "completed" }]);
+		expect(handleCompletionSteer(s)).toBe(true);
+		expect(s.completionSteered).toBe(true);
+		expect(s.pendingSteerMessage).toContain("交付质量");
+	});
+
+	it("does not steer twice (single-shot lock)", () => {
+		const s = makeState([{ id: 1, text: "a", status: "completed" }], { completionSteered: true });
+		expect(handleCompletionSteer(s)).toBe(false);
+		expect(s.pendingSteerMessage).toBeNull();
+	});
+
+	it("does not steer when not all completed", () => {
+		const s = makeState([
+			{ id: 1, text: "a", status: "completed" },
+			{ id: 2, text: "b", status: "pending" },
+		]);
+		expect(handleCompletionSteer(s)).toBe(false);
+		expect(s.completionSteered).toBe(false);
+	});
+
+	it("does not steer on empty list", () => {
+		expect(handleCompletionSteer(makeState([]))).toBe(false);
+	});
+});
+
+// ── auto-clear ──────────────────────────────────────
+
+describe("handleAutoClear", () => {
+	it("does not handle when not all completed, and resets anchor", () => {
+		const s = makeState([{ id: 1, text: "a", status: "pending" }], { allCompletedAtCount: 3 });
+		expect(handleAutoClear(s)).toEqual({ handled: false, cleared: false });
+		expect(s.allCompletedAtCount).toBeNull();
+	});
+
+	it("anchors on first all-completed round without clearing", () => {
+		const s = makeState([{ id: 1, text: "a", status: "completed" }], { userMessageCount: 5 });
+		expect(handleAutoClear(s)).toEqual({ handled: true, cleared: false });
+		expect(s.allCompletedAtCount).toBe(5);
+		expect(s.todos).toHaveLength(1);
+	});
+
+	it("does not clear before AUTO_CLEAR_DELAY_ROUNDS (2) elapse", () => {
+		const s = makeState([{ id: 1, text: "a", status: "completed" }], {
+			userMessageCount: 5, allCompletedAtCount: 4,
+		});
+		expect(handleAutoClear(s)).toEqual({ handled: true, cleared: false });
+	});
+
+	it("clears and resets flags after delay elapses", () => {
+		const s = makeState([{ id: 1, text: "a", status: "completed" }], {
+			userMessageCount: 6, allCompletedAtCount: 4, completionSteered: true,
+		});
+		expect(handleAutoClear(s)).toEqual({ handled: true, cleared: true });
+		expect(s.todos).toEqual([]);
+		expect(s.nextId).toBe(1);
+		expect(s.allCompletedAtCount).toBeNull();
+		expect(s.completionSteered).toBe(false);
+	});
+});
+
+// ── stall detection ─────────────────────────────────
+
+describe("handleStallDetection", () => {
+	it("fires once when idle exceeds STALL_THRESHOLD (5)", () => {
+		const s = makeState([{ id: 1, text: "task", status: "pending" }], {
+			userMessageCount: 10, lastTodoCallCount: 5,
+		});
+		expect(handleStallDetection(s)).toBe(true);
+		expect(s.stallNotified).toBe(true);
+		expect(s.pendingSteerMessage).toContain("#1");
+	});
+
+	it("does not fire twice (single-shot lock)", () => {
+		const s = makeState([{ id: 1, text: "task", status: "pending" }], {
+			userMessageCount: 10, lastTodoCallCount: 5, stallNotified: true,
+		});
+		expect(handleStallDetection(s)).toBe(false);
+		expect(s.pendingSteerMessage).toBeNull();
+	});
+
+	it("does not fire below threshold", () => {
+		const s = makeState([{ id: 1, text: "task", status: "pending" }], {
+			userMessageCount: 8, lastTodoCallCount: 5,
+		});
+		expect(handleStallDetection(s)).toBe(false);
+	});
+});
+
+// ── reminder ────────────────────────────────────────
+
+describe("handleReminder", () => {
+	it("fires when idle exceeds REMINDER_INTERVAL (2)", () => {
+		const s = makeState([{ id: 1, text: "task", status: "pending" }], {
+			userMessageCount: 5, lastTodoCallCount: 3,
+		});
+		expect(handleReminder(s)).toBe(true);
+		expect(s.pendingSteerMessage).toContain("#1");
+	});
+
+	it("does not fire within interval", () => {
+		const s = makeState([{ id: 1, text: "task", status: "pending" }], {
+			userMessageCount: 4, lastTodoCallCount: 3,
+		});
+		expect(handleReminder(s)).toBe(false);
+	});
+});
+
+// ── reminder / context builders ─────────────────────
+
+describe("buildMinimalReminder", () => {
+	it("mentions the next pending task", () => {
+		const s = makeState([
+			{ id: 1, text: "done", status: "completed" },
+			{ id: 2, text: "next", status: "pending" },
+		]);
+		expect(buildMinimalReminder(s)).toContain("#2 next");
+	});
+
+	it("returns empty string when no pending", () => {
+		expect(buildMinimalReminder(makeState([{ id: 1, text: "done", status: "completed" }]))).toBe("");
+	});
+});
+
+describe("buildBeforeAgentStartMessage", () => {
+	it("injects hidden context for pending tasks only", () => {
+		const s = makeState([
+			{ id: 1, text: "a", status: "pending" },
+			{ id: 2, text: "b", status: "completed" },
+		]);
+		const m = buildBeforeAgentStartMessage(s);
+		expect(m).toBeDefined();
+		expect(m!.message.display).toBe(false);
+		expect(m!.message.customType).toBe("todo-context");
+		expect(m!.message.content).toContain("#1: a");
+		expect(m!.message.content).not.toContain("#2");
+	});
+
+	it("returns undefined when list empty", () => {
+		expect(buildBeforeAgentStartMessage(makeState([]))).toBeUndefined();
+	});
+
+	it("returns undefined when all completed", () => {
+		const s = makeState([{ id: 1, text: "a", status: "completed" }]);
+		expect(buildBeforeAgentStartMessage(s)).toBeUndefined();
+	});
+});
+
+// ── reconstructState ────────────────────────────────
+
+describe("reconstructState", () => {
+	it("leaves state empty when no todo entry", () => {
+		const entries = [{ type: "message", message: { role: "user", content: "hi" } }];
+		const s = createTodoSessionState();
+		reconstructState(s, makeCtx(entries));
+		expect(s.todos).toEqual([]);
+		expect(s.nextId).toBe(1);
+	});
+
+	it("replays the latest todo entry snapshot", () => {
+		const entries = [todoEntry([{ id: 1, text: "a", status: "pending" }], 2)];
+		const s = createTodoSessionState();
+		reconstructState(s, makeCtx(entries));
+		expect(s.todos).toHaveLength(1);
+		expect(s.todos[0].text).toBe("a");
+		expect(s.nextId).toBe(2);
+	});
+
+	it("uses the last todo entry and GCs older ones (splice from tail)", () => {
+		const entries = [
+			todoEntry([{ id: 1, text: "old", status: "pending" }], 2),
+			todoEntry([{ id: 5, text: "new", status: "completed" }], 6),
+		];
+		const s = createTodoSessionState();
+		reconstructState(s, makeCtx(entries));
+		expect(s.todos[0].id).toBe(5);
+		expect(s.nextId).toBe(6);
+		expect(entries).toHaveLength(1);
+	});
+
+	it("migrates legacy status on replay", () => {
+		const legacy = [{ id: 1, text: "a", status: "failed" }] as unknown as Todo[];
+		const entries = [todoEntry(legacy, 2)];
+		const s = createTodoSessionState();
+		reconstructState(s, makeCtx(entries));
+		expect(s.todos[0].status).toBe("pending");
+	});
+});
+
+// ── agent_end integration (短路顺序) ────────────────
+
+describe("agent_end short-circuit order", () => {
+	it("completion steer fires before auto-clear (completion does not short-circuit)", () => {
+		const s = makeState([{ id: 1, text: "a", status: "completed" }], { userMessageCount: 5 });
+		// 模拟 agent_end: handleCompletionSteer(不短路) → handleAutoClear(短路)
+		expect(handleCompletionSteer(s)).toBe(true);
+		expect(s.pendingSteerMessage).toContain("交付质量");
+		expect(handleAutoClear(s)).toEqual({ handled: true, cleared: false });
+		expect(s.allCompletedAtCount).toBe(5);
+	});
+
+	it("after delay, auto-clear clears but the one-shot steer stays queued", () => {
+		// 竞态点：completion steer 早已置位，auto-clear 现在清空 todos
+		const s = makeState([{ id: 1, text: "a", status: "completed" }], {
+			userMessageCount: 7, allCompletedAtCount: 5,
+			completionSteered: true, pendingSteerMessage: "<queued>",
+		});
+		expect(handleCompletionSteer(s)).toBe(false); // 已 steered，不重复
+		expect(handleAutoClear(s).cleared).toBe(true);
+		expect(s.todos).toEqual([]);
+		// pendingSteerMessage 仍保留，由下一 turn before_agent_start 消费（此时 todos 已空）
+		expect(s.pendingSteerMessage).toBe("<queued>");
+	});
+});

package/src/__tests__/todo.test.ts

@@ -3,7 +3,6 @@ import { describe, expect, it } from "vitest";
 
 import {
 	addTodos,
-	buildRender,
 	formatTodoLine,
 	migrateTodo,
 	type Todo,
@@ -201,15 +200,15 @@ describe("handleSingleUpdate FR-6 guards (tool single path)", () => {
 	it("FR-6: cancelled todo + status → cannot restore", () => {
 		const state = createTodoSessionState();
 		state.todos = [{ id: 1, text: "dropped", status: "cancelled" }];
-		const result = handleSingleUpdate(state, { action: "update", id: 1, status: "pending" });
-		expect(result.error).toBe("#1 is cancelled (cannot restore)");
+		expect(() => handleSingleUpdate(state, { action: "update", id: 1, status: "pending" }))
+			.toThrow("#1 is cancelled (cannot restore)");
 	});
 
 	it("FR-6: verification todo + status=cancelled → cannot cancel", () => {
 		const state = createTodoSessionState();
 		state.todos = [{ id: 2, text: "run tests", status: "in_progress", isVerification: true }];
-		const result = handleSingleUpdate(state, { action: "update", id: 2, status: "cancelled" });
-		expect(result.error).toBe("#2 is verification todo (cannot cancel)");
+		expect(() => handleSingleUpdate(state, { action: "update", id: 2, status: "cancelled" }))
+			.toThrow("#2 is verification todo (cannot cancel)");
 	});
 });
 
@@ -269,27 +268,6 @@ describe("formatTodoLine", () => {
 	});
 });
 
-// ── buildRender ─────────────────────────────────────
-
-describe("buildRender", () => {
-	it("should calculate summary correctly", () => {
-		const todos: Todo[] = [
-			{ id: 1, text: "a", status: "completed" },
-			{ id: 2, text: "b", status: "pending" },
-			{ id: 3, text: "c", status: "in_progress" },
-		];
-		const render = buildRender(todos);
-		expect(render).toBeDefined();
-		expect(render!.summary).toBe("1/3 completed");
-		expect(render!.data.items).toHaveLength(3);
-	});
-
-	it("should handle empty list", () => {
-		const render = buildRender([]);
-		expect(render!.summary).toBe("0/0 completed");
-	});
-});
-
 // ── widget 渲染布局 ────────────────────────────────
 
 const mockTheme = {

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

@@ -0,0 +1,56 @@
+// Behavioral tests for todo dual-form traps (text/texts, id/ids).
+//
+// Complements the source-text prompt-quality locks in tool-prompt.test.ts: those
+// 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.
+//
+// handleAdd/handleDelete were exported specifically to enable these tests.
+
+import { describe, expect, it } from "vitest";
+
+import { createTodoSessionState } from "../state";
+import { handleAdd, handleDelete } from "../tool";
+
+describe("handleAdd — text/texts dual-form detection", () => {
+  it("triggers dual-form error when singular 'text' used instead of 'texts'", () => {
+    const state = createTodoSessionState();
+    expect(() => handleAdd(state, { action: "add", text: "write spec" })).toThrow(
+      /singular "text"|add needs texts/,
+    );
+  });
+
+  it("throws 'requires texts' when neither text nor texts given", () => {
+    const state = createTodoSessionState();
+    expect(() => handleAdd(state, { action: "add" })).toThrow(/requires texts/);
+  });
+
+  it("throws 'requires texts' on empty array (missing, not dual-form)", () => {
+    const state = createTodoSessionState();
+    expect(() => handleAdd(state, { action: "add", texts: [] })).toThrow(/requires texts/);
+  });
+
+  it("does NOT throw when correct 'texts' array provided", () => {
+    const state = createTodoSessionState();
+    expect(() => handleAdd(state, { action: "add", texts: ["write spec"] })).not.toThrow();
+  });
+});
+
+describe("handleDelete — id/ids dual-form detection", () => {
+  it("triggers dual-form error when singular 'id' used instead of 'ids'", () => {
+    const state = createTodoSessionState();
+    expect(() => handleDelete(state, { action: "delete", id: 5 })).toThrow(
+      /singular "id"|delete needs ids/,
+    );
+  });
+
+  it("throws 'requires ids' when neither id nor ids given", () => {
+    const state = createTodoSessionState();
+    expect(() => handleDelete(state, { action: "delete" })).toThrow(/requires ids/);
+  });
+
+  it("does NOT throw when correct 'ids' array provided (after seeding a todo)", () => {
+    const state = createTodoSessionState();
+    handleAdd(state, { action: "add", texts: ["temp"] }); // seed todo #1
+    expect(() => handleDelete(state, { action: "delete", ids: [1] })).not.toThrow();
+  });
+});

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

@@ -0,0 +1,105 @@
+// 提示词质量回归：todo tool 的 description 与 runtime 纠错文案必须是
+// "弱模型友好"的——条件必填字段要给完整 JSON 正例，双形陷阱（text/texts、
+// id/ids）要给消歧反例，失败后 throw 要带 Correct 正例让模型自我纠正。
+//
+// 本测试用源码文本断言锁定这些约束，防止后续重构把正例/反例/纠错文案删掉或
+// 弱化。读源码而非 import，避免 mock 链（tool.ts 依赖 typebox/ExtensionAPI/
+// Theme 等值导入）。参考 subagent-workflow 的 prompt 回归范式。
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TOOL_SRC = readFileSync(join(__dirname, "../tool.ts"), "utf-8");
+
+/**
+ * 提取 description 拼接区（从 `description:` 到下一个 `promptSnippet:`）。
+ * tool.ts 的 description 用字符串拼接（非模板字面量），故整段截取后做子串断言。
+ */
+function extractDescriptionRegion(src: string): string {
+	// 锚定到 registerTodoTool 内的 tool description，而非 schema 字段的 description:
+	// （Type.String({ description: "..." }) 等 schema 字段会先被 indexOf 命中，导致
+	// 捕获区域含 schema 描述 + tool 描述——虽当前子串唯一能过但 fragile to restructuring）。
+	const regIdx = src.indexOf("registerTodoTool");
+	if (regIdx === -1) throw new Error("registerTodoTool not found in tool.ts");
+	const start = src.indexOf("description:", regIdx);
+	if (start === -1) throw new Error("tool description: not found in registerTodoTool");
+	const end = src.indexOf("promptSnippet:", start);
+	if (end === -1) throw new Error("promptSnippet: not found in tool.ts");
+	return src.slice(start, end);
+}
+
+const DESCRIPTION_REGION = extractDescriptionRegion(TOOL_SRC);
+
+// ── description 必须给完整 JSON 正例 ─────────────────
+
+describe("todo description — 给完整 JSON 正例", () => {
+	it("add 正例：含 {\"action\":\"add\",\"texts\"", () => {
+		// 弱模型 add 时易误用单数 text；正例必须显式 texts 数组。
+		expect(DESCRIPTION_REGION).toContain('{"action":"add","texts"');
+	});
+
+	it("add+verification 正例：含 isVerification", () => {
+		expect(DESCRIPTION_REGION).toContain('"isVerification":true');
+	});
+
+	it("update single 正例：含 {\"action\":\"update\",\"id\"", () => {
+		expect(DESCRIPTION_REGION).toContain('{"action":"update","id"');
+	});
+
+	it("update batch 正例：含 {\"action\":\"update\",\"updates\"", () => {
+		// updates[] 批量路径是 [批量优先] 规范的核心，正例不可缺。
+		expect(DESCRIPTION_REGION).toContain('{"action":"update","updates"');
+	});
+
+	it("delete 正例：含 {\"action\":\"delete\",\"ids\"", () => {
+		// 弱模型 delete 时易误用单数 id；正例必须显式 ids 数组。
+		expect(DESCRIPTION_REGION).toContain('{"action":"delete","ids"');
+	});
+});
+
+// ── description 必须给双形陷阱反例（消歧） ──────────
+
+describe("todo description — 双形陷阱反例（消歧单复数）", () => {
+	it("Don't 段存在", () => {
+		expect(DESCRIPTION_REGION).toMatch(/Don't/);
+	});
+
+	it("反例标注：text 属于 update（add 用 texts）", () => {
+		// 反例必须含消歧词，告诉模型 text 属于 update 而非 add。
+		expect(DESCRIPTION_REGION).toContain("text is for update");
+		expect(DESCRIPTION_REGION).toContain("add uses texts");
+	});
+
+	it("反例标注：id 属于 update（delete 用 ids）", () => {
+		expect(DESCRIPTION_REGION).toContain("id is for update");
+		expect(DESCRIPTION_REGION).toContain("delete uses ids");
+	});
+
+	it("反例标注：update 缺 id", () => {
+		expect(DESCRIPTION_REGION).toContain("missing id");
+	});
+});
+
+// ── runtime throw 必须带 Correct 纠错正例 ───────────
+
+describe("todo runtime — throw 含 Correct 纠错正例", () => {
+	it("源码含 ≥4 处 Correct: 纠错文案（覆盖 add/delete/update 路径）", () => {
+		// 每个 required throw 必须追加完整 JSON 正例，弱模型失败后能自我纠正。
+		const matches = TOOL_SRC.match(/Correct:/g) || [];
+		expect(matches.length).toBeGreaterThanOrEqual(4);
+	});
+
+	it('add 双形检测：含 singular "text" 纠错文案', () => {
+		expect(TOOL_SRC).toContain('singular "text"');
+		expect(TOOL_SRC).toContain('"text" — that field is for update');
+	});
+
+	it('delete 双形检测：含 singular "id" 纠错文案', () => {
+		expect(TOOL_SRC).toContain('singular "id"');
+		expect(TOOL_SRC).toContain('"id" — that field is for update');
+	});
+});