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

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

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

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

Fallback 场景

| 异常情况 | 处理方式 | |----------|----------| | 用户没有 Git 环境 | Phase 5 跳过，提醒用户手动复制文件 | | 作者信息完全缺失 | Phase 3 使用占位符 [your-homepage]，在 README 末尾注释提醒用户填写 | | Playwright 截图失败 | 检查 Chromium 路径 → 尝试 npx playwright install chromium → 仍失败则跳过信息图，Phase 3 保留 ![Banner](assets/banner.png) 占位（后续可手动替换） | | 用户只想要文字版（无信息图） | 跳过 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 so

readme-generator

Como adicionar

Cole no README do seu repo

Skills relacionadas

xlsx

how-it-works

weekly-digests

mem-search

Receba novas skills de Dados e Análise toda segunda