@zhushanwen/pi-goal 0.2.0 → 0.4.0

package/src/ports.ts

@@ -0,0 +1,68 @@
+/**
+ * Ports — 能力抽象接口
+ *
+ * D-22: ports 的核心价值是机器可检查的边界（engine/ 禁止 import Pi），
+ * 不是"可替换的 adapter"。service 层通过这些接口访问 Pi 能力，
+ * adapter 层提供实现（包装 ctx / pi）。
+ */
+
+import type { GoalRuntimeState } from "./engine/types";
+
+// ── GoalHistoryEntry（DTO，非 aggregate，D-09）─────────
+
+export interface GoalHistoryEntry {
+	goalId: string;
+	objective: string;
+	/** widget/history 标题用（fallback objective 截断）。旧 entry 无此字段。 */
+	slug?: string;
+	status: string;
+	completedTasks: number;
+	totalTasks: number;
+	elapsedSeconds: number;
+	timestamp: number;
+}
+
+// ── PersistencePort ──────────────────────────────────
+
+export interface PersistencePort {
+	/** 写入 goal-state entry（最新 1 条，GC 由 session 层管） */
+	appendState(state: GoalRuntimeState): void;
+	/** 写入 goal-history 归档 entry */
+	appendHistory(entry: GoalHistoryEntry): void;
+}
+
+// ── UiPort ───────────────────────────────────────────
+
+export interface UiPort {
+	/** 设置 widget（undefined = 清除）。hasUI=false 时 adapter 跳过（FR-6.6） */
+	setWidget(name: string, content: string[] | string | undefined): void;
+	/** 设置 status bar */
+	setStatus(name: string, text: string | undefined): void;
+	/** 弹通知 */
+	notify(text: string, level: "info" | "warning" | "error"): void;
+	/** 是否有 UI（headless/RPC mode 为 false） */
+	readonly hasUI: boolean;
+}
+
+// ── MessagingPort ────────────────────────────────────
+
+export interface MessagingPort {
+	/** 发送 custom message（goal-context 等） */
+	sendContextMessage(content: string, deliverAs: "steer" | "followUp", customType?: string): void;
+	/** 发送 user message（触发 AI 开始工作，FR-8.12） */
+	sendUserMessage(content: string, deliverAs: "steer" | "followUp"): void;
+}
+
+// ── SessionPort ──────────────────────────────────────
+
+export interface SessionEntryLike {
+	type: string;
+	customType?: string;
+	data?: unknown;
+}
+
+export interface SessionPort {
+	getEntries(): SessionEntryLike[];
+	getContextUsage(): { tokens?: number; contextWindow?: number } | null;
+	readonly signal: AbortSignal | undefined;
+}

package/src/projection/__tests__/prompts.test.ts

@@ -0,0 +1,245 @@
+/**
+ * projection/prompts.ts 测试 — prompt 生成函数 + formatBudget 4 样式
+ *
+ * 覆盖：
+ * - formatBudget 4 种 style（percent/line/remaining/report）
+ * - escapeXmlText（XML 注入防护）
+ * - continuationPrompt / budgetLimitPrompt / objectiveUpdatedPrompt / contextInjectionPrompt
+ *
+ * 全解耦后 stalenessReminderPrompt 已删（原依赖 pi.__todoGetList，跨 ext 失效）。
+ *
+ * 纯函数测试，不 import Pi SDK。
+ */
+import { describe, expect, it } from "vitest";
+
+import { createGoalState } from "../../engine/goal";
+import type { GoalRuntimeState } from "../../engine/types";
+import {
+	budgetLimitPrompt,
+	contextInjectionPrompt,
+	continuationPrompt,
+	formatBudget,
+	objectiveUpdatedPrompt,
+} from "../prompts";
+
+// ── 辅助 ─────────────────────────────────────────────
+
+function makeState(overrides?: Partial<GoalRuntimeState>): GoalRuntimeState {
+	return {
+		...createGoalState("test objective"),
+		...overrides,
+	};
+}
+
+// ── formatBudget 4 样式（FR-3.4 唯一收敛出口）────────
+
+describe("formatBudget — 4 styles (FR-3.4)", () => {
+	it("percent: Token + Time 百分比", () => {
+		const state = makeState({
+			budget: { tokenBudget: 1000, timeBudgetMinutes: 10 },
+			tokensUsed: 500,
+		});
+		const out = formatBudget(state, 300, "percent"); // 300s = 5min / 10min = 50%
+		expect(out).toContain("Token: 50%");
+		expect(out).toContain("Time: 50%");
+	});
+
+	it("percent: 无预算 → 空字符串", () => {
+		const state = makeState();
+		expect(formatBudget(state, 0, "percent")).toBe("");
+	});
+
+	it("line: 剩余/总量格式", () => {
+		const state = makeState({
+			budget: { tokenBudget: 1000, timeBudgetMinutes: 10 },
+			tokensUsed: 300,
+		});
+		const out = formatBudget(state, 120, "line"); // 120s = 2min used, 8min remaining
+		expect(out).toContain("Tokens: 700/1000");
+		expect(out).toContain("Time: 8m/10m");
+	});
+
+	it("remaining: used/total (N remaining) 格式", () => {
+		const state = makeState({
+			budget: { tokenBudget: 1000, timeBudgetMinutes: 10 },
+			tokensUsed: 400,
+		});
+		const out = formatBudget(state, 60, "remaining"); // 60s=1min used, 9min remaining
+		expect(out).toContain("Token: 400/1000 (600 remaining)");
+		expect(out).toContain("Time: 1m/10m (9m remaining)");
+	});
+
+	it("report: 多行 usage + duration", () => {
+		const state = makeState({
+			budget: { tokenBudget: 1000, timeBudgetMinutes: 10 },
+			tokensUsed: 700,
+		});
+		const out = formatBudget(state, 125, "report"); // 125s = 2m5s
+		expect(out).toContain("Token usage: 700/1000");
+		expect(out).toContain("Duration: 2m5s");
+	});
+
+	it("report: 无 token 预算 → 只有 duration", () => {
+		const state = makeState();
+		const out = formatBudget(state, 65, "report"); // 65s = 1m5s
+		expect(out).toBe("Duration: 1m5s");
+	});
+
+	it("remaining clamp: 超预算不出现负数", () => {
+		const state = makeState({
+			budget: { tokenBudget: 100, timeBudgetMinutes: 1 },
+			tokensUsed: 150, // 超 tokenBudget
+		});
+		const out = formatBudget(state, 120, "remaining"); // 120s 超 1min budget
+		expect(out).toContain("(0 remaining)"); // 不出现负数
+	});
+});
+
+// ── escapeXmlText（XML 注入防护）──────────────────────
+
+describe("XML escaping in prompts", () => {
+	it("objective 中的 <>& 被转义（continuationPrompt）", () => {
+		const state = makeState({ objective: "<script>alert('x')</script> & data" });
+		const out = continuationPrompt(state, 0);
+		expect(out).toContain("&lt;script&gt;");
+		expect(out).toContain("&amp; data");
+		expect(out).not.toContain("<script>");
+	});
+
+	it("objectiveUpdatedPrompt 转义新旧 objective", () => {
+		const state = makeState({ objective: "new <b>x</b>" });
+		const out = objectiveUpdatedPrompt(state, "old <i>y</i> & z");
+		expect(out).toContain("&lt;b&gt;x&lt;/b&gt;");
+		expect(out).toContain("&lt;i&gt;y&lt;/i&gt;");
+		expect(out).toContain("&amp; z");
+	});
+});
+
+// ── continuationPrompt ───────────────────────────────
+
+describe("continuationPrompt", () => {
+	it("含 objective + Turn + Completion audit 段落", () => {
+		const state = makeState({ currentTurnIndex: 3 });
+		const out = continuationPrompt(state, 0);
+		expect(out).toContain("Turn 3");
+		expect(out).toContain("test objective");
+		expect(out).toContain("Completion audit");
+	});
+
+	it("对标 Codex 三约束：Completion audit / Fidelity / Blocked 完整", () => {
+		const state = makeState();
+		const out = continuationPrompt(state, 0);
+		// Completion audit: 逐项证据验证
+		expect(out).toContain("Completion audit");
+		expect(out).toContain("Evidence must prove completion");
+		expect(out).toContain("are NOT evidence");
+		// Fidelity: 不缩小目标范围
+		expect(out).toContain("Fidelity");
+		expect(out).toContain("requested end state");
+		expect(out).toContain("narrower or safer solution");
+		// Blocked: 不首次就放弃
+		expect(out).toContain("Blocked");
+		expect(out).toContain("Do not report blocked the first time");
+		expect(out).toContain("try alternative approaches first");
+	});
+
+	it("软建议 complete 前完成所有 todo（FR-6，全解耦后非强制）", () => {
+		const state = makeState();
+		const out = continuationPrompt(state, 0);
+		expect(out).toContain("Recommend finishing all todos");
+		expect(out).toContain("verification todos");
+	});
+
+	it("含 plan audit 软提醒（FR-7/D27 prompt 驱动）", () => {
+		const state = makeState();
+		const out = continuationPrompt(state, 0);
+		expect(out).toContain("plan.md step was executed");
+	});
+});
+
+// ── budgetLimitPrompt ────────────────────────────────
+
+describe("budgetLimitPrompt", () => {
+	it("token 维度 → TOKEN budget 提示", () => {
+		const state = makeState({
+			budget: { tokenBudget: 1000, timeBudgetMinutes: 10 },
+			tokensUsed: 950,
+		});
+		const out = budgetLimitPrompt(state, "token", 60);
+		expect(out).toContain("TOKEN budget");
+		expect(out).toContain("Tokens used: 950 / 1000");
+		expect(out).toContain("wrap up immediately");
+	});
+
+	it("time 维度 → time budget 提示", () => {
+		const state = makeState({
+			budget: { tokenBudget: 1000, timeBudgetMinutes: 10 },
+		});
+		const out = budgetLimitPrompt(state, "time", 540); // 540s = 9m
+		expect(out).toContain("time budget");
+		expect(out).toContain("Time elapsed: 9m0s / 10 min");
+	});
+});
+
+// ── objectiveUpdatedPrompt ───────────────────────────
+
+describe("objectiveUpdatedPrompt", () => {
+	it("显示新旧 objective + 指令", () => {
+		const state = makeState({ objective: "new obj" });
+		const out = objectiveUpdatedPrompt(state, "old obj");
+		expect(out).toContain("Objective updated");
+		expect(out).toContain("Previous objective: old obj");
+		expect(out).toContain("new obj");
+		expect(out).toContain("supersedes");
+	});
+});
+
+// ── contextInjectionPrompt ───────────────────────────
+
+describe("contextInjectionPrompt", () => {
+	it("包含 objective/status/turn + 预算百分比 + 规则", () => {
+		const state = makeState({
+			status: "active",
+			currentTurnIndex: 2,
+			budget: { tokenBudget: 1000, timeBudgetMinutes: 10 },
+			tokensUsed: 200,
+		});
+		const out = contextInjectionPrompt(state, 60);
+		expect(out).toContain("GOAL mode activated");
+		expect(out).toContain("Status: active");
+		expect(out).toContain("Turn: 2");
+		expect(out).toContain("Token: 20%"); // 200/1000
+		expect(out).toContain("test objective");
+	});
+
+	it("要求建 todo（含 verification todo，FR-6/#10）", () => {
+		const state = makeState();
+		const out = contextInjectionPrompt(state, 0);
+		expect(out).toContain("todo tool");
+		expect(out).toContain("verification todos");
+		expect(out).toContain("isVerification intent");
+	});
+
+	it("无 goal_manager 引用（#1 清理后）", () => {
+		const state = makeState();
+		const out = contextInjectionPrompt(state, 0);
+		expect(out).not.toContain("goal_manager");
+		expect(out).not.toContain("create_tasks");
+		expect(out).not.toContain("add_subtasks");
+	});
+
+	it("planAvailable=false（默认）→ 不建议 plan mode（避免建议不存在的工具，FR-7）", () => {
+		const state = makeState();
+		const out = contextInjectionPrompt(state, 0, false);
+		expect(out).not.toContain("plan mode");
+		expect(out).not.toContain("__planStart");
+	});
+
+	it("planAvailable=true → 注入 plan mode 建议段落（FR-7 LLM 自主判断复杂度）", () => {
+		const state = makeState();
+		const out = contextInjectionPrompt(state, 0, true);
+		expect(out).toContain("plan mode");
+		expect(out).toContain("__planStart");
+		expect(out).toContain("Complex tasks");
+	});
+});

package/src/projection/__tests__/widget.test.ts

@@ -0,0 +1,255 @@
+/**
+ * widget.ts 测试 — projection 层渲染（TC-2）
+ *
+ * 覆盖：
+ * - toSingleLine: 多行压缩
+ * - renderStatusLine: 状态后缀 + cancelled 短路 + 预算/停滞指标
+ * - renderWidgetLines: cancelled 短路 + objective + 预算进度条
+ * - renderTerminalStatusLine: 终态单行 + cancelled 短路
+ * - updateWidget: FR-6.6 hasUI 守卫 + 终态折叠 + cancelled 清除
+ *
+ * 用 passthrough ThemeLike（fg/bold 返回原文），断言渲染逻辑而非颜色。
+ */
+import { describe, expect, it } from "vitest";
+
+import { createGoalState } from "../../engine/goal";
+import type { GoalRuntimeState } from "../../engine/types";
+import type { UiPort } from "../../ports";
+import { createGoalSession } from "../../session";
+import {
+	renderStatusLine,
+	renderTerminalStatusLine,
+	renderWidgetLines,
+	type ThemeLike,
+	toSingleLine,
+	updateWidget,
+} from "../widget";
+
+// ── Passthrough theme（断言渲染逻辑，不含颜色干扰）────
+
+const theme: ThemeLike = {
+	fg: (_color: string, text: string) => text,
+	bold: (text: string) => text,
+};
+
+// ── 辅助 ─────────────────────────────────────────────
+
+function makeState(overrides?: Partial<GoalRuntimeState>): GoalRuntimeState {
+	return {
+		...createGoalState("test objective"),
+		status: "active",
+		...overrides,
+	};
+}
+
+// ── toSingleLine ─────────────────────────────────────
+
+describe("toSingleLine", () => {
+	it("多行 → 空格分隔单行 + 去首尾空白（不折叠连续空格）", () => {
+		expect(toSingleLine("hello\nworld")).toBe("hello world");
+		expect(toSingleLine("a\nb\nc")).toBe("a b c");
+		expect(toSingleLine("  trimmed  ")).toBe("trimmed");
+	});
+	it("单行原样返回（trim）", () => {
+		expect(toSingleLine("  single  ")).toBe("single");
+	});
+});
+
+// ── renderStatusLine ─────────────────────────────────
+
+describe("renderStatusLine", () => {
+	it("cancelled → 空字符串（短路）", () => {
+		expect(renderStatusLine(makeState({ status: "cancelled" }), theme)).toBe("");
+	});
+
+	it("active 状态：标题用 slug（fallback objective）+ turn 计数", () => {
+		const text = renderStatusLine(makeState({ status: "active", currentTurnIndex: 3 }), theme);
+		// 无 slug 时 fallback 到 objective 截断
+		expect(text).toContain("◆ test objective");
+		expect(text).toContain("Turn 3"); // currentTurnIndex
+	});
+
+	it("active 状态有 slug → 标题用 slug", () => {
+		const text = renderStatusLine(
+			makeState({ status: "active", slug: "refactor-auth", currentTurnIndex: 2 }),
+			theme,
+		);
+		expect(text).toContain("◆ refactor-auth");
+		expect(text).not.toContain("test objective"); // slug 优先，objective 不显示
+	});
+
+	it("无预算 → 显示已消耗绝对值（token + time）", () => {
+		const text = renderStatusLine(
+			makeState({ status: "active", tokensUsed: 12000, timeUsedSeconds: 90 }),
+			theme,
+		);
+		expect(text).toContain("12k tokens"); // formatTokens 缩写
+		expect(text).toContain("1m30s"); // formatMinutes
+	});
+
+	it("blocked → 含 ⊘ Blocked 后缀", () => {
+		const text = renderStatusLine(makeState({ status: "blocked" }), theme);
+		expect(text).toContain("⊘ Blocked");
+	});
+
+	it("paused → 含 ⏸ Paused 后缀", () => {
+		const text = renderStatusLine(makeState({ status: "paused" }), theme);
+		expect(text).toContain("⏸ Paused");
+	});
+
+	it("complete → 含 ✓ Completed 后缀", () => {
+		const text = renderStatusLine(makeState({ status: "complete" }), theme);
+		expect(text).toContain("✓ Completed");
+	});
+
+	it("budget_limited → 含 ⊗ Token budget exhausted 后缀", () => {
+		const text = renderStatusLine(makeState({ status: "budget_limited" }), theme);
+		expect(text).toContain("⊗ Token budget exhausted");
+	});
+
+	it("time_limited → 含 ⏱ Time budget exhausted 后缀", () => {
+		const text = renderStatusLine(makeState({ status: "time_limited" }), theme);
+		expect(text).toContain("⏱ Time budget exhausted");
+	});
+
+	it("tokenBudget > 0 → 显示 token 百分比", () => {
+		const text = renderStatusLine(
+			makeState({
+				status: "active",
+				budget: { tokenBudget: 1000, timeBudgetMinutes: 0 },
+				tokensUsed: 500,
+			}),
+			theme,
+		);
+		expect(text).toContain("50% tokens");
+	});
+});
+
+// ── renderTerminalStatusLine ─────────────────────────
+
+describe("renderTerminalStatusLine", () => {
+	it("cancelled → 空字符串", () => {
+		expect(renderTerminalStatusLine(makeState({ status: "cancelled" }), theme)).toBe("");
+	});
+
+	it("complete → 含 ✓ Completed", () => {
+		const text = renderTerminalStatusLine(makeState({ status: "complete" }), theme);
+		expect(text).toContain("✓ Completed");
+	});
+
+	it("budget_limited → 含 ⊗ Token budget exhausted", () => {
+		const text = renderTerminalStatusLine(makeState({ status: "budget_limited" }), theme);
+		expect(text).toContain("⊗ Token budget exhausted");
+	});
+});
+
+// ── renderWidgetLines ────────────────────────────────
+
+describe("renderWidgetLines", () => {
+	it("cancelled → 空数组", () => {
+		expect(renderWidgetLines(makeState({ status: "cancelled" }), theme)).toEqual([]);
+	});
+
+	it("active → 不含 objective 全文行（精简，slug 作标题）", () => {
+		const lines = renderWidgetLines(makeState({ status: "active" }), theme);
+		// GAP-8: 移除 Objective 全文行（slug 已作标题）
+		expect(lines.some((l) => l.includes("Objective:"))).toBe(false);
+	});
+
+	it("active 无 slug → 标题 fallback objective 截断", () => {
+		const lines = renderWidgetLines(makeState({ status: "active" }), theme);
+		expect(lines[0]).toContain("◆ test objective");
+	});
+
+	it("tokenBudget + timeBudget → 含进度条行（used/total 格式）", () => {
+		const lines = renderWidgetLines(
+			makeState({
+				status: "active",
+				budget: { tokenBudget: 1000, timeBudgetMinutes: 30 },
+				tokensUsed: 250,
+				timeUsedSeconds: 540, // 9 min
+			}),
+			theme,
+		);
+		// 新格式：进度条 + used/total（缩写）
+		expect(lines.some((l) => l.includes("Token:") && l.includes("250/1k"))).toBe(true);
+		expect(lines.some((l) => l.includes("Time:") && l.includes("9m/30min"))).toBe(true);
+	});
+
+	it("无预算 → 显示已消耗绝对值行（no budget）", () => {
+		const lines = renderWidgetLines(
+			makeState({ status: "active", tokensUsed: 5000, timeUsedSeconds: 120 }),
+			theme,
+		);
+		expect(lines.some((l) => l.includes("5k used (no budget)"))).toBe(true);
+		expect(lines.some((l) => l.includes("2m elapsed (no budget)"))).toBe(true);
+	});
+});
+
+// ── updateWidget（FR-6.6 hasUI 守卫）─────────────────
+
+describe("updateWidget (FR-6.6 hasUI guard)", () => {
+	interface RecordedCall {
+		method: "setWidget" | "setStatus";
+		args: unknown[];
+	}
+
+	function makeUiPort(hasUI: boolean): { ui: UiPort; calls: RecordedCall[] } {
+		const calls: RecordedCall[] = [];
+		const ui = {
+			hasUI,
+			setWidget(name: string, content: unknown) {
+				calls.push({ method: "setWidget", args: [name, content] });
+			},
+			setStatus(name: string, text: unknown) {
+				calls.push({ method: "setStatus", args: [name, text] });
+			},
+			notify() {},
+			fg: (_color: string, text: string) => text,
+			bold: (text: string) => text,
+		} as UiPort;
+		return { ui, calls };
+	}
+
+	it("hasUI=false → 不调 setWidget/setStatus（headless 守卫）", () => {
+		const { ui, calls } = makeUiPort(false);
+		const session = createGoalSession();
+		session.state = makeState({ status: "active" });
+		updateWidget(session, ui);
+		expect(calls).toHaveLength(0); // FR-6.6
+	});
+
+	it("session.state=null → 清除 widget + status", () => {
+		const { ui, calls } = makeUiPort(true);
+		updateWidget(createGoalSession(), ui);
+		expect(calls.some((c) => c.method === "setWidget" && c.args[1] === undefined)).toBe(true);
+		expect(calls.some((c) => c.method === "setStatus" && c.args[1] === undefined)).toBe(true);
+	});
+
+	it("cancelled → 清除 widget + status", () => {
+		const { ui, calls } = makeUiPort(true);
+		const session = createGoalSession();
+		session.state = makeState({ status: "cancelled" });
+		updateWidget(session, ui);
+		expect(calls.some((c) => c.method === "setWidget" && c.args[1] === undefined)).toBe(true);
+		expect(calls.some((c) => c.method === "setStatus" && c.args[1] === undefined)).toBe(true);
+	});
+
+	it("终态（非 cancelled）→ setStatus 终态单行 + setWidget undefined", () => {
+		const { ui, calls } = makeUiPort(true);
+		const session = createGoalSession();
+		session.state = makeState({ status: "complete" });
+		updateWidget(session, ui);
+		expect(calls.some((c) => c.method === "setStatus" && typeof c.args[1] === "string")).toBe(true);
+		expect(calls.some((c) => c.method === "setWidget" && c.args[1] === undefined)).toBe(true);
+	});
+
+	it("active → setStatus + setWidget（正常渲染）", () => {
+		const { ui, calls } = makeUiPort(true);
+		const session = createGoalSession();
+		session.state = makeState({ status: "active" });
+		updateWidget(session, ui);
+		expect(calls.some((c) => c.method === "setStatus" && typeof c.args[1] === "string")).toBe(true);
+		expect(calls.some((c) => c.method === "setWidget" && Array.isArray(c.args[1]))).toBe(true);
+	});
+});