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.
This commit is contained in:
Turtle
2026-08-12 19:52:04 +08:00
parent a204970725
commit 30b2a04b69
8 changed files with 36 additions and 32 deletions

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)。