本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。 英文原文

AX Wiki 知識庫

狀態：現行 範圍：現行狀態 上次審閱：2026-10-03 負責人：AX Code 執行環境

AX Wiki 是 AX Code 原生的儲存庫 Wiki 編譯器。它把已追蹤的原始碼、設定、測試、工作流程與既有文件，編成一份小型、以原始碼為依據的 Markdown 知識庫，放在 .ax-wiki/ 底下。它使用與 AX Code 相同的供應商設定與模型路由；沒有另外的執行檔，也沒有另外的憑證存放區。

ax-code wiki viz 會畫出編譯後的頁面，以及它們引用的檔案。該圖的螢幕截圖在 Wiki 證據視覺化。

它適合放在哪裡

Wiki 散文是編譯出來的導覽層，不是結構證明。若 wiki 與程式碼不一致，請相信程式碼，並執行 ax-code wiki update。

快速開始

先連接 AX Code 供應商，然後執行：

ax-code wiki plan
ax-code wiki generate
ax-code wiki doctor

ax-code init --wiki 會產生 AGENTS.md、插入 AX Wiki 指標區塊，並在同一個工作流程中編譯 wiki。用 --wiki-only-agents 可以只加指標，而不呼叫模型。

指令

產生選項包含 --model provider/model、--dir <relative>、--quiet、--skip-agents 與 --force。--force 是刻意要求的：只有這樣，才能取代在受保護區段之外手動編輯過的產生內容。

儲存庫目錄

從 v7.22.2 起，預設輸出目錄是 .ax-wiki/。隱藏前綴標示由 AX Code 維護的儲存庫知識。它不會讓檔案被 Git 忽略：請決定要提交這份知識，或把 /.ax-wiki/ 加到儲存庫的 .gitignore。

使用 wiki.dir，位置在 ax-code.json 或 --dir docs/knowledge，可以選擇另一個相對目錄；CLI 旗標優先。所有產生、狀態、代理程式指標、背景維護與視覺化都使用該選擇。編譯器不會自動偵測、移動或合併較舊的 ax-wiki/ 目錄。套件與產生器名稱、ax-wiki.config.json 與 ax-wiki.instructions.md 都不變。

產生的契約

AX Wiki 會寫入 Markdown 頁面與 .ax-wiki/.manifest.json。每個頁面的前言包含：

• generated_by: ax-wiki
• 精簡的 summary
• 從有證據支持的產生所傳回的精確 symbols
• 用來編譯該頁的、相對於儲存庫的 sources

資訊清單儲存確定性的計畫雜湊、儲存庫原始碼雜湊、頁面雜湊、產生模型、git 修訂與產生時間。頁面以不可分割的方式寫入；資訊清單最後寫入，而且只在完整的記憶體內候選通過驗證之後。

原始碼探索優先使用 Git 已追蹤且未被忽略的檔案清單，排除產生、建置與 vendor 目錄以及 wiki 本身，略過二進位或過大的檔案，並拒絕儲存庫以外的路徑或符號連結。

子系統導覽

預設計畫會保留快速開始、架構與開發頁面。若模組超過一頁的原始碼數量或證據位元組預算，也可以得到聚焦頁面，例如 modules/core/src/session.md。這些頁面涵蓋該模組 src、lib 或 app 目錄下的直接子目錄，每個子系統至少三個程式碼檔，而且模組內至少有兩個合格子系統。

子系統頁面包含它們的實作子樹，以及模組 test 或 tests 目錄下相符的檔案。它們的產生指示會要求進入點、執行流程、邊界、具體的變更位置與相關測試。模組頁面會把最多兩個測試檔放在排名最高的原始碼正後面，讓測試能參與有上限的證據選擇。

預設總預算仍是 12 頁，包含三個總覽頁。模組總覽與子系統頁面依原始碼數量競爭剩餘名額；子系統只有在它的父層總覽之後才會納入。因此較大的子系統可以排擠較小的套件頁面。請用 ax-code wiki plan 預覽結果。提高 maxPages（自動計畫最多 40），或在特定子系統需要保證涵蓋時設定明確的 pages。明確計畫具權威，不會再收到自動的子系統頁面。

這改善的是導覽與證據焦點；它不會驗證產生的散文，也不保證代理程式會讀 wiki。依賴實作細節之前，請沿著引用回到目前的原始碼。

代理程式如何使用 wiki

代理程式以三種方式到達 wiki，從最便宜到最具體：

1. 提示索引。 健康的 wiki 存在時，工作階段提示會帶一段短的 <repo_wiki> 區塊：wiki 位置、新鮮度標籤，以及每個頁面一行（路徑與修剪過的摘要，預設 12 頁大約 750 token）。摘要只指出該去哪裡讀；它們不是證明。
2. repo_wiki 工具。 這是唯讀工具，有三種操作：index（帶有每頁新鮮度的頁面卡片）、read（一頁加上它引用的來源、哪些引用來源已變更，以及在那些來源中找不到的前言符號），以及 related（依符號、本文提及或原始碼路徑找頁面）。它在完整與程式開發工具設定檔中可用，並使用 read 權限。
3. 一般檔案工具。 read、glob 與 grep 作用在 .ax-wiki/ 上，仍然可用。

提示的新鮮度是逐頁判斷的：頁面所引用的每個來源仍與資訊清單雜湊相符時，該頁就是新鮮的。新增或編輯、且沒有任何頁面引用的檔案，會讓提示標籤保持 fresh，並加上說明，表示 wiki 尚未涵蓋它。被引用的來源有變時，標籤會標成 stale，提示會要求代理程式只把 wiki 當導覽。ax-code wiki status 與 wiki lint 維持更嚴格的整個儲存庫判定：任何新增、移除或編輯的合格檔案都算過期。

wiki 絕不會取代原始碼：每個 read 結果都會列出要對照驗證的檔案；若頁面與程式碼不一致，程式碼勝出。

增量更新與手動內容

wiki update 會把目前的原始碼雜湊與資訊清單比較，並透過每個頁面的選擇器對應變更。計畫一變，就會重新產生所有已規劃的頁面；否則無關的頁面保持不動。

產生的散文由編譯器擁有。請把持久的維護者文字放在受保護區塊裡：

<!-- AX-WIKI:PROTECTED:START deployment-warning -->

Production migrations require an operator-approved maintenance window.

<!-- AX-WIKI:PROTECTED:END -->

受保護的本文在重新產生後仍然保留。除非提供 --force，否則 AX Wiki 拒絕覆寫其他手動編輯。過時的產生頁面，只有在受管理內容未變、且沒有受保護區段時，才會被移除。

設定

在專案的 ax-code.json 中設定這項整合：

{
  "wiki": {
    "enabled": true,
    "auto": true,
    "dir": ".ax-wiki",
    "model": "openai/gpt-5-mini",
    "autoInjectAgents": true,
    "touchClaudeMd": true,
    "maxPages": 12,
    "generationConcurrency": 2,
    "maxSourcesPerPage": 80,
    "exclude": ["fixtures/**"]
  }
}

include、exclude、maxSourceBytes 與 maxPageSourceBytes 控制證據探索與預算。instructions 會加上專案專用的編譯器指引。若要完全策展的計畫，請設定 pages 項目，並帶上 path、title、purpose 與 selectors；明確計畫必須包含 quickstart.md。

generationConcurrency 接受 1 或 2。原生雲端產生預設同時呼叫兩個頁面；本機引擎與 CLI 供應商預設為一個。當供應商會把重疊請求排入佇列或節流時，把它設為 1。排程不會使既有頁面內容失效。除非提供這個設定，可重用套件維持序列執行。

每個模型頁面最多有兩次已分類的嘗試，共用 180 秒期限。相對的 Wiki 連結會在頁面被接受之前，對照頁面計畫檢查；連結損壞的回應可以用剩下的嘗試修復該頁。發布之前，最終驗證與手動內容防護仍會執行。

被中斷的建置會把已驗證的結果留在 .ax-wiki/.page-cache/（或已設定的 Wiki 目錄）。之後的建置只有在檢查目前的原始碼證據、計畫、產生器、模型與先前內容之後，才重用相符的結果。初始產生在完整候選通過驗證之前不會發布。成功發布會移除已取用的暫存項目；之後明確的 wiki generate 仍會重新產生所有頁面。快取項目有上限，並且受權限把關；損毀或無法存取的項目會被忽略。

.build-report.json 會把模型產生與快取的頁面，和實際已發布的 written 頁面分開。它選擇性的 pages 陣列會記錄每個頁面的嘗試次數、時間、提示與原始碼的位元組大小，以及供應商有提供時的精確 token 用量。失敗或取消的建置不會回報已發布的頁面。

你也可以把編譯器指引放在 ax-wiki.instructions.md，把核心引擎設定放在 ax-wiki.config.json。兩者都有提供時，明確的 AX Code 執行環境設定會覆寫核心設定。

預設的互動式維護

在 AX Code TUI 中開啟專案，預設會啟用背景 Wiki 維護。專案閒置 30 秒之後，缺少的成品會被產生，過期的成品會增量更新。忙碌或正在重試的工作階段、已排入佇列的工作，以及非空白的草稿，會優先並取消背景產生。套用的是目前代理程式的讀寫權限；唯讀代理程式不會產生。這個背景工作流程不會改寫任何代理程式指示檔。

用 "wiki": { "auto": false } 停用背景維護，或用 enabled: false 停用編譯與提示注入。auto 預設為 true，而且不會寫入設定。它使用已設定的 Wiki 模型，或 AX Code 的預設模型，工作期限 10 分鐘，最多自動嘗試三次並退避。明確的圖請求，或原始碼與設定的變更，可以再允許一次嘗試。無介面執行與 CI 不會啟用互動式排程器。非 Git 目錄需要明確請求。在 Git 專案中，Wiki 的產生與取用使用最近的工作樹根目錄，因此在套件裡開啟 AX Code 不會建立分開的套件 Wiki。

工作階段側邊欄與 /wiki-viz 會立刻開啟本機進度頁，並要求維護。快照就緒之後，該頁會顯示已記錄的 Wiki 頁面與原始碼關係。請見 Wiki 視覺化。

代理程式路由

健康的 wiki 存在，而且 wiki.enabled 不是 false 時，工作階段提示會收到精簡的 <repo_wiki> 協定。它告訴代理程式從快速開始著手，只載入相關頁面，透過引用的檔案驗證重要主張，結構問題則使用圖與 LSP 工具。

healthy 描述 wiki 目錄、索引與資訊清單是否存在。分開的 freshness 欄位是 fresh、stale 或 unknown。狀態與工作階段路由會用有效的包含、排除與大小設定，比較目前的原始碼雜湊，因此未提交的編輯、新增與刪除都會被偵測到。檢查不會重用已快取的新鮮判定；它們會以有上限的讀取並行掃描合格來源。缺少或停用的 wiki 會略過原始碼掃描。新鮮度是某個時間點的原始碼檢查，不是驗證每一個產生的主張或頁面；成品驗證請用 lint。

過期或未驗證的 wiki 仍可用於導覽，並有明確指示：依賴實作主張之前，先驗證目前的原始原始碼。驗證錯誤會產生 unknown。沒有 wiki 目錄時，wiki status 以 0 結束（缺少 wiki 就是報告）。有 wiki 時，若 wiki 不健康，或新鮮度不是 fresh，就會以失敗結束。

Wiki 證據有上限：在頁面預算內，每個選取的來源最多貢獻前 32,000 個位元組，截斷會標給產生器。GraphContext 可以加入選取的片段，但每個片段最多 80 行。這些導覽輔助不保證保留每一個變更的函式或必要的防護；範圍審查時，請另外提供必要的原始程式碼。

受管理的 <!-- AX-WIKI:START --> 區塊位於 AGENTS.md，帶有相同的路由原則，而不把 wiki 內容複製進儲存庫指示。

CI

在已通過供應商驗證的工作中，先執行 ax-code wiki update，再執行 ax-code wiki lint，然後開啟文件 PR。請見 examples/ax-wiki-update.yml。把產生的 wiki 變更當成其他文件：審查原始碼引用，並避免自動合併模型輸出。

疑難排解