diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e7ae4ec --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,13 @@ +# AI 开发协作入口 + +开始修改、提交、推送或合并前,必须阅读并遵守 [仓库提交与合并规范](./仓库提交与合并规范.md)。该文件是本仓库多人协作的具体流程,不可仅凭本摘要跳过全文。 + +- 每个任务使用独立目录和唯一任务分支,默认前缀 `codex/`;不得共享目录并行编辑。 +- 保留他人的未提交修改和已有提交,仅暂存本任务内容;不得清理或覆盖未知工作。 +- 推送前同步远端,逐项检查最终差异并验证;被拒绝后先查明并合并更新,禁止任何形式的强推。 +- 不改写已发布历史,不批量选择冲突的某一方;不明确的行为取舍需要负责人确认。 +- 所有变更通过 PR 进入 `main`,不得直接推送主分支;独立审核与最新内容的验证通过后由维护者合并。 +- 不提交凭据、私钥、环境秘密或真实业务数据;不把合并授权当成生产部署授权。 +- 最终交付报告实际分支、提交 SHA、验证结果及 PR 状态,不能将“已推送”报告为“已合并”。 + +这些文档不代表服务端保护已启用。任何 AI 工具无法自动读取规则时,由使用它的开发者主动提供全文。 diff --git a/README.md b/README.md index 87563e8..1a66e50 100644 --- a/README.md +++ b/README.md @@ -45,4 +45,6 @@ npm --prefix frontend run check ## 参与修改 +开始开发前请阅读 [仓库提交与合并规范(多用户与 AI 开发必读)](./仓库提交与合并规范.md)。AI 工具的规则入口为 [AGENTS.md](./AGENTS.md)。每个任务使用独立目录和分支,通过 PR、同步验证和独立审核合并,禁止强推或覆盖其他开发者的工作。 + 所有用户均可 Fork 仓库、创建分支并提交 Pull Request。直接推送本仓库需要仓库所有者授予协作者写权限。提交时请说明修改和验证结果,勿提交 `.env`、密码、令牌、数据库备份或真实业务数据。 diff --git a/仓库提交与合并规范.md b/仓库提交与合并规范.md new file mode 100644 index 0000000..3e55ae8 --- /dev/null +++ b/仓库提交与合并规范.md @@ -0,0 +1,187 @@ +# 仓库提交与合并规范(多用户与 AI 开发必读) + +本规范适用于所有开发者及其使用的 AI 编程工具。目标是保留他人的提交和业务行为,让每次修改都可审核、可追溯、可回退。开始修改前必须阅读本文件与根目录 `AGENTS.md`。 + +公开仓库允许所有人 Fork、修改并提交 Pull Request(PR);直接写入本仓库仍需要协作者权限。每名开发者使用自己的账号和凭据,禁止多人共用管理员账号或把账号、密码、令牌写入代码、文档、提交信息及 PR。 + +## 1. 必须遵守的规则 + +1. **一个任务一个分支、一个独立工作目录。** 默认分支名为 `codex/<开发者>-<任务>-<唯一编号>`。不同 AI 会话不得同时修改同一工作目录,也不得共用任务分支。 +2. **通过 PR 合并到 `main`。** 禁止直接向 `main` 推送;由有合并权限的维护者在审核及验证通过后合并。 +3. **禁止强制推送。** 不得使用 `--force`、`-f`、`--force-with-lease`、带 `+` 的推送 refspec 或 `--mirror` 绕过拒绝。不得删除他人分支、重建仓库或替换历史来解决冲突。 +4. **保留他人工作。** 未确认归属的修改、未跟踪文件、提交和业务逻辑都不能删除或覆盖。禁止为得到“干净目录”执行 `git reset --hard`、`git clean -fd/-fdx` 或全量恢复文件。 +5. **先同步,再验证,再推送。** 推送成功、没有文本冲突、测试通过,都不能单独证明没有覆盖他人的业务行为;必须审核最终差异。 +6. **不能把冲突处理交给一条批量命令。** 禁止对整批冲突使用 `ours` / `theirs`,或把旧版本目录复制到新版本上。意图不明时停止该部分合并,交由相关开发者或维护者确认。 +7. **已推送的提交不得改写。** 共享分支和已发布的任务分支不要 rebase、amend 或 squash 后重新推送;用新的修正提交及 merge 保留历史。维护者在 PR 页面使用平台的 squash 合并功能不属于强推,但必须满足审核要求。 +8. **不夹带任务之外的改动。** 不顺手重构、恢复已删除功能、修改权限或部署配置;确有依赖变更时,在 PR 中说明必要性。 + +普通 Git 推送会拒绝非快进更新,但无法防止“基于最新提交,却把文件内容改回旧实现”的正常提交。因此,防止覆盖既需要保留历史,也需要检查代码含义和回归行为。 + +## 2. 开工前:确认仓库、基线与隔离目录 + +先检查当前位置、远端、分支及现有修改,不要直接执行复制来的修改命令: + +```bash +pwd +git remote -v +git branch --show-current +git status --short +git fetch origin +git log -5 --oneline origin/main +git rev-parse origin/main +``` + +记录 `origin/main` 的完整 SHA,作为本任务起始基线。确认远端确实是本项目;Fork 开发者还需核对上游仓库。浏览已有 PR,确认有没有人正在改同一模块。 + +如果当前目录有他人的修改,不要暂存、提交、stash、清理或覆盖它们。新建独立克隆,或在仓库内创建独立 worktree。下面的分支名和目录名仅是示例,执行前必须换成自己的唯一名称;若已经存在,换名而不是删除: + +```bash +git worktree add -b codex/alice-login-001 ../cangku-alice-login-001 origin/main +cd ../cangku-alice-login-001 +git status --short +``` + +只有已经确认由自己独占且干净的工作目录,才可直接使用 `git switch -c <任务分支> origin/main`。开始编辑前再次确认实际所在目录和分支。多个独立克隆通常更便于隔离;worktree 仍共享 Git 对象和部分仓库配置,不得随意修改全局或共享配置。 + +## 3. 修改与提交:仅纳入自己的任务 + +- 修改前阅读最新代码、调用方及相关测试,不凭历史对话或旧文件恢复整个模块。 +- 共享接口、权限、数据库迁移、依赖锁文件、路由和配置是容易互相影响的区域;涉及它们时,在 PR 中标明影响范围,必要时先协调接口约定。 +- 保留锁文件中其他开发者的依赖,用项目规定的包管理器生成自己的变更;不要以“重新生成”为由丢弃他人的依赖。 +- 数据库迁移使用不重复的名称,兼容已有数据,不能修改已经执行的历史迁移来代替新增迁移。 +- 不提交 `.env`、私钥、令牌、真实业务数据、数据库备份、`node_modules` 或无关构建产物。示例配置只使用占位值。 + +提交前逐项检查,并显式暂存文件;文件中混有不同任务时使用 `git add -p` 选择自己的改动。不要盲目使用 `git add .` 或 `git add -A`: + +```bash +git status --short +git diff --stat +git diff +git add <本任务文件路径> +git diff --cached --check +git diff --cached +git commit -m "docs: 说明本次变更目的" +``` + +尖括号内容是需要替换的占位符,不要原样执行。提交信息说明修改目的,每个提交保持逻辑完整。使用自己的真实开发身份,不冒用其他开发者身份。 + +## 4. 推送前:同步远端并处理并行修改 + +先把自己的工作整理为提交,确认没有未知的未提交修改,再执行同步。以下命令应当在自己的任务分支中执行: + +```bash +git fetch origin +git branch --show-current +git status --short +git log --left-right --oneline HEAD...origin/main +git merge origin/main +``` + +如果远端已经有同名任务分支,还必须检查 `HEAD...origin/<任务分支>`。远端出现本地没有的提交时,先查明来源,再用 `git merge origin/<任务分支>` 合入;不允许用本地版本覆盖它。不要把新分支第一次推送时不存在的远端引用当成错误而强推。 + +发生冲突时: + +1. 使用 `git status` 和 `git diff --name-only --diff-filter=U` 定位冲突。 +2. 阅读共同基线、双方提交及调用关系,弄清楚双方改动要实现的行为。 +3. 逐处整合并保留双方有效意图,同时检查相关文件中未产生文本冲突的逻辑兼容性。 +4. 意图或取舍不明确时,停止处理相关冲突并请负责人确认;不得自动选择“自己的版本”。 +5. 解决后显式暂存已解决的文件,确认没有未解决冲突,检查暂存差异,再完成 merge 提交。 +6. 对合并后的结果重新验证,并在 PR 中说明冲突位置及处理理由。 + +同步完成后审核整个任务相对最新主分支的差异: + +```bash +git diff --check origin/main...HEAD +git diff --stat origin/main...HEAD +git diff origin/main...HEAD +git status --short +``` + +完成下节验证后才可推送: + +```bash +git push -u origin HEAD +``` + +若推送被拒绝,重新 fetch、查看新增提交、合并、审核及验证。**拒绝不是强推授权。** 不通过修改 push 配置或反复重试危险命令绕过保护。 + +Fork 开发者约定 `origin` 为自己的 Fork、`upstream` 为本项目:从 `upstream/main` 创建任务分支,同步时合并 `upstream/main`,并检查自己 `origin/<任务分支>` 的更新;推送至自己的 Fork 后向本项目 `main` 发起 PR。不要将自己的 Fork 主分支误认成项目最新主分支。 + +## 5. 验证要求 + +按改动范围执行仓库现有检查: + +```bash +npm --prefix backend run check +npm --prefix frontend run check +``` + +- 后端改动运行后端检查;前端改动运行前端检查;跨端接口或共享行为改动需要两侧检查。 +- 功能修复补充能检出原问题的测试;影响页面交互时验证实际操作路径;涉及接口、权限或数据迁移时验证受影响场景及已有行为。 +- 仅文档变更可检查内容、链接、示例命令和 `git diff --check`,说明未运行应用测试的原因。 +- 使用隔离的测试环境和数据,不为了检查连接生产数据库或执行生产迁移。 +- 记录实际命令、结果和被验证的提交 SHA。失败要如实报告;无法运行的检查标记“未运行/受阻”,不能写成“通过”。 +- 同步或冲突解决改变了待合并内容后,重新运行受影响的验证。旧提交上的成功结果不能证明新提交正确。 + +## 6. PR 与安全合并 + +每个 PR 只对应一个明确任务,目标为 `main`,描述至少包含: + +```markdown +## 目的与范围 +- 解决的问题: +- 修改的模块/文件: +- 是否使用 AI 及负责开发者: + +## 同步与兼容性 +- 起始基线 SHA: +- 最近同步的 main SHA: +- 待审核任务分支 SHA: +- 并行 PR、共享接口、迁移/配置影响: +- 冲突及处理理由(无冲突也应说明): +- 如何确认保留了其他开发者的已有行为: + +## 验证 +- 实际执行的命令及结果: +- 未运行或失败的检查及原因: +- 人工验证路径(如适用): + +## 风险与回退 +- 已知风险: +- 回退方式和数据兼容性: +``` + +合并要求: + +1. 至少一名非提交者的维护者或开发者审核最终差异;AI 自我复查可以辅助,但不代替独立审核。提交 AI 不得用另一个会话或共享账号冒充独立审核者。 +2. 审核需关注是否撤销他人逻辑、丢失配置/依赖、改变接口与权限、破坏已上线功能,不能只看有无冲突或测试绿灯。 +3. 审核和检查必须对应最终待合并提交;后续新提交或冲突解决后需要重新确认,不能沿用失效的批准。 +4. 合并前再次确认最新 `main` 已被纳入任务分支,并验证组合后的行为。其他 PR 先合并导致主分支前进时,更新本 PR、重新检查并确认审核后再合并。 +5. 由维护者通过仓库 PR 合并功能依次处理;同时有多个待合并 PR 时串行合并。有合并队列时使用针对最新组合提交的检查,避免两份旧验证同时放行。 +6. 未解决冲突、必需检查失败、尚未审核或同步状态不清楚时不得合并。缺少独立审核者时保持 PR 待审核,不自行批准。 +7. 合并后核对主分支结果。删除任务分支前确认已合并且无人继续使用,不删除其他开发者的分支。 + +## 7. 发现误合并或代码被覆盖 + +先保留当前状态、记录相关提交 SHA 和影响,暂停自己受影响的后续提交,交由维护者定位问题。使用新的修复 PR 或 `git revert` 生成撤销提交,让历史可追溯。撤销 merge 提交需要维护者先确认正确的主父提交,不要盲目套用 `-m` 参数。 + +禁止将 `main` reset 回旧版本再强推。代码回退不会自动恢复数据库和外部状态;涉及迁移或数据变更时,需要单独验证兼容性与恢复方案。部署只能使用已合并、已验证的明确提交,并遵守实际部署授权;提交或合并代码本身不代表获准操作生产服务器。 + +## 8. AI 交付前检查清单 + +- [ ] 已阅读本规范;当前仓库、目录、账号、任务分支和基线正确。 +- [ ] 没有覆盖、清理、暂存或提交他人的未提交修改。 +- [ ] 提交仅包含本任务内容,没有秘密信息、真实业务数据或无关产物。 +- [ ] 已同步最新主分支及远端任务分支,未强推、未改写已发布历史。 +- [ ] 已逐项审核最终差异;冲突处理保留双方有效行为,疑点已确认。 +- [ ] 已完成受影响的验证,记录准确结果和提交 SHA。 +- [ ] PR 已说明范围、兼容性、验证、风险和回退方法。 +- [ ] 已明确报告当前状态:本地提交 / 已推送 / PR 待审核 / 已合并;没有把推送成功说成合并或部署成功。 + +## 9. 文档要求与服务端强制保护的区别 + +本文件规定协作流程,`AGENTS.md` 提供 AI 读取入口;它们不是权限控制,不能保证每个 AI 工具自动读取或遵守。使用不自动读取这些文件的工具时,开发者必须主动提供规则。 + +仓库管理员应在服务端落实以下保护,并以实际设置为准:保护 `main`、禁止直接及强制推送和删除、要求 PR 与独立审核、使过期审核失效、绑定真实运行的必需检查、限制合并权限、按个人发放最小权限凭据。没有真正运行的检查不能仅凭同名状态作为合并依据。 + +**添加本文件不等于上述保护已经启用。** 此文档变更不修改仓库权限、分支保护、CI 或生产部署;如需启用服务端限制,应由管理员单独配置并验证。