自学教程

DeepSeek Harness 会话日志与轮次生命周期

DeepSeek Harness

会话（Session）是 DeepSeek Harness 承载一次 Agent 交互的顶层容器；轮次（Turn）是会话内部 LLM 与工具交互的单次交互单元。会话日志负责持久化存储每一轮的消息、工具调用、审批记录、沙箱事件；轮次生命周期定义了一轮交互从发起、推理、工具调用到结束的完整状态流转。理解会话与轮次生命周期，是做会话持久化、回溯调试、多轮Agent编排的基础。

一句话区分：会话 = 完整对话项目；轮次 = 用户/模型一次往返交互；会话日志 = 全链路可回放的事件记录。

一、会话 Session：顶层上下文容器

一个会话代表一组连续交互，独立拥有上下文、工作目录、会话级权限、沙箱状态、日志存储。

1. 会话核心属性

  • sessionId：会话唯一标识，用于索引、持久化、日志检索
  • title：会话标题，可由模型自动生成或手动设置
  • createdAt / updatedAt：创建时间、最后更新时间
  • workspace：会话独立工作目录，沙箱的默认隔离目录
  • state：会话状态：active（进行中） / archived（归档） / deleted（已删除）
  • config：会话独立配置，可继承 Profile 全局配置，支持会话级权限覆盖

2. 会话日志存储范围

会话日志会持久化保存会话内所有轮次的完整事件，不只保存LLM对话文本，包含：

  1. 用户消息、模型消息（含思维链内容）
  2. 工具调用请求、参数、返回结果、异常堆栈
  3. 权限门禁校验记录、审批事件、用户审批选择
  4. 沙箱启动、销毁、权限升级事件
  5. 事件系统自定义埋点、插件输出的审计信息

日志支持两种存储后端：内置本地文件存储、数据库插件存储，可在Profile配置切换。

二、轮次 Turn：单次交互单元与完整生命周期

一轮（Turn）由用户输入触发，模型推理、执行工具、返回结果，构成一轮闭环。

一轮内可以包含多段工具调用（多工具串行执行），但同属同一个Turn。

轮次完整生命周期（6个状态）

  1. pending 待启动 Pending
    用户提交消息，创建Turn实例，写入会话日志；加载会话上下文，准备发起LLM推理。

此时还未向大模型发送请求。

  1. inferring 模型推理 Inferring
    将历史会话上下文提交LLM，开始流式接收StreamChunk返回内容。
  • 普通文本：直接追加到消息
  • 识别工具调用：进入工具执行分支
  1. toolInvoking 工具调用中 Tool Invoking
    进入工具执行流水线：前置钩子 → 权限门禁 → 审批校验 → 参数校验 → 沙箱执行。
    同一轮内可连续执行多个工具，所有工具事件全部记录到本轮日志。
    任意工具触发审批，本轮暂停，进入等待用户决策状态。
  2. awaitUserConfirm 等待用户确认 Await User Confirm
    审批弹窗触发，轮次暂停，保存当前轮次快照。
    用户操作前，模型不会继续推理；用户同意/拒绝后，恢复本轮流水线。
  3. generating 结果生成 Generating
    所有工具执行完成，模型基于工具返回结果，继续生成最终回复文本。
  4. completed / failed 完成/失败 Completed / Failed
  • completed：本轮交互正常结束，写入结束标记，会话更新updatedAt
  • failed：发生不可恢复异常，记录错误堆栈，标记轮次失败，会话保持active状态，可继续发起新轮次

重要规则：一轮结束，才会开启下一轮；一轮内部可以多次调用工具，不产生新轮次。

轮次日志数据结构

每一条轮次日志会绑定 turnId，关联所属 sessionId，日志条目类型分为：

  • message：消息（用户、助手）
  • tool_call：工具调用请求
  • tool_result：工具返回结果
  • approval_event：审批事件
  • sandbox_event：沙箱启停/权限变更事件
  • error：异常事件

三、会话与轮次的关系

  1. 一个会话包含多个轮次；轮次从属于单个会话，不能跨会话。
  2. 上下文窗口以会话为单位，每一轮的消息追加到会话上下文。
  3. 会话级资源（工作目录、会话权限）在整个会话生命周期复用；沙箱实例可在轮次之间复用或按需销毁，由沙箱插件配置控制。
  4. 删除单条轮次日志：仅删除本轮记录，保留会话；归档会话：冻结全部轮次，不再允许新增轮次。

四、会话日志能力：回放、断点、调试

1. 会话回放

基于完整会话日志，可以完整复现整轮交互，包含工具调用、审批弹窗、沙箱事件，用于调试Agent行为、复现bug。

回放模式可选择是否真实执行工具：dry-run模式只读取日志，不执行真实沙箱；run模式重跑工具。

2. 断点续交互

支持基于历史轮次快照，从任意历史轮次位置继续对话，截断后续消息，重新开始推理。适合多轮调试、分支实验。

3. 日志检索

可按sessionId、turnId、时间范围、工具名称、事件类型检索日志，插件可订阅日志写入事件，对接外部审计平台。

五、配置示例（cordis.patch.yml）

session:
  defaultTtl: 30d          # 会话默认保留时长
  log:
    storage: file          # 存储后端 file / db
    keepRawChunk: true     # 保存StreamChunk原始流式分片
    auditAllApproval: true # 记录全部审批事件
  sandbox:
    reuseBetweenTurn: true # 轮次之间复用沙箱实例

六、开发：日志订阅事件

插件可通过事件系统监听会话、轮次生命周期事件，实现自定义日志上报：

// 监听轮次完成事件
ctx.events.on("turn:completed", (payload) => {
  console.log("轮次结束", payload.sessionId, payload.turnId);
  // 自定义上报到外部日志系统
})// 监听会话归档事件
ctx.events.on("session:archived", (payload) => {
  // 会话归档回调
})

核心事件列表：

  • session:create 会话创建
  • session:archive 会话归档
  • turn:start 轮次启动
  • turn:toolInvoke 轮次内调用工具
  • turn:awaitConfirm 轮次等待审批
  • turn:completed 轮次正常完成
  • turn:failed 轮次异常失败

七、常见问题排查

  1. 工具调用记录没有出现在会话日志
    排查：确认日志配置 keepRawChunk 开启；工具执行是否被权限门禁直接拦截（被门禁直接拒绝的请求依然会写入审计日志）。
  2. 回放会话时，工具不会自动执行
    排查：默认dry-run模式，只读取日志；需要开启run模式才会重新执行沙箱工具。
  3. 新建轮次，无法读取上一轮文件
    排查：沙箱未开启轮次复用；每轮结束销毁沙箱实例，文件仅保存在会话持久化工作区。
  4. 会话被自动归档
    排查：到达defaultTtl会话过期时间；可修改TTL或者手动取消归档。

八、最佳实践

  1. 生产环境开启完整审计日志，记录所有审批、工具调用事件，便于安全审计。
  2. 长期运行Agent会话，定期归档不活跃会话，减少内存与存储占用。
  3. 调试Agent逻辑，优先使用会话回放功能，复现问题，不用反复手动重跑对话。
  4. 敏感业务场景，日志开启脱敏，自动过滤密钥、Token等敏感信息。
  5. 轮次内大量工具调用场景，控制单轮工具调用上限，防止无限循环调用工具。

小结

  • 会话 Session：顶层交互容器，拥有独立工作目录、会话配置与完整日志，支持归档与持久化。
  • 轮次 Turn：会话内部单次交互生命周期单元，一轮可包含多次工具调用，存在等待审批的暂停状态。
  • 会话日志：记录全链路事件，支持检索、断点续对话、会话回放，是调试与审计的核心载体。
    会话、轮次、日志体系，和前面的工具流水线、权限门禁、沙箱审批串联，构成完整Agent运行时。
标签：

0 条笔记