README Writer - 项目文档生成器

📝 为本地项目或 GitHub 项目生成专业的 README.md 文档

采用交互式工作流程：自动收集信息 → 用户确认 → 生成目录 → 用户确认 → 生成 README → 迭代优化

---

🎯 何时使用（触发场景）

✅ 使用此技能当用户说：

场景	示例
本地项目	"为这个项目写 README：~/.openclaw/skills/my-project"
GitHub 项目

"给 https://github.com/user/repo 写 README" |
| Skill 项目 | "为 easy-image-generate 写 README" |
| 优化现有 | "优化这个项目的 README" |
| 指定风格 | "参考 skill-rembg 风格写 README" |

❌ 不使用此技能：

• - 代码审查 → 用代码分析工具
• 项目部署 → 用部署/CI/CD 工具
• 问题排查 → 用调试工具

---

🔄 交互式工作流程

完整流程（11 步）

1. 1. 用户输入（本地路径或 URL）
2. 自动收集项目信息
3. 展示信息，用户确认/修改
4. 询问 README 目的和风格偏好
5. 生成建议目录结构
6. 用户确认/调整目录
7. 💬 可选章节询问（致谢/贡献/更新日志）
8. 生成 README 草稿
9. 质量检查 + 用户反馈
10. 迭代优化（可多次）
11. 最终版本 + 备份

---

📊 第 1 步：项目信息收集

本地项目

自动读取：

• - package.json → 项目名称、描述、版本、脚本
• requirements.txt → Python 依赖
• pyproject.toml → Python 项目配置
• Cargo.toml → Rust 项目
• 主语言文件（.py/.js/.ts/.rs 等）
• 目录结构（scripts/ docs/ tests/）
• 现有 README（如有）

展示给用户确认：

📊 检测到项目信息：

基本信息：

• - 项目名称：[自动提取]
• 版本：[自动提取]
• 描述：[自动提取]
• 主要语言：[自动提取]

项目类型： [自动识别]

核心功能： [自动分析]

以上信息是否正确？需要补充或修改吗？

---

🎯 第 2 步：询问 README 目的

询问模板：

🎯 这个 README 的主要读者是谁？

A. 潜在用户 - 快速了解项目用途
B. 开发者 - 想要贡献代码
C. 两者兼顾（推荐）

📝 希望突出什么内容？

A. 快速上手 - 安装 + 使用示例
B. 功能特点 - 详细的功能列表
C. API 文档 - 技术细节
D. 项目背景 - 为什么创建这个项目

🎨 文档风格偏好？

A. 简洁专业 - 像 requests 库
B. 活泼友好 - 像 skill-rembg（emoji+ 双语）
C. 详细完整 - 像大型框架

---

📑 第 3 步：生成目录结构

根据项目类型和偏好生成建议目录结构，用户确认后再继续。

---

💬 第 3.5 步：可选章节询问

必须询问的章节：

📝 需要添加以下章节吗？

1️⃣ 致谢部分（🙏 Acknowledgements）

感谢贡献者、使用的工具或平台

请回复：

• - "有，致谢：OpenClaw、ClawHub"
• "没有，不需要"

2️⃣ 贡献指南（🤝 Contributing）

如何为项目贡献代码

请回复：

• - "需要，是开源项目"
• "不需要，个人项目"

3️⃣ 更新日志（📝 Changelog）

项目版本历史

请回复：

• - "需要，有多个版本"
• "不需要，初始版本"

规则：

• - ✅ 必须先询问，再生成
• ✅ 用户说"没有"就不生成该章节
• ✅ 用户说"有"就列出具体内容

---

✍️ 第 4 步：生成 README 草稿

生成规则

0. Badge 区域（项目简介后）

🎨 采用多行专业布局（丰富完整，用户可手动精简）：

CODEBLOCK0

💡 设计理念：

• - ✅ Badge 丰富完整 - 生成所有可能的 Badge，用户可手动删除不需要的
• ✅ URL 处理灵活 - 能确定的用实际链接，确定不了的用 Demo 占位符
• ✅ 无个人信息 - 所有 Demo 使用通用占位符（author、repo、skill-name）
• ✅ Windows 用 Base64 - 避免图片链接失效问题

---

📋 Badge 动态生成规则

Row 1: 核心信息 Badge（项目身份）

1. ClawHub Badge

• - 条件：检测到是 OpenClaw Skill（有 SKILL.md）
• 格式：INLINECODE4
• skill-name：从 SKILL.md 的 name 字段读取，转换为 kebab-case
• 链接：使用 Demo 占位符 INLINECODE6

2. GitHub Badge

• - 条件：用户提供了 GitHub URL 或检测到 .git 目录
• 格式：INLINECODE8
• author/repo：从 Git 远程仓库或 package.json 提取
• 链接：如无法提取，使用 Demo 占位符 INLINECODE9

3. Version Badge（必须生成）

• - 读取优先级：

1. package.json → version
2. pyproject.toml → version
3. Cargo.toml → version
4. pom.xml → version
5. composer.json → version
6. 默认：0.0.1

• - 格式：INLINECODE21
• 链接：使用项目主页或 Demo 占位符

---

Row 2: 包管理器 Badge（如已发布）

根据项目类型生成对应的包管理器 Badge：

项目类型	Badge	链接
npm 包	INLINECODE22	npmjs.com
Python 包

[![PyPI](https://img.shields.io/pypi/v/package-name?color=3776AB&logo=pypi)](https://pypi.org/project/package-name) | pypi.org |
| Ruby Gem | [![Gem](https://img.shields.io/gem/v/gem-name?color=E9563D&logo=ruby)](https://rubygems.org/gems/gem-name) | rubygems.org |
| Go Module | [![Go](https://img.shields.io/badge/go.mod-v1.20-00ADD8?logo=go)](https://pkg.go.dev/module/path) | pkg.go.dev |
| Maven | [![Maven](https://img.shields.io/maven-central/v/group/artifact?color=E43C3C&logo=apache-maven)](https://search.maven.org) | search.maven.org |

链接处理：如无法获取实际包名，使用 Demo 占位符

---

Row 3: 技术栈/语言版本 Badge

自动读取项目配置生成：

Node.js 项目（读取 package.json → engines.node）：
CODEBLOCK1

Python 项目（读取 pyproject.toml 或 setup.py → python_requires）：
CODEBLOCK2

Rust 项目（读取 Cargo.toml → edition）：
CODEBLOCK3

Go 项目（读取 go.mod → go 版本）：
CODEBLOCK4

PHP 项目（读取 composer.json → require.php）：
CODEBLOCK5

链接处理：使用官方文档链接或 Demo 占位符

---

Row 4: 平台 Badge（全部生成，用户可精简）

默认生成所有平台 Badge，用户可根据实际情况手动删除：

CODEBLOCK6

颜色规范：

• - macOS: #000000（黑）
• Windows: #0078D6（蓝）+ Base64 SVG Logo
• Linux: #FCC624（黄）
• Android: #3DDC84（绿）
• iOS: #000000（黑）
• Web: #4285F4（蓝）

链接处理：使用 Demo 占位符 https://openclaw.ai

---

Row 5: License Badge

读取优先级：

1. 1. package.json → INLINECODE46
2. INLINECODE47 → INLINECODE48
3. INLINECODE49 → INLINECODE50
4. INLINECODE51 / LICENSE.md / LICENSE.txt 文件名
5. 默认：INLINECODE54

License 颜色映射：

• - MIT: #BD2D2D（红）
• Apache-2.0: #D54D2D（橙红）
• GPL-3.0: #FF7A00（橙）
• BSD-3-Clause: #3B82F6（蓝）
• ISC: #10B981（绿）
• Unlicense: #6B7280（灰）
• 其他：#6B7280（灰）

格式：INLINECODE62

链接处理：指向 LICENSE 文件（如不存在，用户可手动修改）

---

✅ Badge 生成示例（完整版）

示例：Node.js 项目（完整 Badge 展示）

CODEBLOCK7

💡 提示用户：在 README 末尾添加说明：

> 💡 **Badge 说明**：以上 Badge 为自动生成，如与实际不符可手动删除或修改。

---

⚠️ Badge 生成规则总结

• - ✅ 必须使用 HTML 注释分行（<!-- Badge Row X: ... -->）
• ✅ Badge 丰富完整 - 生成所有可能的 Badge，用户可手动精简
• ✅ Version Badge 必须生成（无版本号时用 0.0.1）
• ✅ 平台 Badge 全部生成（macOS/Windows/Linux/Android/iOS/Web）
• ✅ Windows 使用 Base64 SVG Logo（避免图片链接失效）
• ✅ License Badge 根据实际 License 生成（无时默认 MIT）
• ✅ URL 灵活处理 - 能确定用实际链接，确定不了用 Demo 占位符
• ✅ 无个人信息 - 所有 Demo 使用通用占位符（author、repo、skill-name）
• ✅ 颜色统一（使用 shields.io 标准色）
• ✅ 放置位置：项目描述后，目录前

1. 中英双语规则

中文部分：

• - 完整的项目介绍
• 所有章节内容
• 所有代码示例

English Version：

• - ✅ 必须完整翻译所有章节
• ✅ 代码示例中的注释和输出要用英文
• ✅ 目录链接要对应英文锚点
• ✅ 内容长度和信息量与中文一致
• ✅ 英文部分必须有独立的 Table of Contents
• ✅ 英文 TOC 条目数量必须与中文一致

章节对应规则：

• - 中文使用 ## 标记主章节
• 英文使用 ### 标记主章节
• 英文 TOC 使用 INLINECODE70
• 中文代码块使用 `` 标记 - 英文代码块使用 ` 标记 #### 2. 代码块格式 **所有代码块使用 ` 标记** 格式： `语言 代码内容 CODEBLOCK9** #### 3. 可选章节 根据第 3.5 步的用户确认结果生成： - 致谢部分（如用户确认需要） - 贡献指南（如用户确认需要） - 更新日志（如用户确认需要） #### 4. 其他规则 - **Emoji 标记** - 适度使用，增强可读性 - **代码示例** - 至少 3 个实用示例 - **表格展示** - 参数、配置等用表格 - **质量检查** - 生成后自动检查 --- ## 🔄 第 5 步：迭代优化 支持多次迭代，根据用户反馈修改 README。 --- ## 📋 特殊场景处理 ### 场景 1：已有 README ⚠️ 检测到已有 README.md **选项：** A. 完全重写（覆盖现有） B. 基于现有优化（保留结构，改进内容） C. 生成新版本（README.new.md） ### 场景 2：多语言项目 🌍 检测到多语言项目 **建议：** A. 生成独立的 README_CN.md 和 README_EN.md B. 在主 README 中分章节（中文 | English） ### 场景 3：大型项目 📊 检测到大型项目（>50 文件） **建议：** - README.md（简介 + 快速开始） - docs/ 目录（详细文档） --- ## 🎨 README 风格指南 ### 核心原则 1. **结构清晰** - emoji 标记章节，层级分明 2. **中英双语** - 默认中文 + English version，**内容完整一致** 3. **实用优先** - 根据项目类型调整 4. **灵活发挥** - 根据项目特点自由组织 ### 项目类型特定内容 | 项目类型 | 特有章节 | 说明 | |----------|---------|------| | **Python** | 依赖安装、虚拟环境、PyPI 发布 | requirements.txt, setup.py | | **前端** | 技术栈、构建命令、部署指南 | package.json, npm scripts | | **API 服务** | 端点列表、请求示例、认证方式 | REST/GraphQL, curl 示例 | | **CLI 工具** | 命令行参数、子命令、配置选项 | 参数说明，使用示例 | | **库/SDK** | API 参考、类型定义、版本兼容性 | 函数/类说明，类型提示 | | **OpenClaw Skill** | 触发词、使用场景、配置 | SKILL.md 内容提取 | --- ## ✅ 质量检查清单 生成 README 后自动检查： ### 基础检查 - [ ] 项目简介清晰（1-2 句话） - [ ] 安装步骤完整且可执行 - [ ] 至少有 3 个使用示例 - [ ] 功能特点列出（3-5 个） - [ ] 目录导航正确（如>100 行） - [ ] 代码块指定语言 - [ ] 链接有效 - [ ] 许可证明确 ### 中英双语检查 - [ ] 中文内容完整 - [ ] **English version 完整翻译所有章节** - [ ] **英文目录链接正确（锚点用英文）** - [ ] **英文代码示例注释已翻译** - [ ] **英文内容长度与中文一致** - [ ] **英文部分有独立的 Table of Contents** - [ ] **英文 TOC 条目数量与中文目录一致** ### 可选章节检查 - [ ] **致谢部分已询问用户**（有/无） - [ ] 贡献指南已询问（需要/不需要） - [ ] 更新日志已询问（需要/不需要） ### Badge 检查（新增） - [ ] **项目描述后有 Badge 区域** - [ ] **使用 3 行布局**（核心信息 + 平台 + 许可证） - [ ] **使用 HTML 注释分行**（） - [ ] **Version Badge 已生成**（无版本号时为 0.0.1） - [ ] **平台 Badge 正确**（默认 macOS+Windows+Linux 或用户指定） - [ ] **License Badge 正确**（根据实际 License 或默认 MIT） - [ ] **每个 Badge 都有链接** - [ ] **颜色符合标准**（使用 shields.io 标准色） ### 代码块检查 - [ ] **代码块使用 ` 标记（无 ~~~）** - [ ] **无多余的 `** ### 禁止项 - ❌ **不要自动生成致谢部分**（必须先询问） - ❌ **不要省略 English version 的内容** - ❌ **不要使用中文锚点生成英文目录** - ❌ **英文部分不要缺少 Table of Contents** - ❌ **英文 TOC 条目不要与中文不一致** - ❌ **不要使用 ~~~ 标记代码块** - ❌ **不要生成多余的 `** - ❌ **Badge 不要缺少 Version**（无版本号时必须用 0.0.1） - ❌ **平台 Badge 不要错误**（用户未指定时必须 macOS+Windows+Linux） - ❌ **License 不要错误**（必须读取实际 License 或默认 MIT） - ❌ **Badge 不要缺少链接** - ❌ **不要省略 HTML 注释分行** --- ## 📝 版本管理 ### 备份策略 生成前备份现有 README： cp README.md README.md.bak.日期 ### 版本记录 在 README 末尾添加更新日志章节。 --- ## 🔧 配置选项 ### 语言设置 | 参数 | 说明 | 默认 | |------|------|------| | --lang bilingual | 中英双语 | ✅ | | --lang chinese | 仅中文 | - | | --lang english | 仅英文 | - | ### 详细程度 | 参数 | 章节 | 适合 | |------|------|------| | --detail minimal | 简介、安装、使用 | 小型项目 | | --detail standard | + 功能、API、贡献 | 中型项目（默认） | | --detail complete | + FAQ、基准、架构 | 大型项目 | ### 风格选项 | 参数 | 说明 | |------|------| | --style professional | 简洁专业 | | --style friendly | 活泼友好（emoji+ 双语） | | --style complete` | 详细完整 |

---

🚀 快速上手

基础使用

CODEBLOCK10

指定风格

CODEBLOCK11

指定类型

CODEBLOCK12

---

📄 许可证

MIT License

---

Happy Documenting! 📝✨

Top / 返回顶部