@zhushanwen/pi-goal 0.1.0 → 0.1.2

package/README.md

@@ -1,151 +1,49 @@
-# /goal — Pi 目标驱动模式
+# goal
 
-Codex 风格的 `/goal` 命令，让 Pi 进入自主循环，持续工作直到目标达成。支持任务追踪、证据验证、Token/时间预算、阻塞检测。
+Codex 风格的 `/goal` 命令 — 持久目标驱动自主循环，支持任务追踪、证据验证、Token/时间预算、阻塞检测。
+
+## 功能
+
+- **自主循环**：`/goal <目标>` 启动后，AI 自动拆分任务并持续执行
+- **证据验证**：完成任务必须提供具体证据，不能空口完成
+- **预算控制**：Token 和时间双预算，70% 预警、90% 收尾、100% 终止
+- **阻塞检测**：连续无进展自动阻塞，用户可手动 resume
+- **持久化**：状态通过 session entries 保存，重启后自动恢复
 
 ## 安装
 
 ```bash
-# 全局安装（所有项目生效）
-git clone https://github.com/zhushanwen321/xyz-pi-extensions.git
-ln -s $(pwd)/xyz-pi-extensions/goal ~/.pi/agent/extensions/goal
+# symlink 方式（开发推荐）
+ln -s /path/to/xyz-pi-extensions-workspace/main/packages/goal \
+      ~/.pi/agent/extensions/goal
 
-# 项目级安装
-mkdir -p .pi/extensions
-ln -s /path/to/xyz-pi-extensions/goal .pi/extensions/goal
+# npm 方式（正式）
+pi install npm:@zhushanwen/pi-goal
 ```
 
-安装后重启 Pi session 生效。
-
-## 快速开始
+## 使用
 
 ```
 /goal 修复项目中所有失败的测试
 /goal 实现用户认证功能 --tokens 500000 --timeout 30
+/goal status      # 查看进度
+/goal pause       # 暂停
+/goal resume      # 恢复
+/goal clear       # 清除
 ```
 
-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      # 元数据（仅标识用）
+├── index.ts
+└── src/
+    ├── index.ts       # 入口 — 命令、事件、工具注册
+    ├── state.ts       # 状态机（6 态）
+    ├── commands.ts    # 命令参数解析
+    ├── templates.ts   # Steering prompt 模板
+    ├── tool-handler.ts# goal_manager 工具处理
+    ├── budget.ts      # 预算计算
+    ├── constants.ts   # 常量
+    └── widget.ts      # TUI 状态栏渲染
 ```
-
-## License
-
-MIT

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.1.0",
+  "version": "0.1.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",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
   "keywords": [
-    "pi",
+    "pi-package",
     "extension",
     "goal",
     "autonomous",
@@ -16,7 +22,18 @@
     "index.ts"
   ],
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*"
+    "@mariozechner/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": "*",
+    "@sinclair/typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "@earendil-works/pi-ai": {
+      "optional": true
+    }
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit"

package/src/index.ts

@@ -16,8 +16,11 @@
  * - deserializeState 向后兼容旧格式
  */
 
-import type { ExtensionAPI, ExtensionContext, CustomEntry } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ExtensionCommandContext, CustomEntry, Theme } from "@mariozechner/pi-coding-agent";
+
 import { Text } from "@mariozechner/pi-tui";
+import { type Static } from "typebox";
+
 
 import {
 	type GoalTask,
@@ -141,8 +144,8 @@ function reconstructGoalState(pi: ExtensionAPI, session: GoalSession, ctx: Exten
 
 // ── Command Handler ───────────────────────────────────
 
-async function handleGoalCommand(pi: ExtensionAPI, session: GoalSession, args: string, ctx: ExtensionContext): Promise<void> {
-	const parsed = parseGoalArgs(args);
+async function handleGoalCommand(pi: ExtensionAPI, session: GoalSession, args: string | undefined, ctx: ExtensionContext): Promise<void> {
+	const parsed = parseGoalArgs(args ?? "");
 
 	switch (parsed.action) {
 		case "status": {
@@ -742,17 +745,20 @@ export default function goalExtension(pi: ExtensionAPI) {
 		],
 		parameters: GoalManagerParams,
 
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		async execute(_toolCallId: string, params: Static<typeof GoalManagerParams>, _signal: AbortSignal | undefined, _onUpdate: any, ctx: ExtensionContext) {
 			try {
 				return await executeGoalAction(pi, session, params, ctx);
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
 				const inputSummary = JSON.stringify(params, null, 2);
-				throw new Error(`${msg}\n\nInput: ${inputSummary}`);
+				return {
+					content: [{ type: "text", text: `${msg}\n\nInput: ${inputSummary}` }],
+					isError: true,
+				};
 			}
 		},
 
-		renderCall(args, theme) {
+		renderCall(args: any, theme: Theme) {
 			let text = theme.fg("toolTitle", theme.bold("goal_manager ")) + theme.fg("muted", args.action);
 			if (args.tasks) text += ` ${theme.fg("dim", `(${args.tasks.length} tasks)`)}`;
 			if (args.updates) text += ` ${theme.fg("dim", `(${args.updates.length} updates)`)}`;
@@ -763,7 +769,7 @@ export default function goalExtension(pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result: any, { expanded }: any, theme: Theme) {
 			const details = result.details as GoalManagerDetails | undefined;
 			if (!details || !Array.isArray(details.tasks)) {
 				const text = result.content[0];
@@ -811,14 +817,14 @@ export default function goalExtension(pi: ExtensionAPI) {
 	pi.registerCommand("goal", {
 		description:
 			"目标驱动模式: /goal <objective> [--tokens N] [--timeout N] [--max-turns N] | /goal pause | /goal resume | /goal clear | /goal update <new-objective> | /goal status | /goal history",
-		handler: async (args, ctx) => {
+		handler: async (args: string | undefined, ctx: ExtensionCommandContext) => {
 			await handleGoalCommand(pi, session, args, ctx);
 		},
 	});
 
 	// ── Event: before_agent_start ──────────────────────
 
-	pi.on("before_agent_start", async (_event, ctx) => {
+	pi.on("before_agent_start", async (_event: any, ctx: ExtensionContext) => {
 		return handleBeforeAgentStart(pi, session, ctx);
 	});
 
@@ -831,7 +837,7 @@ export default function goalExtension(pi: ExtensionAPI) {
 
 	// ── Event: turn_end ────────────────────────────────
 
-	pi.on("turn_end", async (_event, ctx) => {
+	pi.on("turn_end", async (_event: any, ctx: ExtensionContext) => {
 		if (!session.state) return;
 		session.state.currentTurnIndex++;
 		updateWidget(session, ctx);
@@ -839,7 +845,7 @@ export default function goalExtension(pi: ExtensionAPI) {
 
 	// ── Event: message_end (token accounting) ──────────
 
-	pi.on("message_end", async (event, _ctx) => {
+	pi.on("message_end", async (event: any, _ctx: ExtensionContext) => {
 		if (!session.state || !isActiveStatus(session.state.status)) return;
 		if (event.message.role !== "assistant") return;
 
@@ -858,13 +864,13 @@ export default function goalExtension(pi: ExtensionAPI) {
 
 	// ── Event: agent_end ───────────────────────────────
 
-	pi.on("agent_end", async (_event, ctx) => {
+	pi.on("agent_end", async (_event: any, ctx: ExtensionContext) => {
 		await handleAgentEnd(pi, session, ctx);
 	});
 
 	// ── Event: session_start (state reconstruction) ───
 
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", async (_event: any, ctx: ExtensionContext) => {
 		reconstructGoalState(pi, session, ctx);
 		if (session.state) {
 			session.tasksCompletedAtAgentStart = getCompletedCount(session.state.tasks);
@@ -881,7 +887,7 @@ export default function goalExtension(pi: ExtensionAPI) {
 	];
 
 	for (const customType of goalMessageTypes) {
-		pi.registerMessageRenderer(customType, (message, _options, theme) => {
+		pi.registerMessageRenderer(customType, (message: any, _options: any, theme: Theme) => {
 			const prefix =
 				message.customType === "goal-context-exceeded"
 					? theme.fg("error", "[GOAL 预算] ")

package/src/tool-handler.ts

@@ -237,7 +237,7 @@ export async function executeGoalAction(
 						`如需追加任务请用 add_tasks，如需全部重新规划请用 /goal update。`,
 				);
 			}
-			state.tasks = params.tasks.map((desc, i) => ({
+			state.tasks = params.tasks.map((desc: string, i: number) => ({
 				id: i + 1,
 				description: normalizeDescription(desc),
 				status: "pending" as const,
@@ -256,7 +256,7 @@ export async function executeGoalAction(
 			const startId = state.tasks.length > 0
 				? Math.max(...state.tasks.map((t) => t.id)) + 1
 				: 1;
-			const newTasks: GoalTask[] = params.tasks.map((desc, i) => ({
+			const newTasks: GoalTask[] = params.tasks.map((desc: string, i: number) => ({
 				id: startId + i,
 				description: normalizeDescription(desc),
 				status: "pending" as const,
@@ -273,8 +273,8 @@ export async function executeGoalAction(
 			if (!params.updates || params.updates.length === 0) {
 				throw new Error("update_tasks requires a non-empty updates array");
 			}
-			const taskIds = params.updates.map((u) => u.taskId);
-			const duplicateIds = taskIds.filter((id, i) => taskIds.indexOf(id) !== i);
+			const taskIds = params.updates.map((u: { taskId: number; status: string; evidence?: string }) => u.taskId);
+			const duplicateIds = taskIds.filter((id: number, i: number) => taskIds.indexOf(id) !== i);
 			if (duplicateIds.length > 0) {
 				throw new Error(`重复的 taskId: ${[...new Set(duplicateIds)].join(", ")}`);
 			}
@@ -400,11 +400,11 @@ export async function executeGoalAction(
 			}
 			const subtasks = parentTask.subtasks ?? [];
 			const startId = subtasks.length > 0 ? Math.max(...subtasks.map((s) => s.id)) + 1 : 1;
-			const trimmed = params.texts.map((t) => t.trim()).filter((t) => t.length > 0);
+			const trimmed = params.texts.map((t: string) => t.trim()).filter((t: string) => t.length > 0);
 			if (trimmed.length === 0) {
 				throw new Error("texts 中至少需要一个非空字符串");
 			}
-			const newSubtasks: Subtask[] = trimmed.map((text, i) => ({
+			const newSubtasks: Subtask[] = trimmed.map((text: string, i: number) => ({
 				id: startId + i,
 				text,
 				status: "pending" as const,