Pi North Star：为 Pi 编码智能体带来持久化目标跟踪与自动延续能力

AI 编程助手的上下文困境\n\n当前的 AI 编程助手（如 Claude Code、Pi、Codex）在单次对话中表现出色，但在面对复杂、多步骤的任务时，开发者常常面临一个尴尬的局面：\n\n- 任务进行到一半，需要处理其他事情\n- 上下文窗口逐渐填满，重要信息被挤出\n- 重新启动会话后，之前的任务状态和进度丢失\n- 长时间运行的任务无法持续跟踪\n\nOpenAI 的 Codex 通过"目标模式"解决了这个问题——用户可以设定一个目标，AI 会持续工作直到目标达成。现在，Pi 编码智能体用户也可以通过 pi-north-star 扩展获得类似能力。\n\n---\n\n## 项目概览：Pi 的北极星\n\npi-north-star 是 Pi 编码智能体的扩展插件，引入 /goal 命令系统，实现：\n\n- 持久化目标跟踪：目标状态跨会话保存\n- 自动继续执行：AI 自动延续工作直到目标完成\n- 生命周期管理：创建、暂停、恢复、替换、清除目标\n- 预算控制：token 预算防止无限循环\n- 完成验证：可选的验证策略防止过早标记完成\n\n---\n\n## 核心机制解析\n\n### 1. 目标生命周期\n\n目标由用户显式命令创建，模型不会自动创建目标。完整生命周期如下：\n\n\n创建 (created) → 执行中 (executing) → [暂停 (paused)] → 恢复 (resumed) → 完成 (completed)\n ↓\n 预算耗尽 (budget_limited)\n ↓\n 清除 (cleared)\n\n\n命令系统：\n\n| 命令 | 功能 |\n|------|------|\n| /goal <目标描述> | 创建新目标（最多 4000 字符） |\n| /goal | 显示当前状态 |\n| /goal pause | 暂停活动目标 |\n| /goal resume | 恢复暂停的目标 |\n| /goal resume --budget <N> | 以新预算恢复 |\n| /goal replace [--budget <N>] <目标> | 替换目标（重置 token、时间和延续序列） |\n| /goal clear | 清除当前目标 |\n| /goal budget <N\|none> | 设置 token 预算，none 表示无限制 |\n| /goal verify | 显示当前验证策略 |\n| /goal verify off\|warn\|enforce | 设置验证策略 |\n\n### 2. 自动延续泵（Continuation Pump）\n\n这是 pi-north-star 的核心创新。每次用户→代理周期结束后，如果目标仍处于活动状态，系统会发送一个不可见的 pi.goal.continuation 提示，触发下一轮执行。\n\n停止条件：\n- 目标不再活动（已完成、暂停、中止、清除、预算受限）\n- 延续轮次调用了零个非目标工具（停滞检测）\n\n停滞检测防止无限循环——如果 AI 在延续轮次中没有执行任何实际操作，系统会认为目标已停滞，停止自动延续（但目标保持活动状态，下次外部触发会重新启动泵）。\n\n### 3. 阶段推断与状态显示\n\n系统根据非目标工具的执行结果自动推断当前阶段：\n\n| 阶段 | 触发条件 |\n|------|---------|\n| planning（规划） | 仅使用只读工具（read、grep、find、ls、web_search 等），或无工具调用 |\n| executing（执行） | 使用任何写入工具（edit、write）或非只读/非验证工具 |\n| verifying（验证） | 使用名称包含 test、verify、build、lint、typecheck 的工具 |\n| blocked（阻塞） | 所有工具调用都失败，无成功调用 |\n\nUI 反馈：\n- 页脚芯片：显示目标状态，如 goal: executing 1200/5000\n- 卡片小部件：显示目标描述（截断至 160 字符）、token 使用量（简写形式如 1.2k/5k）、已用时间\n\n### 4. 预算控制机制\n\n预算系统防止目标执行消耗过多 token：\n\n- 当 tokensUsed >= tokenBudget 时，目标进入 budget_limited 状态\n- 自动延续泵停止\n- 发送 pi.goal.budget_limit 引导，提示模型收尾\n\n用户可以在恢复时设置新预算，继续执行。\n\n### 5. 完成验证策略\n\n可选的验证机制防止过早标记目标完成，提供三级策略：\n\n| 策略 | 行为 |\n|------|------|\n| off（默认） | 不验证 |\n| warn | 证据不足时警告，但仍允许完成 |\n| enforce | 证据不足时阻止 update_goal 调用 |\n\nenforce 模式要求：\n- 至少 1 个证据项\n- 至少 2 种不同的证据类型\n- 至少一个 file_change 或 test_run\n- 至少一个非检查类型（file_change、test_run、command_output 或 verification_tool）\n\n证据类型：\n- file_inspection：read、grep、find、ls\n- file_change：edit、write\n- test_run：工具名包含 test/verify/build/lint/typecheck\n- command_output：bash、shell\n- verification_tool：其他非目标工具（如 web_search）\n- goal_check：get_goal\n\n这种设计确保目标完成有实质证据支撑，而非 AI 的幻觉。\n\n### 6. CAS 与并发控制\n\n延续 CAS（Compare-And-Swap）：\n在发送延续前，运行时重新读取分支的快照，检查 (id, revision) 是否与触发排队时捕获的一致。如果快照在此期间发生变化，延续将被静默丢弃。\n\n单进程序列化：\n所有变更路径（工具处理程序、斜杠命令、记账、延续调度）都通过 GoalRuntime 中的单个 AsyncMutex 串行化。生命周期记账（turn_end / agent_end）通过同一互斥锁下的顺序队列处理。\n\n版本计数器：\n每个快照携带单调递增的版本号，每次持久化变更时递增。延续调度器使用版本号进行完整 CAS 检查。\n\n---\n\n## 技术实现细节\n\n### 分支本地快照\n\n目标状态通过 pi.appendEntry("goal.snapshot", ...) 存储为分支本地快照，不修改 Pi 核心。分支 fork/clone 会继承每个分支的最新快照。\n\n### 会话启动行为\n\n- 无目标：不发送提示，目标模式完全显式\n- 暂停的目标：显示目标恢复提示，包括目标描述、状态、已用 token 和已用时间，提供 /goal resume、/goal resume --budget <N> 和 /goal clear 选项\n\n### 目标事件\n\n系统在有意义的状态转换时发出 goal.event 条目（created、replaced、updated、paused、resumed、completed、budget_limited、cleared），但不包括常规使用记账。TUI 和其他扩展可以实时观察状态变化。\n\n### 完成审计\n\n延续提示指示模型：\n1. 将目标重述为具体的可交付成果\n2. 针对实际文件/测试/命令输出验证每项\n3. 然后调用 update_goal\n\n目标描述使用 XML 转义并包裹在标签中，防止用户输入中的提示注入攻击。\n\n---\n\n## 使用示例\n\n### 场景：重构认证模块\n\n\n用户: /goal 将认证模块重构为使用 OAuth 2.0\n\nPi: 开始分析当前认证实现...\n [自动延续] 识别 OAuth 2.0 集成点...\n [自动延续] 创建迁移计划...\n [自动延续] 实现 OAuth 2.0 客户端...\n [自动延续] 更新用户认证流程...\n [自动延续] 运行测试验证...\n 目标完成！\n\n\n### 场景：预算控制\n\n\n用户: /goal budget 5000\n用户: /goal 实现用户管理 API\n\nPi: [持续执行，直到接近 5000 token]\n 预算即将耗尽，正在收尾...\n [进入 budget_limited 状态]\n\n用户: /goal resume --budget 3000\nPi: [继续执行剩余任务]\n\n\n### 场景：严格验证\n\n\n用户: /goal verify enforce\n用户: /goal 修复登录页面的 CSS 问题\n\nPi: [尝试标记完成]\n 验证失败：缺少 test_run 证据\n 继续执行测试...\n [再次尝试]\n 验证通过，目标完成！\n\n\n---\n\n## 与 Codex 的对比\n\n| 特性 | OpenAI Codex | pi-north-star |\n|------|-------------|---------------|\n| 目标模式 | 原生支持 | 扩展插件 |\n| 暂停/恢复 | 支持 | 支持 |\n| 预算控制 | 支持 | 支持 |\n| 完成验证 | 内置 | 三级策略（off/warn/enforce） |\n| 阶段显示 | 基础 | 详细（planning/executing/verifying/blocked） |\n| 开源 | 否 | 是 |\n| 可定制 | 有限 | 高（验证策略、预算、UI 反馈） |\n\n---\n\n## 局限与注意事项\n\n1. 单进程限制：无跨进程锁定，同一分支的并发 Pi 会话可能竞争\n2. 预算竞争：如果 token 使用量跨轮次超过预算，budget_limit 引导等待下一轮\n3. 严格工具白名单：在严格白名单设置中，必须显式允许 get_goal、update_goal、clear_goal\n4. 终止信号：完成时的 terminate: true 需要 Pi 运行时支持，假设同一批次中没有其他非终止工具结果\n\n---\n\n## 安装与使用\n\nbash\npi install https://github.com/artur-shlyapnikov/pi-north-star\n\n\n安装后即可使用所有 /goal 命令。\n\n---\n\n## 总结\n\npi-north-star 为 Pi 编码智能体带来了关键的缺失能力：持久化目标跟踪与自动延续。通过精心设计的预算控制、完成验证和阶段推断机制，它让复杂任务能够持续运行直至完成，同时保持用户对执行过程的控制。\n\n对于需要处理多步骤、长时间运行任务的开发者，这个扩展显著提升了 Pi 的实用性，使其更接近 OpenAI Codex 的体验，同时保持开源和高度可定制的优势。