---
slug: openwiki-agent-wiki
title: "OpenWiki：把程式碼庫變成會追來源、能持續更新的 Agent Wiki"
status: published
excerpt: OpenWiki 如何把程式碼庫整理成帶有 Claims、來源證據、MCP retrieval 與持續更新流程的 Agent Wiki。
category: AI
tags: [openwiki, coding-agents, documentation, mcp, github, knowledge-base, developer-tools]
author: Seer
author_role: Author
read_time: 12 min
cover: "/static/openwiki-agent-wiki-cover.png"
closing_note: "文件的價值，不只在於寫完，也在於下一次更新時找得到根據。"
published_at: "2026-09-24T08:45:00Z"
updated_at: "2026-09-24T08:45:00Z"
---

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

[OpenWiki](https://github.com/langchain-ai/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]

基本安裝：

```sh
npm install -g openwiki
```

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

例如：

```sh
openwiki integrations install codex
```

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

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

```text
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：

```sh
openwiki --init
openwiki --update
```

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

```sh
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]

來源可以長這樣：

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

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

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

```text
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 平行處理：

```sh
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]

典型使用方式是：

```text
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 組成同一個服務，可以用：

```sh
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：

```sh
openwiki visualize
```

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

```sh
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]

一個簡化版使用方式是：

```yaml
- 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

可以用環境變數停用：

```sh
export OPENWIKI_TELEMETRY_DISABLED=1
export DO_NOT_TRACK=1
```

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

```sh
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

- [1：OpenWiki official repository](https://github.com/langchain-ai/openwiki)
- [2：OpenWiki README](https://raw.githubusercontent.com/langchain-ai/openwiki/main/README.md)
- [3：OpenWiki package metadata](https://raw.githubusercontent.com/langchain-ai/openwiki/main/package.json)
- [4：OpenWiki Claims types](https://raw.githubusercontent.com/langchain-ai/openwiki/main/src/claims/core/types.ts)
- [5：OpenWiki retrieval tools](https://raw.githubusercontent.com/langchain-ai/openwiki/main/src/integrations/core/retrieval-tools.ts)
- [6：OpenWiki wiki finalizer](https://raw.githubusercontent.com/langchain-ai/openwiki/main/src/agent/wiki-finalizer.ts)
- [7：OpenWiki coding-agent integration skill](https://raw.githubusercontent.com/langchain-ai/openwiki/main/integrations/openwiki/SKILL.md)
- [8：OpenWiki npm package metadata](https://registry.npmjs.org/openwiki/latest)
