fix(agent): 保留持久化Run完整内容
This commit is contained in:
@@ -9,7 +9,7 @@
|
||||
|
||||
第一阶段 Agent Runtime 已经能够完成模型调用、Tool Calling、权限确认、取消、Usage 和 Citation，但 Run 与 Event 仍以进程内字典和列表为事实来源。第一阶段审阅加入的 Run/Event 数量上限解决了内存无界增长，却没有解决重启丢失、断线续传、Benchmark 复用和敏感数据审计等第二阶段问题。
|
||||
|
||||
本轮处理了 8 类问题：
|
||||
本轮处理了 9 类问题：
|
||||
|
||||
| 编号 | 问题 | 级别 | 处理结果 |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -18,11 +18,12 @@
|
||||
| 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-06 | Trace 可能保存 Secret 和超大 Tool Result | P0 | 全部持久化副本统一脱敏，审计摘要限长 |
|
||||
| A-07 | 进程重启后未终止 Run 永久显示运行中 | P1 | 自动收束为 `AGENT_PROCESS_RESTARTED` |
|
||||
| A-08 | 前端 DTO 与 SSE Client 无法消费恢复协议 | P1 | 同步 TypeScript Contract、Service、标签和 SSE id |
|
||||
| A-09 | AgentRun 与审计摘要共用限长规则 | P1 | Run 只脱敏不限长，保证重启前后内容一致 |
|
||||
|
||||
修复后的验证基线为：后端 80 项测试、前端 27 项测试、TypeScript 类型检查和生产构建通过。
|
||||
修复后的验证基线为：后端 81 项测试、前端 27 项测试、TypeScript 类型检查和生产构建通过。
|
||||
|
||||
## 2. A-01：Agent Run 与 Event 只存在于进程内存
|
||||
|
||||
@@ -267,7 +268,7 @@ Tool 参数和输出来自模型、插件或外部服务，属于不可信数据
|
||||
|
||||
### 解决思路
|
||||
|
||||
所有进入持久化边界的数据统一经过同一个净化函数，不能分别在 Router、Runtime 和 Repository 中维护不同规则。净化必须同时覆盖键名、常见密钥值模式、递归深度、字符串长度和集合大小。
|
||||
所有进入持久化边界的数据统一经过同一个净化函数，不能分别在 Router、Runtime 和 Repository 中维护不同脱敏规则。Secret 脱敏适用于全部副本；体积限制只适用于 Trace Event、Request 和 Config 等审计数据，不能改变对外查询所依赖的 AgentRun 事实。
|
||||
|
||||
### 解决方案
|
||||
|
||||
@@ -280,17 +281,20 @@ Config Snapshot
|
||||
AgentEvent Data
|
||||
```
|
||||
|
||||
净化规则：
|
||||
通用脱敏规则：
|
||||
|
||||
- `api_key`、Authorization、Access/Refresh Token、Password、Secret 等键替换为 `[REDACTED]`；
|
||||
- 常见 `sk-...` 和 `Bearer ...` 字符串模式直接替换；
|
||||
- `credential_id` 等非明文引用保留，不误判为 Secret。
|
||||
|
||||
Event、Request 和 Config 审计副本额外执行限长：
|
||||
|
||||
- 单字符串最多保留 4096 个字符；
|
||||
- 单集合最多保留 100 项；
|
||||
- 递归深度最多 8 层；
|
||||
- 超限位置使用明确的 `[TRUNCATED]` 或 `[MAX_DEPTH]` 标记；
|
||||
- `credential_id` 等非明文引用保留，不误判为 Secret。
|
||||
- 超限位置使用明确的 `[TRUNCATED]` 或 `[MAX_DEPTH]` 标记。
|
||||
|
||||
回归测试直接读取 `agent_runs` 原始 SQLite 字段，确认测试密钥没有落盘，避免只验证 API 响应造成假安全。
|
||||
`AgentRun` Snapshot 仍经过同一套 Secret 脱敏，但不执行长度、集合和深度截断。回归测试直接读取 `agent_runs` 原始 SQLite 字段，确认测试密钥没有落盘，避免只验证 API 响应造成假安全。
|
||||
|
||||
## 8. A-07：重启后未终止 Run 永久显示运行中
|
||||
|
||||
@@ -352,7 +356,35 @@ Agent 的异步 Task 和 Permission Future 不能跨进程恢复。持久化 Run
|
||||
|
||||
Trace 时间线、树形布局、筛选、节点展开和 Citation 跳转仍由前端负责人实现。
|
||||
|
||||
## 10. 事务、顺序与恢复不变量
|
||||
## 10. A-09：AgentRun 与审计摘要共用限长规则
|
||||
|
||||
### 原因
|
||||
|
||||
初版使用 `sanitize_trace_value()` 同时处理 `run_json`、Request、Config 和 Event。该函数不仅脱敏，还会截断超过 4096 字符的字符串、超过 100 项的集合和超过 8 层的结构。`run_json` 随后又被 `GET /agent/runs/{run_id}` 和 Run 列表当作重启后的事实来源，因此审计数据的防膨胀规则意外改变了业务响应。
|
||||
|
||||
### 后果
|
||||
|
||||
- 常见的长模型回答在 AI Core 重启后只剩前 4096 个字符和截断标记；
|
||||
- 长输入、Tool Result 和嵌套结果也可能丢失；
|
||||
- 同一个 Run 在进程内与重启后的接口响应不一致；
|
||||
- 前端刷新、Benchmark 复核和问题追踪无法取得原始运行结果；
|
||||
- 原有测试只验证了 Trace 参数截断，没有比较重启前后的长正文。
|
||||
|
||||
审阅时使用 5000 字符 output 复现：写入前长度为 5000，重新读取后长度变为 4110，并以 `...[TRUNCATED]` 结尾。
|
||||
|
||||
### 解决思路
|
||||
|
||||
持久化边界包含两类数据：AgentRun 是业务事实，Trace Event、Request 和 Config 是可视化与审计摘要。两类数据必须共享 Secret 脱敏规则，但不能共享有损的体积限制。
|
||||
|
||||
### 解决方案
|
||||
|
||||
- `sanitize_trace_value()` 增加明确的 `apply_limits` 策略参数；
|
||||
- 默认继续限长，保持 Event、Request 和 Config 的安全边界；
|
||||
- `_serialize_run()` 使用 `apply_limits=False`，完整保留 input、output、Tool Result 和 Citation；
|
||||
- Secret 键名及 `sk-`、Bearer 模式在两种策略下始终脱敏；
|
||||
- 增加超过 4096 字符的 input/output 持久化回归测试，直接从新 Repository 读取并逐字比较。
|
||||
|
||||
## 11. 事务、顺序与恢复不变量
|
||||
|
||||
本轮修复明确了以下不变量：
|
||||
|
||||
@@ -364,8 +396,9 @@ Trace 时间线、树形布局、筛选、节点展开和 Citation 跳转仍由
|
||||
6. 重启后不能安全继续执行的 Run 必须明确失败，不能永久悬挂。
|
||||
7. 所有持久化 Trace 数据先脱敏、再写入。
|
||||
8. 前端按 `run_id + sequence` 去重，不能依赖一次网络读取对应一条 SSE Event。
|
||||
9. AgentRun 的持久化副本不执行审计摘要限长，重启前后业务字段必须一致。
|
||||
|
||||
## 11. 验证方法
|
||||
## 12. 验证方法
|
||||
|
||||
后端：
|
||||
|
||||
@@ -393,7 +426,7 @@ git diff --check
|
||||
验证结果：
|
||||
|
||||
```text
|
||||
backend pytest 80 passed
|
||||
backend pytest 81 passed
|
||||
backend compileall passed
|
||||
frontend vitest 11 files / 27 tests passed
|
||||
frontend type-check passed
|
||||
@@ -409,22 +442,23 @@ git diff --check passed
|
||||
- Model Call、Permission Resolved 和 Tool parent ID；
|
||||
- 进程中断 Run 自动生成唯一终止事件；
|
||||
- API Key、Authorization 和超长 Tool 参数净化；
|
||||
- 超长 AgentRun input/output 在持久化和重启读取后保持完整；
|
||||
- 直接检查 SQLite，确认 Secret 未进入 Run/Request/Config Snapshot；
|
||||
- OpenAPI 发布 Trace 路径；
|
||||
- 前端 SSE Client 发送和解析恢复游标。
|
||||
|
||||
测试仍会出现本机 `.pytest_cache` 无写入权限警告，不影响 80 项用例结果，也不涉及产品代码。
|
||||
测试仍会出现本机 `.pytest_cache` 无写入权限警告，不影响 81 项用例结果，也不涉及产品代码。
|
||||
|
||||
## 12. 当前边界与后续工作
|
||||
## 13. 当前边界与后续工作
|
||||
|
||||
### 12.1 本阶段明确不做
|
||||
### 13.1 本阶段明确不做
|
||||
|
||||
- 不在后端生成前端 Trace 树形布局；
|
||||
- 不在进程重启后自动重放未完成 Tool 副作用；
|
||||
- 不把 Secret 明文放入 Trace、日志或 Benchmark；
|
||||
- 不为 Benchmark 建立绕过 Agent Runtime 的专用执行协议。
|
||||
|
||||
### 12.2 后续需要继续处理
|
||||
### 13.2 后续需要继续处理
|
||||
|
||||
- 增加 Trace 保留、归档和被 Benchmark 引用时的保护策略；
|
||||
- 引入保留窗口后实现 `TRACE_CURSOR_EXPIRED`；
|
||||
@@ -434,24 +468,24 @@ git diff --check passed
|
||||
- 前端完成 Trace Timeline/Tree、筛选、节点详情和 Citation 跳转；
|
||||
- 多进程或远程执行出现需求后，再设计带租约和幂等副作用的执行恢复。
|
||||
|
||||
## 13. 可复用经验
|
||||
## 14. 可复用经验
|
||||
|
||||
### 13.1 资源上限不等于持久化
|
||||
### 14.1 资源上限不等于持久化
|
||||
|
||||
限制内存 Run 和 Event 数量只能防止进程膨胀，不能解决重启、审计和报告复现。临时保护措施应在文档中明确标注，不能被误认为最终架构已经完成。
|
||||
|
||||
### 13.2 游标必须独立于缓存结构
|
||||
### 14.2 游标必须独立于缓存结构
|
||||
|
||||
只要 sequence 来源于 `len(list)`、数组下标或当前页位置，裁剪和分页就可能破坏唯一性。可恢复事件流必须使用独立、单调且可持久化的逻辑序号。
|
||||
|
||||
### 13.3 恢复读取不等于恢复执行
|
||||
### 14.3 恢复读取不等于恢复执行
|
||||
|
||||
恢复 Run/Trace 查询相对安全；恢复一个包含 Tool 副作用的执行任务需要额外的幂等、租约和补偿机制。在没有这些机制时，明确失败比重复执行更可靠。
|
||||
|
||||
### 13.4 脱敏要覆盖全部持久化副本
|
||||
### 14.4 脱敏要覆盖全部持久化副本
|
||||
|
||||
同一敏感值可能同时出现在 Event、Run Snapshot、Request、Config、日志和报告中。只检查最终 API 响应无法证明数据没有落盘，安全测试应直接验证持久化介质。
|
||||
|
||||
### 13.5 生产者和消费者 Contract 必须同时更新
|
||||
### 14.5 生产者和消费者 Contract 必须同时更新
|
||||
|
||||
后端新增事件类型、字段或 SSE 规则时，至少同步 Pydantic、OpenAPI、TypeScript DTO、Service 和协议测试。可视化页面可以由另一成员开发，但不能让对方从后端实现反推 Contract。
|
||||
|
||||
Reference in New Issue
Block a user