commit 2a1ff652c6bfdcdd39faa2173350ff127b09666f Author: wehub-skill-sync Date: Mon Jul 13 21:36:38 2026 +0800 chore: import zh skill guide-recap diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..49d0d0e --- /dev/null +++ b/README.wehub.md @@ -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 清单整理 +- 原作者、版权和许可证信息以上游仓库为准 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..aa3a04f --- /dev/null +++ b/SKILL.md @@ -0,0 +1,219 @@ +--- +name: guide-recap +description: 将 CHANGELOG 条目转换为社交平台内容（LinkedIn、Twitter/X、Newsletter、Slack），支持法语和英语。在发布后或每周使用，从指南更新中生成可直接发布的内容。 +argument-hint: " [--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 忽略 +- 发布前请检查并个性化调整（这些是草稿，非最终文案） diff --git a/assets/linkedin-template.md b/assets/linkedin-template.md new file mode 100644 index 0000000..404a862 --- /dev/null +++ b/assets/linkedin-template.md @@ -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） +- 法语：使用敬语「您」 +- 英语：美式英语 diff --git a/assets/newsletter-template.md b/assets/newsletter-template.md new file mode 100644 index 0000000..b47c075 --- /dev/null +++ b/assets/newsletter-template.md @@ -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） +- 注明所有提及的来源 diff --git a/assets/slack-template.md b/assets/slack-template.md new file mode 100644 index 0000000..88e9c5b --- /dev/null +++ b/assets/slack-template.md @@ -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:` 代码 diff --git a/assets/twitter-template.md b/assets/twitter-template.md new file mode 100644 index 0000000..268e887 --- /dev/null +++ b/assets/twitter-template.md @@ -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 条以上） diff --git a/examples/version-output.md b/examples/version-output.md new file mode 100644 index 0000000..e825330 --- /dev/null +++ b/examples/version-output.md @@ -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 +``` diff --git a/examples/week-output.md b/examples/week-output.md new file mode 100644 index 0000000..44aa0b3 --- /dev/null +++ b/examples/week-output.md @@ -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 diff --git a/references/changelog-parsing-rules.md b/references/changelog-parsing-rules.md new file mode 100644 index 0000000..8a290b5 --- /dev/null +++ b/references/changelog-parsing-rules.md @@ -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. 标题中使用日期范围，不使用具体版本号 diff --git a/references/content-transformation.md b/references/content-transformation.md new file mode 100644 index 0000000..5898c2e --- /dev/null +++ b/references/content-transformation.md @@ -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" +``` diff --git a/references/tone-guidelines.md b/references/tone-guidelines.md new file mode 100644 index 0000000..67bf89f --- /dev/null +++ b/references/tone-guidelines.md @@ -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 `
` 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 `'`, but when interpolated into an inline `onclick` attribute: + +```javascript +onclick="openDrawer('${esc(r.skill_id)}')" +``` + +the HTML parser decodes `'` 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 `