---
name: sync-reference-projects
description: 同步 MaaPipelineEditor 的 MaaFramework 社区参考项目。当用户说“同步项目”“同步参考项目”或要求更新社区参考仓库时使用；不用于同步 MPE 自身仓库。
---

执行参考项目同步前，先读取 `dev/docs/社区参考项目索引.md`，确认项目清单和脚本约定。

该同步流程是 MPE 社区参考源码的唯一补齐和更新入口。参考项目缺失或需要更新时，不要在系统临时目录、工作区内部或其他旁路位置手动 `git clone`；通过下述仓库级命令维护索引登记的本地副本。同步完成后的调研应直接读取 `../maa-refs` 下的仓库。

在仓库根目录执行：

```bash
yarn refs:sync
```

该命令使用 Node.js 调用系统 `git`，Windows 与 macOS 均可直接运行，不依赖 PowerShell。脚本的默认目标是与 MPE 同级的 `maa-refs` 目录。参考副本以索引登记的原仓库为准：不存在时克隆；已存在时获取远端默认分支并强制对齐，覆盖本地修改和提交，清理未跟踪及忽略文件。分支分叉、detached HEAD 或没有 upstream 均自动恢复到远端默认分支。子模块不参与调研，不下载或更新，并移除已检出的子模块内容。该覆盖规则仅适用于参考源码目录，不用于 MPE 自身或 LocalBridge 运行库。

汇报每个项目的最终同步结果。失败不应阻止其他项目继续同步。

如失败原因是临时网络问题（例如连接超时、连接重置、SSL 握手连接失败或 HTTP 5xx），可自动重试，无需再次确认。每次同步任务最多追加 2 次重试，分别等待 5 秒、15 秒后重新执行上述仓库级命令；该命令会重新检查全部项目。仅当上一轮仍有临时网络失败时继续重试，成功或达到上限后停止，并汇报仍失败的项目及原因。

认证或权限错误、仓库不存在、证书校验失败等非临时网络问题不应触发自动重试。远端获取成功前不得清理本地内容；不得关闭证书校验。origin 未登记时由脚本恢复到清单中的原仓库地址，已登记的迁移别名继续沿用。