NotesAgentic/docs/retrospectives/Agent-Core第二阶段问题与修复复盘.md

Agent Core 第二阶段：Trace 持久化与 SSE 恢复问题复盘

审阅与修复日期：2026-09-01 涉及分支：feat/agent-trace-persistence 功能提交：3cb197a feat(agent): 持久化Trace并支持SSE恢复 文档用途：记录 Agent Run、Trace、SSE 恢复和审计数据安全问题的形成原因、实际后果、解决思路与落地方案，供后续开发文档、比赛材料和技术博客写作使用。

1. 背景与结论

第一阶段 Agent Runtime 已经能够完成模型调用、Tool Calling、权限确认、取消、Usage 和 Citation，但 Run 与 Event 仍以进程内字典和列表为事实来源。第一阶段审阅加入的 Run/Event 数量上限解决了内存无界增长，却没有解决重启丢失、断线续传、Benchmark 复用和敏感数据审计等第二阶段问题。

本轮处理了 8 类问题：

编号	问题	级别	处理结果
A-01	Agent Run 与 Event 只存在于进程内存	P0	增加 SQLite v3 Schema 和 Trace Repository
A-02	Event 裁剪后 sequence 可能重复	P0	改为独立单调序号并建立数据库幂等键
A-03	SSE 断线后无法从指定事件恢复	P1	支持 Last-Event-ID、after_sequence 和 SSE id
A-04	缺少可分页 Trace 与 Benchmark 配置快照	P1	增加 Trace API、统计摘要与配置快照
A-05	Trace 缺少模型调用、父子关系和权限结果	P1	增加第二阶段事件及耗时/parent 字段
A-06	Trace 可能保存 Secret 和超大 Tool Result	P0	Run、Request、Config、Event 统一脱敏与截断
A-07	进程重启后未终止 Run 永久显示运行中	P1	自动收束为 AGENT_PROCESS_RESTARTED
A-08	前端 DTO 与 SSE Client 无法消费恢复协议	P1	同步 TypeScript Contract、Service、标签和 SSE id

修复后的验证基线为：后端 80 项测试、前端 27 项测试、TypeScript 类型检查和生产构建通过。

2. A-01：Agent Run 与 Event 只存在于进程内存

原因

旧 AgentRuntime 使用 _records: dict[str, RunRecord] 保存全部运行状态。每个 RunRecord 内部再保存 events、实时订阅队列和异步任务。创建、查询、列表和 SSE 回放都只读取这个字典，没有 Repository 边界。

第一阶段为控制内存加入了最多 200 个 Run、每个 Run 2000 个 Event 的限制。这是必要的资源保护，但只是减少进程内数据量，不能替代持久化。

后果

• AI Core 重启后，历史 Run、Tool Result、Citation 和错误全部丢失；
• 前端刷新或重新连接后，只能读取当前进程尚未淘汰的数据；
• Agent Benchmark 无法使用稳定的历史事实计算指标；
• Run 列表随着进程重启清空，界面记录和实际操作脱节；
• 内存裁剪后的旧事件无法再恢复。

解决思路

将 SQLite 中的 Run/Event 作为唯一持久化事实，把内存降级为执行上下文和实时订阅窗口。Runtime 继续负责状态机，Repository 负责落库、分页、恢复和统计，Router 不直接访问数据库。

解决方案

新增 SQLite v3 migration：

agent_runs
├── run_id
├── status
├── run_json
├── request_json
├── config_snapshot_json
├── created_at
└── updated_at

agent_events
├── run_id
├── sequence
├── event
├── data_json
└── timestamp

新增 AgentTraceRepository，负责：

• 创建 Run 及请求、配置快照；
• 在同一事务中更新 Run 并追加 Event；
• 按创建时间分页列出 Run；
• 按 sequence 读取 Event；
• 生成 Trace 分页响应和统计摘要；
• 恢复进程中断的非终态 Run。

内存中的 2000 条 Event 上限继续保留，但只用于实时订阅窗口；完整记录由 SQLite 管理。

3. A-02：Event 裁剪后 sequence 可能重复

原因

旧 _publish() 使用下面的方式生成序号：

sequence = len(record.events)

当事件数量超过 2000 后，Runtime 会删除列表头部。列表长度重新回到 2000，后续事件仍会得到 2000，形成重复 sequence。

后果

• run_id + sequence 无法作为幂等键；
• 前端按 sequence 去重时会错误丢弃新事件；
• 时间线排序出现同序号节点；
• 持久化后会触发主键冲突，或者在错误的覆盖策略下破坏旧事件；
• Benchmark 无法可靠还原 Tool Call 顺序。

解决思路

sequence 应属于 Run 的逻辑时钟，不能从当前缓存长度推导。内存是否裁剪不得影响序号。

解决方案

• RunRecord 增加独立的 next_sequence；
• 每次发布读取当前值，再原子递增；
• agent_events 使用 (run_id, sequence) 复合主键；
• Repository 对重复写入使用幂等插入，不覆盖已经存在的事件事实；
• Trace 和 SSE 均严格按 sequence 升序返回。

4. A-03：SSE 断线后无法恢复

原因

旧 SSE 接口只能从内存列表头部重新回放全部历史，再切换到实时队列。协议帧只有 event: 和 data:，没有 SSE 标准的 id:。接口也不读取 Last-Event-ID 或查询游标。

前端即使知道自己最后处理到哪个 sequence，也无法把该位置传回服务端。

后果

• 短暂断网或页面切换后只能从头回放；
• 长 Run 重连会重复传输大量事件；
• 前端需要依赖本地去重掩盖服务端缺少恢复能力；
• AI Core 重启后无法续传，因为历史事件本身也不存在；
• 实时与历史交界处容易漏事件或重复事件。

解决思路

恢复协议以 sequence 为游标。服务端先注册实时订阅，再读取 sequence > cursor 的持久化历史，随后消费实时队列；交界处允许重复，但 Runtime 和前端都按 sequence 去重。

解决方案

接口支持两种游标输入：

GET /api/agent/runs/{run_id}/events?after_sequence=42
Last-Event-ID: 42

返回帧包含：

id: 43
event: ToolResult
data: {"run_id":"...","sequence":43,"data":{...}}

具体处理：

• after_sequence 优先于 Last-Event-ID；
• 默认游标为 -1，表示从 sequence 0 开始；
• 非整数或小于 -1 的 Header 返回 TRACE_CURSOR_INVALID；
• 历史回放读取 SQLite，不依赖内存窗口；
• 历史与实时交界处按最后已发送 sequence 跳过重复项；
• 终态 Run 回放完终止事件后关闭连接。

5. A-04：缺少可分页 Trace 与 Benchmark 配置快照

原因

旧接口只有 Run 状态和 SSE。SSE 适合实时消费，不适合报告页随机访问、大 Trace 分页或 Benchmark 批量计算。Run 也没有保存创建时的 Provider、Model、Skill、允许工具和限制参数快照。

后果

• Trace 页面只能依赖一次长连接重建全部状态；
• Benchmark 需要绕过正式接口读取 Runtime 内部对象；
• Provider 或 Skill 配置变化后，旧结果失去可解释性；
• 大 Trace 无法受控分页，接口响应体会持续增大；
• 前端和 Benchmark 容易各自实现一套不一致的统计逻辑。

解决思路

提供面向读取的 Trace Snapshot API，但只返回平铺事实，不在后端生成前端树形布局。前端按 parent ID 和 sequence 构造时间线，Benchmark 从同一事件计算指标。

解决方案

新增接口：

GET /api/agent/runs/{run_id}/trace?after_sequence=-1&limit=200

响应包含：

{
  "run_id": "run_123",
  "status": "completed",
  "items": [],
  "next_sequence": 199,
  "has_more": true,
  "summary": {
    "model_calls": 2,
    "tool_calls": 3,
    "duration_ms": 1530,
    "token_usage": 2048,
    "errors": 0
  },
  "config_snapshot": {}
}

配置快照保存：

• Provider ID 和类型；
• Model；
• Capability；
• Skill ID；
• 允许的 Tool；
• max_steps、Token Budget 和网络权限；
• 经过脱敏的 Metadata。

6. A-05：Trace 缺少关键执行事实

原因

第一阶段事件能够表达 Run、Tool、Permission Request、Usage 和 Citation，但没有明确表示一次模型调用的开始、完成或失败。Tool Call 与模型轮次之间也没有 parent ID，Tool Result 缺少统一耗时。权限接口只唤醒 Future，不记录最终决定。

后果

• 前端无法展示“模型调用 → 多个 Tool → 下一次模型调用”的完整树；
• Agent Benchmark 无法计算模型调用次数和平均步骤耗时；
• 并发 Tool Call 时难以判断属于哪个模型轮次；
• 权限卡片消失后，Trace 中只保留“请求过权限”，不知道用户允许还是拒绝；
• Provider 失败只能看到最终 RunFailed，缺少模型调用级上下文。

解决思路

保持现有 AgentEvent envelope 不变，只增加事件类型和可选数据字段。调用关系使用稳定 ID 表达，不让前端根据相邻位置猜测父子关系。

解决方案

新增事件：

ModelCallStarted
ModelCallCompleted
ModelCallFailed
PermissionResolved

补充字段：

• Model Call：model_call_id、Provider、Model、Step、Finish Reason、Token、Duration；
• Tool Call/Result：parent_model_call_id、duration_ms；
• Permission Resolved：request_id、Permission、Decision；
• Model Call Failed：error_code 和耗时，不写入第三方原始敏感异常。

模型与 Tool 耗时使用单调时钟计算，避免系统时间调整影响 Duration。

7. A-06：Trace 可能保存 Secret 和超大结果

原因

Tool 参数和输出来自模型、插件或外部服务，属于不可信数据。旧事件直接保存 ToolCall.model_dump() 和 ToolResult.model_dump()。notes.read、附件或第三方 Tool 可以返回大段正文，参数也可能包含 api_key、Authorization 或 Password。

初版持久化修复只净化了 agent_events.data_json。提交前审阅发现，agent_runs.run_json 中的 tool_results、output 和 input 仍可能保存同一份敏感值，说明“只在事件层脱敏”并不完整。

后果

• API Key 或 Bearer Token 可能进入 SQLite、备份和测试产物；
• Trace API 不返回 Secret，但数据库中的 Run Snapshot 仍可能泄露；
• 单个 Tool Result 可以让 Event 和 Run JSON 快速膨胀；
• 前端展开节点时可能因为超大 JSON 卡顿；
• Benchmark Dataset 或报告导出可能间接携带密钥。

解决思路

所有进入持久化边界的数据统一经过同一个净化函数，不能分别在 Router、Runtime 和 Repository 中维护不同规则。净化必须同时覆盖键名、常见密钥值模式、递归深度、字符串长度和集合大小。

解决方案

统一处理以下对象：

AgentRun Snapshot
AgentRunCreateRequest Snapshot
Config Snapshot
AgentEvent Data

净化规则：

• api_key、Authorization、Access/Refresh Token、Password、Secret 等键替换为 [REDACTED]；
• 常见 sk-... 和 Bearer ... 字符串模式直接替换；
• 单字符串最多保留 4096 个字符；
• 单集合最多保留 100 项；
• 递归深度最多 8 层；
• 超限位置使用明确的 [TRUNCATED] 或 [MAX_DEPTH] 标记；
• credential_id 等非明文引用保留，不误判为 Secret。

回归测试直接读取 agent_runs 原始 SQLite 字段，确认测试密钥没有落盘，避免只验证 API 响应造成假安全。

8. A-07：重启后未终止 Run 永久显示运行中

原因

Agent 的异步 Task 和 Permission Future 不能跨进程恢复。持久化 Run 后，如果直接返回数据库状态，重启前处于 queued、running 或 waiting_permission 的记录会一直保持非终态，但新进程中没有对应 Task 可以继续执行。

后果

• 前端长期显示“运行中”或“等待授权”；
• SSE 订阅等待一个永远不会到来的终止事件；
• Benchmark Runner 无法判断 Case 已中断；
• 用户取消该 Run 时，新进程找不到实际 Task；
• 统计中的成功率和耗时被悬挂 Run 污染。

解决思路

本阶段提供“状态恢复”，不伪装成“执行恢复”。没有可重放状态机、Provider 幂等令牌和 Tool 副作用日志之前，自动继续执行会造成重复写入或重复网络请求。

解决方案

新 Runtime 首次读取不属于当前进程的非终态 Run 时：

• 状态改为 failed；
• 错误码设为 AGENT_PROCESS_RESTARTED；
• 错误信息说明进程在完成前重启；
• 使用数据库最大 sequence 加一，追加唯一 RunFailed 事件；
• 后续 Run 查询、Trace 和 SSE 都返回同一终态事实。

已经完成、失败或取消的 Run 不修改，可以在重启后继续查询和回放。

9. A-08：前端无法消费第二阶段恢复协议

原因

后端增加新事件和 SSE id 后，前端 AgentEventType 仍只包含第一阶段事件。SseClient 只解析 event 和 data，忽略 id，也没有发送 Last-Event-ID。因此仅完成后端并不能形成可联调的 Contract。

后果

• Record<AgentEventType, string> 中文标签无法通过类型检查；
• 前端不知道 Model Call 和 Permission Resolved 的类型；
• 断线后无法把最后事件 ID 传回后端；
• Trace 可视化负责人需要自行猜测 Wire DTO；
• 后端恢复能力只能通过 Curl 使用，页面调用链没有闭环。

解决思路

范侧只提供稳定的前端接口适配，不越过分工实现 Trace Visualization。Pydantic Contract、TypeScript Wire DTO 和 Service 必须在同一功能提交中同步。

解决方案

• TypeScript 增加四类第二阶段 Agent Event；
• 增加 AgentTraceSummary 和 AgentTraceResponse；
• agentService.getAgentTrace() 封装分页查询；
• streamAgentEvents() 接受 afterSequence；
• SseClient 发送 Last-Event-ID 并解析返回帧的 id；
• 新事件增加中文标签和详情字段名；
• 增加 SSE 请求头和 Event ID 单元测试。

Trace 时间线、树形布局、筛选、节点展开和 Citation 跳转仍由前端负责人实现。

10. 事务、顺序与恢复不变量

本轮修复明确了以下不变量：

1. run_id + sequence 唯一标识一条 Agent Event。
2. sequence 在一个 Run 内只增不减，不受内存裁剪影响。
3. 发布事件时，在同一 SQLite 事务中更新 Run Snapshot 并追加 Event。
4. SSE、Trace 页面和 Agent Benchmark 读取同一份 agent_events，不建立旁路。
5. 终止事件为 RunCompleted、RunFailed 或 RunCancelled；终态 Run 不再产生业务事件。
6. 重启后不能安全继续执行的 Run 必须明确失败，不能永久悬挂。
7. 所有持久化 Trace 数据先脱敏、再写入。
8. 前端按 run_id + sequence 去重，不能依赖一次网络读取对应一条 SSE Event。

11. 验证方法

后端：

cd backend
uv run python -m compileall -q app
uv run pytest

前端：

cd frontend
pnpm test
pnpm type-check
pnpm build

仓库检查：

git diff --check

验证结果：

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

本轮新增回归覆盖：

• 完成 Run 在新 Runtime 中恢复查询；
• Trace 多页读取和游标无重复；
• SSE Last-Event-ID、after_sequence 和 id: 帧；
• Model Call、Permission Resolved 和 Tool parent ID；
• 进程中断 Run 自动生成唯一终止事件；
• API Key、Authorization 和超长 Tool 参数净化；
• 直接检查 SQLite，确认 Secret 未进入 Run/Request/Config Snapshot；
• OpenAPI 发布 Trace 路径；
• 前端 SSE Client 发送和解析恢复游标。

测试仍会出现本机 .pytest_cache 无写入权限警告，不影响 80 项用例结果，也不涉及产品代码。

12. 当前边界与后续工作

12.1 本阶段明确不做

• 不在后端生成前端 Trace 树形布局；
• 不在进程重启后自动重放未完成 Tool 副作用；
• 不把 Secret 明文放入 Trace、日志或 Benchmark；
• 不为 Benchmark 建立绕过 Agent Runtime 的专用执行协议。

12.2 后续需要继续处理

• 增加 Trace 保留、归档和被 Benchmark 引用时的保护策略；
• 引入保留窗口后实现 TRACE_CURSOR_EXPIRED；
• 根据桌面网络策略增加有上限的指数退避自动重连；
• 评估高频 Token Event 的批量写入，减少 SQLite 连接与事务开销；
• Agent Benchmark 接入正式 Trace 并验证指标字段是否充足；
• 前端完成 Trace Timeline/Tree、筛选、节点详情和 Citation 跳转；
• 多进程或远程执行出现需求后，再设计带租约和幂等副作用的执行恢复。

13. 可复用经验

13.1 资源上限不等于持久化

限制内存 Run 和 Event 数量只能防止进程膨胀，不能解决重启、审计和报告复现。临时保护措施应在文档中明确标注，不能被误认为最终架构已经完成。

13.2 游标必须独立于缓存结构

只要 sequence 来源于 len(list)、数组下标或当前页位置，裁剪和分页就可能破坏唯一性。可恢复事件流必须使用独立、单调且可持久化的逻辑序号。

13.3 恢复读取不等于恢复执行

恢复 Run/Trace 查询相对安全；恢复一个包含 Tool 副作用的执行任务需要额外的幂等、租约和补偿机制。在没有这些机制时，明确失败比重复执行更可靠。

13.4 脱敏要覆盖全部持久化副本

同一敏感值可能同时出现在 Event、Run Snapshot、Request、Config、日志和报告中。只检查最终 API 响应无法证明数据没有落盘，安全测试应直接验证持久化介质。

13.5 生产者和消费者 Contract 必须同时更新

后端新增事件类型、字段或 SSE 规则时，至少同步 Pydantic、OpenAPI、TypeScript DTO、Service 和协议测试。可视化页面可以由另一成员开发，但不能让对方从后端实现反推 Contract。