多Agent系统里，产出错了，你不知道错在哪一环。Researcher漏搜了？Context Budgeting压掉了？Planner方向选错了？还是Writer自己编的？这就是Traceability要解决的问题。

问题：Agent决策是个黑箱

多Agent系统不是一个人在工作，是一条生产线：

Researcher → Context Budgeting → Planner → Writer → Reviewer

每一站都在做决策：

Agent	决策内容
Researcher	搜不搜这篇文章，按什么关键词搜
Context Budgeting	哪些素材排在前面，哪些被压缩掉
Planner	选哪个方向，放弃哪个方向
Writer	引用哪段素材，怎么用自己的话改写
Reviewer	过不过，哪里要改

问题：这些决策全部隐形。你只知道最终产出了一篇文章，不知道 Researcher 搜了12篇但只用了3篇，不知道 Planner 选了方向A放弃了方向B。

解决方案：加一条可追溯层

Traceability不是新Agent，是一层包裹性代码——在每个Agent执行前后，记录它做了什么决策、基于什么输入、产出了什么输出。

def traceable(agent, name, state):
    snapshot_in = state.snapshot()       # 记下输入
    result = agent(state)                # 执行
    snapshot_out = result.snapshot()     # 记下输出
    record_decision_trace(               # 存日志
        agent=name,
        input_keys=list(snapshot_in.keys()),
        output_keys=list(snapshot_out.keys()),
        changed_fields=diff(snapshot_in, snapshot_out),
        timestamp=now()
    )
    return result

决策日志示例

每跑完一个Agent，日志里多一条结构化JSON：

{
  "agent": "Researcher",
  "timestamp": "2026-05-05 10:23:01",
  "input": { "topic": "Agent 可追溯性", "materials_dir": "Knowledge Repository" },
  "output": { "research_notes": "(2391 chars)", "sources_count": 5 },
  "decisions": [
    "searched with keywords: 'agent traceability', 'decision log', 'audit'",
    "matched 12 files, selected top 5 by relevance",
    "rejected 7 files: 4 duplicate, 2 off-topic, 1 too short"
  ]
}

三层追溯体系

层级	回答	实现
决策追溯	谁干了什么	traceable包装器
来源追溯	这段话从哪来的	素材来源标注
状态追溯	state怎么演化的	快照时间线

第一层：决策追溯

每个Agent的输入、输出、决策日志。回答"谁干了什么"。

第二层：来源追溯

产出里的每一段话，能不能追溯到原始素材？

在输出里保留引用标记：

（来源：素材库_Agent_Memory_三层检索架构.md，第12段）

Reviewer审核时多了一个验证维度：这段引用是否歪曲了原意？

第三层：状态追溯

State对象是怎么演化的？

state_v1.json → Researcher 写入 research_notes
state_v2.json → Context Budgeting 改写 research_notes
state_v3.json → Planner 写入 outline
state_v4.json → Writer 写入 draft
state_v5.json → Reviewer 写入 review_passed=true

价值：把Pipeline的任何一个中间状态恢复出来，复现当时发生了什么。

实战：定位Writer编造数据

回到那个数据出错的问题：

1. 打开traces/目录，按时间搜一下
2. Researcher的trace → 搜了12篇，选了5篇 —— 排除 Researcher 漏检
3. Context Budgeting的trace → 5篇全放进去了 —— Context Budgeting没砍
4. Planner的trace → 策划里有那个数据 —— Planner方向没错
5. Writer的trace → 输入素材里没有那个数据 —— 定位到了：Writer自己编的

不是猜测，是一条线追到底，找到根。

加进Pipeline

state = traceable(researcher_agent, "Researcher", state)
state = traceable(context_budget, "ContextBudgeting", state, budget=4000)
state = traceable(planner_agent, "Planner", state)
state = traceable(writer_agent, "Writer", state)
state = traceable(reviewer_agent, "Reviewer", state)

就这一层包装。每个Agent的代码一行没改。

Traceability是Harness层的职责，不是Agent层的职责——由治理框架提供，不由干活的人自己实现。

清理规则

跑1000篇文章就是几百MB。加条清理规则：

# 保留最近30天的trace，超期自动归档或删除
retention:
  trace_days: 30
  archive: true

Traceability的价值在"能追溯"，不在"存一辈子"。

核心认知

不是"我相信AI能把事办好"，而是"我能证明它为什么办好了，或者它是怎么办砸的"。

Reviewer升级

有了Traceability，Reviewer不止能说"这篇不行，回去改"，还能说"第三段引用的数据，Writer没有引用任何素材，是自己编的"——

审核从判断题升级成了溯源题。

📦 GitHub：github.com/yuyingzhi828/multi-agent-writer