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 內容:
- Backstage TechDocs 匯出(
--techdocs):支援將產出的架構文件轉為 Spotify Backstage 內部開發者入口網站(IDP)所需的 MkDocs 標準目錄,該功能於 2026 年 11 月 5 日(PR #155)併入main,安裝v2.0.0tag 並無此旗標。 - 解析器語言擴充:論文僅評測 7 種語言,
v2.0.0README 標示 11 種,而main分支已擴充至 17 種語言——新增的 Vue、Rust、Dart/Flutter、Go、Zig 與 Lean 4 皆為 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 工具軌。
- CodeWiki Provider Backends
-
- API KeyPydanticAI
- OAuth SubCawBackend
- 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 跑完長流程而埋入的四個底層操作:
- 直接相依個人 Git 儲存庫:
pyproject.toml的 dependencies 寫死coding-agent-wrapper @ git+https://github.com/anhnh2002/caw@main(anhnh2002即第一作者 Anh Nguyen Hoang),並未鎖定 commit hash。 - Codex 強制關閉沙盒與審核:
codex exec在背景執行時,若未開啟最高權限(caw 的EXEC模式),遇到需要審核的 MCP 工具呼叫便會直接取消。為避免生成中斷,caw_backend.py將執行參數對應為--dangerously-bypass-approvals-and-sandbox,並以 monkey-patch 把工具逾時拉長到 24 小時(tool_timeout_sec=86400)。 - Claude 偷換
subprocess繞過組織降級:在受企業管理政策管控的環境中,即使指定略過權限檢查,政策仍可能將 bypass 權限限縮為僅准編輯檔案的acceptEdits模式,進而擋掉 CodeWiki 自帶的 MCP 工具。為此,程式在 Python runtime 直接替換 caw 模組內的subprocess.Popen參照,為每個命令強制加上--allowedTools mcp__<server>以放行工具呼叫。 - 工作目錄強制固定:由於兩個 CLI 解析相對路徑的行為不同,程式會分別把子行程的
cwd固定在輸出目錄(codex)與儲存庫根目錄(claude)。
CAUTION
私有儲存庫慎用訂閱直通模式:codex 訂閱軌會在子行程開啟 --dangerously-bypass-approvals-and-sandbox,且底層相依套件直連未鎖定版本的外部 Git 分支。處理敏感專案時應在隔離容器內執行,或改走 API Key 軌與 MCP 軌。
NOTE
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_tokens | 327680 | 32,768 | 32,768 | 單次 LLM 呼叫的最大輸出 token 數 |
max_token_per_module | 363690 | 36,369 | 36,369 | 分群階段決定模組是否繼續往下切分的容量門檻 |
max_token_per_leaf_module | 160000 | 16,000 | 8,000 | 葉節點模組(不再細分的底層模組)容量上限 |
max_depth | 誤傳控制分群深度 | 2 | 2 | 寫作 Agent 遞迴產生子 Agent 的最大委派層數 |
把門檻放大 10 倍雖不會讓程式崩潰,但會導致分群階段幾乎不切分模組,失去細粒度架構拆解的效果。建議將 ~/.codewiki/config.json 重設回 32768/36369/8000,讓分組行為回到官方調校軌道。
這兩組參數的作用不同,源於解析、分群與撰寫三階段的分工:
- 第一階段:靜態解析與 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選出進入點元件。 - 第二階段: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"備援模組。 - 第三階段:Agent 遞迴寫作(
max_depth = 2):寫作 Agent 經由編輯器、元件讀取與子模組生成工具寫入檔案。max_depth只限制寫作階段遞迴產生子 Agent 的委派層數,與前一階段的分群切分毫無關係。另外,組裝USER_PROMPT時內嵌的模組樹與檔案內容受 900,000 字元預算限制(prompt_template.py,為避開 codex 伺服器端1,048,576字元的input_too_large硬上限),超限時會自動裁切內嵌內容,改由 Agent 呼叫讀檔工具補讀。
NOTE
CLI 生成實戰:繁中輸出、客製指示與目錄結構
執行生成任務時,常用 CLI 旗標包含:
- 產生繁體中文文件(
--language zh-TW):官方內建多語系開關,傳入語言程式碼或名稱即可輸出繁體中文內容,且生成的檔案名稱與模組名稱仍保持純 ASCII,不會破壞網址路由。 - 注入團隊專屬指示(
--instructions):可傳入如"讀者是 DevOps 工程師"等客製指示。該指示會包在<CUSTOM_INSTRUCTIONS>標籤中注入所有模組與頂層總覽頁(overview.md)的系統提示詞。 - 指定文件類型與範圍(
--doc-type、--focus):--doc-type支援api、architecture、user-guide、developer四種值;搭配--focus可針對特定子系統加強描述,或用--github-pages --create-branch與--techdocs匯出發布格式。 - 選擇目錄結構(
hierarchicalvsflat):doc_layout.py定義兩種結構——預設hierarchical按模組樹建子資料夾(如auth/session/store.md),flat則將所有.md攤平放於根目錄(給相對連結易寫錯的小模型使用;CodeWiki 自身的 35 篇文件即採flat)。 - 內建的中斷續跑機制:每個模組開跑前會先檢查目標檔案是否已存在且可重複使用,存在便直接跳過;執行後也會驗證檔案確實寫出,防止 Agent 空轉卻回報成功。
一次完整建置後,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 並直接退回完整重建:
- Step 1: Graph Diff (graph_diff.py)比對正規化 body hash 與簽名,只改註解 = 零變更;刪除+新增且本體相似度達 95% (--tau-ren) 視為改名
- Step 2: 模組樹修復規則路由:同檔 -> 同目錄 -> 相依鄰居多數決 (過半數);失敗交 routing agent;模組膨脹逾 33% 觸發重分群
- Steps 3 & 4: 葉節點變更報告與完整重建退回判定追蹤自身變更 + 上游相依 (預設 1 hop) + 頁面已提及元件;活躍模組逾 50% 或結構變更逾 30% 時,退回完整重建
- Steps 5 & 6: 相依序派工與收尾審計Agent 自選原地修補 / 重寫 / no-op,僅准修補相關頁面;掃描失效連結與過時名稱,決策與成本寫入 update_record.json
更新階梯與 CI 參數調校
在工程實務上,上述管線的深度與退回門檻可以 CLI 旗標微調:
- 選擇更新階梯(
--update-rung):提供0至3b五級,直接對應上方管線的啟用程度——0退回 1.x 舊行為(檔案變更即整模組重建);1僅跑 Step 2 的純規則路由;2加上 routing agent 與 Step 3 的 1 hop 上游傳播;預設為3(完整啟用 Step 5 的原頁面原地修補);3b則將 Step 3 的上游相依追蹤(--k-hop)擴充為 2 hops。 - 微調退回與重分群門檻(
--tau-*):若預設門檻在大型重構時過於敏感或遲鈍,可手動調整改名相似度--tau-ren(預設0.95)、鄰居路由門檻--tau-nb(0.5)、模組重分群膨脹率--tau-grow(0.33),以及觸發完整重建的活躍比例--tau-full(0.5)與結構變更比例--tau-tree(0.3)。
TIP
CI 中使用 Squash Merge 請覆寫比對基準:當團隊採用 Squash Merge 或 Rebase 合併進主分支時,PR 分支原記錄於 metadata.json 的個別 commit 節點在合併後會消失,導致主分支 CI 找不到基準;此時應手動傳入 --compare-to HEAD~1 指定基準。
- 自動化審計(
update_record.json):每次更新的結果必為四種之一:no_change(零呼叫零成本)、incremental、full_fallback(附觸發比例)或detector_failure(舊圖載入失敗),所有決策與呼叫成本皆可事後稽核。
工程落實的適用邊界
從 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;單靠靜態邊與語意分組,這類底層系統專案仍難以精準還原架構。