diff --git a/docs/subsystems/plan.i18n.yaml b/docs/subsystems/plan.i18n.yaml index 7c20a42864..3295167755 100644 --- a/docs/subsystems/plan.i18n.yaml +++ b/docs/subsystems/plan.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/plan.md -plan.md: eb88047573536cd15be587b1419271bfbd93e9f1 -plan.zh.md: 5a838a045d63f2cabad80cad8af12df5da7e87f3 +plan.md: c8bb6c9b6a0bcfd20ed6eadece4552d49f3c757c +plan.zh.md: c8acedaef0724581227b57afbf81418a7e538aed diff --git a/docs/subsystems/plan.md b/docs/subsystems/plan.md index eb88047573..c8bb6c9b6a 100644 --- a/docs/subsystems/plan.md +++ b/docs/subsystems/plan.md @@ -10,9 +10,9 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/s `plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace [session event](session.md): durable and replayable, never in the model transcript. `foldPlanMode(events, end?)` returns the last logged value in the prefix, or `false` when there is none — the state in force is always a pure fold of the session log, so resume, fork, and compaction recover it with no live mirror, and UIs observe committed flips through `session/event`. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md). -## Pending intent and the turn-boundary flush +## Pending intent and the step-boundary flush -Because every session event is turn-enclosed, a user selection is held as pending intent until a turn boundary. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary. +Because every session event is turn-enclosed, a user selection is held as pending intent until the next step boundary — within the same turn when one is open. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary. The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception seam that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)). diff --git a/docs/subsystems/plan.zh.md b/docs/subsystems/plan.zh.md index 5a838a045d..c8acedaef0 100644 --- a/docs/subsystems/plan.zh.md +++ b/docs/subsystems/plan.zh.md @@ -10,9 +10,9 @@ `plan/mode`（`{ active: boolean }`）是仅记日志、整值替换的[会话事件](session.md)：持久且可回放，绝不进入模型 transcript（文本记录）。`foldPlanMode(events, end?)` 返回前缀中最后一条已记录值，没有时返回 `false`：生效状态始终是会话日志的纯折叠，因此恢复、fork 与压缩（compaction）无需实时镜像即可将其复原，UI 通过 `session/event` 观察已提交的切换。完整事件声明见[持久化日志事件目录](../persistence-catalog.md)。 -## 待定意图与轮次边界冲刷 +## 待定意图与步骤边界冲刷 -由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到轮次边界。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。 +由于每个会话事件都位于轮次之内，用户的选择会作为待定意图保留到下一个步骤边界——已有轮次开启时即在同一轮次之内。`set(agent, active)` 记录待定选择（目标值与已记录或已在待定中的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`，即影响当前步骤的已记录状态，加上正在等待边界的乐观选择。 唯一的冲刷点是一个前置（prepend）注册的 `agent/step` 监听器——agent loop 的轮内拦截 seam，在每次请求派生之前运行，包括第 1 轮第 1 步和请求恢复重试。提示词提交本身绝不冲刷：它发生在轮次开启之前，此时追加 `plan/mode` 会落在任何开启的轮次之外，因此在提示词处做出的选择由它开启的轮次内的第一个步骤边界落地。前置注册意味着冲刷先于下游的 `agent/step` 监听器链运行。冲刷失败会被收容（计划策略绝不能阻塞轮次），追加失败的选择保持待定，等待后续边界。已冲刷的用户选择还会以一条插件来源的 `user/message` 通知叙述这次切换，但仅当最后记录的请求头描述的是另一种状态时才叙述，因此模型恰好在上下文变化时被告知，且绝不重复。空闲时做出的待定选择只存在于进程内，进程在下一个边界之前退出即丢失（[README 限制](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)）。