@zhushanwen/pi-todo 0.8.9 → 0.9.0

package/README.md

@@ -32,6 +32,8 @@ pi install npm:@zhushanwen/pi-todo
 - `status` 枚举：`pending` / `in_progress` / `completed`
 - `add` 不接受 `status`（恒为 pending），不存在 `verifyTexts`（goal 侧的对应概念是 `successCriteria`）
 - 全部 completed 后由 **auto-clear 机制**延迟 2 轮自动清空并重置 `nextId=1`（无手动 clear action）
+- **add 时 auto-GC**：旧列表全部 completed 时，add 自动清空旧列表再新增（`nextId` 重置 1），开启新任务无需先手动清理
+- **规模软上限**：建议 todo 总数不超过 10 个；add 后总数超过 10 时在结果中附加提醒（不拒绝，合并细粒度步骤或 delete 瘦身由模型自决）
 
 ### 错误处理约定
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.8.9",
+  "version": "0.9.0",
   "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.8.2",
-    "@zhushanwen/pi-extension-logger": "0.4.1"
+    "@xyz-agent/extension-protocol": "0.9.0",
+    "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",

package/src/__tests__/todo.test.ts

@@ -12,7 +12,7 @@ import {
 } from "../model";
 import { renderWidgetLines } from "../render";
 import { createTodoSessionState } from "../state";
-import { handleSingleUpdate } from "../tool";
+import { handleAdd, handleSingleUpdate } from "../tool";
 
 // ── 数据模型 + 向后兼容 ──────────────────────────────
 
@@ -105,6 +105,84 @@ describe("todo add", () => {
 	});
 });
 
+// ── todo add — auto-GC（全部 completed 后 add 自动清理旧列表）──
+
+describe("todo add auto-GC", () => {
+	it("旧列表全部 completed → 清空旧列表，新 id 从 1 开始，nextId 重置", () => {
+		const existing: Todo[] = [
+			{ id: 1, text: "old A", status: "completed" },
+			{ id: 2, text: "old B", status: "completed" },
+		];
+		const result = addTodos(existing, 3, ["new task"]);
+
+		expect(result.autoCleared).toBe(true);
+		expect(result.newTodos).toHaveLength(1);
+		expect(result.newTodos[0]).toEqual({ id: 1, text: "new task", status: "pending" });
+		expect(result.newNextId).toBe(2);
+	});
+
+	it("存在未完成项（pending/in_progress）→ 不清理，正常追加", () => {
+		const existing: Todo[] = [
+			{ id: 1, text: "done", status: "completed" },
+			{ id: 2, text: "wip", status: "in_progress" },
+			{ id: 3, text: "waiting", status: "pending" },
+		];
+		const result = addTodos(existing, 4, ["more"]);
+
+		expect(result.autoCleared).toBe(false);
+		expect(result.newTodos).toHaveLength(4);
+		expect(result.newTodos[3].id).toBe(4);
+	});
+
+	it("空列表 → 不触发 auto-GC（autoCleared=false）", () => {
+		const result = addTodos([], 1, ["first"]);
+		expect(result.autoCleared).toBe(false);
+		expect(result.newTodos[0].id).toBe(1);
+	});
+
+	it("resultText 说明自动清理了旧列表", () => {
+		const existing: Todo[] = [{ id: 1, text: "old", status: "completed" }];
+		const result = addTodos(existing, 2, ["new task"]);
+		expect(result.resultText).toContain("Auto-cleared 1 completed todo(s)");
+	});
+});
+
+// ── todo add — 超限软提醒（> RECOMMENDED_MAX_TODOS）──
+
+describe("todo add over-limit reminder", () => {
+	function makeTodos(n: number): Todo[] {
+		return Array.from({ length: n }, (_, i) => ({
+			id: i + 1,
+			text: `task ${i + 1}`,
+			status: "pending" as const,
+		}));
+	}
+
+	it("总数超过 10 → resultText 附加提醒（含建议上限值）", () => {
+		const result = addTodos(makeTodos(9), 10, ["x", "y"]);
+		expect(result.newTodos).toHaveLength(11);
+		expect(result.resultText).toContain("recommended max of 10");
+	});
+
+	it("总数恰为 10 → 不提醒", () => {
+		const result = addTodos(makeTodos(9), 10, ["x"]);
+		expect(result.newTodos).toHaveLength(10);
+		expect(result.resultText).not.toContain("recommended max");
+	});
+
+	it("旧列表全部 completed 的 auto-GC 场景，新列表 ≤10 → 不误报提醒", () => {
+		const completed = Array.from({ length: 12 }, (_, i) => ({
+			id: i + 1,
+			text: `old ${i + 1}`,
+			status: "completed" as const,
+		}));
+		const result = addTodos(completed, 13, ["fresh task"]);
+		expect(result.autoCleared).toBe(true);
+		expect(result.newTodos).toHaveLength(1);
+		expect(result.resultText).not.toContain("recommended max");
+	});
+});
+
 // ── todo update batch ───────────────────────────────
 
 describe("todo update batch", () => {
@@ -197,6 +275,37 @@ describe("handleSingleUpdate guards (tool single path)", () => {
 	});
 });
 
+// ── handleAdd — auto-GC 重置完成周期跟踪 ────────────
+
+describe("handleAdd auto-GC resets completion-cycle tracking", () => {
+	it("全部 completed 后 add → completionSteered / allCompletedAtCount 重置，新一轮完成可再次 steer", () => {
+		const state = createTodoSessionState();
+		state.todos = [{ id: 1, text: "old", status: "completed" }];
+		state.completionSteered = true;
+		state.allCompletedAtCount = 3;
+
+		handleAdd(state, { action: "add", texts: ["new task"] });
+
+		expect(state.completionSteered).toBe(false);
+		expect(state.allCompletedAtCount).toBeNull();
+		expect(state.todos).toHaveLength(1);
+		expect(state.todos[0].id).toBe(1);
+		expect(state.nextId).toBe(2);
+	});
+
+	it("存在未完成项时 add → 完成周期跟踪不受影响", () => {
+		const state = createTodoSessionState();
+		state.todos = [{ id: 1, text: "wip", status: "in_progress" }];
+		state.nextId = 2;
+		state.completionSteered = false;
+
+		handleAdd(state, { action: "add", texts: ["more"] });
+
+		expect(state.todos).toHaveLength(2);
+		expect(state.nextId).toBe(3);
+	});
+});
+
 // ── completed 无拦截 ────────────────────────────────
 
 describe("completed without interception", () => {

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

@@ -59,6 +59,15 @@ describe("todo description — 中文版（动作 + 规则）", () => {
 		expect(DESCRIPTION_REGION).toContain("未真正完成不得标记 completed");
 	});
 
+	it("含规模控制规则（建议不超过 10 个）", () => {
+		expect(DESCRIPTION_REGION).toContain("建议 todo 总数不超过 10 个");
+		expect(DESCRIPTION_REGION).toContain("细粒度步骤优先合并");
+	});
+
+	it("含 auto-GC 行为说明（旧任务全部 completed 后 add 自动清理）", () => {
+		expect(DESCRIPTION_REGION).toContain("旧任务全部 completed 后再 add 会自动清理旧列表");
+	});
+
 	it("已删除旧英文 Examples 段与 Don't 段", () => {
 		expect(DESCRIPTION_REGION).not.toContain("Available actions");
 		expect(DESCRIPTION_REGION).not.toContain("Don't");
@@ -103,4 +112,8 @@ describe("todo tool prompt — snippet & guidelines", () => {
 		expect(TOOL_SRC).toContain("[自动闭合] 全部完成后自动清理");
 		expect(TOOL_SRC).toContain("[批量优先] 完成多项任务时使用 updates[] 批量更新");
 	});
+
+	it("promptGuidelines 含 [规模控制] 条目（不超过 10 个）", () => {
+		expect(TOOL_SRC).toContain("[规模控制] todo 总数建议不超过 10 个");
+	});
 });

package/src/model.ts

@@ -115,16 +115,25 @@ export function buildGui(todos: Todo[]): GuiRenderResult {
 
 // ── Add 逻辑 ─────────────────────────────────────────
 
+/** 建议的单 session todo 数上限（软约束：超限提醒，不硬拒绝） */
+export const RECOMMENDED_MAX_TODOS = 10;
+
 export interface AddResult {
 	newTodos: Todo[];
 	newNextId: number;
 	resultText: string;
+	/** 旧列表全部 completed 被自动清理时为 true（handleAdd 据此重置完成周期跟踪） */
+	autoCleared: boolean;
 }
 
 /**
  * 批量新增 todo。
  * texts 整体 trim；任一项 trim 后为空串则 throw（不再静默 filter 丢弃——
  * 模型应学到传有效项，C1 决策）。
+ *
+ * auto-GC：旧列表非空且全部 completed 时视为「上一任务已结束、开启新任务」，
+ * 先清空旧列表再新增（nextId 重置为 1，与 handlers.handleAutoClear 的清理
+ * 语义一致），避免已完结任务长期堆积在列表里。
  */
 export function addTodos(
 	currentTodos: Todo[],
@@ -141,9 +150,13 @@ export function addTodos(
 		throw new Error("texts must not contain empty or whitespace-only items");
 	}
 
-	const startId = currentNextId;
-	const newTodos = [...currentTodos];
-	let nextId = currentNextId;
+	const autoCleared =
+		currentTodos.length > 0 && currentTodos.every((t) => t.status === "completed");
+	const baseTodos = autoCleared ? [] : currentTodos;
+	const startId = autoCleared ? 1 : currentNextId;
+
+	const newTodos = [...baseTodos];
+	let nextId = startId;
 	for (let i = 0; i < trimmed.length; i++) {
 		newTodos.push({
 			id: nextId++,
@@ -153,10 +166,21 @@ export function addTodos(
 	}
 	const endId = nextId - 1;
 
+	let resultText = `Added ${trimmed.length} todos (#${startId}-#${endId})`;
+	if (autoCleared) {
+		resultText += `\nAuto-cleared ${currentTodos.length} completed todo(s) from the previous task`;
+	}
+
+	// 软上限提醒：总数超过建议值时附加提醒（不拒绝，把决策留给模型）
+	if (newTodos.length > RECOMMENDED_MAX_TODOS) {
+		resultText += `\nNote: ${newTodos.length} todos exceeds the recommended max of ${RECOMMENDED_MAX_TODOS}. Prefer consolidating fine-grained steps or deleting items no longer needed.`;
+	}
+
 	return {
 		newTodos,
 		newNextId: nextId,
-		resultText: `Added ${trimmed.length} todos (#${startId}-#${endId})`,
+		resultText,
+		autoCleared,
 	};
 }
 

package/src/tool.ts

@@ -91,10 +91,16 @@ export function handleAdd(state: TodoSessionState, params: TodoParamsT): string
 			'add requires texts parameter (non-empty array). Correct: {"action":"add","texts":["..."]}',
 		);
 	}
-	// addTodos 内部对空项 trim+throw（C1）
+	// addTodos 内部对空项 trim+throw（C1）；旧列表全部 completed 时自动清理（auto-GC）
 	const r = addTodos(state.todos, state.nextId, params.texts);
 	state.todos = r.newTodos;
 	state.nextId = r.newNextId;
+	if (r.autoCleared) {
+		// 新任务周期：重置完成跟踪，否则上一任务的 completionSteered=true
+		// 会屏蔽本轮全部完成时的质量检查 steer
+		state.allCompletedAtCount = null;
+		state.completionSteered = false;
+	}
 	return r.resultText;
 }
 
@@ -249,13 +255,16 @@ export function registerTodoTool(
 			"\n\n规则：" +
 			"\n- 同一时间只有一个 todo 处于 in_progress" +
 			"\n- 完成一个 todo 立即标记 completed，不要攒到最后批量标记" +
-			"\n- 未真正完成不得标记 completed：被阻塞或测试失败时保持 in_progress",
+			"\n- 未真正完成不得标记 completed：被阻塞或测试失败时保持 in_progress" +
+			"\n- 列表保持聚焦：建议 todo 总数不超过 10 个，细粒度步骤优先合并" +
+			"\n- 旧任务全部 completed 后再 add 会自动清理旧列表，直接添加新任务即可",
 		promptSnippet: "用 todo 跟踪多步骤工作；记得为验证步骤（测试、类型检查）单独建 todo。",
 		promptGuidelines: [
 			"[Usage] 多步骤工作（3+步）时使用，AI 自发创建，无需用户触发",
 			"[验证任务] 为测试 / 类型检查等验证步骤单独建 todo，完成前确保验证通过",
 			"[批量优先] 完成多项任务时使用 updates[] 批量更新，减少工具调用次数",
 			"[自动闭合] 全部完成后自动清理，无需手动 delete",
+			"[规模控制] todo 总数建议不超过 10 个；超过时合并细粒度步骤或 delete 掉不再需要的项",
 			"[Not for] 单步操作、简单对话",
 		],
 		executionMode: "sequential",