適用情境

• 中大型 monorepo（> 500 檔），每次全量重建太慢
• 開發中希望助理看到的圖譜永遠反映當前編輯狀態
• 想與 git 工作流整合：commit → 自動重建

流程總覽

flowchart LR
    A[1. 一次性全量建圖] --> B[2. graphify hook install]
    B --> C[3. 開發時 graphify watch]
    C --> D[4. 手動 graphify update 補語意層]
    D --> E[5. commit 觸發 post-commit hook]
    E -.->|自動 AST 重建| C

步驟 1：一次性全量建圖

第一次仍需 full build 把 baseline 圖譜建立：

export ANTHROPIC_API_KEY=sk-...   # 若 corpus 含 docs/PDF 才需要
graphify extract .                 # 全量建圖

產出 graphify-out/graph.json（baseline）。

💡 若 corpus 全是程式碼、無 docs/PDF，可改用 --code-only 完全跳過 LLM。

步驟 2：裝設 git hook 自動重建

graphify hook install

寫入：

• post-commit hook（每次 commit 後 AST-only 重建，零 API 成本）
• post-checkout hook（切 branch 後重建）
• graph.json 的 git merge driver（兩人平行 commit graphify-out/ 時自動 union）

驗證 hook 已裝：

graphify hook status

步驟 3：開發時搭配 watch 即時同步

開發 session 開一個持續 watch 的 process:

# 在 background terminal
graphify watch ./src

檔案一變動就觸發 AST 增量解析，助理讀到的 graph.json 永遠是當前編輯狀態。

💡 watch 預設只跑 AST（不重算 LLM 語意層），避免每存檔就花 token。

步驟 4：手動 graphify update 補語意層

當你寫了大段 docs（README、ADR、RFC）想立即讓助理看到新概念節點：

# 只重抓變動過的檔（增量）
graphify update ./docs --mode deep

# 等同
graphify extract ./docs --update --mode deep

這會：

• 對變動過的 docs 跑 LLM 語意層
• 保留先前 AST 結果不重算
• 把新 concept / rationale 節點融入既有 graph.json

步驟 5：commit 後 hook 自動重建

git add src/auth/login.py
git commit -m "feat(auth): rate limit"
# → post-commit hook 自動觸發 AST-only 重建

graph.json 更新後，下一位 pull 的團隊成員的助理立刻看到最新圖譜。

進階：忽略檔案 / 排除 docs 但納入 ignored code

.graphifyignore

# .graphifyignore
node_modules/
dist/
*.generated.ts

# 全部排除後再 re-include
*
!src/**

.graphifyignore 與 .gitignore 合併；衝突時 .graphifyignore 的 ! negation 可勝出。¹

--no-gitignore

# 假設 .gitignore 排除了某些有用的 generated code，想納入圖譜
graphify extract . --no-gitignore

只停 .gitignore；.graphifyignore 與敏感檔過濾仍生效。

範例：FastAPI monorepo 持續同步

sequenceDiagram
    participant Dev
    participant Graphify
    participant Git
    Dev->>Graphify: graphify extract . (一次性 baseline)
    Dev->>Graphify: graphify hook install
    loop 開發
        Dev->>Graphify: graphify watch ./services
        Graphify-->>Dev: ✓ 圖譜已同步
        Dev->>Git: git commit -m "..."
        Git-->>Graphify: post-commit trigger
        Graphify-->>Graphify: AST-only rebuild
    end

何時不要用此工作流

• 第一次試用 → 用 快速入門工作流
• 需要全量 reset（refactor 後清理幽靈節點） → graphify extract . --force
• 多 PR 團隊、需要 graph-based review queue → 用 完整開發工作流

相關指令與外部參考

• graphify watch-update 指令詳解
• graphify build 指令詳解
• 官方 README Team setup

下一步

1. 完整開發工作流（含 PR 影響）
2. 快速入門工作流

v0.9.55～v0.9.56：新版增量流程檢查點

新版增量流程多了幾個需要納入日常操作的可靠性觀念：

1. AST rebuild 不得吃掉 semantic work：code-only watch rebuild 不再清除 pending semantic-update flag；文件語意層仍會在後續適當時機重萃取。
2. 相同 basename 要保持可區分：no-cluster mode 也會 disambiguate errors.ts 這類同名檔案，避免增量更新後節點重新碰撞。
3. Watchdog timeout 必須清 worker：重建超時會先終止 spawned extraction workers，避免下一次 update 與 orphan process 疊加。
4. Resolver 升級後做一次基準刷新：若專案使用 @/ alias、Node #imports、Rust traits 或 Python imported types，升到 v0.9.56 後建議先跑一次完整 graphify update，再回到日常 watch。

這些修正的共同目標是：增量結果必須和完整重建的語意盡量一致，而不是只有速度快。