《新公开仓库上线 SOP 指南》
2026-10-13
写在前面
2026 年 10 月 12 日到 13 日，我把两个从实战中提炼的模板仓库公开发布到了 GitHub：
- multi-agent-shared-library：多 Agent 共享工作库框架（目录骨架 + 14 节同步防覆盖协议 + 索引工具）
- knowledge-base-template：主题知识库框架模板（四层架构 + 入库 SOP + 三层索引）
顺手把 muse-skills-cn 也对标检查了一遍。这篇文章是全流程的 SOP 沉淀。
一、环境工具
| 工具 | 用途 | 备注 |
|---|---|---|
| GitHub 账号 | 建仓、转公开/私有 | 公开仓免费，私有仓免费 |
| Git Database API（Python urllib 直调） | 推送文件、建提交、更新分支 | 直调接口完成推送；Token 不落地明文 |
| browser.search | 调研 README 写法、竞品 | 先调研再动手 |
| 本地构建目录 | 模板源文件、私有母版 | 公开发布前最后一次检查在本地构建目录做 |
| shields.io | README 徽章 | star / license / last-commit 三件套 |
推送铁律：走 Git Database API；更新分支用 PATCH /git/refs/heads/main；SHA 传完整 40 位；推完必须回读验证。
二、方法流程（七步）
第 1 步：本地构建 + 脱敏自查
- 模板仓库只放框架、规则、空模板、工具脚本，零个人信息：无人名、无账号、无提交号、无本地路径、无真实笔记内容。
- 示例内容用张三/李四、
main-env这类明显虚构的占位符。 - 绑定个人环境的脚本（如某桌面端的去重脚本）不纳入模板，改为通用版或文档说明。
第 2 步：建私有仓，先推私有
- 先建私有仓库，推送完整内容。
- 验证：文件数对得上、目录结构完整、关键文档可读。
- 好处：公开前有最后一次反悔机会；私有仓可作为后续迭代的母版。
第 3 步：用户确认后转公开
- 转公开是不可逆的心理门槛（公开后被 fork 即无法收回），必须用户亲口确认。
- GitHub 网页端 Settings → Danger Zone → Change visibility。
第 4 步：README 标准化（对标调研）
先做第 5 步的调研，再按标准结构改：
# 标题
[徽章：stars / license / last-commit]
> 一句话卖点（解决什么问题 + 适用谁）
## 🚀 安装使用 ← Fork/克隆命令，二选一写清
## 快速开始 / 用法 ← 最小可跑通路径
## （项目主体内容）
## 🤝 参与贡献 ← Issue/PR 指引 + 隐私红线
## 💬 交流群 ← 二维码 + 群号文字版
## 👤 作者 ← 署名 + GitHub 主页链接
## 📄 许可证 ← 许可证说明 + LICENSE 文件链接
- 对外统一署名用
liyu，GitHub 主页链接到个人账号。 - 交流群二维码图片压到 200KB 以内；文案里同时写群号文字版（图片加载失败时可照号搜索）。
第 5 步：补 LICENSE 文件
- 三个项目统一用 MIT License（见第四节调研结论）。
- 注意：shields.io 的 license 徽章读取的是仓库根目录的 LICENSE 文件，没有这个文件徽章显示 unknown。
第 6 步：推送 + 回读验证
- README、LICENSE、assets 等变更分别提交，提交信息写清改了什么。
- 每次推送后回读验证：徽章、作者、许可三项在远端 README 是否存在；图片文件是否在 tree 里。
第 7 步：上线引流
- 个人网站项目区上架（见本站《网站更新默认全流程》）。
- 模板本身免费，变现走"一对一指导服务"（另见《新服务上架流程 SOP》）。
三、踩坑及解决
| # | 坑 | 现象 | 解决 |
|---|---|---|---|
| 1 | README 顶部 YAML frontmatter | GitHub 不解析 README 的 frontmatter，会渲染成难看的纯文本段落 | 公开版 README 去掉 frontmatter，元数据留在仓库内文档或删掉 |
| 2 | Markdown 代码块嵌套 | 写安装节时 ```bash 里又套 ```bash，渲染错乱 |
Fork/克隆二选一用文字描述，只给一种留代码块；写完数 ``` 必须成对 |
| 3 | license 徽章显示 unknown | 只写了"采用 MIT"文字，没放 LICENSE 文件 | 补根目录 LICENSE 文件（标准 MIT 文本，Copyright 写 liyu） |
| 4 | 二维码图片过大 | 原图 694KB，拖慢页面 | PIL 压到 480px 宽（约 196KB），二维码照常可扫 |
| 5 | 交流群只有图片 | 图片加载失败时用户加不了群 | 文案同时写群号文字版 |
| 6 | 先公开后改 | 公开状态下改 README，每次提交都暴露在外 | 先私有仓改稳，确认后再转公开；转公开后的小修补用小步提交 |
| 7 | 占位符与作者署名冲突 | 模板里 {{OWNER_NAME}} 是给使用者替换的，liyu 是模板作者 |
两者并存：作者节写"模板作者 liyu"，正文占位符保留给 fork 者替换，README 里说明清楚 |
四、调研信息
4.1 README 主流写法（2026-10-13 调研）
来源：makeareadme.com、awesome-readme、freeCodeCamp、dev.to 等多方口径，共识结构：
- 标题 + 一句话卖点 + 徽章（3~5 个，只放真实会更新的状态）
- 截图/Demo（有可视化产物的放首屏；纯文档模板可省略）
- 快速开始 / 安装（最小可复制粘贴跑通的路径放最前）
- 用法 / 原理（篇幅超过两屏的移入 docs/）
- 参与贡献、许可证、作者（收尾三件套）
核心原则：README 是门面不是手册——陌生人 30 秒内要能判断"这是什么、给谁用、怎么跑起来"。
4.2 许可证选型
| 许可 | 特点 | 结论 |
|---|---|---|
| MIT | 最宽松；可商用、可闭源修改；只要求保留署名 | ✅ 选用。引流款模板要最低 adoption 门槛 |
| Apache 2.0 | 同 MIT + 专利授权条款 | 备选，无专利顾虑时没必要 |
| GPL 系列 | 传染性：衍生作品必须同许可开源 | ❌ 会吓跑想商用的人，引流效果打折 |
选用 MIT 的理由：变现路线是"免费模板引流 + 收费指导服务"，模板本身越开放、传播越广，服务转化池越大。MIT 允许别人 fork 商用，但我们不靠卖模板赚钱，无损失。
4.3 对标项目
muse-skills-cn（自有项目）：徽章、作者、License、目录、安装、投稿、交流群全齐，是本次标准化的对标基准。jasonbitsmith/muse-skills：内容形式（一句话痛点 + 三步做法）被 muse-skills-cn 借鉴。
五、内容验收清单
发布前逐项打勾：
- [ ] 本地构建目录与远端文件数一致
- [ ] README 无 frontmatter、无嵌套代码块、无占位符残留（除设计好的模板占位符）
- [ ] 徽章三个：stars / license / last-commit，指向正确的
user/repo - [ ] 一句话卖点说清"解决什么 + 给谁用"
- [ ] 安装使用：Fork/克隆命令可复制执行
- [ ] LICENSE 文件在仓库根目录，shields 徽章显示正常
- [ ] 作者节：liyu + GitHub 主页链接
- [ ] 交流群：二维码图片存在且 <200KB，群号有文字版
- [ ] 参与贡献：Issue/PR 指引 + 隐私红线（不接受带个人信息的 PR）
- [ ] 脱敏复查：无人名、账号、密钥、本地路径、真实业务内容
- [ ] 每次推送后回读验证通过
- [ ] 用户亲口确认转公开
六、总结
- 先私有、后公开：私有仓是母版和反悔机会，公开是单行道，顺序不能反。
- README 先调研再写：对标 1~2 个同类优质项目，8 件套（徽章/卖点/安装/用法/贡献/交流群/作者/许可）一次配齐，比事后补三次省时间。
- MIT 是引流款的最优解：模板免费传播 + 服务收费变现的路线下，许可越宽松，漏斗开口越大。
- 细节决定门面：frontmatter、嵌套代码块、694KB 二维码——每个都是"一眼不专业"的扣分项，验收清单就是用来防这些的。
- 推送后必回读：Git Database API 推送后回读验证是铁律，README 尤其要看渲染结果，不能只看提交成功。
作者：liyu ｜ 2026-10-13 ｜ 实战沉淀，持续更新