用PR统一多仓库AI编程规则

多仓库共用一份 AGENTS.md，最麻烦的往往不是第一次复制，而是后续谁来更新、哪些项目已经落后，以及统一规则会不会覆盖项目自己的约定。team-ai-sync 给出的方案是：集中维护共享文件，再通过 Pull Request 分发，让每个仓库保留审核和合并权。

这篇教程值得看的地方，是它把同步、预演和审批串成了一套可落地的流程。不过，自动生成 PR 只能让改动可审查，不能证明指令适合所有项目；作者跑通的检查，也有明确的验证范围。

统一存放之后，为什么还要逐仓库提 PR

AGENTS.md、CLAUDE.md、提示词目录和编辑器配置，都会影响开发工具或 AI 编程代理的行为。不同仓库各留一份副本，很容易逐渐分叉：某个项目更新了测试要求，另一个项目还在沿用旧命令，团队却以为大家执行的是同一套规范。

team-ai-sync 把这些文件放进一个源仓库，再向目标仓库分发。关键在于，它不会直接完成合并，而是创建或更新同步分支和 PR，由目标仓库维护者决定是否接受。

共享文件可以集中维护，接受规则的决定仍应留在各个仓库。

这对前端和全栈团队很实际。同一条构建要求，可能适用于 web-app，却不适用于 api-service；同一份部署说明，也未必覆盖所有项目。PR 给维护者留下了结合项目语境检查的机会。

工具不会自动批准或合并 PR，不会绕过分支保护，也不会管理密钥或修改目标仓库设置。原文提到 GitLab CI/CD 和 Bitbucket 的对应包，但不支持用同一套流程跨平台同步：GitHub 目标用 GitHub Action，GitLab 项目用 component，Bitbucket 仓库用 pipe。

overwrite 和 skip，决定你怎样对待本地修改

源仓库至少需要配置一个文件或目录。下面的 sync-config.json 展示了同步范围、覆盖方式和 PR 参数：

{
  "targetRepositories": [
    "your-org/api-service",
    "your-org/web-app"
  ],
  "syncMode": "overwrite",
  "deleteOrphans": false,
  "files": ["AGENTS.md", "CLAUDE.md", ".editorconfig"],
  "directories": [".github/instructions", ".github/prompts"],
  "exclude": [],
  "prOptions": {
    "title": "chore: sync team AI assets",
    "body": "Synced from {{sourceRepo}} at {{sourceCommit}}.",
    "commitMessage": "chore(ai-assets): sync team assets",
    "branch": "chore/team-ai-sync",
    "labels": ["automation", "chore"],
    "userReviewers": [],
    "teamReviewers": []
  }
}

最需要先看清的是 "syncMode": "overwrite"。它会替换目标仓库中已存在的配置路径，不会自动调和本地修改。skip 则跳过已存在的文件，适合首次铺设起步文件、保留本地编辑的场景。

两者解决的问题不同。如果希望共享规范持续保持一致，skip 无法保证后续更新进入已有文件；选择 overwrite，就需要在 PR 中认真处理项目差异。原文没有展示共享规则与项目规则如何分层，也没有给出自动合并两类内容的方案。

目录会递归复制，exclude 接受仓库相对路径或 glob 模式。项目还会在处理目标前校验路径，拒绝绝对路径、.. 穿越、.git 路径段，以及解析后超出仓库根目录的路径。

deleteOrphans 默认是 false。开启后，工具可以删除同步目录中源端已不存在的文件。删除范围虽然限定在已配置的同步目录内，但目标仓库自行添加的文件仍可能受影响，不能把整个目录都视为无差别的公共区。

dry run 检查的是改动范围，不是规则质量

教程使用稳定版 paladini/team-ai-sync@v1，Action 运行在 Node 24 上。源仓库中的 .github/workflows/sync-ai-assets.yml 通过 main 分支的 push 或 workflow_dispatch 触发，在 ubuntu-latest 上先执行 actions/checkout@v4，再调用同步 Action。

首次运行应加入预演参数，先确认它准备改动什么：

- uses: paladini/team-ai-sync@v1
  with:
    github-token: ${{ secrets.TEAM_SYNC_ADMIN_PAT }}
    config-path: sync-config.json
    dry-run: true

这里要看的是 dry-run: true：它会校验配置，把目标克隆到临时工作树，复制配置路径并报告是否存在差异，但不会推送分支或创建 PR。它仍然会访问目标仓库，并非只检查 JSON 格式。

config-path 默认就是 sync-config.json，使用这个文件名时可以省略；Action 还接受 source-root 输入。确认预演结果后，移除 dry-run: true 或设为 false，才进入实际分发。

正式运行会确定每个目标的默认分支，创建或重置配置的同步分支，复制文件，并在存在变化时提交、推送，为每个发生变化的目标创建或更新一个 PR。配置里的 chore/team-ai-sync 因而应当留给自动化使用。

跨仓库写入使用单独的 github-token。源工作流的 GITHUB_TOKEN 只需读取源仓库；存入 secret TEAM_SYNC_ADMIN_PAT 的细粒度 PAT 或 GitHub App token，则负责克隆目标、推送和操作 PR。目标权限需要 Contents: Read and write、Pull requests: Read and write，配置标签时还需要 Issues: Read and write。

Action 提供 pr-urls、synced-targets、failed-targets 和 changed 等 JSON 输出。目标可以独立失败，其他目标继续执行，所以不能只看工作流是否成功，还要检查 failed-targets。合并后再次运行，无差异时应报告 changed=false。

我的判断

我认可它把审批留在目标仓库的设计。与手工复制相比，源仓库和固定 PR 流程更容易追踪更新；与直接写入默认分支相比，维护者可以检查具体差异，再决定是否合并。原文没有提供维护成本或同步效率的对照数据，这部分收益仍是流程上的推断。

最需要团队先达成共识的，是哪些文件允许被统一覆盖。

如果共享 AGENTS.md 混入项目专属命令，自动化只会更稳定地把不合适的内容送到更多仓库。预演能发现文件变化，PR 能提供审核入口，但两者都不能代替对指令内容的判断。私钥、凭证和机器专属设置也不应进入分发范围，token 应保存在 secret 中，并只授权必要目标。

作者报告，在 v1 检出版本上执行 npm ci、npm run lint、npm test、npm run build 均完成，TypeScript lint 通过，6 个测试文件中的 18 项测试通过，Action 打包成功。项目公开演示还记录了预演、创建和更新 PR、合并、最终无变化的生命周期。

这些证据支持基础流程可以运行，但不等于完整安全保证：npm ci 同时报告了 9 项依赖审计问题，其中 7 项为高危。原文没有交代这些问题的可利用条件，也没有给出大规模仓库运行、复杂权限组合或故障恢复的验证结果。

能拿来做什么

• 先挑少量前端或 Node 仓库试运行，把共享文件放入源仓库，用 dry-run: true 对照预期差异，再检查生成 PR 是否只包含配置路径。
• 在选择 overwrite 前逐项确认共享范围。若需求只是给新项目安装起步文件，可以使用 skip；若要持续更新规范，就需要明确项目差异由谁审核。
• 将 deleteOrphans 保持为 false，等同步目录的归属明确后再考虑开启。每次调整删除策略，都先预演并检查目标文件。
• 把首次手动合并后的再次运行作为验收步骤，同时检查 failed-targets 和 changed，确认目标没有遗漏，且无差异时返回 changed=false。