kevin/deepseek-harness
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Turtle
2026-08-12 21:03:15 +08:00
parent a204970725
commit 30b2a04b69
8 changed files with 36 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/agent-lifecycle.i18n.yaml
+2 -2
View File
@@ -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
docs/agent-lifecycle.md
+3 -3
View File
@@ -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
```
docs/agent-lifecycle.zh.md
+3 -3
View File
@@ -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
```
docs/architecture.i18n.yaml
+2 -2
View File
@@ -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
docs/architecture.md
+11 -9
View File
@@ -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).
docs/architecture.zh.md
+11 -9
View File
@@ -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)。
docs/subsystems/llm-streaming.i18n.yaml
+1 -1
View File
@@ -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
scripts/gen-doc-graphs.ts
+3 -3
View File
@@ -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`,
'```',
'',