Graft 代码上下文层
为编程代理生成可检索的代码图，减少反复探索仓库所耗费的调用、令牌与时间。
README清楚区分本地树解析与用户配置的LLM调用，声明无遥测，并详细列出仓库内及用户级写入；初始化提供选择、无TTY不写入、--dry-run、--no-global、--no-hooks和--no-mcp，因此确认机制充分。CI使用只读权限、禁用凭据持久化并固定Action提交。但安装包含未展示的postinstall脚本，依赖使用可浮动的范围版本；API密钥可经命令行传入，却未说明密钥存储、日志脱敏、请求中具体发送哪些源码内容或提供者保留策略。没有明确卸载或恢复流程。来源归属较弱：许可证仅称“Context Graph Engine contributors”，且package.json的仓库、主页和问题地址仍指向context-graph-engine，与NanoNets/Graft对象不一致。
README、CI和针对检索、索引损坏回退、跨平台及提示信息的测试总体形成一致的产品行为，并显示缺失或损坏sidecar会回退、结构查询失败会给出显著说明。扣分在于文档存在内部张力：一处称graft/为不提交的本地缓存，另一处称可提交并由Git同步；“构图两遍均由模型驱动”也与后文的无模型结构构建表述不够协调。Node 20要求、可选LSP及多提供者配置有说明，但未展示依赖安装失败、模型不可用或网络错误的完整处理。
目标用户、单仓库/单体仓库、多仓库、CI和多种编码Agent场景描述具体；支持语言、结构层与深度层、可选LSP、未支持文件跳过、网络边界和各开关均有明确界限。交互式选择、无TTY保护、显式agents参数及查询覆盖率门槛体现了精确触发。扣分主要是环境证据只覆盖Ubuntu和Windows及Node 20，未展示macOS、不同shell、本地模型兼容矩阵或各Agent集成的同等测试覆盖。
README目录、快速开始、架构、CLI、集成、语言和开发信息组织完整，安装方式、写入位置、参数和示例丰富；MIT文本与package元数据一致。已披露pre-1.0、仅支持最新npm版本、未支持语言跳过及LSP降级等限制。扣分在于package.json仍使用旧项目URL，产品命名和更新路径不稳定；未提供所给材料中的独立FAQ或完整已知问题清单，亦未见CHANGELOG、标签策略或迁移指南。安全报告邮箱和响应目标提供了维护入口，但许可证归属泛化且发布者身份无法由材料确认。
输出被设计为可直接消费的Markdown节点、文件行号、源码片段、JSON模式、API骨架、调用追踪和显式回退提示；测试具体覆盖排序、作用域融合、sidecar一致性及损坏降级，支持较高可用性。项目相对冷启动检索具有可信的潜在增量价值。扣分在于4倍更便宜、3倍更快、SWE-bench提升等核心效果主要来自README自报；未提供基准脚本、原始结果或逐实例资料，因此成本收益只能算有方法说明但未被所给文件充分核验。
大量具体行为可追溯到命令说明、配置边界、CI和针对性测试，安全与许可证另有文件交叉支持。测试对检索与降级声明提供了较强的仓库内佐证。扣分在于性能和正确率数据只在README出现，无法由所给测试交叉验证；部分措辞将测得结果推广为普遍结论，同时README存在缓存是否提交及构建路径的矛盾。文档确实明确标注了尚未交付的Markdown crux功能，这有助于区分现状与规划，但整体事实、推断和营销主张仍未完全分层。
- 安装会执行未提供源码的postinstall脚本；采用前应检查该脚本及发布到npm的实际包内容。
- 深度构建会把代码内容发送给用户选择的LLM提供者；材料未明确请求载荷、密钥日志处理或提供者数据保留政策。
- 选择Codex集成可能修改~/.codex/config.toml、hooks目录和用户级hooks.json，并影响所有仓库；先使用--dry-run，必要时加--no-global。
- 未提供明确卸载或回滚命令，应在初始化前备份将被修改的配置并记录dry-run输出。
- README对graft/应忽略还是提交存在矛盾，团队应先确定缓存和生成制品策略，避免意外提交源码派生内容。
- 性能与SWE-bench结论没有随所给材料附带可审计的原始结果或基准实现，不应直接用于容量、预算或质量承诺。
- package.json中的仓库、主页和问题跟踪地址与当前NanoNets/Graft名称不一致，发布来源和支持入口应人工核验。
这个 Agent 能做什么，适合哪些场景？
Graft 是面向 Claude Code、Cursor、Codex、Gemini 等编程代理的开源代码库上下文层。它使用 tree-sitter 在本地构建按符号组织的代码图、文件卡片和调用关系，并可通过可选的 LLM 深度构建生成概念节点、摘要与关键代码片段。产物保存在本地 graft/ 目录中，由 CLI、MCP 服务器以及代理原生指令文件提供给编程代理使用。graft ask、grep、skeleton、callers 和 map 可搜索实现、查看 API 表面、追踪依赖与快速了解仓库结构；graft viz 则提供本地交互式视图。结构化构建和查询不需要模型、密钥或网络，只有深度摘要层会通过用户配置的 OpenAI 兼容接口、Anthropic 原生 API 或其他受支持端点调用模型。它适合希望给代理提供持久、可刷新且能随代码变更更新的仓库知识，同时仍将代码图保留在本机文件系统中的团队。
运行 graft build 时，Graft 读取支持语言的源文件，用 tree-sitter 提取函数、类、方法、导入和调用边，写入 graft/.graph/wiring.json 以及与源码树对应的文件卡片。graft build --deep 会先让配置的模型概括各文件，再把摘要组织成包含类型化链接的概念节点，同时为符号添加摘要和 crux；这些结果按内容或函数体哈希缓存。graft ask 根据任务返回排名后的节点和准确 file:line，graft skeleton 输出单文件签名，graft callers 追踪入向或出向依赖，graft grep 按所属符号汇总正则命中，graft map 展示目录集群、枢纽和热点。查询前会检查工作树指纹，并在代码发生变化时执行不调用模型的增量结构刷新。graft init 可写入 AGENTS.md、GEMINI.md、Cursor 或其他代理规则文件，注册六个 MCP 工具，并为 Claude Code 安装项目级技能、状态栏和自动同步钩子；选择 agents 主机时还可修改用户级 Codex 配置。graft viz 在 localhost 提供上下文图、符号代码图和文件层级视图。
- 接手陌生大型仓库的开发者，可先运行 graft map，再让编程代理通过 graft ask 定位子系统、入口和关键文件。
- 使用 Claude Code 或 Codex 处理跨文件修改的团队，可用 graft callers 或 graft_trace_calls 查看某个符号的调用方和变更影响范围。
- 希望压缩代理上下文的工程师，可用 graft skeleton 或 graft_file_api 只提供文件签名，而不发送完整函数体。
- 维护单体仓库或多个并列 Git 仓库的团队，可让 Graft 自动发现子项目，并用 --in 将检索限制到特定范围。
- 需要穷举代码模式的维护者，可用 graft grep 或 graft_find_all 按所属符号收集全部正则命中，并按耦合度排序。
- 不愿把结构化代码分析交给远端服务的团队，可仅使用本地 tree-sitter 构建、查询和新鲜度检查，按需再启用 LLM 深度层。
这个 Agent 有哪些优点和局限？
- 基础代码图、调用边、构建、漂移检查和查询均由 tree-sitter 在本地确定性执行，不需要模型密钥或网络。
- 同时提供 CLI、六个 MCP 工具、代理指令文件和本地可视化界面，可适配多种编程代理工作流。
- 不仅建立文件索引，还提取符号、跨文件调用与导入关系，并提供 callers、skeleton、grep 和 map 等针对性操作。
- 支持内容哈希缓存和查询前增量刷新，可覆盖已暂存、未暂存及未提交的代码变化。
- 提供 OpenAI 兼容接口和 Anthropic 原生 API 等多提供商深度构建路径，模型、密钥和端点由用户控制。
- README 报告了受控测试及 SWE-bench Verified 结果，包括正确率、令牌、调用次数、成本和耗时指标。
- LLM 生成的概念节点、文件摘要及符号 crux 需要用户自行提供模型、API 密钥和相关费用；自动同步不会替用户更新这一深度层。
- 完整精度的手写解析器仅覆盖 TypeScript/JavaScript、Python、Go 和 Java；其余列出的语言使用较宽泛的通用提取，未列出的语言会被跳过。
- 编译器级调用边依赖 PATH 中已有对应语言服务器，并且属于尽力而为的可选增强。
- 初始化可能写入多个仓库文件；选择 agents 主机时还可能修改机器级 ~/.codex/config.toml 和钩子文件，需要先用 --dry-run 或 --no-global 控制范围。
- 代码图是本地可再生成缓存，团队成员仍需各自运行 graft build；不能把已生成的本地图当成免安装的共享服务。
- 性能和正确性数字来自仓库作者描述的特定模型、任务、仓库和测试配置，不能保证在其他代码库或代理上获得相同幅度。
如何安装或部署这个 Agent？
需要 Node.js 以及 npm 或 npx。全局安装并初始化当前仓库：
npm install -g @nanonets/graft
graft init不全局安装也可以运行：
npx @nanonets/graft init在自动化或无 TTY 环境中，init 默认不写文件；应明确传入代理，例如 graft init --agents claude，或使用 graft init --yes。正式写入前可运行 graft init --dry-run；若不希望修改 ~/.codex/，添加 --no-global。基础 graft build 不需要 API 密钥。若要运行 graft build --deep，需配置 GRAFT_PROVIDER、GRAFT_API_KEY 和 GRAFT_MODEL；OpenAI 线格式还可通过 GRAFT_BASE_URL 指向 OpenAI、OpenRouter、Fireworks、Groq、LiteLLM 或本地兼容端点。
如何使用这个 Agent？
最小工作流程：在仓库根目录执行 graft build，然后运行 graft map 获取结构概览，或执行 graft ask "任务描述" 查找相关代码。查看文件 API 可运行 graft skeleton <file>；分析影响范围可运行 graft callers <symbol> -d N；穷举模式可运行 graft grep "<regex>"。需要模型生成的概念节点和符号摘要时，在配置提供商凭据后执行 graft build --deep。运行 graft check 检测图是否落后于代码，运行 graft viz 打开 localhost 交互视图。代理可通过 graft init 自动安装的指令与 MCP 配置使用它，也可手工注册命令 npx -y @nanonets/graft mcp。查询默认会在工作树变化后进行增量刷新；可用 --no-refresh 或 GRAFT_NO_REFRESH=1 禁用。
这个 Agent 与同类方案有什么区别？
与每次从零开始 grep、打开文件并追踪导入的冷启动 Claude Code 相比，Graft 会先构建并复用仓库代码图。README 报告的 162 次受控运行中，Graft 推送上下文方案平均减少了 46% 工具调用、42% 令牌和 60% 延迟，同时两组正确率均为 93%；按需拉取工具方案较慢，但正确率达到 98%。在 50 个 SWE-bench Verified 实例中，接入 Graft 的 Claude Code 解决 33 个，冷启动组解决 27 个，并使用更少的令牌、调用和时间。这些是所述测试配置下的项目结果，而不是对所有仓库的普遍保证。