@zhushanwen/pi-todo 0.6.0 → 0.7.0

package/src/tool.ts

@@ -1,5 +1,11 @@
 /**
- * Todo tool 注册 + execute dispatcher + 5 个 action handler。
+ * Todo tool 注册 + execute dispatcher + 4 个 action handler。
+ *
+ * Schema 设计（T4）：TodoParams 为 discriminated union（按 action 区分），每个分支
+ * 只声明自己的参数且 additionalProperties:false。这样缺失必填（如 {action:'add'} 缺
+ * texts）在 schema 层就被拒绝，不依赖运行时 handler throw。实测 typebox Value.Check
+ * 与 ajv（plain，不开 discriminator 选项）均正确拒绝；故不使用 discriminator keyword
+ * （typebox 输出 anyOf，ajv discriminator 选项要求 oneOf 会编译失败）。
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -10,7 +16,7 @@ import { type Static, Type } from "typebox";
 import {
 	addTodos,
 	buildGui,
-	formatTodoLine,
+	formatTodoList,
 	type Todo,
 	type TodoDetails,
 	updateTodos,
@@ -19,7 +25,11 @@ import {
 import { renderTodoResult } from "./render";
 import type { TodoSessionState } from "./state";
 
-// ── Action 参数类型 ──────────────────────────────────
+// ── Action 参数类型（运行时）──────────────────────────
+// 刻意保持为宽松 interface（全部字段可选）而非 strict discriminated union：
+// handler 需要检测「双形陷阱」（add 同时传 text+texts 等错误输入），schema 层虽已用
+// additionalProperties:false 拒绝，但 handler 作为 defense-in-depth 仍需能访问/判断
+// 这些字段。类型严格性由 TodoParams schema（discriminated union）承担。
 
 export interface TodoActionParams {
 	action: string;
@@ -31,46 +41,77 @@ export interface TodoActionParams {
 	updates?: Array<{ id: number; status?: string; text?: string }>;
 }
 
-// ── TodoParams schema ────────────────────────────────
+// ── TodoParams schema（discriminated union by action）──────────
 
-const TodoParams = Type.Object({
-	action: StringEnum(["list", "add", "update", "delete", "clear"] as const),
-	text: Type.Optional(Type.String({ description: "Todo text (for update action)" })),
-	id: Type.Optional(Type.Number({ description: "Todo ID (for update action)" })),
-	texts: Type.Optional(Type.Array(Type.String(), { description: "Todo text list (for add action)" })),
-	ids: Type.Optional(Type.Array(Type.Number(), { description: "Todo ID list (for delete action)" })),
-	status: Type.Optional(
-			StringEnum(VALID_STATUSES, { description: "Target status (for update action)" }),
-		),
-	updates: Type.Optional(
-			Type.Array(
-				Type.Object({
-					id: Type.Number({ description: "Todo ID to update" }),
-					status: Type.Optional(
-						Type.String({ description: "Target status; one of pending/in_progress/completed/cancelled" }),
-					),
-					text: Type.Optional(Type.String({ description: "New todo text" })),
-				}),
-				{ description: "Batch updates array (takes priority over single id/status/text)" },
-			),
+const StatusSchema = StringEnum(VALID_STATUSES);
+
+const ListParams = Type.Object(
+	{ action: Type.Literal("list") },
+	{ additionalProperties: false },
+);
+const AddParams = Type.Object(
+	{
+		action: Type.Literal("add"),
+		texts: Type.Array(Type.String(), { description: "待添加的 todo 文本数组" }),
+	},
+	{ additionalProperties: false },
+);
+const UpdateSingleParams = Type.Object(
+	{
+		action: Type.Literal("update"),
+		id: Type.Number({ description: "要更新的 todo id" }),
+		status: Type.Optional(StatusSchema),
+		text: Type.Optional(Type.String({ description: "新文本（trim 后不可为空）" })),
+	},
+	{ additionalProperties: false },
+);
+const UpdateBatchParams = Type.Object(
+	{
+		action: Type.Literal("update"),
+		updates: Type.Array(
+			Type.Object({
+				id: Type.Number({ description: "要更新的 todo id" }),
+				status: Type.Optional(StatusSchema),
+				text: Type.Optional(Type.String({ description: "新文本（trim 后不可为空）" })),
+			}),
+			{ description: "批量更新数组（优先于单条 id/status/text）" },
 		),
-	});
+	},
+	{ additionalProperties: false },
+);
+const DeleteParams = Type.Object(
+	{
+		action: Type.Literal("delete"),
+		ids: Type.Array(Type.Number(), { description: "要删除的 todo id 数组" }),
+	},
+	{ additionalProperties: false },
+);
+
+export const TodoParams = Type.Union([
+	ListParams,
+	AddParams,
+	UpdateSingleParams,
+	UpdateBatchParams,
+	DeleteParams,
+]);
 
-// ── 5 个 action handler ──────────────────────────────
+// ── 4 个 action handler ──────────────────────────────
 // 错误处理约定（见 CLAUDE.md「Tool 设计」）：handler 失败直接 throw，
-// 不返回「错误成功模式」。model 层纯函数返回 Result 对象（合法），
+// 不返回「错误成功模式」。model 层纯函数（updateTodos）返回 Result 对象（合法），
 // 由 dispatcher 在拿到 error 时 throw，把友好文案交给 Pi 框架展示。
+// addTodos 的校验失败直接 throw（C1：不再静默 filter）。
 
-/** list action */
+/** list action — 返回完整格式化列表 */
 function handleList(state: TodoSessionState): string {
-	return state.todos.length
-		? state.todos.map((t) => formatTodoLine(t)).join("\n")
-		: "No todos";
+	return state.todos.length ? formatTodoList(state.todos) : "No todos";
 }
 
-/** add action — 失败抛错 */
 /** add action — 失败抛错。export 供 behavioral 测试（text/texts 双形陷阱检测）。 */
 export function handleAdd(state: TodoSessionState, params: TodoActionParams): string {
+	// 双形陷阱：同时传 text 和 texts → throw（TC7）
+	if (params.text !== undefined && params.texts !== undefined) {
+		throw new Error('add only accepts texts array; do not also pass singular "text"');
+	}
 	if (!params.texts || params.texts.length === 0) {
 		// 双形陷阱：弱模型 add 时误用单数 text（那是 update 的字段）
 		if (params.text !== undefined) {
@@ -82,11 +123,11 @@ export function handleAdd(state: TodoSessionState, params: TodoActionParams): st
 			'add requires texts parameter (non-empty array). Correct: {"action":"add","texts":["..."]}',
 		);
 	}
+	// addTodos 内部对空项 trim+throw（C1）
 	const r = addTodos(state.todos, state.nextId, params.texts);
-	if (r.error) throw new Error(r.resultText);
 	state.todos = r.newTodos;
 	state.nextId = r.newNextId;
-	return r.resultText!;
+	return r.resultText;
 }
 
 /** update action: batch — 失败抛错 */
@@ -107,7 +148,9 @@ export function handleSingleUpdate(state: TodoSessionState, params: TodoActionPa
 		throw new Error(
 			'update requires at least status or text parameter. Correct: {"action":"update","id":<n>,"status":"in_progress"}',
 		);
-	if (params.text !== undefined && params.text === "") throw new Error("text cannot be empty string");
+	// text 校验统一（CT5）：trim 后空串 throw（不只判 ===）
+	if (params.text !== undefined && params.text.trim().length === 0)
+		throw new Error("text cannot be empty or whitespace-only");
 	if (
 		params.status !== undefined &&
 		!VALID_STATUSES.includes(params.status as (typeof VALID_STATUSES)[number])
@@ -118,23 +161,12 @@ export function handleSingleUpdate(state: TodoSessionState, params: TodoActionPa
 	const todo = state.todos.find((t) => t.id === params.id);
 	if (!todo) throw new Error(`Todo #${params.id} not found`);
 
-	// cancelled 不可恢复（失败抛错）
-	if (todo.status === "cancelled" && params.status !== undefined) {
-		throw new Error(`#${params.id} is cancelled (cannot restore)`);
-	}
-
 	if (params.status !== undefined) todo.status = params.status as Todo["status"];
-	if (params.text !== undefined) todo.text = params.text;
+	if (params.text !== undefined) todo.text = params.text.trim();
 
 	const parts: string[] = [`Updated todo #${todo.id}`];
 	if (params.status !== undefined) parts.push(`status → ${params.status}`);
 	if (params.text !== undefined) parts.push(`text → "${todo.text}"`);
-
-	// 最后一个完成提示
-	const incompleteAfter = state.todos.filter((t) => t.status !== "completed");
-	if (params.status === "completed" && incompleteAfter.length === 0) {
-		return parts.join(", ") + "\n\nAll todos completed. Please summarize your work.";
-	}
 	return parts.join(", ");
 }
 
@@ -144,8 +176,8 @@ function handleUpdate(state: TodoSessionState, params: TodoActionParams): string
 	return handleSingleUpdate(state, params);
 }
 
-/** delete action — 失败抛错；部分 id 缺失则整体拒绝（原子性） */
-/** delete action — 失败抛错。export 供 behavioral 测试（id/ids 双形陷阱检测）。 */
+/** delete action — 失败抛错；部分 id 缺失则整体拒绝（原子性）。
+ * export 供 behavioral 测试（id/ids 双形陷阱检测）。 */
 export function handleDelete(state: TodoSessionState, params: TodoActionParams): string {
 	if (!params.ids || params.ids.length === 0) {
 		// 双形陷阱：弱模型 delete 时误用单数 id（那是 update 的字段）
@@ -174,16 +206,6 @@ export function handleDelete(state: TodoSessionState, params: TodoActionParams):
 	return `Deleted ${removedIds.length} items (#${removedIds.join(", #")}), ${state.todos.length} remaining`;
 }
 
-/** clear action */
-function handleClear(state: TodoSessionState): string {
-	const count = state.todos.length;
-	state.todos = [];
-	state.nextId = 1;
-	state.allCompletedAtCount = null;
-	state.completionSteered = false;
-	return count > 0 ? `Cleared ${count} todos` : "No todos to clear";
-}
-
 // ── Dispatcher ───────────────────────────────────────
 
 function executeTodoAction(
@@ -195,8 +217,7 @@ function executeTodoAction(
 	content: Array<{ type: "text"; text: string }>;
 	details: TodoDetails;
 } {
-	state.lastTodoCallCount = state.userMessageCount;
-	state.stallNotified = false;
+	const isMutation = params.action !== "list";
 
 	let resultText: string;
 	switch (params.action) {
@@ -212,27 +233,33 @@ function executeTodoAction(
 		case "delete":
 			resultText = handleDelete(state, params);
 			break;
-		case "clear":
-			resultText = handleClear(state);
-			break;
 		default:
 			throw new Error(`Unknown action: ${params.action}`);
 	}
 
 	refreshDisplay(ctx);
 
+	// content 组装（T3）：突变附带完整列表；list 已含列表
+	let contentText: string;
+	if (isMutation) {
+		const listText = state.todos.length > 0 ? formatTodoList(state.todos) : "No todos";
+		contentText = `${resultText}\n${listText}`;
+	} else {
+		contentText = resultText;
+	}
+
 	const details: TodoDetails = {
 		action: params.action as TodoDetails["action"],
 		todos: [...state.todos],
 		nextId: state.nextId,
 	};
 	// RPC 模式（xyz-agent GUI）附加 __gui__，前端按 list-tree 渲染。
-	// TUI/print/json 模式走原生文本渲染（resultText 已在 content 中）。
+	// TUI/print/json 模式走原生文本渲染（contentText 已在 content 中）。
 	if (ctx.mode === "rpc") {
 		details.__gui__ = buildGui(state.todos);
 	}
 	return {
-		content: [{ type: "text" as const, text: resultText }],
+		content: [{ type: "text" as const, text: contentText }],
 		details,
 	};
 }
@@ -248,28 +275,22 @@ export function registerTodoTool(
 		name: "todo",
 		label: "Todo",
 		description:
-			"Manage a todo list." +
-			"\n\nAvailable actions:" +
-			"\n- list: View all todos" +
-			"\n- add: Batch add todos (requires texts array)" +
-			"\n- update: Update todo(s) — single (id + optional status/text) or batch (updates[], takes priority)" +
-			"\n- delete: Batch delete todos (requires ids array)" +
-			"\n- clear: Clear all todos and reset IDs" +
-			"\n\nExamples:" +
-			'\n{"action":"add","texts":["write spec","implement"]}' +
-			'\n{"action":"update","id":1,"status":"in_progress"}' +
-			'\n{"action":"update","updates":[{"id":1,"status":"completed"},{"id":2,"status":"in_progress"}]}' +
-			'\n{"action":"delete","ids":[3]}' +
-			"\n\nDon't:" +
-			'\n{"action":"add","text":"x"} ← text is for update; add uses texts:[...]' +
-			'\n{"action":"delete","id":3} ← id is for update; delete uses ids:[...]' +
-			'\n{"action":"update","status":"x"} ← missing id',
-		promptSnippet: "Use todo when breaking multi-step work into trackable items. Consider adding a separate todo for verification checks like running tests or typecheck.",
+			"管理当前会话的 todo 列表。" +
+			"\n\n动作：" +
+			"\n- list: 查看全部 todo" +
+			"\n- add: 批量添加 todo（texts 数组）" +
+			"\n- update: 按 id 更新 todo——status 和/或 text；批量用 updates[]" +
+			"\n- delete: 按 id 删除 todo（ids 数组）" +
+			"\n\n规则：" +
+			"\n- 同一时间只有一个 todo 处于 in_progress" +
+			"\n- 完成一个 todo 立即标记 completed，不要攒到最后批量标记" +
+			"\n- 未真正完成不得标记 completed：被阻塞或测试失败时保持 in_progress",
+		promptSnippet: "用 todo 跟踪多步骤工作；记得为验证步骤（测试、类型检查）单独建 todo。",
 		promptGuidelines: [
-			"[Usage] 多步骤工作（3+步）时使用。AI 自发创建，无需用户触发",
+			"[Usage] 多步骤工作（3+步）时使用，AI 自发创建，无需用户触发",
 			"[验证任务] 为测试 / 类型检查等验证步骤单独建 todo，完成前确保验证通过",
 			"[批量优先] 完成多项任务时使用 updates[] 批量更新，减少工具调用次数",
-			"[自动闭合] 全部完成后工具自动清理，无需手动 clear",
+			"[自动闭合] 全部完成后自动清理，无需手动 delete",
 			"[Not for] 单步操作、简单对话",
 		],
 		executionMode: "sequential",