autocontext 知识库机制详解:Playbook 跨运行继承,如何让 Agent 记住每一条经验教训
autocontext 知识库机制详解:Playbook 跨运行继承,如何让 Agent 记住每一条经验教训
autocontext 是一个递归自我改进的 Agent harness,它的知识库机制核心是 Playbook 跨运行继承(cross-run inheritance):每次运行结束时自动把 playbook.md、hints、技能文件打包成快照,下次运行时从历史最佳快照一键恢复,让 Agent 不再从零开始,真正做到"记住每一条经验教训"。
为什么 Agent 的经验教训要跨运行保留?
大多数 Agent 框架有一个共同痛点:这次运行踩过的坑,下次运行还要再踩一遍。autocontext 的思路是"文件系统优先"(filesystem-first)——运行产物直接落在磁盘上,可读、可 diff、可回放、可训练。官方 README 对它的定位很直白:
给它一个目标,它运行任务并对照评估,保留有用的教训,丢弃死路,并为下一次运行留下 traces、reports、playbooks 和数据集。
知识库就存放在 knowledge/<scenario>/ 目录下,每个 scenario(场景)有自己独立的一套经验:
knowledge/<scenario>/
├── playbook.md # 核心:经验手册
├── hints.md # Coach 给出的提示
├── tools/ # 场景工具
└── snapshots/<run_id>/ # 每次运行结束的知识快照
三步闭环:快照 → 记录 → 恢复
autocontext 的跨运行继承由三个环节组成,代码入口在 generation_runner.py。
第一步:运行结束自动打快照
每轮 run 完成后,runner 会调用 snapshot_knowledge,把该场景当前的 playbook.md、hints.md、hint_state.json、SKILL.md 以及 harness 校验脚本完整拷贝到 knowledge/<scenario>/snapshots/<run_id>/ 目录,并返回 playbook 内容的 SHA-256 短哈希用于溯源。实现见 artifact_snapshots.py。
第二步:用 SQLite 记录"哪次运行最好"
光有文件快照还不够——需要知道哪一版知识最好。迁移脚本 004_knowledge_inheritance.sql 创建了 knowledge_snapshots 表,字段包括:
scenario/run_id:快照归属best_score/best_elo:该次运行的最佳得分与 ELOplaybook_hash:playbook 内容指纹
查询时(见 sqlite_store.py#L777),系统按 best_score DESC 取每个场景的最高分快照。也就是说:继承的不是"最近一次",而是"历史最佳"。
第三步:新运行开始时一键恢复
新一轮 run 启动时,runner 检查该场景的 playbook.md 是否存在(逻辑见 generation_runner.py#L1054):
- 如果 playbook 已存在——直接用,不做覆盖,保证当前积累不被旧快照冲掉;
- 如果 playbook 缺失(比如你清理了知识库)——自动从历史最佳快照恢复 playbook、hints、技能文件和 harness 校验器。
这条"只补不盖"的恢复策略,是避免经验丢失的关键设计。
Playbook 中的经验如何被精细化治理?
Playbook 不是一团乱记,它内置了结构化治理机制(lifecycle.py):
- 经验块标记:playbook 中用
<!-- LESSONS_START -->/<!-- LESSONS_END -->注释包裹经验条目,每条经验以列表项形式写入; - 陈旧标记:过时的经验会加上
stale标记而不是直接删除,保留可追溯的"死路"记录; - 内容去重:每条经验按规范化文本计算哈希生成唯一 ID,重复教训自动合并。
配合 playbook_max_versions(默认保留 5 个历史版本)配置,经验手册既持续进化又不会无限膨胀。
开关与配置:默认开启,可精确控制
跨运行继承在 settings.py#L240 中默认开启:
cross_run_inheritance: bool = Field(default=True)
两个注意点:
- 消融实验模式:当
ablation_no_feedback=True时快照与恢复都会跳过,用于做"无反馈基线"的对照实验; - MCP 沙箱模式:沙箱环境(sandbox.py)会显式将其关闭,保证隔离执行不受宿主历史知识影响。
如何快速验证这套机制?
仓库自带端到端测试,覆盖快照生成、最佳快照查询、恢复、防覆盖、配置关闭等场景,见 test_cross_run_inheritance.py。你也可以直接用 CLI 体验继承效果:
pip install autocontext
AUTOCONTEXT_AGENT_PROVIDER=deterministic \
autoctx solve "improve customer-support replies for billing disputes" --iterations 3
同一场景跑两轮后,检查 knowledge/<scenario>/snapshots/ 下是否出现快照目录,再删掉 playbook.md 重跑一轮——你会看到经验被自动"继承"回来。
小结
| 机制 | 作用 | 关键文件 |
|---|---|---|
| 知识快照 | 运行结束打包 playbook/hints/skills/harness | artifact_snapshots.py |
| 最佳快照查询 | 按 best_score 选取历史最优 | sqlite_store.py |
| 启动恢复 | playbook 缺失时自动回填 | generation_runner.py |
| 经验生命周期 | stale 标记 + 哈希去重 | lifecycle.py |
| 迁移脚本 | knowledge_snapshots 表定义 | 004_knowledge_inheritance.sql |
一句话总结:autocontext 用"快照 + 分数索引 + 只补不盖恢复"三件套,把每次运行的经验教训沉淀为可继承的 Playbook,让 Agent 的每一次迭代都站在历史最佳之上。