# Oss Publish

> 把一个项目/skill 安全体面地开源到 GitHub。用户说"帮我开源这个/把X发到GitHub/做成公开仓库"时使用：开源版改写（路径通用化/剥内部引用/冷读审校）→发布前敏感审计（身份/路径/内部代号/密钥 grep 到零命中）→用户拍板仓库名与License→干净目录全新git历史+noreply身份发布→发布后从远端clone回来复扫→固定结构汇报。核心思想：push即永久公开，审计在发布前做足。English triggers - "open-source this", "publish this to GitHub", "make this a public repo". A push is permanent, audit before publishing.

- Skill: `yiweicreates/oss-publish` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yiweicreates/oss-publish`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yiweicreates/oss-publish/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: YiweiCreates (https://skillmd.com/u/yiweicreates)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yiweicreates/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 选择 → 确认后发布。

### 第四步 · 发布

```bash
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 · 敏感词审计清单（模板——首次使用时按用户实际情况填一份专属清单，存在用户私有区，别把填好的清单本身开源出去）

```bash
# 身份与路径（按用户实际替换占位符）
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`）**属于设计上公开的身份，不算泄漏**。

---

## 复制即用启动词

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