openclaw-refactor-docs

OpenClaw 重構文件

概述

當使用者給定一個目標 OpenClaw 文件頁面，並要求重寫、重構、重組、拆分、縮短或改善它時，請使用此技能。

此技能建立在 technical-documentation 之上：使用該技能來處理風格、頁面類型、結構、範例、可發現性與驗證。此技能增加了重構工作流程，以避免在大幅文件重構期間遺失準確的行為。

輸入

必要：

• 目標文件頁面路徑，例如 docs/plugins/codex-harness.md。

選用：

• 期望的頁面類型，例如主題頁、指南、參考或疑難排解。
• 具體目標，例如縮短主頁面、將細節移至參考頁面，或與當前 CLI 行為保持一致。
• 相關的原始碼檔案、schema、命令、測試、規格或 PR。

如果目標頁面遺失或含糊不清，請在編輯前提出一個簡潔的問題。否則，繼續進行。

工作合約

重構目標頁面，使其在所陳述的範圍內更有用、更簡潔且更全面。

不要將重寫視為可以丟棄行為事實的許可。保留、驗證、移動或明確退役現有材料。不正確的文件比冗長的文件更糟糕。

偏好以下拆分方式：

• 主題頁或指南頁涵蓋 80/20 路徑、讀者必須做出的決定、安全設定、最小的可靠驗證、常見失敗以及連結到其他地方。
• 參考頁涵蓋詳盡的欄位、預設值、列舉值、限制、優先順序規則、API 合約、狹義的內部實作細節以及罕見的除錯細節。
• 疑難排解頁從可觀察到的症狀開始，並對應到檢查、原因和修正。

工作流程

1. 載入文檔標準

先讀取 ../technical-documentation/SKILL.md。在整個重構過程中，套用其頁面類型、風格、範例、導航和驗證指引。

當 pnpm docs:list 可用時執行它，然後只讀取目標頁面以及重構可能需要的入口點、參考頁面或相關頁面。

2. 分類頁面

在編輯之前，根據 technical-documentation 決定預期的頁面類型。

如果當前頁面混合了多種頁面類型，請選擇主要頁面類型，並規劃其他材料的位置：

• 將詳盡的合約移至現有或新的參考頁面。
• 將症狀驅動的材料移至現有或新的疑難排解頁面。
• 將狹義的設定工作流程移至指南，當它們中斷主要路徑時。
• 當讀者需要完成工作流程時，將簡潔的路由、決策和安全細節保留在主頁面。

3. 保留並稽核現有事實

在重寫之前，從舊頁面建立一個工作中的清單。包含：

• 設定欄位、標誌、命令、斜線命令、環境變數、預設值、列舉值、可空值和約束。
• 優先順序規則、降級行為、上限、限制、速率限制、逾時、生命週期狀態、佇列行為和相容性規則。
• 認證、權限、核准、沙箱、安全性、隱私和破壞性操作行為。
• 設定需求、支援的版本、依賴項、作業系統、憑證和帳戶需求。
• 錯誤訊息、疑難排解症狀、診斷和復原步驟。
• 範例、預期輸出、命令路由表和交叉連結。

針對每個事實，選擇一個結果：

• 保留在重構後的目標頁面中。
• 移至特定的現有頁面。
• 移至特定的新頁面。
• 刪除，因為當前原始碼證明它已過時或超出範圍。

不要從名稱或意圖推斷預設值、權限、政策、逾時行為或安全狀態。請驗證它們。

4. 尋找事實來源

對於每個行為敏感的主張，使用最近的權威來源：

• 公用 schema、外掛程式 manifest、產生的設定文件或匯出的型別，用於設定欄位。
• CLI 實作、斜線命令處理器、說明文字和命令測試，用於命令和標誌。
• 執行時期原始碼和測試，用於生命週期、佇列、權限、降級、逾時和提供者行為。
• 協定文件、SDK 外觀和合約測試，用於 API 和外掛程式表面。
• 僅將現有文件作為次要證據，除非目標純粹是概念性的。

如果頁面承諾提供參考，請將其表格與 schema、manifest、CLI 說明、產生的文件或匯出的型別進行比較。遺失的公用欄位、預設值、優先順序規則、上限或副作用都是正確性錯誤。

5. 規劃移置的材料

當將細節移出目標頁面時，請在編輯前記錄目的地：

• 現有頁面：命名頁面和章節。
• 新頁面：選擇頁面類型、slug、標題、frontmatter 摘要、doc-schema-version: 1 和 read_when 提示。
• 目標頁面：保留一個簡短的摘要，並在讀者需要更深入細節的地方加上連結。

避免重複的事實。如果同一個合約出現在多個地方，請選擇一個規範頁面並連結到它。

6. 重寫

按以下順序重寫：

1. 讓第一個畫面回答讀者可以做什么以及這個頁面為何存在。
2. 將推薦的路徑放在替代方案之前。
3. 僅在主要流程中保留決策制定和常見的操作細節。
4. 將詳盡的表格和罕見的細節移至計劃中的參考頁面。
5. 保留簡潔的路由表，當它們幫助讀者選擇命令、設定路徑、harness、外掛程式、提供者或參考時。
6. 從可觀察到的症狀添加疑難排解，而不是從內部的猜測。
7. 連結相關概念、指南、參考、診斷和相鄰的工具。

將 doc-schema-version: 1 添加到重構所遷移、建立或實質重寫的每個文件頁面的 YAML frontmatter 中。僅將其應用於文件頁面檔案，而不是 docs.json、詞彙表 JSON 或其他非頁面元資料。如果遷移的頁面是生成的，請更新生成器，使重新生成保留此標記，而不是手動編輯生成的輸出。

除非使用者明確要求草稿，否則不要留下像是 "TODO"、"TBD" 或 "see docs" 這類的佔位符。

7. 比較新舊頁面

編輯後，比較新頁面和舊頁面：

• 確認所有行為敏感的事實都被保留、移置或基於原始碼理由被有目的地刪除。
• 檢查主頁面是否仍然從頭到尾涵蓋 80/20 的場景。
• 檢查參考頁面在其所聲稱的範圍內是否仍然詳盡。
• 檢查從目標頁面到移置細節的連結是否有效。
• 檢查標題是否穩定、可搜尋且以行動為導向。

如果重構有目的地刪除了相關材料，請在最終報告中說明它去了哪裡或被刪除的原因。

8. 驗證

對受影響的表面執行最小可靠的文件檢查：

• pnpm docs:list
• git diff --check -- <touched-files>
• 針對性的 pnpm exec oxfmt --check --threads=1 <touched-files>
• pnpm docs:check-mdx
• pnpm docs:check-links
• 當連結文字、導覽、標籤或詞彙表表面發生變化時，執行 pnpm docs:check-i18n-glossary
• 當 schema、產生的設定文件、API 文件或產生的基準線被觸及時，執行產生的文件檢查

在可行的情況下，執行頁面中的命令和範例。如果您無法驗證某個行為敏感的主張，請移除該主張、在進行中的報告中標記不確定性，或請求缺少的來源。

最終報告

報告：

• 目標頁面中發生了什麼變化。
• 哪些細節被移置以及它們的目的地頁面。
• 哪些事實來源檢查支持了行為敏感的主張。
• 執行了哪些驗證，以及哪些驗證因不相關的原因失敗。

不要包含冗長的重寫日記。僅在存在剩餘風險時，才優先說明這些風險。