GitHub README Maker

零 ASCII 艺术 · 零 Emoji 堆砌 · 排版驱动设计 · 信息图精准插入

从第一性原理出发：README 是项目的门面，是 Google 和 AI 搜索的入口，是开发者决定是否 star/fork 的第一印象。一个好的 README 需要在 15 秒内传达三件事：这是什么、能解决什么问题、怎么用。

---

设计哲学

反模式（绝对避免）：

• ❌ 用 ASCII 艺术字幕开头（╔══╗ ◇ Project ◇ ╚══╝）
• ❌ 第一行就是图片（SEO 不友好，爬虫读不到）
• ❌ Emoji 装饰标题（## 🚀 功能——降低专业度）
• ❌ 大段文字没有信息图辅助（阅读疲劳）
• ❌ 缺少 GitHub Topics 和 Description（SEO 失分）

正确模式：

• # 项目名 H1 + blockquote 标语 → 立即建立认知
• Badge 行 → 信息密度高，一眼扫描状态
• 16:9 Banner 信息图 → 视觉冲击，替代 ASCII
• Features 信息图 + Workflow 信息图 → 核心价值可视化
• 结构化作者区块 → 表格形式，统一风格

零 Emoji 原则（README 及信息图均适用）：

• README 中不用 emoji 装饰标题或作者表格（:octocat: :globe_with_meridians: 等 shortcode 同样禁止）
• 信息图 HTML 中不用 emoji 作为图标——改用编号（01 02）、SVG 图形或几何色块
• 检查点提示文字中不用 ✅ 📋 ⚙️ 等符号，改用纯文字说明

---

总体流程

Phase 0    环境检查 (Node.js + Playwright)
Phase 0.5  模式识别 (新建 vs 升级)
Phase 1    项目信息采集 (6 个关键字段)
Phase 1.5  设计风格选择 (npx getdesign list → 提取 Token，默认 claude)
Phase 2    信息图生成 (3 张 HTML → PNG，应用风格 Token)
Phase 3    README 组装 (8 个标准区块)
Phase 4    GitHub 元信息建议 (description + topics)
Phase 5    Git 提交 (可选，用户确认后)

---

Phase 0: 环境检查

在开始前验证：

node --version   # 要求 >= 18

检查 package.json：

ls package.json 2>/dev/null || npm init -y

检查 Playwright：

node -e "require('playwright')" 2>/dev/null && echo "OK" || (npm install playwright && npx playwright install chromium)

为什么需要 Playwright？ 信息图以 HTML 方式编写后通过 Playwright 截图为 PNG，这是在没有设计工具的情况下生成高质量信息图的最佳实践。详见 scripts/gen_infographic.mjs。

---

Phase 0.5: 模式识别

在采集信息前，先判断这是哪种场景——新建还是升级，后续流程会有所不同。

判断规则

场景	判断条件	进入流程
全新创建	用户没有提到现有文件，或目录内无 README.md	Phase 1 → 2 → 3 → 4 → 5（完整流程）
升级现有	用户说「我已有 README」「帮我优化/重构」，或当前目录存在 README.md	先读取现有文件，再执行 Phase 1 → 2 → 3（差量更新）→ 4 → 5

升级现有 README 的差量策略

当识别为「升级」场景时：

1. 读取现有 README，提取已有内容（项目名、描述、安装方式等）
2. 诊断缺失项，重点检查：
   • 是否缺少 Banner/Features/Workflow 信息图？→ Phase 2 补充生成
   • H1 标题是否以 ASCII 艺术或图片开头？→ Phase 3 重构开头
   • 是否缺少作者区块？→ Phase 3 补充
   • 是否缺少 GitHub 元信息建议？→ Phase 4 补充
3. 保留用户已有的独特内容（如详细的 API 文档、贡献指南），不要因为升级而删除

升级时告诉用户：「我已读取你的现有 README，会保留原有内容并补充/重构以下部分：[列出差异]」，等用户确认后再继续。

Fallback 场景

异常情况	处理方式
用户没有 Git 环境	Phase 5 跳过，提醒用户手动复制文件
作者信息完全缺失	Phase 3 使用占位符 [your-homepage]，在 README 末尾注释提醒用户填写
Playwright 截图失败	检查 Chromium 路径 → 尝试 npx playwright install chromium → 仍失败则跳过信息图，Phase 3 保留  占位（后续可手动替换）
用户只想要文字版（无信息图）	跳过 Phase 2，Phase 3 中信息图位置改为简洁的功能列表

---

Phase 1: 项目信息采集

向用户询问（或从上下文推断）以下 6 个字段：

字段	示例	说明
project_name	Travel Guidebook	项目名，首字母大写
tagline	从调研到成书的一站式旅行路书引擎	一句话价值主张，≤ 30 字
problem	用 AI 自动生成精排旅行 PDF，替代手动整理攻略	解决什么问题
features	并行调研 / 高德地图 MCP / Playwright PDF 导出	核心功能，3-6 条
tech_stack	Node.js / Playwright / Claude Code	主要技术栈
author	见下方作者结构	个人主页/GitHub/Twitter/公众号

作者信息结构：

author:
  homepage: https://example.dev
  github: username
  twitter: @handle
  wechat: 公众号名称（可选）

如果用户已在上下文中提供了这些信息，无需重复询问，直接推断并确认。

---

Phase 1.5: 设计风格选择

使用 getdesign 工具从 60+ 大厂设计规范中选择风格，生成的信息图将自动应用对应的色彩和排版系统。

Step 1：列出可用风格

npx getdesign list

如果 npx getdesign list 执行失败（命令不存在、网络超时、npm registry 不可达）：跳过 Step 1-3，直接使用下方「claude 风格默认 Token」进入 Step 4。告知用户：「getdesign 工具暂不可用，将使用默认 claude 风格继续。」

展示完整列表后，向用户提示：

以上是 60+ 可用的大厂设计风格。

默认风格：claude — Anthropic's AI assistant. Warm terracotta accent, clean editorial layout.

请选择一种风格（直接回车使用默认 claude）：

Step 2：下载风格文件

用户选择后（或按回车使用默认），执行：

# 将风格下载到临时目录，不污染项目目录
mkdir -p /tmp/getdesign-<style>
cd /tmp/getdesign-<style>
npx getdesign add <style>
# 生成 /tmp/getdesign-<style>/DESIGN.md

如果用户选择 claude（默认）：

mkdir -p /tmp/getdesign-claude && cd /tmp/getdesign-claude && npx getdesign add claude

Step 3：从 DESIGN.md 提取设计 Token

读取 /tmp/getdesign-<style>/DESIGN.md，按以下规则提取 token：

Token	提取位置	映射到模板变量
主色（Accent）	Section 2 "Primary" 中第一个品牌强调色	{{PRIMARY_COLOR}}
背景色	Section 2 "Surface & Background" page background	模板 background-color / {{BG_COLOR}}
标题字体	Section 3 "Font Family" Headline 字体（无法加载自定义字体时用 fallback）	模板 font-family
暗色文字	Section 2 "Neutrals & Text" 最深的文字色	模板 color 主文字

claude 风格默认 Token（用户不选 / getdesign 不可用时直接使用）：

Token	值	说明
{{PRIMARY_COLOR}}	#c96442	Terracotta Brand — 暖赤陶橙
背景色	#f5f4ed	Parchment — 羊皮纸暖白
标题字体	Georgia, serif	Anthropic Serif 的 fallback
主文字色	#141413	Anthropic Near Black — 暖黑

提取失败时的 fallback： 在 DESIGN.md 的 Key Characteristics 列表中找第一个 hex 颜色值，作为 {{PRIMARY_COLOR}}。背景色默认 #0d1117（GitHub 深色），字体默认 Inter。

Step 4：更新总体流程中的变量声明

将提取到的 Token 记录为本次生成的变量，供 Phase 2 使用：

PRIMARY_COLOR = <从DESIGN.md提取>
BG_COLOR      = <从DESIGN.md提取>
HEADING_FONT  = <从DESIGN.md提取>
TEXT_COLOR    = <从DESIGN.md提取>
STYLE_NAME    = <用户选择的风格名>

---

Phase 2: 信息图生成（核心）

生成 3 张 16:9 HTML 信息图，截图引擎使用 scripts/gen_infographic.mjs。

生成流程（每张图）

Step 1：从 templates/ 读取模板，替换占位符，写入 /tmp/

templates/ 目录下有三个基础模板，包含 {{PROJECT_NAME}}、{{PRIMARY_COLOR}}、{{TAGLINE}} 等占位符。操作方式：

# 读取 templates/banner.html 内容后，将以下占位符替换为实际值，写入 /tmp/
# {{PROJECT_NAME}}     → 实际项目名（如 "codeflow"）
# {{TAGLINE}}          → 一句话标语
# {{PRIMARY_COLOR}}    → 主色 hex（如 "#0ea5e9"）
# {{CATEGORY}}         → 项目类别（如 "CLI Tool" / "Agent Skill"）
# {{PLATFORM}}         → 运行平台（如 "Node.js" / "Python"）
# {{LANGUAGE}}         → 主要语言（如 "TypeScript"）
# {{VERSION_INFO}}     → 版本信息（如 "v1.0 · 2026"）
# {{TECH_CARDS}}       → banner 右侧技术卡片（见下方 HTML 结构）
# {{FEATURE_CARDS}}    → features 功能卡片（见下方 HTML 结构）
# {{FEATURE_COUNT}}    → 功能数量数字（如 "6"）
# {{PIPELINE_STAGES}}  → workflow 流程阶段（见下方 HTML 结构）
# {{STAGE_COUNT}}      → 阶段数量（如 "5"）

卡片 HTML 结构参考（从 templates/ 提取，直接复制并填入内容）：

{{TECH_CARDS}}（banner.html 右侧，每条技术一个）：

<div class="tech-card">
  <div class="tech-icon">01</div>
  <div class="tech-info">
    <div class="tech-name">Node.js</div>
    <div class="tech-desc">Runtime environment</div>
  </div>
</div>
<!-- 重复 .tech-card，编号递增：02, 03... 建议 3-5 条 -->

{{FEATURE_CARDS}}（features.html 网格，每个功能一个，需设置 --accent）：

<div class="card" style="--accent: {{PRIMARY_COLOR}}">
  <div class="card-icon">01</div>
  <div class="card-tag">Core</div>
  <div class="card-title">并行调研</div>
  <div class="card-desc">多个 Agent 同时搜索，汇总后去重排序</div>
</div>
<!-- 重复 .card，编号递增，card-tag 可选：Core / Integration / Output 等 -->

{{PIPELINE_STAGES}}（workflow.html 流水线，.stage 和 .arrow 交替）：

<div class="stage">
  <div class="stage-num">STEP 01</div>
  <div class="stage-title">信息采集</div>
  <ul class="stage-items">
    <li>读取项目源码</li>
    <li>提取 package.json</li>
  </ul>
  <span class="stage-badge">Input</span>
</div>
<div class="arrow"></div>
<!-- 重复 .stage + .arrow，最后一个 .stage 后不加 .arrow -->

Step 2：截图

node scripts/gen_infographic.mjs /tmp/readme-banner.html assets/banner.png 1920 1080
node scripts/gen_infographic.mjs /tmp/readme-features.html assets/features.png 1920 1080
node scripts/gen_infographic.mjs /tmp/readme-workflow.html assets/workflow.png 1920 1080

Step 3：清理临时文件

rm /tmp/readme-banner.html /tmp/readme-features.html /tmp/readme-workflow.html

⚠️ 关键： HTML 临时文件只写 /tmp/，截图 PNG 保存到 assets/。不要把 HTML 提交到 git（.gitignore 已包含 *.html 排除规则）。

主色选择指南

优先使用 Phase 1.5 提取的 PRIMARY_COLOR。如果用户跳过了风格选择，则按下表根据项目性质手动选择：

项目类型	推荐主色	Hex
开发工具 / CLI	科技蓝	#0ea5e9
AI / Agent	紫色	#a78bfa
出行 / 生活	琥珀金	#f59e0b
效率 / 自动化	翠绿	#10b981
设计 / 创意	玫瑰	#f43f5e
数据 / 分析	青色	#06b6d4

设计系统（保持一致）

参考 references/design-system.md，默认采用：

• 背景色：#0d1117（GitHub 深色）
• 字体：Inter（西文）+ Noto Sans SC（中文），均通过 Google Fonts CDN 加载
• 圆角：12px，卡片边框：1px solid #21262d

三张图的主色 {{PRIMARY_COLOR}} 必须填写相同的值——视觉一致性是专业度的核心。

Phase 2 检查点（生成后必须暂停）

三张 PNG 生成完毕后，向用户汇报：

信息图生成完成：
  - assets/banner.png   (1920×1080, ~500KB)
  - assets/features.png (1920×1080, ~120KB)
  - assets/workflow.png (1920×1080, ~100KB)

请在你的文件管理器中预览这三张图，确认：
1. 项目名/标语是否正确？
2. 配色是否符合项目风格？
3. 功能卡片的描述是否准确？

确认后输入「继续」进入 README 组装。如需调整，告诉我哪里需要修改。

不要在用户确认之前进入 Phase 3。

---

Phase 3: README 组装

标准结构（8 个区块，顺序不可随意调换）

<div align="center">

# 项目名

**一句话标语**

<img src="assets/banner.png" alt="[项目名] — [功能描述]" width="100%">

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![...其他 badge...]

</div>

---

## 这是什么

[2-3 句话，说清楚：这是什么、解决什么问题、最大亮点]

输入：[示例输入] 输出：[示例输出]

---

## 核心特性

<img src="assets/features.png" alt="[alt 文本]" width="100%">

[可选：补充 1-2 条文字说明]

---

## 工作流程

<img src="assets/workflow.png" alt="[alt 文本]" width="100%">

---

## 安装

[依赖 + 安装命令]

---

## 快速上手

[最简示例，让用户 5 分钟内跑起来]

---

## 许可证

[MIT](./LICENSE) — 自由使用、修改、分发。

---

## 关于作者

| | |
|:---|:---|
| 个人主页 | [domain.dev](https://domain.dev) |
| GitHub | [username](https://github.com/username) |
| Twitter | [@handle](https://x.com/handle) |
| 公众号 | 微信搜「公众号名」 |

区块规则

1. H1 必须在 <div align="center"> 内，但 H2 及以下在外面（便于 anchor 链接）
2. Banner 紧跟 H1，不超过 3 行文字就出现图
3. Badge 行放在 banner 下方，不超过 5 个（保持整洁）
4. Features 和 Workflow 用纯图片，不需要再重复文字列表
5. 关于作者用表格，不用列表，不用 blockquote
6. 最后一定有许可证，默认 MIT

---

Phase 4: GitHub 元信息建议

Repository Description（≤ 160 字符）

格式：[一句话功能] — [核心技术关键词]

示例：

AI Agent Skill for generating beautifully typeset travel guidebook PDFs with parallel research and Playwright export

规则：

• 英文优先（GitHub 国际受众）
• 包含 2-3 个核心技术关键词（供搜索引擎索引）
• 不用 emoji，不用感叹号
• 说「做什么」不说「很厉害」

Topics（7-10 个）

推荐策略：

1. 技术类（语言/框架）：如 nodejs, typescript, react
2. 领域类（应用场景）：如 travel, pdf-generation, ai-agent
3. 工具类（用到的工具）：如 playwright, claude, mcp
4. 受众类（目标用户）：如 developer-tools, automation

示例（travel-guidebook）：

agent-skill  claude-code  travel  pdf-generation  playwright
nodejs  mcp  copilot-cli  ai-agent  itinerary

Phase 4 检查点（给出建议后暂停）

生成元信息建议后，向用户展示并等待确认：

GitHub 元信息建议（请在 repo Settings 中填写）：

Description:
  [生成的英文描述，≤160字符]

Topics（在 repo 主页点击齿轮图标添加）:
  [tag1]  [tag2]  [tag3]  ...

以上建议是否合适？如需调整描述或 Topics，直接告诉我。
确认后继续 → Git 提交（Phase 5）。

---

Phase 5: Git 提交（可选）

用户确认 README 满意后，询问是否初始化 git 并提交：

cd [项目目录]
git init
git add README.md assets/ LICENSE
git commit -m "docs: add README with infographics and author section

- Banner, features, workflow 三张 16:9 信息图
- SEO 优化标题和描述
- 结构化作者区块
- MIT 许可证"

提醒用户：将 HTML 模板文件加入 .gitignore（如 *.html 临时文件），只提交 PNG 截图结果。

---

常见问题处理

信息图字体不显示？ HTML 模板中使用了 Google Fonts CDN，需要联网。截图时 Playwright 会自动等待字体加载。如果断网，在 <style> 中换成系统字体：font-family: -apple-system, 'PingFang SC', sans-serif。

截图比例不对？ gen_infographic.mjs 的 --width 和 --height 参数控制视口大小。16:9 = 1920×1080（标准）或 1280×720（轻量）。

Playwright 找不到 Chromium？

npx playwright install chromium
# 或指定路径：
PLAYWRIGHT_BROWSERS_PATH=~/.cache/ms-playwright npx playwright install chromium

如何适配暗色/亮色主题？ 参见 references/design-system.md 的主题切换方案。Banner 默认深色背景，如项目风格偏向亮色（如教育类），可切换为 #fafafa 背景 + 深色文字。