以下场景、轨迹与统计均为教学示例,不来自任何真实生产系统的运行记录。字段设计和校验规则只用于说明“什么算一条可验证的轨迹”,不代表某个框架的官方 schema。
“让模型把思考过程写出来”几乎成了 Agent 的默认动作。但把一段 CoT 贴进日志,和拥有一条可验证的轨迹,是两件事。前者只证明模型说了些什么;后者要能回答:它做了什么动作、看到了什么观测、结论引用了哪一步证据、如果没有得到这个观测还能不能复现同样的结论。
这一节不讨论 CoT 是否真的提升了模型能力,而是讨论一个更工程化的问题:当一次运行结束后,你留下的东西够不够用来复盘、评测和回归。如果答案是不够,那么 CoT 只是更长的日志,不是资产。
从自由文本到结构化轨迹
自由文本 CoT 的问题不是“不准确”,而是不可判定。你无法稳定地判断一段话里哪句是动作、哪句是推测、哪个结论有证据支撑。不同的模型、不同的提示、不同的温度,会产出结构完全不同的文本,评测脚本只能靠正则和关键词猜。
结构化轨迹把这个过程拆成有序的步骤。每一步至少要有四类字段:
| 字段 | 作用 | 缺失后的后果 |
|---|---|---|
| 步骤编号 | 建立顺序与引用关系 | 无法判断证据是前向还是后向 |
| 思考 | 记录这一步为什么这么做 | 只能看到动作,无法复盘选择 |
| 动作 | 声明这一步做了什么 | 轨迹退化成叙述 |
| 动作类型 | 区分工具、回答、结束 | 无法检查终止是否合法 |
| 观测 | 工具返回了什么 | 无法重放,也无法判断结论来源 |
| 证据引用 | 结论指向哪一步观测 | 结论不可追溯,评测只能看答案 |
这里的原则是:观测属于工具步骤,证据属于回答步骤。工具步骤产生观测,不引用自己的结论;回答步骤引用更早的工具步骤,不产生新观测;结束步骤只负责终止。把这三类混在一起,校验器就无法区分“模型说的”和“环境给的”。
形式化一点。一条轨迹是步骤序列 $T = (s_1, \dots, s_n)$,每个步骤 $s_i$ 带有类型 $k_i \in {\text{tool}, \text{answer}, \text{finish}}$。校验器检查一组不变量:
- 编号从 1 开始连续递增;
- 工具步骤必须有非空观测;
- 回答步骤必须有至少一条证据引用;
- 证据引用必须指向更早的、类型为工具的步骤;
- 最后一步必须是
finish,且它是唯一的结束标记。
这些不变量不保证推理正确。它们保证的是:如果轨迹通过校验,你至少可以逐帧重放它,并且每个结论都能找到来源。至于来源是否可信、推理是否成立,是下一层评测要解决的问题。
最小实验:三条轨迹的校验
实验构造三条轨迹,任务都是“回答订单状态”:
- 完整轨迹:先调用
query_order,拿到观测,再引用该观测作答,最后结束。 - 缺证据轨迹:动作和观测都齐全,但回答步骤没有证据引用。
- 悬空引用轨迹:回答引用了一个不存在的步骤。
校验器返回全部违规项,而不是遇到第一个错误就停。这样一次运行就能暴露多个结构问题,避免修一个跑一次。
# file: agp_lab/trace_format.py | write
# tier: 3
# verify: python3 -m unittest tests.test_trace_format
"""结构化推理轨迹的格式与可验证性。
一条可审计的轨迹由有序步骤组成:每步至少包含步骤编号、思考、
动作和动作类型;工具动作必须带观测,回答动作必须带证据引用。
校验器不判断推理结论是否正确,只回答两个问题:
1. 这条轨迹能否被重放:动作与观测是否成对出现;
2. 这条轨迹能否被追溯:每个结论的证据是否指向更早的工具步骤。
实验用三条手工轨迹演示:完整轨迹通过;缺证据的轨迹可以重放但
不可追溯;引用悬空的轨迹在结构层就被拒绝。
"""
from __future__ import annotations
from dataclasses import dataclass
TOOL = "tool"
ANSWER = "answer"
FINISH = "finish"
ACTION_KINDS = (TOOL, ANSWER, FINISH)
REF_PREFIX = "step:"
@dataclass(frozen=True)
class Step:
step_id: int
thought: str
action: str
kind: str
observation: str | None = None
evidence: tuple[str, ...] = ()
@dataclass(frozen=True)
class Trace:
task: str
steps: tuple[Step, ...]
@dataclass(frozen=True)
class Violation:
code: str
step_id: int | None
detail: str
@dataclass(frozen=True)
class Report:
task: str
steps: int
valid: bool
coverage: float
violations: tuple[Violation, ...]
def parse_ref(ref: str) -> int | None:
"""把 step:3 解析为 3;格式不对返回 None。"""
if not ref.startswith(REF_PREFIX):
return None
raw = ref[len(REF_PREFIX):]
if not raw.isdigit():
return None
return int(raw)
def validate(trace: Trace) -> list[Violation]:
"""检查结构不变量,返回全部违规项而不是只报第一个。"""
violations: list[Violation] = []
steps = trace.steps
if not steps:
return [Violation("empty_trace", None, "轨迹没有步骤")]
seen: dict[int, Step] = {}
for position, step in enumerate(steps, start=1):
if step.step_id != position:
violations.append(
Violation("bad_step_id", step.step_id, f"期望编号 {position}")
)
if step.step_id in seen:
violations.append(
Violation("duplicate_step_id", step.step_id, "编号重复")
)
seen[step.step_id] = step
if not step.thought.strip():
violations.append(Violation("missing_thought", step.step_id, "缺少思考"))
if not step.action.strip():
violations.append(Violation("missing_action", step.step_id, "缺少动作"))
if step.kind not in ACTION_KINDS:
violations.append(Violation("unknown_kind", step.step_id, step.kind))
continue
if step.kind == TOOL:
if step.observation is None or not step.observation.strip():
violations.append(
Violation("missing_observation", step.step_id, "工具步骤缺少观测")
)
if step.evidence:
violations.append(
Violation("tool_with_evidence", step.step_id, "工具步骤不应引用自身结论")
)
elif step.kind == ANSWER:
if not step.evidence:
violations.append(
Violation("missing_evidence", step.step_id, "回答缺少证据引用")
)
if step.observation is not None:
violations.append(
Violation("answer_with_observation", step.step_id, "回答步骤不应产生观测")
)
elif step.kind == FINISH:
if position != len(steps):
violations.append(
Violation("finish_not_last", step.step_id, "finish 不是最后一步")
)
if step.evidence:
violations.append(
Violation("finish_with_evidence", step.step_id, "finish 不应引用证据")
)
for ref in step.evidence:
target = parse_ref(ref)
if target is None:
violations.append(Violation("bad_ref_format", step.step_id, ref))
continue
if target >= step.step_id:
violations.append(Violation("forward_ref", step.step_id, ref))
continue
referenced = seen.get(target)
if referenced is None or referenced.kind != TOOL:
violations.append(Violation("dangling_ref", step.step_id, ref))
if steps[-1].kind != FINISH:
violations.append(
Violation("no_finish", steps[-1].step_id, "轨迹未以 finish 结束")
)
return violations
def evidence_coverage(trace: Trace) -> float:
"""回答步骤中证据引用全部合法的比例;没有回答步骤时记为 1。"""
answers = [step for step in trace.steps if step.kind == ANSWER]
if not answers:
return 1.0
covered = 0
for step in answers:
refs = [parse_ref(ref) for ref in step.evidence]
if refs and all(
target is not None and 0 < target < step.step_id for target in refs
):
covered += 1
return covered / len(answers)
def audit(trace: Trace) -> Report:
"""把校验结果收敛成一行可直接进报表的对象。"""
violations = validate(trace)
return Report(
task=trace.task,
steps=len(trace.steps),
valid=not violations,
coverage=evidence_coverage(trace),
violations=tuple(violations),
)
def sample_traces() -> tuple[Trace, ...]:
"""三条手工轨迹:完整、缺证据、证据引用悬空。"""
observation = "订单 123 状态:已支付"
complete = Trace(
task="完整轨迹",
steps=(
Step(1, "先查订单服务", "query_order", TOOL, observation=observation),
Step(2, "观测显示已支付", "answer", ANSWER, evidence=("step:1",)),
Step(3, "结束", "finish", FINISH),
),
)
missing_evidence = Trace(
task="缺证据轨迹",
steps=(
Step(1, "先查订单服务", "query_order", TOOL, observation=observation),
Step(2, "观测显示已支付", "answer", ANSWER),
Step(3, "结束", "finish", FINISH),
),
)
dangling_ref = Trace(
task="悬空引用轨迹",
steps=(
Step(1, "先查订单服务", "query_order", TOOL, observation=observation),
Step(2, "引用一个不存在的步骤", "answer", ANSWER, evidence=("step:0",)),
Step(3, "结束", "finish", FINISH),
),
)
return complete, missing_evidence, dangling_ref
if __name__ == "__main__":
print(f"{'轨迹':<18}{'步骤':>4}{'可验证':>8}{'覆盖率':>8} 违规")
for trace in sample_traces():
report = audit(trace)
codes = ", ".join(
f"{item.code}@{item.step_id}" for item in report.violations
) or "-"
valid = "yes" if report.valid else "no"
print(
f"{trace.task:<14}{report.steps:>6}{valid:>8}"
f"{report.coverage:>8.2f} {codes}"
)
运行:
cd private/labs/agp-lab
python3 -m agp_lab.trace_format
输出:
轨迹 步骤 可验证 覆盖率 违规
完整轨迹 3 yes 1.00 -
缺证据轨迹 3 no 0.00 missing_evidence@2
悬空引用轨迹 3 no 0.00 dangling_ref@2
三行结果对应三种不同的失败形态:
- 完整轨迹通过,说明字段齐全、引用方向正确、终止合法。它仍然可能是错的,但至少可以被审计。
- 缺证据轨迹能重放,却不能追责。动作和观测都在,回答却没有任何来源;在生产里,这类轨迹最容易在“答案看起来对”时被放过。
- 悬空引用轨迹在任何执行之前就被拒绝。引用指向不存在的步骤,说明记录器或生成器已经破坏了结构,继续分析没有意义。
证据覆盖率只统计回答步骤中证据引用全部合法的比例。它是一个很粗的指标,但足够用来做回归门:如果一次改动让覆盖率从 1.0 掉到 0.6,不需要看具体内容,就知道轨迹资产出了问题。
边界与失败模式
结构化轨迹不是免费的。它至少带来三类成本,也对应三类失败模式。
第一类是记录成本。每一步都要求思考、动作、观测和证据,会让模型输出变长,解析也更容易失败。实践中常见的折中是:工具调用强制结构化,思考允许自由文本。但折中一旦没有边界,就会退化成“只有工具日志,没有决策记录”。
第二类是伪结构化。模型学会了填字段,却把证据写成 step:1 而不管第 1 步到底是不是相关观测。校验器只能检查引用是否存在、方向是否正确,不能检查引用是否切题。这是结构与语义之间的缝隙,必须靠独立验证器或人工抽检补上。
第三类是过度记录。把完整提示、完整工具返回、完整模型输出全部落盘,轨迹会迅速膨胀,包含大量敏感信息,也会让评测变慢。轨迹应该记录“决策所需的最小证据”,而不是“所有字节”。
还有一种边界容易被忽略:轨迹格式与执行器耦合。如果格式由某个框架私有定义,换一个运行时就要重写解析和校验。更稳妥的做法是把轨迹当成独立的数据契约:字段、类型、引用规则先定下来,执行器只负责填充。这样评测、回放和迁移才不会被单个框架锁死。
架构含义
把轨迹当数据契约,会推出四条架构要求:
- 先定义 schema,再写执行器。 步骤编号、动作类型、观测字段、证据引用规则要在代码之前确定;执行器不得私自增加“只有它懂”的字段。
- 校验前置,而不是事后补。 每一步产生后立即校验局部不变量;整条轨迹结束后校验全局不变量。不要让坏轨迹进入评测集。
- 把证据引用做成硬约束。 回答步骤没有证据就是结构错误,不是“质量稍差”。只有硬约束才能挡住“看起来合理”的编造。
- 区分可重放与可追溯。 可重放要求动作和观测齐全;可追溯要求结论有来源。两个指标分开统计,才能定位是记录缺失还是推理缺失。
在 W1 检索问答里,证据引用通常指向检索结果;在 W2 代码修复里,它指向失败测试或堆栈;在 W3 运维处置里,它指向监控快照和变更记录。任务不同,证据对象不同,但“结论必须能指回观测”这条不变量不变。
判据表
| 判据 | 合格线 | 不合格的典型表现 |
|---|---|---|
| 字段完整性 | 每个步骤四类字段齐全 | 只有自然语言 CoT |
| 观测归属 | 工具步骤有观测,回答步骤无观测 | 观测和结论混在同一步 |
| 证据方向 | 只引用更早的工具步骤 | 前向引用、引用回答步骤 |
| 终止合法性 | 唯一 finish 且位于末尾 | 多个结束标记或无结束标记 |
| 覆盖率 | 回答步骤证据覆盖率可统计 | 只能人工判断 |
| 可迁移性 | schema 独立于执行框架 | 字段名绑定某个 SDK |
这张表可以直接用于代码评审:任何一条不满足,就说明 trace 还不能作为评测资产。
小结
- 自由文本 CoT 不可判定;结构化轨迹把思考、动作、观测和证据拆成可校验的字段。
- 校验器只保证可重放与可追溯,不保证推理正确;后者需要独立验证。
- 工具步骤产生观测,回答步骤引用观测,结束步骤只负责终止;三类混淆会让校验失效。
- 缺证据和悬空引用是两种不同的失败:前者能重放但不可追责,后者在结构层就应被拒绝。
- 轨迹应作为独立的数据契约,而不是某个执行框架的副产物。
阅读导航:上一节:2.3 预算、超时与强制终止 · 下一节:3.2 ReAct 闭环 。
常见错误与边界
- 把 CoT 日志当轨迹。 日志只证明模型说了什么;没有动作、观测和证据引用,就无法重放和追责。
- 只校验最后一步。 结构错误往往发生在中间步骤;逐步骤校验局部不变量,才能定位记录器的问题。
- 把证据引用当装饰。 引用存在不等于引用切题;校验器负责结构,独立验证器或抽检负责语义。
- 让执行器私有格式反向定义 schema。 换框架就重写评测,说明轨迹不是资产,而是框架的缓存。
- 记录所有字节。 过度记录会放大隐私风险和存储成本;轨迹只应保留决策所需的最小证据。
- 用覆盖率替代正确性。 覆盖率只说明“有没有来源”,不说明“来源是否支持结论”;两者必须分开报告。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。