@zhushanwen/pi-todo 0.9.3 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "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": {
-    "@taiji/extension-protocol": "0.11.0",
-    "@zhushanwen/pi-extension-logger": "0.6.0"
+    "@zhushanwen/extension-protocol": "0.12.0",
+    "@zhushanwen/pi-extension-logger": "0.6.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",

package/src/__tests__/gui.test.ts

@@ -1,9 +1,36 @@
+/**
+ * buildGui 测试 — meta head + tab-bar 双段架构。
+ *
+ * 覆盖：
+ * - 内容根 = tab-bar 双段：tabs 与 sections 等长（2 段，容器化前提），待办段 =
+ *   未完成项 numbered list-tree（行首序号语义不变），已完成段 = 已完成项 list-tree
+ * - 两段互斥且覆盖全量（tab 标签计数与段内容同源）；空段 = 空 items（既有空态语义）
+ * - meta：title=Todo、progress=current/total 计数、status 语义、托盘 icon（显式
+ *   'list-checks'）+ badge（未完成条数）
+ */
+import type { GuiComponent, GuiComponentProps } from "@zhushanwen/extension-protocol";
 import { describe, expect, it } from "vitest";
 
 import { buildGui, type Todo } from "../model";
 
-describe("buildGui（v1.1 meta head 架构）", () => {
-	it("内容根 = numbered list-tree：行首序号由 ListTree 渲染，label 纯文本（无 #N 前缀）", () => {
+/** tab-bar props（根形状断言收口在此：非 tab-bar 根直接失败，段结构断言才有意义） */
+function tabBarProps(gui: ReturnType<typeof buildGui>): GuiComponentProps["tab-bar"] {
+	if (gui.component.type !== "tab-bar") {
+		throw new Error(`内容根应为 tab-bar，实际 ${gui.component.type}`);
+	}
+	return gui.component.props as GuiComponentProps["tab-bar"];
+}
+
+/** 段必须是 list-tree：返回其 props（段形状先验，供 items 断言） */
+function listTreeProps(section: GuiComponent | undefined): GuiComponentProps["list-tree"] {
+	if (!section || section.type !== "list-tree") {
+		throw new Error(`段应为 list-tree，实际 ${section?.type ?? "undefined"}`);
+	}
+	return section.props as GuiComponentProps["list-tree"];
+}
+
+describe("buildGui（meta head + tab-bar 双段架构）", () => {
+	it("内容根 = tab-bar：sections 与 tabs 等长（2 段），待办段 = 未完成项 numbered list-tree", () => {
 		const todos: Todo[] = [
 			{ id: 1, text: "pending task", status: "pending" },
 			{ id: 2, text: "active task", status: "in_progress" },
@@ -11,16 +38,67 @@ describe("buildGui（v1.1 meta head 架构）", () => {
 		];
 		const gui = buildGui(todos);
 		expect(gui.v).toBe(1);
-		expect(gui.component.type).toBe("list-tree");
-		expect(gui.component.props.numbered).toBe(true);
-		const items = gui.component.props.items;
-		expect(items).toHaveLength(3);
-		// pending → 无 status（guiResult 的 stripUndefined 删除 undefined 键），无 icon（状态由圆点单一表达）
-		expect(items[0]).toEqual({ label: "pending task", depth: 0 });
-		// in_progress → running
-		expect(items[1]).toEqual({ label: "active task", status: "running", depth: 0 });
-		// completed → done
-		expect(items[2]).toEqual({ label: "done task", status: "done", depth: 0 });
+		const { tabs, sections } = tabBarProps(gui);
+		// 标签计数与段内容同源（待办 = 未完成数，已完成 = completed 数）
+		expect(tabs.map((t) => t.label)).toEqual(["待办 2", "已完成 1"]);
+		// 首段带 active：容器化宿主据此建立初始 tab（此后本地切换不被推送重置）
+		expect(tabs[0]!.active).toBe(true);
+		expect(tabs[1]!.active).toBeUndefined();
+		// 与 tabs 等长（长度不等时宿主忽略 sections 退化为纯展示，段内容即丢失）
+		expect(sections).toHaveLength(tabs.length);
+
+		const openProps = listTreeProps(sections![0]![0]);
+		// 行首序号语义不变：numbered 开，label 纯文本（无 #N 前缀，序号由 ListTree 渲染）
+		expect(openProps.numbered).toBe(true);
+		expect(openProps.items).toEqual([
+			// pending → 无 status（guiResult 的 stripUndefined 删除 undefined 键），无 icon
+			{ label: "pending task", depth: 0 },
+			// in_progress → running
+			{ label: "active task", status: "running", depth: 0 },
+		]);
+	});
+
+	it("已完成段 = 已完成项 list-tree（两段互斥且覆盖全量，行内 status 映射不变）", () => {
+		const todos: Todo[] = [
+			{ id: 1, text: "pending task", status: "pending" },
+			{ id: 2, text: "done task", status: "completed" },
+			{ id: 3, text: "another done", status: "completed" },
+		];
+		const { tabs, sections } = tabBarProps(buildGui(todos));
+		expect(tabs.map((t) => t.label)).toEqual(["待办 1", "已完成 2"]);
+		expect(sections).toHaveLength(2);
+
+		const doneProps = listTreeProps(sections![1]![0]);
+		expect(doneProps.numbered).toBe(true);
+		expect(doneProps.items).toEqual([
+			{ label: "done task", status: "done", depth: 0 },
+			{ label: "another done", status: "done", depth: 0 },
+		]);
+
+		// 互斥且覆盖全量：两段 label 并集 = 原清单，无漏行（重复行由 items 精确断言承担）
+		const openLabels = listTreeProps(sections![0]![0]).items.map((i) => i.label);
+		const doneLabels = doneProps.items.map((i) => i.label);
+		expect([...openLabels, ...doneLabels].sort()).toEqual([
+			"another done",
+			"done task",
+			"pending task",
+		]);
+	});
+
+	it("空段（无已完成项 / 无未完成项）= 空 items 的 list-tree：既有空态语义，无装饰性占位", () => {
+		const noDone = tabBarProps(buildGui([{ id: 1, text: "a", status: "pending" }]));
+		expect(noDone.tabs.map((t) => t.label)).toEqual(["待办 1", "已完成 0"]);
+		expect(noDone.sections![1]![0]).toEqual({
+			type: "list-tree",
+			props: { numbered: true, items: [] },
+		});
+
+		const allDone = tabBarProps(buildGui([{ id: 1, text: "a", status: "completed" }]));
+		expect(allDone.tabs.map((t) => t.label)).toEqual(["待办 0", "已完成 1"]);
+		expect(allDone.sections![0]![0]).toEqual({
+			type: "list-tree",
+			props: { numbered: true, items: [] },
+		});
 	});
 
 	it("meta：title=Todo，progress=current/total 计数（head 渲染，body 不再有 progress-bar）", () => {
@@ -34,10 +112,26 @@ describe("buildGui（v1.1 meta head 架构）", () => {
 			title: "Todo",
 			status: "running",
 			progress: { current: 1, total: 3 },
+			icon: "list-checks",
+			badge: "2",
 		});
 	});
 
-	it("全部完成 → meta.status=done", () => {
+	it("meta.icon 推显式 'list-checks' key；badge = 未完成条数（与待办段计数同源）", () => {
+		const gui = buildGui([
+			{ id: 1, text: "a", status: "completed" },
+			{ id: 2, text: "b", status: "pending" },
+		]);
+		// 协议形状：string（宿主按 lucide 名解析）或 { paths }（自定义形状）。
+		// todo 只用 key 形态——与宿主内置 widgetKey 映射（'todo'→ListChecks）同款，
+		// 宿主改自己的映射表也不会换掉 todo 图标。
+		expect(gui.meta!.icon).toBe("list-checks");
+		expect(gui.meta!.badge).toBe("1");
+		// badge 与首段标签计数同源（同一 open 计数，无双口径）
+		expect(tabBarProps(gui).tabs[0]!.label).toContain(gui.meta!.badge!);
+	});
+
+	it("全部完成 → meta.status=done（badge 归零）", () => {
 		const todos: Todo[] = [
 			{ id: 1, text: "a", status: "completed" },
 			{ id: 2, text: "b", status: "completed" },
@@ -46,20 +140,32 @@ describe("buildGui（v1.1 meta head 架构）", () => {
 			title: "Todo",
 			status: "done",
 			progress: { current: 2, total: 2 },
+			icon: "list-checks",
+			badge: "0",
 		});
 	});
 
-	it("有 pending 无 in_progress → status=idle；empty todos → 无 progress", () => {
+	it("有 pending 无 in_progress → status=idle；empty todos → 无 progress + 双空段", () => {
 		const pendingOnly: Todo[] = [{ id: 1, text: "a", status: "pending" }];
 		expect(buildGui(pendingOnly).meta).toEqual({
 			title: "Todo",
 			status: "idle",
 			progress: { current: 0, total: 1 },
+			icon: "list-checks",
+			badge: "1",
+		});
+		expect(buildGui([]).meta).toEqual({
+			title: "Todo",
+			status: "idle",
+			icon: "list-checks",
+			badge: "0",
 		});
-		expect(buildGui([]).meta).toEqual({ title: "Todo", status: "idle" });
-		// 空 list：numbered 仍开（items 空，无行渲染）
-		const emptyGui = buildGui([]);
-		expect(emptyGui.component.type).toBe("list-tree");
-		expect(emptyGui.component.props.items).toEqual([]);
+		// 空清单：两段皆空 list-tree（numbered 仍开，items 空，无行渲染）
+		const empty = tabBarProps(buildGui([]));
+		expect(empty.tabs.map((t) => t.label)).toEqual(["待办 0", "已完成 0"]);
+		expect(empty.sections!.map((s) => s[0])).toEqual([
+			{ type: "list-tree", props: { numbered: true, items: [] } },
+			{ type: "list-tree", props: { numbered: true, items: [] } },
+		]);
 	});
 });

package/src/__tests__/todo.test.ts

@@ -1,15 +1,24 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+// handlers.ts 模块级 getLogger —— 测试里 spy warn（脏条目汇总留痕断言面）
+const loggerWarnSpy = vi.hoisted(() => vi.fn());
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => ({ warn: loggerWarnSpy, debug: vi.fn(), error: vi.fn() }),
+}));
 
 import {
 	addTodos,
 	formatTodoLine,
 	formatTodoList,
+	isBlankUpdateText,
+	isValidTodoStatus,
 	migrateTodo,
 	type Todo,
 	updateTodos,
 	VALID_STATUSES,
 } from "../model";
+import { reconstructState } from "../handlers";
 import { renderWidgetLines } from "../render";
 import { createTodoSessionState } from "../state";
 import { handleAdd, handleSingleUpdate } from "../tool";
@@ -30,6 +39,25 @@ describe("Todo data model", () => {
 		expect(VALID_STATUSES).toEqual(["pending", "in_progress", "completed"]);
 	});
 
+	// 共享校验原语：migrateTodo 迁移映射 / tool 单条 update / model 批量 update
+	// 三处共用的同一判据（校验收敛单点，文案由调用方编排）
+	it("isValidTodoStatus — 三态字面量为真、其余（含历史 verifying）为假", () => {
+		expect(isValidTodoStatus("pending")).toBe(true);
+		expect(isValidTodoStatus("in_progress")).toBe(true);
+		expect(isValidTodoStatus("completed")).toBe(true);
+		expect(isValidTodoStatus("verifying")).toBe(false);
+		expect(isValidTodoStatus("done")).toBe(false);
+		expect(isValidTodoStatus("")).toBe(false);
+	});
+
+	it("isBlankUpdateText — trim 后空串为真（CT5 不只判 ===）、非空为假", () => {
+		expect(isBlankUpdateText("")).toBe(true);
+		expect(isBlankUpdateText("   ")).toBe(true);
+		expect(isBlankUpdateText("\t\n")).toBe(true);
+		expect(isBlankUpdateText("hello")).toBe(false);
+		expect(isBlankUpdateText(" a ")).toBe(false);
+	});
+
 	it("should migrate verifying → in_progress", () => {
 		const oldTodo = { id: 1, text: "test", status: "verifying" } as unknown as Todo;
 		const migrated = migrateTodo(oldTodo);
@@ -67,6 +95,74 @@ describe("Todo data model", () => {
 		expect(() => migrateTodo(undefined)).toThrow(TypeError);
 		expect(() => migrateTodo("garbage")).toThrow(TypeError);
 	});
+
+	it("dirty id (string / NaN) → TypeError（不产 NaN 毒化 nextId）", () => {
+		expect(() => migrateTodo({ id: "1", text: "x", status: "pending" })).toThrow(/invalid id/);
+		expect(() => migrateTodo({ id: Number.NaN, text: "x", status: "pending" })).toThrow(/invalid id/);
+		expect(() => migrateTodo({ text: "missing id", status: "pending" })).toThrow(/invalid id/);
+	});
+
+	it("dirty text (number / missing) → TypeError", () => {
+		expect(() => migrateTodo({ id: 1, text: 42, status: "pending" })).toThrow(/invalid text/);
+		expect(() => migrateTodo({ id: 1, status: "pending" })).toThrow(/invalid text/);
+	});
+});
+
+// ── reconstructState 脏条目降级（汇总 warn + 不产 NaN）──
+
+describe("reconstructState dirty entry degradation", () => {
+	/** 构造最小 ctx：sessionManager.getEntries 返回给定 toolResult 快照。 */
+	function makeCtx(details: unknown): Parameters<typeof reconstructState>[1] {
+		return {
+			sessionManager: {
+				getEntries: () => [
+					{ type: "message", message: { role: "toolResult", toolName: "todo", details } },
+				],
+			},
+		} as unknown as Parameters<typeof reconstructState>[1];
+	}
+
+	beforeEach(() => {
+		loggerWarnSpy.mockClear();
+	});
+
+	it("脏条目跳过 + 汇总一次 warn，好条目保留、nextId 不产 NaN", () => {
+		const state = createTodoSessionState();
+		reconstructState(
+			state,
+			makeCtx({
+				todos: [
+					{ id: 1, text: "ok", status: "completed" },
+					{ id: "bad", text: "dirty id" },
+					{ id: 2, text: 42 },
+				],
+				nextId: 9,
+			}),
+		);
+		expect(state.todos).toHaveLength(1);
+		expect(state.todos[0]).toMatchObject({ id: 1, text: "ok", status: "completed" });
+		// details.nextId 存在 → 直接采用，Math.max 不见脏 id
+		expect(state.nextId).toBe(9);
+		// 计数可见：一次 warn 带跳过数与总量（不逐条刷屏）
+		expect(loggerWarnSpy).toHaveBeenCalledTimes(1);
+		expect(loggerWarnSpy).toHaveBeenCalledWith(
+			expect.stringContaining("skipped dirty todo entries"),
+			expect.objectContaining({ skipped: 2, total: 3, errors: expect.any(Array) }),
+		);
+	});
+
+	it("nextId 缺失 + 脏条目跳过 → nextId 从存活条目推导（不产 NaN）", () => {
+		const state = createTodoSessionState();
+		reconstructState(
+			state,
+			makeCtx({
+				todos: [{ id: "bad", text: "dirty" }, { id: 5, text: "ok", status: "pending" }],
+			}),
+		);
+		expect(state.todos).toHaveLength(1);
+		expect(state.nextId).toBe(6);
+		expect(Number.isNaN(state.nextId)).toBe(false);
+	});
 });
 
 // ── todo add ────────────────────────────────────────

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

@@ -1,7 +1,7 @@
 /**
  * executeTodoAction handler 级测试 —— M17 后的两条路径：
  * 1. tool result 无 __gui__（全模式统一——状态展示不再进 details）
- * 2. refreshDisplay GUI widget 推送（rpc 推 marker 编码 / tui 推纯文本行）
+ * 2. refreshDisplay GUI widget 推送（rpc 推 marker 编码的 tab-bar 双段信封 / tui 推纯文本行）
  *
  * 策略：executeTodoAction 未导出，通过 registerTodoTool + mock pi 捕获
  * 已注册 tool，再以不同 ctx.mode 调 execute。setup 第三参传真实
@@ -10,7 +10,7 @@
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { GUI_WIDGET_MARKER } from "@taiji/extension-protocol";
+import { GUI_WIDGET_MARKER } from "@zhushanwen/extension-protocol";
 import { describe, expect, it, vi, type Mock } from "vitest";
 
 import { makeRefreshDisplay } from "../index";
@@ -40,6 +40,7 @@ interface RegisteredTool {
 		onUpdate: unknown,
 		ctx: { mode: TestMode },
 	) => Promise<ExecuteResult>;
+	renderCall?: (args: Record<string, unknown>, theme: Theme, context?: unknown) => unknown;
 }
 
 // pi-coding-agent 的 ExtensionContext 类型声明里没有 mode 字段（运行时实际有），
@@ -78,6 +79,31 @@ const stubTheme = {
 	getBashModeBorderColor: () => (text: string) => text,
 } as unknown as Theme;
 
+// ── renderCall 非法 args 安全渲染（TUI 渲染先于 schema 校验）──
+
+/** 注册 → 捕获 tool → 以非法 args 调 renderCall，返回渲染文本（width 足够宽避免 wrap）。 */
+function renderedCallText(args: unknown): string {
+	const { tool } = setup();
+	if (!tool.renderCall) throw new Error("todo tool did not register renderCall");
+	const node = tool.renderCall(args as Record<string, unknown>, stubTheme) as {
+		render: (width: number) => string[];
+	};
+	return node.render(400).join("\n");
+}
+
+describe("renderCall — 非法 args 安全渲染", () => {
+	it("args 为 null / 原始类型 → 占位文本，不抛错", () => {
+		expect(renderedCallText(null)).toContain("(invalid args)");
+		expect(renderedCallText("bogus")).toContain("(invalid args)");
+	});
+
+	it("字段错型（action 非字符串 / texts、ids 非数组）→ 不抛错，安全回落到标题", () => {
+		const text = renderedCallText({ action: 7, texts: "not-an-array", ids: 3, status: 1 });
+		expect(text).toContain("todo ");
+		expect(text).not.toContain("(invalid args)");
+	});
+});
+
 /** 构造指定 mode 的 ctx，setWidget 为 vi.fn 供断言（refreshDisplay 推送出口）。 */
 function makeCtx(mode: TestMode, hasUI: boolean): {
 	ctx: { mode: TestMode; hasUI: boolean; ui: { theme: Theme; setStatus: Mock; setWidget: Mock<SetWidgetFn> } };
@@ -100,6 +126,42 @@ const makeRpcCtx = () => makeCtx("rpc", false);
 /** TUI 模式 ctx：hasUI=true。 */
 const makeTuiCtx = () => makeCtx("tui", true);
 
+// ── GUI 信封解析（wire 形状：只声明断言用到的字段）────
+
+interface GuiEnvelope {
+	v: number;
+	component: {
+		type: string;
+		props: {
+			tabs: Array<{ label: string; active?: boolean }>;
+			// 段 = 子树（组件数组），与 tabs 等长一一对应
+			sections: Array<
+				Array<{
+					type: string;
+					props: {
+						numbered?: boolean;
+						items: Array<{ label: string; status?: string; depth?: number }>;
+					};
+				}>
+			>;
+		};
+	};
+	meta: {
+		title: string;
+		icon?: string;
+		badge?: string;
+		progress?: { current: number; total: number };
+	};
+}
+
+/** 取最后一次 setWidget 推送的 marker 编码信封（G-1 / G-4 共用解析） */
+function lastEnvelope(setWidget: Mock<SetWidgetFn>): GuiEnvelope {
+	const call = setWidget.mock.calls.at(-1);
+	const encoded = call?.[1]?.[0];
+	if (!encoded) throw new Error("setWidget 未收到 marker 编码载荷");
+	return JSON.parse(encoded.slice(GUI_WIDGET_MARKER.length)) as GuiEnvelope;
+}
+
 // ── tool result：无 __gui__（M17 后全模式统一）─────────
 
 describe("executeTodoAction — tool result 无 __gui__（全模式）", () => {
@@ -155,7 +217,7 @@ describe("executeTodoAction — tool result 无 __gui__（全模式）", () => {
 // ── refreshDisplay：GUI widget 推送（M17，真实实现）────
 
 describe("refreshDisplay — GUI widget 推送（setup 传真实实现）", () => {
-	it("G-1: rpc + add → setWidget 收到 ('todo', [GUI_WIDGET_MARKER + JSON])，解析后为 v1.1 信封（list-tree + meta）", async () => {
+	it("G-1: rpc + add → setWidget 收到 ('todo', [GUI_WIDGET_MARKER + JSON])，解析后为信封（tab-bar 双段 + meta）", async () => {
 		const { tool } = setup();
 		const { ctx, setWidget } = makeRpcCtx();
 		await tool.execute(
@@ -169,22 +231,48 @@ describe("refreshDisplay — GUI widget 推送（setup 传真实实现）", () =
 		const [key, value] = setWidget.mock.calls[0]!;
 		expect(key).toBe("todo");
 		expect(value).toHaveLength(1);
-		const encoded = value![0]!;
 		// marker 前缀用协议常量断言（不手写编码）
-		expect(encoded.startsWith(GUI_WIDGET_MARKER)).toBe(true);
-		const parsed = JSON.parse(encoded.slice(GUI_WIDGET_MARKER.length)) as {
-			v: number;
-			component: { type: string; props: { numbered: boolean; items: Array<{ label: string }> } };
-			meta: { title: string; progress: { current: number; total: number } };
-		};
-		// v1.1 wire：GuiRenderResult 信封（component + meta 宿主元数据）
+		expect(value![0]!.startsWith(GUI_WIDGET_MARKER)).toBe(true);
+		const parsed = lastEnvelope(setWidget);
+		// wire：GuiRenderResult 信封（component + meta 宿主元数据）
 		expect(parsed.v).toBe(1);
-		expect(parsed.component.type).toBe("list-tree");
-		expect(parsed.component.props.numbered).toBe(true);
-		expect(parsed.component.props.items).toHaveLength(2);
-		expect(parsed.component.props.items[0]).toMatchObject({ label: "task A" });
-		expect(parsed.component.props.items[1]).toMatchObject({ label: "task B" });
-		expect(parsed.meta).toMatchObject({ title: "Todo", progress: { current: 0, total: 2 } });
+		expect(parsed.component.type).toBe("tab-bar");
+		// 两段与 tabs 等长（长度不等宿主即忽略 sections 退化为纯展示）
+		expect(parsed.component.props.tabs.map((t) => t.label)).toEqual(["待办 2", "已完成 0"]);
+		expect(parsed.component.props.sections).toHaveLength(2);
+		const openSection = parsed.component.props.sections[0]!;
+		expect(openSection).toHaveLength(1);
+		expect(openSection[0]!.type).toBe("list-tree");
+		expect(openSection[0]!.props.numbered).toBe(true);
+		expect(openSection[0]!.props.items.map((i) => i.label)).toEqual(["task A", "task B"]);
+		expect(parsed.meta).toMatchObject({
+			title: "Todo",
+			icon: "list-checks",
+			badge: "2",
+			progress: { current: 0, total: 2 },
+		});
+	});
+
+	it("G-4: rpc + update(completed) → 信封待办段剔除该项、已完成段含该项（badge 同步 -1）", async () => {
+		const { tool } = setup();
+		const { ctx, setWidget } = makeRpcCtx();
+		await tool.execute("id", { action: "add", texts: ["task A", "task B"] }, undefined, undefined, ctx);
+		await tool.execute(
+			"id",
+			{ action: "update", updates: [{ id: 1, status: "completed" }] },
+			undefined,
+			undefined,
+			ctx,
+		);
+		const parsed = lastEnvelope(setWidget);
+		expect(parsed.component.props.tabs.map((t) => t.label)).toEqual(["待办 1", "已完成 1"]);
+		expect(parsed.component.props.sections[0]![0]!.props.items.map((i) => i.label)).toEqual([
+			"task B",
+		]);
+		expect(parsed.component.props.sections[1]![0]!.props.items).toEqual([
+			{ label: "task A", status: "done", depth: 0 },
+		]);
+		expect(parsed.meta).toMatchObject({ badge: "1", progress: { current: 1, total: 2 } });
 	});
 
 	it("G-2: rpc + delete 清空列表 → setWidget 收到 ('todo', undefined)（清除语义）", async () => {

package/src/handlers.ts

@@ -75,18 +75,27 @@ export function reconstructState(state: TodoSessionState, ctx: ExtensionContext)
 
 		const details = msg.details as TodoDetails | undefined;
 		if (details?.todos && Array.isArray(details.todos)) {
-			// 脏数据降级：单条迁移失败（null/primitive）跳过该条，全部失败则忽略整个快照，不中断回放
+			// 脏数据降级：单条迁移失败（null/primitive/脏 id/脏 text）跳过该条；跳过清单
+			// 汇总一次 warn（不逐条刷屏），全部失败则忽略整个快照，不中断回放
 			const migrated: TodoDetails["todos"] = [];
+			const skippedErrors: string[] = [];
 			for (const t of details.todos) {
 				try {
 					migrated.push(migrateTodo(t));
 				} catch (e) {
-					// best-effort 降级：脏数据（null/primitive）跳过该条，不中断会话回放
-					logger.debug("reconstructState: skipping dirty todo entry", { error: String(e) });
+					skippedErrors.push(String(e));
 				}
 			}
+			if (skippedErrors.length > 0) {
+				logger.warn("reconstructState: skipped dirty todo entries", {
+					skipped: skippedErrors.length,
+					total: details.todos.length,
+					errors: skippedErrors,
+				});
+			}
 			if (migrated.length > 0) {
 				state.todos = migrated;
+				// 脏 id 已在 migrateTodo 被拒——Math.max 只见存活条目，不产 NaN
 				state.nextId = details.nextId ?? Math.max(...migrated.map((t) => t.id)) + 1;
 			}
 		}

package/src/index.ts

@@ -22,7 +22,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { setWidgetDual, type GuiContext } from "@taiji/extension-protocol";
+import { setWidgetDual, type GuiContext } from "@zhushanwen/extension-protocol";
 
 import { registerTodosCommand } from "./commands";
 import { registerTodoEventHandlers, type RefreshDisplayFn } from "./handlers";

package/src/model.ts

@@ -4,12 +4,13 @@
  */
 
 import {
+	type GuiComponent,
 	type GuiRenderResult,
 	guiComponent,
 	guiResult,
 	type TreeItem,
 	type WidgetMeta,
-} from "@taiji/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 
 // ── 数据模型 ─────────────────────────────────────────
 
@@ -27,10 +28,39 @@ export interface TodoDetails {
 
 export const VALID_STATUSES = ["pending", "in_progress", "completed"] as const;
 
-type ValidStatus = (typeof VALID_STATUSES)[number];
+/** 合法状态三态的推导类型（导出供包内其余模块命名收窄后的类型）。 */
+export type ValidStatus = (typeof VALID_STATUSES)[number];
+
+/**
+ * status 合法性判据（type guard）：migrate 迁移映射 / tool 单条 update / model 批量
+ * update 三处共享的同一校验原语——判定规则单点，错误文案由各调用方按面向对象
+ * （迁移降级 / LLM 单条引导 / 批量 id 定位）自行编排，展示层差异不属规则差异。
+ */
+export function isValidTodoStatus(status: string): status is ValidStatus {
+	return (VALID_STATUSES as readonly string[]).includes(status);
+}
+
+/**
+ * update text 有效性判据（CT5）：trim 后空串 = 非法（不只判 ===），tool 单条与
+ * model 批量两条 update 路径共享。
+ */
+export function isBlankUpdateText(text: string): boolean {
+	return text.trim().length === 0;
+}
 
 // ── 迁移/兼容 ───────────────────────────────────────
 
+/**
+ * 历史状态 → 现态映射（旧格式一次性降级）。
+ *
+ * 三态化：cancelled → completed 不丢数据，且解除 every(completed) 死锁。
+ */
+const LEGACY_STATUS: Record<string, ValidStatus> = {
+	verifying: "in_progress",
+	failed: "pending",
+	cancelled: "completed",
+};
+
 /** 旧格式迁移：verifying → in_progress，failed → pending，cancelled → completed（历史三态化降级），done:boolean → status */
 export function migrateTodo(raw: unknown): Todo {
 	// raw 是任意旧格式数据（兼容 done:boolean 等历史结构），以 Record 方式安全访问字段
@@ -41,36 +71,48 @@ export function migrateTodo(raw: unknown): Todo {
 		);
 	}
 	const record = raw as Record<string, unknown>;
-	const hasValidStatus =
-		typeof record.status === "string" &&
-		VALID_STATUSES.includes(record.status as ValidStatus);
+	const rawStatusField = record.status;
+	const hasValidStatus = typeof rawStatusField === "string" && isValidTodoStatus(rawStatusField);
 
 	let status: ValidStatus;
 	if (hasValidStatus) {
-		status = record.status as ValidStatus;
+		status = rawStatusField;
 	} else {
 		// 极旧格式 done: boolean
 		const done = typeof record.done === "boolean" ? record.done : undefined;
 		status = done === true ? "completed" : "pending";
 	}
 
-	// 历史状态映射（先转 string 避免类型收窄后无法比较）
-	const rawStatus = record.status as string | undefined;
-	if (rawStatus === "verifying") status = "in_progress";
-	if (rawStatus === "failed") status = "pending";
-	// 三态化降级：历史 cancelled 项映射为 completed（不丢数据，且解除 every(completed) 死锁）
-	if (rawStatus === "cancelled") status = "completed";
+	// 历史状态映射（查表单点：三条互斥 if → 一张表，不再裸 cast）
+	const rawStatus = typeof record.status === "string" ? record.status : undefined;
+	const legacyStatus = rawStatus ? LEGACY_STATUS[rawStatus] : undefined;
+	if (legacyStatus) status = legacyStatus;
+
+	// id/text 契约校验：脏 id（非 number / NaN）会在 reconstructState 的 Math.max 推导
+	// nextId 时产出 NaN 毒化后续 add/update/delete 锚点，脏 text 破坏渲染与 add 的 trim
+	// 契约——按「脏数据明确报错 → 调用方单条跳过」契约，与上方 null/primitive 守卫同型
+	// throw TypeError（调用方 reconstructState 收集降级）。
+	const id = record.id;
+	if (typeof id !== "number" || Number.isNaN(id)) {
+		throw new TypeError(
+			`migrateTodo: invalid id (expected number, got ${typeof id}${Number.isNaN(id) ? " NaN" : ""})`,
+		);
+	}
+	if (typeof record.text !== "string") {
+		throw new TypeError(`migrateTodo: invalid text (expected string, got ${typeof record.text})`);
+	}
 
 	return {
-		id: record.id as number,
-		text: record.text as string,
+		id,
+		text: record.text,
 		status,
 	};
 }
 
 // ── GUI 渲染辅助 ─────────────────────────────────────
 
-/** completed 计数单一来源：buildGui / renderStatusText / renderWidgetLines / component 四个消费点共用口径 */
+/** completed 计数单一来源：renderStatusText / renderWidgetLines / component 三个消费点共用口径
+ * （buildGui 的 tab 计数与段内容改由 openTodos/doneTodos 同源复用，不再经本函数）。 */
 export function todoProgress(todos: Todo[]): { completed: number; total: number } {
 	return {
 		completed: todos.filter((t) => t.status === "completed").length,
@@ -78,14 +120,37 @@ export function todoProgress(todos: Todo[]): { completed: number; total: number
 	};
 }
 
+/** 单段清单：两段共用同一构造（仅过滤条件不同），保住行首序号范式与 status 映射的单一口径。 */
+function todoListTree(todos: Todo[]): GuiComponent {
+	const items: TreeItem[] = todos.map((t) => ({
+		label: t.text,
+		status:
+			t.status === "in_progress"
+				? "running"
+				: t.status === "completed"
+					? "done"
+					: undefined, // pending 无 status
+		depth: 0,
+	}));
+	return guiComponent("list-tree", { numbered: true, items });
+}
+
 /**
- * 把 todos 组装为 GuiRenderResult（v1.1 meta head 架构，对齐 extension-protocol@0.3.0）。
+ * 把 todos 组装为 GuiRenderResult（meta head + tab-bar 双段架构）。
  *
- * - meta（标题/状态/进度）由宿主壳层渲染成唯一 head：进度计数 "N/M" + mini bar
- *   替代 body 内 progress-bar（精简 body），全完成 status=done（head 绿点 + bar 变绿）。
- * - 内容根 = numbered list-tree：行首弱化序号（编辑器行号范式，ListTree 渲染），
+ * - meta（标题/状态/进度/icon/badge）由宿主壳层（widget 面板 head + 托盘）唯一渲染：
+ *   进度计数 "N/M" + mini bar 替代 body 内 progress-bar（精简 body），全完成 status=done
+ *   （head 绿点 + bar 变绿）；icon 点名 lucide key 'list-checks'（与宿主内置 widgetKey
+ *   映射 'todo'→ListChecks 同图标）——宿主映射只是兜底，显式声明后宿主调整自己的映射表
+ *   也不会换掉 todo 的图标；badge = 未完成条数（托盘 `[☑ 2]`，宿主超长 truncate）。
+ * - 内容根 = tab-bar 双段（tabs/sections 等长 2 段，宿主本地切换、不回传 extension）：
+ *   待办段 = 未完成项（pending + in_progress），已完成段 = completed 项——两段互斥且覆盖
+ *   全量，tab 标签计数与段内容同源（否则「待办 N」与实际行数成双口径）；分段而非堆叠，
+ *   使已完成项不占待办首屏（面板形态裁决，设计 D5）。
+ * - 两段同构 numbered list-tree：行首弱化序号（编辑器行号范式，ListTree 渲染），
  *   id 不再烧进 label——update/delete 锚点由模型经 list action 获取，用户引用
  *   「第 N 项」即可；状态由行尾圆点单一表达（无 icon，v6 单一信息源裁决）。
+ *   空段 = items 为空的 list-tree（沿用既有空态语义，不加装饰性占位）。
  *
  * status → 圆点映射：
  *   pending      → 无圆点（常态归零）
@@ -93,29 +158,37 @@ export function todoProgress(todos: Todo[]): { completed: number; total: number
  *   completed    → done（success + label 弱化）
  */
 export function buildGui(todos: Todo[]): GuiRenderResult {
-	const { completed, total } = todoProgress(todos);
-	const inProgress = todos.filter((t) => t.status === "in_progress").length;
+	// 先划分段数组，再复用同一批数组产出标签/内容/badge/inProgress——避免
+	// 「total - completed」与「两次 filter」两个口径各自推导同一事实。
+	const openTodos = todos.filter((t) => t.status !== "completed");
+	const doneTodos = todos.filter((t) => t.status === "completed");
+	const total = todos.length;
+	const completed = doneTodos.length;
+	const open = openTodos.length;
+	const inProgress = openTodos.filter((t) => t.status === "in_progress").length;
 
 	const status: WidgetMeta["status"] =
 		total > 0 && completed === total ? "done" : inProgress > 0 ? "running" : "idle";
 
-	const items: TreeItem[] = todos.map((t) => ({
-		label: t.text,
-		status:
-			t.status === "in_progress"
-				? "running"
-				: t.status === "completed"
-					? "done"
-					: undefined, // pending 无 status
-		depth: 0,
-	}));
-
 	return guiResult(
-		guiComponent("list-tree", { numbered: true, items }),
+		guiComponent("tab-bar", {
+			tabs: [
+				// 首段带 active：容器化宿主据此建立初始 tab（此后本地切换不被推送重置）
+				{ label: `待办 ${open}`, active: true },
+				{ label: `已完成 ${completed}` },
+			],
+			// 段 = 子树（组件数组，与 tabs 等长一一对应；宿主渲染 active 段的全部子组件）
+			sections: [
+				[todoListTree(openTodos)],
+				[todoListTree(doneTodos)],
+			],
+		}),
 		{
 			title: "Todo",
 			status,
 			progress: total > 0 ? { current: completed, total } : undefined,
+			icon: "list-checks",
+			badge: String(open),
 		},
 	);
 }
@@ -210,7 +283,7 @@ export function updateTodos(
 ): UpdateResult {
 	// text 校验统一（CT5）：text 存在则 trim，空串 throw（不静默跳过）
 	for (const u of updates) {
-		if (u.text !== undefined && u.text.trim().length === 0) {
+		if (u.text !== undefined && isBlankUpdateText(u.text)) {
 			throw new Error(`update item id ${u.id}: text cannot be empty or whitespace-only`);
 		}
 	}
@@ -219,26 +292,30 @@ export function updateTodos(
 	if (new Set(ids).size !== ids.length) {
 		throw new Error("duplicate ids in updates");
 	}
+	// 校验遍同时产出 patch（非法输入在任何突变前 throw，文案不变）；突变遍直接消
+	// patch，不再重复判定同一条件（旧实现第二遍 isValidTodoStatus 恒真）
+	const patches = new Map<number, { status?: Todo["status"]; text?: string }>();
 	for (const u of updates) {
-		const todo = currentTodos.find((t) => t.id === u.id);
-		if (!todo) {
+		if (!currentTodos.some((t) => t.id === u.id)) {
 			throw new Error(`Todo #${u.id} not found`);
 		}
 		if (!u.status && !u.text) {
 			throw new Error(`update item for id ${u.id} has neither status nor text`);
 		}
-		if (u.status && !VALID_STATUSES.includes(u.status as (typeof VALID_STATUSES)[number])) {
-			throw new Error(`invalid status '${u.status}' for update item id ${u.id}`);
+		const patch: { status?: Todo["status"]; text?: string } = {};
+		if (u.status) {
+			if (!isValidTodoStatus(u.status)) {
+				throw new Error(`invalid status '${u.status}' for update item id ${u.id}`);
+			}
+			patch.status = u.status;
 		}
+		if (u.text !== undefined) patch.text = u.text.trim();
+		patches.set(u.id, patch);
 	}
 
 	const updated = currentTodos.map((t) => {
-		const u = updates.find((u) => u.id === t.id);
-		if (!u) return t;
-		const patch: Partial<Todo> = {};
-		if (u.status) patch.status = u.status as Todo["status"];
-		if (u.text !== undefined) patch.text = u.text.trim();
-		return { ...t, ...patch };
+		const patch = patches.get(t.id);
+		return patch ? { ...t, ...patch } : t;
 	});
 	return {
 		updatedTodos: updated,

package/src/render.ts

@@ -154,7 +154,7 @@ function buildTodoListText(todoList: Todo[], options: { expanded: boolean }, the
 // ── Tool renderResult handler ────────────────────────
 
 import { Text } from "@earendil-works/pi-tui";
-import { firstContentText } from "@taiji/extension-protocol";
+import { firstContentText } from "@zhushanwen/extension-protocol";
 
 export function renderTodoResult(result: unknown, options: { expanded: boolean }, theme: Theme): Text {
 	const r = result as { content: Array<{ type: string; text?: string }>; details?: unknown };

package/src/tool.ts

@@ -17,8 +17,10 @@ import { type Static, Type } from "typebox";
 import {
 	addTodos,
 	formatTodoList,
-	type Todo,
+	isBlankUpdateText,
+	isValidTodoStatus,
 	type TodoDetails,
+	type ValidStatus,
 	updateTodos,
 	VALID_STATUSES,
 } from "./model";
@@ -122,20 +124,23 @@ export function handleSingleUpdate(state: TodoSessionState, params: TodoParamsT)
 		throw new Error(
 			'update requires at least status or text parameter. Correct: {"action":"update","id":<n>,"status":"in_progress"}',
 		);
-	// text 校验统一（CT5）：trim 后空串 throw（不只判 ===）
-	if (params.text !== undefined && params.text.trim().length === 0)
+	// text/status 校验判据与 model.updateTodos 批量路径共享同一原语（CT5）；文案
+	// 保持单条引导形态（LLM 单条修正提示），展示层差异不属规则差异。校验遍同时产出
+	// 收窄结果 nextStatus——非法输入仍在任何突变前 throw，突变遍不再重复判定同一条件
+	if (params.text !== undefined && isBlankUpdateText(params.text))
 		throw new Error("text cannot be empty or whitespace-only");
-	if (
-		params.status !== undefined &&
-		!VALID_STATUSES.includes(params.status as (typeof VALID_STATUSES)[number])
-	) {
-		throw new Error(`status only accepts ${VALID_STATUSES.join(" / ")}`);
+	let nextStatus: ValidStatus | undefined;
+	if (params.status !== undefined) {
+		if (!isValidTodoStatus(params.status)) {
+			throw new Error(`status only accepts ${VALID_STATUSES.join(" / ")}`);
+		}
+		nextStatus = params.status;
 	}
 
 	const todo = state.todos.find((t) => t.id === params.id);
 	if (!todo) throw new Error(`Todo #${params.id} not found`);
 
-	if (params.status !== undefined) todo.status = params.status as Todo["status"];
+	if (nextStatus !== undefined) todo.status = nextStatus;
 	if (params.text !== undefined) todo.text = params.text.trim();
 
 	const parts: string[] = [`Updated todo #${todo.id}`];
@@ -227,7 +232,8 @@ function executeTodoAction(
 		nextId: state.nextId,
 	};
 	// 状态展示不再进 tool result（GUI 渲染字段已移除）：GUI 走 refreshDisplay 的
-	// guiSetWidget 推送（M17 widget 面板），TUI 走原生文本渲染（contentText 已在 content 中）。
+	// setWidgetDual 推送（GUI 臂 = guiSetWidget/marker 通道，低层原语不单独调用；渲染终点 =
+	// composer 任务托盘的协议 widget 区），TUI 走原生文本渲染（contentText 已在 content 中）。
 	return {
 		content: [{ type: "text" as const, text: contentText }],
 		details,
@@ -275,14 +281,24 @@ export function registerTodoTool(
 		},
 
 		renderCall(args: Record<string, unknown>, theme: Theme, _context?: unknown) {
-			let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", args.action as string);
-			const texts = args.texts as string[] | undefined;
-			const ids = args.ids as number[] | undefined;
+			// TUI 渲染先于 schema 校验（args 是未经 schema 收窄的原始形态）：非对象整体
+			// 走安全占位，字段逐个 typeof/Array.isArray 守卫替代裸断言——非法形态不抛错
+			if (typeof args !== "object" || args === null) {
+				return new Text(
+					theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", "(invalid args)"),
+					0,
+					0,
+				);
+			}
+			const action = typeof args.action === "string" ? args.action : "";
+			const texts = Array.isArray(args.texts) ? args.texts : undefined;
+			const ids = Array.isArray(args.ids) ? args.ids : undefined;
+			let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", action);
 			if (texts && texts.length > 0) text += ` ${theme.fg("dim", `(${texts.length} items)`)}`;
 			if (ids && ids.length > 0) text += ` ${theme.fg("accent", `#${ids.join(", #")}`)}`;
 			if (args.id !== undefined) text += ` ${theme.fg("accent", `#${args.id}`)}`;
 			if (args.text) text += ` ${theme.fg("dim", `"${args.text}"`)}`;
-			if (args.status) text += ` ${theme.fg("warning", args.status as string)}`;
+			if (typeof args.status === "string" && args.status) text += ` ${theme.fg("warning", args.status)}`;
 			return new Text(text, 0, 0);
 		},