docs: correct the turn-flow event order and dispatch modes

turn/start precedes the first claim and pre-step, a rejected or empty first claim closes a zero-step turn, llm/stream and tools/* are their own domains, and agent/turn-stopping is serial. Regenerates the lifecycle diagram from the same facts and names --patch overlays exactly.
2026-08-15 21:04:50 +00:00 · 2026-08-12 19:52:04 +08:00
parent a204970725
commit 30b2a04b69
8 changed files with 36 additions and 32 deletions
--- a/docs/agent-lifecycle.i18n.yaml
+++ b/docs/agent-lifecycle.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/agent-lifecycle.md
-agent-lifecycle.md: 8bdf54b0345e539ca415eec108fd58ace70ba72c
-agent-lifecycle.zh.md: ad6f2ec1f9e7d2e336b79a10e85736d096b784fb
+agent-lifecycle.md: 84e235563d05d8105c55f9dc40ac0d791bd05dce
+agent-lifecycle.zh.md: df6fe19385f16477d60da260d72477a19526e686
--- a/docs/agent-lifecycle.md
+++ b/docs/agent-lifecycle.md
@@ -21,15 +21,15 @@ sequenceDiagram
  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
  Agent->>Driver: queued work wakes driver
  Driver-->>SDK: <code>agent/status</code> running
+  Driver->>Session: <code>turn/start</code>
  Note over Agent,Driver: claim pending next-step input plus one queued prompt
  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
  Driver->>Hooks: <code>agent/pre-step</code> waterfall
  Hooks-->>Driver: authoritative reject or enter(messages)
  alt proposed step rejected or pre-step failed
-    Driver-->>Driver: claimed batch stays removed, no turn opens
+    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
  else enter proposed step
-  Driver->>Session: <code>turn/start</code>
  Driver->>Session: <code>step/start</code>
  Driver->>Session: <code>user/message</code> per entered message
  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
@@ -66,8 +66,8 @@ sequenceDiagram
    Hooks-->>Driver: authoritative reject or enter(messages)
  end
  end
-  Driver->>Session: <code>turn/end</code>
  end
+  Driver->>Session: <code>turn/end</code>
  Driver-->>SDK: <code>agent/status</code> idle
 ```

--- a/docs/agent-lifecycle.zh.md
+++ b/docs/agent-lifecycle.zh.md
@@ -23,15 +23,15 @@ sequenceDiagram
  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
  Agent->>Driver: queued work wakes driver
  Driver-->>SDK: <code>agent/status</code> running
+  Driver->>Session: <code>turn/start</code>
  Note over Agent,Driver: claim pending next-step input plus one queued prompt
  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
  Driver->>Hooks: <code>agent/pre-step</code> waterfall
  Hooks-->>Driver: authoritative reject or enter(messages)
  alt proposed step rejected or pre-step failed
-    Driver-->>Driver: claimed batch stays removed, no turn opens
+    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
  else enter proposed step
-  Driver->>Session: <code>turn/start</code>
  Driver->>Session: <code>step/start</code>
  Driver->>Session: <code>user/message</code> per entered message
  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
@@ -68,8 +68,8 @@ sequenceDiagram
    Hooks-->>Driver: authoritative reject or enter(messages)
  end
  end
-  Driver->>Session: <code>turn/end</code>
  end
+  Driver->>Session: <code>turn/end</code>
  Driver-->>SDK: <code>agent/status</code> idle
 ```

--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.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/architecture.md
-architecture.md: b88bae1c35ae4c286ac1b591c7857012ab065cd7
-architecture.zh.md: 63e39a4ea02d4794dd13d5a599ae6d1b563ecd95
+architecture.md: e0909c7924fcb9a8b29b3a3426c847e9ca7f4dfb
+architecture.zh.md: b35088aa2a00623eacb2d53b19c86d9c192cd1d0
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -24,7 +24,7 @@ Each declares itself in its own `package.json` under a `dsh` field: `dsh.profile

 [`dsh-base`](../packages/bundle/base/README.md) is the first layer of every profile: model adapters, tools, persistence, sandbox and approval policy, settings, credentials, telemetry. [`dsh-web-app`](../packages/bundle/web-app/README.md) adds the browser application; [`dsh-headless`](../packages/bundle/headless/README.md) adds a one-shot runner with no server at all.

-Layers apply to an empty entry list in this order: each bundle in the profile's listed order, then the profile's `cordis.patch.yml`, then the home-level one, then any app overlay. A patch targets a row by id and replaces its whole config, or inserts new rows.
+Layers apply to an empty entry list in this order: each bundle in the profile's listed order, then the profile's `cordis.patch.yml`, then the home-level one, then any `--patch` overlay. A patch targets a row by id and replaces its whole config, or inserts new rows.

 To see the tree your machine actually boots:

@@ -62,28 +62,30 @@ The [event map](event-producer-consumer.md) lists every event's producers and co

 ## Turn flow

-A **step** is one model request plus the tools it calls. A **turn** is one or more steps, opened from queued input and closed once nothing is owed.
+A **step** is one model request plus the tools it calls. A **turn** is zero or more steps: it opens before its first input is claimed and closes once nothing is owed.

 ```text
-claim next-step input plus one queued message
-  -> agent/pre-step            reject | enter(messages)
-  -> turn/start
+turn/start
+  claim next-step input plus one queued message
+  assemble prompt sections + tool schemas
+  -> agent/pre-step                   reject | enter(messages)
+     reject, or a first enter rewritten empty -> close the turn with no step
     step/start
     append entered messages as user/message
-     assemble prompt sections + tool schemas, derive history from the log
+     derive model history from the log
     agent/request -> llm/stream -> assistant/chunk* -> assistant/message
     tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*
     step/end
     tools owe another request, or next-step input arrived -> claim -> next step
  -> agent/turn-stopping
-  -> turn/end
+turn/end
 ```

-`turn/*`, `step/*`, `user/message`, `assistant/*`, and `tool/*` are durable session events; the rest are live `agent/*` waterfalls, whose listeners must call `next()` to delegate.
+`turn/*`, `step/*`, `user/message`, `assistant/*`, and `tool/*` are durable session events; the rest are live extension points across three domains. `agent/pre-step`, `agent/request`, `llm/stream`, and the three `tools/*` events are waterfalls, whose listeners must call `next()` to delegate; `agent/turn-stopping` is serial and has no `next()`.

 Input reaches the driver through one inbox. Some messages wake it immediately; injected context waits in the inbox until another message does.

-`agent/pre-step` decides what the model sees. Listeners may rewrite the claimed messages or reject them outright, and a rejected attempt still opens and closes a durable turn, so the log records it. Each step then assembles what the model reads from the prompt sections and tool schemas that plugins registered.
+`agent/pre-step` decides what the model sees. Listeners may rewrite the claimed messages or reject them outright; a rejected or empty first claim still closes a durable turn that spent no step, so the log records the attempt. Each step reads the prompt sections and tool schemas that plugins registered.

 Details: the [sequence diagram](agent-lifecycle.md), the [tool pipeline](tool-execution-pipeline.md), and [cancellation and error recovery](subsystems/core.md#the-agent-handle).

--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -24,7 +24,7 @@

 [`dsh-base`](../packages/bundle/base/README.md) 是每个 profile 的第一层：模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测。[`dsh-web-app`](../packages/bundle/web-app/README.md) 增加浏览器应用；[`dsh-headless`](../packages/bundle/headless/README.md) 增加一次性运行器，且完全不带服务器。

-各层按此顺序应用在空条目列表之上：先按 profile 列出的顺序应用每个组合包，然后是 profile 的 `cordis.patch.yml`，然后是 home 级的那份，最后是任意应用 overlay。一条 patch 按 id 定位某个条目并替换其整个 config，或插入新条目。
+各层按此顺序应用在空条目列表之上：先按 profile 列出的顺序应用每个组合包，然后是 profile 的 `cordis.patch.yml`，然后是 home 级的那份，最后是任意 `--patch` overlay。一条 patch 按 id 定位某个条目并替换其整个 config，或插入新条目。

 要查看你的机器实际启动的配置树：

@@ -62,28 +62,30 @@ dsh --profile web --dump-config

 ## 轮次流程

-一个**步骤**是一次模型请求加上它调用的工具。一个**轮次**包含一个或多个步骤，由已排队的输入打开，并在不再欠下任何工作时关闭。
+一个**步骤**是一次模型请求加上它调用的工具。一个**轮次**包含零个或多个步骤：它在领取首条输入之前打开，并在不再欠下任何工作时关闭。

 ```text
-claim next-step input plus one queued message
-  -> agent/pre-step            reject | enter(messages)
-  -> turn/start
+turn/start
+  claim next-step input plus one queued message
+  assemble prompt sections + tool schemas
+  -> agent/pre-step                   reject | enter(messages)
+     reject, or a first enter rewritten empty -> close the turn with no step
     step/start
     append entered messages as user/message
-     assemble prompt sections + tool schemas, derive history from the log
+     derive model history from the log
     agent/request -> llm/stream -> assistant/chunk* -> assistant/message
     tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*
     step/end
     tools owe another request, or next-step input arrived -> claim -> next step
  -> agent/turn-stopping
-  -> turn/end
+turn/end
 ```

-`turn/*`、`step/*`、`user/message`、`assistant/*` 和 `tool/*` 是持久会话事件；其余是实时的 `agent/*` waterfall（瀑布式事件），其监听器必须调用 `next()` 才能委托下去。
+`turn/*`、`step/*`、`user/message`、`assistant/*` 和 `tool/*` 是持久会话事件；其余是分属三个事件域的实时扩展点。`agent/pre-step`、`agent/request`、`llm/stream` 和三个 `tools/*` 事件是 waterfall（瀑布式事件），其监听器必须调用 `next()` 才能委托下去；`agent/turn-stopping` 是 serial 事件，没有 `next()`。

 输入通过同一个 inbox 到达驱动器。有些消息会立即唤醒它；注入的上下文会留在 inbox 中，直到另一条消息将其唤醒。

-`agent/pre-step` 决定模型看到什么。监听器可以改写已领取的消息，也可以直接拒绝它们，而被拒绝的尝试仍会打开并关闭一个持久轮次，因此日志会记录它。随后每个步骤都会用插件注册的提示词片段和工具 schema 组装模型读到的内容。
+`agent/pre-step` 决定模型看到什么。监听器可以改写已领取的消息，也可以直接拒绝它们；首次领取被拒绝或被改写为空时，仍会关闭一个不含步骤的持久轮次，因此日志会记录这次尝试。每个步骤读取插件注册的提示词片段和工具 schema。

 详情见[时序图](agent-lifecycle.md)、[工具流水线](tool-execution-pipeline.md)和[取消与错误恢复](subsystems/core.md#the-agent-handle)。

--- a/docs/subsystems/llm-streaming.i18n.yaml
+++ b/docs/subsystems/llm-streaming.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md
 llm-streaming.md: 6b3b539fd874857f2b5e94cc05ee68ac4a1d0fb7
-llm-streaming.zh.md: d42699a27057d96b828bb902b02d10e6df9da3e3
+llm-streaming.zh.md: d5bf02c20ead8a574075d996540efba427fe75ce
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -1213,15 +1213,15 @@ function renderLifecycle(): string {
    `  Agent-->>SDK: ${mermaidCode('agent/inbox/inserted')} { message }`,
    '  Agent->>Driver: queued work wakes driver',
    `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
+    `  Driver->>Session: ${mermaidCode('turn/start')}`,
    '  Note over Agent,Driver: claim pending next-step input plus one queued prompt',
    `  Driver-->>SDK: ${mermaidCode('agent/inbox/spliced')} pure deletion`,
    `  Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
    `  Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
    '  Hooks-->>Driver: authoritative reject or enter(messages)',
    '  alt proposed step rejected or pre-step failed',
-    '    Driver-->>Driver: claimed batch stays removed, no turn opens',
+    '    Driver-->>Driver: claimed batch stays removed, the open turn spends no step',
    '  else enter proposed step',
-    `  Driver->>Session: ${mermaidCode('turn/start')}`,
    `  Driver->>Session: ${mermaidCode('step/start')}`,
    `  Driver->>Session: ${mermaidCode('user/message')} per entered message`,
    `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
@@ -1258,8 +1258,8 @@ function renderLifecycle(): string {
    '    Hooks-->>Driver: authoritative reject or enter(messages)',
    '  end',
    '  end',
-    `  Driver->>Session: ${mermaidCode('turn/end')}`,
    '  end',
+    `  Driver->>Session: ${mermaidCode('turn/end')}`,
    `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
    '```',
    '',