feat(sync-air-cargo): 以 Synced-From trailer 记录同步点，同步后自动在 air-cargo 本地提交

- 默认区间模式：基线取 air-cargo 最近的 Synced-From，目标为 main，内容取自提交对象
- 无记录时按内容反推基线（仅预览，apply 须 --base 确认），每次预览做基线校验
- 新增三方校验，列出将覆盖的 air-cargo 侧独立修改；分支/工作区/祖先关系保护
- --worktree 同步未提交变更且不推进同步点；提交信息仅「<Label> <日期>」+ trailer，不 push
- 新增 config（main → feature/hefei，air-cargo 位于项目根目录）
- 排除清单补充 .mcp.json、.claude.*、CLAUDE.local.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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

@@ -1,49 +1,70 @@
 ---
 name: sync-air-cargo
-description: 将 aerologic-app 项目中未提交的变更（已修改、新增、已删除、包括未跟踪的文件）以文件级 cp/rm 方式同步到同级目录下的 air-cargo 项目——两者是同一份源码的两个独立 git 仓库副本，分别推送到不同的远程地址。只做文件复制/删除，不对内容做任何二次编辑或转换。每当用户提到"同步到 air-cargo"、"同步到另一个仓库/项目"、"推送/复制到 cargo 项目"、"两个项目要保持一致"，或者在 aerologic-app 里改完代码后问要不要同步/推送到另一个仓库时，应主动使用此 skill，而不是手动逐个 cp 文件。
+description: 将 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`，再由用户在 `air-cargo` 里自行提交、推送。
+`aerologic-app` 和 `air-cargo` 是同一份项目源码的两个独立 git 仓库副本，分别推送到不同的远程仓库地址。日常开发只在 `aerologic-app` 中进行，完成后把变更同步到 `air-cargo` 并在本地提交，**push 由用户自己做**。
 
-同步的判定完全基于 `git status`：在 `aerologic-app` 里，工作区中存在的文件（无论是修改、新增还是未跟踪）就复制覆盖到 `air-cargo` 对应路径；工作区中已不存在的文件（即被删除的）就在 `air-cargo` 里删除对应路径。这样天然覆盖了修改/新增/删除/未跟踪/重命名（重命名会被当作"删除旧路径 + 新增新路径"处理）等所有情况，不需要逐个状态码去分支判断。
+- **位置**：`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 目录」一节）
 
-**只同步工程项目本身的文件**：`CLAUDE.md` 以及 `.claude/` 目录（包括其下的 `skills/`、`commands/`、`settings.local.json`、`mcp.json` 等）属于 Claude Code 的工具配置/记忆，两个仓库各自独立维护，不属于"项目源码"，因此始终排除在同步范围之外，不会被复制也不会被删除。脚本会在输出里单独列出"已忽略，不参与同步"的清单，方便核对。
+## 同步点：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 个会提示基线或分支可能不对
 
 ## 使用方法
 
-脚本位于 `scripts/sync.sh`，用法：
-
 ```bash
-bash scripts/sync.sh [SOURCE_DIR] [TARGET_DIR] [preview|apply]
+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>]
 ```
 
-- `SOURCE_DIR` 默认为当前目录（一般就是 aerologic-app 项目根目录）
-- `TARGET_DIR` 默认为 `SOURCE_DIR` 同级的 `air-cargo` 目录，一般不需要手动指定
-- 第三个参数默认 `preview`（只打印清单，不做任何改动），传 `apply` 才会真正执行复制/删除
+| 参数 | 说明 |
+|------|------|
+| `preview` / `apply` | 默认 `preview`，只打印计划；`apply` 复制/删除并在 air-cargo 本地提交 |
+| `--base <ref>` | 指定基线：反推结果经确认后传入，或用来纠正错误的同步点 |
+| `--to <ref>` | 指定目标提交，默认 `main`（只同步到某个较早的提交时使用） |
+| `--worktree` | 工作区模式，不能和 `--base`/`--to` 同时用 |
+| `--label <word>` | 提交信息的通用词，默认 `Update`。用户要求时可换成 `Fixed`、`Optimized` 等 |
 
 ### 步骤
 
-1. **先预览**，让用户看到将要发生什么：
-   ```bash
-   bash /Users/kid/Development/Fusion/Projects/aerologic-app/.claude/skills/sync-air-cargo/scripts/sync.sh
-   ```
-   输出会分别列出"待复制/覆盖"和"待删除"的文件清单。
+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 由用户自己做。
 
-2. **用 `AskUserQuestion` 工具向用户确认**，不要只是在文字里问一句让用户打字回复。这是一个会覆盖 `air-cargo` 中已有文件、且删除操作不可逆的操作，必须先把预览清单（待复制、待删除的文件数量和列表）放进问题描述里，让用户能一眼看到影响范围，选项至少包含"确认同步"和"取消"。得到确认后才能继续执行 `apply`（这遵循整体规则：覆盖性/破坏性操作需要用户确认，不要因为 skill 本身能直接跑就跳过确认）。
+### 脚本的保护措施
 
-3. **用户确认后执行同步**：
-   ```bash
-   bash /Users/kid/Development/Fusion/Projects/aerologic-app/.claude/skills/sync-air-cargo/scripts/sync.sh . /Users/kid/Development/Fusion/Projects/air-cargo apply
-   ```
-   执行完会输出"复制/更新 N 个文件，删除 M 个文件"的汇总。
-
-4. **同步之后不要自动 commit/push**。脚本只做文件复制，`air-cargo` 那边的 `git add` / `commit` / `push` 由用户自行决定和操作——两个仓库指向不同的远程地址，提交推送这类会影响远程共享状态的操作应始终由用户主导确认。
+- air-cargo 当前分支不是 `config` 里的 `TARGET_BRANCH` → 报错
+- air-cargo 工作区有本次同步范围**以外**的未提交改动 → 报错；范围内的改动（例如上次同步还没提交）允许，重跑会覆盖成相同内容
+- 基线不是目标的祖先（aerologic-app 被 rebase / force-push 过）→ 报错，用 `--base` 重新指定
+- 区间内只有不参与同步的文件变化 → 仍然提交一个空提交，推进同步点
 
 ## 注意事项
 
-- 脚本只识别 git 能感知到的变更（`git status` 看得到的），`.gitignore` 忽略的文件（如构建产物 `build/`、`.gradle/`）不会被同步，这也是符合预期的——不应该把本地构建缓存同步过去。
-- 如果 `air-cargo` 里对应路径本身也有未提交的本地修改，会被直接覆盖覆盖掉，预览阶段要留意这一点并提醒用户。
+- 只同步 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`，否则会覆盖成未安装的旧版本