Oss publish

项目开源（oss-publish）· 把一个项目安全体面地开源到 GitHub

一句话：用户说"帮我开源一个项目/把 X 发到 GitHub 上"时跑这套：先做开源版改写与敏感审计 → 用户拍板仓库名和范围 → 全新历史规范身份发布 → 发布后从远端复查 → 按固定结构汇报。核心思想：push 出去的东西就当永久公开（会被缓存/索引），所以一切审计在发布前做足，发布后只做验证。

---

〇、定位与触发

什么时候用：用户说"帮我开源这个/把 X 开源/发布到我 GitHub 上/做成公开仓库"。 什么时候不用：往私有仓库推日常提交；给已有开源仓库修 bug 发 PR（常规 git 流程）。

---

一、八条铁律

1. push = 永久公开。GitHub 会被爬虫/缓存/镜像，git push --force 救不回已泄漏的内容。所以敏感审计必须在发布前做足，发布后的复查只是验证不是补救。
2. 双版本分离：私有版（含私有路径/内部引用/客户信息）留在用户自己的工作区；开源版从零重写路径层和引用层——输出路径改通用（如 ~/Downloads/...）、内部工具名换成通用说法、去掉一切"我们/本公司"语境改为面向陌生用户。两版各自维护，私有版头部标注开源仓库地址并注明"改内容记得同步"。
3. 全新 git 历史：开源仓库一律在干净目录 git init 重来，绝不从私有工作仓库带出历史（历史里的旧提交、旧作者邮箱、被删文件全是泄漏源）。
4. 提交身份规范：统一用用户的公开身份名 + GitHub noreply 邮箱（格式 <数字ID>+<用户名>@users.noreply.github.com，GitHub Settings→Emails 可查），真实邮箱绝不进提交。
5. License 必选再发布：代码/文档默认 MIT；含设计资产/图片/数据时另议（问一句）；项目里借鉴过别人的开源必须鸣谢并遵守对方许可。被研究/借鉴对象是 UNLICENSED 的，只能开源"你自己的方法/文字"，不能带对方代码资产。
6. 发布前用户拍板：仓库名、一句话描述、公开范围（哪些文件进/哪些不进）、License——列清楚给用户确认一次再 gh repo create --public。授权过的本次会话内后续修补推送不用再问。
7. 发布后以远端为准复查：git clone --no-local 从 GitHub 拉回来复扫敏感词 + 核对文件清单 + 看 README 渲染，不查本地草稿当交差。
8. 优质开源不止于无泄漏：README 要能让陌生人 30 秒懂（是什么/为什么/怎么装/长什么样/License）、中英描述、加 topics、无杂物文件（.DS_Store/node_modules/临时产物）、自造词首现处解释（冷读标准，参见本合集 plain-write）。

---

二、五步流程

第一步 · 备料与开源版改写

1. 确认要开源的内容清单；确认其中借鉴/依赖的第三方许可。
2. 按铁律 2 做双版本改写：路径通用化、内部引用剥离、语境改为陌生用户视角。
3. 组仓库结构：README（是什么→为什么→安装→使用示例→License）+ LICENSE + 主体内容；skill 类项目按 Claude Code 规范放 <skill名>/SKILL.md（带 frontmatter），README 写明 cp -r <skill名> ~/.claude/skills/ 装法。
4. 冷读审校一遍（本合集 plain-write）：自造词首现处解释、加一行英文简介、逻辑通顺。

第二步 · 发布前敏感审计（招牌环节，见附录 A 清单）

1. 敏感词 grep：姓名/账号（含曾用名）/真实邮箱/本机路径/私有笔记库路径/内部工具名/客户与内部项目代号。
2. 密钥模式 grep：sk- / ghp_ / AKIA / api_key= 等。
3. 杂物检查：find 看有没有 .DS_Store、临时文件、不该进的大文件。
4. 三项全过才进下一步；任何命中先修再扫，扫到零命中为止。

第三步 · 用户拍板

报给用户：仓库名 + 一句话描述（中英）+ 文件清单 + License 选择 → 确认后发布。

第四步 · 发布

cd <干净目录> && git init
git add -A
git -c user.name="<公开身份名>" -c user.email="<ID>+<用户名>@users.noreply.github.com" \
  commit -m "<项目名> v1.0: <一句话>"
gh repo create <仓库名> --public --source . --push --description "<中文一句话 | English one-liner>"
gh repo edit --add-topic <相关topics>   # 提升可发现性

第五步 · 发布后复查 + 汇报

1. git clone --no-local https://github.com/<用户名>/<仓库名>.git 拉回来：复扫敏感词（附录 A 全表）、核对文件清单与提交身份。
2. 有条件时网页/API 看一眼 README 渲染、description、topics。
3. 发现问题：小问题（措辞/格式）直接修了推；泄漏类问题立即报告用户——修复推送之外还要评估是否需要删库重建（缓存不可控）。
4. 按第三节固定结构汇报。
5. 私有侧收尾：私有版文档标注开源仓库地址，后续改动记得双向同步。

---

三、汇报结构（固定模板）

1. 开源了什么：项目名 + 仓库地址 + 可见性状态（PUBLIC）+ License。
2. 项目 Brief：这是个什么东西、给谁用、核心价值一句话。
3. 已做的工作清单：改写/审计/发布/复查各步的实际动作。
4. 检查结果与修复：敏感审计结论（发布前+发布后两轮）、发现的问题、每个问题是否已修复并已推送（挂 commit）。
5. 优缺点与待改进：现在这个开源项目质量如何、还差什么（如英文文档/示例截图/CI 徽章），哪些值得下次做。
6. 状态确认：只有全部修复验证完才说"开源已完成"；有未决项就列出来等拍板。

---

四、反模式

1. 从私有工作仓库直接 push 出去——历史就是泄漏源。
2. 审计只查本地草稿不查远端——以为推的是 A 其实推了 A+.DS_Store。
3. 用真实邮箱提交、或忘了改 user.name 带出本机 git 全局配置。
4. 先发布再审计——顺序反了，缓存不等人。
5. 开源版里残留"我们的知识库/某某内部工具"这类内部语境——陌生人读着莫名其妙，还暴露内部结构。
6. 无 License 就发布——别人不敢用，等于白开源。
7. README 只写"这是个 skill"不写怎么装、说什么话触发——开源了个寂寞。
8. 借鉴了别人的开源不鸣谢。

---

附录 A · 敏感词审计清单（模板——首次使用时按用户实际情况填一份专属清单，存在用户私有区，别把填好的清单本身开源出去）

# 身份与路径（按用户实际替换占位符）
grep -rniE "<真实姓名>|<姓名拼音>|<账号曾用名>|<公司/团队名>|/Users/|<私有笔记库目录名>|<真实邮箱域>" . --exclude-dir=.git
# 内部工具/方法论名（防暴露内部结构；开源版应已换通用说法）
grep -rniE "<内部工具名1>|<内部工具名2>|<内部SOP名>" . --exclude-dir=.git
# 客户与项目代号（按本项目涉及的裁剪）
grep -rniE "<客户名>|<项目代号>|<合作者人名>" . --exclude-dir=.git
# 密钥模式（固定项）
grep -rniE "sk-[a-zA-Z0-9]{10,}|ghp_[a-zA-Z0-9]{10,}|AKIA[A-Z0-9]{12,}|api[_-]?key\s*[:=]" . --exclude-dir=.git
# 杂物（固定项）
find . -name ".DS_Store" -o -name "*.log" -o -name "node_modules" -not -path "./.git/*"
# git 身份核验（固定项）
git log --format="author: %an <%ae>%ncommitter: %cn <%ce>"

注意：GitHub 官方 noreply 邮箱（<ID>+<用户名>@users.noreply.github.com）属于设计上公开的身份，不算泄漏。

---

复制即用启动词

使用 oss-publish 帮我开源 <项目/内容>：
1) 做开源版改写：路径通用化、剥离内部引用、面向陌生用户重写语境，冷读审校（自造词首现解释+英文简介）
2) 发布前敏感审计：附录A全表 grep 到零命中（身份/路径/内部代号/密钥/杂物）
3) 报我拍板：仓库名+中英描述+文件清单+License
4) 干净目录 git init 全新历史，公开身份+noreply邮箱提交，gh repo create --public 发布，补 topics
5) 发布后从远端 clone 回来复扫+核对，问题修复推送
6) 按固定结构汇报：开源了什么→Brief→已做工作→检查与修复→优缺点待改进→状态确认