使用手冊
在 User-Manual/ 目錄下維護一個有證據支持的 Markdown 來源。發布三種版本：一般使用者版、管理員/操作員版以及技術參考版。Markdown 即是產品；渲染是一個獨立且可替換的步驟。
選擇最小的工作流程
- 新手冊：訪談使用者、檢查儲存庫、提出模組地圖、取得核可，然後使用經核准的 JSON 模組檔案執行
scripts/init_manual.py。 - 現有手冊：讀取
User-Manual/manual.yml，檢查要求的範圍及相關 Git 差異，然後只更新受影響的頁面與資產。 - 涵蓋範圍稽核：執行
scripts/audit_manual.py並解釋每一個錯誤與警告。 - 組建：僅在稽核通過後才執行
scripts/build_manual.py。該腳本會組合各版本，然後根據manual.yml中的renderer.kind進行渲染：markdown（預設）、command或mkdocs。 - 新鮮度檢查：在更新後執行
scripts/manual_state.py record --feature <dir>；status在輸入或手冊輸出自記錄以來發生變化時會回傳退出碼 1。
init_manual.py 將組建、稽核和狀態腳本（以及隨附的樣式表，位於 tools/theme/）複製到 User-Manual/tools/ 供 CI 使用。升級此技能後，請從其 scripts/ 目錄重新整理那些副本。--no-tools 可在 CI 從其他位置執行腳本時跳過複製動作。CI 工作流程遵循 --ci-policy <file> 中的 ci: 映射，否則在 .specify/workflow.yml 存在時遵循該檔案。
此技能不需要 .specify/、功能規格或任何 Spec Kit 命令。應根據使用者的請求、儲存庫證據以及版本控制變更來決定工作範圍。
僅路由所需的內容
| 任務 | 請閱讀 |
|---|---|
| 探索與訪談 | discovery.md |
| 頁面結構與 Markdown 語法 | content-model.md |
| 目標讀者與語言 | audience-language.md |
| 增量變更 | incremental-update.md |
| 實體、欄位、列舉、ER 圖 | data-reference.md |
| 渲染器、模板、品牌、HTML、PDF、RTL | publishing.md |
| API 文件 | api-docs.md |
| 發行說明與遷移指南 | release-docs.md |
| 使用者介面截圖 | ui-screenshots.md |
| 預覽與發布 | preview-publishing.md |
不可協商的規則
- 要求使用英文。阿拉伯文為專案選用，但頁面、渲染器、圖表及 PDF 從初始化起就必須支援從右到左（RTL）排版。
- 使用平實、自然的英文或阿拉伯文。針對宣告的目標讀者撰寫；切勿將技術說明原文照搬給一般使用者。
- 所有說法必須基於實作、合約、測試、觀察到的行為、架構或經核准的基礎設施來源。標明未知事項，且絕不憑空捏造行為。
- 絕不包含機密、憑證、令牌、私鑰、連接字串、生產紀錄或未經去識別化的個人資料。請使用確定性的合成範例。
- 將經核准且可擴展的模組地圖儲存在
User-Manual/manual.yml中。後續發現的項目在獲得核准前，應標記為proposed。 - 保持 Markdown 的正統性並使用 GitHub 自身的語法，使每個頁面在 GitHub 上都能正確顯示；組建步驟會將其轉譯給其他渲染器使用。僅能透過組建來產生其他格式。
- 僅產生有用的圖表，若
illustrate技能已安裝則使用之。將系統概覽與可讀的模組層級細節分開：一個系統 ER 概覽加上較小的模組 ER 圖。為每個有證據的實體、欄位、資料類型、關係、約束及列舉撰寫文件。 - 保留所擁有標記之外的手動撰寫內容，並使重新執行時能收斂。
- 僅連結到該目標讀者會收到的頁面。組建會拒絕跨目標讀者的頁面連結以及缺失的資產，並且只暫存某版本頁面所觸及的資產，因此一個對象絕不會收到另一個對象的截圖或範例。
實際範例
針對「為我們的預約平台建立使用手冊」，從路由、導航、API、測試及架構檔案中辨識出預約、客戶、付款與操作模組。請使用者核准該模組地圖。然後在 User-Manual/ 下建立針對目標讀者的教學、安全的截圖、API 與資料參考、英文內容及選用的阿拉伯文內容，並依照專案選擇的方式渲染：GitHub 上的 Markdown、透過 Pandoc 轉換成團隊的 Word 模板、或是一個包含 PDF 的 MkDocs 網站。