EverOS 的 GitHub 同步守护（GitHub Sync Guard）：GitLab dev 到 GitHub main 的镜像刷新规则与 rsync 实操

EverOS 的 GitHub 同步守护GitHub Sync GuardGitLab dev 到 GitHub main 的镜像刷新规则与 rsync 实操【免费下载链接】EverOSOne portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.项目地址: https://gitcode.com/gh_mirrors/ev/EverOSEverOS 采用双仓库、无共享历史的发布模式内部 GitLab 的dev分支是唯一事实来源公开 GitHub 的main分支只是经过打包导出的发布镜像。本文基于 docs/github-sync.md 系统拆解这一同步守护机制的五类文件处置规则并结合仓库内源码校验脚本、Makefile、分支保护配置给出可落地的 rsync 同步命令、验证流程与评审清单读完你可以独立执行一次GitLab → GitHub的安全刷新并理解背后的自动化防线是如何防止内部内容泄漏、防止 GitHub 专属内容被覆盖的。一、核心原则为什么 GitHub 收到的是打包导出而不是 git push同步机制的第一条铁律是GitLabdev是 source of truthGitHubmain是公开发布镜像。两个仓库没有共享的 commit 历史——GitHub 接收的是打包导出而不是 git push。这句话决定了整个同步流程的形态不能直接用git push把 GitLab 的提交推给 GitHub两者历史完全不同源强行 push 会产生大规模 force-push 或无法合并正确的做法是把 GitLab 工作区打包成文件快照再用rsync等文件级工具覆盖到 GitHub 检出目录最后通过 GitHub PR 合入main由于是文件级同步而非提交级同步哪些文件该覆盖、哪些文件必须保留、哪些文件绝不能出现就需要一套显式的守护规则来约束——这正是本文要讲的内容。这一原则在仓库的 CLAUDE.md 中也有呼应When refreshing this repository from an internal source archive, preserve GitHub-only contributor and automation files. Do not overwriteCLAUDE.md,.claude/skills/*,CONTRIBUTING.md, or.github/*workflow/template files without checking docs/github-sync.md.刷新仓库时必须保留 GitHub 专属的贡献者与自动化文件。同步目标可归纳为五类后续各节逐一展开类别处置动作典型对象1. 必须删除旧文件已被替代从 GitHub 上删除locomo 旧脚本、错误路径的锁模块2. 必须保留GitHub 专属内容不要用 GitLab 版本覆盖CI 工作流、Claude Code 技能、贡献指南3. 覆盖从 GitLab 全量覆盖src/everos/**、测试、依赖锁文件、文档4. 不同步到 GitHubGitLab 内部内容禁止泄漏MR 模板、IDE 配置、内部发布流程5. 不同步到 GitLabGitHub 专属内容只留在 GitHubuse-cases、GitHub CI 脚本与工作流二、第 1 类必须在 GitHub 上删除的过时文件这些文件在 GitHub 上仍存在但已过时每次同步时必须删除文件原因替代品docs/locomo_benchmark.md已被 benchmarks/README.md 取代tests/run_locomo_10x3.sh已被 benchmarks/run.py 取代tests/run_locomo_batch.sh已被 benchmarks/run.py 取代tests/run_locomo_full.sh已被 benchmarks/run.py 取代tests/test_locomo.py已被 benchmarks/run.py 取代src/everos/memory/strategies/_partition_locks.py路径错误正确位置是src/everos/memory/_partition_locks.py源码印证在当前镜像仓库中上述替代品均真实存在benchmarks/ 目录包含run.py、config.py、config.toml、README.md——LoCoMo 基准测试已经收敛为统一的 Python runner TOML 配置方案不再需要多个 shell 脚本正确路径的锁模块 src/everos/memory/_partition_locks.py 存在而strategies/子目录下的错误路径版本已被移除仓库内已经搜索不到任何locomo*命名的旧脚本说明删除规则已经在此前同步中执行过。删除动作本身可并入同步命令见第八节的 Safe Sync Pattern 第 3 步也可在 PR 评审清单中逐项核对见第十节。三、第 2 类必须在 GitHub 上保留不要覆盖的内容这些文件在 GitHub 上含有平台专属内容分支模型、PR 工作流、面向社区的话术同步时必须保留 GitHub 版本禁止用 GitLab 版本覆盖。共分四个子类。3.1 Workflow 与 CI文件GitHub 专属内容CLAUDE.md说的是main分支而非dev/masterCONTRIBUTING.md说的是curated PR contributions而非no external PRs.github/PULL_REQUEST_TEMPLATE.mdGitHub PR 模板.github/BRANCH_PROTECTION.mdGitHub 分支保护规则.github/workflows/ci.yml目标分支为main使用actions/checkoutv6.github/workflows/docs.ymlGitHub 专属文档检查.github/workflows/commits.ymlGitHub 专属 commit lint.github/ISSUE_TEMPLATE/**.yml格式GitLab 用.md.github/dependabot.ymlGitHub 专属依赖扫描其中 .github/BRANCH_PROTECTION.md 是 GitHub 侧main 分支保护基线的权威文件要求合并必须走 PR、普通工作需要两个 approving review、合并前必须解决对话、禁止 force push、禁止删除分支、不做常规管理员绕过并把CI / lint、CI / unit tests、CI / integration tests、CI / package build、Docs / links、Commit lint / commit messages六项设为 required status checks。这类内容如果被内部版本覆盖公开仓库的协作约束就会失效。3.2 Claude Code 规则与技能文件GitHub 专属差异.claude/rules/*.mdGitHub 版本面向贡献者做了简化.claude/skills/commit/SKILL.md使用 Conventional Commits内部用 Gitmoji.claude/skills/new-branch/SKILL.md从main开分支内部从dev.claude/skills/pr/SKILL.mdGitHub PR内部是 GitLab MR.claude/settings.jsonGitHub 权限集含gh pr这与仓库的工程约定高度一致CLAUDE.md 明确写到mainis the default and protected branch. Create scoped branches frommainfeat/*、fix/*、docs/*、ci/*、chore/*、refactor/*and open pull requests back tomainGitHub 侧的 commit/分支/PR 技能文件必须与之匹配而不是内部 GitLab 的 MR Gitmoji 流程。3.3 GitHub 专属脚本与测试scripts/check_commit_messages.pyscripts/check_deprecated_names.pyscripts/check_docs.pyscripts/check_github_contributor_docs.pyscripts/check_pr_title.pyscripts/check_repo_assets.pytests/unit/test_scripts/test_check_*.py这些脚本是 GitHub 侧的 CI 门禁在 Makefile 中体现为check-commits、check-pr-title、docs-check、check-assets、check-github-docs等 target。以 scripts/check_pr_title.py 为例它从 scripts/check_commit_messages.py 动态加载同一份 Conventional Commits 策略ALLOWED_TYPES为feat/fix/refactor/test/docs/style/perf/chore/build/ci/revert标题正则^type[(scope)][!]: description长度上限 72 字符然后校验 PR 标题scripts/check_commit_messages.py 则读取GITHUB_EVENT_NAME、GITHUB_SHA、GITHUB_PR_BASE_SHA等环境变量确定 commit 范围并对 merge commit、Revert、fixup!、squash!做豁免。这些依赖 GitHub Actions 环境变量的逻辑在 GitLab CI 中无法工作因此绝不能覆盖。3.4 根文档GitHub 版本内容不同文件差异README.mdGitHub 版本带 banner、badges、use-case 画廊MakefileGitHub 版本带额外 targetdocs-check、package 等Makefile 确实包含docs-check、package、cov、ci等丰富 targetGitHub 侧需要这份面向公开贡献者的构建/校验入口。四、第 3 类从 GitLab 覆盖的内容除第 1、2 类之外的一切内容都应从 GitLab 覆盖包括但不限于全部src/everos/**源码全部tests/unit/**、tests/integration/**、tests/e2e/**测试pyproject.toml、uv.lockQUICKSTART.md、SECURITY.mdCHANGELOG.md、CITATION.md、ACKNOWLEDGMENTS.mddocs/*.md第 1 类列出的除外docs/openapi.jsonbenchmarks/**.gitignore.gitlab-ci.yml在 GitHub 上无害保持同步即可注意docs/openapi.json属于必须同步的产物它是通过 scripts/dump_openapi.py 从 FastAPI 应用导出并经过make check-openapi漂移门禁校验的契约文档任何 API 变更都必须同时刷新它因此它必须跟随 GitLab 版本走而不是像README.md那样保留平台专属版本。五、第 4 类不要同步到 GitHub 的文件这些文件属于 GitLab 内部不应出现在 GitHub 上文件原因.gitlab/merge_request_templates/GitLab 专属.vscode/IDE 偏好.claude/skills/release/SKILL.md内部发布流程local/临时设计文档evaluation/空模块这一类的共同点是内部性MR 模板与dev分支模型强绑定、.vscode是个人偏好、release 技能暴露内部发布节奏。泄露到公开仓库会造成信息污染因此 rsync 必须显式排除。六、第 5 类不要同步到 GitLab 的文件反过来这些文件是 GitHub 专属的只能留在 GitHub类别文件use-cases/claude-code-plugin、game-of-throne-demo、openher 等文档统计约 90 个文件GitHub CI 脚本scripts/check_*.py 对应测试GitHub CI 工作流commits.yml、docs.yml配置.gitlint、根级.env.example文档docs/use-cases.md当前镜像仓库中的 use-cases/ 目录确实包含claude-code-plugin、game-of-throne-demo、openher三个完整的落地示例模块各自带前端/后端/脚本这些是面向 GitHub 社区展示 EverOS 实际用法的素材属于GitHub 资产不应回流到内部 GitLab。七、Safe Sync Pattern安全的同步实操同步守护文档给出了完整的可执行模式核心思路是rsync 全量覆盖 白名单排除 定点删除过时文件# 1. Clone both repos git clone gitlab gitlab-export git clone github github-checkout # 2. Sync with excludes rsync -a --delete \ --exclude .git \ --exclude CLAUDE.md \ --exclude CONTRIBUTING.md \ --exclude README.md \ --exclude Makefile \ --exclude .github/ \ --exclude .claude/rules/ \ --exclude .claude/skills/ \ --exclude .claude/settings.json \ --exclude scripts/check_*.py \ --exclude tests/unit/test_scripts/ \ --exclude use-cases/ \ --exclude local/ \ --exclude evaluation/ \ --exclude .vscode/ \ --exclude .gitlab/ \ --exclude .gitlab-ci.yml \ gitlab-export/ github-checkout/ # 3. Delete obsolete files cd github-checkout rm -f docs/locomo_benchmark.md rm -f tests/run_locomo_10x3.sh tests/run_locomo_batch.sh tests/run_locomo_full.sh rm -f tests/test_locomo.py rm -f src/everos/memory/strategies/_partition_locks.py # 4. Verify make lint make test逐步解读第 1 步双克隆。分别拉取 GitLab 导出目录与 GitHub 检出目录同步全程以文件为单位进行不涉及 git 历史操作。第 2 步rsync 排除清单。-a保留权限/时间戳等属性--delete删除目标目录中源里不存在的文件这正是过时文件被清理的机制。--exclude列表是守护规则第 2、4、5 类的编码化被排除的对象不会覆盖CLAUDE.md、CONTRIBUTING.md、README.md、Makefile、.github/、.claude/*、scripts/check_*.py、tests/unit/test_scripts/、use-cases/也不会被带进来local/、evaluation/、.vscode/、.gitlab/、.gitlab-ci.yml。注意--delete与排除规则配合时被排除的目标端文件不会被删除从而天然实现保留 GitHub 版本。第 3 步定点删除。对于第 1 类过时文件因为它们在 GitLab 源中已不存在单纯 rsync 无法保证删除取决于目标端状态所以显式rm -f确保它们从 GitHub 检出目录中消失。第 4 步验证。运行make lint与make test确认同步后仓库仍然健康详见下一节。八、同步后的验证Makefile 里的质量门禁同步守护文档把make lint与make test作为标准验证步骤。这两个 target 在 Makefile 中有明确定义可进一步拆解为make lintruff checkruff format --checklint-importsimport-linter 依赖方向校验随后依次运行scripts/check_repo_assets.py禁止提交图片/视频/资产目录、scripts/check_file_sizes.py文件大小硬门禁、scripts/check_deprecated_names.py产品命名门禁、scripts/check_github_contributor_docs.pyGitHub 贡献者文档门禁、scripts/check_datetime_discipline.pydatetime 双时区纪律扫描、scripts/dump_openapi.py --checkOpenAPI 漂移校验make testpytest tests/unit完整 CI 为make cilint test integration package其中package会构建 sdist/wheel 并做 wheel 导入冒烟测试。特别值得关注的是 scripts/check_github_contributor_docs.py——它是把同步守护规则代码化的关键防线。该脚本监控CLAUDE.md、CONTRIBUTING.md、docs/engineering.md、.github/PULL_REQUEST_TEMPLATE.md、.claude/skills/commit|new-branch|pr/SKILL.md七个文件扫描其中是否残留内部分支模型痕迹具体规则包括出现gitlab字样legacy hosting reference出现 merge request 措辞legacy review wording出现gitflow字样legacy branch model出现masterlegacy stable branch reference在分支工作流文件中出现devlegacy integration branch reference在分支工作流文件中出现hotfixlegacy emergency branch model。一旦命中即输出path:line:label:text形式的违规报告并以非零码退出阻止 CI 通过。这意味着即使某次 rsync 误把内部版本覆盖进 GitHubPR 阶段也会被这个脚本拦截——同步守护不仅是操作纪律更是一条自动化的硬门禁。同时make docs-check还会对.github/ISSUE_TEMPLATE/*.yml做 YAML 语法校验防止平台专属模板损坏。九、Review Checklist开 PR 前的逐项核对在 GitHub 上打开同步 PR 之前文档要求逐项确认CLAUDE.md写明分支从main创建.claude/skills/pr/SKILL.md创建 PR 时使用--base mainCONTRIBUTING.md说的是 GitHub pull request而非内部术语第 1 类的过时文件已删除make lint与make test通过没有.gitlab-ci.yml、.vscode/、local/、evaluation/泄漏进来这份清单与 scripts/check_github_contributor_docs.py 的监控范围高度吻合CLAUDE.md分支来源、PR 技能文件的 base、贡献文档的措辞也与 .github/BRANCH_PROTECTION.md 要求的 required status checksCommit lint / commit messages、Docs / links等形成闭环人工核对 CI 门禁双保险确保公开仓库始终呈现 GitHub 本位的协作模型。十、要点总结EverOS 的 GitHub Sync Guard 本质上是一套文件级镜像刷新的治理方案可以用三句话概括历史不同源同步靠文件GitLabdev与 GitHubmain无共享提交历史刷新只能通过打包导出 rsync 覆盖完成因此哪些文件被覆盖必须显式受控五类规则各司其职过时文件定点删除如 locomo 旧脚本、错误路径的_partition_locks.py、平台专属文件永久保留CI 工作流、Claude Code 技能、贡献指南、README/Makefile、其余内容全量覆盖、内部文件双向隔离守护已经代码化以 scripts/check_github_contributor_docs.py 为代表的校验脚本与 Makefile 的lint/docs-check/check-pr-title等 target会在 CI 阶段自动拦截内部术语与分支模型残留配合 .github/BRANCH_PROTECTION.md 的分支保护基线让GitHub 永远呈现正确的公开形态成为可验证的工程事实。对需要维护双仓库镜像的团队而言EverOS 这套同步守护给出了一个可复制的范本把平台差异显式登记成排除清单把删除项收敛成定点命令再把关键约束编码进 CI 门禁最终用一份 PR Review Checklist 收口。【免费下载链接】EverOSOne portable memory layer for every AI agent: local-first, Markdown-native, user-owned, and self-evolving across apps, tools, and workflows.项目地址: https://gitcode.com/gh_mirrors/ev/EverOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考