)
OpenClaw 文檔疊加層Documentation Overlay頁面類型分類、信息架構與驗證命令實戰(zhàn)【免費下載鏈接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 項目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 倉庫在通用技術文檔技能之上專門維護了一份名為 OpenClaw Documentation Overlay 的文檔工程規(guī)則集.agents/skills/technical-documentation/references/openclaw.md它規(guī)定了 OpenClaw 文檔工作的頁面類型、主題頁/指南頁的標準結構、信息架構導航規(guī)則、源碼佐證要求、改寫保留審查流程以及驗證命令清單。讀完本文你將掌握在 OpenClaw 這類大型文檔庫中寫之前先選頁面類型、寫完后按最窄證明跑驗證的完整文檔工程方法論并能直接使用倉庫內對應的腳本與命令自行驗證每一條規(guī)則。Overlay 的定位疊加而非替代這份參考文件開篇即聲明它只用于 OpenClaw 的文檔工作Use this reference only for OpenClaw docs work其作用是把 OpenClaw 專屬的頁面類型、導航、保留preservation與驗證規(guī)則疊加layer在通用 technical-documentation 技能之上。這一疊加關系在整個技能目錄中有明確的組織方式技能入口 .agents/skills/technical-documentation/SKILL.md 的 Workflow 第 6 步寫明處理 OpenClaw 文檔任務時readreferences/openclaw.mdbefore the build/review playbook即必須先讀 overlay 再進入構建/評審流程通用規(guī)則集位于 .agents/skills/technical-documentation/references/principles.md其Practical merge policy規(guī)定規(guī)則沖突時的優(yōu)先級讀者任務成功 結構清晰 長期可維護性 Agent 優(yōu)化并明確When the target repo or request is OpenClaw-specific, layerreferences/openclaw.mdon top評審手冊 .agents/skills/technical-documentation/references/review.md 在 Scope、OpenClaw 專屬檢查項、結構檢查等多個環(huán)節(jié)都回指 overlay要求confirm the content matches an explicit page type fromreferences/openclaw.md。換言之overlay 不是一個獨立體系而是一層倉庫作用域的策略約束通用原則管文檔怎么寫才好overlay 管OpenClaw 文檔長什么樣、放哪里、怎么證明寫對了。讀者模型五條寫作立場Overlay 的 Reader Model 一節(jié)給出五條面向讀者的寫作立場這是所有頁面類型共享的底層約束以讀者要完成的任務開頭Lead with the task the reader is trying to complete先給一條推薦路徑再談備選方案Give one recommended path before alternatives主文檔只聚焦常見路徑把高密度的契約細節(jié)和罕見的調試細節(jié)下沉到鏈接引用的 reference 或 troubleshooting 頁生產(chǎn)風險必須寫在讀者真正可能犯錯的那個位置而不是集中到某處注意事項章節(jié)把概念、指南、參考、CLI 頁、SDK 文檔、測試、排障互相鏈接讓讀者無需重讀就能繼續(xù)深入。第 3 條和第 5 條在 OpenClaw 的實際文檔中可以直接觀察到例如 docs/gateway/index.md 的 frontmatter 中read_when: Running or debugging the gateway process開篇即以Use this page for day-1 startup and day-2 operations of the Gateway service點明任務場景并把深度排障通過 Card 組件鏈接到專門的 troubleshooting 頁——這正是主路徑聚焦 細節(jié)下沉 橫向鏈接規(guī)則在成品文檔中的體現(xiàn)。八種頁面類型寫之前先分類Overlay 要求Choose the page type before writing or reviewing共定義八種頁面類型頁面類型職責Overview總覽把讀者路由到正確的產(chǎn)品區(qū)域、集成路徑或指南Quickstart快速上手用最少且安全的步驟讓新用戶拿到一個可用的結果Topic page主題頁端到端地解釋一個重要的 OpenClaw 實體或能力面surfaceGuide指南從前提條件走到生產(chǎn)就緒走通一個完整工作流API/SDK/CLI reference參考定義范圍內每一個對象、方法、命令、選項、響應、錯誤、枚舉、默認值和版本規(guī)則Testing guide測試指南展示沙箱搭建、fixture、模擬故障以及 live 模式差異Troubleshooting guide排障指南把可觀察的癥狀映射到檢查項、原因和修復Governance file治理文件保持 agent/貢獻者策略具體、有作用域、并與當前 OpenClaw 倉庫行為對齊分類是后續(xù)所有規(guī)則的錨點結構模板見下兩節(jié)按頁面類型選擇導航歸屬見信息架構一節(jié)按頁面類型放置驗證手段見驗證體系一節(jié)按觸碰的表面選擇。Topic Page 的標準結構八步Overlay 為主要實體頁規(guī)定了固定的章節(jié)形狀標題直接以實體或能力面命名無標題的開篇段Unheaded opening說清它是什么、它擁有什么owns、以及它不擁有什么Requirements僅當設置確實需要賬號、版本、權限、插件、操作系統(tǒng)或憑證時才出現(xiàn)Quickstart推薦路徑 最小可靠驗證Configuration把與任務強相關的選項內聯(lián)寫出窮舉式細節(jié)鏈接到參考文檔主要子主題按讀者意圖reader intent組織禁止用一個泛化的 Subtopics 標題兜底Troubleshooting只寫可觀察的失敗現(xiàn)象和具體檢查項Related links指向指南、參考、命令、概念和相鄰主題。其中第 2 條說清不擁有什么和第 6 條按意圖組織子主題是主題頁最容易違背的兩條。前者迫使作者在開篇就劃定邊界避免讀者把 A 實體的問題帶到 B 實體的頁面來找答案后者與 Reader Model 第 3 條呼應——密度高的內容要按意圖分流而不是堆在一個通用容器里。Guide 的標準結構九步工作流類頁面使用另一套形狀標題以結果命名而不是實現(xiàn)細節(jié)命名Title naming the outcome, not the implementation detail開篇說明讀者能完成什么Before you begin賬號、密鑰、權限、版本、工具與假設Choose a path僅當讀者確實必須做選擇時才出現(xiàn)Steps動詞開頭的標題配命令、預期輸出和檢查點Test用最小可靠證據(jù)證明工作流確實跑通Production readiness安全、重試、限制、可觀測性、遷移與清理Troubleshooting緊挨著會導致失敗的那個工作流放置而不是游離到文末之外See also鏈接概念、參考、SDK 文檔與相鄰指南。與 Topic Page 對比可以提煉出兩者的分工主題頁回答這個實體是什么、怎么用指南回答如何從 0 走到生產(chǎn)。Overlay 刻意在第 4 步加上only when the reader must decide的限定防止指南頁退化成菜單頁第 8 步則再次落實風險寫在讀者會犯錯的地方這一讀者模型原則。文檔信息架構IA與導航規(guī)則Overlay 的 Docs IA And Navigation 一節(jié)給出五條導航規(guī)則每一條都能在倉庫里找到對應物改導航之前先讀 docs/docs.json。這是 OpenClaw 的 Mintlify 文檔站配置theme: mint、$schema: https://mintlify.com/docs.json定義了站點名稱、導航、字體、配色與重定向主題頁與常見工作流留在主讀者路徑上窮舉契約、生成的參考、僅維護者可見的細節(jié)與支持性材料放到Reference或其他作用域清晰的支持頁下生成的plugins/reference/*子頁與純重定向頁除非明確要求否則不出現(xiàn)在可見導航里。這條規(guī)則的現(xiàn)實背景在 docs/docs.json 的redirects數(shù)組中可見倉庫中存在大量形如/plan/swarms - /en/tools/swarm、/concepts/channel-docking - /en/concepts/session#retired-channel-docking的重定向記錄說明頁面搬遷、退役retired是常態(tài)而純重定向頁不應污染導航樹頁面搬遷時交接材料中必須包含 keep/drop/move/destination 矩陣保留/丟棄/移動/目標位置與后文保留審查一節(jié)呼應為參與文檔索引的頁面添加 Read when 提示用于 docs-list 路由。第 5 條在倉庫中有完整的工具鏈支撐scripts/docs-list.js 會遍歷docs/下的.md/.mdx文件排除archive、research等目錄解析 frontmatter 中的summary與read_when字段為文檔感知型工具渲染按需的標題元數(shù)據(jù)。以 docs/index.md 為例summary: OpenClaw is a multi-channel gateway for AI agents that runs on any OS. read_when: - Introducing OpenClaw to newcomersread_when聲明的就是什么意圖的讀者應該被路由到這里它把 Overlay 的按讀者意圖組織規(guī)則從寫作約束落成了可被腳本解析的元數(shù)據(jù)。源碼佐證原則Source-Backed ContentOverlay 要求文檔內容必須以當前倉庫行為為證據(jù)共五條CLI 文檔必須與當前的 flags、輸出、錯誤、示例一致API/SDK 文檔必須包含字段、默認值、枚舉取值、約束、可空行為、生命周期狀態(tài)、錯誤與恢復指引配置文檔必須與導出的類型、schema/help 輸出、元數(shù)據(jù)、基線文件和當前文檔對齊依賴支撐的行為dependency-backed behavior必須先從上文檔、源碼或類型中核實才能寫下默認值、時序、錯誤或 API 行為嚴格區(qū)分四種狀態(tài)當前行為current、已發(fā)布行為shipped、計劃行為planned、維護者意圖maintainer intent。第 5 條尤其針對文檔領先于代碼的常見漂移把 roadmap 寫成能力、把 PR 討論寫成已發(fā)布行為都會讓文檔從可驗證的契約退化為愿望清單。在 OpenClaw 這樣的倉庫中這一條可以通過docs:check-links、生成腳本如 scripts/generate-base-config-schema.ts 這類 schema 生成入口以及plugins/reference生成物與源頁面的比對來落地。示例寫作規(guī)范ExamplesOverlay 對代碼示例與命令示例給出八條硬規(guī)范優(yōu)先給完整的、可直接復制粘貼的命令與片段使用現(xiàn)實的變量名和取值占位符一律用尖括號命名如API_KEY當預期輸出有助于驗證時展示成功輸出每個代碼塊只承載一個概念單元并使用語言特定的 fence避免隱藏 setup、auth、錯誤處理或清理的看起來能跑的示例絕不暴露真實密鑰、線上配置、電話號碼、私密視頻或憑證示例必須自包含與 principles.md 中Keep examples self-contained and minimize dependencies的通用約束一致。這八條實質上把示例當作可執(zhí)行的契約來對待復制即可運行、運行即可驗證、驗證即閉環(huán)。保留審查Preservation Reviews改寫與拆分時不丟事實針對改寫rewrite或拆分split文檔的場景Overlay 定義了五步保留審查流程改寫前先識別源單元source units標題、段落、表格、示例、CLI/API 契約、警告、排障事實把每個保留單元映射到目標頁面或章節(jié)寬泛的 covered 標記不構成稠密材料的證據(jù)——當源單元信息密度高時必須使用行級或論斷級line- or claim-level的證據(jù)對丟棄的內容必須定性是過時obsolete、他處重復duplicated elsewhere、不受支持unsupported還是移到了參考/支持頁當使用 docs-audit 產(chǎn)物時驗證它是帶非空mappings[]的映射審計數(shù)據(jù)而不僅僅是清單或重新索引的 JSON。這套流程與導航一節(jié)第 4 條的 keep/drop/move/destination 矩陣是同一枚硬幣的兩面矩陣管頁面級去向保留審查管內容級去向。它的工程價值在于把我改寫了這一頁從主觀陳述變成可審查的映射表——任何一條警告、一個字段表、一條排障事實都能被問到它現(xiàn)在在哪、為什么。驗證體系選擇最窄的證明Overlay 最后一節(jié)給出了驗證命令清單核心原則是Choose the narrowest proof that covers the touched surface選擇能覆蓋觸碰表面的最窄證明驗證命令適用表面?zhèn)}庫內實現(xiàn)pnpm docs:list文檔清單與 frontmatter 元數(shù)據(jù)scripts/docs-list.jspnpm docs:check-mdxMDX 語法與結構scripts/check-docs-mdx.mjs對docs目錄與根 README 運行pnpm docs:check-links文檔內鏈接有效性scripts/docs-link-audit.mjs另有--anchors變體校驗錨點pnpm docs:check-i18n-glossary國際化術語表一致性scripts/check-docs-i18n-glossary.mtspnpm format:docs:check或pnpm lint:docs格式化與 Markdown 風格scripts/format-docs.mts--check模式lint:docs使用 config/markdownlint-cli2.jsoncgit diff --check空白字符/沖突標記等低級問題git 自帶生成文檔或清單檢查生成的參考、插件目錄、labeler、文檔腳本被修改時對應生成腳本如 scripts/docs-link-audit.mjs 同族的生成/審計入口行為測試或命令探針behavior tests / command probes文檔聲稱了運行時行為時倉庫內的測試與命令探測上述腳本名與命令的映射可以在 package.json 的 scripts 段逐一核對docs:list、docs:check-mdx、docs:check-links、docs:check-links:anchors、docs:check-i18n-glossary、format:docs:check、lint:docs等。此外倉庫還提供 scripts/docs-map:genpnpm docs:map:gen生成帶標題的文檔地圖作為導航變更前的盤點手段。清單最后還有一條兜底規(guī)則如果驗證被阻斷必須明確說出哪條命令沒有跑、以及為什么If proof is blocked, say exactly which command was not run and why。這保證了未驗證本身也是一個可審計、可追蹤的狀態(tài)而不是被靜默跳過。把 Overlay 放回完整工作流結合技能入口 SKILL.md 的 Workflowoverlay 在整個文檔工作流中的位置是任務分類build/review × brownfield/evergreen盡早盤點文檔全貌治理文件 產(chǎn)品文檔讀 principles.md 獲取通用規(guī)則集若是 OpenClaw 文檔工作讀本文所述的 overlaybuild 走 build playbookreview 走 review.md 并主動發(fā)現(xiàn)問題輸出交付物 驗證說明 遺留缺口其中 OpenClaw 專屬檢查項頁面類型歸屬、docs/docs.json導航、生成參考頁可見性、保留映射全部來自 overlay?？梢酝茢噙@種通用原則 倉庫 overlay的分層設計是 OpenClaw 文檔體系能同時服務人類讀者、搜索引擎和 Agent 的關鍵通用原則保證跨倉庫可遷移的寫作質量overlay 則把導航歸屬、保留審查、最窄驗證這些只能在具體倉庫語境下成立的約束固化成了可執(zhí)行的檢查項。小結Overlay 是一份作用域明確的疊加規(guī)則只在 OpenClaw 文檔工作中生效先于 build/review playbook 被讀取先選頁面類型再寫內容八種頁面類型各自綁定結構模板、導航歸屬與驗證手段導航以 docs/docs.json 為單一事實源生成的參考頁與純重定向頁默認不進入可見導航頁面搬遷必須附帶去向矩陣內容以源碼為證CLI flags、API 字段、配置默認值都要能從倉庫中的類型、schema、help 輸出或測試中復驗改寫必須可追溯每個源單元都要有保留映射丟棄內容必須定性驗證取最窄證明pnpm docs:list/docs:check-mdx/docs:check-links/docs:check-i18n-glossary/format:docs:check/lint:docs按觸碰表面選擇被阻斷時明確聲明未跑的命令及原因。遵循這套 overlayOpenClaw 的文檔變更就從憑經(jīng)驗的寫作變成了帶分類、帶導航、帶保留映射、帶最窄驗證的工程化流程——這也是大型多通道網(wǎng)關項目能在數(shù)百頁文檔docs/下 20 主題目錄規(guī)模上保持準確性的方法論基礎?！久赓M下載鏈接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 項目地址: https://gitcode.com/GitHub_Trending/cl/openclaw創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 OpenClaw 文檔疊加層（Documentation Overlay）：頁面類型分類、信息架構與驗證命令實戰(zhàn)
OpenClaw 文檔疊加層Documentation Overlay頁面類型分類、信息架構與驗證命令實戰(zhàn)【免費下載鏈接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 項目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 倉庫在通用技術文檔技能之上專門維護了一份名為 OpenClaw Documentation Overlay 的文檔工程規(guī)則集.agents/skills/technical-documentation/references/openclaw.md它規(guī)定了 OpenClaw 文檔工作的頁面類型、主題頁/指南頁的標準結構、信息架構導航規(guī)則、源碼佐證要求、改寫保留審查流程以及驗證命令清單。讀完本文你將掌握在 OpenClaw 這類大型文檔庫中寫之前先選頁面類型、寫完后按最窄證明跑驗證的完整文檔工程方法論并能直接使用倉庫內對應的腳本與命令自行驗證每一條規(guī)則。Overlay 的定位疊加而非替代這份參考文件開篇即聲明它只用于 OpenClaw 的文檔工作Use this reference only for OpenClaw docs work其作用是把 OpenClaw 專屬的頁面類型、導航、保留preservation與驗證規(guī)則疊加layer在通用 technical-documentation 技能之上。這一疊加關系在整個技能目錄中有明確的組織方式技能入口 .agents/skills/technical-documentation/SKILL.md 的 Workflow 第 6 步寫明處理 OpenClaw 文檔任務時readreferences/openclaw.mdbefore the build/review playbook即必須先讀 overlay 再進入構建/評審流程通用規(guī)則集位于 .agents/skills/technical-documentation/references/principles.md其Practical merge policy規(guī)定規(guī)則沖突時的優(yōu)先級讀者任務成功 結構清晰 長期可維護性 Agent 優(yōu)化并明確When the target repo or request is OpenClaw-specific, layerreferences/openclaw.mdon top評審手冊 .agents/skills/technical-documentation/references/review.md 在 Scope、OpenClaw 專屬檢查項、結構檢查等多個環(huán)節(jié)都回指 overlay要求confirm the content matches an explicit page type fromreferences/openclaw.md。換言之overlay 不是一個獨立體系而是一層倉庫作用域的策略約束通用原則管文檔怎么寫才好overlay 管OpenClaw 文檔長什么樣、放哪里、怎么證明寫對了。讀者模型五條寫作立場Overlay 的 Reader Model 一節(jié)給出五條面向讀者的寫作立場這是所有頁面類型共享的底層約束以讀者要完成的任務開頭Lead with the task the reader is trying to complete先給一條推薦路徑再談備選方案Give one recommended path before alternatives主文檔只聚焦常見路徑把高密度的契約細節(jié)和罕見的調試細節(jié)下沉到鏈接引用的 reference 或 troubleshooting 頁生產(chǎn)風險必須寫在讀者真正可能犯錯的那個位置而不是集中到某處注意事項章節(jié)把概念、指南、參考、CLI 頁、SDK 文檔、測試、排障互相鏈接讓讀者無需重讀就能繼續(xù)深入。第 3 條和第 5 條在 OpenClaw 的實際文檔中可以直接觀察到例如 docs/gateway/index.md 的 frontmatter 中read_when: Running or debugging the gateway process開篇即以Use this page for day-1 startup and day-2 operations of the Gateway service點明任務場景并把深度排障通過 Card 組件鏈接到專門的 troubleshooting 頁——這正是主路徑聚焦 細節(jié)下沉 橫向鏈接規(guī)則在成品文檔中的體現(xiàn)。八種頁面類型寫之前先分類Overlay 要求Choose the page type before writing or reviewing共定義八種頁面類型頁面類型職責Overview總覽把讀者路由到正確的產(chǎn)品區(qū)域、集成路徑或指南Quickstart快速上手用最少且安全的步驟讓新用戶拿到一個可用的結果Topic page主題頁端到端地解釋一個重要的 OpenClaw 實體或能力面surfaceGuide指南從前提條件走到生產(chǎn)就緒走通一個完整工作流API/SDK/CLI reference參考定義范圍內每一個對象、方法、命令、選項、響應、錯誤、枚舉、默認值和版本規(guī)則Testing guide測試指南展示沙箱搭建、fixture、模擬故障以及 live 模式差異Troubleshooting guide排障指南把可觀察的癥狀映射到檢查項、原因和修復Governance file治理文件保持 agent/貢獻者策略具體、有作用域、并與當前 OpenClaw 倉庫行為對齊分類是后續(xù)所有規(guī)則的錨點結構模板見下兩節(jié)按頁面類型選擇導航歸屬見信息架構一節(jié)按頁面類型放置驗證手段見驗證體系一節(jié)按觸碰的表面選擇。Topic Page 的標準結構八步Overlay 為主要實體頁規(guī)定了固定的章節(jié)形狀標題直接以實體或能力面命名無標題的開篇段Unheaded opening說清它是什么、它擁有什么owns、以及它不擁有什么Requirements僅當設置確實需要賬號、版本、權限、插件、操作系統(tǒng)或憑證時才出現(xiàn)Quickstart推薦路徑 最小可靠驗證Configuration把與任務強相關的選項內聯(lián)寫出窮舉式細節(jié)鏈接到參考文檔主要子主題按讀者意圖reader intent組織禁止用一個泛化的 Subtopics 標題兜底Troubleshooting只寫可觀察的失敗現(xiàn)象和具體檢查項Related links指向指南、參考、命令、概念和相鄰主題。其中第 2 條說清不擁有什么和第 6 條按意圖組織子主題是主題頁最容易違背的兩條。前者迫使作者在開篇就劃定邊界避免讀者把 A 實體的問題帶到 B 實體的頁面來找答案后者與 Reader Model 第 3 條呼應——密度高的內容要按意圖分流而不是堆在一個通用容器里。Guide 的標準結構九步工作流類頁面使用另一套形狀標題以結果命名而不是實現(xiàn)細節(jié)命名Title naming the outcome, not the implementation detail開篇說明讀者能完成什么Before you begin賬號、密鑰、權限、版本、工具與假設Choose a path僅當讀者確實必須做選擇時才出現(xiàn)Steps動詞開頭的標題配命令、預期輸出和檢查點Test用最小可靠證據(jù)證明工作流確實跑通Production readiness安全、重試、限制、可觀測性、遷移與清理Troubleshooting緊挨著會導致失敗的那個工作流放置而不是游離到文末之外See also鏈接概念、參考、SDK 文檔與相鄰指南。與 Topic Page 對比可以提煉出兩者的分工主題頁回答這個實體是什么、怎么用指南回答如何從 0 走到生產(chǎn)。Overlay 刻意在第 4 步加上only when the reader must decide的限定防止指南頁退化成菜單頁第 8 步則再次落實風險寫在讀者會犯錯的地方這一讀者模型原則。文檔信息架構IA與導航規(guī)則Overlay 的 Docs IA And Navigation 一節(jié)給出五條導航規(guī)則每一條都能在倉庫里找到對應物改導航之前先讀 docs/docs.json。這是 OpenClaw 的 Mintlify 文檔站配置theme: mint、$schema: https://mintlify.com/docs.json定義了站點名稱、導航、字體、配色與重定向主題頁與常見工作流留在主讀者路徑上窮舉契約、生成的參考、僅維護者可見的細節(jié)與支持性材料放到Reference或其他作用域清晰的支持頁下生成的plugins/reference/*子頁與純重定向頁除非明確要求否則不出現(xiàn)在可見導航里。這條規(guī)則的現(xiàn)實背景在 docs/docs.json 的redirects數(shù)組中可見倉庫中存在大量形如/plan/swarms - /en/tools/swarm、/concepts/channel-docking - /en/concepts/session#retired-channel-docking的重定向記錄說明頁面搬遷、退役retired是常態(tài)而純重定向頁不應污染導航樹頁面搬遷時交接材料中必須包含 keep/drop/move/destination 矩陣保留/丟棄/移動/目標位置與后文保留審查一節(jié)呼應為參與文檔索引的頁面添加 Read when 提示用于 docs-list 路由。第 5 條在倉庫中有完整的工具鏈支撐scripts/docs-list.js 會遍歷docs/下的.md/.mdx文件排除archive、research等目錄解析 frontmatter 中的summary與read_when字段為文檔感知型工具渲染按需的標題元數(shù)據(jù)。以 docs/index.md 為例summary: OpenClaw is a multi-channel gateway for AI agents that runs on any OS. read_when: - Introducing OpenClaw to newcomersread_when聲明的就是什么意圖的讀者應該被路由到這里它把 Overlay 的按讀者意圖組織規(guī)則從寫作約束落成了可被腳本解析的元數(shù)據(jù)。源碼佐證原則Source-Backed ContentOverlay 要求文檔內容必須以當前倉庫行為為證據(jù)共五條CLI 文檔必須與當前的 flags、輸出、錯誤、示例一致API/SDK 文檔必須包含字段、默認值、枚舉取值、約束、可空行為、生命周期狀態(tài)、錯誤與恢復指引配置文檔必須與導出的類型、schema/help 輸出、元數(shù)據(jù)、基線文件和當前文檔對齊依賴支撐的行為dependency-backed behavior必須先從上文檔、源碼或類型中核實才能寫下默認值、時序、錯誤或 API 行為嚴格區(qū)分四種狀態(tài)當前行為current、已發(fā)布行為shipped、計劃行為planned、維護者意圖maintainer intent。第 5 條尤其針對文檔領先于代碼的常見漂移把 roadmap 寫成能力、把 PR 討論寫成已發(fā)布行為都會讓文檔從可驗證的契約退化為愿望清單。在 OpenClaw 這樣的倉庫中這一條可以通過docs:check-links、生成腳本如 scripts/generate-base-config-schema.ts 這類 schema 生成入口以及plugins/reference生成物與源頁面的比對來落地。示例寫作規(guī)范ExamplesOverlay 對代碼示例與命令示例給出八條硬規(guī)范優(yōu)先給完整的、可直接復制粘貼的命令與片段使用現(xiàn)實的變量名和取值占位符一律用尖括號命名如API_KEY當預期輸出有助于驗證時展示成功輸出每個代碼塊只承載一個概念單元并使用語言特定的 fence避免隱藏 setup、auth、錯誤處理或清理的看起來能跑的示例絕不暴露真實密鑰、線上配置、電話號碼、私密視頻或憑證示例必須自包含與 principles.md 中Keep examples self-contained and minimize dependencies的通用約束一致。這八條實質上把示例當作可執(zhí)行的契約來對待復制即可運行、運行即可驗證、驗證即閉環(huán)。保留審查Preservation Reviews改寫與拆分時不丟事實針對改寫rewrite或拆分split文檔的場景Overlay 定義了五步保留審查流程改寫前先識別源單元source units標題、段落、表格、示例、CLI/API 契約、警告、排障事實把每個保留單元映射到目標頁面或章節(jié)寬泛的 covered 標記不構成稠密材料的證據(jù)——當源單元信息密度高時必須使用行級或論斷級line- or claim-level的證據(jù)對丟棄的內容必須定性是過時obsolete、他處重復duplicated elsewhere、不受支持unsupported還是移到了參考/支持頁當使用 docs-audit 產(chǎn)物時驗證它是帶非空mappings[]的映射審計數(shù)據(jù)而不僅僅是清單或重新索引的 JSON。這套流程與導航一節(jié)第 4 條的 keep/drop/move/destination 矩陣是同一枚硬幣的兩面矩陣管頁面級去向保留審查管內容級去向。它的工程價值在于把我改寫了這一頁從主觀陳述變成可審查的映射表——任何一條警告、一個字段表、一條排障事實都能被問到它現(xiàn)在在哪、為什么。驗證體系選擇最窄的證明Overlay 最后一節(jié)給出了驗證命令清單核心原則是Choose the narrowest proof that covers the touched surface選擇能覆蓋觸碰表面的最窄證明驗證命令適用表面?zhèn)}庫內實現(xiàn)pnpm docs:list文檔清單與 frontmatter 元數(shù)據(jù)scripts/docs-list.jspnpm docs:check-mdxMDX 語法與結構scripts/check-docs-mdx.mjs對docs目錄與根 README 運行pnpm docs:check-links文檔內鏈接有效性scripts/docs-link-audit.mjs另有--anchors變體校驗錨點pnpm docs:check-i18n-glossary國際化術語表一致性scripts/check-docs-i18n-glossary.mtspnpm format:docs:check或pnpm lint:docs格式化與 Markdown 風格scripts/format-docs.mts--check模式lint:docs使用 config/markdownlint-cli2.jsoncgit diff --check空白字符/沖突標記等低級問題git 自帶生成文檔或清單檢查生成的參考、插件目錄、labeler、文檔腳本被修改時對應生成腳本如 scripts/docs-link-audit.mjs 同族的生成/審計入口行為測試或命令探針behavior tests / command probes文檔聲稱了運行時行為時倉庫內的測試與命令探測上述腳本名與命令的映射可以在 package.json 的 scripts 段逐一核對docs:list、docs:check-mdx、docs:check-links、docs:check-links:anchors、docs:check-i18n-glossary、format:docs:check、lint:docs等。此外倉庫還提供 scripts/docs-map:genpnpm docs:map:gen生成帶標題的文檔地圖作為導航變更前的盤點手段。清單最后還有一條兜底規(guī)則如果驗證被阻斷必須明確說出哪條命令沒有跑、以及為什么If proof is blocked, say exactly which command was not run and why。這保證了未驗證本身也是一個可審計、可追蹤的狀態(tài)而不是被靜默跳過。把 Overlay 放回完整工作流結合技能入口 SKILL.md 的 Workflowoverlay 在整個文檔工作流中的位置是任務分類build/review × brownfield/evergreen盡早盤點文檔全貌治理文件 產(chǎn)品文檔讀 principles.md 獲取通用規(guī)則集若是 OpenClaw 文檔工作讀本文所述的 overlaybuild 走 build playbookreview 走 review.md 并主動發(fā)現(xiàn)問題輸出交付物 驗證說明 遺留缺口其中 OpenClaw 專屬檢查項頁面類型歸屬、docs/docs.json導航、生成參考頁可見性、保留映射全部來自 overlay?？梢酝茢噙@種通用原則 倉庫 overlay的分層設計是 OpenClaw 文檔體系能同時服務人類讀者、搜索引擎和 Agent 的關鍵通用原則保證跨倉庫可遷移的寫作質量overlay 則把導航歸屬、保留審查、最窄驗證這些只能在具體倉庫語境下成立的約束固化成了可執(zhí)行的檢查項。小結Overlay 是一份作用域明確的疊加規(guī)則只在 OpenClaw 文檔工作中生效先于 build/review playbook 被讀取先選頁面類型再寫內容八種頁面類型各自綁定結構模板、導航歸屬與驗證手段導航以 docs/docs.json 為單一事實源生成的參考頁與純重定向頁默認不進入可見導航頁面搬遷必須附帶去向矩陣內容以源碼為證CLI flags、API 字段、配置默認值都要能從倉庫中的類型、schema、help 輸出或測試中復驗改寫必須可追溯每個源單元都要有保留映射丟棄內容必須定性驗證取最窄證明pnpm docs:list/docs:check-mdx/docs:check-links/docs:check-i18n-glossary/format:docs:check/lint:docs按觸碰表面選擇被阻斷時明確聲明未跑的命令及原因。遵循這套 overlayOpenClaw 的文檔變更就從憑經(jīng)驗的寫作變成了帶分類、帶導航、帶保留映射、帶最窄驗證的工程化流程——這也是大型多通道網(wǎng)關項目能在數(shù)百頁文檔docs/下 20 主題目錄規(guī)模上保持準確性的方法論基礎?！久赓M下載鏈接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 項目地址: https://gitcode.com/GitHub_Trending/cl/openclaw創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考