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/RavenRaven 的 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 中的架构说明阶段模块职责标注verdict.py任务成功/失败标签追加式文件谁有判断力谁写保护store.pypin 固定注册表、attempt 合并/拆分、永不清除承诺打包bundle.py把一次 attempt 的 span、产物、会话记录装进自包含目录脱敏redact.py生成脱敏副本原 bundle 永不修改交付report.py脱敏副本压成.tar.gz可分享报告回放replay.py确定性回放把录制的模型回复与工具结果喂回真实 harness最小化cassette.py压缩脱敏为可提交的 Trajectory Cassette回归regression.pyexpect.yaml断言 DSL驱动回归测试套件快速上手一条命令打包并回放轨迹所有命令都在raven trajectory子命令下实现见 raven/cli/trajectory_commands.py不带参数直接执行则打开交互式浏览器。1️⃣ 打包saveraven trajectory save ID把一次 attempt 的 span、产物、会话记录和 verdict 装入自包含目录并自动 pin 住该 id——打包即声明这是语料不许被日志清理工具删掉。2️⃣ 回放replay这是最直观的调试体验。回放会重新运行真实的 harness 代码Agent 循环、消息组装、恢复逻辑但模型回复来自录制的llm.output由 ReplayProvider 按录制顺序喂回不产生任何真实模型调用工具结果来自录制的tool.outputReplayToolRegistry 按顺序应答——没有任何真实工具代码被执行回放自身会抑制 tracing避免向真实存储中造假轨迹。回放还支持strict/warn两种分歧divergence策略strict 下第一次不匹配立即停下并指出是哪次调用、哪个字段、期望值与实际值各是什么warn 下记录分歧但继续喂录制数据。比对时只屏蔽 harness 每次运行都会重新生成的内容如时间戳行、围栏随机数用户消息里的一个日期变化仍会被视为真实分歧——这正是修完 Bug 后回放的价值修复后的代码必然偏离旧录制分歧点就是修复生效的位置。详见 replay.py 模块文档。3️⃣ 标注与保护raven trajectory verdict记录任务成败标签pin/unpin授予/撤销永不清除承诺merge/split把多次尝试合并或拆分为一个逻辑 attempt。脱敏三层纵深防护让轨迹能安全离开机器一个 bundle 里装着完整的模型输入输出和工具结果可能逐字携带 API 密钥与令牌。Raven 的脱敏redact.py用三层防护每层兜住上一层漏掉的东西已知值精确替换自动收集本机真实持有的密钥——raven 配置中的 secret 字段含校验前后的原始配置加上凭据形态的环境变量*_API_KEY、*_TOKEN等全局精确替换为带来源名的占位符如[REDACTED:config.providers.anthropic.api_key]连 JSON 转义写法也不放过正则模式兜底匹配sk-…、Bearer …、AKIA…、ghp_…、PEM 私钥块、JWT 等常见凭据形状抓住第一层不知道的具体值残留扫描脱敏后再扫一遍高熵可疑令牌只报告、不改写交给人工审核。脱敏产物是一份副本原始 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—— 人类契约issueBug 链接、owner负责人、why断言保护的契约、re_record何时允许重新录制四项必填非空——脚手架故意留空逼你在提交前填上真实信息示例见同名目录。cassette/—— 最小化脱敏后的 bundleCI 回放直接消费。第三步门禁。raven trajectory regression validate tests/trajectories/case是静态提交门禁校验两个 schema、cassette 完整性到回放契约级别JSON 能解析不等于能回放、残留扫描覆盖与审阅、以及大小预算单文件 ≤256KB、单用例 ≤1MB。它从不回放——真正的重放由 pytest 回归套件执行CI 的 trajectory 任务跑回放 validate --all。命令速查表你想做什么命令产出打包一次尝试raven trajectory save IDBundle 目录自动 pin生成可分享报告raven trajectory report ID脱敏.tar.gz上报 Bugraven trajectory report-bug带问题元数据的报告包确定性回放raven trajectory replay bundle分歧报告strict/warn最小化为语料raven trajectory minimizeTrajectory Cassette标注成败raven trajectory verdictverdict 记录保护语料raven trajectory pin / unpin永不清除承诺建回归用例raven trajectory regression init用例目录脚手架提交门禁raven trajectory regression validate静态校验结果关键源码路径轨迹层总览与 APIraven/trajectory/init.py回放与分歧策略raven/trajectory/replay.py三层脱敏raven/trajectory/redact.pyCassette 最小化raven/trajectory/cassette.py回归断言 DSL 与门禁raven/trajectory/regression.pyCLI 命令实现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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考