@zhushanwen/pi-goal 0.1.0

package/README.md

@@ -0,0 +1,151 @@
+# /goal — Pi 目标驱动模式
+
+Codex 风格的 `/goal` 命令，让 Pi 进入自主循环，持续工作直到目标达成。支持任务追踪、证据验证、Token/时间预算、阻塞检测。
+
+## 安装
+
+```bash
+# 全局安装（所有项目生效）
+git clone https://github.com/zhushanwen321/xyz-pi-extensions.git
+ln -s $(pwd)/xyz-pi-extensions/goal ~/.pi/agent/extensions/goal
+
+# 项目级安装
+mkdir -p .pi/extensions
+ln -s /path/to/xyz-pi-extensions/goal .pi/extensions/goal
+```
+
+安装后重启 Pi session 生效。
+
+## 快速开始
+
+```
+/goal 修复项目中所有失败的测试
+/goal 实现用户认证功能 --tokens 500000 --timeout 30
+```
+
+Pi 会自动：拆分任务 → 逐个执行 → 收集证据 → 完成目标。
+
+## 命令参考
+
+| 命令 | 说明 |
+|------|------|
+| `/goal <目标>` | 设定新目标（会替换当前未完成的目标） |
+| `/goal status` | 查看当前目标状态、进度、预算 |
+| `/goal pause` | 暂停目标 |
+| `/goal resume` | 恢复暂停/阻塞的目标 |
+| `/goal clear` | 清除目标 |
+| `/goal update <新目标>` | 更新目标描述（清除旧任务，重新规划） |
+
+## 参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--tokens N` | 不限制 | Token 预算上限 |
+| `--timeout N` | 不限制 | 时间预算（分钟） |
+| `--max-turns N` | 50 | 最大轮次 |
+| `--max-stall N` | 5 | 连续无进展轮次，超过后自动阻塞 |
+
+示例：
+
+```
+/goal 重构 auth 模块 --tokens 200000 --timeout 15 --max-turns 30
+/goal 写单元测试 --tokens 100000 --max-stall 3
+```
+
+## 工作流程
+
+```
+用户: /goal 修复登录bug
+  │
+  ▼
+Pi 注入上下文 → LLM 拆分任务 (create_tasks)
+  │
+  ▼
+┌─────────────────────────────┐
+│  每个 turn:                  │
+│  1. LLM 执行任务             │
+│  2. 完成后调用 complete_task │
+│     (必须提供具体证据)        │
+│  3. 检查预算/进展/阻塞        │
+│  4. 注入 continuation 继续   │
+└─────────┬───────────────────┘
+          │ 全部完成
+          ▼
+LLM 调用 complete_goal (提供整体证据)
+```
+
+## 目标状态
+
+```
+         ┌──────────┐
+    ┌───►│  active  │◄─── resume
+    │    └────┬─────┘
+    │         │
+  clear    ┌──┴──┬──────────┬───────────┬──────────┐
+    │      ▼     ▼          ▼           ▼          ▼
+    │  paused  blocked  complete  budget_limited time_limited
+    │    ▲     ▲
+    │    │     │
+    └────┴─────┘ (resume 恢复)
+
+可恢复: paused, blocked → active
+终态: complete, budget_limited, time_limited, cancelled
+```
+
+## 内置保护机制
+
+| 机制 | 说明 |
+|------|------|
+| 证据验证 | `complete_task` / `complete_goal` 必须提供具体证据，不能空口完成 |
+| 预算预警 | Token/时间达 70% 提示注意，90% 注入收尾 steering |
+| 预算终止 | Token 100% → budget_limited 终态 |
+| 阻塞检测 | 连续 N 轮无进展 → blocked，需用户手动 resume |
+| 去抖保护 | 本轮 token 消耗为 0 时不发 continuation，防止无限循环 |
+| 防重入 | `before_agent_start` 注入的上下文不会在 `agent_end` 重复发送 |
+| Resume 预算重检 | 恢复暂停目标时，如果预算已耗尽，直接拒绝 |
+| 零预算拒绝 | `--tokens 0` 会被拒绝 |
+| 空白目标拒绝 | `/goal ""` 或 `/goal "   "` 会被拒绝 |
+| 目标长度限制 | 超过 4000 字符会被拒绝 |
+| 上下文空间保护 | 上下文窗口 >85% 时暂停，防止 OOM |
+
+## goal_manager 工具
+
+Pi 注册了 `goal_manager` 工具供 LLM 调用，用户不需要直接操作：
+
+| Action | 说明 |
+|--------|------|
+| `create_tasks` | 拆分目标为任务清单 |
+| `complete_task` | 标记任务完成（需 taskId + evidence） |
+| `list_tasks` | 查看任务进度和剩余预算 |
+| `complete_goal` | 标记目标完成（需 evidence，且所有任务已完成） |
+| `cancel_goal` | 取消目标（用户要求退出/停止时，LLM 直接调用，一步退出） |
+| `report_blocked` | 报告阻塞原因 |
+
+每个工具响应都包含当前预算信息（已用/剩余），让 LLM 自我调节。
+
+## 注意事项
+
+- 目标描述会被 XML 转义，防止 prompt 注入
+- `/goal update` 会清除已有任务和计数器，允许重新规划
+- 已暂停的目标 resume 时会重新检查预算，超限则直接终止
+- 状态通过 session entries 持久化，session 重启后自动恢复
+- Token 统计排除 cached input，避免跨 turn 双重计算
+- **退出方式有三种**：`/goal clear`（用户手动）、`/goal pause`（暂停稍后继续）、或直接告诉 LLM「停止/取消/退出」，LLM 会调用 `cancel_goal` 一步退出
+
+## 文件结构
+
+```
+goal/
+├── index.ts          # 入口 — 命令、事件、工具注册
+├── src/
+│   ├── index.ts      # Extension 主逻辑
+│   ├── state.ts      # 状态机、类型、序列化
+│   ├── commands.ts   # 命令参数解析
+│   ├── templates.ts  # Steering prompt 模板
+│   └── widget.ts     # TUI 状态栏渲染
+└── package.json      # 元数据（仅标识用）
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@zhushanwen/pi-goal",
+  "version": "0.1.0",
+  "description": "Codex-style /goal command for Pi — persistent goal-driven autonomous loop with evidence-based completion, token/time budgets, blocked detection, and steering templates.",
+  "main": "src/index.ts",
+  "keywords": [
+    "pi",
+    "extension",
+    "goal",
+    "autonomous",
+    "loop"
+  ],
+  "license": "MIT",
+  "files": [
+    "src/",
+    "index.ts"
+  ],
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "scripts": {
+    "typecheck": "npx tsc --noEmit"
+  }
+}

package/src/budget.ts

@@ -0,0 +1,159 @@
+/**
+ * Goal 预算策略 — 阈值、计算、检查
+ *
+ * 集中管理 token 和时间预算的所有决策逻辑。
+ * 调用者（handleAgentEnd、resume）通过 checkBudget() 获取决策结果，
+ * 不再需要了解阈值细节。
+ */
+
+import type { GoalRuntimeState } from "./state";
+import { getElapsedTimeSeconds } from "./state";
+import {
+	SECONDS_PER_MINUTE,
+	PERCENT_FACTOR,
+	BUDGET_RATIO_HIGH,
+	BUDGET_RATIO_LOW,
+	BUDGET_RATIO_TIGHT,
+	BUDGET_PERCENT_HIGH,
+	BUDGET_PERCENT_LOW,
+} from "./constants";
+
+// ── 决策类型 ────────────────────────────────────────
+
+export type BudgetDecision =
+	| { type: "ok" }
+	| { type: "warning70"; dimension: "token" | "time" }
+	| { type: "warning90"; dimension: "token" | "time" }
+	| { type: "steer_limit"; dimension: "token" | "time" }
+	| { type: "exceeded"; dimension: "token" | "time" };
+
+// ── 百分比计算（供 widget 使用）──────────────────────
+
+export function getTokenUsagePercent(state: GoalRuntimeState): number {
+	if (!state.budget.tokenBudget || state.budget.tokenBudget <= 0) return 0;
+	return (state.tokensUsed / state.budget.tokenBudget) * PERCENT_FACTOR;
+}
+
+export function getTimeUsagePercent(state: GoalRuntimeState): number {
+	if (!state.budget.timeBudgetMinutes || state.budget.timeBudgetMinutes <= 0) return 0;
+	const elapsed = getElapsedTimeSeconds(state);
+	const budgetSeconds = state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE;
+	return (elapsed / budgetSeconds) * PERCENT_FACTOR;
+}
+
+// ── Widget 颜色阈值（供 widget.ts 使用）──────────────
+
+export function getBudgetColor(percent: number): "error" | "warning" | "muted" {
+	if (percent >= BUDGET_PERCENT_HIGH) return "error";
+	if (percent >= BUDGET_PERCENT_LOW) return "warning";
+	return "muted";
+}
+
+// ── Resume 时的预算检查 ──────────────────────────────
+
+export function checkBudgetOnResume(state: GoalRuntimeState): { type: "exceeded"; dimension: "token" | "time" } | null {
+	if (state.budget.tokenBudget && state.tokensUsed >= state.budget.tokenBudget) {
+		return { type: "exceeded", dimension: "token" };
+	}
+	if (state.budget.timeBudgetMinutes) {
+		const elapsed = getElapsedTimeSeconds(state);
+		if (elapsed >= state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE) {
+			return { type: "exceeded", dimension: "time" };
+		}
+	}
+	return null;
+}
+
+// ── Agent turn 结束时的预算检查 ─────────────────────
+
+export interface BudgetCheckResult {
+	/** 终止性决策（预算耗尽时只返回一个，优先 token） */
+	terminal: { type: "exceeded"; dimension: "token" | "time" } | null;
+	/** 需要发送的预警（70%/90%） */
+	warnings: BudgetDecision[];
+	/** 是否已发送过 steering（90% token 收尾） */
+	shouldSendSteering: boolean;
+}
+
+export function checkBudgetOnTurnEnd(state: GoalRuntimeState): BudgetCheckResult {
+	const result: BudgetCheckResult = {
+		terminal: null,
+		warnings: [],
+		shouldSendSteering: false,
+	};
+
+	// Token 预算检查
+	if (state.budget.tokenBudget) {
+		const tokenPct = state.tokensUsed / state.budget.tokenBudget;
+
+		// 100% 耗尽 + 已发过 steering → 终止
+		if (tokenPct >= 1 && state.budgetLimitSteeringSent) {
+			result.terminal = { type: "exceeded", dimension: "token" };
+			return result;
+		}
+
+		// 90% + 未发 steering → 发 steer
+		if (tokenPct >= BUDGET_RATIO_HIGH && !state.budgetLimitSteeringSent) {
+			result.shouldSendSteering = true;
+			return result;
+		}
+
+		// 90% 预警（未发过）
+		if (tokenPct >= BUDGET_RATIO_HIGH && !state.budgetWarning90Sent) {
+			result.warnings.push({ type: "warning90", dimension: "token" });
+		} else if (tokenPct >= BUDGET_RATIO_LOW && !state.budgetWarning70Sent) {
+			result.warnings.push({ type: "warning70", dimension: "token" });
+		}
+	}
+
+	// 时间预算检查
+	if (state.budget.timeBudgetMinutes) {
+		const elapsed = getElapsedTimeSeconds(state);
+		const timePct = elapsed / (state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE);
+
+		if (elapsed >= state.budget.timeBudgetMinutes * SECONDS_PER_MINUTE) {
+			result.terminal = { type: "exceeded", dimension: "time" };
+			return result;
+		}
+
+		if (timePct >= BUDGET_RATIO_HIGH && !state.budgetWarning90Sent) {
+			result.warnings.push({ type: "warning90", dimension: "time" });
+		} else if (timePct >= BUDGET_RATIO_LOW && !state.budgetWarning70Sent) {
+			result.warnings.push({ type: "warning70", dimension: "time" });
+		}
+	}
+
+	return result;
+}
+
+// ── 进展评估 ────────────────────────────────────────
+
+export interface ProgressCheck {
+	allTasksDone: boolean;
+	noTasksCreated: boolean;
+	maxTurnsReached: boolean;
+	isStalled: boolean;
+	budgetTight: boolean;
+	completedCount: number;
+	totalCount: number;
+}
+
+export function checkProgress(state: GoalRuntimeState, tasksCompletedAtStart: number): ProgressCheck {
+	const incomplete = state.tasks.filter((t) => t.status === "pending" || t.status === "in_progress");
+	const completedCount = state.tasks.filter((t) => t.status === "completed").length;
+	const totalCount = state.tasks.length;
+	const progressThisRound = completedCount - tasksCompletedAtStart;
+
+	return {
+		allTasksDone: totalCount > 0 && incomplete.length === 0 && completedCount > 0,
+		noTasksCreated: totalCount === 0,
+		maxTurnsReached: state.turnCount >= state.budget.maxTurns,
+		isStalled: progressThisRound === 0,
+		budgetTight: Boolean(
+			state.budget.tokenBudget &&
+			state.tokensUsed >= state.budget.tokenBudget * BUDGET_RATIO_TIGHT,
+		),
+		completedCount,
+		totalCount,
+	};
+}

package/src/commands.ts

@@ -0,0 +1,79 @@
+/**
+ * /goal 命令定义和参数解析
+ */
+
+import type { BudgetConfig } from "./state";
+import { MAX_TURNS_CAP, MAX_STALL_CAP, UPDATE_PREFIX_LENGTH } from "./constants";
+
+export interface GoalCommandArgs {
+	action: "set" | "status" | "pause" | "resume" | "clear" | "update" | "history";
+	objective?: string;
+	budget?: Partial<BudgetConfig>;
+}
+
+export function parseGoalArgs(raw: string): GoalCommandArgs {
+	const trimmed = raw.trim().toLowerCase();
+	const fullRaw = raw.trim();
+
+	// Subcommands without objective
+	if (trimmed === "" || trimmed === "status") {
+		return { action: "status" };
+	}
+	if (trimmed === "pause") {
+		return { action: "pause" };
+	}
+	if (trimmed === "resume") {
+		return { action: "resume" };
+	}
+	if (trimmed === "clear") {
+		return { action: "clear" };
+	}
+	if (trimmed === "history") {
+		return { action: "history" };
+	}
+
+	// /goal update <new objective>
+	if (trimmed.startsWith("update ")) {
+		return { action: "update", objective: fullRaw.slice(UPDATE_PREFIX_LENGTH).trim() };
+	}
+	// /goal update (without argument) → 报错
+	if (trimmed === "update") {
+		return { action: "update" };
+	}
+
+	// /goal <objective> [--tokens N] [--timeout N] [--max-turns N] [--max-stall N]
+	// 只匹配已知 flag，避免误删 objective 中的 -- 文本
+	const knownFlags = /--(?:tokens|timeout|max-turns|max-stall)\s+\d+/g;
+	const objective = fullRaw.replace(knownFlags, "").trim();
+	const budget: Partial<BudgetConfig> = {};
+
+	const tokenMatch = fullRaw.match(/--tokens\s+(\d+)/);
+	if (tokenMatch) {
+		const val = parseInt(tokenMatch[1]!, 10);
+		if (!isNaN(val) && val > 0) budget.tokenBudget = val;
+	}
+
+	const timeMatch = fullRaw.match(/--timeout\s+(\d+)/);
+	if (timeMatch) {
+		const val = parseInt(timeMatch[1]!, 10);
+		if (!isNaN(val) && val > 0) budget.timeBudgetMinutes = val;
+	}
+
+	const maxTurnsMatch = fullRaw.match(/--max-turns\s+(\d+)/);
+	if (maxTurnsMatch) {
+		const val = parseInt(maxTurnsMatch[1]!, 10);
+		if (!isNaN(val)) budget.maxTurns = Math.max(1, Math.min(val, MAX_TURNS_CAP));
+	}
+
+	const maxStallMatch = fullRaw.match(/--max-stall\s+(\d+)/);
+	if (maxStallMatch) {
+		const val = parseInt(maxStallMatch[1]!, 10);
+		if (!isNaN(val)) budget.maxStallTurns = Math.max(1, Math.min(val, MAX_STALL_CAP));
+	}
+
+	if (!objective) {
+		return { action: "status" };
+	}
+
+	return { action: "set", objective, budget };
+}

package/src/constants.ts

@@ -0,0 +1,44 @@
+/**
+ * Goal 扩展语义常量
+ *
+ * 所有数字的含义都通过命名自解释，避免 magic number。
+ */
+
+// ── 时间换算 ────────────────────────────────────────
+
+export const SECONDS_PER_MINUTE = 60;
+export const MS_PER_SECOND = 1000;
+
+// ── 预算比例阈值 (0-1) ──────────────────────────────
+
+export const BUDGET_RATIO_HIGH = 0.9;            // 90% — 触发预警/收尾 steering
+export const BUDGET_RATIO_LOW = 0.7;             // 70% — 触发提醒
+export const BUDGET_RATIO_TIGHT = 0.8;           // 80% — 预算紧张，优先 steer
+export const CONTEXT_USAGE_RATIO_LIMIT = 0.85;   // 85% — 上下文空间不足阈值
+
+// ── 预算百分比阈值 (0-100) ──────────────────────────
+
+export const BUDGET_PERCENT_HIGH = 90;   // widget 颜色变红
+export const BUDGET_PERCENT_LOW = 70;    // widget 颜色变黄
+
+// ── 长度/数量上限 ───────────────────────────────────
+
+export const MAX_TURNS_CAP = 100;             // maxTurns 上限
+export const MAX_STALL_CAP = 20;              // maxStallTurns 上限
+export const UPDATE_PREFIX_LENGTH = 7;        // "update ".length
+
+// ── 百分比换算因子 ──────────────────────────────────
+
+export const PERCENT_FACTOR = 100;
+
+// ── TUI 显示 ────────────────────────────────────────
+
+export const PROGRESS_BAR_DEFAULT_WIDTH = 10;
+export const OBJECTIVE_DISPLAY_LIMIT = 80;
+export const OBJECTIVE_TRUNCATE_KEEP = 77; // DISPLAY_LIMIT - 3 for "..."
+
+// ── 停滞/清理阈值 ────────────────────────────────────
+
+export const TASK_STALL_TURN_THRESHOLD = 10;	// task/subtask 停滞提醒阈值（turn 数）
+export const AUTO_CLEAR_TURNS = 2;				// 终态后自动清理轮数
+export const MAX_HISTORY_ENTRIES = 20;			// goal-history entry GC 上限