@zhushanwen/pi-todo 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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__/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/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";
@@ -25,75 +26,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 +76,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 +100,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 +108,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 +140,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 +178,7 @@ export function handleDelete(state: TodoSessionState, params: TodoActionParams):
 // ── Dispatcher ───────────────────────────────────────
 
 function executeTodoAction(
-	params: TodoActionParams,
+	params: TodoParamsT,
 	state: TodoSessionState,
 	ctx: ExtensionContext,
 	refreshDisplay: (ctx: ExtensionContext) => void,
@@ -296,9 +265,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) {