universal-dev-standards 5.17.0 → 6.1.0

package/bundled/locales/zh-TW/docs/user/FAQ.md

@@ -0,0 +1,132 @@
+---
+source: docs/user/FAQ.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# UDS 常見問題
+
+> **語言**: [English](../../../../docs/user/FAQ.md) | 繁體中文
+
+---
+
+## 安裝與設定
+
+**Q：`uds init` 和 `uds update` 有什麼差別？**
+
+`uds init` 用於首次設定：它會複製標準、設定你的 AI 工具，並安裝 skill。
+`uds update` 則是把已初始化的專案升級到最新的 UDS 版本，過程中不會重新設定。
+
+**Q：不用 Claude Code 也能使用 UDS 嗎？**
+
+可以。UDS 支援 Claude Code、Cursor、GitHub Copilot、Windsurf，以及任何會讀取指令檔的 AI 工具。執行 `uds init` 並選擇你的工具，它就會設定對應的檔案（`.cursorrules`、`CLAUDE.md` 等）。Skill 為 Claude Code 專屬；對於其他工具，標準與等同 CLAUDE.md 的檔案仍然適用。
+
+**Q：我已經有一份 `CLAUDE.md`，`uds init` 會覆寫它嗎？**
+
+不會。`uds init` 會把 UDS 內容合併進你既有的檔案，以清楚標記的區塊附加 UDS 段落。你原有的內容會被保留。
+
+---
+
+## Skill 與命令
+
+**Q：什麼是 Skill？**
+
+Skill 是預先建好的 AI 工作流程，當你在 Claude Code 輸入 `/command` 時就會啟動。例如 `/sdd` 會啟動 Spec-Driven Development（規格驅動開發）skill，引導你建立 spec 檔。Skill 儲存在 `skills/<name>/SKILL.md`，並由 Claude Code 自動載入。
+
+**Q：Skill 和 Standard 有什麼差別？**
+
+**Standard（標準）** 是書面準則（Markdown 或 YAML），說明某件事該怎麼做（例如 「commit-message」標準定義了 Conventional Commits 格式）。**Skill** 則是運用這些標準來執行某個流程的 AI 工作流程。標準是知識庫；Skill 是執行層。
+
+**Q：為什麼我在 Claude Code 選單裡看不到某個 skill？**
+
+可能有三個原因：
+1. **UDS 未初始化**：執行 `uds check` 確認
+2. **超出 skill 預算**：當 skill 很多時，Claude Code 會截斷清單。請參閱 [skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md) 調整哪些 skill 會顯示
+3. **Tier 3 skill**：Tier 3 skill 預設隱藏以節省 context。它們仍可透過 `/<name>` 呼叫。若要顯示，請在你的 `settings.json` 中覆寫——參閱 [skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md)
+
+**Q：選單裡看不到的 skill 還能用嗎？**
+
+可以。不論是否出現在選單中，每個 skill 都能直接輸入 `/<name>` 來呼叫。例如即使 `brainstorm-assistant` 是 Tier 3 而未列出，`/brainstorm` 仍然有效。
+
+**Q：我怎麼知道哪個命令會觸發哪個 skill？**
+
+完整的「命令對 skill」對照請見 [COMMANDS-INDEX.md](../../../../docs/user/COMMANDS-INDEX.md)，或以 skill 為中心的檢視 [SKILLS-INDEX.md](../../../../docs/user/SKILLS-INDEX.md)。
+
+**Q：我怎麼停用一個從不使用的 skill？**
+
+在你的 `.claude/settings.json` 中：
+```json
+{
+  "skillOverrides": {
+    "brainstorm-assistant": "disabled"
+  }
+}
+```
+所有覆寫選項請見 [skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md)。
+
+---
+
+## 規格驅動開發
+
+**Q：每次變更都得寫 spec 嗎？**
+
+不用。建議在功能、user story 與較具規模的變更時撰寫 spec。對於小型 bug 修正或重構，`/commit` 與 `/code-review` 就足夠了。經驗法則：若實作會花超過 2 小時，寫 spec 會有幫助。
+
+**Q：spec 存放在哪裡？**
+
+預設位於專案根目錄的 `specs/SPEC-NNN-<slug>.md`。格式遵循 UDS spec-driven-development 標準。
+
+**Q：什麼是 AC（Acceptance Criterion，驗收條件）？**
+
+驗收條件是一條可測試的陳述，用來定義一個功能何時算「完成」。例如：「Given 一位已註冊使用者，When 他以正確憑證登入，Then 他會取得有效的 session token。」AC 驅動測試覆蓋並防止範圍蔓延。
+
+---
+
+## 更新與版本
+
+**Q：我要如何把 UDS 更新到最新版？**
+
+```bash
+uds update
+```
+
+這會下載最新的標準與 skill，同時保留你專案專屬的客製化。
+
+**Q：我要如何查看目前的 UDS 版本？**
+
+```bash
+uds --version
+# 或
+cat .standards/manifest.json | grep version
+```
+
+**Q：更新 UDS 會破壞我現有的 spec 或 CLAUDE.md 嗎？**
+
+不會。標準更新保持向後相容。Spec 是你的檔案，`uds update` 絕不會動它們。CLAUDE.md 只有在你明確執行 `uds init --force` 時才會被修改。
+
+---
+
+## 架構
+
+**Q：什麼是「雙層架構（Dual-Layer Architecture）」？**
+
+UDS 有兩層：
+- **Core Standards（核心標準，`.standards/` — Markdown 檔）**：人類可讀的準則、完整理論、邊界案例
+- **AI Standards（AI 標準，`.standards/` — `.ai.yaml` 檔）**：同一份標準的 token 精簡、為 AI 最佳化的版本，專為 Claude Code 的 context window 設計
+
+當 Skill 執行時，它會讀取 `.ai.yaml` 檔。當開發者想了解背後理由時，則閱讀 `.md` 檔。
+
+**Q：`skills/` 和 `.standards/` 有什麼差別？**
+
+`skills/` 包含驅動 Claude Code 中 `/command` 的 SKILL.md 檔，它們是工作流程。
+`.standards/` 包含底層知識庫（Core Standards + AI Standards）。Skill 引用標準；標準不引用 skill。
+
+**Q：什麼是 Skill Tier？（DEC-061）**
+
+Tier 控制 Claude Code 的 context 預算有多少用於 skill 描述：
+- **Tier 1**：永遠以完整描述列出（15 個 skill — 每日使用）
+- **Tier 2**：預設以完整描述列出（28 個 skill — 每週使用）
+- **Tier 3**：預設僅列出名稱（12 個 skill — 專家／事件驅動）
+
+所有 tier 都能透過 `/<name>` 完整呼叫。Tier 只影響 _列出_ 的行為。

package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md

@@ -0,0 +1,144 @@
+---
+source: docs/user/GETTING-STARTED.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# UDS 入門指南
+
+> **語言**: [English](../../../../docs/user/GETTING-STARTED.md) | 繁體中文
+
+本指南帶你走過 UDS 從零開始，直到完成第一份 AI 輔助的 spec 與 commit。
+預估時間：**5 分鐘**。
+
+---
+
+## 先決條件
+
+- Node.js ≥ 20.0.0（`node --version`）
+- 一個 AI 程式設計助理：Claude Code（建議）、Cursor、GitHub Copilot 或類似工具
+
+---
+
+## 步驟 1 — 安裝
+
+```bash
+npm install -g universal-dev-standards
+uds --version
+```
+
+> **不想全域安裝？** 使用 `npx universal-dev-standards init` 即可不安裝直接執行。
+
+---
+
+## 步驟 2 — 初始化你的專案
+
+在你的專案目錄內執行 `uds init`：
+
+```bash
+cd your-project
+uds init
+```
+
+互動式精靈將會：
+1. 偵測你的 AI 工具（Claude Code、Cursor 等）
+2. 複製標準到 `.standards/`
+3. 設定你 AI 工具的指令檔（例如 `CLAUDE.md`）
+4. 安裝你所選擇的 skill
+
+初始化後，你應該會看到：
+```
+.standards/          ← AI 可讀的標準
+CLAUDE.md            ← 已更新 UDS 指引（Claude Code）
+```
+
+> **已經有 CLAUDE.md？** `uds init` 會採合併方式——不會覆寫你既有的內容。
+
+---
+
+## 步驟 3 — 你的第一份 Spec（`/sdd`）
+
+在寫程式碼之前，先建立一份 spec：
+
+1. 在你的專案中開啟 Claude Code
+2. 輸入：`/sdd` 並按 Enter
+3. 描述你想要建構的東西（例如「新增使用者以 email + 密碼登入」）
+4. Claude 會在 `specs/SPEC-NNN-*.md` 建立一份 spec 檔
+
+這份 spec 會記錄：
+- **Background（背景）** — 為什麼需要這個功能
+- **Acceptance Criteria（驗收條件，AC）** — 可測試的結果
+- **Out of Scope（範圍外）** — 明確的邊界
+
+> **為什麼要先寫 spec？** AC 驅動的開發能減少範圍蔓延，並讓 review 更快。
+> `/sdd` 遵循 UDS Spec-Driven Development（規格驅動開發）標準。
+
+---
+
+## 步驟 4 — 撰寫程式碼（搭配 TDD 或 BDD）
+
+有了 spec 之後，選擇你的工作流程：
+
+| 工作流程 | 命令 | 適用時機 |
+|----------|------|----------|
+| 測試驅動開發 | `/tdd` | 撰寫單元／整合測試 |
+| 行為驅動開發 | `/bdd` | 撰寫功能場景 |
+| 直接實作 | — | 簡單、已充分理解的任務 |
+
+TDD 範例：
+```
+/tdd specs/SPEC-001-user-login.md
+```
+Claude 會引導你走過 RED → GREEN → REFACTOR 循環。
+
+---
+
+## 步驟 5 — Commit（`/commit`）
+
+準備好要 commit 時：
+
+```
+/commit
+```
+
+Claude Code 將會：
+1. 審查你已 stage 的變更
+2. 產生一則符合 [Conventional Commits](https://www.conventionalcommits.org/) 格式的訊息
+3. 在 commit 前把訊息顯示給你確認
+
+> **安全推送？** 在 `git push` 前使用 `/push` 取得額外的品質閘門。
+
+---
+
+## 常用命令速覽
+
+| 任務 | 命令 |
+|------|------|
+| 瀏覽所有 skill | `/dev-workflow` |
+| 建立 spec | `/sdd` |
+| TDD 工作流程 | `/tdd` |
+| BDD 工作流程 | `/bdd` |
+| 產生 commit | `/commit` |
+| 安全推送 | `/push` |
+| 架構決策 | `/adr` |
+| 程式碼審查 | `/code-review` |
+
+完整清單請見 [SKILLS-INDEX.md → 觸發時機速查](../../../../docs/user/SKILLS-INDEX.md#觸發時機速查-when-to-use)。
+
+---
+
+## 疑難排解
+
+- **找不到 skill**：輸入 `uds check` 驗證安裝狀態
+- **CLAUDE.md 未更新**：重新執行 `uds init --force`
+- **Claude Code 選單中未顯示 skill**：見 [TROUBLESHOOTING.md](../../../../docs/user/TROUBLESHOOTING.md)
+
+---
+
+## 後續步驟
+
+- **探索所有 skill**：[SKILLS-INDEX.md](../../../../docs/user/SKILLS-INDEX.md)
+- **自訂 skill 顯示**：[skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md)
+- **每日工作流程模式**：[DAILY-WORKFLOW-GUIDE.md](../../adoption/DAILY-WORKFLOW-GUIDE.md)
+- **理解架構**：[GLOSSARY.md](../../../../docs/user/GLOSSARY.md)

package/bundled/locales/zh-TW/docs/user/GLOSSARY.md

@@ -0,0 +1,178 @@
+---
+source: docs/user/GLOSSARY.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# UDS 術語表
+
+> **語言**: [English](../../../../docs/user/GLOSSARY.md) | 繁體中文
+
+UDS 專屬，或在 UDS 脈絡下有特定用法的術語。
+
+---
+
+## A
+
+**AC（Acceptance Criterion，驗收條件）**
+一條可測試的陳述，定義一個功能何時算完成。以 Given-When-Then 或一般英文撰寫。AC 記錄在 Spec 檔中，並在測試裡被引用。
+_參見：`/atdd`、`/sdd`、`acceptance-test-driven-development` 標準_
+
+**Activity（活動）**
+在 DEC-051 四層分類模型中，Activity 是一個具名的工作流程步驟（例如「撰寫失敗的測試」、「執行回歸測試」）。Activity 定義於 UDS 標準中，並由 Skill 執行。
+
+**ADR（Architecture Decision Record，架構決策記錄）**
+記錄一項重大技術決策的文件：脈絡、考量過的選項、所選方案，以及後果。
+_參見：`/adr`、`adr-standards` 標準_
+
+**ATDD（Acceptance Test-Driven Development，驗收測試驅動開發）**
+一種實務做法：在開始實作前先定義驗收條件，並撰寫測試來驗證這些 AC。橋接 BDD 與 TDD。
+_參見：`/atdd`_
+
+---
+
+## B
+
+**BDD（Behavior-Driven Development，行為驅動開發）**
+一種使用自然語言 Given-When-Then 場景來描述系統行為的開發實務。場景同時作為文件與測試規格。
+_參見：`/bdd`、`behavior-driven-development` 標準_
+
+**Bundle（Bundle 層）**
+包含在 `npm install` 套件中的 UDS 標準子集（供採用者使用）。與 Source 層不同——後者包含所有標準，含治理與維護工具。
+_參見：DEC-045_
+
+---
+
+## C
+
+**Core Standard（核心標準）**
+位於 `core/`（以及 `.standards/*.md`）的 Markdown 檔，包含某個 UDS 標準完整、人類可讀的版本。涵蓋背後理由、邊界案例、範例與參考資料。
+_對比：AI Standard_
+
+**AI Standard（AI 標準）**
+位於 `.standards/`（以及 `ai/standards/`）的 `.ai.yaml` 檔，是 Core Standard 的 token 精簡、為 AI 最佳化的編碼。Skill 在執行時讀取它。
+
+---
+
+## D
+
+**DEC（Decision，決策）**
+記錄於 `dev-platform/cross-project/decisions/DEC-NNN-*.md` 的跨專案架構或產品決策。DEC 依序編號，追蹤重大選擇背後的「為什麼」。
+
+**Dual-Layer Architecture（雙層架構）**
+UDS 的兩層設計：Core Standards（完整知識、人類可讀）+ AI Standards（token 精簡、機器可讀）。Skill 使用 AI Standards；開發者閱讀 Core Standards。
+
+---
+
+## S
+
+**SDD（Spec-Driven Development，規格驅動開發）**
+一種 UDS 實務做法：在寫程式碼前先建立規格文件。Spec 定義背景、範圍、驗收條件與範圍外項目。
+_參見：`/sdd`、`spec-driven-development` 標準_
+
+**Skill**
+封裝為 SKILL.md 檔的預建 AI 工作流程。在 Claude Code 輸入 `/<name>` 即可啟動。Skill 運用 AI Standards 來實作 UDS 的活動。
+_參見：[SKILLS-INDEX.md](../../../../docs/user/SKILLS-INDEX.md)_
+
+**Skill Budget（Skill 預算）**
+Claude Code 的 context window 中保留用於列出可用 skill 的比例。當有 55+ 個 skill 時，描述可能被截斷。UDS 以 Tier 來管理這項預算。
+_參見：DEC-061、[skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md)_
+
+**Skill Tier（Skill 分級，DEC-061）**
+依使用頻率對 skill 進行分類，藉以控制列出行為：
+- **Tier 1（Core）**：15 個 skill，每日使用，永遠以描述列出
+- **Tier 2（Advanced）**：28 個 skill，每週使用，預設以描述列出
+- **Tier 3（Specialist）**：12 個 skill，事件驅動，預設僅列出名稱（仍可透過 `/<name>` 呼叫）
+
+**Standard（標準）**
+涵蓋某項特定實務（例如 commit 訊息、API 設計、測試）的 UDS 準則文件。標準與技術、語言無關。每個標準同時存在為 Core Standard（`.md`）與 AI Standard（`.ai.yaml`）。
+
+**Source（Source 層）**
+完整的 UDS 儲存庫，包含所有標準、治理工具與維護腳本。是 Bundle 層的超集合。
+_參見：DEC-045_
+
+---
+
+## T
+
+**TDD（Test-Driven Development，測試驅動開發）**
+一種在實作程式碼前先撰寫測試的開發實務。RED-GREEN-REFACTOR 循環：寫一個失敗的測試 → 讓它通過 → 重構。
+_參見：`/tdd`、`test-driven-development` 標準_
+
+---
+
+## U
+
+**UDS（Universal Development Standards，通用開發標準）**
+本專案。一套與語言無關、與框架無關的軟體開發品質彙集，含 149 個核心標準、55 個 AI skill 與 51 個斜線命令。
+
+**UDS Manifest（`uds-manifest.json`）**
+所有 UDS 標準與 skill 的機器可讀索引。包含統計數據、skill 對命令的對照，以及分類歸屬。供 UDS CLI 與文件產生器使用。
+
+---
+
+## X
+
+**XSPEC（Cross-Project Spec，跨專案規格）**
+位於 `dev-platform/cross-project/specs/XSPEC-NNN-*.md` 的規格文件。用於影響多個子專案（UDS、VibeOps、telemetry）的功能，或新的 UDS 功能。
+_依集中化政策（2026-04-22），所有新 spec 一律建立為 XSPEC。_
+
+---
+
+## 術語正規化（Canonical Forms，標準形式）
+
+> 跨標準反覆出現的術語與符號之單一真實來源（XSPEC-292 T6）。這些表格把**既有、刻意為之**的慣例明文化，讓新標準對齊而非漂移。它們**不會**重新命名任何東西——多數看似「雙重術語」的情況其實是依層級設計、各得其所（例如 JSON body 中的 `createdAt` 對比資料庫欄位的 `created_at` 是正確的，並非衝突）。
+
+### 依層級的欄位命名
+
+同一個概念依其所在層級的慣例書寫。跨越層級邊界是一種轉換，而非不一致。
+
+| 層級 | 慣例 | 範例 |
+|------|------|------|
+| 結構化日誌（JSON） | `snake_case` | `trace_id`、`request_id`、`http_method`、`db_table` |
+| API JSON body | `camelCase` | `createdAt`、`firstName`、`httpStatus` |
+| API 查詢參數 | `snake_case` | `?sort_by=created_at` |
+| URL 路徑片段 | `kebab-case` | `/user-profiles` |
+| HTTP header 名稱 | `lowercase-hyphen` | `x-request-id`、`traceparent` |
+| 資料庫資料表／欄位 | `snake_case`（單數資料表）| `user_account`、`created_at` |
+| 程式碼識別子 | 語言原生 | `camelCase`（JS/TS）、`snake_case`（Python/Go）|
+
+_標準：`logging-standards`、`api-design-standards`、`database-standards`。_
+
+### 測試層級縮寫
+
+大寫＝該術語；小寫＝環境識別子。`IT` 永遠指 Integration Testing（整合測試），絕非 Information Technology。
+
+| 縮寫 | 全稱 | 典型環境 |
+|------|------|----------|
+| `UT` | Unit Testing（單元測試）| `local` |
+| `IT` | Integration Testing（整合測試）| `local` / `ci` |
+| `ST` | System Testing（系統測試）| `ci` / `sit` |
+| `E2E` | End-to-End Testing（端到端測試）| `staging` |
+| `AT` | Acceptance Testing（驗收測試）| — |
+| `UAT` | User Acceptance Testing（使用者驗收測試）| — |
+| `SIT` | System Integration Testing（系統整合測試，該術語）；`sit` 是 SIT **環境** id | `ci` |
+
+_標準：`testing`（testing-standards）、`test-governance`。_
+
+### 狀態：文字 vs 符號
+
+**文字**是標準／機器可讀的值；**符號**是可選的視覺呈現。兩者成對，並非互相競爭。
+
+| 標準文字 | 符號 | 領域 |
+|----------|------|------|
+| `covered` | ✅ | AC／測試覆蓋 |
+| `partial` | ⚠️ | AC／測試覆蓋 |
+| `uncovered` | ❌ | AC／測試覆蓋（測試缺口）|
+| `not_implemented` | 🚫 | AC（程式碼缺口，非測試缺口）|
+
+_領域專屬的生命週期各自維持獨立的狀態機——ADR（`Proposed → Accepted → Deprecated → Superseded`）、文件生命週期（`draft → active → archived`），以及上方的 AC 覆蓋彼此不同，**不會**被合併。標準：`acceptance-criteria-traceability`、`adr-standards`、`documentation-structure`。_
+
+---
+
+## 另見
+
+- [FAQ.md](FAQ.md) — 常見問題
+- [SKILLS-INDEX.md](../../../../docs/user/SKILLS-INDEX.md) — 所有 skill 與描述
+- [GETTING-STARTED.md](GETTING-STARTED.md) — 首次設定

package/bundled/locales/zh-TW/docs/user/README.md

@@ -0,0 +1,70 @@
+---
+source: docs/user/README.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# UDS 使用者文件
+
+> **語言**: [English](../../../../docs/user/README.md) | 繁體中文
+
+歡迎來到 UDS（Universal Development Standards，通用開發標準）使用者文件中心。
+
+---
+
+## 新手入門
+
+剛安裝完 UDS？從這裡開始：
+
+1. **[GETTING-STARTED.md](../../../../docs/user/GETTING-STARTED.md)** — 5 分鐘導覽：安裝 → 初始化 → 第一份 spec → 第一次 commit（繁中翻譯進行中）
+2. **[GLOSSARY.md](../../../../docs/user/GLOSSARY.md)** — 什麼是 Skill？Standard？Tier？所有 UDS 術語的定義（繁中翻譯進行中）
+3. **[SKILLS-INDEX.md](../../../../docs/user/SKILLS-INDEX.md)** — 依 Tier 與分類瀏覽全部 55 個 skill（自動產生，僅英文）
+
+---
+
+## 日常使用
+
+| 我想要… | 前往 |
+|---------|------|
+| 找到正確的命令 | [SKILLS-INDEX.md → 觸發時機速查](../../../../docs/user/SKILLS-INDEX.md#觸發時機速查-when-to-use) |
+| 查看所有斜線命令 | [COMMANDS-INDEX.md](../../../../docs/user/COMMANDS-INDEX.md) |
+| 自訂列出哪些 skill | [skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md) |
+| 快速參考卡 | [CHEATSHEET.md](../CHEATSHEET.md) |
+| 解答常見問題 | [FAQ.md](../../../../docs/user/FAQ.md) |
+| 修正問題 | [TROUBLESHOOTING.md](../../../../docs/user/TROUBLESHOOTING.md) |
+
+---
+
+## 維護者 / 貢獻者
+
+| 主題 | 資源 |
+|------|------|
+| UDS 的結構 | [../../CONTRIBUTING.md](../../../../CONTRIBUTING.md) |
+| CLI 參考 | [cli/README.md](../../../../cli/README.md) |
+| 採用指南 | [ADOPTION-GUIDE.md](../../../../adoption/ADOPTION-GUIDE.md) |
+| 發布前資訊 | [PRE-RELEASE.md](../../../../docs/PRE-RELEASE.md) |
+| 更新自動產生的文件 | 執行 `npm run docs:generate-index` |
+
+---
+
+## 文件地圖
+
+```
+docs/
+├── user/                        ← 你在這裡（面向使用者的文件）
+│   ├── README.md                ← 本檔 — 文件中心
+│   ├── GETTING-STARTED.md       ← 首次設定指南
+│   ├── SKILLS-INDEX.md          ← 55 個 skill 依 Tier 與分類（自動產生）
+│   ├── COMMANDS-INDEX.md        ← 所有斜線命令（自動產生）
+│   ├── CHEATSHEET.md            ← 快速參考卡
+│   ├── FAQ.md                   ← 常見問題
+│   ├── GLOSSARY.md              ← 術語表
+│   └── TROUBLESHOOTING.md       ← 問題 → 解法
+├── reference/                   ← 完整參考（自動產生）
+│   └── FEATURE-REFERENCE.md
+└── internal/                    ← 維護者文件（非給終端使用者）
+```
+
+> **注意**：標記「自動產生」的檔案由 `npm run docs:generate-index` 重建。
+> 請勿手動編輯——下次執行時變更會被覆寫。