Goal 模式

Goal 模式为一个 session 提供可跨越多个普通 Agent turn 的持久目标，适合无法在单次回答中完成、但应始终围绕同一结果并汇总用量的工作。

Goal 模式是编排层，不是第二套 Agent runtime。每个 Goal turn 仍遵循正常的 AgentTask、TaskRuntime、TurnRunner、Sandbox、审批、provider fallback、transcript 和用量核算约定。

它没有固定阶段、隐藏 evaluator 或专用执行循环。持久目标会加入普通 Default 模式 turn；如果该 turn 结束时没有明确的 Goal 终态决定，Goal 继续保持 active。session 通过共享 idle gate 后，Gateway 会根据最新 transcript、workspace、外部状态和 Goal snapshot 启动另一个普通 Default turn，由 Agent 根据当前证据决定下一步。

启动和管理 Goal

在由 Gateway 支持的 Web UI 或终端聊天中使用：

/goal 准备发布并验证全部必要检查
/goal set 准备发布并验证全部必要检查
/goal status
/goal edit 准备发布、验证全部检查并更新 changelog
/goal pause
/goal resume
/goal clear

/goal <objective> 与 /goal set <objective> 等价。目标会去除首尾空白，长度必须为 1–4000 个 Unicode 字符；第一次 Goal turn 中，它也会作为真实的首条用户消息保存。无参数 /goal 在 Goal 存在时显示状态，否则显示帮助。

一个 session 同时只能有一个未完成 Goal。再次启动会返回冲突，不会静默替换。已完成 Goal 的 owning task 完全结束且 session idle 后可以新建 Goal。

edit 保留 Goal identity、替换目标并清空旧 progress。运行中的主 Agent 会在下一个安全模型边界采用新目标；若当前 task 已在收尾，则下一个普通 Goal turn 使用新目标。编辑已完成 Goal 会重新激活同一个 Goal，保留 identity、创建时间和 lifetime usage，但重置终态、progress 和当前 guardrail window。
pause 禁止后续自动继续，但不会取消已接受的 task；如需终止当前 task，应使用普通 Stop。
resume 把未完成的 paused、blocked 或 usage-limited Goal 恢复为 active。若原 task 仍拥有 Goal，不会创建重复 task；否则在共享 idle gate 允许时开始。恢复会开启新的 guardrail window，但保留 lifetime accounting。
clear 删除 Goal tracking 并撤销 execution lease，不会取消当前 task、删除 transcript 或 artifact。generation 与 Goal fence 会阻止遗留 task 重新创建或修改已清除 Goal。若要连同已开始处理的 edit 一起停止，应使用 Stop。

Composer 的 Stop 作用边界相反：只取消当前 AgentTask。若取消后 Goal 尚未完成，Goal 会以 user_cancelled 原因暂停，不会立刻自动继续。

状态、进度与完成

Goal 有五种状态：

状态	含义
`active`	可以接受用户工作或自动继续。
`paused`	尚未完成，但明确 resume 前禁止自动继续。
`blocked`	尚未完成；Agent 遇到真实僵局，或 runtime 记录了终止性 turn failure。解决原因后再 resume。
`usage_limited`	尚未完成；provider 将 turn 判定为用量受限。解决限制后再 resume。
`complete`	已完成，也是唯一的完成状态。

Goal ribbon 与 /goal status 会显示目标、执行状态、progress、turn 数、lifetime 与当前窗口运行时间、token usage、原因和 guardrail。executionState 区分 idle、queued 和 working；deferred reason 可说明自动工作正在等待用户输入、其他 session 工作或 Plan 模式。

复杂工作中，主 Agent 可用最多 20 个结构化步骤替换 progress checklist。每步最多 200 字符，可选说明最多 1000 字符，最多一个步骤为 in_progress。它只是当前工作的动态投影，可随证据变化合并、删除、重排或重写，不是阶段状态机，也不要求每个 turn 对应固定步骤。

标记 complete 前，Agent 必须用当前权威状态审计整个持久目标及其引用要求。测试、artifact 检查、命令结果和外部检查必须直接证明每个适用验收条件；证据缺失、间接、过期、矛盾或不确定时，Goal 仍应保持 active 并继续有用工作。助手文本、artifact 交付或看似完成的 checklist 都不会自行完成 Goal。

Agent 声明 blocked 也必须审慎：同一阻塞条件至少连续阻止三个 Goal turn，且已经穷尽安全、范围内的检查和替代路径。困难、缓慢、不确定或仅需澄清本身不构成 blocked。真实 provider、tool、取消、超时或用量 failure 仍由 runtime 按系统规则处理。

类似 [goal:complete] 的文字没有控制含义，只是普通可复制文本。

自动继续与用户优先级

Goal turn 结束后，Gateway 会通过共享 idle admission gate 重新判断。只有同时满足以下条件才接受 continuation：

session generation、Goal identity、objective revision 和 continuation sequence 匹配；
Goal 为 active 且没有 owning task；
session 处于 Default 模式且没有活动的手动 Plan run；
execution lease 有效，owner 仍订阅且有权限；
没有明确用户输入或其他 queued/running session 工作；
当前 guardrail window 仍允许另一个 turn。

明确用户输入在与自动工作竞争时始终优先。普通 Default follow-up 可以 claim active Goal；若消息先进入队列，会在 task 真正激活时重新验证。Plan、Review、subagent、cron、memory、compaction 和 system turn 不会 claim Goal。

自动 continuation 是系统事件，不会伪造用户 transcript、Goal command receipt 或 memory 消息，但仍会在已连接的 Web UI/CLI 中展示助手输出、tool、审批和用量。终端输入与外部 Goal turn 并发时，CLI 先尝试正常 steering，失败后才创建新用户 turn。

Goal 模式不会重放失败或超时的整个 turn，因为 tool 可能已经产生不可逆副作用。底层 provider 与核心 retry 仍遵循各自安全规则。自动 continuation 也不是单独 evaluator，而是让同一主 Agent 在普通 Default loop 中继续执行，并进行完成或阻塞审计。

Goal progress 不是 Plan 模式

Goal 是跨普通 Default turn 持久存在的目标，可选 checklist 只是轻量状态视图。
Plan 模式是在实现前提出或修改计划的交互协作模式。

更新 Goal progress 不会进入 Plan 模式、创建 PlanRun、规定阶段或强制结束 turn。切换到 Plan 模式后 Goal 仍保持持久和 active，但 Goal-owned execution 与自动继续会以 plan_mode 原因等待；回到 Default 后重新进入共享 idle gate，最多接受一个符合条件的 continuation。

Execution lease、断线与重启

启动或恢复 Goal 会向调用方、已订阅的 Web UI/CLI 连接授予进程内 execution lease。只读 spectator 不会获得、刷新或继承 lease。权限、凭据和 route envelope 不写入 Goal row；每次自动 turn 都从实时连接重建并重新验证。

owner 断线或取消订阅后，进程内 lease 会 detach，但持久 Goal 仍为 active。运行中的 task 可以结束或报告 blocker，但 lease detach 期间不会接受新的自动 continuation；状态以 owner_disconnected 表示延迟原因，而不会把暂时网络故障伪装成用户 pause。

Web UI 为当前浏览器 tab 保存不透明、仅进程有效的 continuity token。刷新后先恢复认证消息订阅，再用 token 重新附加 lease，不修改 Goal revision，也不重置 turn/runtime guardrail window。普通 subscribe、status 和 hydrate 都是只读的。token 不可用时，授权 operator 可通过 Goal 控件或 /goal resume 明确接管 detached lease；活跃 owner 尚在时拒绝接管。

Gateway 关闭或重启会把未完成 active Goal 以 process_restart 暂停，重启绝不会自动调用 provider。Gateway 重启后应重新连接并明确 resume。

消息 channel 可以向已有 active Goal 提交普通 Default turn，但不能启动、恢复 Goal 或拥有 lease，避免无人值守 channel 流量授权持续 token 消耗。

reset session 会轮换 generation、删除当前 Goal 并撤销 lease；删除 session 也会删除 Goal 与 command receipt；fork session 不继承 Goal。

Artifact 交付

普通 turn 中成功的 publish_artifact 交付仍是终止性的；在 Goal-owned turn 中它只是普通 tool result：artifact 立即可用，Agent 仍按相同 route、安全策略、审批和 provider fallback 继续 tool loop。只有整个目标完成或真正 blocked 时才调用 update_goal；artifact 或 checklist 不代表完成。

若成功 turn 没有终态 Goal decision，Goal 保持 active，idle gate 最多接受一个自动 continuation。因旧版兼容而以 goal_checkpoint_required 暂停的 Goal 仍可读取，明确 resume 后会按正常 Goal loop 继续，不会重放幂等 artifact delivery。

Guardrail 与用量

在 config.toml 中配置：

[goal]
execution_enabled = true
max_turns = 50
runtime_budget_seconds = 3600

max_turns 范围为 1–500；runtime_budget_seconds 范围为 60–86400 秒，只计算 Goal-owned task 的实际运行时间，不包括排队、pause 和 Gateway downtime。

guardrail 不会在 task 中途终止它。结构化 complete 或 blocked 结果优先；若结束后 Goal 仍 active，达到限制会以 turn_limit 或 runtime_limit 暂停。成功 resume 会重置窗口内 turn 与 active-time counter，lifetime turn、active time 和 token total 继续保留。

用量从权威 terminal task 和 usage ledger 结算一次。Goal snapshot 报告 input、output、reasoning、cache-read、cache-write 和 total token。provider usage-limit 会把 active Goal 转为 usage_limited；普通 failure 或 timeout 会使其 blocked，而不会重放 turn。

紧急停止与回滚

设置 kill switch 并重启 Gateway，可在不删除 Goal 状态的情况下停止新 Goal 执行：

[goal]
execution_enabled = false

启动时 active Goal 会以 feature_disabled 转为 paused；没有 Goal retry timer 或启动时全局自动入队。status、edit、pause 和 clear 仍可用。重新启用并重启后，需要连接到 session 并明确 resume。

这是受支持的非破坏性运维回滚。不要把 binary downgrade 当成数据库回滚；降级前备份 session database，并遵循目标版本的迁移说明。

旧实验性设置（idle nudge、blocked/failure retry、retry backoff/polling、无人值守 continuation、watcher TTL）已不再控制行为，应从本地配置删除。Goal schema 通过正常 session database migration 应用；升级后仅有持久状态不会自动恢复执行，重启后仍需明确 resume 和新的 execution lease。

客户端 RPC contract

Gateway client 使用以下 session-scoped method：

goals.capabilities
goals.set
goals.status
goals.edit
goals.pause
goals.resume
goals.reattach
goals.clear

每个持久 mutation 都携带客户端生成的规范 UUID v4 clientRequestId。goals.reattach 只修改进程内执行权限，使用严格的 session-generation 与 Goal fence，不写 command receipt，也不重置 guardrail counter。

goals.set 另带 UUID v4 clientMessageId；edit、pause、resume、clear 携带最后观察到的 expectedGoalId 与 expectedStateRevision。用相同 request identity 和规范化 payload 重试会返回已保存 response；同 identity 配不同 payload 返回 IDEMPOTENCY_CONFLICT。

接受的 mutation 会返回 request identity、session generation、适用的 task/user-message/previous-Goal identity 和当前 Goal snapshot。客户端应直接合并 snapshot，不要为正确性再轮询。

稳定冲突码包括：

INVALID_GOAL_OBJECTIVE
GOAL_ACTIVE
GOAL_NOT_FOUND
GOAL_BUSY
STALE_GOAL
SESSION_GENERATION_CHANGED
PLAN_MODE_ACTIVE
PLAN_RUN_ACTIVE
EXECUTION_LEASE_REQUIRED
GOAL_NOT_RESUMABLE
GOAL_EXECUTION_DISABLED
IDEMPOTENCY_CONFLICT

权限允许时，stale、active 和 busy conflict 可包含当前 snapshot，使 UI 无需额外 status request 即可收敛。

事件、重连与隐私安全诊断

客户端通过 mutation response、hydrate snapshot 和单一 session.event.goal event stream 收敛，不依赖正确性轮询或 watcher heartbeat。session generation、stream sequence、state revision 和 progress revision fence 会阻止旧 hydrate、replay、task 或 callback 覆盖新状态。

Goal 诊断只使用有界结构化字段，如 command action/outcome、defer class、terminal state、guardrail class、turn 数、active duration 和 token 数。目标文本、progress 文本、blocked reason、助手输出、route authority 和凭据不得写入 Goal metric。

排障时请记录 /goal status、session key、非敏感 reason code 和相关 Gateway log event name。除非内容为合成或已完全脱敏，否则不要把目标或 transcript 粘贴到公开 issue。

配置 · Session · Web UI · 终端 UI · 用量与成本 · 故障排查