核心用法
fork-manager 是一套面向开源贡献者的完整 Fork 管理解决方案，解决"提了 PR 但上游迟迟不合并，自己又需要提前使用这些改进"的典型痛点。技能采用 Orchestrator + Worker 架构，主代理负责任务分发和监控，子代理执行具体操作，确保长时间任务（如 145+ PR 的 rebase）不阻塞主会话。
主要工作流程：
- status：快速诊断 Fork 与上游的差距、PR 状态
- sync：将主分支同步到上游最新
- rebase-all：批量 rebase 所有 PR 分支
- build-production：构建包含所有开放 PR + 本地补丁的生产分支
- full-sync：完整自动化流程（sync → update-config → review-closed → audit-open → rebase-all → resolve-conflicts → build-production）
智能冲突解决（--auto-resolve）：
当启用自动冲突解决时，系统会 spawn 最多 5 个 Opus 子代理并行处理冲突。结果分级为：
- trivial（机械冲突，如 import/formatting）—— 自动解决并推送，无需人工审查
- semantic（业务逻辑冲突）—— 自动解决但标记 ⚠️ 需人工复核
- unresolvable —— 标记 ❌ 并上报，不推送
本地补丁（localPatches）管理：
独特支持被上游拒绝/关闭的 PR 转为本地长期维护补丁，包含完整元数据（关闭原因、保留理由、定期复查日期），解决"上游不要但我需要"的场景。
显著优点
1. 生产级架构：Orchestrator/Worker 模式 + 4 分钟健康检查 + 自动重试（最多 2 次）+ checkpoint 恢复，确保长时间任务可靠完成
2. GitHub 原生集成：使用 gh CLI 作为真实数据源，本地 config 仅为缓存，避免状态漂移
3. 智能冲突分级：区分机械冲突与语义冲突，前者全自动，后者辅助决策
4. PR 全生命周期管理：从创建、rebase、冲突、合并/关闭到转为本地补丁或彻底清理
5. 审计与冗余检测：自动识别「上游已解决」「外部重复 PR」「自有 PR 重叠」三类冗余
6. Cron 友好：支持定时自动运行，紧凑输出格式，失败 checkpoint 便于下次恢复
潜在缺点与局限性
1. 依赖外部工具链：必须安装 git 和 gh CLI，且 gh 需要有效认证
2. 冲突解决非 100% 可靠：语义冲突依赖 LLM 理解代码意图，存在误判风险
3. 网络密集型：频繁 fetch GitHub API，大量 PR 场景可能触发速率限制
4. 仅支持特定工作流：假设用户是 Fork 所有者、通过分支提 PR，不适用于直接上游分支推送模式
5. 自动推送风险：--force-with-lease 虽安全，但 rebase 后分支历史被重写，协作方需协调
6. 学习曲线：config.json 结构复杂，初次配置需理解 openPRs/prBranches/localPatches 三层抽象
适合人群
- 活跃开源贡献者：同时维护 5+ 开放 PR，需要定期与上游同步
- Fork 长期维护者：基于上游项目构建自己的发行版（distribution），需要合并未合并补丁
- 企业内源团队：内部 Fork 开源项目，部分改进提交上游、部分仅内部使用
- PR 依赖链开发者：PR B 依赖 PR A 未合并，需要构建集成测试环境
常规风险
| 风险 | 说明 | 缓解措施 |
|------|------|----------|
| **数据丢失** | rebase/force push 可能丢失分支历史 | 使用 `--force-with-lease` 而非 `--force`；操作前自动 stash |
| **代码语义错误** | AI 自动解决的语义冲突可能逻辑错误 | semantic 冲突标记 ⚠️ 强制人工复核；3+ 周期冲突升级提醒 |
| **GitHub API 限流** | 大量 PR 查询可能触发 rate limit | 本地 caching（config.json）；合理设置 cron 间隔 |
| **Token 泄露** | `gh` CLI 依赖的 token 若泄露可写操作 | 使用最小权限 token；CI 场景使用短期凭证 |
| **意外删除分支** | 误判 PR 状态可能导致分支被删 | 关闭 PR 必须经过 `review-closed` 交互确认，永不自动删除 |