085

OpenWiki:把程式碼庫變成會追來源、能持續更新的 Agent Wiki

OpenWiki:把程式碼庫變成會追來源、能持續更新的 Agent Wiki 封面圖

OpenWiki 如何把程式碼庫整理成帶有 Claims、來源證據、MCP retrieval 與持續更新流程的 Agent Wiki。

Seer

2026-09-24

很多團隊都有一份「看起來像文件、實際上很快過期」的 README。程式碼改了,架構圖沒改;API 換了,Agent 還在讀舊說明;多個 repository 放在同一個服務裡,知識又被切散在不同地方。

OpenWiki 的做法,是把程式碼庫和相關知識整理成一套由 Markdown 組成的 linked wiki,再把每個重要事實綁回版本化的 source evidence。它提供給 coding agent 的不只是「一份自動生成文件」,還包含可持續更新的頁面佇列、Claims、索引、來源追蹤與本地檢索工具。[1][2]

本文會整理 OpenWiki 的定位、安裝與使用方式,拆解它如何處理程式碼文件的生成和更新,再看 Claims、MCP retrieval、跨 repository workspace、CI 排程與隱私邊界。本文依官方 README、package metadata、核心 TypeScript 與整合 skill 整理;命令與功能分別標示為官方文件或原始碼可核對的行為。

先講定位:OpenWiki 維護的是 Agent 讀得懂的專案記憶

OpenWiki 的主產物是一個放在 repository 裡的 openwiki/ Markdown wiki。它可以記錄架構、概念、工作流、操作方式、整合與測試,coding agent 之後能透過 OpenWiki 的 retrieval 工具找出相關頁面,再回到目前的程式碼核對重要細節。[2][7]

它的核心問題可以拆成三層:

  1. 文件生成:第一次掃描 repository,建立一套可讀的 wiki。
  2. 文件維護:程式碼變更後,只更新受影響的頁面,保留未受影響的內容。
  3. 證據管理:頁面中的重要事實,保留對應的 source resource 與版本資訊,讓下一次更新知道哪些內容需要重新確認。

這種設計適合以下情境:

  • 新成員需要快速理解大型 repository。
  • coding agent 常常需要先搜尋架構,再修改程式。
  • 一個服務分散在 control plane、data plane、infrastructure 等多個 repository。
  • 團隊希望文件留在 Git 裡,可以 review、回溯與跟著程式碼一起更新。
  • 需要把文件更新放進排程 CI,降低依賴人工記憶的維護成本。

OpenWiki 的 README 也把它定位成「你擁有的 linked Markdown wiki」:文件留在自己的 repository,Agent 可以讀取,使用者也能直接閱讀或輸出成圖形化 visualizer。[2]

安裝與第一條工作流

目前 package metadata 顯示 openwiki 的套件版本是 0.6.0,需要 Node.js 22.22.0 以上,CLI 入口是 openwiki,授權是 MIT。[3][8]

基本安裝:

npm install -g openwiki

接著選一個 coding agent 整合。官方 README 目前列出的整合包括 Codex、Claude Code、OpenCode、Cursor、IBM Bob / Bob Shell、Kiro、Oh My Pi 和 Antigravity。[2]

例如:

openwiki integrations install codex

預設是 user-level 安裝,一次安裝後可以從不同 Git repository 使用;如果只想裝在特定專案,加入 --project,並用 openwiki integrations list 查看目前狀態。[2][5]

完成安裝後,重新啟動 coding agent,進入目標 repository,直接提出:

Initialize this repository's OpenWiki from the current source and tests.

OpenWiki 會讓 Agent 研究 repository、規劃頁面,再把結果寫進 openwiki/。每個頁面完成後保存進度,所以中途中斷時,已完成的頁面可以成為下一輪的 resume 單位。[2][7]

這裡有一個重要的工具分工:

  • coding-agent integration 使用宿主 Agent 的 repository tools 與已登入模型 session。
  • OpenWiki 負責 durable queue、Claims 驗證與保存、source-drift 處理、索引、provenance 和 finalization。
  • OpenWiki 不會替 coding agent 自己準備另一個模型 provider。[2][7]

如果不想透過外部 coding agent,也可以使用 OpenWiki 自己的 Deep Agents CLI:

openwiki --init
openwiki --update

這條路徑會在第一次執行時設定 provider、credentials 和 model,之後把程式碼 wiki 寫進目前 repository 的 openwiki/。個人知識庫則使用另一個模式:

openwiki personal --init
openwiki personal --update

Code mode 針對目前 repository;Personal mode 使用連接器與 ~/.openwiki/wiki。官方也明確區分:coding-agent integration 目前處理 repository code wiki,個人 brain 與 connector context 走 native CLI 的 personal 模式。[2]

真正的核心:每一頁都有 Grounded Claims

OpenWiki 最值得看的地方是 Claims 設計。

一般自動文件工具多半只產生 Markdown。OpenWiki 會為重要事實建立一筆 Claim,保存三個核心欄位:

  • id:穩定的 Claim 識別碼。
  • statement:一個具體、可被檢查的事實敘述。
  • evidence:支援這個敘述的 source resource,以及當時觀察到的版本。[4]

來源可以長這樣:

repo://src/server.ts#L40-L82

這讓「這個頁面說了什麼」和「它根據哪一段程式碼說」分開保存。下一次更新時,OpenWiki 可以檢查 source evidence 是否改變,再決定 Claim 要保留、更新或撤回。

Claims 的更新操作也被拆成明確類型:

add       新增一個事實
confirm   確認既有事實仍然成立
update    修改既有事實或替換 evidence
retract   撤回已不再成立的事實

原始碼的型別定義把這四種 mutation 固定下來,新的 Claim 不由模型自行指定 ID;既有 Claim 也不應該被模型任意重建。[4]

這帶來一個實務上的差異:更新文件時,OpenWiki 追蹤的單位不只是「這個 Markdown 檔案上次什麼時候改過」,還包含「這句話依據的程式碼版本有沒有變」。

例如一頁文件寫著:

Retry manager 會在連續三次失敗後降低併發度,並將當前工作交回 queue。

如果 retry manager 的實作改了,OpenWiki 可以把對應 Claim 標記成需要確認的內容。Agent 重新研究後,可以保留、改寫或撤回該 Claim;文件和證據資料會一起被更新。

這套機制仍然依賴 Agent 能否正確研究與描述程式碼。Claims 可以讓證據路徑可檢查,無法單獨保證文字一定正確;它比較像文件維護的驗證骨架,語意正確性仍需要人工與測試共同把關。

一次生成為什麼能續跑?

OpenWiki 把 repository 文件生成拆成一個有狀態的 page-job lifecycle:

  1. 研究 repository 並規劃 wiki taxonomy。
  2. 建立每一頁的工作項目與相關頁面。
  3. 逐一取出 pending page job。
  4. Agent 研究該頁需要的 source、caller、dependency、test 和 operational contract。
  5. 寫入 Markdown 和 Claims decision。
  6. 驗證頁面、Claims、索引與內部連結。
  7. 將完成頁面保存,繼續下一頁。
  8. 全部完成後執行 finalization。

OpenWiki 的 integration skill 要求 Agent 遵守 openwiki_begin → openwiki_submit_plan → openwiki_next_page → openwiki_submit_page → openwiki_finish 的生命週期;如果 source drift 讓原本的 plan 失效,就要重新開始並提交替代計畫。[7]

Native CLI 的 repository init 和 update 可以使用 page workers 平行處理:

OPENWIKI_PAGE_CONCURRENCY=4 openwiki --update

README 說明預設併發數是 1,可設定 1 到 8;每個 worker 處理一頁,完成頁面會成為 durable resume unit。Provider 發生 rate limit 時,系統會降低後續併發度,並把當前失敗頁面交給後續 update 重試。[2]

這裡要把兩條路徑分開看:

  • Native CLI:可以用 page concurrency 平行生成。
  • Coding-agent integration:使用宿主 Agent 的 sequential page lifecycle,由 OpenWiki 負責 queue、Claim 與 finalization。

兩者都叫 OpenWiki,執行形狀卻不同,不能把 native CLI 的併發設定直接套到 coding-agent integration。

Finalizer 做什麼?

頁面寫完後,OpenWiki 還會做一輪 deterministic finalization。原始碼目前明確列出幾個步驟:[6]

  1. Mermaid 驗證。
  2. wiki index 同步。
  3. 內部連結驗證。
  4. Claims source projection。
  5. generated provenance reconciliation。

這個順序很重要。OpenWiki 會在 Agent 產出 Markdown 後繼續處理頁面、索引、Claim evidence、provenance 和 link structure,最後整理成可持續維護的狀態。

對團隊來說,這比「每次重新生成整本文件」更接近一般軟體工程流程:生成是可中斷的,頁面有自己的完成狀態,來源有自己的版本,最後再由固定的檢查步驟收斂輸出。

Agent 怎麼查這套 Wiki?

OpenWiki 提供的 retrieval 工具目前包含:

  • openwiki_list_workspaces
  • openwiki_list_wikis
  • openwiki_search
  • openwiki_read

openwiki_search 會從既有 wiki 找 compact、ranked results;openwiki_read 再讀取搜尋結果指定的完整 Markdown section。兩者都是 local、read-only、model-free,不會自行啟動生成,也不會額外呼叫模型。[5][7]

典型使用方式是:

Search this repository's OpenWiki for how retry handling works,
then read the relevant sections.

Agent 先用 openwiki_search 找到頁面和 heading anchor,再把 page、section 和必要的 wiki ID 傳給 openwiki_read。這個設計把「找哪裡」和「讀完整內容」拆開,可以避免每個任務一開始就把整本 wiki 預載進上下文。[5][7]

如果多個 repository 組成同一個服務,可以用:

openwiki link
openwiki workspace use payments
openwiki workspace current
openwiki workspace clear

每個 repository 保留自己的 wiki,也可以加入多個 workspace。搜尋時,如果 repository 只屬於一個 workspace,會自動使用它;如果同時屬於多個 workspace,又沒有 active workspace,搜尋會回傳 workspace_required,讓 Agent 先請使用者選擇範圍。[2][5]

這個 workspace 機制解決的是「相關 repository 太多」的範圍問題。它仍然不等於跨整個公司所有資料的全域搜尋;每次搜尋要有明確 workspace,結果也會帶出來源 wiki,後續再讀取指定頁面。

Visualizer:把 Markdown Wiki 變成可探索的圖

OpenWiki 也提供本地 visualizer:

openwiki visualize

它會在 loopback address 上啟動服務,左側顯示 wiki 的節點圖,右側顯示 Markdown reader。若要輸出靜態版本:

openwiki visualize openwiki --export docs/openwiki-visualizer

輸出目錄包含 index.html、client.js、client-lib.js、styles.css 和 graph.json,可以放到 GitHub Pages、MkDocs 或其他靜態主機。[2]

這裡有一個容易漏掉的邊界:官方 README 說 visualizer 的 graph、Markdown 和 diagram library 會從 public CDN 載入,因此本地和靜態 viewer 都需要網路連線。[2]

所以它適合作為文件探索介面,不適合直接宣稱成完全離線的知識產品。

放進 CI:讓文件跟著變更走

OpenWiki 官方提供 GitHub Actions、GitLab CI 和 Bitbucket Pipelines 的範例。GitHub Actions 版本大致會做這些事:

  1. 使用完整 Git history checkout repository。
  2. 安裝 Node.js 22 與 OpenWiki。
  3. 設定 provider、model 與 credentials。
  4. 執行 openwiki code --update --print。
  5. 清理暫存 .run.json。
  6. 只把 openwiki、AGENTS.md、CLAUDE.md 和 workflow 相關檔案放進更新 PR。[2]

完整 history 很重要,因為 update 需要知道上一次文件化到哪個 commit;如果 CI 只抓 shallow clone,變更範圍可能無法正確計算。[2]

一個簡化版使用方式是:

- name: Install OpenWiki
  run: npm install --global openwiki

- name: Update repository wiki
  run: openwiki code --update --print
  env:
    OPENWIKI_PROVIDER: openrouter
    OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

實際放進團隊前,還要補上:

  • 固定 OpenWiki 版本,不要讓 CI 每次漂移到不同 latest。
  • 把 provider secret 放在 CI secret,不放進 repository。
  • 限制 PR 的 add-paths,避免生成流程修改到不相關檔案。
  • 對自動合併設定人工 review 或 branch protection。
  • 決定是否保存失敗前已完成的部分頁面。

OpenWiki 的範例也特別提醒,auto-merge 是 repository infrastructure 的事情,不等於 OpenWiki 自己擁有安全合併能力;required checks、token 權限與 branch rules 仍然要由團隊設定。[2]

隱私、遙測與 ignored paths

OpenWiki 的 telemetry 預設開啟,但官方描述的 openwiki_run 事件只收集匿名安裝 ID、命令、成功/失敗結果、粗略錯誤分類,以及 setup 時的 brain mode、model provider 和 connector names。[2]

官方列出的不收集項目包括:

  • 檔案內容
  • repository 名稱與資料
  • credentials
  • prompt
  • model output
  • connector payload
  • error message
  • file path、URL、model ID
  • run duration 與 IP address

可以用環境變數停用:

export OPENWIKI_TELEMETRY_DISABLED=1
export DO_NOT_TRACK=1

如果要確認實際送出的 payload,也可以使用:

openwiki --telemetry-file /tmp/openwiki-telemetry.json

但 telemetry 只是其中一層。OpenWiki 要讀 repository、呼叫模型 provider、使用 coding-agent tools,這些資料流仍然要依照團隊自己的 provider、Agent、CI 與 connector 設定檢查。

另一方面,.openwikiignore 可以限制檔案系統掃描和 shell execute,讓 secrets、log、generated files 或其他目錄不要被讀取。[2]

它提供的是 read boundary,無法保證敏感資訊完全消失。README 也說,忽略路徑仍可能從其他允許讀取的 README、tests 或 commit message 被推論出來。因此敏感資料治理仍然要放在 repository 權限、provider policy 和 Agent host 的安全設定上。

OpenWiki 適合誰?

適合導入的情境

  • Repository 進入多人維護,原作者離開後文件難以接手。
  • 一個服務拆成多個 repository,需要跨 repo 查找架構上下文。
  • coding agent 常常重複做「找入口、讀 config、追 caller、找測試」的工作。
  • 希望文件變更可以透過 Git diff、PR 與 Claims evidence review。
  • 團隊願意讓文件更新成為 CI 或 release 流程的一部分。

不必急著導入的情境

  • 專案很小,README 和測試已經足夠。
  • 團隊沒有固定 provider、Agent 或 CI credential 管理方式。
  • 希望得到完全自動、零人工核對的產品文件。
  • 只想要一次性的程式碼摘要,不打算維護 repository 內的 wiki。
  • 需要完全離線的可視化文件介面,但沒有準備自行處理 CDN 依賴。

結論:把文件生成改成可維護的 repository artifact

OpenWiki 的重點在「維護」兩個字。

它把程式碼文件拆成幾個可以持續檢查的部分:Markdown 頁面、page queue、Grounded Claims、source versions、retrieval tools、workspace registry 與 deterministic finalizer。這讓 Agent 之後查資料時,能先從既有 wiki 找到上下文,再回目前程式碼確認重要細節。

如果你只是想快速產生一份 README,OpenWiki 的完整 Claims、workspace 和 CI 結構可能顯得偏重。若你的問題是多個 Agent 反覆重新探索同一個 repository,或文件隨程式碼變更而失去可信度,OpenWiki 的設計就比較有價值。

我會把它的採用順序排成:

  1. 先在一個中型 repository 執行 code wiki 初始化。
  2. 檢查 openwiki/、AGENTS.md、CLAUDE.md 和 .claims 的 diff。
  3. 設定 .openwikiignore,確認敏感路徑不會進入研究範圍。
  4. 讓 coding agent 用 openwiki_search 和 openwiki_read 查一次具體問題。
  5. 確認 update 是否能保留未受影響頁面,再接 CI 排程。
  6. 最後才把多個 repository 放進 workspace,避免一開始就把範圍做大。

OpenWiki 把「AI 幫你寫文件」往前推了一步:真正需要管理的,不只是生成結果,還有結果背後的來源、版本、更新範圍和下一次查找入口。

Sources

文件的價值,不只在於寫完,也在於下一次更新時找得到根據。

Visits

--

Waiting for Cloudflare metrics.