open-source-release

---
name: open-source-release
description: "开源发布规范：把一个项目整理成专业、安全、别人愿意点开的公开仓库。覆盖公开前的安全检查（提交邮箱、密钥、私人信息、第三方授权）、许可证、README 和演示素材、仓库门面（Topics、分享预览图）、发布后验证。适用于：准备开源或公开仓库、新建开源项目、想让仓库看起来更专业、写或重写 README、发布前检查。用户说“开源这个项目”“公开仓库”“README 太简陋”“仓库看着很 low”“发布前帮我查一下”时使用。Open source release checklist: pre-publication safety, licensing, README, demo assets, repo presentation, post-release verification."
---

# 开源发布规范

目标：**公开后不泄露、不侵权，别人 30 秒内能看懂这是什么、值不值得用。**

专业感主要来自真实的演示和准确的说明，不来自徽章和文件数量。没有东西可展示时，先把项目做出来，不要靠包装。

## 0. 边界（先读）

- 可以直接做：读代码和历史、本地检查、在本地写 README 和文档、生成演示素材。
- 必须先问用户：创建公开仓库、推送、把私有仓库改成公开、改写 git 历史、发版、绑定域名、改账号或仓库设置。**推送可能自动触发上线**，也算对外发布。
- 公开后很难撤回：网页可能已被缓存、fork 或抓取。安全问题要在第一次推送前解决。
- 汇报时把“已实现 / 已验证 / 未测”分开写，没测过的不能说成可用。

## 1. 先弄清三件事

开始写之前先回答，答不上来就问用户：

1. **给谁用**：使用者是谁，他们从哪里看到这个项目？
2. **一句话价值**：不提技术名词也能说明白，用户能得到什么？
3. **能展示什么**：截图、动图、在线地址、命令输出，至少要有一样真实的东西。

## 2. 公开前安全检查（有问题就停下）

实际运行，不凭印象判断。**所有检查都要覆盖全部 git 历史**，因为只删当前文件，旧提交里仍然能看到。

在要发布的仓库里运行本技能自带的脚本（只读，不联网）：

```bash
bash <本技能目录>/scripts/preflight.sh --allow-email <同意公开的邮箱> --keyword <真实姓名> --keyword <私人邮箱> --keyword <本机用户路径>
```

- `[问题]` 必须解决，退出码不是 0 就不能发布。
- `[需确认]` 要逐条看过，并在汇报里说明结论。
- 脚本不检查图片等二进制文件的内容，也不检查第三方授权（见 2.3）。
- 提交新内容后要再跑一次。

### 2.1 提交身份

提交者的名字和邮箱对所有人可见，主页隐藏邮箱也没用。

- 确认这些名字和邮箱都是用户愿意公开的。不确定就问，不要默认私人邮箱可以公开。
- 想隐藏邮箱可以用 GitHub 的 noreply 地址（`<ID>+<用户名>@users.noreply.github.com`）。
- 提交邮箱要加到 GitHub 账号并验证，否则提交不会关联到账号。
- 历史里已有不想公开的身份，且仓库尚未公开时，有两种处理方式，都要用户同意：用 `git filter-repo` 改写作者信息，或者只保留当前内容、重新开始一条历史。

### 2.2 密钥和私人信息

脚本已安装 [gitleaks](https://github.com/gitleaks/gitleaks) 时会一起运行；没有安装时只做正则搜索，并提示需确认。

`--keyword` 要包含这个用户自己的信息：真实姓名、私人邮箱、手机号、本机用户路径、服务器 IP、账号 ID、内部域名、未公开的项目名。具体关键词只写在命令行里，不要写进任何会公开的文件。

- 搜到真实密钥：**先让用户作废并换新**，再清理历史。只从代码里删掉不算解决。
- 检查 `.gitignore`，确认依赖、构建产物、环境变量文件和系统文件不会被提交。
- 示例配置用 `.env.example`，只放变量名和假值。
- 看一眼大文件和用户数据：`git ls-files | xargs du -h 2>/dev/null | sort -h | tail`。

### 2.3 第三方内容授权

代码之外的东西最容易出问题。列出项目里所有不是用户原创的内容，逐项确认来源和授权：

| 内容 | 要确认什么 |
| --- | --- |
| 依赖和复制来的代码 | 协议是否允许，是否要保留版权声明 |
| 图片、模型、音频、字体、数据集 | 能否再分发，是否要署名，能否商用 |
| 提示词、文章、教程 | 原作者是否同意，署名和原文链接 |
| 品牌、Logo、影视动漫素材 | 默认不要用 |
| AI 生成内容 | 工具条款是否允许公开，据实说明是 AI 生成 |

- 没有授权就不公开，可以换掉或者自己重做。
- 用户说“作者同意了”时，写明依据是用户说明，并建议用户留存记录。
- 别人的内容不能套用项目的开源协议。要在 README 的授权部分单独写清楚，比如“提示词不在 MIT 范围内，权利归原作者”。

### 2.4 许可证

- 用户没有特别要求时，推荐 MIT，但要让用户确认。
- `LICENSE` 里的版权人写用户愿意公开的名字，不要自行填写真实姓名。
- 没有 LICENSE 不算开源，别人默认没有使用权。

## 3. 仓库里放什么

**按项目实际需要放，不为凑社区标准分数加文件。**

| 文件 | 什么时候要 |
| --- | --- |
| `README.md` | 必须 |
| `LICENSE` | 必须 |
| `.gitignore` | 必须 |
| `README.en.md` 或 `README.zh-CN.md` | 必须，中文版和英文版都要有，开头互相放链接 |
| `AGENTS.md` | 项目还会让 AI 持续修改时，写清约定和验收方法 |
| `CONTRIBUTING.md` | 接受外部贡献时，简短写明怎么本地运行、怎么提交 |
| `.github/ISSUE_TEMPLATE/` | 希望别人反馈问题时 |
| `.github/workflows/` | 确实有构建、测试或发布要自动跑时 |
| `SECURITY.md` | 处理用户数据、登录、支付，或有人依赖它运行时 |
| `CODE_OF_CONDUCT.md` | 社区开始有多人参与时 |
| `CHANGELOG.md`、版本发布 | 别人会安装某个版本时；网站和作品集通常不需要 |

## 4. README

结构和模板见 [references/readme-template.md](references/readme-template.md)。原则：

- **第一屏定生死**：演示图、一句话价值、在线地址或一条能跑的命令，都放在滚动之前。
- **按读者的决定顺序写**：这是什么 → 效果如何 → 怎么用 → 怎么运行 → 工作原理 → 授权。维护者才需要的内容移到 `CONTRIBUTING.md` 或 `docs/`。
- **只写验证过的事实**：不写没测过的兼容性、性能数字和没做的功能。命令都要在干净环境里实际运行过。
- **同一件事只写一处**，其他地方放链接，否则迟早对不上。
- **不写空话**：删掉“强大”“优雅”“开箱即用”这类词，换成能看到的事实。
- **徽章要少而有用**：只放真实反映状态的（构建状态、版本、协议），最多 3 到 4 个。没人用的项目不放 stars、downloads 徽章，也不放自己手写的“质量优秀”类徽章。
- **不写用不上的内容**：没有计划就别写路线图，没有参与者就别放贡献者墙。
- **翻译要意译**：结构和原文保持一致，互相放链接，术语用目标语言社区的习惯说法。

## 5. 演示素材

这是提升最大的一项，优先做。

- 用真实运行的画面，不用效果图或虚构数据。截图里不能有私人信息，先检查账号名、浏览器标签页、终端路径。
- 页面和动画项目：README 放 8 到 12 秒循环 GIF，宽度约 1000px，体积尽量控制在 10MB 内，超过就降帧率或尺寸。GIF 第一帧也要好看，因为加载时先看到它。
- 命令行项目：录终端（asciinema、VHS），或放一张命令和输出的截图。
- 素材放在 `docs/` 或 `assets/`，用相对路径引用，不要依赖外部图床。
- 分享预览图：1280×640，主体放在中间，文字要大。

## 6. 仓库门面

推送后设置（要用户同意）：

- **Description**：一句话价值，和 README 开头一致。
- **Homepage**：有在线地址就填。
- **Topics**：5 到 10 个别人真的会搜的词，全小写，比如技术名、用途、类型。
- **Social preview**：在仓库 Settings 上传，这样分享链接时会显示大图。
- 不用的功能关掉（Wiki、Projects、Discussions），页面更干净。

```bash
gh repo edit <owner>/<repo> --description "..." --homepage "https://..." --add-topic a --add-topic b --enable-wiki=false --enable-projects=false
```

## 7. 不同类型的重点

| 类型 | 第一屏放什么 | 最要紧的事 | 必须跑通（没跑通不能汇报发布完成） |
| --- | --- | --- | --- |
| 网站、作品集、Demo | 动图 + 在线地址 | 线上能打开，手机上不坏 | 打开线上地址，窄屏看一遍 |
| 库、SDK | 最短可运行示例 + 安装命令 | 示例真的能跑，API 有文档，语义化版本 | 在空项目里安装，运行 README 的示例 |
| 命令行工具 | 终端录屏 + 安装命令 | 干净环境能装上，`--help` 够用 | 按 README 安装，运行 `--help` 和一个真实命令 |
| 模板、脚手架 | 成品截图 + “用这个模板”步骤 | 从零跑通一次，不残留作者信息 | 按步骤新建项目并启动 |
| AI 技能 | 使用前后的对比 + 一句话安装 | 不依赖本机路径，写清适用边界和来源 | 推送前运行 `npx skills add . --list`，推送后运行 `npx skills add <owner>/<repo> --list`，要列出全部技能且没有解析警告，再实际安装一个 |
| 提示词 | 成品效果 + 提示词原文 | 写清来源和授权 | 复制提示词实际生成一次 |

`SKILL.md` 头部的 `description` 含有英文冒号时要加引号，否则 YAML 解析失败，工具会跳过这个技能。

## 8. 发布后验证

不要只看本地，要用陌生人的视角验证：

1. **干净环境**：`git clone` 到新目录，按 README 从头跑一遍。这里最容易发现漏提交的文件。
2. **未登录查看**：用无痕窗口打开仓库，确认图片能显示、相对链接都有效、英文版也能打开。
3. **再查一次提交**：`gh api repos/<owner>/<repo>/commits/<默认分支> --jq '{login:.author.login,email:.commit.author.email}'`，确认提交已关联到正确账号。
4. **有网站的**：查 HTTPS、404 页面、手机宽度，以及自动部署是否成功。修复后如果看不到变化，先排除 CDN 和浏览器缓存。
5. **分享卡片**：把链接发到目标平台预览一下。

## 9. 汇报格式

完成后先给出这张清单。**每一项都要写，不能省略**；只能标“已完成”“未做”或“不适用（写明原因）”。有“未做”时，不能说发布已完成。

| 项目 | 对应章节 | 状态 |
| --- | --- | --- |
| 脚本检查通过，需确认项已看过 | 2 | |
| 第三方内容授权 | 2.3 | |
| 许可证 | 2.4 | |
| README | 4 | |
| 演示素材 | 5 | |
| 仓库门面 | 6 | |
| 本类型必须跑通的项目 | 7 | |
| 发布后验证 | 8 | |

然后说明：

- 脚本结果和需确认项的结论，尤其是提交身份、密钥和第三方授权。
- 改了什么，发布到了哪里（附链接）。
- 还需要用户手动做的事。
- 没测到的部分，比如国内访问、某些浏览器。

• SKILL.md 11 KB
• references/readme-template.md 2 KB
• scripts/preflight.sh 5 KB