发布、品牌与 Shuffle 协议

发布、品牌与 Shuffle 协议

阶段 5–7 的操作手册：文档与品牌对齐、安全清扫、版本发布、终审。

README 与品牌

结构（顺序即信息层级）：

1. 权威 logo，居中
2. 一句话定位
3. 少量核心 badge
4. 安装 → 使用 → 架构 → 项目状态

规则：

• 默认英文 README；用户要求时提供本地化版本（如 README_zh.md），内容同源、同步更新
• logo 一律使用仓库已有的权威资产（用户制作的 favicon/logo）。绝不自造替代品；发现 agent 生成的替代品（SVG/PNG），删除并替换为权威资产
• badge 只留反映真实状态的核心项（构建、版本、许可证等），每个链接可达；失效或装饰性 badge 删除
• 语气：简洁、事实、不夸张。禁 AI 腔：反义排比、拟人、clever 标题、过程叙述。每个数字带口径与复现方式
• 声明与行为一致：README 写的每条能力必须在代码中真实存在、真实可用；写之前逐条核对
• 清理：失效链接、过期引用、孤立图片与重复品牌资产一并清除

安全清扫（push 前）

扫描范围：工作树、暂存区、待推送 diff、git 历史。

扫描对象：

• env 文件、配置、密钥、token、私钥、证书
• 个人数据、内部地址、日志、notebook 输出
• 夹具与样本数据中的真实凭证
• 误提交的大二进制与本地产物

动作：

• 验证 .gitignore 覆盖上述类别；提供 .env.example 而非真实 env
• 发现已入库密钥：先轮换/吊销，再清理历史；只删文件不算修复
• 确认远端 URL 与目标分支

发布账不止密钥

密钥只是其中一格。首次公开会把公开后无法低成本修改的东西一并固化，逐项结清再推：

• 作者邮箱与署名
• 已进入 git 历史的第三方内容——删除提交不改变其可取回性，唯一解是缩小公开面（干净初始提交 + 备份原线）
• 对外声明里的许可与能力表述（逐条现场验证，写下来的印象不是证据）
• 只写在一种语言里的承诺
• 仓库里每个非源码二进制的来源、许可与引用面

核验要按内容哈希在公开侧数出现次数；按文件名核会被同名替换骗过。

判据权威在 axiom 6.1 的依赖法律问（逐条读许可原文、逐子件核实、内联依赖不得连带它的示例素材）与第四部四十一（对外声明须有闸兜住：不成立的声明要做成一条此刻就叫的检查，而不是留一句待办文字）。，防误推

版本与发布

• 四处一致：版本号、CHANGELOG、包元数据、文档中的版本引用
• 版本号语义化；破坏性变更必须升主版本并附迁移说明
• tag 命名遵循仓库既有约定
• 顺序：质量门禁全绿 → 更新版本与 CHANGELOG → 提交 → 打 tag → push → 验证远端（tag 存在、CI 绿、release 页正确）
• 无显式授权不 force push；不跳过 hooks

Shuffle 终审协议

打 tag 前的最后一道闸。目的：打破路径依赖与确认偏误，用陌生眼光再审一遍。

执行：

1. 将全部检查项随机重排，按新顺序执行，不按记忆顺序
2. 五种视角各审一遍：
   • 维护者：五年后接手，能否看懂当初为什么这样做
   • 新贡献者：只凭 README 与文档，一小时内能否跑起来
   • 运维：半夜故障时，日志、告警、回滚路径够不够
   • 攻击者：认证、授权、注入面、密钥暴露面
   • 终端用户：只信 README 的声明，逐条验证是否属实
3. 四个对照必须一致：
   • 文档 ↔ 代码行为
   • 品牌资产 ↔ 权威源
   • 版本 ↔ CHANGELOG ↔ tag
   • 本地 ↔ 远端
4. 发现即修，修完重跑质量门禁，然后才定稿发布