FlorianBruniaux/claude-code-ultimate-guide

source-command-audit-whitepapers

当用户要求运行迁移后的源代码命令 audit-whitepapers 时使用此技能。

命令模板

审计白皮书与摘要卡片

对所有白皮书（法语 + 英语）和摘要卡片（法语 + 英语）进行全面新鲜度和质量审计。根据当前指南版本为每个文档评分，检查 FR/EN 一致性，并验证元数据一致性。

参数

• --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 frontmatter（读取第一个 --- 和第二个 --- 之间的内容）。提取：

   • title， subtitle， author， date
   • version（主要白皮书和摘要卡片中跟踪的指南版本）
   • wp-version（白皮书自身的语义版本，仅主要白皮书）
   • guide-version（摘要卡片中使用的显式指南版本字段）
   • card-number， category， difficulty（仅摘要卡片）
   • series（仅主要白皮书）

5. 显示发现摘要：

   指南版本：{VERSION}
   发现：{N} 个主要白皮书（{FR}/{EN} 法语/英语），{N} 个摘要卡片（{FR}/{EN} 法语/英语）
   排除：{N} 个自定义文件（strangebee， purchasely， devwithai），{N} 个捆绑文件
   

---

第2阶段：版本差距分析（每个文件40分）

目标：评估每个文档相对于指南的时效性。

语义化版本比较逻辑

将版本字符串解析为 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 字段存在且为有效语义化版本	5	字段存在且匹配 \d+\.\d+\.\d+（仅白皮书）
wp-version 与 FR/EN 配对一致	10	对应文件中 wp-version 值相同（仅白皮书）
guide-version 与 FR/EN 配对一致	10	对应文件中 guide-version（或 version）相同（卡片）

新鲜度标签：

• 落后0-1个小版本：新鲜
• 落后2-3个小版本：陈旧
• 落后4-10个小版本：非常陈旧
• 落后11+个小版本：严重

注意：指南版本的15、10、5分是互斥的（只授予最高适用等级）。

---

第3阶段：内容陈旧度检查（每个文件20分）

目标：检测自上次更新以来，白皮书涵盖的指南部分是否已发生更改。

白皮书到指南的映射（内嵌）

白皮书#	法语文件名前缀	英语文件名前缀	指南章节
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	商业/投资回报率内容

步骤

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阶段：FR/EN 对等性检查（每个文件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 遵循语义化版本模式	3	匹配 \d+\.\d+\.\d+
wp-version 遵循语义化版本模式	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	两个字段均存在且在同一文件中具有相同值

需自动检测的已知问题：EN C 系列卡片使用两种不同的类别值（c01-c05 上为 "Conceptual"，c06+ 上为 "Design"）。在报告的元数据问题部分明确标记此不一致性。

---

第6阶段：评分与分级

分数公式（每个文件）

总计 = 版本差距 (40) + 内容陈旧度 (20) + FR/EN 对等性 (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} 个小版本）

---

## 白皮书分数

| 白皮书# | 标题 | version | 差距 | wp-version | 对等性 | 分数 | 等级 |
|-----|-------|---------|-----|------------|--------|-------|-------|
| 00  | ...   | ...     | -N  | ...        | OK/差距 | N%    | X     |
...

<details>
<summary>单个标准分解（白皮书 00）</summary>

| 阶段 | 标准 | 结果 | 分数 |
|-------|-----------|--------|--------|
| 版本差距 | 指南版本为最新 | 严重 (-11) | 0/15 |
| 版本差距 | wp-version 有效语义化版本 | 通过 | 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>

---

## FR/EN 对等性报告

### 白皮书
| 白皮书# | 法语 | 英语 | wp-version 匹配 | version 匹配 |
|-----|----|----|------------------|---------------|
...

### 摘要卡片
- **法语数量**：{N} | **英语数量**：{N}
- **缺失的法语文档**：[列表或 "无"]
- **缺失的英语文档**：[列表或 "无"]
- **版本不匹配**：[列表或 "无"]

---

## 元数据问题

### 已知：EN 摘要卡片类别不一致
EN C 系列卡片对 "Conceptual/Design" 类别使用了两个不同的值：
- "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. 修复 EN 类别不一致问题（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}

类别修复补丁（EN 摘要卡片）

要更新的文件（类别："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