CodeWiki 實戰:安裝版本選擇、OAuth 風險與元件級局部更新

為大型儲存庫生成架構文件時,常見工具不是停留在單一函式的 docstring 堆砌,就是完整重跑一次——以 svelte 這種約 12.5 萬行的儲存庫為例,一次完整建置實測要 2 小時 46 分、21.48 美元。

FSoft-AI4Code 開發的 CodeWiki(FSoft-AI4Code/CodeWiki)採取了不同的工程路線:以靜態分析抽出不會捏造的元件與相依邊,把模組分組與寫作交給 Agent,並在 v2.0 引入元件級相依圖 diff。根據官方局部更新指南實測,單一 commit 更新只需完整建置 1.6% 的成本。

然而,若只看二手介紹或舊版報告就動手部署,很容易踩進陷阱:把 Google 同名服務(codewiki.google)的評價張冠李戴、裝了 v2.0.0 tag 卻找不到 TechDocs 旗標、在設定檔留下膨脹 10 倍的參數,或在私有儲存庫啟用 OAuth 訂閱直通時,讓 codex 軌在關閉沙盒下執行。

本文根據 CodeWiki main 分支原始程式碼(commit a1b9f4a)與官方局部更新指南,整理環境安裝、三軌 Provider 資安邊界、設定檔校正與 CI 局部更新實務。


認清版本差異與同名專案

動手安裝前,必須先釐清兩個基本前提:同名專案的混淆,以及 Git tag 與 main 分支的功能落差。

FSoft-AI4Code 於 2025 年 6 月建立的開放原始碼專案 CodeWiki,與 Google 在 2025 年 11 月發布於 Google 官方部落格的 codewiki.google 完全無關。

Hacker News 上關於「Documentation Theater」的熱門討論串,針對的都是 Google 線上服務;評估開放原始碼版 CodeWiki 的能力與限制時,應以實際原始程式碼與發表於 ACL 2026 Findings 的基準測試為準。

CodeWiki 採 MIT 授權,執行環境需要 Python 3.12+、Git,以及安裝期使用的 Node.js。挑選安裝來源時,不能只看最新的 v2.0.0 tag(2026-09-18 發布),因為多項關鍵功能屬於 v2.0.0 之後才併入 main 分支的 Unreleased 內容:

IMPORTANT

需要 TechDocs 或 Go/Rust 支援時請裝 main 分支:若團隊計畫串接 Backstage TechDocs,或目標儲存庫包含 Vue、Rust、Dart/Flutter、Go、Zig、Lean 4,安裝時必須使用 pip install git+https://github.com/FSoft-AI4Code/CodeWiki.git@main。


三軌 Provider 架構與訂閱直通的安全底線

CodeWiki 提供三種推論整合軌道:API Key 軌、OAuth 訂閱直通軌與 MCP 工具軌。

  1. CodeWiki Provider Backends
    1. API KeyPydanticAI
    1. OAuth SubCawBackend
    1. MCP Servercodewiki mcp

1. API Key 軌(PydanticAIBackend)

實作於 pydantic_ai_backend.py,底層經由 pydantic-ai 串接 openai-compatible、anthropic、bedrock、azure-openai、google(含 Gemini API 與 Vertex AI)及 atlas。

這條軌道具備最完整的工程防護:在 llm_services.py 中繼承 OpenAIChatModel 以修復非標準 Proxy 回應,並自動注入 Anthropic 式 prompt caching 標記與不支援模型的拒絕清單。此外,只有 API Key 軌支援 --fallback-model,能藉由 FallbackModel 自動串接備援模型。

憑證管理採零機密設定設計(config_manager.py):API key 預設寫入系統鑰匙圈(如 macOS Keychain),僅在 keyring 不可用時(如無 X11/D-Bus 的 Linux 容器或 CI runner)自動改用 ~/.codewiki/credentials.json,亦可直接以標準環境變數注入;~/.codewiki/config.json 只保存非機密設定。

並行與計費由 request_limit(預設 100)與 agent_retries(預設 3)控制,並可使用下列指令自訂模型的輸入、輸出與快取單價:

codewiki config pricing set MODEL --input RATE --output RATE

2. OAuth 訂閱直通軌(CawBackend)與底層繞過風險

若將 provider 設為 claude-code 或 codex,系統會切換至 CawBackend(caw_backend.py),藉由第三方包裝層 caw(coding-agent-wrapper) 驅動本機已登入 OAuth 的官方 claude 或 codex CLI。

在此模式下,--main-model 採直通設計,任何底層 CLI 接受的模型字串(如 codex CLI 命名空間下的 gpt-6.1-terra)皆可直接使用;但 --fallback-model 在訂閱軌會被明確忽略。

在私有儲存庫使用訂閱軌之前,必須看懂 caw_backend.py 為了讓 CLI Agent 跑完長流程而埋入的四個底層操作:

CAUTION

私有儲存庫慎用訂閱直通模式:codex 訂閱軌會在子行程開啟 --dangerously-bypass-approvals-and-sandbox,且底層相依套件直連未鎖定版本的外部 Git 分支。處理敏感專案時應在隔離容器內執行,或改走 API Key 軌與 MCP 軌。

3. MCP 工具軌(codewiki mcp)

若不想在 CodeWiki 內設定任何 LLM 憑證,可啟動 codewiki mcp(實作於 codewiki/mcp/),由外部 IDE(Cursor、Claude Desktop、Claude Code、CodeBuddy)提供推論能力。

在此模式下,CodeWiki 僅作為純工具伺服器,輸出 analysis、code_reader、module_tree、doc_writer 與 prompt_server 五類工具;儲存庫亦附帶 skills/codewiki-wiki-generator/SKILL.md 供 Coding Agent 掛載。


校正本機 Config:消除 10 倍膨脹並釐清 max_depth

檢視部分既有本機設定檔(~/.codewiki/config.json)或舊版實測報告時,常會看到 327680、363690、160000 這組被沿用的 token 參數。對照 config.py 的原始程式碼預設值,這是明顯「多打一個 0」造成的 10 倍至 20 倍膨脹:

設定項 (config.json)常見誤傳膨脹值v1 歷史預設v2 現行預設 (config.py)實際控制行為
max_tokens32768032,76832,768單次 LLM 呼叫的最大輸出 token 數
max_token_per_module36369036,36936,369分群階段決定模組是否繼續往下切分的容量門檻
max_token_per_leaf_module16000016,0008,000葉節點模組(不再細分的底層模組)容量上限
max_depth誤傳控制分群深度22寫作 Agent 遞迴產生子 Agent 的最大委派層數

把門檻放大 10 倍雖不會讓程式崩潰,但會導致分群階段幾乎不切分模組,失去細粒度架構拆解的效果。建議將 ~/.codewiki/config.json 重設回 32768/36369/8000,讓分組行為回到官方調校軌道。

這兩組參數的作用不同,源於解析、分群與撰寫三階段的分工:

  1. 第一階段:靜態解析與 Artifact 納入(ast_parser.py、analyzers/):17 種語言中有 16 種用 tree-sitter,唯獨 Python 採用標準函式庫 ast 模組,建立單向 depends_on 相依邊並濾除標準函式庫呼叫。v2.0 新增 artifact-aware 分析(analyzers/artifact.py),將 Dockerfile、CI workflow 與設定檔一併連入相依圖,再由 leaf_selection.py 選出進入點元件。
  2. 第二階段:LLM 語意分群與預設保護機制(cluster_modules.py):模組邊界由 LLM 判斷而非圖演算法。程式依目錄分批送交模型分群,當模組超過 max_token_per_module(36,369)便繼續往下拆,直到低於該門檻,或總量不足 min_token_per_module(1,000)的兩倍(避免再拆出低於 1,000 token 的碎塊)才停止。調大 max_token_per_module 會讓分群在一開始就滿足停止條件;外圍另設有元件唯一性驗證、整批失敗時依目錄字首與 token 容量分批打包的結構化退回機制,並在 Build/CI 元件遺漏逾 20% 時強制插入 "Build, Deployment and Configuration" 備援模組。
  3. 第三階段:Agent 遞迴寫作(max_depth = 2):寫作 Agent 經由編輯器、元件讀取與子模組生成工具寫入檔案。max_depth 只限制寫作階段遞迴產生子 Agent 的委派層數,與前一階段的分群切分毫無關係。另外,組裝 USER_PROMPT 時內嵌的模組樹與檔案內容受 900,000 字元預算限制(prompt_template.py,為避開 codex 伺服器端 1,048,576 字元的 input_too_large 硬上限),超限時會自動裁切內嵌內容,改由 Agent 呼叫讀檔工具補讀。

CLI 生成實戰:繁中輸出、客製指示與目錄結構

執行生成任務時,常用 CLI 旗標包含:

一次完整建置後,docs/ 目錄下會產出五類標準產出檔案:overview.md、各模組 .md 檔、module_tree.json、記錄 commit 資訊的 metadata.json,以及存放相依圖與索引、供後續 --update 比對使用的 temp/ 工作目錄。


元件級局部更新:1.6% 成本的六步管線與參數調校

初次完整建置的瓶頸在漫長的 LLM Agent 寫作迴圈。開啟 v2.0 的 --update 後,svelte 的單一 commit 局部更新縮減至 3 分鐘、花費 $0.34(約完整建置的 1.6%)。

這套實作於 codewiki/src/be/updater/ 的更新機制,不像一般腳本只跑 git diff 比對檔案,而是以「元件(class/function/build file)為變更單位、葉節點模組為工作單位」執行六步管線。

執行 --update 的基本前提,是輸出目錄中必須保留前次建置留下的 module_tree.json 與 temp/ 快取目錄(包含先前的元件 hash 與呼叫圖),否則將因無從比對而觸發 detector_failure 並直接退回完整重建:

  1. Step 1: Graph Diff (graph_diff.py)比對正規化 body hash 與簽名,只改註解 = 零變更;刪除+新增且本體相似度達 95% (--tau-ren) 視為改名
  2. Step 2: 模組樹修復規則路由:同檔 -> 同目錄 -> 相依鄰居多數決 (過半數);失敗交 routing agent;模組膨脹逾 33% 觸發重分群
  3. Steps 3 & 4: 葉節點變更報告與完整重建退回判定追蹤自身變更 + 上游相依 (預設 1 hop) + 頁面已提及元件;活躍模組逾 50% 或結構變更逾 30% 時,退回完整重建
  4. Steps 5 & 6: 相依序派工與收尾審計Agent 自選原地修補 / 重寫 / no-op,僅准修補相關頁面;掃描失效連結與過時名稱,決策與成本寫入 update_record.json

更新階梯與 CI 參數調校

在工程實務上,上述管線的深度與退回門檻可以 CLI 旗標微調:

TIP

CI 中使用 Squash Merge 請覆寫比對基準:當團隊採用 Squash Merge 或 Rebase 合併進主分支時,PR 分支原記錄於 metadata.json 的個別 commit 節點在合併後會消失,導致主分支 CI 找不到基準;此時應手動傳入 --compare-to HEAD~1 指定基準。


工程落實的適用邊界

從 ACL 2026 Findings 論文(arXiv:2510.24428)的 CodeWikiBench 評測結果與 main 分支實作,可以清楚看出這套「靜態抽素材、LLM 判模組」架構的強項與極限。

在高階腳本語言上,CodeWiki 表現突出:整體得分 68.79%,領先商業版 DeepWiki(64.06%)、deepwiki-open(50.05%)與 OpenDeepWiki(47.13%);在 Python、JS、TS 儲存庫(如 puppeteer 與 OpenHands)上,更領先商業版 DeepWiki 10.47 個百分點。

針對 main 分支新增的 Go 與 Dart/Flutter,analyzer 也手寫了框架級歸屬規則,例如將 Go 方法歸屬至接收者型別、將 Flutter 的 Riverpod provider 與路由連向對應畫面,並自動忽略生成的 *.g.dart。

相對地,C/C++ 底層系統專案仍是受限領域:在 wazuh(140 萬行 C)與 electron(18.4 萬行 C++)上,CodeWiki 以 53.24% 落後給 DeepWiki 的 56.39%。論文將此歸因於指標運算、手動記憶體管理與 template metaprogramming;單靠靜態邊與語意分組,這類底層系統專案仍難以精準還原架構。