2026年9月24日 · 阅读 —
开源发布别再拍脑袋：oss-release-prep 把“能不能发”拆成一张张有证据的清单
开源发布别再拍脑袋：oss-release-prep 把“能不能发”拆成一张张有证据的清单
发布到 GitHub 之前，我们大多数人靠的是直觉。
“README 写得差不多就行”“LICENSE 好像有”“代码里应该没有密钥吧”——这几句话单独听都有道理，凑到一起就是发布现场漏掉真实风险的方式。我见过不止一次，仓库推上去才发现 .gitignore 没配、绝对本机路径混进了某个配置、密钥早就躺在 git 历史里了。
自己在逐步开源本地的一些存货项目过程，不断调整积累了一些规则经验，制作了该 skill: oss-release-prep 。它不制造神奇能力，只做一件踩在我判断点上的事：把“能不能发布”拆成一个个可打勾、必须有证据支撑的检查项，再产出规范、可切换的中英双语文档。这篇讲它到底怎么拆、拆完有什么用、以及哪些设计值得抄进自己的发布流程。
oss-release-prep/
├── SKILL.md # 激活入口（frontmatter + 规则）
├── prompts/oss-release-prep.md # 完整执行规范
├── agents/openai.yaml # 可发现元数据
├── references/
│ ├── readme-style.md # README 结构与详细度基准
│ └── release-checklist.md # 发布前逐项检查表（A–K，D 节为硬阻断）
├── examples/release-checklist-sample.md # 检查清单输出样例（不含真实密钥）
├── evals/
│ ├── eval.yaml
│ └── cases/ # basic-success / edge-incomplete-input / edge-scope-boundary
├── scripts/validate_skill_package.py
└── tests/test_oss_release_prep.py # 本地单测（unittest）使用方式
把本 Skill 指向一个项目，它会：
- 勘察仓库——目录结构、构建/测试命令、依赖与运行环境、git 状态、现有 README / License / 忽略规则、是否存在敏感文件。
- 跑发布检查清单——按
references/release-checklist.md逐项核对并记录证据。 - 补齐缺失工件——按需创建/修复
LICENSE、.gitignore、.gitattributes、缺失的 README 章节、徽章与结构说明。 - 生成中英双语 README——
README.md（英）+README.zh-CN.md（中），结构镜像、切换链接互指。 - 提升可发现性（可选）——About 描述、topics、GitHub Discussions、gruvbox-material 双语主页。
- 构建发布产物（可选）——
uv build的 sdist/wheel 附为 release assets；更新监管工具后做一次外部 reviewer 代码审查作为质量门禁。 - 交付——报告改了什么、如何验证、产物路径、风险/回滚，并把敏感信息扫描结果作为独立证据项。
发布动作（git push、gh repo create）仅在您显式授权时执行；否则本 Skill 把可复制的命令交给您运行。
一道它不是回答“怎么写 README”，而是“凭什么能发布”的题
先给它一个准确画像：把任意项目整理成符合 GitHub 开源要求的状态，并产出规范、详细、可中英双语切换的 README。但它真正的立场，落在 README 里反复出现的四个字上：以证据而非直觉为准。
翻译成工程语言就是每个发布项都要被核对并记录，无依据的“应该没问题”一律视为未通过。这个判断我完全认，因为它跟我给 Agent 做验收时遇到的是同一个问题：
光说“这功能能跑”不算数，你得能证明它跑过；光说“没有敏感信息”也不算数，你得把扫描结果摆出来。
对照表：
| 凭直觉的反例 | 这套 Skill 做的事 |
|---|---|
| “看起来差不多就行” | 每项都有证据：命令输出、文件存在、git 状态 |
| 只写一个 README，内容随意 | 固定结构：徽章 + 目录 + 结构 + 快速开始 + License + 维护者 |
| 一个文件里中英混排 | 两个独立文件 + 互指的切换链接 |
| 想发就发 | 敏感信息扫描、License 检查、构建测试验证、发布动作门禁 |
| 漏掉产物与其他推广位 | 发布产物、About/topics、Discussions、项目主页 |
四个核心概念
第一，证据链。 一个检查项只有被可引用的事实撑住才算通过。事实可以是命令输出、文件存在、git 状态、具体代码位置。无依据的“应该没问题”不叫通过，叫待办，并且会被如实记进下一步。这一条定的是最低要求：结论必须能回溯到某个具体动作，而不是“我印象里没问题”。
第二，敏感信息红线，且是硬阻断。 API key（sk-…、ghp_…、AKIA…）、token、cookie、私钥、密码、个人数据、绝对本机路径，全部严禁公开。任一命中立即中止发布——这个“立即”不豁免“还没推送”的情况。也就是说，你就算只在本地看到密钥，它也把发布停在这里，逼你先处理。这不是苛刻，是我写过流程就知道的那句实话：密钥一旦进历史，删文件没用，得轮换。宁可在这里停下来。
第三，双语双文件 README。 README.md（英文）+ README.zh-CN.md（中文）各自独立成文、结构镜像、切换链接互指。GitHub 会自动把 README.zh-CN.md 识别为语言变体，仓库首页就会出现切换 tab。它禁止单文件内中英混排。这件事对很多项目的价值，比想象中大——听过太多“双语就是这个文件前面贴段英文后面贴中文”的混排，检索和切换都很痛苦。
第四，门禁式发布 + 验证分层。 推广动作（git push、gh repo create、覆盖线上内容）只在用户显式授权时执行，否则如实报告“未执行”，并把可复制的命令交给你自己跑。同时它把静态检查、结构校验、实际运行、发布动作分开报告，任何没执行的一步都如实标注，绝不混进“已通过”。
这个“验证分层不互相冒充”的设计我特别认同。因为发布场景最坑的，就是把“静态检查过了”误读成“已经发布成功”或“行为已验证”。这三件事根本不是一回事。
A–K：十一节检查清单，K 是给监管工具收口
它的发布检查清单是十一个字母，每一节都需要证据，缺证据即视为未通过。我按用途重新排了一下，方便看清它堵的是哪些洞：
| 节 | 关注点 | 它堵的坑 |
|---|---|---|
| A | 版本库状态 | git init + 已提交、默认分支、无被跟踪的敏感文件 |
| B | 必备文件 | README、README.zh-CN、LICENSE、.gitignore、.gitattributes |
| C | README 质量 | 徽章 + 定位 + 目录 + 快速开始 + 结构/用法 + License + 维护者，命令能跑通 |
| D | 敏感信息扫描（红线） | 无 key/token/私钥/个人数据/绝对路径，命中即阻断 |
| E | 可验证性 | 构建/测试命令已运行并通过，依赖与安装步骤有据可查 |
| F | 动作门禁 | push / repo create 仅在显式要求时执行 |
| G | 可发现性 | 一行 About、topics（ai、llm、skill、persona、self-memory），用 gh repo view 验证 |
| H | 项目主页 | gruvbox-material 黑金风格 index.html，内置中英切换 |
| I | 社区运营 | 启用 GitHub Discussions 且至少一个类别 |
| J | 发布产物 | uv build 的 sdist/wheel 附到 release，用 gh release view 验证 |
| K | 发布质量门禁 | 监管工具清理干净（make-code-clean、code-review-graph）；更新工具后做外部 reviewer 代码审查 |
最值得反复看的是 D。它不只是“检查一遍”，而是被定性为红线且优先于其他所有规则，不因尚未推送而豁免。我把它理解成一个比“发布动作”更靠前的刹车：很多事故不是发生在 git push 那一刻，而是发生在你以为没问题、参数却早埋下的那一刻。
五个设计原则，几乎每一条都是工程判断
它 README 里的“安全边界与设计原则”部分，我逐条读下来，基本就是一份可复用的发布观：
- 敏感信息红线居首且最高，优先于其它所有规则。
- 绝不占位伪造：示例绝不用“改几个字符的真实密钥”冒充兼容，一律用无意义占位符（
sk-YOUR_KEY_HERE、<token>），且不与真实值同构。 - 以证据为准，只写有依据的结论，未验证项如实标注。
- 不虚构内容：技术栈、构建/测试命令、依赖均以本项目为准，不外借、不编造。
- 发布动作显式授权；验证分层不被混淆——静态检查不等于已发布，也不等于已验证行为。
“绝不占位伪造”这条我单独拎出来说。很多演示工具为了“看起来能跑”，会用 sk-xxx 这种和真实格式同构的假 key。这套 Skill 明确禁止，要求占位符既无意义又不与真实值同构。这是一个很容易被忽略、却很关键的纪律——因为一旦示例和真实值长得像，用户在复制过程中就可能混进真东西。
它给自己留的验证，也配得上它的主张
强调“以证据为准”的工具，自己也得能验。它自带三层验证：
# 包契约 + 密钥/绝对路径扫描
python3 scripts/validate_skill_package.py .
# 本地单测（unittest）
python3 -m unittest discover -s tests外加 evals/ 目录里的三个基于规则的评测用例：一个成功路径（basic-success）、两个拦截用例（edge-incomplete-input 信息缺失、edge-scope-boundary 范围拦截）。这三个用例相当于把“成功 / 该拦住的没拦住 / 输入不全时不硬编”三种预期行为都锁死，用来防止以后改坏了。它自己遵守“静态校验、单测、评测逐层分开”的原则，没有把脚本跑过就当成行为验证。
环境要求也很克制：Python 3，无第三方依赖。一个工具敢把依赖压到零，本身就是对“好用”的一种定义。
值钱的是它把“能不能发布”从主观感觉，翻译成了可打勾、可回查、可复制的清单。 这跟我们做测试、做 Agent 验收是同一条主线——把抽象判断拆成带证据的检查动作。
它有几个设计，我觉得可以直接抄进自己的发布流程：
- 敏感信息红线独立成节且最高优先，不跟其他检查混在一起讨价还价。
- 动作门禁：push、建仓库这类不可逆动作，默认只给命令、不代为执行。这是对“自动化容易替人做主”的反制。
- 发布产物可验证：
uv build出来的 sdist/wheel 不只是“生成了”，还要用gh release view去验证真的挂上了。 - K 的监管工具收口：更新
make-code-clean、code-review-graph这类监管工具后，先做一次外部 reviewer 代码审查再发布。设备更新一轮就跑一轮审查，防止新工具没磨合就进生产。
同时也要说清它的适用范围，免得过度使用。 FAQ 里已说明：不是所有项目都需要全部章节。默认产出详版本，但章节按项目实际情况取舍，基准与两个详细度级别写在 references/readme-style.md。发布产物里的 uv build 也只是 Python 示例，非 Python 项目该换二进制、JS bundle 或容器镜像。所以它更适合当一个“发布前检查骨架”来用，而不是一套必须原样照搬到任何仓库的教条。
很多人会问“我的项目这么小，也要整个 A–K 吗”。答案是否定的。小项目从 B、C、D、E 起步就够，G、H、I、J 这类可发现性和产物的提升项，等真需要再补。检查清单的价值在于帮你发现“该做而没做”的事，不在不停加项。
几个 FAQ 的答案，其实已经替你想清了取舍
它 README 里的 FAQ 都很短，但每个都挡在常见误判上，我按原文提炼成一句句判断：
- 它会自己 push 或建仓库吗？ 不会。发布动作需要显式授权，未授权时如实报告“未执行”并给出可复制的命令。
- 只支持 Python 项目吗？ 不是。检查清单适用于任意仓库；
uv build只是 Python 示例，非 Python 项目用等价产物。 - 发现密钥会怎样？ 红线命中即中止：先移除密钥、轮换已泄露凭据、用
git filter-repo等清除 git 历史，重扫零命中后再继续。 - 为什么是两个 README 而不是一个文件混排？ 独立文件、结构镜像、切换链接互指，GitHub 自动识别语言变体并出切换 tab。
- 小项目需要全部章节吗？ 不需要。默认详尽版，章节按项目实际取舍。
别把“看起来发了”当成“真的能发”
这套 Skill 最大的感受，不是它多聪明，而是它的立场跟我处理 Agent 验收时完全一致：“能跑”换成工程的衡量标准，是“有证据、可回查、失败能停”。
发布这个动作的平替，永远是那张把“凭感觉”换成“有依据”的清单：README 内容有结构、命令能跑通、密钥扫描零命中、动作需要你点头、产物用命令真验证过。这几条单拎出来都不惊艳，连起来就是一次能让人睡着的发布。
oss-release-prep 把这个过程做成了可复用的 Skill。你大可直接把它拿过来跑一遍自己的仓库，当它替你列出第一条“没证据、算待办”的项时，你就会明白它到底省掉了多少埋在地下的雷。
附：项目信息
| 项目 | 说明 | 地址 |
|---|---|---|
| oss-release-prep | 开源发布准备 + 中英双语 README 生成的 Codex Skill，MIT 许可 | GitHub xsoway/oss-release-prep（README.zh-CN.md 等） |
| 结构 | SKILL.md 激活入口 + prompts 执行规范 + references 基准/清单 + evals 评测 + scripts 校验 | manifest 如上，无第三方依赖，Python 3 |
快速验证它自己是健康的两次命令：
python3 scripts/validate_skill_package.py .
python3 -m unittest discover -s tests项目地址： https://github.com/xsoway/oss-release-prep
#开源 #Skill #Agent #README #发布流程 #证据