AgentKit Studio
概念

会话与工作区

会话是 DSH 拥有的持久事件日志,工作区是会话绑定的目录。两者分别决定「历史存在哪」和「能写哪里」。

会话(session)是一条 DSH 拥有的持久事件日志;工作区(workspace)是这条会话绑定的目录。前者回答「历史存在哪」,后者回答「Agent 能写哪里」。

这两个概念经常被合成一句「会话就是一次对话」,但它们的生命周期、所有权和失败方式都不同。这一页分别讲清,再说明两者如何交汇在同一次运行上。

为什么必须分开

问题归会话管归工作区管
刷新页面后历史还在吗✅ 事件日志在宿主持久化—
Agent 能改哪些文件—✅ 目录边界决定写入范围
同一个 Agent 的两个会话会互相污染吗❌ 各自独立的事件序列❌ 可以指向不同目录
换一台机器还能继续吗取决于持久化后端取决于目录是否随行

把两者混为一谈,最典型的误判是以为「新建会话就换了工作目录」。新建会话只是开了一条新的事件序列,目录由工作区绑定决定。

会话:日志归 DSH 所有

Studio 不拥有转录。它只做四件事:校验身份、投影一种已证明的消息形状、把不支持的事实保留为可忽略事件、以及提供分页窗口。

所有权边界

持久日志、节点装配器、远程通道与渲染器都归 DSH。Studio 的会话适配器是一条窄边界,不是第二份存储。

16 个事件类型

类别事件
轮次turn/start、turn/end
步骤step/start、step/end
消息system/message、user/message、assistant/message、assistant/attempt
工具tool/call、tool/result
审批approval/asked、approval/decided
请求request/header、request/context
编排agent/inbox/spliced、agent-preset/selected

除事件外还有 3 个进程内流帧:start、chunk、end。流帧是增量,不是事件;它们不写进持久日志。

事件的规范信封

每条事件都必须带齐这些字段,缺一项就不能进入投影:

字段约束
event_id非空字符串
event_type非空字符串
run_id非空字符串
scope_id非空字符串
seq非负安全整数
timestamp非负有限数
schema_version必须等于 2

冲突处理是拒绝而不是覆盖:同一个 event_id 出现两次但内容不同,报「事件在重放期间被修改」;两个不同 event_id 抢同一个 seq,也报错。内容完全相同的重复事件是幂等的,直接跳过。

官方类型与可忽略类型

11 个事件是「官方类型」,会被渲染成正常的聊天节点。其余类型一律加上 ksadk/ 前缀,并标记为可忽略——宿主不认识的事实被保留下来,但不会破坏会话界面。这条规则让新事件可以在不改渲染器的情况下先落地。

还有一个专门的防护:一个 run 结束之后才到达的事件(历史分页与重连尾部的乱序)会被降级成可忽略类型。否则一条迟到的事件会被投影进聊天,看起来像模型在结束后又说了话。

瞬时帧:只给客户端,不给日志

未完成的助手消息需要实时增量。它用 assistant/live-chunk 帧表达,并且带一个分数序号(seq + 0.5)——表示「排在两条持久事件之间」。

特性持久事件瞬时帧
进事件日志✅❌ 永不
出现在快照接口✅只出现在客户端窗口
序号整数分数(n + 0.5)
用途事实来源打字机效果

这条分界线是硬性的:如果瞬时帧被写进持久日志,重连重放时会看到重复文本。

会话标识与版本

项值
会话契约p1-session-contract-v0.1
历史契约版本2
持久化后端dsh-native-disk
跨 Pod 共享否
活跃运行可恢复否(历史可读,未完成的 turn 不自动续跑)
会话 ID 非法RUNTIME_SESSION_ID_INVALID
会话 ID 冲突RUNTIME_SESSION_ID_CONFLICT

会话的所有权属于 Agent 状态,不属于部署版本状态。这意味着更新部署版本不会让已有会话消失——会话目录在版本目录之外。

工作区:目录边界

工作区就是会话绑定的当前目录。默认取宿主进程的工作目录,可以用环境变量覆盖。它不是抽象概念,而是一条真实的路径边界:

场景行为
默认宿主进程的工作目录
由环境变量指定该值被解析成绝对路径后作为边界
本地 Star Harness 会话找不到工作区路由NATIVE_ENGINE_WORKSPACE_UNAVAILABLE,提示选择已配置的工作区
执行策略为 read-only拒绝一切写入
执行策略为 workspace-write允许写入工作区内部
执行策略为 danger-full-access允许写入工作区之外

工作区还带一条状态根隔离规则:命令状态、A2A 状态、浏览器状态等的根目录既不能是工作区本身,也不能位于工作区内部,更不能包含工作区。状态按「Agent + 工作区摘要 + 会话」三层分片,所以两个 Agent 的两个会话之间不会共享读改写状态。

两个概念如何交汇

一次运行同时需要两边:

参与方提供什么缺了会怎样
会话sessionId、事件序列、历史分页无法定位运行
工作区当前目录、写入边界无法执行工具
修订版本agentId、revision无法确定用哪份定义
构建buildId无法复现

四个来源齐全才构成一次合法运行,见 Agent · Revision · Build · Run。

硬规则

  1. Studio 不写会话日志。它只投影 DSH 的事件,写日志是 DSH 的职责。
  2. 瞬时帧永远不进持久日志。分数序号只用于客户端排序。
  3. schema_version 必须等于 2,其他版本直接拒绝,不做兼容推断。
  4. 非官方事件类型必须可忽略。未知事实可以保留,不能破坏界面。
  5. 工作区是一条路径边界,不是命名空间。换目录等于换边界。
  6. 状态根与工作区必须互不包含,否则读改写状态会污染工作区。

相关任务

相关参考

你要查的东西去哪一页
16 个事件与 3 个流帧的字段会话事件
RUNTIME_*、SESSION_* 错误码错误码
24 个 sessions/* operation控制协议
工作区与执行策略相关环境变量环境变量

本页导航