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