19 KiB
审计设计演进：从 Session Trace 到 Exact Run
今天看到的审计系统包含 exact Run、决策 Timeline、Agent Step、Tool Invocation、Token 对账和独立 Reasoning。它看起来像一套预先设计好的完整架构，但真实过程并不是这样。
这套设计是被一系列具体问题推出来的：先是答案无法回放，然后是 Tool 记录语义不一致，再后来是同一 Session 多轮串线，最后 Single ReAct 重构又让旧审计链失去所有权。每次变化都解决了当时最紧迫的问题，也留下了下一阶段才看得见的新缺口。
这篇文章不按提交逐条记流水账，而是解释六次能力跃迁。第一次阅读只看第 1、2、4、7 和 10 节，就能抓住主线。
1. 先看完整演进
flowchart LR
A["只能看到最终答案"] --> B["01 可查询 Trace<br/>答案可以回放"]
B --> C["02 Evidence 与质量语义<br/>记录开始可比较"]
C --> D["03 exact Run<br/>多轮不再串线"]
D --> E["04 Canonical Tool Truth<br/>事实与长期审计分层"]
E --> F["05 Single ReAct 审计重建<br/>责任回到 Harness"]
F --> G["06 Timeline / Token / Reasoning<br/>决策、成本与敏感正文分治"]
六个阶段分别改变了审计系统回答问题的能力：
| 阶段 | 审计开始能够回答 |
|---|---|
| 01 可查询 Trace | 一次诊断大致执行过哪些 Agent Step 和 Tool |
| 02 语义加固 | Tool 成功、无证据、失败以及 Prompt/规则版本分别是什么 |
| 03 exact Run | 这些记录究竟属于同一 Session 中的哪一轮 |
| 04 Canonical Tool Truth | 当前发布校验依赖的完整事实，与长期审计元数据如何分开 |
| 05 Single ReAct 重建 | 新 Harness 中谁负责记录 Agent 和 Tool，审计失败如何处理 |
| 06 决策、成本与敏感正文 | 决策顺序、模型成本、Reasoning 可用性和治理缺口是什么 |
这不是从“简单”机械升级到“复杂”。每一步都在重新定义审计的边界。
2. 第一阶段：先让最终答案可以被回放
当时的问题
系统已经能执行诊断并返回结果，但演示者只能展示最终答案。面试官如果继续问“Agent 调了哪些 Tool、Verifier 做了什么、证据在哪里”，只能翻数据库或日志临时解释。
当时的选择
2026-07-03 的 MVP Trace 变更增加了独立只读 API：
GET /api/diagnosis/{sessionId}/trace
它直接聚合已有持久化数据：
flowchart LR
API["Trace API"] --> SESSION[("diagnosis_session")]
API --> STEP[("agent_step")]
API --> TOOL[("tool_invocation")]
SESSION --> RESP["聚合 Trace Response"]
STEP --> RESP
TOOL --> RESP
这个阶段没有改变 Chat 主流程，也没有新增数据库表。目标很克制：先把已经存在的执行记录变成一个稳定、只读、可演示的查询入口。
没有选择什么
- 没有把 Trace 塞进
/api/chat响应； - 没有为了演示制造全离线假运行时；
- 没有先设计通用事件平台；
- 没有重写已有 Agent 和 Tool 持久化。
解决了什么
系统第一次可以从最终答案回到 Agent Step 和 Tool 记录，演示流程也形成了“Chat → Trace → Feedback”的闭环。
新暴露的问题
Trace 能查出来，不代表记录语义已经可靠：
- 不同 Tool 的持久化路径并不统一；
success、无结果和失败的含义不稳定；- Trace 仍以
sessionId为唯一身份； - 记录能展示，但还不能稳定支撑评测。
第一阶段解决的是“有没有回放入口”，不是“审计是否已经正确”。
3. 第二阶段：从“有记录”走向“有稳定语义”
当时的问题
评测系统准备使用 Tool Trace 计算证据质量时，发现不同 Tool 对状态的表达不一致：有的调用统一走 recorder，有的在本地 helper 中写表；无命中、失败和降级路径也可能被混成一个模糊结果。
与此同时，AIOps 还是一条独立入口。它能执行自动诊断，却没有与 Chat 相同的 Trace 故事。
当时的选择
2026-07-04 到 07-09 的一组变化没有急着增加新表，而是先收紧契约：
- 统一 Tool recorder 和 evidence summary 语义；
- 区分调用成功、没有证据和真正失败；
- 覆盖 Verifier 缺失、非法输出和 degraded path；
- 让 AIOps 复用已有 Trace 基础设施；
- 用 compact
prompt_audit和 Gatekeeper rule-set version 记录决策版本，不保存完整 Prompt。
flowchart TB
TOOL["Tool 调用"] --> S1["执行是否成功"]
S1 --> S2["是否找到 Evidence"]
S2 --> S3["Verifier / Gatekeeper 如何判断"]
S3 --> S4["使用哪一版 Prompt / Rule"]
S4 --> EVAL["稳定 Trace 与确定性评测"]
没有选择什么
- 没有把完整 Prompt 存进 Trace；
- 没有使用 Prompt 内容 hash 作为频繁变化的版本协议；
- 没有引入 LLM-as-judge 代替确定性 fixture；
- 没有为 AIOps 另建一套 Trace 数据模型。
解决了什么
审计记录开始拥有可比较的语义。评测可以区分“Tool 正常但无证据”和“Tool 本身失败”，也能知道某次判断使用了哪版 Prompt 与规则。
AIOps 当时被定义为 Chat 的兄弟入口：不同触发方式，共享同一套持久化 Trace。这在当时是合理的复用选择。
新暴露的问题
两个入口共享 Trace，并没有解决最根本的身份问题。只要同一个 sessionId 连续执行多轮，所有 Step 和 Tool 仍会混到一起。
而且审计维度越丰富，跨轮污染的破坏越大：不仅回放错误，Feedback、Verifier、评分和案例沉淀都会读错对象。
4. 第三阶段：Session 不是一次执行，必须引入 exact Run
触发它的真实故障
2026-07-10 的 E2E 使用同一个 sessionId 连续请求两轮。Redis 多轮上下文表现正常，但 MySQL 出现了另一种现实：
diagnosis_session
query / answer 被后一轮覆盖
agent_step
第一轮 + 第二轮持续追加
tool_invocation
第一轮 + 第二轮持续追加
主记录表达最新一轮，明细却表达多轮混合。Trace 不再代表某一次诊断，Feedback 也不知道评价的是哪一轮结果。
当时的选择
系统没有只在旧表上补一个轮次字段，而是拆分两种生命周期：
flowchart TB
S["chat_session<br/>多轮对话目录"] --> R1["diagnosis_run 1<br/>第一轮执行"]
S --> R2["diagnosis_run 2<br/>第二轮执行"]
R1 --> D1["step / tool by run_id"]
R2 --> D2["step / tool by run_id"]
核心决策包括：
sessionId表示多轮会话；runId成为正式 API 字段，表示一次可回放执行；agent_step和tool_invocation增加run_id；- Trace、Feedback、Evaluation 和案例来源优先绑定 Run；
- 指定
runId时必须校验它属于 path 中的sessionId。
没有选择什么
- 没有继续让
diagnosis_session同时承担会话与执行； - 没有尝试根据时间戳把历史混合 Trace 伪造成多个真实 Run；
- 没有在这个阶段引入
diagnosis_trace_event； - 没有立即删除旧表和旧客户端兼容。
“当时没有引入 Timeline”很重要。这个阶段只解决身份隔离，复用 agent_step 与 tool_invocation 表达 Trace；typed Timeline 是后续才增长出来的能力。
解决了什么
两轮 E2E 得到同一个 Session 下两个不同 Run：
- run1 exact Trace 只返回 run1；
- run2 exact Trace 只返回 run2；
- step/tool mixed row check 为 0；
- 多轮对话上下文仍然连续。
审计终于拥有稳定的最小单位：一次 Run 可以独立回放、评分、反馈和沉淀。
新暴露的问题
Run 隔离修复了“记录属于谁”，但没有回答“Tool 的完整事实由谁保管”。旧 JPA ToolInvocation 更像长期 preview，无法成为 EvidenceGuard 的独立验真来源。
兼容策略也留下了债务：不传 runId 时读取 latest run、旧表保留、历史 mixed trace 只能映射为 compatibility run。
5. 第四阶段：长期 Trace 不能同时充当证据真理源
当时的问题
Single ReAct + Harness 设计要求 EvidenceGuard 独立验证 Agent 引用。如果 Guard 只能读取 Agent 已经看过的裁剪结果，等于让模型用自己的输入证明自己。
旧 tool_invocation 又不能直接升级为完整事实存储：长期保存 raw response 会扩大敏感数据、存储体积和保留治理范围。
当时的选择
2026-07-21 的 ToolBoundary 设计把一次 Tool 调用拆成不同用途的数据面：
flowchart TB
RAW["Tool Raw Result"] --> CAN["Canonical Invocation<br/>Redis 短期完整真相"]
CAN --> OBS["Agent Observation<br/>有界投影视图"]
CAN --> GUARD["EvidenceGuard<br/>独立验真"]
CAN -.-> DUR["Durable Audit<br/>MySQL 长期元数据"]
Canonical Invocation 保存当前 Run 所需的 request、raw response、Agent projection、状态和时间，并拥有 PROJECTING / READY / ERROR 生命周期。Agent 只能获得投影结果，不能访问 Redis 或完整 raw。
没有选择什么
- 没有让 JPA
tool_invocation保存全部 raw； - 没有让 Agent 获取 Redis key 或 canonical record；
- 没有把无证据和调用失败合并；
- 没有让 raw 超限时静默截断后继续充当完整真相。
解决了什么
系统第一次明确区分：
- 当前 Run 的验真事实：完整、短期、Harness-only；
- Agent 的推理观察：有界、稳定、可消费；
- 长期审计记录：适合复盘，但不复制完整 raw。
这也奠定了后来的失败语义：canonical store 缺失时无法验真，需要 fail-closed；durable audit 写入失败不应改变 Tool observation，可以 fail-open。
新暴露的问题
新 ToolBoundary 有了 canonical store，却尚未接回长期 tool_invocation 审计。与此同时，旧 recorder 依赖 ThreadLocal 和旧 Tool 副作用，不能直接带进新 Harness。
换句话说，新架构已经有了“事实”，但一度失去了“长期记录”。
6. 第五阶段：Single ReAct 后，审计必须重新确定所有权
当时的问题
旧系统的审计依附于多 Agent、@Tool、ThreadLocal 和旧 AgentLoggingHook。Single ReAct 清理删除 Planner、Executor、Verifier、Composer 和独立 AIOps 入口后，继续保留这些记录路径会出现三个问题：
- 审计逻辑仍依赖已经退出生产链的结构；
- Tool backend 可能通过旧 annotation/recorder 产生重复副作用；
- Agent hook 可能长期保存正文和 Thought，违反新的数据边界。
当时的选择
2026-07-22 的收尾没有给旧 recorder 增加更多兼容分支，而是重建 Harness-native 审计：
| 旧方式 | 新方式 |
|---|---|
| 多 Agent 名称和旧 Hook 决定步骤语义 | HarnessAgentAuditHook 记录单体 Diagnosis Agent 步骤 |
| ThreadLocal 回退传递身份 | exact RunContext / run-scoped tracker |
| Tool 自身带 recorder 副作用 | ToolBoundary 统一触发 durable audit port |
| Agent 输入输出正文与 Thought 混入普通记录 | 普通 Step 以 roles、count、Tool names、bytes 等 metadata 为主 |
| JPA 审计与 canonical truth 概念混合 | Redis canonical fail-closed，JPA durable audit fail-open |
| Chat 与 AIOps 两条公开诊断入口 | 统一 /api/chat + Intent Router |
没有选择什么
- 没有把
/api/ai_ops迁移成第二个 Harness use case； - 没有保留旧
@Tool与新 ACI 双注册； - 没有让 audit DB 故障直接改变 Agent Observation；
- 没有为了兼容继续使用旧多 Agent 身份。
解决了什么
审计责任终于与当前执行架构一致：Agent Step 由 Agent Hook 负责，Tool durable audit 由 ToolBoundary 负责，最终 Run 由应用和 Release 收口。
这一步也说明演进不是只做加法。07-04 保留 AIOps 兄弟入口是当时的合理方案；07-22 删除它，则是“唯一入口、唯一 Harness”新目标下的必要替换。
新暴露的问题
metadata-only 解决了普通 Trace 的泄漏风险，却无法满足“为什么 Agent 选择这个 Tool”的深度审计需求。Run 虽然有 Step 和 Tool，也仍缺一条统一的决策 Timeline 和完整模型成本账本。
7. 第六阶段：从执行记录扩展到决策、成本与 Reasoning
新架构暴露的新问题
真实 E2E 出现过一条失败 Run：Diagnosis Agent 重复调用 lookup_knowledge，累计 12 次 Tool、45,087 Token 后才进入 BUDGET_EXHAUSTED；Evidence Repair 还出现过结构解析失败。
旧 Trace 可以看见许多 Step 和 Tool，却不容易直接回答：
- Agent 为什么继续查询，什么时候没有信息增益；
- Token 消耗来自 Router、Agent、Repair 还是 SemanticGuard；
- Evidence、Semantic 和 Release 决策按什么顺序发生；
- Provider 是否真的返回 Reasoning，还是系统只保存了 assistant text。
当前选择
2026-07-23 之后，审计继续分化为三个正交能力：
- typed Decision Timeline：用 RUN、ROUTING、AGENT、TOOL、EVIDENCE、SEMANTIC、RELEASE 阶段记录决定顺序；
- Model Token Ledger：按组件和轮次记录 usage，在 Run 结束执行总额对账；
- Reasoning Audit：独立保存 Provider Reasoning 与 assistant text，普通 Trace 只暴露可用性和 bytes 等 metadata。
flowchart TB
RUN["exact Run"] --> TL["Decision Timeline<br/>决定如何发生"]
RUN --> STEP["Agent Step<br/>模型轮次"]
RUN --> TOOL["Tool Invocation<br/>外部行为"]
RUN --> TOKEN["Token Ledger<br/>组件成本"]
RUN --> RSN["Reasoning Audit<br/>敏感正文"]
TL --> TRACE["普通 Trace"]
STEP --> TRACE
TOOL --> TRACE
TOKEN --> TRACE
RSN -.-> RAPI["独立受限查询"]
没有选择什么
- 没有把 Reasoning 塞回普通 Trace 或 SSE；
- 没有在 Provider 不返回 Reasoning 时伪造思考过程；
- 没有只在 Run 结束写一个无法解释的 Token 总数；
- 没有把 Timeline 变成用于重建业务状态的完整 Event Sourcing。
解决了什么
当前 Trace 不仅能展示“发生过哪些调用”，还可以解释决定顺序、组件成本和发布依据。tokens_reconciled 能检查分项与总额，usage_available=false 能区分真实零消耗与供应商未返回 usage。
仍未完成什么
- Reasoning 访问控制、保留期限和加密尚未闭环；
- 非 DeepSeek Provider 和 reasoning unavailable live 样本仍需补充；
agent_step.thought仍存在兼容镜像语义；- latest-run 与 legacy Trace fallback 仍然存在；
- durable audit fail-open 意味着业务成功仍可能伴随审计缺口。
演进到这里，系统不再把“记录越多”当作审计完成，而开始治理哪些记录应该存在、谁能读取、缺失时如何表达。
8. 哪些设计被保留，哪些被替换
| 早期设计 | 当前结果 | 判断 |
|---|---|---|
| Trace 与 Chat 响应分离 | 保留独立只读 Trace API | 核心边界正确，持续保留 |
| 聚合持久化 Step/Tool | 保留，并增加 Run、Timeline 和对账 | 基础能力被扩展 |
| Session 作为 Trace 身份 | 改为 exact Run，Session 只作目录 | 被真实串线问题替换 |
| AIOps 作为兄弟入口 | 删除，统一 /api/chat |
阶段性合理，后续架构收敛后退出 |
| ToolInvocation 同时承担事实与审计 | 拆为 canonical truth 与 durable audit | 责任过载，被数据分层替换 |
| 旧 ThreadLocal/Tool 副作用 recorder | 改为 Harness-native Hook、Tracker 和 Audit Port | 与当前执行架构重新对齐 |
| 普通 Step 保存 Thought/正文 | 转向 metadata + 独立 Reasoning | 安全边界收紧，但兼容镜像尚未完全清除 |
| 一个 Token 总数 | 组件轮次账本 + Run 对账 | 从统计值升级为可解释成本 |
演进中真正稳定下来的不是某张表，而是三条原则：执行身份要精确、数据责任要分层、缺失和失败要诚实可见。
9. 为什么不能一开始就设计成现在这样
站在今天回看，很容易认为最初就应该有 Run、Timeline、Reasoning 和 canonical store。但当时缺少三个关键事实：
- 没有多轮 E2E，就无法证明 Session 身份会造成怎样的跨轮污染；
- 没有 EvidenceGuard，就无法看清长期 Tool audit 与当前验真 truth 的责任冲突；
- 没有真实 Token 和 Reasoning 样本，就无法确定哪些字段应该对账、哪些正文必须隔离。
过早一次性设计完整审计平台，很可能得到通用事件总线、万能 JSON 和全量 raw 存储，却没有解决 MVP 当时最重要的问题。
这套演进采用的是另一种方式：先围绕可观察故障收紧最小契约，再让新的真实运行暴露下一层边界。
10. 用一张图记住设计为什么变成现在这样
flowchart TB
P1["答案无法解释"] --> D1["独立 Trace API"]
P2["Tool 状态语义不一致"] --> D2["Evidence / Quality 契约"]
P3["同一 Session 多轮串线"] --> D3["exact Run"]
P4["长期审计不能独立验真"] --> D4["Canonical Truth / Durable Audit 分层"]
P5["旧审计依赖旧多 Agent 与 ThreadLocal"] --> D5["Harness-native Audit"]
P6["决策顺序、成本和 Reasoning 不可解释"] --> D6["Timeline / Token / Reasoning 分治"]
D1 --> NOW["当前可回放、可对账、有数据边界的审计系统"]
D2 --> NOW
D3 --> NOW
D4 --> NOW
D5 --> NOW
D6 --> NOW
一句话概括：
审计系统最初只是把已有 Session 记录聚合出来；真实 E2E 先迫使它建立稳定 Evidence 语义，再用 exact Run 修复多轮身份，随后 Single ReAct 重构又把 Tool 真理源与长期审计分开，最终才发展出统一 Timeline、Token 对账和独立 Reasoning 治理。
11. 事实来源与延伸阅读
devflow/projects/2026-07-03-mvp-demo-trace-acceptance/：独立只读 Trace API 的起点；devflow/projects/2026-07-04-evidence-trace-hardening/：Evidence 状态和 degraded path 契约加固；devflow/projects/2026-07-04-aiops-traceable-diagnosis-entry/：早期 AIOps 兄弟入口与共享 Trace；devflow/projects/2026-07-09-interview-demo-quality-audit/：Prompt/Rule version 与确定性质量审计；devflow/projects/2026-07-10-session-run-trace-isolation/：多轮串线、exact Run 决策和两轮 E2E；devflow/projects/2026-07-21-single-react-tool-invocation-store/：canonical Tool truth 与 durable audit 分层；devflow/projects/2026-07-22-single-react-cleanup-e2e/：Single ReAct 审计所有权重建；- ISS-015 诊断运行质量与 Reasoning 审计收敛：Timeline、Token、Reasoning 和当前缺口；
- 审计主设计：当前设计不变量与关键取舍；
- 真实 Run 案例：当前审计能力的具体回放方式。