Zilmac 部落格
← 返回技術實踐

Graphify + OpenCode 實戰教學:讓開源 AI Coding Agent 擁有完整專案結構記憶

API 與 Agent ·約 13 分鐘閱讀

開發者在 Mac 終端用 OpenCode 與 Graphify 查詢本機程式知識圖

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,无強制雲端上傳
3
核心查詢:query · path · explain
AST
graphify 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 知识图谱視覺化:模組节点、依賴边与 OpenCode 終端查詢示意
建图后可打开 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 補上了長期缺失的那一块「專案地圖」。

限時優惠

Zilmac

雲端 Mac、遠端開發與 Mac VPS,為 iOS 與跨平台團隊補齊 Apple 工具鏈。

返回首頁
限時優惠 點擊查看方案