Apifox 分支协作与 AI 写入：在指定分支上安全修改…

当需要用 Apifox CLI 在分支上修改资源、创建 AI 分支、pick-to、合并分支或处理 AI 写入权限时使用。

适用场景

解决思路

1. 先阅读 ../apifox-cli/SKILL.md；若旧总入口与本 skill 的领域规则冲突，以当前 CLI help 和本 skill 为准。
2. 具体命令参数以当前 CLI help 为准。
3. 在分支上写入后，必须用同一 --branch 回读和验证，不要跨分支用默认视角判断资源是否存在。
4. 分支写入前先问清楚用户要哪种方式：直接编辑目标分支，或通过 AI 分支编辑。
5. 直接编辑目标分支：适合用户明确允许直接修改，且目标分支没有保护或权限限制。
6. 通过 AI 分支编辑：适合 AI 代改接口、测试用例、测试场景或配置；也适合目标分支受保护、未开启外部 AI 直接写入，或用户希望先隔离验证再合并。
7. 开始写入前必须确认项目 ID。
8. 开始写入前必须确认源分支和目标分支。
9. 开始写入前必须确认要修改的资源范围。
10. 开始写入前必须确认是否允许后续创建 merge request 或直接合并。
11. AI 分支流程：确认源分支和目标变更 -> 创建 AI 分支 -> pick-to 已有资源 -> 在 AI 分支修改 -> 验证 get/run/report -> preview merge-request -> 用户确认后 create merge-request 或 merge。
12. 创建 AI 分支时指定来源：--from <sourceBranchName>。
13. 使用规范名称：ai/年月日-from-来源分支名-功能或模块名，例如 ai/20260312-from-main-userRegister。
14. 修改源分支已有资源前，先用 branch pick-to 导入到 AI 分支；新建资源不需要 pick-to。
15. 在 AI 分支上修改、查询、验证时都带 --branch <aiBranchName>。
16. 按资源类型验证结果，例如 get、run、本地报告或云端报告检查。
17. 合并前先 merge-request preview，让用户确认影响范围。
18. 用户确认后，再 merge-request create 或 branch merge；目标主分支受保护时优先 merge request。
19. AI 分支初始为空，不会自动复制源分支全部资源。
20. branch get 可能返回 type: SPRINT 且 isAiBranch: true；这不代表操作时应使用 --type sprint。AI 分支相关操作仍按当前 help 使用 --type ai。
21. 分支参数优先使用分支名：--branch <branchName>。
22. 兼容纯数字 branchId，但分支名更直观，日志和排障更清楚。
23. 同一任务内查询、创建、更新、运行测试必须带同一个分支上下文，避免在 main/default 视角找不到资源。
24. pick-to 必须带 --type ai。
25. pick-to 只支持从主分支或普通迭代分支导入到 AI 分支。
26. pick-to 不能导入到主分支。
27. pick-to 不能以 AI 分支作为来源分支。
28. 使用 --include-endpoint-cases 可在导入接口时同时导入接口用例。
29. 主分支、迭代分支、通用分支可能要求开启“外部 AI 编辑权限”。
30. 典型错误信息包含 Automation caller branch required。
31. 创建 AI 分支可能成功，但写入 AI 分支内容仍可能因“允许 AI 修改 AI 分支内容”关闭而失败。
32. 遇到写入受限，不要自动切策略；让用户选择开启直接编辑权限，或改走 AI 分支。
33. 目标主分支受保护时，优先 merge-request preview/create，不要直接 branch merge。
34. 不要在用户未确认时创建 AI 分支。
35. 不要在 AI 分支里修改源分支已有资源而不先 pick-to。
36. 不要在分支任务中省略 --branch <branchName>。
37. 不要在用户未确认时 merge、create merge-request 或审批 merge request。
38. 不要删除、归档分支，除非用户明确要求。
39. 遇到 Automation caller branch required 时，必须停下来问用户选择权限策略，不要自动创建或切换 AI 分支。
40. get 不带 branch 找不到资源时，带 --branch <branchName> 重试。
41. AI 分支里找不到源资源时，先 branch pick-to 导入。
42. projectBranchState 有计数但 AI 分支页面为空时，不要误判为已导入；AI 分支仍需 pick-to。
43. run-config 在分支下 404 时，确认 case/endpoint/environment/branch 均存在后转 apifox-cli-checkup。
44. merge 被保护分支拦截时，改走 merge-request。
45. 分支管理命令入口：apifox branch --help。
46. 合并请求命令入口：apifox merge-request --help。
47. 资源命令通常都支持 --branch <branchName>；查询、创建、更新、运行测试时保持同一个分支上下文。

适用边界 · 注意事项

• 未获得用户明确确认时，不要创建 AI 分支、merge、create merge-request、审批 merge request、删除或归档分支。
• 目标主分支受保护或权限受限时，不要直接 branch merge 或直接编辑，应改走 merge-request 或 AI 分支。
• 用户未指定分支上下文或未确认权限策略时，不要自动切换策略或跨分支判断资源是否存在。