OpenCode 是 2026 年最受关注的开源终端 Coding Agent 之一:多模型、可自托管、AGENTS.md 可版本化。但它的「记忆」默认仍是会话级——换一台机器、新开一个 session,或者上下文被一次巨大的 xcodebuild 日志挤掉之后,Agent 往往又要从 grep 和随机读文件重新摸索仓库结构。
如果你要的是可复查、可增量更新、带 file:line 引用的「项目结构记忆」,Graphify 与 OpenCode 的官方集成是一条很务实的路径:在本地把仓库建成 graphify-out/ 知识图谱,通过 AGENTS.md 规则 + opencode.json 插件,让 Agent 在改代码前先走 graphify query / path / explain。本文是面向实战的完整教程;若你还在对比终端 Agent,可先读 Claude Code 替代工具 2026;跨会话「用户偏好记忆」则属于另一层,可参考 Mem0 / Zep / TencentDB Agent Memory 评测。
graphify-out/graph.json,无强制云端上传query · path · explaingraphify update 增量重建,通常无 LLM 费用OpenCode 缺的不是模型,而是「结构记忆」
终端 Agent 的典型失败模式并不是「写不出函数」,而是找错层:
- 在
apps/mobile里改 UI,却误触packages/core的公共 API; - 重复实现已有 util,因为上次 session 里读过、这次没被召回;
- 对「认证流程」的回答停留在某个旧文件,而路由已迁到 middleware。
把整仓文件列表或 README 塞进 prompt 只能缓解一时。真正需要的是可遍历的结构:谁 import 谁、符号定义在哪、社区/模块簇如何划分,并且每条结论能回到 path:line。Graphify 的定位正是把仓库变成这种图;OpenCode 集成则把「查图」写进 Agent 的默认工作流(见 Graphify + OpenCode 官方说明)。
Graphify 是什么:代码知识图谱,不是又一个 RAG
文档 RAG 擅长「这段话怎么解释需求」;Graphify 擅长「这段代码在系统里连到哪里」。它从 AST 与文档中提取节点与边,输出可查询的 JSON 图,并对边标注来源类型:
- EXTRACTED:解析器直接读到的 import、定义、调用;
- INFERRED:启发式推断的关联;
- AMBIGUOUS:不确定连接——Agent 应谨慎,必要时打开源文件核实。
这种「诚实审计」对 Coding Agent 很重要:模型少了一点幻觉空间,你也更容易在 code review 里追问依据。与我们在 AI Agent 技术栈 里强调的 MCP + 工具调用一致:记忆层要可验证,而不只是更长 prompt。
graphify-out/graph.html 交互浏览;Agent 侧则用 CLI 或 MCP 做受限 token 的子图查询。建图后你会得到什么:graphify-out/
对仓库根目录执行完整 pipeline 后,典型产物包括:
graph.json:可查询的图(GraphRAG 友好);graph.html:本地交互可视化;GRAPH_REPORT.md:自动摘要与建议追问列表。
OpenCode 集成会额外写入/更新项目内可 diff 的配置:AGENTS.md 中的 Graphify 使用规则,以及 opencode.json 里注册的小型插件——在 Agent 第一次想用 bash 探索仓库时提醒「先查图」。这些文件适合进 Git;graph.json 是否提交取决于体积与 CI 策略(见 FAQ)。
安装与接线:uv、平台命令与 --project
推荐用 uv 安装 CLI(PyPI 包名为 graphifyy):
uv tool install graphifyy
graphify opencode install --project
等价命令:graphify install --platform opencode --project。--project 把 skill 与规则落在仓库内,便于团队 review;若只希望用户级安装,可去掉该参数。
常见踩坑:裸 graphify install 不会配置 OpenCode
默认安装目标其实是 Claude Code。若让 OpenCode Agent 自行执行裸命令,可能只在 ~/.claude/ 留下文件而 OpenCode 毫无感知。纠正方式:先 graphify claude uninstall(若误装),再执行 graphify opencode install。官方集成页对此有明确提示。
OpenCode 本体安装请参阅 OpenCode 文档(终端、桌面与 IDE 扩展)。模型与 API Key 的配置不在本文展开——Graphify 建图阶段以 AST 为主,不消耗你选用的聊天模型 token。
在 OpenCode 里建图:/graphify 与 CLI
在已安装 Graphify skill 的 OpenCode 会话中,对当前仓库执行:
/graphify .
或在 shell 中(与 Agent 无关的纯本地操作):
cd /path/to/your-repo
graphify .
大型 monorepo 可先对子目录建图,或之后用 graphify . --update 增量同步。深度抽取可加 --mode deep(更慢、INFERRED 边更丰富)。首次建图时间取决于文件数量与语言 mix;完成后用 graphify query "authentication entrypoint" 做冒烟测试。
三条查询命令:先查图,再改文件
把下面三条当作 OpenCode Agent 的「结构记忆 API」:
| 命令 | 用途 | 典型问题 |
|---|---|---|
graphify query "<问题>" |
按问题抽取有 token 预算的子图(默认 BFS,可加 --dfs 追单一路径) |
「支付回调在哪处理?」 |
graphify path "A" "B" |
两概念/符号之间的最短依赖路径 | 从 AuthModule 到 Database 怎么连? |
graphify explain "Symbol" |
单节点邻域的自然语言解释 + 引用 | CheckoutService 负责什么、被谁调用? |
实践建议:在 AGENTS.md 里写死一条团队规范——涉及跨目录重构、鉴权、数据流的问题,必须先 query,再读文件,最后才编辑。这比事后让 Agent「多读几个文件」省 token,也减少误改公共模块的概率。
示例(token 上限显式声明):
graphify query "where is webhook signature verified" --budget 1500
graphify path "WebhookController" "StripeClient"
graphify explain "WebhookController"
AGENTS.md 与 opencode.json 插件如何协作
OpenCode 原生支持把长期指令放进 AGENTS.md。Graphify 的安装器会写入类似规则:
- 若存在
graphify-out/,架构类问题优先走 Graphify CLI; - 改代码后运行
graphify update .(仅变更文件,AST 路径); - 引用结果时保留
file:line,对 AMBIGUOUS 边要求人工确认。
opencode.json 插件的作用更「轻量」:在 Agent 习惯性调用 bash/find 之前插入提醒,降低「全仓库扫描」本能。两者都是明文项目文件——适合 PR review,也比把规则藏在某个开发者本机里更可维护。
可选:MCP 把图交给其他客户端
若你希望 Cursor、Codex 或其他 MCP 客户端共用同一张图,可安装 MCP 扩展:
uv tool install "graphifyy[mcp]"
# 或重装:uv tool install --reinstall "graphifyy[mcp]"
在客户端配置 stdio 服务(路径必须是绝对路径):
{
"mcpServers": {
"graphify": {
"command": "graphify-mcp",
"args": ["/absolute/path/to/repo/graphify-out/graph.json"]
}
}
}
连通后先调用 graph_stats,再用 query_graph 提问。详见 Graphify MCP 文档。OpenCode 路径仍以 AGENTS.md + 插件为主;MCP 适合「同一仓库、多入口」的团队。
保持图谱新鲜:update、watch 与 git hook
graphify update .:只重提取变更文件,适合每次 feature 分支合并前;graphify hook install:post-commit / post-checkout 自动刷新;graphify . --watch:监听目录变更(无 LLM 的自动重建,适合长会话开发)。
Stale 图比没有图更危险——Agent 会自信地引用已移动的文件。把「更新图」写进 CI(例如 main 分支 nightly graphify update)可以让远程 Mac 上的 OpenCode 会话始终对齐主干结构。
团队场景:远程 Mac、Monorepo 与治理
远程 / 云端 Mac:OpenCode 与 Graphify 都应安装在执行构建的那台 Mac上。Zilmac 一类云端 Mac 适合 iOS、签名与 xcodebuild 场景:你在本地 IDE SSH 进去,图与仓库同在远端磁盘,避免「本地建图、远端改码」路径不一致。
Monorepo:可对子包单独建图,或用多 URL graphify 合并跨仓图(高级用法见 Graphify skill 文档)。无论哪种,团队应统一「查询预算」与「必须先 query 的目录清单」(例如 packages/auth)。
安全:本地图不上传并不等于零风险——graph.json 仍可能包含路径与符号名。若仓库含密钥文件名模式,继续依赖 .gitignore 与 Graphify 忽略规则,不要把生产 secret 写进可被索引的示例配置。
常见问题
Graphify 会替代 Mem0 / Zep 吗?
不会。Graphify 解决代码库结构;Mem0、Zep 等解决跨会话用户与任务记忆。生产里常见组合:Graphify 管仓库拓扑,Memory 层管「这个客户要用 TestFlight」类事实。
图很大,OpenCode 会变慢吗?
查询返回的是预算子图,不是整张 graph.json。瓶颈通常在首次建图;日常 update 只触及变更文件。若仍慢,缩小建图根目录或降低 --mode deep 使用频率。
只有 Python/JS 仓库能用吗?
Graphify 支持多语言 AST 与文档抽取,具体覆盖以当前版本文档为准。混合仓库(例如 RN + 原生 iOS)往往比单一语言更需要 path/explain,因为依赖链跨目录。
和 Claude Code + Graphify 冲突吗?
不冲突,但安装命令分平台。同一台机器可以为不同 Agent 各装一套;误用裸 graphify install 时按前文卸载 Claude 侧再装 OpenCode 侧即可。
总结:OpenCode 负责执行,Graphify 负责可验证的结构记忆。用 graphify opencode install --project 接线,用 /graphify . 建图,用 query/path/explain 约束 Agent 的探索路径,再用 update 与 hook 让图跟住代码——你就给开源 Coding Agent 补上了长期缺失的那一块「项目地图」。