企业官网建设流程全解析

Raven Trajectory轨迹系统完全指南：从回放、脱敏到构建Bug回归测试语料库

【免费下载链接】RavenThe Harness of Harnesses: a trusted, persistent, self-evolving multi-agent ecosystem for all-domain collaboration.项目地址: https://gitcode.com/gh_mirrors/raven35/Raven

Raven 的 Trajectory（轨迹）系统把 AI Agent 的每一次任务尝试——每一次模型调用、每一次工具执行——变成可回放、可脱敏、可入库的轨迹语料库：一条命令回放历史会话、三层脱敏抹掉密钥、一个 Bug 修复永久沉淀为 CI 可执行的回归测试用例。对于想要调试 Agent 行为、分享问题现场、防止老 Bug 复发的用户来说，这是 Raven 里最值得了解的子系统之一。

什么是 Trajectory 系统：从"日志"到"语料"的三级跳

普通的链路日志回答的是"代码跑没跑挂"，而 Raven 的轨迹层回答的是"这个任务到底做成了没有"。它建立在 tracing 存储之上，把原始 span 提升为可寻址、可标注、受保护的 Agent 工作单元，核心寻址单位叫attempt（一次任务尝试，可能跨多个对话轮次；默认情况下 attempt id 就等于 trace id，零配置即可使用）。

上图是 Raven 演示中一次 Agent 任务的示例输出。像这样的每次模型调用与工具执行，都会被轨迹系统完整记录、可回放、可脱敏。

整个轨迹层由 8 个模块组成，各管一段，见 raven/trajectory/init.py 中的架构说明：

快速上手：一条命令打包并回放轨迹

所有命令都在raven trajectory子命令下（实现见 raven/cli/trajectory_commands.py），不带参数直接执行则打开交互式浏览器。

1️⃣ 打包（save）：raven trajectory save <ID>把一次 attempt 的 span、产物、会话记录和 verdict 装入自包含目录，并自动 pin 住该 id——打包即声明"这是语料，不许被日志清理工具删掉"。

2️⃣ 回放（replay）：这是最直观的调试体验。回放会重新运行真实的 harness 代码（Agent 循环、消息组装、恢复逻辑），但：

• 模型回复来自录制的llm.output，由 ReplayProvider 按录制顺序喂回，不产生任何真实模型调用；
• 工具结果来自录制的tool.output，ReplayToolRegistry 按顺序应答——没有任何真实工具代码被执行；
• 回放自身会抑制 tracing，避免向真实存储中"造假轨迹"。

回放还支持strict/warn两种分歧（divergence）策略：strict 下第一次不匹配立即停下并指出是哪次调用、哪个字段、期望值与实际值各是什么；warn 下记录分歧但继续喂录制数据。比对时只屏蔽 harness 每次运行都会重新生成的内容（如时间戳行、围栏随机数），用户消息里的一个日期变化仍会被视为真实分歧——这正是修完 Bug 后回放的价值：修复后的代码必然偏离旧录制，分歧点就是修复生效的位置。详见 replay.py 模块文档。

3️⃣ 标注与保护：raven trajectory verdict记录任务成败标签；pin/unpin授予/撤销"永不清除"承诺；merge/split把多次尝试合并或拆分为一个逻辑 attempt。

脱敏：三层纵深防护让轨迹能安全离开机器

一个 bundle 里装着完整的模型输入输出和工具结果，可能逐字携带 API 密钥与令牌。Raven 的脱敏（redact.py）用三层防护，每层兜住上一层漏掉的东西：

1. 已知值精确替换：自动收集本机真实持有的密钥——raven 配置中的 secret 字段（含校验前后的原始配置）加上凭据形态的环境变量（*_API_KEY、*_TOKEN等），全局精确替换为带来源名的占位符，如[REDACTED:config.providers.anthropic.api_key]，连 JSON 转义写法也不放过；
2. 正则模式兜底：匹配sk-…、Bearer …、AKIA…、ghp_…、PEM 私钥块、JWT 等常见凭据形状，抓住第一层不知道的具体值；
3. 残留扫描：脱敏后再扫一遍高熵可疑令牌，只报告、不改写，交给人工审核。

脱敏产物是一份副本：原始 bundle 是本地语料，永不修改；副本内附带redaction.json元数据，完整记录每层统计与二进制文件排除策略——报告自我说明了自己的脱敏过程。raven trajectory report <ID>一键完成"重打包 → 脱敏 → 预览残留嫌疑项 → 产出.tar.gz"。

构建 Bug 回归测试语料库：把一次修复变成永久 CI 守卫

这是轨迹系统最有生产价值的闭环：一个固定的 harness Bug，被永久转化为 CI 守卫。

第一步：最小化成 Cassette。原始 bundle 动辄数 MB、含完整模型 I/O，既超仓库大小限制又可能夹带密钥。raven trajectory minimize把它裁剪到"回放恰好要消费的最小面"——只保留携带llm.*/tool.*/turn.input产物的 span 与对应产物，system prompt 整体替换为占位符（回放本就不比对它，且它最易泄露录制机路径），再整条过一遍脱敏。裁剪规则见 cassette.py。若录制不完整（缺模型输入输出或工具结果），裁剪会直接拒绝：不完整的录制守不住回归。

第二步：脚手架回归用例。raven trajectory regression init <source> --name <case_name>从 bundle、attempt id、报告 tarball 或 bug 报告包生成tests/trajectories/<case>/目录，工作流见 tests/trajectories/README.md 与 trajectory_regression_commands.py。每个用例三件套：

• expect.yaml—— 断言 DSL：回放的第一个分歧必须落在哪里、活体侧那里必须做什么。仓库里的示例 sample_diverges_toward_fix/expect.yaml 断言：修复后的代码必须在第 1 次模型调用的messages[1]处分歧，且活体请求"不再包含错误文本、包含修复后文本"：

  mode: strict divergence: {kind: llm, index: 0, field: "messages[1]"} checks: - {call: llm, index: 0, message: -1, op: not_contains, value: "[recorded-by-buggy-harness]"} - {call: llm, index: 0, message: -1, op: contains, value: "tidy the workspace"}

  断言的哲学很关键：Bug 修复后 harness 必然偏离旧录制，所以自然的断言不是"零分歧"，而是"分歧点在预期调用处，且活体值正是修复后的行为"（用例也可以反过来断言零分歧，守卫忠实复现）。

• case.yaml—— 人类契约：issue（Bug 链接）、owner（负责人）、why（断言保护的契约）、re_record（何时允许重新录制）四项必填非空——脚手架故意留空，逼你在提交前填上真实信息；示例见同名目录。

• cassette/—— 最小化+脱敏后的 bundle，CI 回放直接消费。

第三步：门禁。raven trajectory regression validate tests/trajectories/<case>是静态提交门禁：校验两个 schema、cassette 完整性（到回放契约级别，"JSON 能解析"不等于"能回放"）、残留扫描覆盖与审阅、以及大小预算（单文件 ≤256KB、单用例 ≤1MB）。它从不回放——真正的重放由 pytest 回归套件执行，CI 的 trajectory 任务跑"回放 +validate --all"。

命令速查表

关键源码路径

• 轨迹层总览与 API：raven/trajectory/init.py
• 回放与分歧策略：raven/trajectory/replay.py
• 三层脱敏：raven/trajectory/redact.py
• Cassette 最小化：raven/trajectory/cassette.py
• 回归断言 DSL 与门禁：raven/trajectory/regression.py
• CLI 命令实现：raven/cli/trajectory_commands.py、raven/cli/trajectory_regression_commands.py
• 回归用例与示例：tests/trajectories/

从一条save命令到 CI 里永远跑着的回归守卫，Raven 的轨迹系统把 Agent 的"黑盒调试"变成了可回放、可分享、可回归的工程闭环。修好一个 Bug 的那一刻，别忘了让它留下一份语料——下次同样的问题，CI 会先于用户发现它。

【免费下载链接】RavenThe Harness of Harnesses: a trusted, persistent, self-evolving multi-agent ecosystem for all-domain collaboration.项目地址: https://gitcode.com/gh_mirrors/raven35/Raven