跳到主要内容

持久目标 (/goal)

/goal 为 Kopi Agent 设定一个跨轮次持续存在的常驻目标。每轮结束后,一个轻量级 judge(评判)模型会检查助手的最新回复是否满足了该目标。如果没有,Kopi Agent 会自动向同一会话注入一条 continuation(继续)提示并继续工作——直到目标达成、你暂停或清除目标,或轮次预算耗尽为止。

这是我们对 Ralph loop 的诠释,直接源自 Eric Traut(OpenAI)的 Codex CLI 0.128.0 的 /goal。核心理念——让目标跨轮次保持活性,且在达成之前不停止——来自他们。这里的实现是独立的,并已适配 Kopi Agent 的架构。

适用场景​

对于你希望 Kopi Agent 自主迭代、而不需要你每轮重新提示的任务,请使用 /goal:

  • "修复 src/ 中的所有 lint 错误,并验证 ruff check 能通过"
  • "将功能 X 从仓库 Y 移植过来(包括测试),并让 CI 变绿"
  • "调查为什么 session ID 在运行中压缩时有时会发生偏移,并撰写一份报告"
  • "构建一个小型 CLI,按 EXIF 日期重命名文件,然后针对 photos/ 文件夹进行测试"

agent 只做一轮就停下的任务不需要 /goal。而对于那些*否则你得说三遍"继续"*的任务,它才能大显身手。

快速上手​

/goal Fix every failing test in tests/kopi_cli/ and make sure scripts/run_tests.sh passes for that directory

你会看到:

  1. 目标已接受 — ⊙ Goal set (20-turn budget): <your goal>
  2. 第 1 轮运行 — Kopi Agent 开始工作,就像你把目标作为普通消息发送了一样。
  3. judge 运行 — 该轮结束后,judge 模型会判定 done 还是 continue。
  4. 按需触发循环 — 如果 continue,你会看到 ↻ Continuing toward goal (1/20): <judge's reason>,随后 Kopi Agent 自动执行下一步。
  5. 终止 — 最终你会看到 ✓ Goal achieved: <reason> 或 ⏸ Goal paused — N/20 turns used。

命令​

命令作用
/goal <text>设置(或替换)常驻目标。会立即启动第一轮,因此你无需再单独发送一条消息。
/goal draft <text>从自然语言目标起草一份结构化的完成契约,然后进行设置。参见完成契约。
/goal show打印当前目标的完成契约。
/goal 或 /goal status显示当前目标、其状态以及已使用的轮次数。
/goal pause停止自动继续循环,但不清除目标。
/goal resume恢复循环(将轮次计数器重置为零)。
/goal clear彻底丢弃目标。
/goal wait <pid> [reason]将循环挂起在一个后台进程上——在该进程运行期间,它会停止每轮重新推动 agent,并在进程退出时自动恢复。
/goal unwait移除等待屏障并立即恢复循环。

在 CLI 以及所有网关平台(Telegram、Discord、Slack、Matrix、Signal、WhatsApp、SMS、iMessage、Webhook、API server 和 web 仪表板)上的工作方式完全相同。

完成契约​

只用一个简单的 /goal <text> 也能正常工作,但含糊的目标会导致含糊的判定——judge 只能检查你告诉它要达成什么。Codex 的 /goal 指南也提出了同样的观点:一个持久目标要想发挥最佳效果,就应当明确完成的含义、如何证明、不能破坏什么、范围涵盖哪些,以及何时停止。Kopi Agent 将这一点改造为叠加在现有目标循环之上的可选完成契约。

契约包含五个字段,均为可选:

字段含义
outcome完成时必须成立的唯一终态。
verification证明结果达成的具体测试 / 命令 / 产物。
constraints不得更改或退化的内容。
boundaries范围涵盖哪些文件、目录、工具或系统。
stop_whenKopi Agent 应停止并请求输入的条件。

设置契约后,两个提示都会改变:continuation 提示会要求 agent 以验证面为目标并遵守约束;judge 提示则仅当验证标准被具体证据满足时(命令结果、文件摘录、测试输出)才判定 done——而不是接受一句含糊的"看起来完成了"。这直接收紧了 /goal 最常见的失败模式(在目标定义不充分时过早完成,或无休止地过度继续)。

设置契约的两种方式​

1. 让 Kopi Agent 起草(推荐——改编自 Codex 的"让 agent 起草目标"提示):

/goal draft Migrate the auth service from session cookies to JWT

Kopi Agent 会通过 goal_judge 辅助模型将你的一句话扩展为完整契约,进行设置,并向你展示结果,方便你审查或收紧任何字段。如果辅助模型不可用,则回退为普通的自由形式目标——起草永远不会阻碍目标的设置。

2. 使用 field: value 行以内联方式书写:

/goal Migrate auth to JWT
verify: pytest tests/auth passes
constraints: keep the /login response shape unchanged
boundaries: only touch services/auth and its tests
stop when: a DB schema migration is required

第一个(或前几个)非字段行是目标标题;可识别的字段前缀(verify:、verified by:、constraints:、preserve:、boundaries:、scope:、stop when:、blocked: 等)会填充到契约中。带有随手写的冒号的普通目标(Fix bug: the parser drops commas)不会被破坏——只有已知的字段前缀会被提取出来。

使用 /goal show 查看当前生效的契约。契约与目标一同持久化在 SessionDB.state_meta 中,因此能够在 /resume 后保留。此功能之前创建的旧目标会原样加载(不含契约)。契约与 /subgoal 标准可以组合:子目标会作为额外标准并入契约,judge 也必须同时满足它们。

在目标执行过程中追加验收标准:/subgoal​

在目标处于活跃状态时,你可以使用 /subgoal <text> 追加额外的验收标准,而无需重置循环。每次调用都会向目标的子目标列表中添加一个带编号的条目;agent 在下一轮看到的续接提示(continuation prompt)会包含原始目标以及一个"用户在循环过程中追加的标准"区块,而裁决提示(judge prompt)会被改写,使最终判定必须考量每一个子目标 —— 只有原始目标和每个子目标都达成后,目标才会被标记为完成。

命令作用
/subgoal <text>向当前活跃目标追加一条新标准。需要一个活跃的 /goal。
/subgoal(无参数)显示当前带编号的子目标列表。
/subgoal remove <N>移除第 N 个子目标(从 1 开始计数)。
/subgoal clear丢弃所有子目标,但保留原始目标不变。

子目标会与目标一起持久化保存在 SessionDB.state_meta 中,因此它们能经受住 /resume。设置新的 /goal <text> 会替换目标并清空子目标列表;/goal clear 同样如此。

当你启动一个循环("修复失败的测试")并在中途意识到还希望它"顺便为你刚修复的 bug 添加一个回归测试"时,就可以使用此功能 —— /subgoal add a regression test 能在不打断运行中循环的前提下收紧成功标准。

挂起等待后台进程:自动处理,并支持手动覆盖​

有些目标依赖于一件耗时数分钟且会自行运行的事情 —— 例如已推送 PR 上的 CI、一次长时间构建、一个测试矩阵、一次部署,或一个限流冷却期。若无辅助机制,目标循环会在等待期间每一轮都去戳一下 agent,让它陷入"完成了没?"的无谓忙碌中。

这会被自动处理。每一轮,裁决器都能看到 agent 的实时后台进程(即 terminal(background=true) 注册表 —— 包括 pid、session id、命令、运行时长、近期输出,以及任何 watch_patterns / notify_on_complete 触发器),同时还能看到目标和 agent 的回复。当 agent 的进展确实被其中某个进程卡住时,裁决器会返回 wait 判定而非 continue,循环便会挂起(park):后续轮次会被跳过(不调用裁决器、不续接、不消耗轮次),直到等待条件得到满足 —— 然后循环带着结果正常恢复。裁决器也可以基于时间(wait_for_seconds)进行挂起,用于退避/冷却等待。/goal status 在挂起期间会显示 ⏳ Goal (parked …)。

裁决器会根据进程自身的信号来选择正确的等待方式:

  • wait_on_session <id> —— 在进程自身的触发器触发时释放:进程退出,或者(如果它是用 watch_patterns 启动的)其模式匹配成功。这种方式适用于长期运行的 watcher / 服务器 / 轮询器,它们会在运行中途发出信号(例如一个打印 BUILD SUCCESSFUL 并继续运行的构建进程,或一个 notify_on_complete watcher),且可能永远不会自行退出。
  • wait_on_pid <pid> —— 仅在进程退出时释放。
  • wait_for_seconds <n> —— 在固定延迟后释放。

你无需为此输入任何内容 —— 这是裁决器的决定,依据循环交给它的进程上下文做出。手动命令则作为覆盖手段存在:

命令作用
/goal wait <pid> [reason]手动挂起循环,直到对应 PID 的进程退出。
/goal unwait清除任何等待屏障(由裁决器或手动设置的)并立即恢复。

屏障(基于 pid 或时间)会与目标一起持久化在 SessionDB.state_meta 中,因此它能经受住 /resume。/goal pause、/goal resume 和 /goal clear 都会将其丢弃。如果在设置屏障时该 PID 已经不存在(或在挂起期间退出),或者时间期限已过,屏障会在下一次检查时自动清除 —— 过期的屏障永远不会卡住循环。

典型流程:agent 推送一个 PR,用 terminal(background=true, notify_on_complete=true) 启动一个 CI watcher,并报告"正在监控 CI。"裁决器看到该 watcher 进程仍在运行,就针对其 pid 返回 wait,循环随即安静下来 —— 然后在 CI 完成的那一刻恢复,并依据实际结果对目标进行裁决。

行为细节​

judge(评审器)​

每一轮结束后,Kopi Agent 都会调用一个辅助模型,并传入:

  • 当前目标的文本
  • agent 最近一次的最终响应(最后约 4 KB 的文本)
  • 一段系统提示,要求 judge 以严格的 JSON 回复:{"done": <bool>, "reason": "<one-sentence rationale>"}

judge 刻意保持保守:只有当响应明确确认目标已完成、最终交付物已清晰产出,或目标无法达成/被阻塞(此时视为 DONE 并附上阻塞原因,这样我们就不会在不可能的任务上浪费预算)时,才会将目标标记为 done。

失败开放(fail-open)语义​

如果 judge 出错(网络抖动、响应格式错误、辅助 client 不可用),Kopi Agent 会将判定结果视为 continue —— 失效的 judge 绝不会卡住进度。轮次预算才是真正的兜底机制。

轮次预算​

默认为 20 个续接轮次(goals.max_turns,位于 config.yaml)。当预算耗尽时,Kopi Agent 会自动暂停,并准确告诉你如何继续:

⏸ Goal paused — 20/20 turns used. Use /goal resume to keep going, or /goal clear to stop.

/goal resume 会将计数器重置为零,因此你可以分批、有节制地继续推进。

用户消息始终优先​

在目标激活期间,你发送的任何真实消息都会优先于续接循环。在 CLI 上,你的消息会进入 _pending_input,排在排队的续接之前;在 gateway 上,它同样通过 adapter FIFO 传递。在你的轮次结束后 judge 会再次运行 —— 因此如果你的消息恰好完成了目标,judge 会捕捉到并停止。

运行中安全性(gateway)​

当一个 agent 已经在运行时,/goal status、/goal pause、/goal clear、/goal wait 和 /goal unwait 都可以安全执行 —— 它们只操作控制平面状态,不会打断当前轮次。在运行中设置新目标(/goal <new text>)会被拒绝,并返回一条提示要求你先 /stop,这样旧的续接就不会与新的续接产生竞争。

持久化​

目标状态保存在 SessionDB.state_meta 中,以 goal:<session_id> 作为键。这意味着 /resume 会从你离开的地方继续 —— 设定一个目标,合上笔记本电脑,第二天回来,/resume,目标依然如你离开时那样保持原状(active、paused 或 done)。

提示缓存​

续接提示是一条追加到历史记录中的普通 user 角色消息。它不会修改系统提示、交换工具集,也不会以任何会使 Kopi Agent 提示缓存失效的方式改动对话。运行一个 20 轮的目标,在缓存层面的成本与 20 轮普通对话完全相同。

配置​

添加到 ~/.kopi/config.yaml:

goals:
# Max continuation turns before Kopi Agent auto-pauses and asks you to
# /goal resume. Default 20. Lower this if you want tighter loops;
# raise it for long-running refactors.
max_turns: 20

选择 judge 模型​

judge 使用 goal_judge 辅助任务。默认情况下,它会解析为你的主模型(参见 Auxiliary Models)。如果你想将 judge 路由到一个便宜快速的模型以控制成本,请添加一个覆盖配置:

auxiliary:
goal_judge:
provider: openrouter
model: google/gemini-3-flash-preview

judge 调用的体量很小(约 200 个输出 token),且每轮只运行一次,因此选择一个便宜快速的模型通常是正确的做法。

示例演练​

You: /goal Create four files /tmp/note_{1..4}.txt, one per turn, each containing its number as text

⊙ Goal set (20-turn budget): Create four files /tmp/note_{1..4}.txt, one per turn, each containing its number as text

Kopi Agent: Creating /tmp/note_1.txt now.
💻 echo "1" > /tmp/note_1.txt (0.1s)
I've created /tmp/note_1.txt with the content "1". I'll continue with the remaining files on the next turn as you specified.

↻ Continuing toward goal (1/20): Only 1 of 4 files has been created; 3 files remain.

Kopi Agent: [Continuing toward your standing goal]
💻 echo "2" > /tmp/note_2.txt (0.1s)
Created /tmp/note_2.txt. Two more to go.

↻ Continuing toward goal (2/20): 2 of 4 files created; 2 remain.

Kopi Agent: [Continuing toward your standing goal]
💻 echo "3" > /tmp/note_3.txt (0.1s)
Created /tmp/note_3.txt.

↻ Continuing toward goal (3/20): 3 of 4 files created; 1 remains.

Kopi Agent: [Continuing toward your standing goal]
💻 echo "4" > /tmp/note_4.txt (0.1s)
All four files have been created: /tmp/note_1.txt through /tmp/note_4.txt, each containing its number.

✓ Goal achieved: All four files were created with the specified content, completing the goal.

You: _

四轮,一次 /goal 调用,你没有发送任何"继续"提示。

当 judge 判断出错时​

没有 judge 是完美的。需要留意两种失败模式:

假阴性 —— judge 说继续,但目标实际已完成。 轮次预算会捕捉到这种情况。你会看到 ⏸ Goal paused,然后可以 /goal clear,或者直接发送一条新消息。

假阳性 —— judge 说已完成,但仍有工作未完成。 你会看到 ✓ Goal achieved,但你心里清楚并非如此。发送后续消息继续工作,或者更精确地重新设定目标:/goal <more specific text>. judge 的系统提示刻意保持保守,以使假阳性比假阴性更少见。

如果你觉得某个 judge 判定难以信服,↻ Continuing toward goal 或 ✓ Goal achieved 行中的原因文本会准确告诉你 judge 看到了什么。这通常足以判断是目标文本存在歧义,还是模型的响应存在歧义。

致谢​

/goal 是 Kopi Agent 对 Ralph loop 模式的诠释。其面向用户的设计 —— 让目标跨轮次保持存活,在达成之前不停止,并提供创建/暂停/恢复/清除控制 —— 由 OpenAI Codex 团队的 Eric Traut 在 Codex CLI 0.128.0 中推广并发布。我们的实现是独立的(中心化 CommandDef 注册表、SessionDB.state_meta 持久化、辅助 client judge、gateway 侧的 adapter-FIFO 续接),但这个创意属于他们。功劳应当归于应得之人。