白皮書稽核指令

source-command-audit-whitepapers

當使用者要求執行已遷移的原始碼指令 audit-whitepapers 時，使用此技能。

指令範本

稽核白皮書與摘要卡片

針對所有白皮書（法文 + 英文）和摘要卡片（法文 + 英文）進行全面的新鮮度與品質稽核。根據目前的指南版本為每個文件評分，檢查法文/英文對等性，並驗證元資料的一致性。

引數

• --fix - 產生更新建議與前端資料修補程式（不會修改檔案）
• --verbose - 顯示所有準則，包含通過的項目，而不僅是失敗的項目
• --cards-only - 僅稽核摘要卡片（跳過主要白皮書）
• --wp-only - 僅稽核主要白皮書（跳過摘要卡片）

使用方式

/audit-whitepapers                  # 完整稽核，僅顯示失敗項目
/audit-whitepapers --fix            # 稽核 + 優先順序更新建議
/audit-whitepapers --verbose        # 所有準則的完整詳細資料
/audit-whitepapers --cards-only     # 僅摘要卡片
/audit-whitepapers --wp-only        # 僅白皮書

---

階段 1：探索

目標：定位並盤點所有可稽核的文件。

步驟

1. 讀取目前指南版本：讀取專案根目錄的 VERSION 檔案。這是所有文件應同步的目標版本。

2. 掃描目錄以尋找 .qmd 檔案：

   whitepapers/fr/         （主要白皮書，法文）
   whitepapers/en/         （主要白皮書，英文）
   whitepapers/recap-cards/fr/    （摘要卡片，法文）
   whitepapers/recap-cards/en/    （摘要卡片，英文）
   

3. 分類每個檔案：

   • 主要白皮書：在 whitepapers/fr/ 或 whitepapers/en/ 中符合 [0-9][0-9]-*.qmd 的檔案
   • 備忘單：符合 *cheatsheet*.qmd 的檔案（分開追蹤，不計分）
   • 自訂白皮書：來自外部合作夥伴（strangebee、purchasely、devwithai）且符合 *-whitepaper.qmd 或 *-cheatsheet.qmd 的檔案——不納入計分，分開列出
   • 摘要卡片：recap-cards/fr/ 或 recap-cards/en/ 中的所有 .qmd 檔案
   • 套裝／包含：fiches-recap-serie.qmd、fiches/ 子目錄中的檔案——排除（它們是組合文件）

4. 解析 YAML 前端資料：針對每個包含的檔案（讀取第一個 --- 和第二個 --- 之間的內容）。提取：

   • title、subtitle、author、date
   • version（主要白皮書和摘要卡片中追蹤的指南版本）
   • wp-version（白皮書自己的 semver，僅限主要白皮書）
   • guide-version（摘要卡片中使用的明確指南版本欄位）
   • card-number、category、difficulty（僅限摘要卡片）
   • series（僅限主要白皮書）

5. 顯示探索摘要：

   指南版本：{VERSION}
   找到：{N} 份主要白皮書（{FR}/{EN} 法/英）、{N} 份摘要卡片（{FR}/{EN} 法/英）
   排除：{N} 個自訂檔案（strangebee、purchasely、devwithai）、{N} 個套裝檔案
   

---

階段 2：版本差距分析（每個檔案 40 分）

目標：評估每個文件與目前指南相比的時效性。

Semver 比較邏輯

將版本字串解析為 MAJOR.MINOR.PATCH。陳舊度量標準為 minor_gap = current_minor - file_minor（使用相同的 MAJOR）。如果 MAJOR 不同，則視為嚴重。

對於主要白皮書，指南版本欄位為 version。 對於摘要卡片，指南版本欄位為 guide-version（若無則回退至 version）。

計分表

準則	分數	偵測方式
指南版本最新（落後 0-1 個次要版本）	15	minor_gap <= 1
指南版本近期（落後 2-3 個次要版本）	10	minor_gap 2-3（部分分數，取代 15 分）
指南版本陳舊（落後 4-10 個次要版本）	5	minor_gap 4-10（部分分數）
wp-version 欄位存在且為有效 semver	5	欄位存在且符合 \d+\.\d+\.\d+（僅限白皮書）
wp-version 與法文/英文配對一致	10	對應檔案中有相同的 wp-version 值（僅限白皮書）
guide-version 與法文/英文配對一致	10	對應檔案中有相同的 guide-version（或 version）值（卡片）

新鮮度標籤：

• 落後 0-1 個次要版本：新鮮
• 落後 2-3 個次要版本：陳舊
• 落後 4-10 個次要版本：非常陳舊
• 落後 11 個以上次要版本：嚴重

注意：指南版本的 15、10、5 分互斥（僅授予最高適用的層級）。

---

階段 3：內容陳舊度檢查（每個檔案 20 分）

目標：偵測白皮書涵蓋的指南章節自上次更新以來是否已變更。

白皮書與指南對應關係（內嵌）

WP#	法文檔案名稱前綴	英文檔案名稱前綴	指南章節
00	00-introduction	00-series-introduction	guide/ultimate-guide.md 第 1-2 章
01	01-prompts	01-effective-prompts	第 2 章提示相關章節
02	02-personnalisation	02-customization	第 3 章記憶體、第 4 章代理、第 5 章技能
03	03-securite	03-security	第 7 章鉤子、安全相關章節
04	04-architecture	04-architecture	第 2 章內部、架構相關章節
05	05-equipe	05-team	第 3 章團隊設定、第 9 章 CI/CD
06	06-privacy	06-privacy	第 2 章資料/隱私相關章節
07	07-guide-reference	07-reference-guide	第 10 章參考資料
08	08-agent-teams	08-agent-teams	第 9 章代理團隊
09	09-apprendre	09-learning	guide/roles/learning-with-ai.md
10	10-budget	10-ai-budget	商業/ROI 內容

步驟

1. 針對每份主要白皮書，提取 date 欄位。如果日期不是 YYYY-MM-DD 格式，請解析它（例如 "2026-02-12" 或 "March 2026"）。
2. 執行 git log --since="{date}" --oneline -- guide/ultimate-guide.md guide/roles/ guide/core/ 以計算自白皮書日期以來觸及指南內容的提交次數。
3. 計分：

準則	分數	偵測方式
自白皮書日期後無指南提交	10	git log 回傳 0 筆提交
自白皮書日期後有少量提交（1-5）	7	1-5 筆提交（部分）
中等提交（6-15）	4	6-15 筆提交（部分）
大量提交（>15）	0	超過 15 筆提交
此白皮書已定義對應關係	5	白皮書編號在上方對應關係表中
Git 歷史可存取	5	git log 指令執行無錯誤

摘要卡片：跳過詳細的 Git 分析。根據 minor_gap 授予固定陳舊度分數：

• 落後 0-1：20 分
• 落後 2-3：15 分
• 落後 4-10：8 分
• 落後 11 以上：0 分

---

階段 4：法文/英文對等性檢查（每個檔案 20 分）

目標：每個文件都應有另一個語言的完整、版本一致的對應檔案。

配對策略

主要白皮書：根據兩位數的數字前綴（例如 00、03、10）進行配對。法文和英文的檔案名稱不同，但前綴一致。

摘要卡片：根據相同的檔案名稱進行配對（兩個語言目錄使用相同的檔案名稱）。

計分表

準則	分數	偵測方式
另一個語言中存在對應檔案	10	找到前綴相符的檔案（白皮書）或名稱完全相同的檔案（卡片）
配對間 wp-version 相符	5	相同的 wp-version 值（僅限白皮書）
配對間指南版本相符	5	相同的 version/guide-version 值

配對中的法文和英文檔案在對等性上獲得相同的分數（如果配對完整，兩者皆得 20 分；如果缺少一個，則現有檔案在對等性上得 0 分）。

---

階段 5：元資料品質（每個檔案 20 分）

目標：驗證前端資料的完整性、欄位格式以及同類型檔案間的一致性。

主要白皮書（最高 20 分）

準則	分數	偵測方式
必填欄位存在	6	包含所有：title、subtitle、author、date、version、wp-version、series
version 符合 semver 模式	3	符合 \d+\.\d+\.\d+
wp-version 符合 semver 模式	3	符合 \d+\.\d+\.\d+
date 可解析且非未來日期	3	有效日期，不晚於今天
series 值一致	2	等於 "Codex Ultimate Guide"
無缺失 wp-version（未留空或不存在）	3	欄位具有非空值

摘要卡片（最高 20 分）

準則	分數	偵測方式
必填欄位存在	5	包含所有：title、subtitle、card-number、category、difficulty、guide-version、author、version、date
card-number 與檔案名稱前綴相符	4	例如，card-number 中的 C01 與檔案名稱中的 c01- 相符
category 對語言有效	4	法文："Technique"、"Methodologie"、"Conception" 之一；英文："Technical"、"Methodology"、"Design" 之一（將 "Conceptual" 標記為英文中不一致）
difficulty 為有效值	3	其中之一："beginner"、"intermediate"、"advanced"
guide-version 和 version 欄位彼此相符	4	兩個欄位皆存在且在同一檔案中具有相同的值

要自動偵測的已知問題：英文 C 系列卡片使用兩個不同的 category 值（c01-c05 使用 "Conceptual"，c06 以上使用 "Design"）。在報告的「元資料問題」章節中明確標記此不一致性。

---

階段 6：計分與評級

計分公式（每個檔案）

總分 = 版本差距（40）+ 內容陳舊度（20）+ 法文/英文對等性（20）+ 元資料品質（20）
分數 = （總分 / 100）* 100  [以百分比表示]

評級量表

等級	分數	狀態
A	90-100	新鮮，完全同步
B	80-89	良好（生產閾值）
C	70-79	需要盡快更新
D	60-69	陳舊，應優先處理
F	<60	嚴重：內容可能已過時

整體健康分數

加權健康 = （白皮書分數總和 * 2 + 卡片分數總和 * 1） / （白皮書數量 * 2 + 卡片數量 * 1）

白皮書加權 2 倍，因為每份長度為 20-80 頁，而摘要卡片為 2 頁。陳舊的白皮書風險更高。

---

階段 7：報告

輸出以下 Markdown 報告。使用 <details> 區塊來顯示個別檔案的細部分析，以保持頂層的可掃描性。

# 白皮書與摘要卡片稽核

**日期**：{today}
**指南版本**：{VERSION}
**整體健康**：{score}%（{grade}）
**稽核檔案數**：{total}（{wp_count} 份白皮書，{card_count} 份摘要卡片）

---

## 版本狀態儀表板

| 狀態 | 白皮書 | 摘要卡片 | 總計 |
|--------|-------------|-------------|-------|
| 新鮮（落後 0-1 個次要版本）   | N | N | N |
| 陳舊（落後 2-3 個次要版本）   | N | N | N |
| 非常陳舊（落後 4-10 個版本）   | N | N | N |
| 嚴重（落後 11 個以上版本）      | N | N | N |

**目前使用的版本**：
- 主要白皮書 00-09：{version}（落後 {gap} 個次要版本）
- 主要白皮書 10：{version}（落後 {gap} 個次要版本）
- 摘要卡片：{guide-version}（落後 {gap} 個次要版本）

---

## 白皮書分數

| WP# | 標題 | version | 差距 | wp-version | 對等性 | 分數 | 等級 |
|-----|-------|---------|-----|------------|--------|-------|-------|
| 00  | ...   | ...     | -N  | ...        | OK/差距 | N%    | X     |
...

<details>
<summary>個別準則細部分析（WP 00）</summary>

| 階段 | 準則 | 結果 | 分數 |
|-------|-----------|--------|--------|
| 版本差距 | 指南版本最新 | 嚴重（-11） | 0/15 |
| 版本差距 | wp-version 有效 semver | OK | 5/5 |
| ... | ... | ... | ... |
| **總分** | | | **N/100** |
</details>

---

## 摘要卡片分數

| 系列 | 卡片數 | 平均 guide-version | 平均差距 | 平均分數 | 等級 |
|--------|-------|-------------------|---------|-----------|-------|
| T（技術）    | 22 | ... | -N | N% | X |
| M（方法論）  | 22 | ... | -N | N% | X |
| C（概念）   | 13 | ... | -N | N% | X |

<details>
<summary>個別卡片分數</summary>

| 卡片 | 類別 | guide-version | 差距 | 對等性 | 元資料 | 分數 | 等級 |
|------|----------|---------------|-----|--------|----------|-------|-------|
...
</details>

---

## 法文/英文對等性報告

### 白皮書
| WP# | 法文 | 英文 | wp-version 相符 | version 相符 |
|-----|----|----|------------------|---------------|
...

### 摘要卡片
- **法文數量**：{N} | **英文數量**：{N}
- **缺少法文**：[清單或「無」]
- **缺少英文**：[清單或「無」]
- **版本不符**：[清單或「無」]

---

## 元資料問題

### 已知：英文摘要卡片類別不一致
英文 C 系列卡片對「概念/設計」類別使用了兩個不同的值：
- "Conceptual"：c01、c02、c03、c04、c05
- "Design"：c06、c07、c08、...
建議：標準化為 "Design" 以符合指南術語。
受影響的檔案：whitepapers/recap-cards/en/c01-*.qmd 至 c05-*.qmd（將 "Conceptual" 改為 "Design"）

### 其他問題
[列出任何缺失的欄位、錯誤格式、日期問題...]

---

## 優先處理的待辦事項

### 嚴重（等級 F，落後 11 個以上版本）
[列出具有檔案路徑的特定白皮書]

### 高優先級（等級 D-F，落後 2 個以上版本）
[列出特定檔案]

### 中等優先級（元資料品質、類別修正）
[列出特定問題]

### 低優先級（潤飾、日期對齊）
[列出特定問題]

---

## 後續步驟

1. 執行 `/update-whitepapers --since {oldest_version}` 以更新所有陳舊的白皮書
2. 修復英文類別不一致（5 個檔案：c01 至 c05，將 "Conceptual" 改為 "Design"）
3. 更新後重新執行 `/audit-whitepapers` 以追蹤進度
4. 目標：所有檔案的健康度達到 80% 以上（等級 B）

---

修正模式（--fix）

當傳入 --fix 時，在報告後附加一個修正建議章節。此章節提供具體的修補程式，但不會修改任何檔案。

前端資料版本修補程式

針對每個指南版本陳舊的檔案，輸出：

# 檔案：whitepapers/fr/00-introduction-serie.qmd
# 變更：
version: "3.27.6"  ->  version: "{current_VERSION}"
date: 2026-02-12   ->  date: {today}

類別修正修補程式（英文摘要卡片）

要更新的檔案（類別："Conceptual" -> "Design"）：
- whitepapers/recap-cards/en/c01-trust-calibration.qmd
- whitepapers/recap-cards/en/c02-*.qmd
- whitepapers/recap-cards/en/c03-*.qmd
- whitepapers/recap-cards/en/c04-*.qmd
- whitepapers/recap-cards/en/c05-*.qmd