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 的差量策略

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

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

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

Fallback 场景

Phase 1: 项目信息采集

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

作者信息结构：

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：

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

提取失败时的 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。如果用户跳过了风格选择，则按下表根据项目性质手动选择：

设计系统（保持一致）

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

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