核心用法
fork-manager 是一套完整的 Fork 生命周期管理方案，面向持续向开源项目贡献代码的开发者。其工作流程涵盖：
1. 同步上游（sync） – 将 fork 的 main 分支与上游仓库保持同步，记录 commit 范围
2. 配置更新（update-config） – 以 GitHub API 为单一事实来源，刷新 openPRs 缓存，自动检测 PR 被重新打开、分支重命名、已合并或关闭等状态变更
3. 闭环审核（review-closed / audit-open / review-patches） – 对关闭的 PR 提供「丢弃/保留为本地补丁/重新提交」的交互式决策；对开放 PR 检测上游已修复或重复实现；对本地补丁按 reviewDate 定期复核
4. 批量 rebase（rebase-all） – 将所有 PR 分支及本地补丁分支依次 rebase 到最新 upstream/main
5. 冲突自动解决（resolve-conflicts） – 在 --auto-resolve 标志或配置启用时，派生最多 5 个 Opus 子代理并行处理冲突，结果分为 trivial（无需审阅）、semantic（需人工复核）、unresolvable（失败上报）
6. 生产分支构建（build-production） – 从 upstream/main 新建 productionBranch，按序合并所有 open PRs 与 local patches，生成可直接部署的聚合分支
显著优点
- 编排器-工作器（Orchestrator-Worker）架构：主代理仅做调度，重任务派生子代理执行，避免上下文窗口污染，支持失败恢复与超时重试
- GitHub 为唯一事实来源：本地 config 仅作缓存，任何依赖 PR 列表的操作前强制刷新，消除状态漂移
- AI 驱动的冲突解决：通过子代理自动处理 import、formatting、文件删除等机械冲突，对业务逻辑冲突标记待审，显著降低维护负担
- 本地补丁一等公民：将「被拒绝/不修复」的 PR 转为 localPatches 长期维护，支持独立的 reviewDate 与元数据追踪
- 完善的审计与防丢失机制：强制 stash 保护未提交文件、force-with-lease 防止覆盖他人提交、checkpoint.json 支持断点续传
潜在缺点与局限性
- 重度依赖 GitHub CLI：需预装并认证
gh，且对 GitHub Enterprise Server 的支持取决于 gh 版本 - 冲突解决质量不可完全保证：AI 子代理对复杂业务逻辑冲突可能产生「表面解决但语义错误」的结果，semantic 级结果必须人工复核
- 并发与成本：自动冲突解决模式下最多同时运行 5 个 Opus 子代理，长耗时任务可能产生较高 token 消耗
- 学习曲线陡峭：config.json 字段繁多（openPRs、prBranches、localPatches、notes 等），初期配置需要仔细阅读文档
- 仅限 fork 场景：不适用于非 fork 仓库的通用 PR 管理或 issue 梳理（需转用
github或issue-prioritizerskill）
适合人群
- 长期维护大型开源项目 fork、同时保持多个未合并 PR 活跃的高频贡献者
- 需要「生产分支」聚合所有自用补丁（含上游拒绝的功能）的内部发行版维护者
- 希望自动化「每日同步上游 + rebase + 解决冲突」流水线的DevOps/平台工程师
常规风险
| 风险场景 | 缓解措施 |
|----------|----------|
| 未提交文件在 branch 切换时被覆盖 | 强制 `--include-untracked` stash 保护 |
| force push 误删他人提交 | 统一使用 `--force-with-lease` |
| AI 解决冲突引入静默 bug | semantic 结果强制标记 ⚠️ 待人工复核 |
| 长期冲突循环消耗资源 | 3+ 次循环自动升级为「🔴 持久冲突」并建议丢弃/重建 |
| Token/凭据泄露 | 依赖 gh 的认证体系，建议配置最小权限 Personal Access Token |