AgentKit Studio
参考

会话事件

16 个 DSH 会话事件与 3 个助手流帧:何时触发、如何配对、哪些会落库。

事件词表

Studio Host 投影消费 16 个 DSH 会话事件,另有 3 个进程内助手流帧。事件名是 DSH 的稳定词表,Studio 不新增、不改名。

事件家族触发时机源码
turn/startturn一轮开始:用户消息被接纳,模型轮次开始。src/host/dsh-session-contract.mjs:3
turn/endturn一轮结束:携带终态与用量。src/host/dsh-session-contract.mjs:4
step/startstep一个 step 开始:模型一次输出到工具调用的边界。src/host/dsh-session-contract.mjs:5
step/endstep一个 step 结束。src/host/dsh-session-contract.mjs:6
system/messagesystem系统消息注入:策略、上下文或指令。src/host/dsh-session-contract.mjs:7
request/headerrequest请求头:模型、路由与协议版本。src/host/dsh-session-contract.mjs:8
request/contextrequest请求上下文:工作区、执行策略与冻结运行时。src/host/dsh-session-contract.mjs:9
user/messageuser用户消息。src/host/dsh-session-contract.mjs:10
assistant/messageassistant助手消息:一轮的最终输出。src/host/dsh-session-contract.mjs:11
assistant/attemptassistant一次尝试:重试时同一轮会有多条。src/host/dsh-session-contract.mjs:12
tool/calltool工具调用请求,携带调用 id。src/host/dsh-session-contract.mjs:13
tool/resulttool工具结果,用调用 id 与请求配对。src/host/dsh-session-contract.mjs:14
approval/askedapproval审批请求:工具需要在执行前获得授权。src/host/dsh-session-contract.mjs:15
approval/decidedapproval审批决策:允许、拒绝或超时。src/host/dsh-session-contract.mjs:16
agent/inbox/splicedagentAgent 收件箱被插入新事件(并发消息)。src/host/dsh-session-contract.mjs:17
agent-preset/selectedagent-preset会话选中了某个 Agent 预设。src/host/dsh-session-contract.mjs:18

家族分布

事件名以第一个斜杠分段。家族决定了投影层的处理顺序。

家族条数事件
turn2turn/start turn/end
step2step/start step/end
system1system/message
request2request/header request/context
user1user/message
assistant2assistant/message assistant/attempt
tool2tool/call tool/result
approval2approval/asked approval/decided
agent1agent/inbox/spliced
agent-preset1agent-preset/selected

助手流帧

进程内的助手流只有三种帧,按 start → chunk* → end 顺序出现。它们不落库,只用于流式渲染。

帧源码
startsrc/host/dsh-session-contract.mjs:22
chunksrc/host/dsh-session-contract.mjs:22
endsrc/host/dsh-session-contract.mjs:22

顺序与配对

turn/start → request/header → request/context → step/start
  → assistant/attempt → (tool/call → approval/asked → approval/decided → tool/result)*
  → step/end → assistant/message → turn/end
事件顺序规则
turn/start一轮的唯一起点。
turn/end唯一保证出现的终止事件;缺失表示连接中断。
step/start一个 step 内至少一次 assistant/attempt。
step/end与 step/start 一一配对。
system/message可出现在任意位置,不改变轮次状态。
request/header紧跟 turn/start,每轮一次。
request/context紧跟 request/header。
user/message通常在一轮开头出现一次。
assistant/message每轮最多一条,取最后一次尝试。
assistant/attempt重试时同一轮会出现多条。
tool/call按调用 id 与 tool/result 配对。
tool/result必须在对应的 tool/call 之后。
approval/asked只在工具需要授权时出现。
approval/decided必须与 approval/asked 配对。
agent/inbox/spliced表示并发写入,投影需按序合并。
agent-preset/selected通常出现在一轮开始之前。

版本与兼容性

项值说明
会话事件16DSH 词表子集,不可自行扩展
流帧3start / chunk / end
家族数10按第一个斜杠分段
持久化仅会话事件流帧不落库

开发者入口

内容源码位置
会话事件词表src/host/dsh-session-contract.mjs
运行时契约src/runtime-contract.mjs
会话适配src/session-adapter.mjs
原生轮次契约packages/harness/src/native/dsh-turn-contract.ts

相关测试:

测试文件位置
runtime-contract.test.mjstests/runtime-contract.test.mjs
session-adapter.test.mjstests/session-adapter.test.mjs

本页导航