# 贡献指南

Cage 采用“贡献 Issue 审核 → 邀请成为协作者 → 提交 PR → 审查合入”的流程。仓库仅允许协作者创建 PR；修复代码、改进功能和修改文档都从明确的贡献方案开始。

## 提交方案并等待审核

在[新建 Issue 页面](https://github.com/Lee-xeo/Claude-Cage/issues/new/choose)选择“方案贡献（Contribution）”。说明要解决的问题、基于的版本或提交、适用系统、解决思路、验证结果和影响范围。有代码时附上 Fork 分支、具体提交、diff 或补丁；尚未验证的部分请明确注明。

只有问题描述时使用“问题反馈”；尚无具体方案的功能需求使用“功能建议”。提交前先搜索已有 Issue，已有相关讨论时在贡献 Issue 中关联它。

仓库管理员或具有 `maintain` 权限的维护者审核方案、确认愿意接纳本次贡献后，为仍处于打开状态的 `contribution` Issue 添加 `accepted` 标签。通过审核表示可以进入实现和 PR 审查阶段，最终合入仍取决于代码审查与验证结果。

## 接受协作者邀请

添加 `accepted` 标签会触发 **Invite approved contributors** 工作流，向该 Issue 的作者发送协作者邀请，并在 Issue 中说明后续步骤。已有写权限的协作者可直接提交 PR；待接受的邀请会被复用。

贡献者需要通过 GitHub 通知或[仓库邀请页面](https://github.com/Lee-xeo/Claude-Cage/invitations)接受邀请。邀请过期或流程失败时，请在原 Issue 中联系维护者处理。

协作者拥有整个仓库的写权限，该权限不限于这一条 Issue。`main` 受分支保护，协作者通过独立分支和 PR 交付变更，由代码所有者 `@Lee-xeo` 审核后合入；新增提交后需要重新审核。关闭 Issue 或移除 `accepted` 标签不会自动取消邀请或撤销已有权限；权限调整由仓库管理员在仓库设置中处理。

## 提交 PR

1. 接受邀请后，将本地基线更新到仓库最新的 `main`。
2. 为本次贡献创建独立分支，命名为“开始日期-GitHub用户名-工作内容”，例如 `261112-alice-fix-startup`。保留无关的在途改动，提交范围与审核通过的方案保持一致；扩大范围时先在原 Issue 中讨论。
3. 完成实现并运行与改动相关的检查。涉及共享功能时核对 macOS、Windows 和 Linux；说明实际验证的平台、结果及未验证范围。
4. 推送分支并创建指向 `main` 的 PR，在正文中关联贡献 Issue，例如 `Closes #123`，说明用户可见的变化、验证结果和已知限制。
5. 根据评审意见更新 PR。通过审查与所需检查后由维护者合入，随后删除已合入的分支并关闭对应 Issue。

源代码、配置、日志和附件中均不得包含密码、令牌、订阅链接等敏感信息。引用第三方代码时注明来源并保留所需许可。

## 维护者：配置自动邀请

自动邀请使用 `contribution-invites` Environment 中的 Secret `CONTRIBUTION_INVITE_TOKEN`。使用只授权 `Lee-xeo/Claude-Cage` 的 fine-grained personal access token，并授予仓库权限 **Administration: Read and write**；其余权限保持最小范围。令牌应设置有效期，并在到期前更新。

在仓库 **Settings → Environments → contribution-invites** 中，只允许 `main` 分支部署，并将该令牌保存为 Environment Secret。邀请令牌不得放进普通仓库 Secret，否则具有写权限的协作者可以在其他分支的工作流中使用它。GitHub Actions 自带的 `GITHUB_TOKEN` 用于检查审核者权限和写入提醒，无法单独完成协作者邀请。

`main` 的分支保护要求 PR、至少一次代码所有者审核及新提交后的重新审核，禁止强制推送和删除；`.github/CODEOWNERS` 将所有路径的代码所有者设为 `@Lee-xeo`。管理员保留处理自有改动的权限。这些保护与仅限 `main` 的 Environment 共同阻止普通协作者在未审核的分支中取得邀请令牌。

日常审核步骤：

1. 确认 Issue 有 `contribution` 标签，并完成方案与贡献者的审核。
2. 由管理员或具有 `maintain` 权限的维护者添加 `accepted` 标签。普通 `write`、`triage` 和 `read` 权限不会触发授权成功。
3. 查看 **Actions → Invite approved contributors** 的结果。只有邀请成功、已有待接受邀请或作者已有写权限时，工作流才会在 Issue 中发布后续步骤。
4. 如凭据缺失、过期、权限不足或邀请发送失败，先修复原因，再在该工作流页面选择 **Run workflow**，使用 `main` 分支并填写原 Issue 编号重试。重试同样检查当前审核者权限、Issue 状态及两个标签，并复用已有提醒。

自动化读取默认分支中的脚本，不执行申请者的代码。它只负责审核后的邀请和提醒；方案审核、接受邀请、实现代码和 PR 审查由对应参与者完成。

GitHub 参考：[邀请协作者 API](https://docs.github.com/en/rest/collaborators/collaborators#add-a-repository-collaborator)、[工作流令牌的权限边界](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token#granting-additional-permissions)。