feat(agent): 持久化 Agent Trace 并支持 SSE 断点恢复 #7

2026-09-01T10:36:29+08:00

Kronecker commented

2026-09-01 10:36:29 +08:00

背景

第一阶段 Agent Run 和 Event 只保存在进程内存中。服务重启后历史运行记录会丢失，SSE 连接中断后也无法从指定位置继续消费事件，无法满足第二阶段 Agent Trace 可视化和 Benchmark 对稳定运行事实的需求。

本次改动将 Agent Run/Event 接入 SQLite，并建立可分页、可恢复、可供前端与 Benchmark 共用的 Trace 数据链路。

主要改动

Agent Trace 持久化

新增 AgentTraceRepository
新增 SQLite v3 migration：
- agent_runs
- agent_events
使用 run_id + sequence 作为事件幂等键
Run 列表、详情和 Trace 支持进程重启后读取
未完成的历史 Run 在重启后收束为 AGENT_PROCESS_RESTARTED

SSE 断点恢复

SSE 帧增加 id: sequence
支持 Last-Event-ID 请求头
支持 after_sequence 查询参数
先回放持久化历史，再切换到实时订阅
历史和实时事件按 sequence 去重
非法游标返回 TRACE_CURSOR_INVALID

Trace 接口

新增：

GET /api/agent/runs/{run_id}/trace

支持：

after_sequence
limit
分页事件列表
next_sequence
has_more
模型调用次数
Tool 调用次数
执行耗时
Token Usage
错误数量
创建 Run 时的配置快照

Agent Event 扩展

新增事件：

ModelCallStarted
ModelCallCompleted
ModelCallFailed
PermissionResolved

Tool Call 和 Tool Result 增加：

parent_model_call_id
duration_ms

持久化安全与完整性

API Key、Authorization、Password、Secret、常见 sk- 和 Bearer 内容入库前脱敏
Trace Event、Request 和 Config Snapshot 保持字符串、集合与递归深度限制
AgentRun 仅脱敏、不执行审计摘要限长
修复长 input/output 在服务重启后被截断的问题
保证进程内和持久化读取的 AgentRun 内容一致

前端契约

同步 Agent Event TypeScript 类型
增加 AgentTraceResponse 和统计 DTO
增加 Trace 查询 Service
SSE Client 支持发送和解析 Event ID
增加第二阶段事件中文标签
增加 SSE 恢复协议单元测试

文档整理

将 docs 按用途拆分为：

architecture
contracts
development
guides
retrospectives

同时新增：

文档总索引
CI/CD 团队开发细则
Agent Trace 问题与修复复盘

仓库内旧文档路径和交叉引用均已更新。

数据库影响

本次新增 v3 migration，只增加 Agent Trace 相关表和索引，不删除或修改现有 Note、Block、Task、FTS 和 Vector 数据。

验证结果

backend compileall   passed
backend pytest       81 passed
frontend vitest      11 files / 27 tests passed
frontend type-check  passed
frontend build       passed
Markdown links       passed
git diff --check     passed

已知边界

当前只恢复 Run 状态和 Trace 读取，不自动恢复重启前未完成的 Agent 执行
Trace 自动归档和保留策略尚未实现
前端 Trace Timeline/Tree、高级筛选和 Citation 跳转由后续前端任务完成
SSE 指数退避自动重连将在桌面网络策略确定后实现
Benchmark 后续直接复用本次 Trace Contract，不建立旁路 Agent 执行协议

合并建议

本分支基于当前 main，没有分叉或合并冲突。相关测试、类型检查、生产构建和文档检查均已通过，建议合并。

## 背景第一阶段 Agent Run 和 Event 只保存在进程内存中。服务重启后历史运行记录会丢失，SSE 连接中断后也无法从指定位置继续消费事件，无法满足第二阶段 Agent Trace 可视化和 Benchmark 对稳定运行事实的需求。本次改动将 Agent Run/Event 接入 SQLite，并建立可分页、可恢复、可供前端与 Benchmark 共用的 Trace 数据链路。 ## 主要改动 ### Agent Trace 持久化 - 新增 `AgentTraceRepository` - 新增 SQLite v3 migration： - `agent_runs` - `agent_events` - 使用 `run_id + sequence` 作为事件幂等键 - Run 列表、详情和 Trace 支持进程重启后读取 - 未完成的历史 Run 在重启后收束为 `AGENT_PROCESS_RESTARTED` ### SSE 断点恢复 - SSE 帧增加 `id: sequence` - 支持 `Last-Event-ID` 请求头 - 支持 `after_sequence` 查询参数 - 先回放持久化历史，再切换到实时订阅 - 历史和实时事件按 sequence 去重 - 非法游标返回 `TRACE_CURSOR_INVALID` ### Trace 接口新增： ```http GET /api/agent/runs/{run_id}/trace ``` 支持： - `after_sequence` - `limit` - 分页事件列表 - `next_sequence` - `has_more` - 模型调用次数 - Tool 调用次数 - 执行耗时 - Token Usage - 错误数量 - 创建 Run 时的配置快照 ### Agent Event 扩展新增事件： - `ModelCallStarted` - `ModelCallCompleted` - `ModelCallFailed` - `PermissionResolved` Tool Call 和 Tool Result 增加： - `parent_model_call_id` - `duration_ms` ### 持久化安全与完整性 - API Key、Authorization、Password、Secret、常见 `sk-` 和 Bearer 内容入库前脱敏 - Trace Event、Request 和 Config Snapshot 保持字符串、集合与递归深度限制 - AgentRun 仅脱敏、不执行审计摘要限长 - 修复长 input/output 在服务重启后被截断的问题 - 保证进程内和持久化读取的 AgentRun 内容一致 ### 前端契约 - 同步 Agent Event TypeScript 类型 - 增加 `AgentTraceResponse` 和统计 DTO - 增加 Trace 查询 Service - SSE Client 支持发送和解析 Event ID - 增加第二阶段事件中文标签 - 增加 SSE 恢复协议单元测试 ### 文档整理将 `docs` 按用途拆分为： - `architecture` - `contracts` - `development` - `guides` - `retrospectives` 同时新增： - 文档总索引 - CI/CD 团队开发细则 - Agent Trace 问题与修复复盘仓库内旧文档路径和交叉引用均已更新。 ## 数据库影响本次新增 v3 migration，只增加 Agent Trace 相关表和索引，不删除或修改现有 Note、Block、Task、FTS 和 Vector 数据。 ## 验证结果 ```text backend compileall passed backend pytest 81 passed frontend vitest 11 files / 27 tests passed frontend type-check passed frontend build passed Markdown links passed git diff --check passed ``` ## 已知边界 - 当前只恢复 Run 状态和 Trace 读取，不自动恢复重启前未完成的 Agent 执行 - Trace 自动归档和保留策略尚未实现 - 前端 Trace Timeline/Tree、高级筛选和 Citation 跳转由后续前端任务完成 - SSE 指数退避自动重连将在桌面网络策略确定后实现 - Benchmark 后续直接复用本次 Trace Contract，不建立旁路 Agent 执行协议 ## 合并建议本分支基于当前 `main`，没有分叉或合并冲突。相关测试、类型检查、生产构建和文档检查均已通过，建议合并。 ```

Kronecker added 4 commits 2026-09-01 10:36:30 +08:00

feat(agent): 持久化Trace并支持SSE恢复 3cb197aafe

docs(agent): 记录Trace问题与修复方案 49dbacb296

docs: 重组文档目录并补充CI/CD细则 a5b709a46f

fix(agent): 保留持久化Run完整内容 0e8d4b7b9f

Kronecker merged commit 83782f1d0a into main

2026-09-01 10:36:44 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Kronecker/NotesAgentic#7