ContextIQ — AST code graph for token-efficient agent context

wiki/ai/sources/contextiq-ast-code-graph-agent-context.md

分类：ai / sources · 更新：2026-07-26 09:05

ContextIQ — AST code graph for token-efficient agent context

核心判断

ContextIQ 值得进入 wiki，因为它把“给 coding agent 更好的仓库上下文”具体化为本地 AST/code graph、token-budgeted context pack、MCP tools、hallucination guardrails 和 savings ledger。它不是单纯做检索，而是试图让 agent 在修改代码前拿到相关 symbols、调用/继承关系、源码片段和 budget dropped list，并在生成后验证文件/符号/导入是否真实。

这对用户重要：llm-wiki 已经把 wiki-vquery、wikilinks、raw provenance 作为知识上下文层；ContextIQ 则代表代码仓库侧的对应物。未来 Hermes 做 agentic coding 时，最耗费 token 和最容易幻觉的环节通常是重复读仓库、误判符号关系、修改 hub file 或编造不存在文件。AST graph + context pack + verify-output 这类机制可以成为 coding workflow 的 context provider。

机制：local graph + context pack + grounded generation

ContextIQ README 中最有价值的机制包括：

本地 SQLite code graph：索引 symbols、call/import/inheritance edges；Python 用 stdlib ast，其他 25+ 语言通过 tree-sitter 深解析，更多语言用 regex fallback。
Token-budgeted context pack：针对 task 返回相关 symbol、caller/callee/base class signatures、匹配源码块，以及因预算丢弃的项目。
Auto-refresh on query：每次查询前增量刷新，降低 agent 在编辑后使用过期 context 的概率。
MCP surface：为 Claude Code / Cursor / Windsurf / VS Code 等 MCP 客户端提供 context tools。
Grounded guardrails：verify-plan / verify-output 检查 fabricated files / symbols / local imports；review 检查 scope drift、hub edits、missing tests、breaking changes。
Savings ledger：记录 context pack vs whole-file 的 token/dollar delta，让 context engineering 的收益可观察。

一阶原理是：上下文不是“读更多文件”，而是以结构图表示代码事实，再按任务预算投影为最小有用上下文，并在产出后检查是否违反这些事实。

与现有 wiki 概念的关系

对 Context-Engineering：它是“上下文质量 × token efficiency × adoption evidence”的代码仓库版本，补足 wiki/文档以外的结构化代码事实层。
对 Repository-Exploration：它把 grep/read 的一次性探索变为可复用 graph provider，但仍需要 agent 对 unknowns 主动追问。
对 Harness-Engineering：verify-plan / verify-output 可成为 coding harness 的 preflight/postflight gates。
对 Agentic-Coding：它提示 agentic coding 的关键杠杆不是让模型盲读全 repo，而是选择合适 context pack、验证修改范围和记录收益。

对 Hermes / llm-wiki 的可执行启发

wiki 也需要 savings/adoption ledger：wiki-vquery 是否减少了重复搜索、是否被回答实际采用，目前缺少量化；可借鉴 ContextIQ 的 count-only ledger。
context pack 要列出 dropped items：当 Hermes 因 token/时间预算只读部分页面时，应在报告中说明哪些相关来源未读，避免过度自信。
代码事实和 wiki 事实分层：代码 graph 负责 deterministic structure，llm-wiki 负责方法论/决策/来源综合，两者不应互相替代。
生成后检查 hallucinated references：wiki ingest 也可做类似 verify-output：检查 wikilinks 是否存在、sources 是否真实、raw hash 是否一致、index 是否包含新页。

失败模式与边界

超大 README / 功能面过宽：ContextIQ 声称的功能很多，正式采用前应用小仓库验证核心 context/verify 能力，而不是一次性接入全部 MCP surface。
graph 不等于语义理解：AST/call graph 能减少结构幻觉，但不能自动理解产品意图、历史决策或业务规则。
语言 parser 覆盖差异：tree-sitter grammar、regex fallback 和 monorepo manifest 可能导致不同语言质量不均。
ledger 容易被误用：token savings 不是任务质量；如果 context pack 省 token 但漏关键文件，会降低结果质量。

深度判断

晋升理由：ContextIQ 体量较大、机制完整，直接补充已有 Context-Engineering 和 Repository-Exploration 页面；但 README 证据很强而实测缺失，且功能声明较多，因此以 medium 置信度入库，后续适合用一个小 repo 做 smoke test。

写入记录

2026-07-26 09:00 CST：新增 source 页面，沉淀 ContextIQ 的 AST code graph、context pack、grounded guardrails 和 savings ledger 对 Hermes/llm-wiki 的启发。