@zhushanwen/pi-goal 0.1.0

package/src/state.ts

@@ -0,0 +1,231 @@
+/**
+ * Goal 状态定义和管理
+ *
+ * 状态机参考 Codex /goal 的 6 种状态：
+ *   Active → Paused (用户暂停)
+ *   Active → Blocked (连续 stall)
+ *   Active → Complete (目标达成)
+ *   Active → BudgetLimited (token 预算耗尽)
+ *   Active → TimeLimited (时间预算耗尽)
+ *   Active → Cancelled (用户清除)
+ *
+ * 终态（不可被任何状态覆盖）：Complete, BudgetLimited, TimeLimited, Cancelled
+ * Paused/Blocked 可被 Active 覆盖（用户 resume）
+ */
+
+import { MS_PER_SECOND } from "./constants";
+
+// ── Goal 状态枚举 ──────────────────────────────────────
+
+export type GoalStatus =
+	| "active"
+	| "paused"
+	| "blocked"
+	| "complete"
+	| "budget_limited"
+	| "time_limited"
+	| "cancelled";
+
+// 终态：不可被其他状态覆盖
+const TERMINAL_STATUSES: ReadonlySet<GoalStatus> = new Set([
+	"complete",
+	"budget_limited",
+	"time_limited",
+	"cancelled",
+]);
+
+// ── 任务数据结构 ──────────────────────────────────────
+
+export type TaskStatus = "pending" | "in_progress" | "completed" | "cancelled";
+
+export type SubtaskStatus = "pending" | "in_progress" | "completed";
+
+export const SUBTASK_STATUSES: readonly SubtaskStatus[] = [
+	"pending",
+	"in_progress",
+	"completed",
+] as const;
+
+export interface Subtask {
+	id: number;
+	text: string;
+	status: SubtaskStatus;
+	lastUpdatedTurn: number;
+}
+
+export const GOAL_TASK_STATUSES: readonly TaskStatus[] = [
+	"pending",
+	"in_progress",
+	"completed",
+	"cancelled",
+] as const;
+
+export function isTerminalTaskStatus(status: TaskStatus): boolean {
+	return status === "completed" || status === "cancelled";
+}
+
+export interface GoalTask {
+	id: number;
+	description: string;
+	status: TaskStatus;
+	evidence?: string; // 完成时的证据描述
+	subtasks?: Subtask[];
+	lastUpdatedTurn: number;
+}
+
+// ── 预算配置 ──────────────────────────────────────────
+
+export interface BudgetConfig {
+	tokenBudget?: number; // token 预算上限 (undefined = 不限制)
+	timeBudgetMinutes?: number; // 时间预算 (分钟, undefined = 不限制)
+	maxStallTurns: number; // 连续无进展轮数阈值，触发 blocked
+	maxTurns: number; // 最大 turn 数上限
+}
+
+// ── 运行时状态（也是持久化数据格式，保持统一）─────────────
+
+export interface GoalRuntimeState {
+	goalId: string;
+	objective: string;
+	status: GoalStatus;
+	tasks: GoalTask[];
+	turnCount: number;
+	stallCount: number;
+	tokensUsed: number;
+	timeStartedAt: number; // Date.now() timestamp
+	timeUsedSeconds: number; // 累计使用秒数（不含当前活跃段）
+	budget: BudgetConfig;
+	lastProgressTurn: number; // 上次有进展的 turn number
+	budgetLimitSteeringSent: boolean; // 是否已发送预算耗尽 steering
+	objectiveUpdatedAt: number; // objective 最后更新时间
+	lastBlockerReason: string | null; // 上次 report_blocked 的原因，resume 时注入
+	budgetWarning70Sent: boolean; // 70% 预算预警已发送（token 或时间任一达 70%）
+	budgetWarning90Sent: boolean; // 90% 预算预警已发送
+	lastTurnTokensUsed: number; // 上一 turn 结束时的 tokensUsed，用于去抖检测
+	currentTurnIndex: number;                    // turn_end 粒度计数器
+	completedAtTurnIndex?: number;               // 进入终态时的 currentTurnIndex
+}
+
+// ── 默认值 ────────────────────────────────────────────
+
+export const DEFAULT_BUDGET: BudgetConfig = {
+	maxStallTurns: 5,
+	maxTurns: 50,
+};
+
+export function createInitialState(objective: string, budget: Partial<BudgetConfig> = {}): GoalRuntimeState {
+	return {
+		goalId: crypto.randomUUID(),
+		objective,
+		status: "active",
+		tasks: [],
+		turnCount: 0,
+		stallCount: 0,
+		tokensUsed: 0,
+		timeStartedAt: Date.now(),
+		timeUsedSeconds: 0,
+		budget: { ...DEFAULT_BUDGET, ...budget },
+		lastProgressTurn: 0,
+		budgetLimitSteeringSent: false,
+		objectiveUpdatedAt: Date.now(),
+		lastBlockerReason: null,
+		budgetWarning70Sent: false,
+		budgetWarning90Sent: false,
+		lastTurnTokensUsed: 0,
+		currentTurnIndex: 0,
+		completedAtTurnIndex: undefined,
+	};
+}
+
+// ── 状态转换 ──────────────────────────────────────────
+
+/**
+ * 安全的状态转换。终态不可被覆盖。
+ */
+export function transitionStatus(current: GoalStatus, next: GoalStatus): GoalStatus {
+	if (TERMINAL_STATUSES.has(current)) return current;
+	return next;
+}
+
+export function isTerminalStatus(status: GoalStatus): boolean {
+	return TERMINAL_STATUSES.has(status);
+}
+
+export function isActiveStatus(status: GoalStatus): boolean {
+	return status === "active";
+}
+
+// ── 序列化（直接用相同类型，避免维护两个相同接口）──────
+
+export function serializeState(state: GoalRuntimeState): GoalRuntimeState {
+	return {
+		...state,
+		tasks: state.tasks.map((t) => ({
+			...t,
+			subtasks: t.subtasks?.map((s) => ({ ...s })),
+		})),
+		budget: { ...state.budget },
+	};
+}
+
+/**
+ * 反序列化，补全缺失字段的默认值（向后兼容旧格式数据）
+ */
+export function deserializeState(data: Record<string, unknown>): GoalRuntimeState {
+	return {
+		goalId: (data.goalId as string) ?? "",
+		objective: (data.objective as string) ?? "",
+		status: (data.status as GoalStatus) ?? "active",
+		tasks: ((data.tasks as Record<string, unknown>[]) ?? []).map((t: Record<string, unknown>) => {
+		if (!("status" in t)) {
+			throw new Error("Legacy goal-state format detected, session reset required");
+		}
+		const rawSubtasks = (t.subtasks ?? t.subTodos) as Record<string, unknown>[] | undefined;
+		const subtasks = Array.isArray(rawSubtasks)
+			? rawSubtasks
+					.filter((s) => typeof s.id === "number" && typeof s.text === "string" && typeof s.status === "string")
+					.map((s) => ({
+						id: s.id as number,
+						text: s.text as string,
+						status: s.status as SubtaskStatus,
+						lastUpdatedTurn: (s.lastUpdatedTurn as number) ?? 0,
+					}))
+			: undefined;
+		return { ...t, subtasks, lastUpdatedTurn: (t.lastUpdatedTurn as number) ?? 0 } as unknown as GoalTask;
+	}),
+		turnCount: (data.turnCount as number) ?? 0,
+		stallCount: (data.stallCount as number) ?? 0,
+		tokensUsed: (data.tokensUsed as number) ?? 0,
+		timeStartedAt: (data.timeStartedAt as number) ?? Date.now(),
+		timeUsedSeconds: (data.timeUsedSeconds as number) ?? 0,
+		budget: { ...DEFAULT_BUDGET, ...((data.budget as Partial<BudgetConfig>) ?? {}) },
+		lastProgressTurn: (data.lastProgressTurn as number) ?? 0,
+		budgetLimitSteeringSent: (data.budgetLimitSteeringSent as boolean) ?? false,
+		objectiveUpdatedAt: (data.objectiveUpdatedAt as number) ?? Date.now(),
+		lastBlockerReason: (data.lastBlockerReason as string | null) ?? null,
+		budgetWarning70Sent: (data.budgetWarning70Sent as boolean) ?? false,
+		budgetWarning90Sent: (data.budgetWarning90Sent as boolean) ?? false,
+		lastTurnTokensUsed: (data.lastTurnTokensUsed as number) ?? 0,
+		currentTurnIndex: (data.currentTurnIndex as number) ?? 0,
+		completedAtTurnIndex: data.completedAtTurnIndex as number | undefined,
+	};
+}
+
+// ── 进度计算 ──────────────────────────────────────────
+
+export function getCompletedCount(tasks: GoalTask[]): number {
+	return tasks.filter((t) => t.status === "completed").length;
+}
+
+export function getIncompleteTasks(tasks: GoalTask[]): GoalTask[] {
+	return tasks.filter((t) => !isTerminalTaskStatus(t.status));
+}
+
+export function getElapsedTimeSeconds(state: GoalRuntimeState): number {
+	if (isTerminalStatus(state.status) || state.status === "paused") return state.timeUsedSeconds;
+	return state.timeUsedSeconds + (Date.now() - state.timeStartedAt) / MS_PER_SECOND;
+}
+
+// getTokenUsagePercent 和 getTimeUsagePercent 已移至 budget.ts
+// 保留 re-export 以便渐进迁移
+export { getTokenUsagePercent, getTimeUsagePercent } from "./budget.js";

package/src/templates.ts

@@ -0,0 +1,232 @@
+/**
+ * Steering prompt 模板
+ *
+ * 参考 Codex /goal 的三套模板：
+ * 1. continuation.md — 每个 continuation turn 开始时注入
+ * 2. budget_limit.md — 首次达到 token budget 时注入
+ * 3. objective_updated.md — 外部修改了 goal objective 时注入
+ *
+ * 所有模板中的 objective 文本都经过 XML 转义，防止 prompt 注入。
+ */
+
+import type { GoalRuntimeState, GoalTask } from "./state";
+import { getIncompleteTasks, getCompletedCount, getElapsedTimeSeconds } from "./state";
+import { SECONDS_PER_MINUTE, PERCENT_FACTOR, TASK_STALL_TURN_THRESHOLD } from "./constants";
+
+// ── XML 转义（防止 objective 中的 XML 标签破坏 prompt 结构）──
+
+function escapeXmlText(input: string): string {
+	return input
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+// ── Continuation Prompt ───────────────────────────────
+// 精简版，对标 Codex ~500 chars。详细信息在 before_agent_start 注入。
+
+export function continuationPrompt(state: GoalRuntimeState): string {
+	const objective = escapeXmlText(state.objective);
+	const incomplete = getIncompleteTasks(state.tasks);
+	const completedCount = getCompletedCount(state.tasks);
+	const total = state.tasks.length;
+
+	// Budget info (single line, Codex style)
+	const budgetLine = formatBudgetLine(state);
+	const stallLine = state.stallCount > 0 ? `\nStall: ${state.stallCount}/${state.budget.maxStallTurns}轮无进展` : "";
+
+	// Task summary (only IDs, not full descriptions — descriptions in before_agent_start)
+	const taskLine = total > 0
+		? `Tasks: ${completedCount}/${total}${incomplete.length > 0 ? ` (剩余: ${incomplete.map(t => `#${t.id}`).join(",")})` : " ✓"}`
+		: "Tasks: 未创建。请立即 create_tasks。";
+
+	return (
+		`<goal_context>\n` +
+		`[GOAL] Turn ${state.turnCount}/${state.budget.maxTurns}${budgetLine}${stallLine}\n` +
+		`<objective>${objective}</objective>\n` +
+		`${taskLine}\n` +
+		`Rules: create_tasks→update_tasks(evidence)→complete_goal(evidence). blocked→report_blocked(reason). subtask: add_subtasks/update_subtasks (替代 todo 工具).\n` +
+		`Audit: 逐项验证每个需求有权威证据。不因预算耗尽标记完成，不因困难标记阻塞。\n` +
+		`</goal_context>`
+	);
+}
+
+// ── Budget Limit Prompt ───────────────────────────────
+
+export function budgetLimitPrompt(state: GoalRuntimeState, limitType: "token" | "time"): string {
+	const objective = escapeXmlText(state.objective);
+	const completedCount = getCompletedCount(state.tasks);
+	const total = state.tasks.length;
+	const elapsed = getElapsedTimeSeconds(state);
+
+	const incomplete = getIncompleteTasks(state.tasks);
+	const incompleteSummary =
+		incomplete.length > 0
+			? `未完成: ${incomplete.map((t) => `#${t.id}`).join(", ")}`
+			: "所有任务已完成。";
+
+	return (
+		`<goal_context>\n` +
+		`[GOAL — ${limitType === "token" ? "TOKEN 预算" : "时间预算"}即将耗尽]\n\n` +
+		`<objective>\n${objective}\n</objective>\n\n` +
+		`当前进度: ${completedCount}/${total} 任务完成\n` +
+		`${incompleteSummary}\n` +
+		(limitType === "token"
+			? `Token 已使用: ${state.tokensUsed} / ${state.budget.tokenBudget ?? "未知"}\n`
+			: `已用时间: ${Math.floor(elapsed / SECONDS_PER_MINUTE)}分${Math.floor(elapsed % SECONDS_PER_MINUTE)}秒 / ${state.budget.timeBudgetMinutes ?? "未知"}分钟\n`) +
+		`\n你必须立即收尾:\n` +
+		`1. 用 goal_manager 的 list_tasks 查看剩余任务\n` +
+		`2. 只标记你真正完成且有证据的任务\n` +
+		`3. 如果目标已达成，调用 goal_manager 的 complete_goal 完成目标\n` +
+		`4. 总结当前进度和剩余工作\n` +
+		`不要再开始新任务。不要因为预算耗尽就标记完成。\n` +
+		`</goal_context>`
+	);
+}
+
+// ── Objective Updated Prompt ──────────────────────────
+
+export function objectiveUpdatedPrompt(state: GoalRuntimeState, oldObjective: string): string {
+	const newObjective = escapeXmlText(state.objective);
+	const escapedOld = escapeXmlText(oldObjective);
+
+	return (
+		`<goal_context>\n` +
+		`[GOAL — 目标已更新]\n\n` +
+		`旧目标: ${escapedOld}\n` +
+		`<untrusted_objective>\n${newObjective}\n</untrusted_objective>\n\n` +
+		`这个新目标取代了之前的所有目标上下文。你需要:\n` +
+		`1. 立即停止朝旧目标方向的工作\n` +
+		`2. 重新评估任务清单，必要时调用 goal_manager 的 create_tasks 重新拆分\n` +
+		`3. 只在旧目标的工作也对新目标有帮助时才继续\n` +
+		`4. 按照新目标继续工作\n` +
+		`</goal_context>`
+	);
+}
+
+// ── Context Injection Prompt (before_agent_start) ─────
+
+export function contextInjectionPrompt(state: GoalRuntimeState): string {
+	const objective = escapeXmlText(state.objective);
+	const completedCount = getCompletedCount(state.tasks);
+	const total = state.tasks.length;
+	const budgetInfo = formatBudgetInfo(state);
+
+	return (
+		`<goal_context>\n` +
+		`[GOAL 模式已激活]\n\n` +
+		`<objective>\n${objective}\n</objective>\n` +
+		`状态: ${state.status}\n` +
+		`轮次: ${state.turnCount}/${state.budget.maxTurns}${budgetInfo}\n` +
+		`任务进度: ${completedCount}/${total}\n\n` +
+		`严格规则:\n` +
+		`1. 第一步必须调用 goal_manager 的 create_tasks 拆分任务（如果尚未创建）\n` +
+		`2. 每完成一个任务调用 update_tasks 将状态设为 completed，并提供 evidence\n` +
+		`3. 只有提供具体证据时才能调用 complete_goal\n` +
+		`4. 遇到阻塞调用 report_blocked\n` +
+		`5. Goal 模式下不要使用 todo 工具，使用 add_subtasks / update_subtasks 追踪细粒度步骤\n` +
+		`</goal_context>`
+	);
+}
+
+// ── Staleness Reminder Prompt ────────────────────────
+
+export function stalenessReminderPrompt(
+	state: GoalRuntimeState,
+	staleTasks: Array<{
+		task: GoalTask;
+		staleTurns: number;
+		staleSubtasks: Array<{ text: string; staleTurns: number }>;
+	}>,
+	allTerminal: boolean,
+): string {
+	const objective = escapeXmlText(state.objective);
+	const lines: string[] = [];
+
+	lines.push("<goal_context>");
+	lines.push("[GOAL 提醒 — 有任务停滞]\n");
+
+	if (allTerminal) {
+		lines.push("所有任务已完成，但 goal_manager 未关闭。请调用 complete_goal 或 cancel_goal。");
+	} else {
+		lines.push(`以下任务已超过 ${TASK_STALL_TURN_THRESHOLD} turn 未更新：\n`);
+		for (const item of staleTasks) {
+			lines.push(`  #${item.task.id}: ${item.task.description} (${item.staleTurns} turn 未操作)`);
+			for (const s of item.staleSubtasks) {
+				lines.push(`    - ${s.text} (${s.staleTurns} turn)`);
+			}
+		}
+		lines.push("\n请检查这些任务的状态，调用 update_tasks 更新进展或 cancel 不再需要的任务。");
+	}
+
+	lines.push(`\n目标: ${objective}`);
+	lines.push(`Turn: ${state.turnCount}/${state.budget.maxTurns}`);
+	lines.push("</goal_context>");
+
+	return lines.join("\n");
+}
+
+// ── Helpers ───────────────────────────────────────────
+
+function formatBudgetInfo(state: GoalRuntimeState): string {
+	const parts: string[] = [];
+	if (state.budget.tokenBudget) {
+		const pct = Math.round((state.tokensUsed / state.budget.tokenBudget) * PERCENT_FACTOR);
+		parts.push(`Token: ${pct}%`);
+	}
+	if (state.budget.timeBudgetMinutes) {
+		const elapsed = getElapsedTimeSeconds(state);
+		const pct = Math.round((elapsed / (state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE)) * PERCENT_FACTOR);
+		parts.push(`时间: ${pct}%`);
+	}
+	return parts.length > 0 ? ` (${parts.join(", ")})` : "";
+}
+
+function formatBudgetLine(state: GoalRuntimeState): string {
+	const parts: string[] = [];
+	if (state.budget.tokenBudget) {
+		const remaining = Math.max(state.budget.tokenBudget - state.tokensUsed, 0);
+		parts.push(`Tokens: ${remaining}/${state.budget.tokenBudget}`);
+	}
+	if (state.budget.timeBudgetMinutes) {
+		const elapsed = getElapsedTimeSeconds(state);
+		const remaining = Math.max(state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE - elapsed, 0);
+		parts.push(`Time: ${Math.floor(remaining / SECONDS_PER_MINUTE)}m/${state.budget.timeBudgetMinutes}m`);
+	}
+	return parts.length > 0 ? ` | ${parts.join(" ")}` : "";
+}
+
+export function formatTaskList(tasks: GoalTask[]): string {
+	if (tasks.length === 0) return "暂无任务。";
+	const completed = tasks.filter(t => t.status === "completed");
+	const active = tasks.filter(t => t.status === "in_progress" || t.status === "pending");
+	const cancelled = tasks.filter(t => t.status === "cancelled");
+	const lines: string[] = [];
+	if (active.length > 0) {
+		lines.push(`进行中/待执行 (${active.length}):`);
+		for (const t of active) {
+			const icon = t.status === "in_progress" ? "●" : "☐";
+			lines.push(`  ${icon} #${t.id}: ${t.description}`);
+			if (t.subtasks && t.subtasks.length > 0) {
+				for (const s of t.subtasks) {
+					const sIcon = s.status === "completed" ? "✓" : s.status === "in_progress" ? "●" : "○";
+					lines.push(`    ${sIcon} #${t.id}.${s.id}: ${s.text}`);
+				}
+			}
+		}
+	}
+	if (completed.length > 0) {
+		lines.push(`已完成 (${completed.length}):`);
+		for (const t of completed) {
+			const evidence = t.evidence ? ` — ${t.evidence}` : "";
+			lines.push(`  ✓ #${t.id}: ${t.description}${evidence}`);
+		}
+	}
+	if (cancelled.length > 0) {
+		lines.push(`已取消 (${cancelled.length}):`);
+		for (const t of cancelled) lines.push(`  ✗ #${t.id}: ${t.description}`);
+	}
+	const summary = `${completed.length}/${tasks.length} 完成` + (cancelled.length > 0 ? `, ${cancelled.length} 已取消` : "");
+	lines.push(summary);
+	return lines.join("\n");
+}