Fork Manager

核心功能

Fork Manager 是一套完整的 Fork 仓库工作流管理方案，专为"既是贡献者又是使用者"的场景设计。核心能力覆盖四大维度：

1. 上游同步与分支维护

• 自动检测主分支落后上游的 commit 数量
• 安全同步（使用 --force-with-lease 防止数据丢失）
• 批量变基所有 PR 分支到最新上游

2. PR 全生命周期管理

• Open PRs：持续跟踪未合并贡献，自动检测是否需要变基
• Closed/拒绝 PRs：交互式决策流——彻底删除、转为本地补丁、或重新提交
• Merged PRs：自动清理并归档

3. 本地补丁系统（核心差异化）

支持将"上游拒绝/不修复但自身需要"的代码转为长期维护的本地补丁：

• 完整元数据追踪（原始 PR、关闭原因、保留理由、复查日期）
• 自动参与生产分支构建
• 定期复查机制（防止上游已修复但本地仍保留）

4. 智能审计与冗余检测

• Upstream 已解决：检测 PR 内容是否被上游其他提交覆盖
• 外部重复：发现他人提交的相似 PR
• 内部重复：检测自身多个 PR 间的文件冲突

显著优势

| 维度 | 优势 |

|------|------|

| **工作流完整性** | 覆盖从日常同步到季度清理的全周期，而非零散命令 |

| **数据安全** | 强制 stash 保护未提交文件、`--force-with-lease` 防覆盖、append-only 历史日志 |

| **决策可追溯** | `history.md` 完整记录每次操作，支持多 agent 协作 |

| **补丁治理** | 将"被拒绝的 PR"从负担转化为可管理的资产，含到期提醒机制 |

| **冲突预防** | 生产分支按"PR 优先、补丁次之"的顺序合并，最大化兼容性 |

潜在局限与风险

技术局限

• GitHub 依赖：重度依赖 gh CLI，暂不支持 GitLab/Gitee 等平台
• 交互瓶颈：review-closed、audit-open 等关键步骤需人工决策，无法完全自动化
• 冲突处理：复杂变基仍需手动介入，工具仅定位问题

操作风险

| 场景 | 风险等级 | 说明 |

|------|---------|------|

| `build-production` 强制重建 | 中高 | 删除并重建分支，虽有 stash 保护，但脚本中断可能导致状态混乱 |

| `rebase-all` 批量强制推送 | 中 | `--force-with-lease` 降低风险，但仍可能与他人协作冲突 |

| 本地补丁长期未 review | 低 | 可能积累技术债务，但功能正常 |

安全考量

• 需要 GitHub token 具备 repo 权限读取 PR 详情
• 本地 config 存储完整仓库路径信息（无敏感凭据）

适合人群

核心用户画像：

• 向开源项目贡献 PR，但不能等待合并即需使用修复的开发者
• 维护长期 fork 的企业/团队（需保留私有补丁同时跟踪上游）
• 多 PR 并行开发者（5+ 开放 PR，需系统性管理变基冲突）

不适合：

• 纯使用者（无贡献需求）
• 完全自动化 CI/CD 场景（需人工决策环节）
• 非 GitHub 生态用户

常规风险提示

1. 首次使用前：确保 gh 已认证且有足够权限，建议先对非关键仓库测试
2. 生产分支：重建后需手动运行项目构建命令（工具会提醒但不执行）
3. 定期维护：建议每周运行 full-sync，避免变基债务累积
4. 多人协作：若团队共享 fork，需协调 productionBranch 更新时机

核心用法

fork-manager 是一款专为开源贡献者设计的 Git 仓库管理技能，主要解决"维护 Fork 的同时使用未合并改进"的痛点。它通过配置文件驱动的方式，支持多个仓库的并行管理。

核心工作流围绕以下几个命令展开：status 快速查看 Fork 与上游的差异；sync 将主分支同步到最新上游；rebase-all 批量处理所有 PR 分支的变基；build-production 构建包含所有未合并改进的生产分支；full-sync 执行完整的同步流水线。

该技能采用声明式配置，每个仓库拥有独立的 config.json，记录仓库元数据、开放的 PR 列表、分支映射以及本地补丁信息。执行历史以 append-only 的 history.md 形式保存，便于审计和问题追踪。

显著优点

1. 完善的本地补丁管理

与传统 Fork 管理工具不同，该技能将"本地补丁"（local patches）作为一等公民。当上游 PR 被拒绝或长期未合并时，用户可以将其标记为本地补丁，持续维护在独立分支中，并在生产构建时自动合并。每个补丁都包含完整的元数据：原始 PR 编号、关闭原因、保留理由、创建时间和复审日期。

2. 智能的 PR 状态审计

audit-open 功能 proactively 检测 PR 冗余：上游是否已通过其他方式解决相同问题？是否有外部贡献者提交了类似的 PR？自己的多个 PR 是否存在代码重叠？这种审计机制避免了维护无效的 PR，减少维护负担。

3. 安全的操作流程设计

代码体现良好的安全意识：所有强制推送使用 --force-with-lease 而非 --force，防止意外覆盖远程提交；在执行 build-production 等破坏性操作前自动 stash --include-untracked，保护未提交文件；每次执行完整记录到历史日志，支持追溯。

4. 人机协作的决策流程

对于 PR 被关闭等复杂场景，技能不会自动删除分支，而是启动交互式审查流程，向用户呈现上下文信息（关闭原因、维护者评论、替代方案），由用户决定：丢弃、转为本地补丁、修改后重新提交或暂缓处理。

潜在缺点与局限性

1. 依赖外部工具环境

该技能完全依赖用户本地已安装的 git 和 gh (GitHub CLI) 工具，不自带任何运行时环境。如果用户未配置 GitHub CLI 认证，或使用的代码托管平台不支持 gh（如 GitLab、Bitbucket），则无法使用。

2. 配置维护成本

虽然声明式配置提供了灵活性，但也意味着用户需要手动维护 config.json 中的 PR 列表和分支映射。对于高频贡献者，PR 数量多时代价较高。update-config 命令可部分缓解，但仍需人工确认。

3. 冲突处理仍需人工介入

当 rebase-all 或 build-production 遇到合并冲突时，技能会暂停并提示用户手动解决。这意味着无法完全无人值守运行，需要开发者保持在线。

4. 文档语言不统一

当前 SKILL.md 混合使用英语和葡萄牙语（如 "Formato do config.json"），可能影响非葡萄牙语用户理解。

适合的目标群体

该技能最适合以下用户群体：

• 活跃的开源贡献者：经常向上游提交 PR，同时需要在本地提前使用这些改进
• 下游发行版维护者：维护基于上游项目的定制版本，需要跟踪和整合上游变更
• 企业内源开发者：在内部 GitHub 环境中，需要同步中央仓库并管理本地定制
• 长期分支维护者：因工作流原因，PR 长期未合并，需要系统化管理"待上游化"的代码

不适合纯终端用户（不贡献代码、不维护 Fork）以及使用非 GitHub 平台的用户。

使用风险

性能风险：full-sync 执行大量 Git 操作（fetch、rebase、merge、push），在大型仓库或网络不稳定时可能耗时较长。建议避免在关键工作时间运行。

数据风险：虽然技能设计了 stash 保护，但 build-production 会强制重建生产分支（git branch -D + git checkout -b）。如果用户在工作目录中有未跟踪的敏感文件（如 .env、密钥），且未正确配置 .gitignore，存在意外暴露风险。

配置漂移风险：config.json 与实际的 GitHub PR 状态可能不一致。如果用户在其他界面（GitHub Web）关闭了 PR 但未更新配置，技能会基于过时信息执行操作。

权限风险：技能需要 git push --force-with-lease 权限，如果配置错误（如 originRemote 指向了上游而非 Fork），可能意外污染上游仓库。建议首次使用前在测试仓库验证配置。