wehub/skillhub-132-guide-recap
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import zh skill guide-recap

Browse Source
This commit is contained in:
wehub-skill-sync
2026-07-13 21:36:38 +08:00
commit 2a1ff652c6
11 changed files with 1426 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.wehub.md
+9
View File
@@ -0,0 +1,9 @@
# WeHub 来源说明
- Skill 名称：`guide-recap`
- 中文类目：指南摘要
- 上游仓库：`florianbruniaux__claude-code-ultimate-guide`
- 上游路径：`.agents/skills/guide-recap/SKILL.md`
- 上游链接：https://github.com/florianbruniaux/claude-code-ultimate-guide/blob/HEAD/.agents/skills/guide-recap/SKILL.md
- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理
- 原作者、版权和许可证信息以上游仓库为准
SKILL.md
+219
View File
@@ -0,0 +1,219 @@
---
name: guide-recap
description: 将 CHANGELOG 条目转换为社交平台内容（LinkedIn、Twitter/X、Newsletter、Slack），支持法语和英语。在发布后或每周使用，从指南更新中生成可直接发布的内容。
argument-hint: "<latest|vX.Y.Z|week [YYYY-MM-DD]> [--interactive] [--format=linkedin|twitter|newsletter|slack] [--lang=fr|en] [--save]"
effort: medium
allowed-tools: Read, Bash
---
# Guide Recap
从 CHANGELOG.md 条目生成社交媒体内容。默认输出 8 份（4 种格式 × 2 种语言）。
## 何时使用
- 在运行 `/release` 后创建社交平台公告
- 每周汇总多个版本
- 在 LinkedIn、Twitter/X、Newsletter 或 Slack 上发帖前
## 用法
```
/guide-recap latest # 最新已发布版本
/guide-recap v3.20.5 # 指定版本
/guide-recap week # 本周（周一至今）
/guide-recap week 2026-01-27 # 指定周（周一至周日）
```
### 标记
| 标记 | 作用 | 默认值 |
|------|--------|---------|
| `--interactive` | 引导模式：选择角度、受众、亮点 | 关闭（自动草稿） |
| `--format=X` | 单一格式：`linkedin`、`twitter`、`newsletter`、`slack` | 全部 4 种格式 |
| `--lang=X` | 单一语言：`fr`、`en` | 法语 + 英语 |
| `--save` | 将输出保存至 `claudedocs/social-posts/` | 仅显示 |
| `--force` | 即使仅含维护类条目也生成内容 | 跳过低分内容 |
## 工作流程（7 步）
### 第 1 步：解析输入
解析 `$ARGUMENTS` 以确定模式：
| 输入 | 模式 | 目标 |
|-------|------|--------|
| `latest` | 单个版本 | `[Unreleased]` 之后的第一个 `## [X.Y.Z]` |
| `vX.Y.Z` 或 `X.Y.Z` | 单个版本 | 精确匹配版本号 |
| `week` | 周范围 | 本周周一至今 |
| `week YYYY-MM-DD` | 周范围 | 该周周一至下周日 |
如果没有参数或参数无效，显示用法说明并退出。
### 第 2 步：提取 CHANGELOG 条目
从项目根目录读取 `CHANGELOG.md`。
**单个版本：**
1. 找到匹配 `## [{version}]` 的行
2. 提取直到下一个 `## [` 行的所有内容
3. 解析 `### Added`、`### Changed`、`### Fixed` 章节
**周范围：**
1. 收集所有日期落在该范围内的 `## [X.Y.Z] - YYYY-MM-DD` 条目
2. 解析所有匹配版本中的所有章节
**错误：未找到版本** -> 列出最近 5 个版本，建议使用 `latest`。
**错误：该周没有条目** -> 显示最近一次发布的日期，建议使用该版本。
### 第 3 步：条目分类
对于每个顶级条目（`###` 下的一级项目符号），分配一个类别：
| 类别 | 权重 | 检测方式 |
|----------|--------|-----------|
| `NEW_CONTENT` | 3 | 新文件、新章节、新图表、新测验题 |
| `GROWTH_METRIC` | 2 | 行数增长、条目数量变化 |
| `RESEARCH` | 1 | 资源评估、外部来源集成 |
| `FIX` | 1 | 在 `### Fixed` 下，更正内容 |
| `MAINTENANCE` | 0 | README 更新、徽章同步、着陆页同步、计数更新 |
详细分类规则请参见 `references/changelog-parsing-rules.md`。
### 第 4 步：转换为用户价值
应用 `references/content-transformation.md` 中的映射规则：
- 技术语言 -> 用户收益
- 提取具体数字
- 注明来源
- 归并相关条目
对照 `references/tone-guidelines.md` 中的 DO/DON'T 检查清单进行验证。
### 第 4b 步：交互模式（仅限 --interactive）
如果设置了 `--interactive` 标记，则在第 4 步和第 5 步之间插入以下流程：
1. 显示候选亮点及评分：
```
Highlights (by score):
[14] 4 new ASCII diagrams (16 -> 20) [NEW_CONTENT]
[ 9] 30 new quiz questions (227 -> 257) [NEW_CONTENT]
[ 6] Docker sandbox isolation guide [NEW_CONTENT]
[ 1] README updated [MAINTENANCE]
```
2. 询问切入角度：
- 自动（最高分作为钩子）
- 用户选择特定条目作为钩子
- 自定义角度（用户提供主题）
3. 询问目标受众：
- `devs`（技术深度）
- `tech-leads`（关注影响力）
- `general`（通俗语言）
- `all`（默认，均衡）
4. 询问主要亮点：
- 自动（最高分）
- 用户从列表中选择
5. 确认选择并进入第 5 步。
### 第 5 步：评分与筛选
计算每条条目的评分：
```
score = (category_weight * 3)
+ (has_number * 2)
+ (named_source * 1)
+ (new_file * 1)
+ (min(impact_files, 3))
+ (breaking * 2)
```
按评分选择前 3-4 条。最高分作为钩子行。
**如果所有评分 < 3**：输出"此版本不推荐生成社交内容。请使用 `--force` 强制生成。"并退出（除非使用了 `--force`）。
### 第 6 步：生成内容
对于每种请求的格式（默认：全部 4 种）和语言（默认：两种）：
1. 从 `assets/` 读取对应的模板
2. 使用评分和转换后的条目填充模板字段
3. 应用 tone-guidelines.md 质量检查清单
**链接：**
| 格式 | 链接目标 |
|--------|-------------|
| LinkedIn | 着陆页 URL |
| Twitter | GitHub 仓库 URL |
| Newsletter | 两者（着陆页 + GitHub） |
| Slack | GitHub 仓库 URL |
**URL：**
- 着陆页：`https://florianbruniaux.github.io/Codex-ultimate-guide-landing/`
- GitHub：`https://github.com/FlorianBruniaux/Codex-ultimate-guide`
### 第 7 步：输出
将每条生成的内容显示在围栏代码块中，标注格式和语言：
```
## LinkedIn (FR)
```text
[内容]
`` `
## LinkedIn (EN)
```text
[内容]
`` `
## Twitter/X (FR)
```text
[内容]
`` `
...
```
如果使用 `--save` 标记：将所有输出写入 `claudedocs/social-posts/YYYY-MM-DD-vX.Y.Z.md`（针对版本）或 `claudedocs/social-posts/YYYY-MM-DD-week.md`（针对周）。如果 `claudedocs/social-posts/` 目录不存在则自动创建。
## 错误处理
| 错误 | 响应 |
|-------|----------|
| 无参数 | 显示用法说明块 |
| 无效参数 | 显示带有示例的用法说明块 |
| 未找到版本 | 列出最近 5 个版本，建议使用 `latest` |
| 该周没有条目 | 显示最近一次发布的日期，建议使用该版本 |
| 所有条目均为 MAINTENANCE（评分 0） | "不推荐生成社交内容。请使用 `--force` 强制生成。" |
| 未找到 CHANGELOG.md | "在项目根目录中未找到 CHANGELOG.md。" |
## 参考文件
- `references/tone-guidelines.md` - DO/DON'T 规则、emoji 预算、语言风格
- `references/changelog-parsing-rules.md` - CHANGELOG 格式、提取、评分算法
- `references/content-transformation.md` - 技术 -> 用户价值映射（30+ 条）
- `assets/linkedin-template.md` - 约 1300 字符，钩子 + 要点 + CTA + 标签
- `assets/twitter-template.md` - 280 字符单条或 2-3 条推文串
- `assets/newsletter-template.md` - 约 500 词，结构化章节
- `assets/slack-template.md` - 紧凑、富含 emoji、Slack 格式
- `examples/version-output.md` - v3.20.5 的完整示例输出
- `examples/week-output.md` - 2026-01-27 周的完整示例输出
## 提示
- 在 `/release` 后立即运行 `/guide-recap latest` 以准备社交平台帖子
- 前几次使用 `--interactive` 以了解评分机制
- 当只需要某个特定输出时，使用 `--format=linkedin --lang=fr`
- `--save` 输出通过 `claudedocs/` 约定被 gitignore 忽略
- 发布前请检查并个性化调整（这些是草稿，非最终文案）
assets/linkedin-template.md
+101
View File
@@ -0,0 +1,101 @@
# LinkedIn 模板
目标：约 1300 字符。结构：钩子 + 背景 + 要点 + 行动号召 + 话题标签。
## 法语模板
```
{法语钩子行}
{法语背景行}
{法语要点_1}
{法语要点_2}
{法语要点_3}
{法语行动号召}
#ClaudeCode #CodingWithAI #DeveloperTools
```
## 英语模板
```
{英语钩子行}
{英语背景行}
{英语要点_1}
{英语要点_2}
{英语要点_3}
{英语行动号召}
#ClaudeCode #CodingWithAI #DeveloperTools
```
## 字段规则
### hook_line（1 行，最多 150 字符）
得分最高的亮点，转化为用户价值。可包含 0-1 个 emoji。
| 模式 | 法语示例 | 英语示例 |
|---------|------------|------------|
| 数字开头 | `30 nouvelles questions quiz pour tester vos connaissances Claude Code` | `30 new quiz questions to test your Claude Code knowledge` |
| 提问式 | `Vous apprenez mieux en visuel ? 4 nouveaux diagrammes ASCII` | `Visual learner? 4 new ASCII diagrams just added` |
| 来源开头 | `Pat Cullen partage son workflow de code review multi-agent` | `Pat Cullen shares his multi-agent code review workflow` |
### context_line（1-2 行，最多 200 字符）
版本引用 + 高层级变更说明。
```
法语："Guide v3.20.5 - mise a jour de la reference visuelle."
英语："Guide v3.20.5 - visual reference update."
```
周报模式：
```
法语："N releases cette semaine dans le Claude Code Ultimate Guide."
英语："N releases this week in the Claude Code Ultimate Guide."
```
### bullets（3 项，每项最多 200 字符）
按得分排名前三的亮点。每项以相关 emoji 开头（每项最多 1 个）。
```
法语：
- [emoji] [转化为您视角的亮点]
- [emoji] [转化为您视角的亮点]
- [emoji] [转化为您视角的亮点]
英语：
- [emoji] [转化为直接「你」视角的亮点]
- [emoji] [转化为直接「你」视角的亮点]
- [emoji] [转化为直接「你」视角的亮点]
```
### cta（1 行，最多 150 字符）
温和的价值陈述或真诚的提问。链接到落地页。
```
法语："Guide complet disponible en open source : {landing_url}"
英语："Full guide available open source: {landing_url}"
```
### hashtags（1 行，恰好 3 个）
固定标签：`#ClaudeCode #CodingWithAI #DeveloperTools`
若明确相关，可添加 1 个特定话题标签：`#CodeReview`、`#Security`、`#TDD`
## 约束条件
- 帖子总字符数：1100-1500 字符
- Emoji 预算：总计 3-4 个（钩子 0-1 个，每个要点 1 个，CTA 0-1 个）
- 不使用浮夸用语（参见 tone-guidelines.md）
- 法语：使用敬语「您」
- 英语：美式英语
assets/newsletter-template.md
+123
View File
@@ -0,0 +1,123 @@
# 新闻简报模板
目标：约 500 字。结构化段落，有一定深度。
## 法文模板
```markdown
# {title_fr}
{intro_paragraph_fr}
## 变更内容
{highlights_section_fr}
## 详细说明
{detail_section_fr}
## 要点总结
{takeaway_fr}
---
[完整指南]({landing_url}) | [GitHub]({github_url})
```
## 英文模板
```markdown
# {title_en}
{intro_paragraph_en}
## What changed
{highlights_section_en}
## In detail
{detail_section_en}
## Key takeaway
{takeaway_en}
---
[Full guide]({landing_url}) | [GitHub]({github_url})
```
## 字段规则
### title（最多 80 字符）
版本或周次框架，具有描述性。
```
FR: "Guide v3.20.5 : Reference visuelle enrichie"
EN: "Guide v3.20.5: Enhanced Visual Reference"
FR: "Semaine du 27 janvier : 4 releases, 9 patterns avances"
EN: "Week of January 27: 4 releases, 9 advanced patterns"
```
### intro_paragraph（2-3 句话，最多 150 词）
发生了什么以及为什么重要。不作夸大渲染。
```
FR: "La version 3.20.5 du Claude Code Ultimate Guide ajoute 4 nouveaux
diagrammes ASCII a la reference visuelle. Le guide contient maintenant
20 diagrammes couvrant TDD, securite et workflows d'apprentissage."
EN: "Version 3.20.5 of the Claude Code Ultimate Guide adds 4 new ASCII
diagrams to the visual reference. The guide now contains 20 diagrams
covering TDD, security, and learning workflows."
```
### highlights_section（项目符号列表，3-5 条）
评分最高的条目，经过转化。每条项目符号：最多 1-2 句话。
```
FR:
- **Cycle TDD Red-Green-Refactor** : Diagramme du flux iteratif test-code-refactor
- **Protocole UVAL** : Visualisation du framework Comprendre-Verifier-Appliquer-Apprendre
- **Defense securite 3 couches** : Prevention, detection, reponse avec guide d'adoption
- **Timeline d'exposition de secrets** : Actions d'urgence par fenetre temporelle (15min/1h/24h)
EN:
- **TDD Red-Green-Refactor Cycle**: Diagram of the iterative test-code-refactor flow
- **UVAL Protocol Flow**: Visualization of the Understand-Verify-Apply-Learn framework
- **Security 3-Layer Defense**: Prevention, detection, response with adoption guide
- **Secret Exposure Timeline**: Emergency actions by time window (15min/1h/24h)
```
### detail_section（1-2 段落，最多 200 词）
对最引人注目的亮点展开说明。提供背景，解释用户能获得什么。如适用，注明来源。
### takeaway（1-2 句话）
单个可操作的见解或总结。
```
FR: "Si vous apprenez mieux en visuel, les 20 diagrammes du guide couvrent
maintenant les workflows les plus frequents, de TDD a la gestion d'incidents."
EN: "If you're a visual learner, the guide's 20 diagrams now cover the most
common workflows, from TDD to incident management."
```
## 约束条件
- 总字数：400-600 词
- emoji 预算：2-3 个（仅限章节标题）
- 不得使用夸大词汇
- 法文：用「您」尊称
- 英文：美式英语
- 页脚中同时包含两个链接（landing 页 + GitHub）
- 注明所有提及的来源
assets/slack-template.md
+86
View File
@@ -0,0 +1,86 @@
# Slack 模板
简洁、易扫读、表情丰富。可直接粘贴使用。
## 法语模板
```
:newspaper: *{title_fr}*
{highlights_fr}
:link: {link}
```
## 英语模板
```
:newspaper: *{title_en}*
{highlights_en}
:link: {link}
```
## 字段规则
### title（最多 60 字符）
```
FR: "Guide v3.20.5 - Reference visuelle"
EN: "Guide v3.20.5 - Visual reference"
FR: "Recap semaine : 4 releases"
EN: "Week recap: 4 releases"
```
### highlights（3–5 行）
每行格式：Slack 表情符号 + 简短描述。要点文字中不使用加粗。
```
FR:
:art: 4 nouveaux diagrammes ASCII (TDD, UVAL, securite, incidents)
:brain: 30 nouvelles questions quiz (257 total)
:shield: Guide sandbox isolation Docker
:mag: 9 patterns avances identifies via claudelog.com
EN:
:art: 4 new ASCII diagrams (TDD, UVAL, security, incidents)
:brain: 30 new quiz questions (257 total)
:shield: Docker sandbox isolation guide
:mag: 9 advanced patterns identified via claudelog.com
```
### link
GitHub 仓库 URL。
## Slack 表情符号参考
使用所有工作区均能正常渲染的标准 Slack 表情符号：
| 表情符号 | 代码 | 用途 |
|-------|------|---------|
| :newspaper: | `:newspaper:` | 标题标记 |
| :art: | `:art:` | 视觉内容、图表、界面 |
| :brain: | `:brain:` | 测验、学习、知识 |
| :shield: | `:shield:` | 安全内容 |
| :mag: | `:mag:` | 研究、分析、竞争情报 |
| :wrench: | `:wrench:` | 工具、工作流、配置 |
| :books: | `:books:` | 新指南、文档 |
| :chart_with_upwards_trend: | `:chart_with_upwards_trend:` | 增长指标 |
| :white_check_mark: | `:white_check_mark:` | 修复、更正 |
| :link: | `:link:` | 链接标记 |
| :arrow_right: | `:arrow_right:` | 增长指示符（X -> Y） |
## 约束条件
- 总字数不超过 500 字符
- 表情符号数量：4–6 个（1 个标题 + 每行亮点各 1 个 + 1 个链接）
- 不使用夸张宣传用语
- 法语：使用「你」称呼（tutoiement）
- 英语：使用美式英语
- 仅包含一个链接（GitHub）
- 不使用话题标签（非 Slack 惯例）
- 使用 Slack 格式：`*bold*`、`_italic_`、`:emoji:` 代码
assets/twitter-template.md
+145
View File
@@ -0,0 +1,145 @@
# Twitter/X 模板
两种模式：单条推文（280 字符）或推文串（2–3 条推文）。
## 单条推文
适用场景：1–2 个亮点、简单版本更新。
### FR 模板
```
{hook_line_fr}
{highlight_fr}
{link}
```
### EN 模板
```
{hook_line_en}
{highlight_en}
{link}
```
### 规则
- 总字符数不超过 280（含链接）
- 最多 2 个 emoji
- 链接指向 GitHub 仓库
- 法文：使用「你」称呼（tutoiement）
- 英文：直接称呼
## 推文串（2–3 条推文）
适用场景：3 个及以上亮点、内容丰富的版本周。
### FR 模板
```
Tweet 1/N：
{hook_line_fr}
{context_fr}
Thread [down_arrow]
---
Tweet 2/N：
{highlight_1_fr}
{highlight_2_fr}
---
Tweet 3/N（可选）：
{highlight_3_fr}
{cta_fr}
{link}
```
### EN 模板
```
Tweet 1/N：
{hook_line_en}
{context_en}
Thread [down_arrow]
---
Tweet 2/N：
{highlight_1_en}
{highlight_2_en}
---
Tweet 3/N（可选）：
{highlight_3_en}
{cta_en}
{link}
```
## 字段规则
### hook_line（最多 100 字符）
最核心亮点的最简表述。必须能与上下文一同放入首条推文。
| 模式 | FR | EN |
|---------|-----|-----|
| 数字开头 | `30 nouvelles questions quiz Claude Code` | `30 new Claude Code quiz questions` |
| 直述 | `Nouveau guide : sandbox isolation Docker` | `New guide: Docker sandbox isolation` |
### context（最多 80 字符）
```
FR：Guide v3.20.5 vient de sortir
EN：Guide v3.20.5 just dropped
```
### highlights（每条最多 120 字符）
转换后的条目，每行一条。不使用项目符号（用换行分隔）。
```
FR：4 diagrammes ASCII pour TDD, UVAL, securite
EN：4 ASCII diagrams for TDD, UVAL, security
```
### cta（最多 60 字符）
```
FR：Tout est open source
EN：All open source
```
### link
GitHub 仓库 URL。计入 280 字符上限（t.co 短链接占 23 字符）。
## 决策：单条推文 vs 推文串
| 条件 | 格式 |
|-----------|--------|
| 1–2 个亮点且全部能放入 280 字符 | 单条推文 |
| 3 个及以上亮点或内容丰富 | 推文串（2–3 条推文） |
| 包含多个版本的周报 | 推文串 |
| 仅涉及维护性改动 | 单条推文（或跳过） |
## 约束条件
- 每条推文：最多 280 字符
- Emoji 预算：整条推文串最多 2 个
- 不使用夸张词汇
- 法文：使用「你」称呼（tutoiement）
- 英文：使用美式英语
- 推文串上限：3 条（不是 5 条以上）
examples/version-output.md
+145
View File
@@ -0,0 +1,145 @@
# 示例：/guide-recap v3.20.5
输入：`/guide-recap v3.20.5`
## 评分
| 条目 | 类别 | 分数 | 细项 |
|-------|----------|-------|-----------|
| 新增 4 个 ASCII 图表（16 -> 20） | NEW_CONTENT | 14 | (3*3)+(1*2)+(0*1)+(1*1)+(2)+(0*2) = 14 |
| README：在表格中添加视觉参考 | MAINTENANCE | 1 | (0*3)+(0*2)+(0*1)+(0*1)+(1)+(0*2) = 1 |
精选亮点：仅 #1（1 条高于阈值）。
钩子行："新增 4 个 ASCII 图表（16 -> 20）"
## 输出
### LinkedIn（法语）
```text
Claude Code 指南新增 4 个 ASCII 图表（总数 16 -> 20）
指南 v3.20.5 - 视觉参考再升级。
- TDD 红-绿-重构周期：测试-编码-重构迭代流程一目了然
- UVAL 协议：理解-验证-应用-学习框架可视化呈现
- 安全三层防御：预防、检测、响应，附团队规模适配路径
- 机密泄露时间线：按时间窗口（15 分钟/1 小时/24 小时）采取紧急行动
完整指南开源可用：https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/
#ClaudeCode #CodingWithAI #DeveloperTools
```
### LinkedIn（英语）
```text
Claude Code 指南新增 4 个 ASCII 图表（总数 16 -> 20）
指南 v3.20.5 - 视觉参考更新。
- TDD 红-绿-重构周期：测试-编码-重构迭代流程一目了然
- UVAL 协议流程：理解-验证-应用-学习框架可视化
- 安全三层防御：预防、检测、响应，附团队规模适配路径
- 机密泄露时间线：按时间窗口（15 分钟/1 小时/24 小时）采取紧急行动
完整指南开源可用：https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/
#ClaudeCode #CodingWithAI #DeveloperTools
```
### Twitter/X（法语）
```text
Claude Code 指南新增 4 个 ASCII 图表
TDD、UVAL、三层安全、事件时间线 - 视觉参考 v3.20.5
https://github.com/FlorianBruniaux/claude-code-ultimate-guide
```
### Twitter/X（英语）
```text
Claude Code 指南新增 4 个 ASCII 图表
TDD、UVAL、三层安全、事件时间线 - 视觉参考 v3.20.5
https://github.com/FlorianBruniaux/claude-code-ultimate-guide
```
### 新闻通讯（法语）
```markdown
# 指南 v3.20.5：视觉参考全面升级
Claude Code Ultimate Guide 3.20.5 版在视觉参考中新增了 4 个 ASCII 图表。该指南现包含 20 个图表，涵盖 TDD、安全及学习工作流。
## 更新内容
- **TDD 红-绿-重构周期**：测试-编码-重构迭代流程图，展示编写测试、最小代码和重构之间的循环
- **UVAL 协议流程**：理解-验证-应用-学习框架的可视化呈现，含失败回溯路径
- **安全三层防御**：预防/检测/响应概览，附团队规模适配路径
- **机密泄露时间线**：按时间窗口（15 分钟/1 小时/24 小时）的紧急行动指南，附严重程度参考
## 详细说明
新增的 4 个图表（#17-#20）覆盖了指南中已有文字记录的工作流，但通过可视化呈现帮助快速理解。TDD 图表需求最高：它将红-绿-重构循环展示为连续循环而非线性步骤。UVAL 图表是首个在学习框架的每一步都展示失败回溯路径的图表。
## 要点总结
如果您是视觉型学习者，指南的 20 个图表现已覆盖从 TDD 到安全管理的最常用工作流。
---
[完整指南](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) | [GitHub](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)
```
### 新闻通讯（英语）
```markdown
# 指南 v3.20.5：视觉参考全面升级
Claude Code Ultimate Guide 3.20.5 版在视觉参考中新增了 4 个 ASCII 图表。该指南现包含 20 个图表，涵盖 TDD、安全及学习工作流。
## 更新内容
- **TDD 红-绿-重构周期**：测试-编码-重构迭代流程图，展示编写测试、最小代码和重构之间的循环
- **UVAL 协议流程**：理解-验证-应用-学习框架的可视化呈现，含失败回溯路径
- **安全三层防御**：预防/检测/响应概览，附团队规模适配路径
- **机密泄露时间线**：按时间窗口（15 分钟/1 小时/24 小时）的紧急行动指南，附严重程度参考
## 详细说明
新增的 4 个图表（#17-#20）覆盖了指南中已有文字记录的工作流，但通过可视化呈现帮助快速理解。TDD 图表需求最高：它将红-绿-重构循环展示为连续循环而非线性步骤。UVAL 图表是首个在学习框架的每一步都展示失败回溯路径的图表。
## 要点总结
如果您是视觉型学习者，指南的 20 个图表现已覆盖从 TDD 到安全管理的最常用工作流。
---
[完整指南](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) | [GitHub](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)
```
### Slack（法语）
```text
:newspaper: *指南 v3.20.5 - 视觉参考*
:art: 新增 4 个 ASCII 图表（TDD、UVAL、安全、事件）
:arrow_right: 总数 16 -> 20 个图表
:link: https://github.com/FlorianBruniaux/claude-code-ultimate-guide
```
### Slack（英语）
```text
:newspaper: *指南 v3.20.5 - 视觉参考*
:art: 新增 4 个 ASCII 图表（TDD、UVAL、安全、事件）
:arrow_right: 总数 16 -> 20 个图表
:link: https://github.com/FlorianBruniaux/claude-code-ultimate-guide
```
examples/week-output.md
+209
View File
@@ -0,0 +1,209 @@
---
name: guide-recap
description: 将 Claude Code Ultimate Guide 更新日志自动排版成多渠道周报
trigger: /guide-recap
usage: /guide-recap week 2026-01-27
---
# 示例：/guide-recap week 2026-01-27
输入：`/guide-recap week 2026-01-27`
日期范围：2026-01-27（星期一）至 2026-02-02（星期日）
## 范围内的版本
| 版本 | 日期 | 条目数 |
|---------|------|---------|
| 3.20.5 | 2026-01-31 | 2 条 |
| 3.20.4 | 2026-01-31 | 3 条 |
| 3.20.3 | 2026-01-31 | 5 条 |
| 3.20.2 | 2026-01-31 | 4 条 |
| 3.20.1 | 2026-01-30 | 2 条 |
| 3.20.0 | 2026-01-30 | 5 条 |
**本周共 6 个版本发布。**
## 评分（热门条目）
| 条目 | 版本 | 类别 | 得分 |
|-------|---------|----------|-------|
| 来自 claudelog.com 的 9 个差距（9 个新模式） | 3.20.3 | NEW_CONTENT | 15 |
| 30 道新测验题（227 → 257） | 3.20.4 | NEW_CONTENT | 14 |
| 4 个新 ASCII 图表（16 → 20） | 3.20.5 | NEW_CONTENT | 14 |
| 多智能体 PR 审查（Pat Cullen） | 3.20.0 | NEW_CONTENT | 13 |
| Docker 沙箱隔离 | 3.20.2 | NEW_CONTENT | 11 |
| 贡献指标（Anthropic 博客） | 3.20.2 | RESEARCH | 8 |
已选：前 4 条（得分 15、14、14、13）。
## 输出
### LinkedIn（法语）
```text
本周 Claude Code Ultimate Guide 发布了 6 个版本
1 月 27 日这一周：指南自发布以来内容最丰富的一周。
- 通过 claudelog.com 识别出 9 个高级模式：Permutation Frameworks、Split-Role Agents、Mechanic Stacking 等 6 个
- 30 道新测验题（共 257 道），覆盖 11 个类别
- 4 个新 ASCII 图表，涉及 TDD、UVAL、安全与事件
- 基于 Pat Cullen 工作的多智能体代码审查工作流：3 个专业智能体、反幻觉规则、严重级别分类
完整指南开源地址：https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/
#ClaudeCode #CodingWithAI #DeveloperTools
```
### LinkedIn（英语）
```text
本周 Claude Code Ultimate Guide 发布了 6 个版本
1 月 27 日这一周：指南自发布以来内容最丰富的一周。
- 通过 claudelog.com 识别出 9 个高级模式：Permutation Frameworks、Split-Role Agents、Mechanic Stacking 等 6 个
- 30 道新测验题（共 257 道），覆盖 11 个类别
- 4 个新 ASCII 图表，涉及 TDD、UVAL、安全与事件
- 基于 Pat Cullen 工作的多智能体代码审查工作流：3 个专业智能体、反幻觉规则、严重级别分类
完整指南开源地址：https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/
#ClaudeCode #CodingWithAI #DeveloperTools
```
### Twitter/X（法语）
```text
推文 1/3：
本周 Claude Code Ultimate Guide 发布了 6 个版本
指南内容最丰富的一周
---
推文 2/3：
9 个高级模式（Permutation Frameworks、Split-Role Agents……）
30 道新测验题（共 257 道）
4 个 ASCII 图表（TDD、UVAL、安全）
---
推文 3/3：
多智能体代码审查（Pat Cullen）
Docker 沙箱隔离
Anthropic 指标：PR/日 +67%
https://github.com/FlorianBruniaux/claude-code-ultimate-guide
```
### Twitter/X（英语）
```text
推文 1/3：
本周 Claude Code Ultimate Guide 发布了 6 个版本
指南自发布以来内容最丰富的一周
---
推文 2/3：
9 个高级模式（Permutation Frameworks、Split-Role Agents……）
30 道新测验题（共 257 道）
4 个 ASCII 图表（TDD、UVAL、安全）
---
推文 3/3：
多智能体代码审查（Pat Cullen）
Docker 沙箱隔离
Anthropic 指标：PR/日 +67%
https://github.com/FlorianBruniaux/claude-code-ultimate-guide
```
### 新闻通讯（法语）
```markdown
# 1 月 27 日这一周：6 个版本发布，9 个高级模式
1 月 27 日这一周是 Claude Code Ultimate Guide 最密集的一周，共发布了 6 个版本。以下是最重要的变化。
## 变更内容
- **9 个高级模式（claudelog.com）**：对 313 篇社区页面进行了系统分析。新增模式：Permutation Frameworks、Split-Role Agents、Mechanic Stacking、Rev the Engine、Task Lists as Diagnostic、"You Are the Main Thread"
- **30 道新测验题**：共 257 道题，覆盖 11 个类别，包括高级模式（+8）、MCP 服务器（+3）、架构（+3）
- **4 个 ASCII 图表**：TDD 红-绿-重构、UVAL 协议、安全三层防御、密钥泄露时间线
- **多智能体代码审查**：Pat Cullen 的生产工作流，包含 3 个专业智能体（一致性、SOLID、防御性代码）、反幻觉规则和收敛循环
## 详情
针对 claudelog.com 的竞品分析识别出指南中的 9 个差距。Permutation Frameworks 模式最为有趣：它提出了一种系统化的方法来测试架构变体（REST vs GraphQL vs tRPC），以 CLAUDE.md 作为驱动。Mechanic Stacking 将 5 层智能（计划模式、扩展思维、Rev、Split-Role、Permutation）与基于影响级别的决策矩阵相结合。
Pat Cullen 的代码审查工作流带来了具体的反幻觉保障措施：在任何建议之前先用 Grep/Glob 验证模式、出现次数规则（>10 = 已确立，3-10 = 新兴，<3 = 未确立），以及读取完整文件上下文。
## 要点总结
本周标志着向高级模式和代码质量的转变。如果你使用 Claude Code 进行审查，多智能体工作流值得探索。
---
[完整指南](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) | [GitHub](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)
```
### 新闻通讯（英语）
```markdown
# 1 月 27 日这一周：6 个版本发布，9 个高级模式
1 月 27 日这一周是 Claude Code Ultimate Guide 最密集的一周，共发布了 6 个版本。以下是最重要的变化。
## 变更内容
- **9 个高级模式（claudelog.com）**：对 313 篇社区页面进行了系统分析。新增模式：Permutation Frameworks、Split-Role Agents、Mechanic Stacking、Rev the Engine、Task Lists as Diagnostic、"You Are the Main Thread"
- **30 道新测验题**：共 257 道题，覆盖 11 个类别，包括高级模式（+8）、MCP 服务器（+3）、架构（+3）
- **4 个 ASCII 图表**：TDD 红-绿-重构、UVAL 协议、安全三层防御、密钥泄露时间线
- **多智能体代码审查**：Pat Cullen 的生产工作流，包含 3 个专业智能体（一致性、SOLID、防御性代码）、反幻觉规则和收敛循环
## 详情
针对 claudelog.com 的竞品分析识别出指南中的 9 个差距。Permutation Frameworks 模式最为有趣：它提出了一种系统化的方法来测试架构变体（REST vs GraphQL vs tRPC），以 CLAUDE.md 作为驱动。Mechanic Stacking 将 5 层智能（计划模式、扩展思维、Rev、Split-Role、Permutation）与基于影响级别的决策矩阵相结合。
Pat Cullen 的代码审查工作流带来了具体的反幻觉保障措施：在任何建议之前先用 Grep/Glob 验证模式、出现次数规则（>10 = 已确立，3-10 = 新兴，<3 = 未确立），以及读取完整文件上下文。
## 要点总结
本周标志着向高级模式和代码质量的转变。如果你使用 Claude Code 进行审查，多智能体工作流值得探索。
---
[完整指南](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) | [GitHub](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)
```
### Slack（法语）
```text
:newspaper: *本周回顾：6 个版本发布（1 月 27 日 - 1 月 31 日）*
:mag: 通过 claudelog.com 发现 9 个高级模式（Permutation Frameworks、Split-Role Agents……）
:brain: 30 道新测验题（共 257 道）
:art: 4 个 ASCII 图表（TDD、UVAL、安全、事件）
:wrench: 多智能体代码审查（Pat Cullen）：3 个智能体、反幻觉、收敛
:shield: Docker 沙箱隔离指南
:link: https://github.com/FlorianBruniaux/claude-code-ultimate-guide
```
### Slack（英语）
```text
:newspaper: *本周回顾：6 个版本发布（1 月 27 日 - 1 月 31 日）*
:mag: 通过 claudelog.com 发现 9 个高级模式（Permutation Frameworks、Split-Role Agents……）
:brain: 30 道新测验题（共 257 道）
:art: 4 个 ASCII 图表（TDD、UVAL、安全、事件）
:wrench: 多智能体代码审查（Pat Cullen）：3 个智能体、反幻觉、收敛
:shield: Docker 沙箱隔离指南
:link: https://github.com/FlorianBruniaux/claude-code-ultimate-guide
references/changelog-parsing-rules.md
+142
View File
@@ -0,0 +1,142 @@
# CHANGELOG 解析规则
如何从 `CHANGELOG.md` 中提取内容并进行分类，以生成社交媒体内容。
## CHANGELOG 格式
本项目遵循 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) 规范。
```
## [Unreleased]
## [X.Y.Z] - YYYY-MM-DD
### Added
- **标题**：描述
- 子详情 1
- 子详情 2
### Changed
- **标题**：描述
### Fixed
- **标题**：描述
---
（水平线分隔同一版本内的分组条目）
```
## 提取方法
### 按版本提取（`/guide-recap v3.20.5`）
1. 读取 CHANGELOG.md
2. 查找匹配 `## [3.20.5]` 的行
3. 提取直到下一个 `## [` 行的全部内容
4. 解析所有 `### Added/Changed/Fixed` 章节
### 提取最新版本（`/guide-recap latest`）
1. 读取 CHANGELOG.md
2. 跳过 `## [Unreleased]`
3. 提取第一个 `## [X.Y.Z]` 块（即最新已发布版本）
### 按周提取（`/guide-recap week` 或 `/guide-recap week 2026-01-27`）
1. 确定日期范围：
- `week` 不带日期：当前周的周一 → 今天
- `week YYYY-MM-DD`：该周的周一 → 接下来的周日
2. 读取 CHANGELOG.md
3. 收集所有日期在范围内的 `## [X.Y.Z] - YYYY-MM-DD` 条目
4. 汇总所有版本的条目
## 条目结构
`### Added/Changed/Fixed` 下的每个顶级要点即为一条**条目**。解析字段如下：
| 字段 | 来源 | 示例 |
|-------|--------|---------|
| `title` | `- **` 后的加粗文本 | `Visual Reference` |
| `description` | 同一行中 `:` 或 `--` 后的文本 | `4 new high-value ASCII diagrams (16 -> 20 total)` |
| `sub_items` | 缩进的子要点 | 详情行列表 |
| `section` | 父级 `###` 标题 | `Added`, `Changed`, `Fixed` |
| `files` | 描述中的文件名/路径 | `guide/ultimate-guide.md`, `machine-readable/reference.yaml` |
| `source` | URL 或具名引用 | `Pat Cullen's Final Review Gist` |
| `metrics` | 描述中的数字 | `227 -> 257`, `+522 lines`, `4 new` |
| `score` | 若存在则取评估分数 | `Score: 4/5` |
## 分类体系
每条条目分配一个类别及对应权重：
| 类别 | 权重 | 匹配模式 |
|----------|--------|---------|
| `NEW_CONTENT` | 3 | 新增指南章节、新文件、新图表、新测验题 |
| `GROWTH_METRIC` | 2 | 行数增长、模板数量变化、测验数量变化 |
| `RESEARCH` | 1 | 资源评估、外部来源整合 |
| `FIX` | 1 | 缺陷修复、内容更正、准确性改进 |
| `MAINTENANCE` | 0 | README 更新、徽章更新、计数同步、着陆页同步 |
### 分类规则
1. 如果条目创建了新的 `.md` 文件或新章节 → `NEW_CONTENT`
2. 如果条目包含带数字的 `->`（增长）→ `GROWTH_METRIC`
3. 如果条目引用了带评估分数的外部来源 → `RESEARCH`
4. 如果条目位于 `### Fixed` 下 → `FIX`
5. 如果条目仅涉及更新计数、徽章或同步 → `MAINTENANCE`
6. 如果条目包含内容充实的子条目 → 提升一级
7. 存在歧义时，优先采用权重更高的类别
### 示例
```
"4 new ASCII diagrams (16 -> 20)" -> NEW_CONTENT（新图表）
"30 New Quiz Questions (227 -> 257)" -> NEW_CONTENT（新题目）
"Quiz badge updated (227 -> 257)" -> MAINTENANCE（徽章同步）
"Guide line count: 15,771 -> 16,293" -> GROWTH_METRIC（增长）
"Score: 4/5 - Docker Sandboxes" -> RESEARCH（评估）
"Fixed 14 -> 15 categories in landing" -> FIX（修正）
"README.md: Added Visual Reference to table" -> MAINTENANCE（导航更新）
```
## 评分算法
对每条条目按以下方式计算分数：
```
score = (category_weight * 3)
+ (has_number * 2)
+ (named_source * 1)
+ (new_file * 1)
+ (min(impact_files, 3))
+ (breaking * 2)
```
| 因子 | 取值 | 检测方式 |
|--------|-------|-----------|
| `category_weight` | 0-3 | 来自上文的类别表 |
| `has_number` | 0 或 1 | 条目包含数值变化（`N -> M`、`+N lines`、`N new`） |
| `named_source` | 0 或 1 | 条目提及了人员或外部来源 |
| `new_file` | 0 或 1 | 条目提到创建了新文件（`NEW`、新的 `.md`） |
| `impact_files` | 0-3 | 提及的不同文件数量（上限为 3） |
| `breaking` | 0 或 1 | 条目位于 `### Breaking` 下，或提及了破坏性变更 |
### 分数解读
| 分数 | 处理方式 |
|-------|--------|
| 10+ | 主要亮点（开场句） |
| 6-9 | 次要亮点（要点） |
| 3-5 | 空间允许则纳入 |
| 0-2 | 跳过（维护性噪音） |
按分数选取前 3-4 条。若所有分数均低于 3，标记为"不建议发布社交媒体内容"。
## 周汇总规则
当为一周内多个版本生成汇总时：
1. 对日期范围内所有版本的所有条目进行评分
2. 去重：若同一主题出现在多个版本中，保留评分最高的一条
3. 在周输出的开头加上版本数量：`本周共 X 个版本`
4. 标题中使用日期范围，不使用具体版本号
references/content-transformation.md
+139
View File
@@ -0,0 +1,139 @@
# 内容转化
将技术性的更新日志（CHANGELOG）语言映射为用户可见的社会价值。所有输出均遵循 tone-guidelines.md 规则。
## 转化原则
```
技术事实（CHANGELOG） -> 用户收益（社交帖子）
```
绝不编造收益。每一次转化都必须能追溯到具体的 CHANGELOG 行。
## 映射表
### 新增内容
| 技术用语（CHANGELOG） | 社交用语（用户价值） |
|---|---|
| `N new ASCII diagrams (X -> Y total)` | `视觉学习者？[主题] 新增 N 张图表` |
| `N New Quiz Questions (X -> Y total)` | `测试你的 Claude Code 知识：新增 N 道题目，涵盖 [主要类别]` |
| `New [guide-name].md (N lines)` | `新指南：[通俗语言描述的主题]` |
| `New section: [Section Name] (~N lines)` | `[你现在可以学到/做的事情]：[通俗描述]` |
| `New workflow: [name]` | `分步指南：如何使用 Claude Code [执行某操作]` |
| `Enhanced [command/agent] (+N lines)` | `[命令] 现在支持 [新功能]` |
| `N new entries in reference.yaml` | 跳过（内部索引，无用户价值） |
### 研究与来源
| 技术用语（CHANGELOG） | 社交用语（用户价值） |
|---|---|
| `Score: 5/5 - [Source]` | `来自 [作者] 的关键发现：[核心洞察]` |
| `Score: 4/5 - [Source]` | `来自 [作者] 的研究：[实用收获]` |
| `Score: 3/5 - [Source]` | `[作者] 确认：[相关发现]` |
| `Source: [URL] ([Author], [Date])` | `基于 [作者] 的工作` |
| `Competitive Analysis: N Gaps from [source]` | `识别出 N 个高级模式：[前 2-3 个名称]` |
| `Resource evaluation: [file]` | 跳过（内部流程，非面向用户） |
| `Fact-checked: N/N claims verified` | 可作为可信度信号提及：`全部 N 条声明已核实` |
### 增长指标
| 技术用语（CHANGELOG） | 社交用语（用户价值） |
|---|---|
| `Guide line count: X -> Y (+N lines)` | `本[周/版本]新增 +N 行文档` |
| `X -> Y total [items]` | `[项目] 现有 Y 个（之前为 X）` |
| `+N lines: X -> Y` | `[功能] 扩展了 N 行 [内容类型]` |
### 修复与变更
| 技术用语（CHANGELOG） | 社交用语（用户价值） |
|---|---|
| `Fixed [technical issue]` | `已修正：[用户可见的修复内容]` |
| `[File]: Updated [field] (X -> Y)` | 除非是用户可见的变更，否则跳过 |
| `Landing synced` | 跳过（基础设施） |
| `Badge updated` | 跳过（基础设施） |
### 维护项（通常跳过）
| 技术用语（CHANGELOG） | 社交价值 |
|---|---|
| `README.md: Added [X] to table` | 跳过 |
| `Updated counts in [files]` | 跳过 |
| `Sync: [description]` | 跳过 |
| `reference.yaml: +N entries` | 跳过 |
| `CLAUDE.md: [update]` | 跳过 |
## 模式识别
### 需要高亮的数字
当条目包含数字变化时，提取并格式化：
```
"30 New Quiz Questions (227 -> 257)"
-> 数量：30
-> 增长："227 -> 257"
-> 高亮："新增 30 道题目"或"现有 257 道题目"
"4 new ASCII diagrams (16 -> 20 total)"
-> 数量：4
-> 增长："16 -> 20"
-> 高亮："新增 4 张图表"或"现有 20 张图表"
"+522 lines"
-> 数量：522
-> 高亮："+522 行新增内容"
```
### 需要署名的来源
提取作者姓名并给出适当署名：
```
"Pat Cullen's Final Review Gist" -> "来自 Pat Cullen 的生产工作流"
"Addy Osmani's 80% Problem" -> "基于 Addy Osmani 的研究"
"Shen & Tamkin RCT" -> "来自 Shen & Tamkin 的研究（Anthropic）"
"claudelog.com (InventorBlack)" -> "由 claudelog.com 社区发现"
"Jude Gao (Vercel)" -> "来自 Vercel 的基准测试（Jude Gao）"
```
### 主题聚类
当多个条目共享一个主题时，将它们聚类：
```
与代码评审相关的条目：
- "Multi-Agent PR Review"
- "Enhanced /review-pr command"
- "Enhanced code-reviewer agent"
-> 聚类："代码评审大升级：多智能体工作流、防幻觉规则、严重程度分类"
与安全相关的条目：
- "Docker sandbox isolation"
- "Security 3-Layer Defense diagram"
- "Secret Exposure Timeline diagram"
-> 聚类："安全聚焦：沙箱隔离、防御层级、事件响应时间线"
```
## 版本 vs 周次框架
### 单版本
```
FR: "Claude Code Ultimate Guide v3.20.5"
EN: "Claude Code Ultimate Guide v3.20.5"
```
### 周次（多个版本）
```
FR: "Cette semaine dans le guide (N releases)"
EN: "本周指南（N 个版本）"
```
### 周次（单个版本）
```
FR: "Cette semaine : guide v3.20.5"
EN: "本周：指南 v3.20.5"
```
references/tone-guidelines.md
+108
View File
@@ -0,0 +1,108 @@
---
## Code Review: `reports/phase3/scripts/build_top200_v2_h5.py`
This diff is a major refactoring of the H5 page builder — from a standalone inline HTML generator (~925 lines) to a template-based approach (~312 lines) that reuses `skill-market-h5.html` as a shell. The table-based layout is replaced with a card grid, the scoring scale changes from 20 to 5, and the UI switches from select-based filters to chip-based filters.
---
### `build_top200_v2_h5.py:100` — `CLEANUP` — Dead return value in `extract_h5_shell()`
**Summary:** The function returns a tuple `(head_and_body, "")` where the second element is always an empty string.
**Suggestion:** Return just `head_and_body` as a plain string, and update the caller (`shell = extract_h5_shell()` instead of `shell, _ = extract_h5_shell()`).
---
### `build_top200_v2_h5.py:105–158` — `CLEANUP` — Fragile template text replacement
**Summary:** The function performs 10+ sequential `.replace()` calls against exact HTML markup in `skill-market-h5.html`. If the template is ever reformatted or tweaked (whitespace changes, attribute reordering), these replacements silently no-op — the old strings remain in the output.
**Failure scenario:** Someone edits `skill-market-h5.html` (e.g., adds a newline inside a `<div>` or changes `class="sub"` to `class="subtitle"`). The build script produces output with stale V1 text labels instead of V2 labels, with no warning.
**Suggestion:** Consider one of:
- Extract translatable strings/labels into a JSON config that both the template and this script reference.
- Use regex or a small HTML parser (e.g., `html.parser`) to find elements by class or ID and replace text content only.
- At minimum, add a post-build assertion that checks the output for expected V2 strings.
---
### `build_top200_v2_h5.py:247` — `CLEANUP` — `esc()` + inline `onclick` bypasses HTML escaping in JS context
**Summary:** The `esc()` function escapes `'` to `&#39;`, but when interpolated into an inline `onclick` attribute:
```javascript
onclick="openDrawer('${esc(r.skill_id)}')"
```
the HTML parser decodes `&#39;` back to `'` **before** the JavaScript engine runs. If a `skill_id` contained a single quote (e.g., `it's_a_test`), the decoded JS would be:
```javascript
openDrawer('it's_a_test')
```
which is a syntax error — the string terminates at the second `'`.
**Failure scenario:** A skill_id containing `'` would break the card's click handler. Extremely unlikely given skill ID naming conventions (slugs like `namespace__skill-name`), but incorrect in principle.
**Suggestion:** Prefer event delegation — attach one click handler on the grid container and read `data-id` from the card:
```javascript
document.getElementById('grid').addEventListener('click', e => {
const card = e.target.closest('[data-id]');
if (card) openDrawer(card.dataset.id);
});
```
Same issue applies to line 268 (`onclick="copyText('${esc(r.copied_path || '')}', this)"`).
---
### `build_top200_v2_h5.py:176–182` — `CLEANUP` — `securityLabel()` fallback ordering is fragile
**Summary:** The function first checks exact keys in the `m` map, then falls back to `String(s).includes('passed')` before `String(s).includes('caution')`. If a new security value containing **both** "passed" and "caution" were introduced (e.g., `passed_with_caution_but_flagged`), it would match `includes('passed')` first and return `'通过'` instead of `'谨慎通过'`.
**Failure scenario:** A hypothetical new security status `passed_with_caution_but_flagged` would display as "通过" rather than "谨慎通过". In practice, all known values are explicitly mapped, so this only matters if new values appear at runtime without updating the code.
**Suggestion:** Check `caution` before `passed` in the fallback chain, since "caution" is a more specific qualifier:
```javascript
if (String(s).includes('caution')) return '谨慎通过';
if (String(s).includes('passed')) return '通过';
```
---
### `build_top200_v2_h5.py:233–237` — `CLEANUP` — Sort options unreachable via UI
**Summary:** The JS sort handler supports `rank`, `rank-desc`, `score`, `score-asc`, and `name` modes. But the template's `<select>` (after `extract_h5_shell()` replacements) only has options for `score` and `score-asc`. The `name` sort option and `rank-desc` are never exposed as user-choosable options. The default `state.sort = 'rank'` (line 172) works for initial load, but users can't switch to name or reverse-rank sorting.
**Suggestion:** Either add the missing `<option>` elements in `extract_h5_shell()`, or remove the unreachable sort cases from the `switch` statement.
---
### `build_top200_v2_h5.py:25–50` — `CLEANUP` — `load_category_zh_map()` silently degrades on missing files
**Summary:** If both CSV files (`platform-high-frequency-skills.csv` and `platform-high-frequency-groups.csv`) are absent, the function silently falls back to just the 3-entry `SUBGROUP_CATEGORY_ZH` dict and whatever the optional markdown filter provides. The output will have very few Chinese category names, but no warning is raised.
**Suggestion:** Log a warning when neither CSV is found, so the developer knows the Chinese mapping is incomplete.
---
### `build_top200_v2_h5.py:68–97` — `CLEANUP` — `transform_records()` copies fields verbatim without validation
**Summary:** The function copies fields from raw JSON to output dicts without any type casting or validation (except `protected` → `bool`). Fields like `weighted_score` and `selection_score` could be strings or numbers from the input, and the JS code on the consumer side has to handle both (e.g., `Number(r.weighted_score) || 0`). Consider normalizing numeric fields here in Python to reduce JS complexity.
**Suggestion:** Add type coercion for numeric fields in Python:
```python
"weighted_score": _to_float(row.get("weighted_score")),
"selection_score": _to_float(row.get("selection_score")),
"rank": _to_int(row.get("rank")),
```
---
## Summary
- **0** blocker findings
- **0** correctness bugs
- **6** cleanup/simplification opportunities
- **Decision:** Ready to merge — no blockers or bugs found. The cleanup items (especially the fragile template replacement and the `onclick` escaping) are worth tracking but not blocking.