@zhushanwen/pi-todo 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "AI-driven todo list for Pi — stateful task management with session persistence and /todos command.",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/gui.test.ts

@@ -2,8 +2,8 @@ import { describe, expect, it } from "vitest";
 
 import { buildGui, type Todo } from "../model";
 
-describe("buildGui", () => {
-	it("maps 3 statuses to list-tree with correct icons", () => {
+describe("buildGui（v1.1 meta head 架构）", () => {
+	it("内容根 = numbered list-tree：行首序号由 ListTree 渲染，label 纯文本（无 #N 前缀）", () => {
 		const todos: Todo[] = [
 			{ id: 1, text: "pending task", status: "pending" },
 			{ id: 2, text: "active task", status: "in_progress" },
@@ -12,20 +12,54 @@ describe("buildGui", () => {
 		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 → 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 });
+		// 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 });
 	});
 
-	it("empty todos → empty list-tree", () => {
-		const gui = buildGui([]);
-		expect(gui.component.props.items).toEqual([]);
+	it("meta：title=Todo，progress=current/total 计数（head 渲染，body 不再有 progress-bar）", () => {
+		const todos: Todo[] = [
+			{ id: 1, text: "a", status: "completed" },
+			{ id: 2, text: "b", status: "in_progress" },
+			{ id: 3, text: "c", status: "pending" },
+		];
+		const gui = buildGui(todos);
+		expect(gui.meta).toEqual({
+			title: "Todo",
+			status: "running",
+			progress: { current: 1, total: 3 },
+		});
+	});
+
+	it("全部完成 → meta.status=done", () => {
+		const todos: Todo[] = [
+			{ id: 1, text: "a", status: "completed" },
+			{ id: 2, text: "b", status: "completed" },
+		];
+		expect(buildGui(todos).meta).toEqual({
+			title: "Todo",
+			status: "done",
+			progress: { current: 2, total: 2 },
+		});
 	});
 
+	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 },
+		});
+		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([]);
+	});
 });

package/src/__tests__/schema.test.ts

@@ -1,10 +1,13 @@
-// Schema 强约束回归（T4/TC3/TC4）：TodoParams 为 discriminated union（按 action），
-// 每个分支只声明自己的参数且 additionalProperties:false。用 typebox 的 Value.Check
-// 验证：缺失必填、多余字段、已删除的 action 都在 schema 层被拒绝，不依赖运行时 throw。
+// Schema 顶层合规回归（OpenAI function calling：parameters 顶层必须是 type:"object"，
+// 顶层 union 会被严格网关 400 拒绝整个会话启动）。
 //
-// 选 Value.Check 而非 ajv：typebox 自带 Value 校验器与其 schema 语义一致；
-// spike 确认 Value.Check 与 plain ajv 对本 schema 的拒绝结论一致（ajv 的
-// discriminator:true 选项会编译失败，故不依赖该选项）。
+// 扁平化后 TodoParams 是单一 Type.Object + action 字段级 union（参考 scheduler 的
+// ScheduleControlParams）。语义变更：所有非 action 字段都是 Optional，缺失必填
+// （如 {action:'add'} 缺 texts、delete 缺 ids）不再被 schema 拒绝——改由 handler 运行时
+// 校验（见 tool-detectors.test.ts）。schema 仍强约束：action 枚举、status 枚举、
+// additionalProperties:false（拒绝未知字段）。
+//
+// 选 Value.Check 而非 ajv：typebox 自带 Value 校验器与其 schema 语义一致。
 
 import { describe, expect, it } from "vitest";
 
@@ -12,9 +15,21 @@ import { Value } from "typebox/value";
 
 import { TodoParams } from "../tool";
 
-describe("TodoParams discriminated union schema", () => {
+describe("TodoParams 扁平 schema（顶层 type:object 合规）", () => {
+	describe("顶层合规（OpenAI function calling）", () => {
+		it("type === object（非顶层 union）", () => {
+			expect(TodoParams.type).toBe("object");
+		});
+		it("无顶层 anyOf（discriminated union 已消除）", () => {
+			expect(TodoParams.anyOf).toBeUndefined();
+		});
+		it("additionalProperties: false", () => {
+			expect(TodoParams.additionalProperties).toBe(false);
+		});
+	});
+
 	describe("合法 payload 通过", () => {
-		it("list（无参）", () => {
+		it("list", () => {
 			expect(Value.Check(TodoParams, { action: "list" })).toBe(true);
 		});
 		it("add + texts", () => {
@@ -31,34 +46,18 @@ describe("TodoParams discriminated union schema", () => {
 		});
 	});
 
-	describe("TC4: 缺失必填被 schema 拒绝", () => {
-		it("add 缺 texts", () => {
-			expect(Value.Check(TodoParams, { action: "add" })).toBe(false);
-		});
-		it("update 缺 id 且缺 updates", () => {
-			expect(Value.Check(TodoParams, { action: "update" })).toBe(false);
-		});
-		it("delete 缺 ids", () => {
-			expect(Value.Check(TodoParams, { action: "delete" })).toBe(false);
+	describe("action 枚举强约束", () => {
+		it("缺 action 被拒绝", () => {
+			expect(Value.Check(TodoParams, {})).toBe(false);
 		});
-	});
-
-	describe("TC3: 已删除的 clear action 被拒绝", () => {
-		it("clear 不在 action 枚举内", () => {
+		it("未知 action（clear 不在 union 内）被拒绝", () => {
 			expect(Value.Check(TodoParams, { action: "clear" })).toBe(false);
 		});
 	});
 
-	describe("额外属性被拒绝（additionalProperties:false）", () => {
-		it("TC7: add 同时传 text+texts（text 是多余字段）→ 拒绝", () => {
-			// schema 层拒绝双形陷阱；handler 层另有 defense-in-depth throw（见 tool-detectors）
-			expect(Value.Check(TodoParams, { action: "add", texts: ["y"], text: "x" })).toBe(false);
-		});
-		it("list 携带多余 texts → 拒绝", () => {
-			expect(Value.Check(TodoParams, { action: "list", texts: ["x"] })).toBe(false);
-		});
-		it("update 单条携带多余 ids → 拒绝", () => {
-			expect(Value.Check(TodoParams, { action: "update", id: 1, ids: [1] })).toBe(false);
+	describe("额外字段被拒绝（additionalProperties:false）", () => {
+		it("list 携带未知字段 foo → 拒绝", () => {
+			expect(Value.Check(TodoParams, { action: "list", foo: 1 })).toBe(false);
 		});
 	});
 
@@ -66,11 +65,24 @@ describe("TodoParams discriminated union schema", () => {
 		it("合法三态 status 通过", () => {
 			expect(Value.Check(TodoParams, { action: "update", id: 1, status: "completed" })).toBe(true);
 		});
-		it("TC2: cancelled 不再合法", () => {
+		it("cancelled 不在 VALID_STATUSES → 拒绝", () => {
 			expect(Value.Check(TodoParams, { action: "update", id: 1, status: "cancelled" })).toBe(false);
 		});
-		it("非法 status 被拒绝", () => {
+		it("非法 status → 拒绝", () => {
 			expect(Value.Check(TodoParams, { action: "update", id: 1, status: "banana" })).toBe(false);
 		});
 	});
+
+	describe("缺失必填 / 双形陷阱降级为 handler 运行时校验", () => {
+		// 扁平化后 {action:"add"} 缺 texts 不再被 schema 拒绝（texts 是 Optional）。
+		// 必填报错改由 handler 运行时校验，见 tool-detectors.test.ts。
+		it("{action:'add'} 缺 texts → schema 放行（handler 校验）", () => {
+			expect(Value.Check(TodoParams, { action: "add" })).toBe(true);
+		});
+		// 双形陷阱（add 同时传 text+texts）从 schema 层降级为运行时 handler 检测，
+		// 见 tool-detectors.test.ts。
+		it("{action:'add', texts:['y'], text:'x'} 双形 → schema 放行（handler 检测）", () => {
+			expect(Value.Check(TodoParams, { action: "add", texts: ["y"], text: "x" })).toBe(true);
+		});
+	});
 });

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

@@ -14,7 +14,7 @@
 import { describe, expect, it } from "vitest";
 
 import { createTodoSessionState } from "../state";
-import { handleAdd, handleDelete } from "../tool";
+import { handleAdd, handleDelete, handleSingleUpdate } from "../tool";
 
 describe("handleAdd — text/texts dual-form detection", () => {
   it("triggers dual-form error when singular 'text' used instead of 'texts'", () => {
@@ -66,3 +66,17 @@ describe("handleDelete — id/ids dual-form detection", () => {
     expect(() => handleDelete(state, { action: "delete", ids: [1] })).not.toThrow();
   });
 });
+
+describe("handleSingleUpdate — id/status/text required guards", () => {
+  it("throws 'requires id' when id missing", () => {
+    const state = createTodoSessionState();
+    expect(() => handleSingleUpdate(state, { action: "update" })).toThrow(/requires id/);
+  });
+
+  it("throws 'at least status or text' when id given but status+text missing", () => {
+    const state = createTodoSessionState();
+    expect(() => handleSingleUpdate(state, { action: "update", id: 1 })).toThrow(
+      /at least status or text/,
+    );
+  });
+});

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

@@ -1,31 +1,33 @@
 /**
- * executeTodoAction handler 级测试 —— 覆盖 `if (ctx.mode === "rpc")` 分支
- * 和非 RPC 模式不附加 __gui__ 的路径。对齐 ask-user R-1~R-7 handler 级范式。
+ * executeTodoAction handler 级测试 —— M17 后的两条路径：
+ * 1. tool result 无 __gui__（全模式统一——状态展示不再进 details）
+ * 2. refreshDisplay GUI widget 推送（rpc 推 marker 编码 / tui 推纯文本行）
  *
  * 策略：executeTodoAction 未导出，通过 registerTodoTool + mock pi 捕获
- * 已注册 tool，再以不同 ctx.mode 调 execute。每个用例新建 state（隔离），
- * 无模块级状态需重置。
+ * 已注册 tool，再以不同 ctx.mode 调 execute。setup 第三参传真实
+ * makeRefreshDisplay(state)（与 index.ts 工厂共用同一实现，不测复制品）。
+ * 每个用例新建 state（隔离），无模块级状态需重置。
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { describe, expect, it } from "vitest";
+import { GUI_WIDGET_MARKER } from "@xyz-agent/extension-protocol";
+import { describe, expect, it, vi, type Mock } from "vitest";
 
+import { makeRefreshDisplay } from "../index";
 import { createTodoSessionState, type TodoSessionState } from "../state";
 import { registerTodoTool } from "../tool";
 
 // ── Types for the registered tool ───────────────────────
 type TestMode = "tui" | "rpc" | "json" | "print";
 
+type SetWidgetFn = (name: string, content: string[] | undefined) => void;
+
 interface ExecuteResult {
 	content: Array<{ type: "text"; text: string }>;
 	details: {
 		action: string;
 		todos: Array<{ id: number; text: string; status: string }>;
 		nextId: number;
-		__gui__?: {
-			v: number;
-			component: { type: string; props: { items: unknown[] } };
-		};
 	};
 }
 
@@ -47,7 +49,7 @@ interface MockPi {
 	registerTool(tool: RegisteredTool): void;
 }
 
-/** 捕获注册的 tool，返回 + 暴露 state 供断言。 */
+/** 捕获注册的 tool，返回 + 暴露 state 供断言。refreshDisplay 传真实实现（makeRefreshDisplay）。 */
 function setup(): { tool: RegisteredTool; state: TodoSessionState } {
 	const state = createTodoSessionState();
 	const pi: MockPi = {
@@ -55,7 +57,7 @@ function setup(): { tool: RegisteredTool; state: TodoSessionState } {
 			this.tool = tool;
 		},
 	};
-	registerTodoTool(pi as unknown as ExtensionAPI, state, () => {});
+	registerTodoTool(pi as unknown as ExtensionAPI, state, makeRefreshDisplay(state));
 	if (!pi.tool) throw new Error("registerTodoTool did not register a tool");
 	return { tool: pi.tool, state };
 }
@@ -76,95 +78,65 @@ const stubTheme = {
 	getBashModeBorderColor: () => (text: string) => text,
 } as unknown as Theme;
 
-/** RPC 模式 ctx：hasUI=false，refreshDisplay 调用 ui.theme/setStatus/setWidget。 */
-const makeRpcCtx = () => ({
-	mode: "rpc" as const,
-	hasUI: false,
-	ui: {
-		theme: stubTheme,
-		setStatus: () => {},
-		setWidget: () => {},
-	},
-});
+/** 构造指定 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> } };
+	setWidget: Mock<SetWidgetFn>;
+} {
+	const setWidget = vi.fn<SetWidgetFn>();
+	return {
+		ctx: {
+			mode,
+			hasUI,
+			ui: { theme: stubTheme, setStatus: vi.fn(), setWidget },
+		},
+		setWidget,
+	};
+}
+
+/** RPC 模式 ctx：hasUI=false。 */
+const makeRpcCtx = () => makeCtx("rpc", false);
 
 /** TUI 模式 ctx：hasUI=true。 */
-const makeTuiCtx = () => ({
-	mode: "tui" as const,
-	hasUI: true,
-	ui: {
-		theme: stubTheme,
-		setStatus: () => {},
-		setWidget: () => {},
-	},
-});
+const makeTuiCtx = () => makeCtx("tui", true);
+
+// ── tool result：无 __gui__（M17 后全模式统一）─────────
 
-// ── RPC 模式：附加 __gui__ ────────────────────────────
+describe("executeTodoAction — tool result 无 __gui__（全模式）", () => {
+	const MODES: TestMode[] = ["rpc", "tui", "json", "print"];
 
-describe("executeTodoAction — RPC mode attaches __gui__", () => {
-	it("R-1: rpc + add → details.__gui__ exists, type is list-tree", async () => {
+	it.each(MODES)("%s + add → details 无 __gui__ 字段，仍含 action/todos/nextId", async (mode) => {
 		const { tool } = setup();
 		const result = await tool.execute(
 			"id",
-			{ action: "add", texts: ["task A", "task B"] },
+			{ action: "add", texts: ["task A"] },
 			undefined,
 			undefined,
-			makeRpcCtx(),
+			makeCtx(mode, mode === "tui").ctx,
 		);
-		expect(result.details.__gui__).toBeDefined();
-		expect(result.details.__gui__!.v).toBe(1);
-		expect(result.details.__gui__!.component.type).toBe("list-tree");
-		// 两条新增 todo 反映在 items 中
-		const items = result.details.__gui__!.component.props.items as Array<{
-			label: string;
-			icon: string;
-		}>;
-		expect(items).toHaveLength(2);
-		expect(items[0]).toMatchObject({ label: "#1: task A", icon: "dot" });
-		expect(items[1]).toMatchObject({ label: "#2: task B", icon: "dot" });
+		expect("__gui__" in result.details).toBe(false);
+		// details 仍带原生文本路径数据（todos / nextId）
+		expect(result.details.action).toBe("add");
+		expect(result.details.todos).toHaveLength(1);
+		expect(result.content[0].text).toContain("Added");
 	});
 
-	it("R-2: rpc + list → __gui__ reflects current todo state", async () => {
+	it.each(MODES)("%s + list → details 无 __gui__ 字段，文本内容可读", async (mode) => {
 		const { tool, state } = setup();
-		// 预置状态（绕开 add，直接构造 todos）
-		state.todos = [
-			{ id: 1, text: "pending task", status: "pending" },
-			{ id: 2, text: "active task", status: "in_progress" },
-			{ id: 3, text: "done task", status: "completed" },
-		];
-		state.nextId = 4;
+		state.todos = [{ id: 1, text: "x", status: "pending" }];
+		state.nextId = 2;
 		const result = await tool.execute(
 			"id",
 			{ action: "list" },
 			undefined,
 			undefined,
-			makeRpcCtx(),
+			makeCtx(mode, mode === "tui").ctx,
 		);
-		expect(result.details.__gui__).toBeDefined();
-		expect(result.details.__gui__!.component.type).toBe("list-tree");
-		const items = result.details.__gui__!.component.props.items as Array<{
-			label: string;
-			icon: string;
-			status?: string;
-		}>;
-		expect(items).toHaveLength(3);
-		// pending → dot 无 status
-		expect(items[0]).toMatchObject({ label: "#1: pending task", icon: "dot" });
-		expect(items[0]).not.toHaveProperty("status");
-		// in_progress → circle / running
-		expect(items[1]).toMatchObject({
-			label: "#2: active task",
-			icon: "circle",
-			status: "running",
-		});
-		// completed → check / done
-		expect(items[2]).toMatchObject({
-			label: "#3: done task",
-			icon: "check",
-			status: "done",
-		});
+		expect("__gui__" in result.details).toBe(false);
+		expect(result.content[0].text).toContain("#1");
 	});
 
-	it("R-3: rpc + update → __gui__ reflects post-update status", async () => {
+	it("rpc + update → details 无 __gui__ 字段，状态变更仍生效", async () => {
 		const { tool, state } = setup();
 		state.todos = [{ id: 1, text: "item", status: "pending" }];
 		state.nextId = 2;
@@ -173,82 +145,76 @@ describe("executeTodoAction — RPC mode attaches __gui__", () => {
 			{ action: "update", updates: [{ id: 1, status: "in_progress" }] },
 			undefined,
 			undefined,
-			makeRpcCtx(),
+			makeRpcCtx().ctx,
 		);
-		expect(result.details.__gui__).toBeDefined();
-		const items = result.details.__gui__!.component.props.items as Array<{
-			icon: string;
-			status?: string;
-		}>;
-		expect(items[0]).toMatchObject({ icon: "circle", status: "running" });
+		expect("__gui__" in result.details).toBe(false);
+		expect(result.details.todos[0]!.status).toBe("in_progress");
 	});
 });
 
-// ── TUI 模式：不附加 __gui__ ──────────────────────────
+// ── refreshDisplay：GUI widget 推送（M17，真实实现）────
 
-describe("executeTodoAction — non-RPC modes omit __gui__", () => {
-	it("T-1: tui + add → details.__gui__ is undefined", async () => {
+describe("refreshDisplay — GUI widget 推送（setup 传真实实现）", () => {
+	it("G-1: rpc + add → setWidget 收到 ('todo', [GUI_WIDGET_MARKER + JSON])，解析后为 v1.1 信封（list-tree + meta）", async () => {
 		const { tool } = setup();
-		const result = await tool.execute(
-			"id",
-			{ action: "add", texts: ["task A"] },
-			undefined,
-			undefined,
-			makeTuiCtx(),
-		);
-		expect(result.details.__gui__).toBeUndefined();
-		// details 仍带原生文本路径数据（todos / nextId）
-		expect(result.details.todos).toHaveLength(1);
-		expect(result.content[0].text).toContain("Added");
-	});
-
-	it("T-2: tui + list → details.__gui__ is undefined", async () => {
-		const { tool, state } = setup();
-		state.todos = [{ id: 1, text: "x", status: "pending" }];
-		state.nextId = 2;
-		const result = await tool.execute(
+		const { ctx, setWidget } = makeRpcCtx();
+		await tool.execute(
 			"id",
-			{ action: "list" },
+			{ action: "add", texts: ["task A", "task B"] },
 			undefined,
 			undefined,
-			makeTuiCtx(),
+			ctx,
 		);
-		expect(result.details.__gui__).toBeUndefined();
-		// 文本内容仍可读
-		expect(result.content[0].text).toContain("#1");
+		expect(setWidget).toHaveBeenCalledTimes(1);
+		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(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 } });
 	});
 
-	it("T-3: print mode + add → details.__gui__ is undefined", async () => {
+	it("G-2: rpc + delete 清空列表 → setWidget 收到 ('todo', undefined)（清除语义）", async () => {
 		const { tool } = setup();
-		const result = await tool.execute(
-			"id",
-			{ action: "add", texts: ["task A"] },
-			undefined,
-			undefined,
-			{ mode: "print", hasUI: false, ui: { theme: stubTheme, setStatus: () => {}, setWidget: () => {} } },
-		);
-		expect(result.details.__gui__).toBeUndefined();
+		const { ctx, setWidget } = makeRpcCtx();
+		await tool.execute("id", { action: "add", texts: ["only"] }, undefined, undefined, ctx);
+		await tool.execute("id", { action: "delete", ids: [1] }, undefined, undefined, ctx);
+		expect(setWidget).toHaveBeenLastCalledWith("todo", undefined);
 	});
 
-	it("T-4: json mode + add → details.__gui__ is undefined", async () => {
+	it("G-3: tui + add → setWidget 收到纯文本行数组（无 marker 前缀）", async () => {
 		const { tool } = setup();
-		const result = await tool.execute(
-			"id",
-			{ action: "add", texts: ["task A"] },
-			undefined,
-			undefined,
-			{ mode: "json", hasUI: false, ui: { theme: stubTheme, setStatus: () => {}, setWidget: () => {} } },
-		);
-		expect(result.details.__gui__).toBeUndefined();
+		const { ctx, setWidget } = makeTuiCtx();
+		await tool.execute("id", { action: "add", texts: ["task A"] }, undefined, undefined, ctx);
+		expect(setWidget).toHaveBeenCalledTimes(1);
+		const [, value] = setWidget.mock.calls[0]!;
+		expect(value!.length).toBeGreaterThan(0);
+		for (const line of value!) {
+			// isGuiCapable 外层判定生效：TUI 行不含 GUI marker 编码
+			expect(line.startsWith(GUI_WIDGET_MARKER)).toBe(false);
+		}
 	});
 });
 
-// ── 共享 state：rpc 附加但 details.todos 是快照副本 ────
+// ── 共享 state：details.todos 是快照副本 ───────────────
 
 describe("executeTodoAction — state isolation & snapshot", () => {
 	it("S-1: each setup() yields independent state (no module-level leak)", async () => {
 		const { tool: tool1 } = setup();
-		await tool1.execute("id", { action: "add", texts: ["first"] }, undefined, undefined, makeRpcCtx());
+		await tool1.execute("id", { action: "add", texts: ["first"] }, undefined, undefined, makeRpcCtx().ctx);
 		// 第二个 setup 起步，不应看到第一个的 todos
 		const { tool: tool2, state: state2 } = setup();
 		expect(state2.todos).toHaveLength(0);
@@ -257,29 +223,26 @@ describe("executeTodoAction — state isolation & snapshot", () => {
 			{ action: "list" },
 			undefined,
 			undefined,
-			makeRpcCtx(),
+			makeRpcCtx().ctx,
 		);
 		expect(result.content[0].text).toBe("No todos");
-		// 空 list 仍走 buildGui([])（rpc 分支无条件 attach）
-		expect(result.details.__gui__).toBeDefined();
-		expect(result.details.__gui__!.component.props.items).toEqual([]);
 	});
 
 	it("S-2: details.todos is a shallow array copy (splice-safe, element-shared)", async () => {
 		// executeTodoAction 用 [...state.todos] 做浅拷贝：数组独立、元素共享。
 		// add/delete 改数组长度时旧 details.todos 不受影响；但原地改元素会共享。
 		const { tool } = setup();
-		await tool.execute("id", { action: "add", texts: ["a", "b"] }, undefined, undefined, makeRpcCtx());
+		await tool.execute("id", { action: "add", texts: ["a", "b"] }, undefined, undefined, makeRpcCtx().ctx);
 		const before = (await tool.execute(
 			"id",
 			{ action: "list" },
 			undefined,
 			undefined,
-			makeRpcCtx(),
+			makeRpcCtx().ctx,
 		)).details.todos;
 		expect(before).toHaveLength(2);
 		// delete 改 state.todos 数组，已发出的 before 快照仍为 2 项
-		await tool.execute("id", { action: "delete", ids: [1, 2] }, undefined, undefined, makeRpcCtx());
+		await tool.execute("id", { action: "delete", ids: [1, 2] }, undefined, undefined, makeRpcCtx().ctx);
 		expect(before).toHaveLength(2);
 	});
 });

package/src/index.ts

@@ -14,20 +14,54 @@
  * - render.ts:   状态栏（status line）/ widget（单双列自适应）/ tool result 三层渲染
  * - component.ts: /todos 命令的 TodoListComponent TUI 视图（只读双列）
  * - commands.ts: /todos 命令注册
- * - index.ts（本文件）: 工厂入口（创建 state + 注册 tool/command/event + refreshDisplay）
+ * - index.ts（本文件）: 工厂入口（创建 state + 注册 tool/command/event + makeRefreshDisplay）
  *
  * 错误处理：handler 失败直接 throw（见 CLAUDE.md「Tool 设计」），不返回错误成功模式。
  * model 层纯函数返回 Result 对象（合法），dispatcher 拿到 error 时 throw。
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { guiSetWidget, isGuiCapable, type GuiContext } from "@xyz-agent/extension-protocol";
 
 import { registerTodosCommand } from "./commands";
 import { registerTodoEventHandlers } from "./handlers";
+import { buildGui } from "./model";
 import { renderStatusText, renderWidgetLines } from "./render";
-import { createTodoSessionState } from "./state";
+import { createTodoSessionState, type TodoSessionState } from "./state";
 import { registerTodoTool } from "./tool";
 
+// ── 刷新显示（导出供测试，生产路径与测试共用同一实现）──────
+
+/**
+ * 构造依赖 TodoSessionState 的 refreshDisplay（M17 widget 面板推送）。
+ *
+ * 类型断言根因：pi 的 ExtensionContext.ui.custom 是泛型方法，参数逆变使其
+ * 与 GuiContext 不兼容，直接传参需断言收窄；双步 unknown 中转沿用 goal
+ * adapters/ports.ts setGuiWidget 同款先例。
+ *
+ * isGuiCapable 外层判定不可省略：guiSetWidget 内部无 isGui 守卫
+ * （extension-protocol helpers.ts 仅查 ctx.ui?.setWidget 存在性），
+ * TUI 模式误调会把 marker 编码行推给原生 widget 造成乱码。
+ */
+export function makeRefreshDisplay(state: TodoSessionState): (ctx: ExtensionContext) => void {
+	return function refreshDisplay(ctx: ExtensionContext): void {
+		const statusText = renderStatusText(state.todos, ctx.ui.theme);
+		ctx.ui.setStatus("todo", statusText || undefined);
+		const isGui = isGuiCapable(ctx as unknown as GuiContext);
+		if (state.todos.length === 0) {
+			if (isGui) {
+				guiSetWidget(ctx as unknown as GuiContext, "todo", undefined);
+			} else {
+				ctx.ui.setWidget("todo", undefined);
+			}
+		} else if (isGui) {
+			guiSetWidget(ctx as unknown as GuiContext, "todo", buildGui(state.todos));
+		} else {
+			ctx.ui.setWidget("todo", renderWidgetLines(state.todos, ctx.ui.theme));
+		}
+	};
+}
+
 // ── 扩展入口 ─────────────────────────────────────────
 
 export default function (pi: ExtensionAPI) {
@@ -37,16 +71,7 @@ export default function (pi: ExtensionAPI) {
 	// 全解耦：不再暴露 pi.__todoGetList 跨扩展 API（goal 不再读 todo 状态）。
 	// todo 进度由 AI 自行管理，goal 不做强制检查。
 
-	// ── 刷新显示（依赖闭包 state） ─────────────────────
-	function refreshDisplay(ctx: ExtensionContext): void {
-		const statusText = renderStatusText(state.todos, ctx.ui.theme);
-		ctx.ui.setStatus("todo", statusText || undefined);
-		if (state.todos.length === 0) {
-			ctx.ui.setWidget("todo", undefined);
-		} else {
-			ctx.ui.setWidget("todo", renderWidgetLines(state.todos, ctx.ui.theme));
-		}
-	}
+	const refreshDisplay = makeRefreshDisplay(state);
 
 	// ── 注册所有 handler / tool / command ──────────────
 	registerTodoEventHandlers(pi, state, refreshDisplay);

package/src/model.ts

@@ -3,7 +3,13 @@
  * 三态: pending → in_progress → completed
  */
 
-import { guiComponent, type GuiRenderResult, guiResult, type TreeItem } from "@xyz-agent/extension-protocol";
+import {
+	type GuiRenderResult,
+	guiComponent,
+	guiResult,
+	type TreeItem,
+	type WidgetMeta,
+} from "@xyz-agent/extension-protocol";
 
 // ── 数据模型 ─────────────────────────────────────────
 
@@ -17,8 +23,6 @@ export interface TodoDetails {
 	action: "list" | "add" | "update" | "delete";
 	todos: Todo[];
 	nextId: number;
-	/** GUI 渲染结果（仅 RPC 模式填充，前端 list-tree 渲染）。对齐 extension-protocol@0.2.0。 */
-	__gui__?: GuiRenderResult;
 }
 
 export const VALID_STATUSES = ["pending", "in_progress", "completed"] as const;
@@ -67,34 +71,46 @@ export function migrateTodo(raw: unknown): Todo {
 // ── GUI 渲染辅助 ─────────────────────────────────────
 
 /**
- * 把 todos 映射为 list-tree GuiRenderResult（对齐 extension-protocol@0.2.0）。
- * status → icon/status 映射：
- *   pending      → dot      / 无 status
- *   in_progress  → circle   / running
- *   completed    → check    / done
+ * 把 todos 组装为 GuiRenderResult（v1.1 meta head 架构，对齐 extension-protocol@0.3.0）。
+ *
+ * - meta（标题/状态/进度）由宿主壳层渲染成唯一 head：进度计数 "N/M" + mini bar
+ *   替代 body 内 progress-bar（精简 body），全完成 status=done（head 绿点 + bar 变绿）。
+ * - 内容根 = numbered list-tree：行首弱化序号（编辑器行号范式，ListTree 渲染），
+ *   id 不再烧进 label——update/delete 锚点由模型经 list action 获取，用户引用
+ *   「第 N 项」即可；状态由行尾圆点单一表达（无 icon，v6 单一信息源裁决）。
+ *
+ * status → 圆点映射：
+ *   pending      → 无圆点（常态归零）
+ *   in_progress  → running（accent）
+ *   completed    → done（success + label 弱化）
  */
 export function buildGui(todos: Todo[]): GuiRenderResult {
-	const items: TreeItem[] = todos.map((t) => {
-		const icon =
-			t.status === "completed"
-				? "check"
-				: t.status === "in_progress"
-					? "circle"
-					: "dot"; // pending
-		const status =
+	const total = todos.length;
+	const completed = todos.filter((t) => t.status === "completed").length;
+	const inProgress = todos.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
-		return {
-			icon,
-			label: `#${t.id}: ${t.text}`,
+					: undefined, // pending 无 status
+		depth: 0,
+	}));
+
+	return guiResult(
+		guiComponent("list-tree", { numbered: true, items }),
+		{
+			title: "Todo",
 			status,
-			depth: 0,
-		};
-	});
-	return guiResult(guiComponent("list-tree", { items }));
+			progress: total > 0 ? { current: completed, total } : undefined,
+		},
+	);
 }
 
 export function getDisplayStatus(t: Todo): string {

package/src/tool.ts

@@ -1,11 +1,12 @@
 /**
  * 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 会编译失败）。
+ * Schema 设计（OpenAI 兼容）：TodoParams 为扁平 Type.Object（顶层 type:"object"，
+ * 满足 OpenAI function calling 规范——顶层 union 会被严格网关 400 拒绝整个会话启动）。
+ * action 字段是字面量 union（list/add/update/delete），其余字段全 Optional；必填校验
+ * （add 缺 texts、delete 缺 ids、双形陷阱 text/texts、id/ids）由 handler 运行时承担
+ * （见 tool-detectors.test.ts）。范式参考 scheduler 的 ScheduleControlParams；设计
+ * 文档见 docs/extensions/tool-schema-openai-compat.md。
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -15,7 +16,6 @@ import { type Static, Type } from "typebox";
 
 import {
 	addTodos,
-	buildGui,
 	formatTodoList,
 	type Todo,
 	type TodoDetails,
@@ -25,75 +25,43 @@ import {
 import { renderTodoResult } from "./render";
 import type { TodoSessionState } from "./state";
 
-// ── 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;
-	text?: string;
-	id?: number;
-	texts?: string[];
-	ids?: number[];
-	status?: string;
-	updates?: Array<{ id: number; status?: string; text?: string }>;
-}
-
-// ── TodoParams schema（discriminated union by action）──────────
+// ── TodoParams schema（扁平 Type.Object，OpenAI 兼容）──────────
+// 顶层必须是 type:"object"（OpenAI function calling 规范——顶层 union 会被严格
+// 网关 400 拒绝）。action 字段是字面量 union；其余字段全 Optional，必填校验交给
+// handler（见 tool-detectors.test.ts）。TodoParamsT 由 schema 派生，handler 签名
+// 统一用它——双形陷阱检测在全 optional 类型上语义不变，且能消除 execute 里的 cast。
 
 const StatusSchema = StringEnum(VALID_STATUSES);
 
-const ListParams = Type.Object(
-	{ action: Type.Literal("list") },
-	{ additionalProperties: false },
-);
-const AddParams = Type.Object(
+export const TodoParams = 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),
+		action: Type.Union(
+			[Type.Literal("list"), Type.Literal("add"), Type.Literal("update"), Type.Literal("delete")],
+			{ description: "list | add | update | delete" },
+		),
 		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）" },
+		texts: Type.Optional(Type.Array(Type.String(), { description: "待添加的 todo 文本数组" })),
+		id: Type.Optional(Type.Number({ description: "要更新的 todo id" })),
+		ids: Type.Optional(Type.Array(Type.Number(), { description: "要删除的 todo id 数组" })),
+		status: Type.Optional(StatusSchema),
+		updates: Type.Optional(
+			Type.Array(
+				Type.Object(
+					{
+						id: Type.Number({ description: "要更新的 todo id" }),
+						status: Type.Optional(StatusSchema),
+						text: Type.Optional(Type.String({ description: "新文本（trim 后不可为空）" })),
+					},
+					{ additionalProperties: false },
+				),
+				{ 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,
-]);
+export type TodoParamsT = Static<typeof TodoParams>;
 
 // ── 4 个 action handler ──────────────────────────────
 // 错误处理约定（见 CLAUDE.md「Tool 设计」）：handler 失败直接 throw，
@@ -107,7 +75,7 @@ function handleList(state: TodoSessionState): string {
 }
 
 /** add action — 失败抛错。export 供 behavioral 测试（text/texts 双形陷阱检测）。 */
-export function handleAdd(state: TodoSessionState, params: TodoActionParams): string {
+export function handleAdd(state: TodoSessionState, params: TodoParamsT): 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"');
@@ -131,7 +99,7 @@ export function handleAdd(state: TodoSessionState, params: TodoActionParams): st
 }
 
 /** update action: batch — 失败抛错 */
-function handleBatchUpdate(state: TodoSessionState, params: TodoActionParams): string {
+function handleBatchUpdate(state: TodoSessionState, params: TodoParamsT): string {
 	const r = updateTodos(state.todos, params.updates ?? []);
 	if (r.error) throw new Error(r.resultText);
 	state.todos = r.updatedTodos;
@@ -139,7 +107,7 @@ function handleBatchUpdate(state: TodoSessionState, params: TodoActionParams): s
 }
 
 /** update action: single — 失败抛错 */
-export function handleSingleUpdate(state: TodoSessionState, params: TodoActionParams): string {
+export function handleSingleUpdate(state: TodoSessionState, params: TodoParamsT): string {
 	if (params.id === undefined)
 		throw new Error(
 			'update requires id parameter. Correct: {"action":"update","id":<n>,"status":"in_progress"}',
@@ -171,14 +139,14 @@ export function handleSingleUpdate(state: TodoSessionState, params: TodoActionPa
 }
 
 /** update action: dispatcher — batch 优先于 single */
-function handleUpdate(state: TodoSessionState, params: TodoActionParams): string {
+function handleUpdate(state: TodoSessionState, params: TodoParamsT): string {
 	if (params.updates && params.updates.length > 0) return handleBatchUpdate(state, params);
 	return handleSingleUpdate(state, params);
 }
 
 /** delete action — 失败抛错；部分 id 缺失则整体拒绝（原子性）。
  * export 供 behavioral 测试（id/ids 双形陷阱检测）。 */
-export function handleDelete(state: TodoSessionState, params: TodoActionParams): string {
+export function handleDelete(state: TodoSessionState, params: TodoParamsT): string {
 	if (!params.ids || params.ids.length === 0) {
 		// 双形陷阱：弱模型 delete 时误用单数 id（那是 update 的字段）
 		if (params.id !== undefined) {
@@ -209,7 +177,7 @@ export function handleDelete(state: TodoSessionState, params: TodoActionParams):
 // ── Dispatcher ───────────────────────────────────────
 
 function executeTodoAction(
-	params: TodoActionParams,
+	params: TodoParamsT,
 	state: TodoSessionState,
 	ctx: ExtensionContext,
 	refreshDisplay: (ctx: ExtensionContext) => void,
@@ -253,11 +221,8 @@ function executeTodoAction(
 		todos: [...state.todos],
 		nextId: state.nextId,
 	};
-	// RPC 模式（xyz-agent GUI）附加 __gui__，前端按 list-tree 渲染。
-	// TUI/print/json 模式走原生文本渲染（contentText 已在 content 中）。
-	if (ctx.mode === "rpc") {
-		details.__gui__ = buildGui(state.todos);
-	}
+	// 状态展示不再进 tool result（GUI 渲染字段已移除）：GUI 走 refreshDisplay 的
+	// guiSetWidget 推送（M17 widget 面板），TUI 走原生文本渲染（contentText 已在 content 中）。
 	return {
 		content: [{ type: "text" as const, text: contentText }],
 		details,
@@ -296,9 +261,9 @@ export function registerTodoTool(
 		executionMode: "sequential",
 		parameters: TodoParams,
 
-		async execute(_toolCallId: string, params: Static<typeof TodoParams>, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
+		async execute(_toolCallId: string, params: TodoParamsT, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
 			if (signal?.aborted) throw new Error("Todo call aborted by signal.");
-			return executeTodoAction(params as TodoActionParams, state, ctx, refreshDisplay);
+			return executeTodoAction(params, state, ctx, refreshDisplay);
 		},
 
 		renderCall(args: Record<string, unknown>, theme: Theme, _context?: unknown) {