manual-branch-integrator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Manual Branch Integrator

手动分支集成工具

Integrate branch intent, not just patches. Prefer Git's merge machinery as a draft, then edit, refactor, audit, validate, and report the deliberate result.

Use clear branch terms throughout the task: the current

HEAD

branch is the destination branch, and

<source>

is the branch being integrated into it. If the user says "target branch" ambiguously, confirm whether they mean the source branch to merge or the destination branch to receive the work.

集成分支的意图，而非仅仅是补丁。将Git的合并机制作为草稿，然后对最终结果进行编辑、重构、审核、验证并提交报告。

在整个任务中使用清晰的分支术语：当前的

HEAD

分支是目标分支，

<source>

是要集成到其中的源分支。如果用户模糊地提到“目标分支”，请确认他们指的是要合并的源分支还是接收工作的目标分支。

Workflow

工作流程

Preflight the repository.
- Confirm the current destination branch, source branch, and whether the user wants whole-branch integration or partial adoption.
- Check state before modifying anything:
  bash
```
git status --short --branch
git merge-base HEAD <source>
git log --oneline --decorate --left-right --cherry-pick HEAD...<source>
```
- Refuse or ask before proceeding if unrelated uncommitted changes are present, if a merge/rebase is already in progress, or if the source branch is ambiguous.
- Record the merge base for the final report.
Build a source commit-intent ledger.
- Inspect every source commit from the merge base to the source branch, in order:
  bash
```
git log --reverse --oneline <base>..<source>
git show --stat --patch <commit>
```
- For each commit, record:
  - behavior added
  - behavior removed
  - files touched
  - tests or docs updated
  - diagnostics, temporary code, compatibility shims, or experiments later removed by follow-up commits
  - disposition: preserve, adapt to current structure, or intentionally reject with reason
- Treat deletions as first-class source intent. Removed UI text, helpers, fields, tests, diagnostics, compatibility paths, and summaries must be integrated or explicitly rejected.
Choose the integration mode.
- Default for whole-branch integration:
  bash
```
git merge --no-commit --no-ff <source>
```
- Treat the merge result as a draft, not an answer. Do not commit until conflicts are resolved, residual differences are classified, deletion greps are complete, and validation has run.
- Resolve conflicts by understanding both branches. Preserve current-branch behavior unless the source branch intentionally changes it. Refactor append-style conflict results into one coherent current-branch structure.
- Ask before choosing between two plausible product behaviors.
- Use pure manual transplant only when explicitly appropriate: partial adoption, intentionally linear history, source branch work that should not be recorded as merged, or a merge draft that would import broad unrelated history. Document why the merge-as-draft default was not used.

Map renamed or refactored paths.

Create a path map when the current branch renamed, split, or reorganized source files.
Apply source behavior into the current structure instead of resurrecting obsolete files.

text

source: app/renderer/workflow/ui/canvas/NodeSessionDialog.svelte
current: app/renderer/workflow/ui/canvas/CanvasNodeDetailsDialog.svelte
reason: current branch extracted a shared dialog frame and renamed the details dialog

Integrate deliberately.
- Implement each ledger item in its chosen destination.
- Keep the current branch's architecture and naming where it is intentional.
- Avoid compatibility layers, duplicate paths, and appended code unless they are required by real callers or the user explicitly wants a staged transition.
- If the source branch deliberately removed behavior, remove it from the current structure too unless the user approves keeping it.
Audit residual differences against the source branch.
- After integration, compare the result to the source branch:
  bash
```
git diff --stat <source>
git diff --name-status <source>
git diff <source> -- <relevant-or-mapped-files>
```
- Classify every meaningful residual difference as one of:
  - current-branch structure intentionally preserved
  - source behavior integrated under a different path
  - missed source behavior to fix before completion
  - intentionally rejected source behavior, with reason
- Do not report completion while any meaningful residual difference is unclassified.
Run deletion grep audits.
- For every behavior removed by the source branch, grep the current tree for names, labels, tests, helpers, fields, and distinctive strings that would reveal a missed deletion.
- Example:
  bash
```
rg "item\.summary|messageSummary|chars|blocks ·" app tests
```
- Record whether each pattern is absent, still present for an intentional reason, or a missed source deletion that must be fixed before completion.
Validate.
- Run relevant checks from existing repo scripts. Prefer targeted tests first, then broader checks when practical.
- In JavaScript/TypeScript repos, likely commands include:
  bash
```
bun run check
bun run test
bun run lint
bun run build
```
- If broad checks fail because of unrelated existing issues, run targeted validation and clearly separate unrelated failures from integration failures.
Final report.
- Include:
  - destination branch, source branch, and merge base
  - whether merge-as-draft or manual transplant was used, and why
  - source commit-intent ledger summary
  - where each source intent landed
  - path mappings used
  - residual differences from the source branch and the classification for each meaningful difference
  - deletion grep audit commands and results
  - files changed
  - validation commands and outcomes
  - remaining risks or user decisions

预检查仓库状态。
- 确认当前目标分支、源分支，以及用户是要集成整个分支还是部分内容。
- 在进行任何修改前检查状态：
  bash
```
git status --short --branch
git merge-base HEAD <source>
git log --oneline --decorate --left-right --cherry-pick HEAD...<source>
```
- 如果存在未提交的无关更改、已有合并/变基正在进行，或者源分支不明确，请拒绝操作或先询问用户再继续。
- 记录合并基准用于最终报告。
构建源提交意图台账。
- 按顺序检查从合并基准到源分支的每一个源提交：
  bash
```
git log --reverse --oneline <base>..<source>
git show --stat --patch <commit>
```
- 为每个提交记录：
  - 新增的行为
  - 删除的行为
  - 涉及的文件
  - 更新的测试或文档
  - 后续提交中移除的诊断代码、临时代码、兼容性垫片或实验性代码
  - 处理方式：保留、适配当前结构，或说明理由后明确拒绝
- 将删除操作视为一等源意图。被移除的UI文本、辅助工具、字段、测试、诊断代码、兼容路径及摘要必须被集成或明确拒绝。
选择集成模式。
- 全分支集成的默认方式：
  bash
```
git merge --no-commit --no-ff <source>
```
- 将合并结果视为草稿，而非最终答案。在解决冲突、分类剩余差异、完成删除内容的 grep 检查及验证通过前，不要提交。
- 通过理解两个分支来解决冲突。保留当前分支的行为，除非源分支有意更改它。将追加式的冲突结果重构为连贯的当前分支结构。
- 在两种合理的产品行为之间做选择前，请询问用户。
- 仅在明确适用的情况下使用纯手动移植：部分内容集成、有意采用线性历史、源分支工作不应记录为已合并，或合并草稿会引入大量无关历史。记录不使用默认“合并为草稿”方式的原因。

映射重命名或重构的路径。

当当前分支重命名、拆分或重组源文件时，创建路径映射。
将源分支的行为应用到当前结构中，而非恢复已废弃的文件。

text

source: app/renderer/workflow/ui/canvas/NodeSessionDialog.svelte
current: app/renderer/workflow/ui/canvas/CanvasNodeDetailsDialog.svelte
reason: current branch extracted a shared dialog frame and renamed the details dialog

审慎集成。
- 在选定的目标位置实现台账中的每一项内容。
- 保留当前分支中有意设计的架构和命名方式。
- 除非有实际调用者需要，或用户明确要求分阶段过渡，否则避免使用兼容层、重复路径和追加代码。
- 如果源分支有意移除了某些行为，除非用户批准保留，否则也要从当前结构中移除这些行为。
审核与源分支的剩余差异。
- 集成完成后，将结果与源分支进行比较：
  bash
```
git diff --stat <source>
git diff --name-status <source>
git diff <source> -- <relevant-or-mapped-files>
```
- 将每一个有意义的剩余差异分类为以下类型之一：
  - 有意保留当前分支的结构
  - 源分支的行为已集成到不同路径下
  - 遗漏的源分支行为，需在完成前修复
  - 明确拒绝的源分支行为，并说明理由
- 若存在未分类的有意义剩余差异，请勿报告完成。
运行删除内容的 grep 审核。
- 对于源分支移除的每一项行为，在当前代码树中 grep 相关名称、标签、测试、辅助工具、字段及独特字符串，以检查是否有遗漏的删除操作。
- 示例：
  bash
```
rg "item\.summary|messageSummary|chars|blocks ·" app tests
```
- 记录每个模式的状态：已不存在、因合理原因仍保留，或属于遗漏的源分支删除操作，需在完成前修复。
验证。
- 运行现有仓库脚本中的相关检查。优先运行针对性测试，在可行情况下再进行更全面的检查。
- 在JavaScript/TypeScript仓库中，常用命令包括：
  bash
```
bun run check
bun run test
bun run lint
bun run build
```
- 如果全面检查因无关的现有问题失败，请运行针对性验证，并明确区分无关失败与集成失败。
最终报告。
- 报告应包含：
  - 目标分支、源分支及合并基准
  - 使用的是“合并为草稿”还是手动移植方式，以及原因
  - 源提交意图台账摘要
  - 每项源意图的落地位置
  - 使用的路径映射
  - 与源分支的剩余差异及每个有意义差异的分类
  - 删除内容的 grep 审核命令及结果
  - 更改的文件
  - 验证命令及结果
  - 剩余风险或需用户做出的决策

Guardrails

约束规则

Do not commit a mechanical merge result just because conflicts are resolved.
Do not lose source-branch deletions during a hand transplant.
Do not restore obsolete files merely to make diffs look closer to the source branch when current-branch structure intentionally changed.
Do not claim exact patch equivalence is required when behavior legitimately landed under different paths.
Do not hide unresolved product choices; ask the user.

不要仅仅因为冲突已解决就提交机械合并的结果。
在手动移植过程中不要丢失源分支的删除操作。
当当前分支结构已有意更改时，不要仅仅为了让差异更接近源分支而恢复已废弃的文件。
当行为合法地落地到不同路径下时，不要要求完全的补丁等价性。
不要隐藏未解决的产品选择问题；请询问用户。