GSRL/GSRL.md

GSRL 全局源码发行规范 v1.0

Global Source Release Lock（GSRL）

状态：正式规范 v1.0

适用范围：任何拥有独立 Git 仓库的项目。

1. 定位

GSRL 是规范，不是工具。它只统一正式发行和接收的基本证据；不指定语言、开发设备、编译器、打包工具、托管平台或 GPT/Codex/RDC 的具体实现。

每个独立 Git 仓库自行负责其发行。一个仓库可以发行多个组件；同一仓库在多台电脑上的 Clone 或 Worktree 不构成不同项目。

2. 触发条件

• 必须执行：独立成果正式发布、交付给其他项目使用、正式接入外部发行成果，以及交付 APK/IPA 或其他正式构建产物。
• 建议执行：重要测试或性能基线开始前，检查实际使用的发行版本及产物。
• 不强制：普通编码、实验、临时调试及尚未作为正式成果交付的开发构建。

开发工作区允许 Dirty；但包含未归档源码修改的构建，不得声称已完成可从 Git 恢复的 Source Lock。

3. 项目发行入口

每个项目维护 release/README.md，使不熟悉开发目录的使用者可以独立取得正式成果。该入口至少说明：

1. 已发行版本系列、当前推荐版本及版本状态；
2. 每个版本的正式文件获取位置；
3. 安装、复制、接入或使用步骤；
4. 必要的依赖、兼容性或环境要求。

建议单产品采用 release/<版本>/，多组件采用 release/<组件>/<版本>/。已有成熟的发布结构可以保留，但必须从 release/README.md 明确链接过去。

较大产物可存放 Gitea Release 附件、npm/Maven/SwiftPM 仓库或其他受控存储。不要为统一目录强迫大文件进入 Git。

4. Source Lock 必备内容

正式发行版本须提供 SOURCE_LOCK.json，至少包含：

• 项目及发行单元名称（如有多个组件）、明确的发行版本；
• Git Remote、完整源码 Commit SHA、可持久找到该 Commit 的 Tag 或其他保留引用；
• 每项正式交付文件的名称、位置及 SHA-256；
• 使用所需的依赖版本/发行身份与说明文档位置（无依赖时明确写空）；
• 发行状态；未核实的候选版本不得标为正式通过。

Source Lock 可以与压缩包同目录放置，也可放在包外作为伴随清单。不要求包内文件包含自己的哈希，以免形成循环引用。

当 Source Lock 写入同一个源码 Git 仓库时，允许先提交被发行的源码、记录其 Commit，然后在后续提交中加入发行记录；不得以随后发生的 Git HEAD 替代最初被发行的源码 Commit。

5. 交付方核验

正式发行前应逐项确认：

1. 本次发行实际使用的代码与 gitCommit 相符；相关未提交修改已处理，不能静默带入；
2. 源码 Commit 已 Push，且能从记录的 Git Remote/保留引用取得；
3. 交付文件实际存在，SHA-256 为重新计算的结果；
4. 交付包包含全部必需文件，所需依赖与使用方式已说明；
5. release/README.md 已登记此次版本及获取位置；
6. 同一发行版本尚未存在另一套已正式发布的文件或源码。

检查全部通过才能标记 PASS / RELEASED。失败时明确原因，不能用版本号相同代替检查通过。

正式发布不可静默覆盖。 已发布内容要修正时，使用新版本；允许保留旧版并标注弃用。

6. 使用方验收

其他项目使用一个正式版本时：

1. 从该项目 release/README.md 找到正式版本和下载入口；
2. 取得对应交付文件及 SOURCE_LOCK.json；
3. 检查项目、版本、Git 来源、文件清单、兼容性与依赖信息齐全；
4. 重新计算收到文件的 SHA-256，确认与 Source Lock 相符；
5. 校验通过后才能标记为正式接收并接入；不通过则要求交付方补齐或重新发行。

使用方不必重做交付方的全部开发测试，但不得凭文件名或人工口头版本说明认定内容正确。必要时保留本次使用的发行版本与 Source Lock 副本或引用，以便以后复查。

7. 工具及管理职责

• GPT：识别正式发行/接收任务，组织核验，并依据实际证据判断是否完成；
• Codex、RDC 和其他工具：执行具体 Git、文件、构建、发布、接入操作，报告结果；
• Git：提供源码历史与可恢复身份；
• 项目维护者：决定版本、发行方式以及发布授权。

可以使用已有的 Git、SHA-256、Gitea Release、包管理器或脚本。不要求安装 GSRL 专用软件，也不建立中央数据库。

任何工具均不得为通过 GSRL 而擅自清理未提交文件、强制 Push、覆盖已发布产物，或未经授权提交无关改动。RDC 多步操作继续按已有严格串行规则执行。

8. 跨设备、跨语言与私有项目

同一个 Git 仓库在 Win11、Linux、Mac 或未来设备上使用同一发行规范；路径和本地分支不是永久发行身份。多个 Worktree 要检查真正用于发布的那个 Worktree。

GSRL 规范仓库可以公开；业务 Git、二进制制品与依赖不要求公开。对私有发行，只需确保有访问权限的使用者能够获得源码或对应已归档制品并验证。

对于生成型成果（PBF、天气数据、Docker 等），如恢复需要原始数据、配置或外部二进制，发行方必须明确提供其版本、哈希和获取条件。只有 Git Commit 而缺少必要输入时，不得声称整个生成结果可恢复。

9. 完成判定

• PASS：源码可从指定 Git 来源取得、发行文件可取得且哈希一致、使用说明与必要依赖完整。
• INCOMPLETE：缺少 Git 可恢复依据、文件、哈希、说明或依赖信息，不能作为正式发行。
• MISMATCH：源码、版本或产物校验不一致，禁止将其当作对应的正式发行版本。

本规范只负责源码与交付内容的确定对应；不默认承诺在任意设备上重新编译出逐字节一致的二进制。

---

核心原则：每个独立 Git 项目独立开发、独立发行、独立负责；正式交付有 Source Lock，接收者核实后再使用。