Agent Context Workshop
Agent Context Workshop
Agent Context Workshop 是一个围绕 coding agent 上下文层的实验仓库：在真实 Rust 项目 qdrant 上构建 code knowledge graph，再把 graph agent 与传统 grep agent 放到 30 个 gold-verified 问题上比较。它的核心价值不在于“图一定比 grep 准很多”，而在于把 Context-Engineering 从口号推进到可测量的工程系统：上下文层是否被 agent 使用、是否减少 token、是否提升重复运行的确定性。
为什么对用户重要
用户的 Hermes / llm-wiki workflow 本质上也在做上下文层：先读 _index.md、查 log.md、搜索既有页、保存 raw、再写 synthesis。Agent Context Workshop 提醒我们，判断一个上下文系统好不好不能只看“最终答对几题”，还要看 agent 是否实际采用了这层上下文，以及多次运行是否稳定。对个人知识库而言，这对应两个可执行指标：检索结果是否真的进入最终答案；同一个问题隔天问是否仍能找到同一批关键证据。
机制：三层 context 与三层抽取 rung
该项目把 context engineering 拆成两个正交维度：
| 维度 | 层级 | 含义 |
| agent 可用上下文 | L1 grep | agent 通过文本搜索临时重建关系 |
| agent 可用上下文 | L2 index + search | 有专门索引，但主要仍是搜索式定位 |
| agent 可用上下文 | L3 graph traversal | agent 可沿符号、依赖、实现、影响半径等关系遍历 |
| 抽取机制 | Rung 0 syntactic | tree-sitter 抽取 symbols/spans，确定性高 |
| 抽取机制 | Rung 1 resolution | rustdoc JSON / griffe 等解析 type、impl、edge |
| 抽取机制 | Rung 2 meaning | LLM/fenic 从注释或语义中提炼 intent，需缓存与验证 |
这解释了为什么它和普通代码索引不同：它不是把更多文本塞给模型，而是把“关系”变成可查询对象。关系一旦确定，agent 不必每次从 grep 结果里重新推断调用链或实现关系。
关键实验结论
README 报告的结果是：单次准确率 graph 21/30、grep 19/30，差距不大；但 graph 在生产更关心的维度上更强：每次运行都答对的确定性 graph 19/30 vs grep 11/30；关系问题上 12/15 vs 6/15；输入 token 约减少 3×；并且通过正确 nudge，agent 使用 graph 工具的 adoption 从 34% 提升到 72%。这些数字应按项目 README 的实验设置理解，尚不是普适结论，因此本页标记为 confidence: medium。
与既有 wiki 概念的关系
- 对 Repository-Exploration：它补充了 SWE-Explore 式“找到关键行”之外的结构化探索维度，即 impact analysis、implementors、blast radius 等关系查询。
- 对 Context-Engineering：它把上下文从静态文档推进到可度量 provider，尤其强调 adoption metric：上下文层存在不等于 agent 会用。
- 对 Agent-Benchmarks：它提示 benchmark 应记录 deterministic repeatability、token efficiency、tool adoption，而不仅是 pass/fail。
- 对 Harness-Engineering：graph tools 是 harness 的一部分；但需要 nudge、门禁和日志来防止 agent 回退到熟悉的 grep 路径。
对 Hermes / llm-wiki 的启发
- 把“是否使用 wiki 证据”纳入完成定义：每次 wiki query 或 ingest 不仅要答对，还应能列出实际读取的页面和 raw 证据路径。
- 把上下文 provider 分层：全文搜索、语义搜索、wikilink graph、raw provenance、git/test output 是不同 provider，不应混成一段长 prompt。
- 衡量 adoption：如果 cron 发现了高质量来源但最终 synthesis 没引用它，说明 discovery 与 write phase 脱节。
- 优先建设确定性关系图：在 llm-wiki 中，wikilinks、index 分类、frontmatter tags 可以先充当轻量 graph；不急于上复杂 Neo4j。
失败模式与边界
- Graph 构建和维护成本可能高于收益，尤其是小仓库或快速变化仓库。
- 关系抽取若混入 LLM 语义层，需要缓存、版本和验证，否则会把 hallucinated edges 固化。
- Adoption 需要 workflow 设计；如果工具描述差或默认搜索更顺手，agent 会忽略 graph。
- 单一示例仓库的 30 题结果不能直接泛化到所有语言、框架和任务类型。
写入记录
- 2026-07-04 09:00 CST：新增 Agent Context Workshop 深度入库，提炼 graph-vs-grep、determinism、token efficiency 与 adoption metric 对 llm-wiki 的启发。