readme-craft

把项目本身作为主要信源，再借 AGENTS.md / CLAUDE.md 补一层"作者意图"，输出一份一眼看上去"专业、像人写的、规范"的 README.md。

设计原则（贯穿整个 procedure）

风格基线：像一份好的开源项目 README，不是像一篇论文或营销页。

Inputs to collect

按需读取，不需要全部问用户：

• 项目路径：默认当前工作目录
• 项目类型：library / cli / web-app / api / tutorial / other
  • 优先从 manifest 自动推断（见 Step 1），推断不出再问
• 目标语言：multi-select，English 必选且默认勾选（详见 Step 1.5）
  • 跳过询问的情形：用户明确说"不要问"、给具体语言列表、或选已有的 README 文件作为唯一源
• 是否覆盖已有 README：默认备份后全量重写（README.md.bak）
  • 用户明确说"增量"才做局部更新
• README banner：默认自动生成，不问（能力检测与降级见 Step 4.5）
  • 用户说"不要 banner"、或现有 README 已引用可用的 banner / logo 图时跳过

Procedure

Step 1 — 扫描项目结构

读取根目录列表和关键 manifest，确定 name、version、description、scripts、dependencies、license。

这是必做步骤——不读 manifest 就在 README 里写技术栈，几乎一定会猜错。

顺带收集 git 元信息（只读命令，不做任何修改）：

git rev-parse --is-inside-work-tree   # 是否 git 仓库（命令失败再退回检查 .git 目录是否存在）
git describe --tags --abbrev=0        # 最新 tag（没有任何 tag 时非零退出）
git remote get-url origin             # remote URL，从中提取 <user>/<repo>

• <user>/<repo> 是后续所有 GitHub 徽章和链接的原料：git@github.com:user/repo.git 和 https://github.com/user/repo.git 都取 user/repo；其余 host（GitLab、自建等）记为"非 GitHub"
• 这三项结果在 Step 1.6（tag 检查）和 Step 5（徽章行）都会用到

Step 1.5 — 选择 README 语言（默认必走）

用 ask_user 工具多选询问（环境没有该工具时，直接在回复里列出选项问一次），默认行为。默认路径下 English 必选（用户要求"默认英文为主 README"）；用户已明确指定语言的按下方结果处理第 3 条，不强制。

question: "需要生成哪些语言的 README？"
selectionMode: multiple
options:
  - English（必选，作主 README）     # 默认勾选，id: en
  - 简体中文（zh-CN）                  # id: zh-CN
  - 日本語（ja）                       # id: ja
  - 한국어（ko）                       # id: ko
# 用户可通过 "Others..." 自由输入 BCP-47 标签：zh-TW、fr、de、es、pt-BR 等

结果处理：

1. 把 Others 里用户输入的字符串也归一为 BCP-47（中文 → zh-CN、英文 → en 等）
2. 默认路径（用户没明确语言偏好，走多选询问）：langs 保证 English 排第一（用户没勾选也强制加入）
3. 用户明确指定语言时完全按用户说的来：说"只要中文"就只生成中文，说"把 README 改成中文"就保持中文为主 README——不强制加 English（强制规则只适用于默认路径，覆盖用户明确意愿是错误行为）
4. 第一个元素对应 README.md，其他元素对应 README.<bcp47>.md
5. 如果用户主动说"不要问"、"按英文来"、"按上次的选择"，跳过本步直接用上次 / 默认值

注意：主 README（第一个语言）承担"完整版"角色，其他语言版本可以稍精简——但所有版本都要可独立阅读，内容不能靠"见 README.md"这类跨语言引用兜底（末尾导航性的"其他语言"清单除外，见 references/i18n.md §6）。

Step 1.6 — git tag 检查（无 tag 时询问）

依据 Step 1 的 git 检测结果分支：

询问（优先用 ask_user 工具，环境没有该工具时在回复里列出选项问一次）：

question: "项目还没有 git tag，要创建一个吗？（有了 tag，version 徽章和 Releases 页才有内容）"
options:
  - 创建 tag（推荐）
  - 跳过

• 创建：tag 名建议 v<Step 1 读到的 manifest version>（如 v1.2.3）；manifest 没有 version 字段就让用户输入版本号。执行：

  git tag -a v1.2.3 -m "Release v1.2.3"

  绝不自动 push——只创建本地 tag，在 Step 7 报告里提醒用户推送命令

• 跳过：version 徽章走 Step 5 的降级路径，不追问

Step 2 — 读取 AI 上下文（可选，但强烈建议）

如果根目录存在下列任一文件，先读再写：

• AGENTS.md / CLAUDE.md（agents.md 规范）
• .cursorrules / CONVENTIONS.md / STYLE.md
• .github/copilot-instructions.md

从这些文件提取：

• 项目目标、目标用户、核心价值主张
• 作者倾向的措辞风格（正式/轻松/极简）
• 是否有特别强调的章节（如性能、安全、兼容性）

注意：这些是给 AI 看的指令文件，不要原样照抄进 README。把"事实"提取出来，用"人类能读懂的话"重写。涉及密钥、token、内部约定等敏感或非公开信息，必须丢弃。

Step 3 — 检测部署 / 运行方式

按以下顺序探测，每命中一个就记录：

Step 4 — 决定模板风格

根据 Step 1 推断的项目类型选骨架（详见 references/templates.md）：

选错模板类型是最常见的失败原因——把 CLI 的 README 写成 web-app 风格会导致全篇违和。

Step 4.5 — README banner（能力检测，默认生成）

判断环境有没有"生图办法"，按能力阶梯取第一条命中的路径：

默认走 A，且不问用户——写 SVG 的成本等于写一段代码，用户不要 banner 会明确说。B 只在用户主动要求位图 / 复杂视觉时才用；环境有生图工具但用户没提，仍走 A，报告里提一句"可以用生图工具重出位图风格"。

输入全部复用前序步骤，不新增提问：

• 项目名 ← Step 1 manifest 的 name
• 技术栈标签 ← Step 1 dependencies 里最核心的 2-4 个
• 风格 ← Step 4 项目类型映射（library / CLI → 暗色科技；web-app → 渐变彩色；tutorial / docs → 极简白底）
• 布局、配色、GitHub 渲染硬约束、生成流程 → 按 references/banner.md 执行

产物：<project-root>/assets/banner.svg，嵌入方式（供 Step 5 第 1 个 section 使用）：

<div align="center">
  <img src="./assets/banner.svg" alt="{{PROJECT_NAME}}" width="100%">
</div>

多语言注意：所有语言版本共用一张 banner，图内文字保持语言中立（项目名 + 技术栈），tagline 不进图——tagline 归各语言版本的文字层（单语言项目可以进）。

banner 属于锦上添花：任何一步失败（推不出项目名、SVG 超重、用户反悔）都直接跳过或降级，不阻塞 README 主流程。

Step 5 — 撰写 README

按 Best-README-Template 的标准化结构产出。每个 section 的具体写法见 references/templates.md；每条 GFM 语法的规则、陷阱、最佳实践见 references/gfm-syntax.md；反 AI 味硬规则（破折号节制、标题禁 emoji、Features 不用 inline-header 列表、AI 高频词替换表）见 references/humanizer-rules.md。三份文件按需回查，本节只规定通用规则和顺序。

必须按顺序包含的 section（缺一个都不算合格）：

1. Banner（如有）+ Title + Tagline（居中，HTML <div align="center"> 包裹）
   • Step 4.5 生成了 banner：<img> 放最顶，# 项目名 的 H1 仍要保留——SVG 内文字读屏读不到，社交预览和目录锚点也靠这个标题；没有 banner 时按 logo / 纯标题原样
2. Shields 徽章行（build / version / license / stars，按实际能填的填，不可获得的不要写）
3. Table of Contents（<details> 折叠；全文 < 200 行可省略，与 Step 6 自检口径一致）
4. About / 项目简介（2-3 句，"这是啥、给谁用、解决啥问题"）
5. Getting Started（Prerequisites + Installation + 第一次 Run）
6. Usage（最小可运行示例）
7. License
8. 底部 reference-style 引用区（所有 shields、logo、社交链接的 [name]: url 定义）

按项目类型从以下池子里挑（不要全要，按需裁剪）：

• Features / Screenshots / Demo / Built With / Tech Stack
• Architecture（复杂项目才写）
• API / Commands / Endpoints（按类型）
• Configuration / Environment Variables（用表格）
• Tests / Deployment / Roadmap
• Contributing / Contact / Authors / Acknowledgments
• FAQ（高频踩坑才写）

每个 section 都要：

• 标准化：标题层级一致（# 一次、## 大节、### 子节）；小节顺序一致
• 人性化：用第二人称或读者视角开头；保留项目个性；不要"leveraging cutting-edge paradigm"
• 多样化：可选 section 按项目实际挑，避免 10 份 README 长一个样
• 规范：GFM 兼容、代码块带语言、表格列对齐、所有链接有效

back-to-top 链接只加在"长"大节末尾，不是每节都加（逐节都挂是视觉噪音，实测反馈）：

<p align="right">(<a href="#readme-top">back to top</a>)</p>

• 加：## 大节一屏放不下时——正文 ≥ 15 行、含多个 ### 子节、或有大表格 / 长代码块，读者才真需要一键回顶部
• 不加：
  • License / Contact / Authors / Contributing / Acknowledgments 这类收尾小节——离文档底部只有几行
  • 连续的短节——宁可整组都没有，也不要每节一个
  • 文档末尾（最后一节 / 底部引用区之后）——不要再补一个居中的 back-to-top
• 拿不准就不加：少一个没人察觉，多一个就是噪音

Alerts 规范（GFM）：

> [!NOTE]
> 提示信息

> [!TIP]
> 技巧

> [!IMPORTANT]
> 重要

> [!WARNING]
> 警告

> [!CAUTION]
> 严重警告

按实际需要选用，不要无脑堆 5 个。

折叠区（长内容用 <details>）：

<details>
<summary>点击展开</summary>

内容……
</details>

徽章（只列有真实来源的；shields.io 格式）：

[![Contributors][contributors-shield]][contributors-url]
[![License][license-shield]][license-url]
[![Version][version-shield]][version-url]

底部统一：

[contributors-shield]: https://img.shields.io/github/contributors/<user>/<repo>.svg?style=for-the-badge
[contributors-url]: https://github.com/<user>/<repo>/graphs/contributors

version 徽章取值判定（按顺序命中第一个就停，来源：Step 1 的 git 检测 + Step 1.6）：

1. GitHub 仓库且有 tag → 动态徽章，发布新版本后自动更新，不会过期：

   [version-shield]: https://img.shields.io/github/v/release/<user>/<repo>.svg?style=for-the-badge
   [version-url]: https://github.com/<user>/<repo>/releases

2. 非 GitHub 托管、用户跳过创建 tag、或无 tag 但 manifest 有 version → 静态徽章（值写死在 URL 里，注意发布新版本后要手动更新）：

   [version-shield]: https://img.shields.io/badge/version-1.2.3-blue?style=for-the-badge

3. 两者都不可得 → 不写 version 徽章

Step 6 — 自检

写完后过一遍：

• 没有 [example](example.com) / YOUR-USERNAME / TBD / 待补充 这类占位符残留
• 章节顺序符合 Step 5 的"必须包含"列表
• 所有徽章 URL 指向真实资源（不可获得的删掉或留 TODO 注释）
• 代码块都有语言标识（```bash / ```ts / ```python 等）
• 表格列对齐、列数一致
• 文档 > 200 行时，TOC 存在
• back-to-top 没有逐节堆：只在大节末尾，License / Authors / Contact 等收尾小节和文档末尾都没有
• 没有任何空 section（"## License" 后面必须有内容）
• 中英混排时两边都通顺
• 有 banner 时：文件真实存在于 assets/、README 引用路径正确、<title> 不是空话

Step 7 — 写入并报告

按 langs 顺序循环写入每个语言版本：

1. 第一个语言（默认是 English，见 Step 1.5；用户明确指定唯一语言时按用户要求）→ 写入 <project-root>/README.md
2. 后续每个语言 → 写入 <project-root>/README.<bcp47>.md（如 README.zh-CN.md、README.ja.md）
3. 已有同名文件 → 先备份为 <file>.bak 再覆盖；若 .bak 已存在，改用带时间戳的 <file>.<YYYYMMDD-HHMMSS>.bak，绝不覆盖旧备份（更早的备份才是用户的原始文件）
4. 输出报告：已生成 N 份 README（语言: en, zh-CN, ja），主 README: README.md（M 行）；生成过 banner 追加：banner: assets/banner.svg（X KB，路径 A）；Step 1.6 创建过 tag 时追加一句：已创建本地 tag v1.2.3（未推送，推送请执行 git push origin v1.2.3）

翻译原则（多语言版本必须遵守，详见 references/i18n.md）：

• ✅ 翻译：所有自然语言段落、bullet、Alert 文字、表格描述、代码注释
• ⚠️ 章节标题：默认不翻译标题 key（i18n.md §4 方案 A，如中英版都用 ## Features）；用户明确要求"完全本地化观感"时才整篇翻译标题（方案 B）
• ❌ 不翻译：shields 徽章 URL、Markdown 链接、命令/路径/文件名、ASCII 树、技术术语、banner 图（所有语言共用一张，图内文字语言中立）
• ⚠️ 代码块内的注释视上下文可翻译，但标识符本身绝对不翻译

Output contract

• 写入 <project-root>/README.md（主 README，第一个语言）+ <project-root>/README.<bcp47>.md ×（N-1）
• 文档长度 200–600 行/语言（视项目复杂度）
• 包含 Best-README-Template 风格：徽章、TOC、back-to-top（只在大节末尾，不逐节堆）、底部引用区
• banner：默认生成 assets/banner.svg 并在主 README 顶部引用；跳过时在报告里说明原因（无名字来源 / 用户拒绝 / 已有现成图）
• 每个 section 都有实际内容；不允许出现"待补充"、"TBD"、占位用户名
• 遵循 GFM 规范（表格、代码块、Alerts、折叠、diff 都能正确渲染）
• 多语言版本结构对齐（章节顺序、section 标题一致），便于读者对照

Failure handling

Examples

输入：当前目录有 package.json（name: vuepress-plugin-xxx，description: "VuePress 主题增强插件"），有 AGENTS.md 描述作者风格偏好（"用第二人称、轻松点"）

操作：扫描 → 读 AGENTS.md 提取风格 → 推断类型 library → Step 1.5 多选询问（用户选 en + zh-CN）→ 选 library 模板 → 撰写英文版 → 翻译成中文版

输出：./README.md（英文，主）+ ./README.zh-CN.md（中文），library 模板，5 个 shields、9 个核心 section，结构对齐，附带 assets/banner.svg（暗色科技风，两个语言版共用）

输入：用户说"把我的项目 README 改成中文，语气轻松点"

操作：读现有 README → 备份 → 按中文 + 轻松风格重写正文，结构保留

输出：同结构，风格改造

输入：用户说"生成中英日三个 README"

操作：跳过 Step 1.5 多选（用户已经指定）→ 撰写三种语言版本 → 写入 README.md（en）+ README.zh-CN.md + README.ja.md

输入：用户说"写个 README，banner 不要自动生成"

操作：其余流程不变，Step 4.5 直接跳过，顶部按纯标题 + tagline 排

输出：README.md，无 banner 文件、顶部无 <img>

与相邻 skill 的边界

Windows (win32) platform notes

流程型 skill：扫描文件、读 manifest、写 README 全用 Read / Write / Glob / Grep 工具。shell 仅用于 git：Step 1 的只读检测（rev-parse / describe / remote）和 Step 1.6 经用户确认的 git tag 创建——命令本身跨平台，Git Bash / PowerShell 通用，无需适配。banner 的 A 路径（手写 SVG）同样只用 Write 写文本文件，无平台差异；可选的 npx svgo 压缩和 B 路径的生图工具属于外部能力，不可用时按 Step 4.5 降级跳过。