assert(0)

1.1 Fork 的正确姿势#

不要直接 Download代码。始终使用 Git Fork，保留完整的 Commit History，这是合并上游更新和排查问题的基础。

•   Upstream Remote: Clone 后第一时间配置上游仓库地址。

1
git remote add upstream https://github.com/original-author/repo.git
2
#验证
3
git remote -v

1.2 分支管理模型#

建议采用 “主干发布，上游隔离” 的策略：

•   main / master: 你的稳定发布分支（部署/发布代码）。

•   upstream-sync: 纯净的上游跟踪分支，永远只执行 git pull upstream master，不包含你的任何修改。

•   dev / feature-xxx: 你的开发分支。

同步流程:

1.  更新 upstream-sync: git checkout upstream-sync && git pull upstream master

2.  合并到开发分支: git checkout dev && git merge upstream-sync

3.  解决冲突 -> 测试 -> 合并到 main

2.1 锁死一切 (Lock Everything)#

任何外部依赖，必须有确定的版本号（Commit Hash 或准确版本号），绝对禁止使用 latest、master 或动态范围版本（如 ^1.0.0） 用于生产环境。

•   Git Submodules: Submodule 本质就是锁定 Commit。

    *   规范: .gitmodules 中的 branch 仅供参考，实际生效的是索引中的 Commit ID。

    *   检查: 定期运行 git submodule status 确保没有 “游离” 的 submodule。

•   包管理器: 必须提交 Lock 文件 (package-lock.json, Cargo.lock, requirements.txt with hashes)。

2.2 依赖本地化与私有化 (Vendoring & Forking)#

原则: 如果上游依赖不稳定、已删除或你需要修改它，必须 Fork 该依赖。

•   案例: 本项目中的 moonlight-common-c 引用了一个不存在于官方仓库的 commit。

•   解决方案: 将该依赖 Fork 到自己名下，保留需要的 commit，然后修改主项目的引用指向你的 Fork。

    *   优点: 你拥有控制权，不会因为原作者删除仓库导致你无法构建。

    *   缺点: 需要自己手动同步原作者的后续更新。

2.3 拒绝隐式依赖#

项目中不应假设系统预装了某个工具。

•   Bad: 文档写 “请安装 Python 3”。

•   Good: 提供 setup.sh 或 .devcontainer 脚本自动安装指定版本的 Python。

•   Best: 使用 Docker 容器化构建环境。

3.1 基础设施即代码 (IaC)#

CI 配置文件（如 .github/workflows/*.yml）就是构建流程的文档。

•   环境一致性: 如果 CI 能跑通，说明构建不依赖开发者本地的特殊配置。

•   步骤显式化: 安装编译器、设置环境变量、初始化 Submodule 等步骤必须在 yaml 中写明。

3.2 密钥安全 (Security)#

•   Push Protection: 开启 GitHub 的 Push Protection，防止 AK/SK 泄露。

•   Environment Variables: 代码中严禁硬编码密钥。

    *   Bad: String key = "aliyun-ak-123";

    *   Good: String key = getEnv("ALIYUN_AK");

•   Secrets Management: CI 中的密钥通过 Repo Settings -> Secrets 注入。

3.3 自动化发布 (Release Workflow)#

不要手动编译上传 zip 包。使用 CI 自动处理：

1.  打 Tag (git tag v1.0.0).

2.  Push Tag (git push origin v1.0.0).

3.  CI 触发 -> 构建 -> 打包 -> 创建 GitHub Release -> 上传附件。