local-merge

/local-merge

通过一次性浅克隆将源分支合并到目标分支，然后仅当 PRIMARY 工作树已处于目标分支时，才更新该工作树。

默认目标分支为 main。

输入

输入	必填	默认值	示例
BRANCH	是	—	feat/local-merge-skill
TARGET	否	main	develop、release/v2
PRIMARY	否	主工作树路径	/Users/you/projects/repo
MESSAGE	否	merge: $BRANCH into $TARGET	merge: feat/auth into main

操作模式

将其视为两个独立问题：

1. 远程集成：在一次性浅克隆中将源分支合并到目标分支，然后推送更新后的目标分支。
2. 本地同步：如果 PRIMARY 已处于目标分支，则安全地更新该工作树。

不要假设远程集成成功就意味着本地同步也是安全的。

核心约束

• 仅使用本地 git 执行合并和发布操作。
• 优先使用一次性浅克隆作为集成工作区。
• 绝不丢弃已跟踪的本地状态。
• 如果已检出的本地目标分支含有仅存在于本地的提交，绝不在不告知的情况下选择合并还是变基。
• 仅当本地目标分支只是落后且可以干净地更新时，才自动快进。
• 遇到冲突就停止并交由用户处理。
• 绝不强制推送。
• 使用绝对路径，并在会更改状态的命令中使用 git -C <abs-path>。
• 构造 shell 命令之前先验证引用。

确定主工作树

将仓库的主工作树用作 PRIMARY。

如果主工作树路径不明确，应停止并询问用户，而不是根据偶然的顺序猜测。

已跟踪状态暂存保护

此技能需要在修改已检出的目标分支之前保留已跟踪的本地更改时，应始终采用同一种方案：

• 仅暂存已跟踪的更改
• 创建临时 WIP 提交
• 继续之前记录临时提交引用
• 更新分支
• 通过软重置该临时提交来恢复精确的已跟踪状态

此保护步骤中不要悄悄包含未跟踪文件。

阶段 1 — 远程集成

1. 确定状态

确定：

• 仓库根目录
• 源分支
• 目标分支
• 远程名称
• 主工作树路径
• PRIMARY 当前是否处于目标分支

验证：

• 源分支和目标分支都是有效的分支引用
• 两个分支的远程引用都存在

以下情况应停止：

• 源分支处于分离头状态
• 源分支尚未发布，且无法干净地推送

如果源分支尚未发布但可以干净地推送，则先推送它再继续。远程集成开始之前，源分支必须已发布。

如果源工作树有未包含在已发布分支中的已跟踪本地更改，应停止。local-merge 仅集成已发布的分支状态；阶段 1 不会保护或合并源分支一侧的未提交状态。

2. 创建集成工作区

从仓库的远程 URL 创建一次性浅克隆。

仅获取所需内容：

• <remote>/$TARGET
• <remote>/$BRANCH

确保克隆包含足够的历史记录以执行合并，并在需要时安全重试。如果浅历史记录不足，应有意加深历史记录，否则停止并说明限制。

3. 将源分支合并到目标分支

在浅克隆中检出目标分支，并将源分支合并到其中。

默认执行普通合并。如果合并已是快进，则接受。

如果发生冲突：

• 立即停止
• 清楚地说明冲突
• 不要自动解决冲突
• 不要继续推送

4. 推送目标分支

从浅克隆中推送更新后的目标分支。

如果因远程分支已变更而导致推送被拒绝，允许采用以下策略重试一次：

• 在浅克隆中更新目标分支
• 仅在一次性克隆中重新构建集成提交，或执行变基
• 仅当更新后的状态不会引入新的人工决策点时才重试

如果重试本身发生冲突或出现歧义，立即停止。

最多重试 3 次。绝不强制推送。

清理一次性克隆失败不影响流程。

阶段 2 — 本地同步

仅当 PRIMARY 已位于目标分支时，才运行此阶段。

如果 PRIMARY 位于其他分支，请报告远程集成已成功，并保持本地同步不变。

1. 检查本地目标状态

收集足够的证据，以判定本地目标分支的状态：

• 工作树是否有已跟踪的本地更改
• 本地 $TARGET 是否落后于 <remote>/$TARGET
• 本地 $TARGET 是否有不在 <remote>/$TARGET 上的提交
• 分支是否可以快进，或已发生分叉
• 即使 git 可以干净地合并，传入的更改与仅存在于本地的更改是否存在操作风险较高的重叠

使用标准 git 证据：

• 状态
• 超前和落后计数
• 传入提交日志
• 仅存在于本地的提交日志
• 差异统计

2. 更新本地目标分支

情况：工作树干净且仅落后

自动快进到 <remote>/$TARGET。

情况：存在已跟踪的本地更改且仅落后

使用已跟踪状态暂存机制，快进到 <remote>/$TARGET，然后恢复已暂存的已跟踪状态。

情况：本地目标分支有不在 <remote>/$TARGET 上的提交

不要默默改写或合并。

询问用户选择：

• 将本地提交变基到更新后的远程目标分支之上
• 将更新后的远程目标分支合并到本地目标分支

如果同时存在已跟踪的本地更改，请在该操作前使用已跟踪状态暂存机制，并在操作后恢复。

用户选择合并或变基后，Agent 可以执行该选择。如果所选操作发生冲突，立即停止，保留暂存引用（如果存在），并将控制权交还给用户。

这是相较于当前技能有意收紧的策略。即使可能进行低风险的自动合并，此版本仍将任何仅存在于本地的目标分支提交视为需要人工决策的情况。

情况：存在语义风险或歧义

如果 git 表示可以合并，但重叠区域存在较高的操作风险，请停止并升级处理，不要将“无文本冲突”视为“安全”。

例如：

• 配置分散在多个相关文件中
• 钩子和配套脚本被并行修改
• 命令约定发生变化，可能会使本地假设失效

完成

报告：

• 远程集成是否成功
• 是否运行了本地同步
• 本地目标分支是已快进、已升级处理，还是保持不变
• 是否暂存了已跟踪状态
• 是否仍需用户作出决定

安全规则

• 不得强制推送
• 除非收到明确指示，否则不得硬重置
• 不得默默解决冲突
• 对于已分叉的本地目标分支，不得默默选择合并或变基
• 人工状态优先于自动化

输出格式

Source branch: <branch>
Target branch: <target>
Remote: <remote>

Remote integration:
- source branch published: yes/no
- shallow clone merge: clean/conflict
- target pushed: yes/no

Local propagation:
- primary on target: yes/no
- tracked state shelter used: yes/no
- result: fast-forward / user decision required / conflict / skipped

If action is required:
- reason
- exact worktree or branch involved
- whether tracked state is currently sheltered