功能

• 通过 /goal 创建、编辑、暂停、恢复和清除当前目标。
• 裸 /goal 会按当前状态打开 TUI 管理器，提供启动、暂停、恢复、编辑、队列、设置、状态与帮助。
• goal_complete 只在有证据证明全部要求完成后结束目标。
• goal_blocked 对真正需要用户或外部行动的重复阻塞进行严格审计。
• goal_wait 在等待外部事件时保持安静，并可设置自动恢复时间。
• 默认在 25 个 Goal 所属模型响应后暂停并保留进度，也会在连续 3 次无工具、空输出或相同输出后触发无进展保护。
• 可设置 token 预算；状态区分 active、paused、blocked、usage_limited、budget_limited 与 complete。
• 三个 Goal 工具默认在首次目标激活后才显示，也可配置为从启动时一直可见。
• 实验模式支持有序目标队列、插队、跳过与删除队尾。

安装

需要 Pi 0.80.6 或更高版本。

pi install npm:@narumitw/pi-goal

# 临时试用
pi -e npm:@narumitw/pi-goal

在项目仓库根目录开发时，还可以用 pi -e ./packages/pi-goal 临时加载。

配置

配置文件位于 ~/.pi/agent/pi-goal.json。文件不存在时使用内置默认值，不会自动创建；可通过 /goal → Settings 在 TUI 中生成和修改。

{
  "toolVisibility": "after-first-goal",
  "experimental": { "goals": false },
  "rpc": { "enabled": false },
  "continuationLimits": {
    "automaticTurns": 25,
    "noProgressTurns": 3
  }
}

TUI 会拒绝 0、负数、小数、文本和不安全整数；保存使用原子写入并保留未知字段。会改变活动工具 schema 的可见性设置只能在 Pi 空闲时修改。

命令

/goal
/goal status
/goal implement snake game
/goal --tokens 100k fix the failing test and verify it
/goal edit ship the smaller fix first
/goal pause
/goal resume
/goal clear

开启实验队列后，还可以使用 /goal add、/goal prioritize、/goal drop-last 和 /goal skip。菜单中的替换、清除、插队、跳过和删除操作会预览影响范围并要求确认。

• /goal <目标> 启动 Goal；已有未完成目标时会先确认是否替换并重置用量。目标最长 4,000 字符。
• /goal --tokens 100k <目标> 设置总 token 预算，支持 k、m 与小数形式，例如 1.5m。
• /goal edit 修改目标而不重置累计用量；活动目标会轮换 stale-turn guard 并开启新的安全阶段。
• /goal pause 停止注入和自动继续但保留目标；/goal resume 轮换 goal id，并在实际启动时重置当前安全阶段。
• /goal clear 清除当前目标或整个队列、状态与待处理继续意图，但不会中止无关的正在运行任务。

实验性有序目标队列

兼容别名 push、unshift、pop、shift 仍可用，但不会出现在自动补全中。每个队列项拥有独立的预算、用量、活动时间、迭代、状态和 stale-id 记录；关闭实验功能时已保留的多项队列会冻结，而不会丢失。

会话与恢复

目标状态存储在 Pi session 中。/reload 或重新打开同一会话可恢复未完成目标；在同一目录新建会话不会继承旧目标。

自动响应计数、重复检测和安全暂停原因会跨 reload 与压缩保存。Goal 在等待、暂停、阻塞或离线期间不会累计活动时间。

恢复的 waiting Goal 会继续保持安静，只恢复原来的绝对截止时间；若终止工具因其他限制不可见，活动 Goal 会恢复为 paused，而不会冒险继续。旧版按工作目录保存的全局状态文件不再读取，/goal clear 会清理当前目录的遗留条目。

Statusline 状态

pi-goal 输出紧凑的纯文本状态，@narumitw/pi-statusline 默认会为它加上 🎯 图标。

token 预算与活动时间

预算依据当前分支中持久化的助手消息 token 用量计算。提供商用量在模型回复完成后才成为权威值，因此最多可能超出一个模型调用。达到预算不会被视为完成，只会停止自动继续并允许一次有限的收尾总结。

• 优先使用 usage.totalTokens；旧记录则回退为 input、output、cacheRead 和 cacheWrite 之和，避免重复计算 reasoning 或 cacheWrite1h。
• 用量是当前分支累计助手 token 减去 Goal 启动时的基线；分支回退后最小按 0 处理。
• 预算不是美元成本上限。默认 25 次自动响应也只是响应次数边界，单次上下文、缓存价格和输出长度仍会变化。
• 活动时间只在 active 且非 waiting 时累计；暂停、阻塞、用量受限、预算受限、关机与离线时间均不计入。
• 需要更严格控制时，同时降低 automaticTurns 并使用 /goal --tokens；Unlimited 只移除响应次数限制。

如何判定完成

• Goal 提示会把用户目标标记为任务数据，并要求逐项导出命名产物、命令、测试、门槛、不变量与交付物。
• 当前 worktree、命令输出、测试、运行行为、PR 状态、渲染产物和外部状态才是证据；计划和历史对话只能作为上下文。
• 完成前默认视为尚未证明。间接、缺失或仅仅与成功一致的证据都不足以结束目标。
• 必须调用 goal_complete，传入精确的当前 goal_id 与总结；普通文本即便声称完成，也不会结束 Goal。
• 扩展能验证 id、空摘要和明显矛盾的摘要，但无法代替真实世界的完成证明。

未完成的 turn 会创建一次 continuation intent；它只会在 Pi 报告 agent 完全 settled、空闲且没有待处理消息后发送。重试、压缩、steering、follow-up 和更新的用户输入始终优先，旧 Goal 的延迟提示无法覆盖新目标。

等待外部事件

goal_wait({
  goal_id: "<current-goal-id>",
  reason: "Waiting for the review monitor",
  resume_after_ms: 300000
})

• 只应在已经安排 monitor 或其他唤醒来源后调用；resume_after_ms 是安全唤醒截止时间，不是轮询频率。
• reason 长度为 1–1,000 字符；截止时间必须是 1–2,147,483,647 的整数，小于 10 秒会按 10 秒执行。省略则可以无限安静等待。
• 接受后保持 canonical 状态 active，但暂停活动计时、取消自动继续并保存原因与绝对截止时间。建议单独调用该工具。
• 用户输入、RPC 输入或其他扩展的非 Goal 消息会解除等待；/goal resume 也会解除，但不重置累计用量。
• reload 会恢复绝对截止时间，不会重新开始计时。唤醒发送失败时只重试一次，避免进入循环。

真正阻塞的目标

goal_blocked 比普通澄清更严格：必须传入当前 goal_id、具体说明用户或外部需要采取什么行动的 reason、解决尝试的证据，以及 repeated_turns。同一阻塞必须连续出现至少 3 个 Goal turn；恢复后重新开始审计。

• reason 最多 1,000 字符，evidence 最多 4,000 字符，turn 次数必须是整数。
• 空内容、超长内容、旧 id、停止状态或少于 3 个 turn 都会被拒绝。
• 困难、未完成、不确定、普通澄清或可恢复的工具/提供商错误都不能作为 blocked 理由。
• 用户解决外部条件后运行 /goal resume，扩展会轮换 goal id 并继续。

中断与排队输入

用户暂停或中止 turn 会进入 paused；终止性的提供商或账户额度错误进入 usage_limited；其他不可重试错误进入 blocked。停止转换会取消待处理继续、在适用时中止旧工作，并阻止陈旧工具调用。

可重试的提供商中断和溢出压缩重试仍保持 active，不会额外排队 continuation。新的用户或扩展工作会覆盖旧继续意图，待处理消息永远优先；旧恢复逻辑也不能阻止替换后的新 Goal。

Managed run RPC

开启 rpc.enabled 后，受信任的同级扩展可通过 Pi 的 pi.events 启动、观察和取消一个 Goal 生命周期，无需模拟 /goal 输入。它是协作协议，不提供身份验证或扩展沙箱。

pi-goal:start
pi-goal:cancel
pi-goal:event:${runId}

pi.events.emit("pi-goal:start", {
  runId: "consumer-generated-run-id",
  objective: "Ship and verify the feature",
  tokenBudget: 100000
});

• runId 必须在当前会话中唯一，匹配字母数字开头、最长 128 字符的安全格式；推荐 UUID。它只是关联 id，不是秘密。
• 状态事件包括 active、complete、blocked、paused、usage_limited、budget_limited 和 cleared；只有 complete 是成功终态。
• 取消使用相同 runId，并走普通暂停转换；手动恢复不再属于已经终结的 managed run。
• 稳定错误码包括 RPC_DISABLED、INVALID_REQUEST、NO_ACTIVE_SESSION、RUN_ID_IN_USE、RUN_NOT_FOUND、GOAL_ALREADY_EXISTS、ACTIVATION_FAILED 和 SUPERSEDED。
• start 不会要求替换已有 Goal，而是直接拒绝；调用方必须等待终态事件，不能假设 emit 会等待完成。

适用场景

• 持续完成实现任务，而不是停在计划阶段。
• 反复调试，直到验证问题已经修复。
• 执行需要多个工具循环的重构。
• 要求智能体在完成前测试、lint 或类型检查。
• 让长时间运行的 Pi 编程会话更自主。

包结构

packages/pi-goal/
├── src/
│   ├── index.ts
│   ├── goal.ts
│   ├── command-registration.ts
│   ├── commands.ts
│   ├── tools.ts
│   ├── lifecycle.ts
│   ├── runtime.ts
│   ├── tool-policy.ts
│   ├── safety.ts
│   ├── wait.ts
│   ├── errors.ts
│   ├── markers.ts
│   ├── run-protocol.ts
│   └── queue.ts
├── README.md
├── LICENSE
├── tsconfig.json
└── package.json

index.ts 是 Pi 入口并转发到 goal.ts；其余文件分别处理命令、工具适配、生命周期、运行状态、工具策略、安全检测、等待、错误分类、提示标记、RPC 和纯队列转换。package.json 通过 pi.extensions 暴露 ./src/index.ts。

关键词

Pi extension、Pi coding agent、goal mode、autonomous coding agent、AI agent workflow、task completion、agent loop、verification、TypeScript Pi package。

许可

采用 MIT License。