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