@zhushanwen/pi-goal 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Codex-style /goal command for Pi — persistent goal-driven autonomous loop with evidence-based completion, token/time budgets, blocked detection, and steering templates.",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/goal-control-adapter.test.ts

@@ -106,6 +106,14 @@ describe("handleComplete — active 守卫 + evidence + finalizeAndPersist", ()
 			handleComplete({ action: "complete", evidence: "   " }, session, makeFakePorts()),
 		).toThrow(/evidence/);
 	});
+
+	it("evidence undefined → throw（schema 降级后 handler 唯一兜底：'required' 错误）", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		expect(() => handleComplete({ action: "complete" }, session, makeFakePorts())).toThrow(
+			/evidence.*required/,
+		);
+	});
 });
 
 // ── handleCreate ─────────────────────────────────────
@@ -142,6 +150,13 @@ describe("handleCreate — slug+objective 必填 + 非终态守卫 + createGoal"
 		).toThrow(/objective/);
 	});
 
+	it("objective undefined → throw（schema 降级后 handler 唯一兜底：'required' 错误）", () => {
+		const session = createGoalSession();
+		expect(() => handleCreate({ action: "create", successCriteria: "y" }, session, makeFakePorts())).toThrow(
+			/objective.*required/,
+		);
+	});
+
 	it("successCriteria 空 → throw（即使有 slug + objective）", () => {
 		const session = createGoalSession();
 		expect(() =>
@@ -153,6 +168,13 @@ describe("handleCreate — slug+objective 必填 + 非终态守卫 + createGoal"
 		).toThrow(/successCriteria/);
 	});
 
+	it("successCriteria undefined → throw（schema 降级后 handler 唯一兜底：'required' 错误）", () => {
+		const session = createGoalSession();
+		expect(() => handleCreate({ action: "create", objective: "x" }, session, makeFakePorts())).toThrow(
+			/successCriteria.*required/,
+		);
+	});
+
 	const NON_TERMINAL_STATUSES: GoalRuntimeState["status"][] = ["active", "paused", "blocked"];
 	it.each(NON_TERMINAL_STATUSES)("已有 %s goal → throw（D25 非终态守卫）", (status) => {
 		const session = createGoalSession();
@@ -250,4 +272,12 @@ describe("handleReportBlocked — active 守卫 + tick + transition + persist",
 			handleReportBlocked({ action: "report_blocked", reason: "" }, session, makeFakePorts()),
 		).toThrow(/reason/);
 	});
+
+	it("reason undefined → throw（schema 降级后 handler 唯一兜底：'required' 错误）", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		expect(() => handleReportBlocked({ action: "report_blocked" }, session, makeFakePorts())).toThrow(
+			/reason.*required/,
+		);
+	});
 });

package/src/__tests__/goal-control-prompt.test.ts

@@ -92,3 +92,20 @@ describe("goal_control 描述修正（A1/slug optional）", () => {
 		expect(ADAPTER_SRC).not.toMatch(/'slug' is required/);
 	});
 });
+
+describe("goal_control budget 默认策略锁定（S-8：三层信号冗余，防回滚无声）", () => {
+	// 新增的 budget-policy prompt 文本散落在三处（description 段 / promptGuidelines 项 /
+	// tokenBudget 参数 description），任一处被回滚都应触发测试失败——这是 prompt-lock 的核心诉求。
+	it("description 模板含中文 '默认不设 tokenBudget' 预算策略段", () => {
+		expect(DESCRIPTION).toContain("默认不设 tokenBudget");
+	});
+
+	it("promptGuidelines budget 项含英文 'never set tokenBudget on your own initiative'", () => {
+		expect(ADAPTER_SRC).toContain("never set tokenBudget on your own initiative");
+	});
+
+	it("tokenBudget 参数 description 含 '默认不设' + '切勿自行决定设置预算'", () => {
+		// 参数 schema description 是第三层信号（与上面两层对齐，三层冗余，见 adapter 源码注释）
+		expect(ADAPTER_SRC).toMatch(/tokenBudget:[\s\S]*?默认不设[\s\S]*?切勿自行决定设置预算/);
+	});
+});

package/src/__tests__/schema.test.ts

@@ -1,17 +1,30 @@
 /**
- * goal_control schema — discriminated union 校验测试（TC6 / CT3）
+ * goal_control schema — 扁平 Object 校验测试（OpenAI 兼容）
  *
- * schema 为 Type.Union（无 discriminator keyword）+ 各分支 additionalProperties:false，
- * 以 action literal 区分分支。pi 生产校验器为 typebox/compile 的 Compile(schema).Check(args)，
- * 与此处 Value.Check 同源（同一 typebox schema 语义），故用 Value.Check 验证拒绝行为。
+ * schema 为扁平 Type.Object + action 字段级 Type.Union（等价 enum）+ 各字段 Optional +
+ * additionalProperties:false。OpenAI function calling 要求 parameters 顶层 type:"object"，
+ * 顶层 Type.Union 序列化后只有 anyOf 无 type 字段，会被严格 OpenAI 兼容网关 400 拒绝
+ * 整个会话——故采用扁平结构（范式对齐 scheduler ScheduleControlParams）。
+ *
+ * typebox schema 对象即序列化形态：GoalControlParams.type 就是发往 provider 的 JSON 顶层 type。
+ * pi 生产校验器为 typebox/compile 的 Compile(schema).Check(args)，与此处 Value.Check 同源，
+ * 故用 Value.Check 验证。
+ *
+ * 分支隔离从 schema 层降级为运行时 handler 字段存在性校验（见 goal-control-adapter.test.ts）。
  */
 import { describe, expect, it } from "vitest";
 import { Value } from "typebox/value";
 
 import { GoalControlParams } from "../adapters/goal-control-adapter";
 
-describe("GoalControlParams — discriminated union（TC6）", () => {
-	// valid：各分支完整 + optional 字段 → 通过
+describe("GoalControlParams — 扁平 Object（OpenAI 兼容）", () => {
+	// 顶层合规：序列化形态顶层必须有 type:"object"，不得有 anyOf（否则被严格网关 400 拒绝）
+	it("顶层 type === 'object' 且无 anyOf（OpenAI function calling 合规）", () => {
+		expect(GoalControlParams.type).toBe("object");
+		expect(GoalControlParams.anyOf).toBeUndefined();
+	});
+
+	// valid：各 action 完整 + optional 字段 → 通过
 	it.each([
 		["create 完整", { action: "create", objective: "x", successCriteria: "y" }],
 		["create + slug", { action: "create", slug: "refactor-auth", objective: "x", successCriteria: "y" }],
@@ -22,16 +35,19 @@ describe("GoalControlParams — discriminated union（TC6）", () => {
 		expect(Value.Check(GoalControlParams, params)).toBe(true);
 	});
 
-	// invalid：缺必填 / 额外字段（additionalProperties:false 代表性用例）/ 分支隔离 / 未知 action
+	// 关键语义变更：扁平化后所有声明的字段（含跨 action 的）均为 Optional，
+	// schema 不再做分支隔离。{action:"complete", evidence, objective} 放行
+	// （objective 是声明的 Optional 字段，schema 层无法区分它属于哪个 action）。
+	// 分支隔离降级为运行时 handler 字段存在性校验，见 goal-control-adapter.test.ts。
+	it("跨 action 字段（complete + objective）现在通过（分支隔离降级为运行时校验）", () => {
+		expect(Value.Check(GoalControlParams, { action: "complete", evidence: "x", objective: "leak" })).toBe(true);
+	});
+
+	// invalid：缺 action / 未知 action / 额外字段（additionalProperties:false）
 	it.each([
-		["create 缺 objective", { action: "create", successCriteria: "y" }],
-		["create 缺 successCriteria", { action: "create", objective: "x" }],
+		["缺 action", { objective: "x", successCriteria: "y" }],
+		["未知 action（不在 union 内）", { action: "unknown" }],
 		["create 含额外字段（additionalProperties:false）", { action: "create", objective: "x", successCriteria: "y", foo: 1 }],
-		["create 含 complete 分支字段 evidence（分支隔离）", { action: "create", objective: "x", successCriteria: "y", evidence: "leak" }],
-		["complete 缺 evidence", { action: "complete" }],
-		["report_blocked 缺 reason", { action: "report_blocked" }],
-		["未知 action", { action: "unknown" }],
-		["缺 action", { objective: "x" }],
 	])("invalid: %s → 拒绝", (_name, params) => {
 		expect(Value.Check(GoalControlParams, params)).toBe(false);
 	});

package/src/adapters/goal-control-adapter.ts

@@ -19,10 +19,12 @@
  * create 不调 sendUserMessage：toolcall 时 AI 已在 turn 中，返回结果后自行续跑
  * （与 /goal set 的 followUp 触发区分；对齐 Codex create_goal 不自动续跑）。
  *
- * schema：discriminated union（C3）——Type.Union 无 discriminator keyword，各分支以
- * action literal 区分 + additionalProperties:false。pi 生产校验器为 typebox/compile
- * 的 Compile(schema).Check(args)，缺失必填字段在 schema 层即被拒绝；execute 内仅保留
- * .trim() 空字符串校验（LLM 可能传空串穿透 schema）。
+ * schema：扁平 Type.Object（OpenAI 兼容，C3）——parameters 顶层必须是 type:"object"，
+ * 顶层 Type.Union 序列化后只有 anyOf 无 type，会被严格 OpenAI 兼容网关 400 拒绝。故采用
+ * 扁平 Object + action 字段级 Type.Union（等价 enum）+ 各字段 Optional + additionalProperties:false。
+ * 分支隔离从 schema 层降级为运行时 handler 字段存在性校验（见各 handler 开头）；
+ * pi 生产校验器为 typebox/compile 的 Compile(schema).Check(args)，缺失/错误 action、额外字段
+ * 在 schema 层拒绝，缺必填字段由 handler 校验兜底。
  *
  * executionMode: "sequential"——状态变更 tool，不可与同批其他 tool 并行执行。
  *
@@ -46,62 +48,61 @@ import { buildPorts } from "./ports";
 // ── Params schema（discriminated union，C3）────────────
 
 /**
- * goal_control 参数 schema。三分支以 action literal 区分（无 discriminator keyword），
- * 各分支 additionalProperties:false，缺失必填在 schema 层拒绝。
+ * goal_control 参数 schema。扁平 Type.Object + action 字段级 Type.Union（等价 enum）。
+ *
+ * OpenAI function calling 规范要求 parameters 顶层必须是 type:"object"；顶层 Type.Union
+ * 序列化后只有 anyOf 无 type 字段，会被严格的 OpenAI 兼容网关 400 拒绝整个会话。故采用
+ * 扁平 Object + action enum，分支隔离从 schema 层降级为运行时 handler 字段存在性校验
+ * （见各 handler 开头）。范式对齐 scheduler ScheduleControlParams。
+ *
+ * additionalProperties:false 阻挡未知字段；缺失/错误 action 仍由 schema 层拒绝。
  */
-const CreateParams = Type.Object(
+export const GoalControlParams = Type.Object(
 	{
-		action: Type.Literal("create"),
+		action: Type.Union(
+			[Type.Literal("create"), Type.Literal("complete"), Type.Literal("report_blocked")],
+			{ description: "create | complete | report_blocked" },
+		),
 		slug: Type.Optional(
 			Type.String({
 				description: "可选。状态栏标题用的短 kebab-case 标识，仅用于显示，不注入 prompt。",
 			}),
 		),
-		objective: Type.String({
-			description:
+		objective: Type.Optional(
+			Type.String({
+				description:
 				"必填。用你自己的话重述真实目标——用户实际想要达成什么，而非字面复述请求。模糊时推断最可能的意图并明确陈述。",
-		}),
-		successCriteria: Type.String({
-			description:
+			}),
+		),
+		successCriteria: Type.Optional(
+			Type.String({
+				description:
 				"必填。可检查的完成条件（如「测试通过」「文件 X 存在且含内容 Y」「命令 Z 输出 W」），不是愿景或「能用就行」。这是 complete 前必须逐条满足的门槛。",
-		}),
+			}),
+		),
 		tokenBudget: Type.Optional(
 			Type.Number({
-				description: "可选。新目标的 token 预算（正数）。除非用户指定，否则省略。",
+				description:
+					"可选。新目标的 token 预算（正数）。默认不设——仅在用户明确要求（如「控制在 1 万 token 内」）或你已获得用户明确同意时才设。切勿自行决定设置预算。",
 			}),
 		),
-	},
-	{ additionalProperties: false },
-);
-
-const CompleteParams = Type.Object(
-	{
-		action: Type.Literal("complete"),
-		evidence: Type.String({
-			description:
+		evidence: Type.Optional(
+			Type.String({
+				description:
 				"必填。具体完成证据（改动/新建的文件、通过的测试、运行的命令）。不要基于假设、意图或部分进度标记完成。",
-		}),
-	},
-	{ additionalProperties: false },
-);
-
-const ReportBlockedParams = Type.Object(
-	{
-		action: Type.Literal("report_blocked"),
-		reason: Type.String({
-			description:
+			}),
+		),
+		reason: Type.Optional(
+			Type.String({
+				description:
 				"必填。具体阻塞条件及已尝试的方案。不要用于不确定、困难、缓慢或未完成的工作——继续做。",
-		}),
+			}),
+		),
 	},
 	{ additionalProperties: false },
 );
 
-export const GoalControlParams = Type.Union([CreateParams, CompleteParams, ReportBlockedParams]);
-
-export type CreateActionParams = Static<typeof CreateParams>;
-export type CompleteActionParams = Static<typeof CompleteParams>;
-export type ReportBlockedActionParams = Static<typeof ReportBlockedParams>;
-export type GoalControlActionParams = Static<typeof GoalControlParams>;
+export type GoalControlParamsT = Static<typeof GoalControlParams>;
 
 // ── Details（renderResult 数据来源）──────────────────
 
@@ -131,13 +132,16 @@ export interface GoalControlDetails {
  * 终态旧 goal 走 createGoal 快速路径覆盖（createGoal 内部 active 守卫，终态可覆盖）。
  */
 export function handleCreate(
-	params: CreateActionParams,
+	params: GoalControlParamsT,
 	session: GoalSession,
 	ports: ServicePorts,
 ): GoalControlDetails {
+	if (params.objective === undefined) {
+		throw new Error("'objective' required for create. Correct: {\"action\":\"create\",\"objective\":\"...\",\"successCriteria\":\"...\"}");
+	}
 	const objective = params.objective.trim();
 	if (!objective) {
-		// schema 已挡缺失，此处仅挡空串（LLM 可能传空串穿透 schema）
+		// schema 已放行（扁平化后 optional），此处挡空串（LLM 可能传空串）
 		throw new Error(
 			"'objective' must not be empty. Describe the concrete objective to pursue. Correct: {\"action\":\"create\",\"slug\":\"<kebab-case>\",\"objective\":\"<concrete objective>\",\"successCriteria\":\"<checkable conditions>\"}",
 		);
@@ -145,6 +149,9 @@ export function handleCreate(
 	// slug 真 optional（TC11）：缺失时 fallback goalId 截断（与 buildGoalGui 口径一致），不强制必填
 	const slugInput = params.slug?.trim();
 
+	if (params.successCriteria === undefined) {
+		throw new Error("'successCriteria' required for create. Correct: {\"action\":\"create\",\"objective\":\"...\",\"successCriteria\":\"...\"}");
+	}
 	const successCriteria = params.successCriteria.trim();
 	if (!successCriteria) {
 		throw new Error(
@@ -192,7 +199,7 @@ export function handleCreate(
  * 全解耦后不再做 todo 完成前置检查——todo 是否全完成由 AI 自行判断（prompt 软建议）。
  */
 export function handleComplete(
-	params: CompleteActionParams,
+	params: GoalControlParamsT,
 	session: GoalSession,
 	ports: ServicePorts,
 ): GoalControlDetails {
@@ -201,6 +208,9 @@ export function handleComplete(
 	if (!isActiveStatus(state.status)) {
 		throw new Error(`Goal is not active (status: ${state.status}). Only an active goal can be completed.`);
 	}
+	if (params.evidence === undefined) {
+		throw new Error("'evidence' required for complete. Correct: {\"action\":\"complete\",\"evidence\":\"...\"}");
+	}
 	const evidence = params.evidence.trim();
 	if (!evidence) {
 		throw new Error(
@@ -223,7 +233,7 @@ export function handleComplete(
  * 否则转 blocked 后 persistState 内部的 tick 因 status≠active 不累加，丢失最后一段运行时间。
  */
 export function handleReportBlocked(
-	params: ReportBlockedActionParams,
+	params: GoalControlParamsT,
 	session: GoalSession,
 	ports: ServicePorts,
 ): GoalControlDetails {
@@ -232,6 +242,9 @@ export function handleReportBlocked(
 	if (state.status !== "active") {
 		throw new Error(`Goal is not active (status: ${state.status}). Only an active goal can report_blocked.`);
 	}
+	if (params.reason === undefined) {
+		throw new Error("'reason' required for report_blocked. Correct: {\"action\":\"report_blocked\",\"reason\":\"...\"}");
+	}
 	const reason = params.reason.trim();
 	if (!reason) {
 		throw new Error(
@@ -268,6 +281,8 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 		label: "Goal Control",
 		description: `管理当前会话的目标（goal）。目标用于追踪需要完成验证的复杂工作。
 
+预算策略：默认不设 tokenBudget。仅在用户明确要求（如「控制在 1 万 token 内」）或用户的指令明确暗示了一个限制时才设。若你认为应该设预算但用户从未提及，先询问用户获得明确同意，切勿自行决定。
+
 动作：
 - create：为复杂的多步骤工作（3+ 步骤、多文件改动、或需要完成验证的工作）主动创建目标。用自己的话重述真实目标，定义可检查的 successCriteria（完成条件）。琐碎的单步任务、普通提问、查找类任务不要创建目标。若已有 active/paused/blocked 目标会失败——请让用户运行 /goal resume 或 /goal clear 后再创建。
 - complete：标记当前 active 目标完成。需要 evidence（具体证据：改动的文件、通过的测试、运行的命令），且必须满足每条 successCriteria 条件。若有预算，在总结里报告最终 token 用量。不要基于假设、意图或部分进度标记完成。
@@ -287,6 +302,9 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 			// create：主动用于复杂多步骤任务。翻转原「显式启动」策略——让 goal 真正可用。
 			// 门槛：3+ 步骤 / 多文件 / 需完成验证，避免对琐碎任务滥建 goal 变噪音。
 			"create: proactively start a goal for complex, multi-step work (3+ steps, multi-file, or needs completion verification) — restate the real objective and define checkable successCriteria. Do NOT create for trivial single-step tasks, ordinary lookups, or when a goal is already active. Test: 'is this worth tracking to completion with verification?' — if yes, create a goal.",
+			// budget：默认不设预算——仅当用户显式要求（或明确同意）时才设。
+			// 对齐 description 的预算策略段 + tokenBudget 参数的 description（三层信号冗余）。
+			"budget: never set tokenBudget on your own initiative — the default is no budget. Set a budget only when the user explicitly requested one (e.g. \"keep it under 10k tokens\") or you obtained explicit user consent first. If you think a budget is warranted but the user never mentioned one, ask the user before creating the goal.",
 			// 全解耦下 todo 非硬前置——objective 实际达成才算（与 handleComplete「todo 由 AI 自判」一致）
 			"complete: proactively call when the active goal's objective is actually achieved, not merely in progress. Evidence must be concrete artifacts (files changed, tests green, commands run) meeting every successCriteria condition. Finishing all todos (incl. verification todos) is the usual readiness signal, but the real bar is the objective being met — you decide.",
 			// ≥3 distinct approaches 或同一 blocker 跨连续 turns（T7）；达到阈值后报告，不反复报告同一 blocker
@@ -297,7 +315,7 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 
 		async execute(
 			_toolCallId: string,
-			params: GoalControlActionParams,
+			params: GoalControlParamsT,
 			signal: AbortSignal | undefined,
 			_onUpdate: unknown,
 			ctx: ExtensionContext,
@@ -317,13 +335,14 @@ export function registerGoalControlTool(pi: ExtensionAPI, session: GoalSession):
 				details = handleReportBlocked(params, session, ports);
 			}
 
-			// 用 params.action 判断（TS 据此收窄 params 到对应分支，安全访问 objective/reason）
+			// 扁平化后 params.objective/reason 为 string|undefined（schema 不再按 action 收窄）；
+			// handler 已对必填字段做存在性校验，此处用 ?. 兜底，未定义时空串
 			const text =
 				params.action === "create"
-					? `Goal created.\nGoal ID: ${details.goalId}\nSlug: ${details.slug ?? ""}\nObjective: ${params.objective.trim()}`
+					? `Goal created.\nGoal ID: ${details.goalId}\nSlug: ${details.slug ?? ""}\nObjective: ${params.objective?.trim() ?? ""}`
 					: params.action === "complete"
 						? `Goal completed.\nGoal ID: ${details.goalId}`
-						: `Goal reported blocked.\nGoal ID: ${details.goalId}\nReason: ${params.reason.trim()}`;
+						: `Goal reported blocked.\nGoal ID: ${details.goalId}\nReason: ${params.reason?.trim() ?? ""}`;
 
 			// RPC 模式下附加 __gui__（用展开避免 details 来自 frozen 对象时加字段失败）
 			if (ctx.mode === "rpc" && session.state) {