aerologic-app/.claude/skills/sync-air-cargo/SKILL.md

name, description

name	description
sync-air-cargo	将 aerologic-app 的变更以文件级 cp/rm 方式同步到项目根目录下的 air-cargo/ 仓库并在其本地提交（不 push）——两者是同一份源码的两个独立 git 仓库副本，分别推送到不同的远程地址。同步点记录在 air-cargo 提交信息的 Synced-From trailer 中，自动从上次同步点同步到 main 最新提交（覆盖已提交未 push、已 push 的变更），也支持只同步未提交的工作区变更。只做文件复制/删除，不对内容做任何二次编辑或转换。每当用户提到"同步到 air-cargo"、"同步到另一个仓库/项目"、"推送/复制到 cargo 项目"、"两个项目要保持一致"、"把某几个 commit 同步过去"，或者在 aerologic-app 里改完代码后问要不要同步/推送到另一个仓库时，应主动使用此 skill，而不是手动逐个 cp 文件。

同步变更到 air-cargo

背景

aerologic-app 和 air-cargo 是同一份项目源码的两个独立 git 仓库副本，分别推送到不同的远程仓库地址。日常开发只在 aerologic-app 中进行，完成后把变更同步到 air-cargo 并在本地提交，push 由用户自己做。

• 位置：air-cargo 在 aerologic-app 根目录下（/Users/tim/Development/Projects/aerologic-app/air-cargo/），已在 aerologic-app 的 .gitignore 中忽略
• 分支映射（config 文件）：aerologic-app main → air-cargo feature/hefei。air-cargo 的 develop 是 2023 年的旧快照，不能往上同步；当前分支不是 feature/hefei 时脚本直接报错
• 不参与同步：CLAUDE.md / CLAUDE.local.md、.claude/ 目录、根目录 .claude.*（如 .claude.local.md）与 .mcp.json（Claude Code 的配置/记忆），不复制也不删除。air-cargo 中不应存在任何 Claude / Agent 相关文件，其本地 .git/info/exclude 已屏蔽这些文件名，防止误提交
• air-cargo 只是提交通道：不参与本项目开发，代码扫描、功能实现、查历史时都忽略它（见 CLAUDE.md「air-cargo 目录」一节）

同步点：air-cargo 提交信息里的 Synced-From trailer

每次同步提交的信息只有一句带日期的通用语句加一个 trailer，不写修改明细：

Update 20261012

Synced-From: aerologic-app@388d6058696c05cfd5892018f52120880a440524

脚本以 air-cargo 当前分支上最近一个 Synced-From 作为基线，把 基线..main 的变更同步过去。记录跟着 air-cargo 的提交历史走，只有真正提交了才算数。

• 区间模式（默认）：基线 = 最近的 Synced-From，目标 = aerologic-app main 最新提交。文件内容从目标提交对象中读取，与 aerologic-app 工作区无关，因此已 commit 未 push、已 push 的变更都用它。提交时写入新的 Synced-From
• 工作区模式（--worktree）：同步 aerologic-app 未提交的变更。提交信息不写 Synced-From，因为这份内容不对应任何提交，不能推进同步点。之后这些改动在 aerologic-app 提交后，下次区间同步会再覆盖一次（内容相同，无副作用）
• 兜底：按内容反推：找不到 Synced-From 时（首次同步，或有人手工提交时丢了 trailer），在 main 的第一父链上找与 air-cargo HEAD 内容差异最少的提交作为候选基线。只用于预览，apply 必须显式传 --base
• 基线校验：每次预览都会比较 air-cargo HEAD 和基线的内容。正常情况下只剩 air-cargo 自己的 6 个元文件：.gitignore（air-cargo 额外忽略 *.jks）、key密码、CONTRIBUTING.md、备忘录.md、国际出港进港权限对照表.xlsx、.docs/大写字母数字输入过滤器使用指南.md。超过 50 个会提示基线或分支可能不对

使用方法

cd /Users/tim/Development/Projects/aerologic-app
bash .claude/skills/sync-air-cargo/scripts/sync.sh [preview|apply] [--base <ref>] [--to <ref>] [--worktree] [--label <word>]

参数	说明
preview / apply	默认 preview，只打印计划；apply 复制/删除并在 air-cargo 本地提交
--base <ref>	指定基线：反推结果经确认后传入，或用来纠正错误的同步点
--to <ref>	指定目标提交，默认 main（只同步到某个较早的提交时使用）
--worktree	工作区模式，不能和 --base/--to 同时用
--label <word>	提交信息的通用词，默认 Update。用户要求时可换成 Fixed、Optimized 等

步骤

1. 预览：先确定模式——用户要同步已提交的代码用默认区间模式；明确说的是"没提交的改动"才加 --worktree。然后执行 sync.sh（区间模式不加参数）。
   • 输出「无需同步」：直接告诉用户，结束
   • 基线来源是「按内容反推」：把候选基线连同基线校验结果一起拿给用户确认（反推可能取到比预期更早的提交，例如 air-cargo 从未同步过的环境配置提交），确认后加 --base <sha> 再预览一次
2. 用 AskUserQuestion 确认，不要只在文字里问一句。问题描述里要包含：基线 → 目标、区间提交数、待复制/待删除数量（及主要模块分布）、「⚠ 将覆盖 air-cargo 侧独立修改」清单（逐个列出）、提交信息。选项至少包含「确认同步并提交」和「取消」。覆盖清单不为空时要特别说明这些文件是 air-cargo 自己改过的（如 .gitignore 里的 *.jks 忽略），由用户决定。
3. 执行：把预览时的参数原样带上，preview 换成 apply。脚本会复制/删除文件、精确暂存这些路径并提交，最后输出提交号和变更统计。
4. 不要 push。向用户报告提交号，并说明 air-cargo 比 origin/feature/hefei 超前几个提交，push 由用户自己做。

脚本的保护措施

• air-cargo 当前分支不是 config 里的 TARGET_BRANCH → 报错
• air-cargo 工作区有本次同步范围以外的未提交改动 → 报错；范围内的改动（例如上次同步还没提交）允许，重跑会覆盖成相同内容
• 基线不是目标的祖先（aerologic-app 被 rebase / force-push 过）→ 报错，用 --base 重新指定
• 区间内只有不参与同步的文件变化 → 仍然提交一个空提交，推进同步点

注意事项

• 只同步 git 跟踪的内容，.gitignore 忽略的构建产物（build/、.gradle/）不会同步，air-cargo/ 本身也不在变更清单里
• 不要在 air-cargo 里手动提交同步内容。如果确实手动提交了，trailer 格式必须完全一致（Synced-From: aerologic-app@<完整 sha>），否则下次只能走反推
• 首个同步点：2026-10-12，air-cargo 3dd792f9，对应 aerologic-app 388d605（基线选 871fa4c）。跳过的 dda0ff8（vfox→mise）随后在 air-cargo 单独提交 3c76385b 补上：删除 .tool-versions / .vfox.toml / .vfox/，新增与 aerologic-app 相同的 mise.toml。这个提交不带 trailer，同步点不变
• 两个仓库都用 mise 管理 JDK（mise.toml：java = "17"）。air-cargo 位于 aerologic-app 之下，mise 会逐级读取配置，所以 air-cargo 里不能再出现 .tool-versions，否则会覆盖成未安装的旧版本