@zhushanwen/pi-todo 0.7.1 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.7.1",
+  "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__/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

@@ -16,7 +16,6 @@ import { type Static, Type } from "typebox";
 
 import {
 	addTodos,
-	buildGui,
 	formatTodoList,
 	type Todo,
 	type TodoDetails,
@@ -222,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,