apifox-branch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

分支协作与 AI 写入

Branch Collaboration & AI Writing

前置条件：先阅读
../apifox-cli/SKILL.md
。若旧总入口与本 skill 的领域规则冲突，以当前 CLI help 和本 skill 为准。

具体命令参数以当前 CLI help 为准。本 skill 只补充分支协作中最容易误用的规则：分支上下文、AI 分支、pick-to、写入权限、保护分支和合并确认。Agent 在分支上写入后必须用同一

--branch

回读和验证，不要跨分支用默认视角判断资源是否存在。

Prerequisite: Read
../apifox-cli/SKILL.md
first. If there is a conflict between the old main entry and the domain rules of this skill, the current CLI help and this skill shall prevail.

Refer to the current CLI help for specific command parameters. This skill only supplements the most easily misused rules in branch collaboration: branch context, AI branches, pick-to, write permissions, protected branches, and merge confirmation. After writing on a branch, the Agent must use the same

--branch

to read back and verify; do not use the default perspective across branches to judge whether resources exist.

何时使用

When to Use

用户指定
```
--branch
```
或说在某个分支上操作。
创建、查看、更新、归档、删除分支。
创建 AI 分支并修改源分支资源。
将源分支资源 pick-to 到 AI 分支。
合并分支或创建/审批 merge request。
遇到 AI 写入权限限制。

User specifies
```
--branch
```
or mentions operating on a certain branch.
Create, view, update, archive, or delete branches.
Create AI branches and modify source branch resources.
Pick source branch resources to AI branches via pick-to.
Merge branches or create/approve merge requests.
Encounter AI write permission restrictions.

命令入口

Command Entries

分支管理：
```
apifox branch --help
```
合并请求：
```
apifox merge-request --help
```
资源命令通常都支持
```
--branch <branchName>
```
。查询、创建、更新、运行测试时保持同一个分支上下文。

Branch management:
```
apifox branch --help
```
Merge requests:
```
apifox merge-request --help
```
Resource commands generally support
```
--branch <branchName>
```
. Maintain the same branch context when querying, creating, updating, and running tests.

先判断怎么改

Determine the Modification Method First

分支写入前先问清楚用户要哪种方式：

直接编辑目标分支：适合用户明确允许直接修改，且目标分支没有保护或权限限制。
通过 AI 分支编辑：适合 AI 代改接口、测试用例、测试场景或配置；也适合目标分支受保护、未开启外部 AI 直接写入，或用户希望先隔离验证再合并。

开始写入前必须确认：

项目 ID。
源分支和目标分支。
要修改的资源范围。
是否允许后续创建 merge request 或直接合并。

Clarify with the user which method to use before writing to a branch:

Directly edit the target branch: Suitable when the user explicitly allows direct modification, and the target branch has no protection or permission restrictions.
Edit via AI branch: Suitable for AI to modify interfaces, test cases, test scenarios, or configurations; also suitable when the target branch is protected, external AI direct writing is not enabled, or the user wants to isolate and verify changes before merging.

Must confirm the following before starting to write:

Project ID.
Source branch and target branch.
Scope of resources to modify.
Whether to allow creating merge requests or direct merging later.

AI 分支流程

AI Branch Workflow

AI 分支用于隔离 AI 修改，避免直接污染源分支。

text

确认源分支和目标变更
  -> 创建 AI 分支
  -> pick-to 已有资源
  -> 在 AI 分支修改
  -> 验证 get/run/report
  -> preview merge-request
  -> 用户确认后 create merge-request 或 merge

标准步骤：

创建 AI 分支时指定来源：
```
--from <sourceBranchName>
```
。

使用规范名称：

ai/年月日-from-来源分支名-功能或模块名

，例如

ai/20260312-from-main-userRegister

。

修改源分支已有资源前，先用
```
branch pick-to
```
导入到 AI 分支；新建资源不需要 pick-to。
在 AI 分支上修改、查询、验证时都带
```
--branch <aiBranchName>
```
。
按资源类型验证结果，例如
```
get
```
、
```
run
```
、本地报告或云端报告检查。
合并前先
```
merge-request preview
```
，让用户确认影响范围。
用户确认后，再
```
merge-request create
```
或
```
branch merge
```
；目标主分支受保护时优先 merge request。

AI 分支注意点：

AI 分支初始为空，不会自动复制源分支全部资源。
```
branch get
```
可能返回
```
type: SPRINT
```
且
```
isAiBranch: true
```
；这不代表操作时应使用
```
--type sprint
```
。AI 分支相关操作仍按当前 help 使用
```
--type ai
```
。

AI branches are used to isolate AI modifications and avoid directly polluting source branches.

text

Confirm source branch and target changes
  -> Create AI branch
  -> pick-to existing resources
  -> Modify in AI branch
  -> Verify via get/run/report
  -> preview merge-request
  -> Create merge-request or merge after user confirmation

Standard steps:

Specify the source when creating an AI branch:
```
--from <sourceBranchName>
```
.

Use standardized names:

ai/YYYYMMDD-from-sourceBranchName-featureOrModuleName

, e.g.,

ai/20260312-from-main-userRegister

Before modifying existing resources from the source branch, import them to the AI branch using
```
branch pick-to
```
; no pick-to is required for new resources.
Always include
```
--branch <aiBranchName>
```
when modifying, querying, or verifying in the AI branch.
Verify results by resource type, e.g.,
```
get
```
,
```
run
```
, local reports, or cloud report checks.
Run
```
merge-request preview
```
before merging to let the user confirm the scope of impact.
After user confirmation, execute
```
merge-request create
```
or
```
branch merge
```
; prioritize merge requests when the target main branch is protected.

Notes on AI branches:

AI branches are empty initially and will not automatically copy all resources from the source branch.
```
branch get
```
may return
```
type: SPRINT
```
and
```
isAiBranch: true
```
; this does not mean
```
--type sprint
```
should be used during operations. Use
```
--type ai
```
for AI branch-related operations as per the current help.

分支参数规则

Branch Parameter Rules

优先使用分支名：
```
--branch <branchName>
```
。
兼容纯数字 branchId，但分支名更直观，日志和排障更清楚。
同一任务内查询、创建、更新、运行测试必须带同一个分支上下文，避免在 main/default 视角找不到资源。

Prioritize using branch names:
```
--branch <branchName>
```
.
Pure numeric branchId is compatible, but branch names are more intuitive and easier for logging and troubleshooting.
Must carry the same branch context for querying, creating, updating, and running tests within the same task to avoid not finding resources from the main/default perspective.

pick-to 规则

pick-to Rules

必须带
```
--type ai
```
。
只支持从主分支或普通迭代分支导入到 AI 分支。
不能导入到主分支。
不能以 AI 分支作为来源分支。
使用
```
--include-endpoint-cases
```
可在导入接口时同时导入接口用例。

Must include
```
--type ai
```
.
Only supports importing from main branches or regular sprint branches to AI branches.
Cannot import to main branches.
Cannot use AI branches as source branches.
Use
```
--include-endpoint-cases
```
to import interface cases along with interfaces.

写入权限规则

Write Permission Rules

主分支、迭代分支、通用分支可能要求开启“外部 AI 编辑权限”。
典型错误信息包含
```
Automation caller branch required
```
。
创建 AI 分支可能成功，但写入 AI 分支内容仍可能因“允许 AI 修改 AI 分支内容”关闭而失败。
遇到写入受限，不要自动切策略；让用户选择开启直接编辑权限，或改走 AI 分支。
目标主分支受保护时，优先
```
merge-request preview/create
```
，不要直接
```
branch merge
```
。

Main branches, sprint branches, and general branches may require enabling "External AI Edit Permission".
Typical error messages include
```
Automation caller branch required
```
.
Creating an AI branch may succeed, but writing content to the AI branch may still fail if "Allow AI to modify AI branch content" is disabled.
Do not automatically switch strategies when encountering write restrictions; let the user choose to enable direct edit permission or switch to using AI branches.
When the target main branch is protected, prioritize
```
merge-request preview/create
```
instead of direct
```
branch merge
```
.

不可违反规则

Non-Violable Rules

不要在用户未确认时创建 AI 分支。
不要在 AI 分支里修改源分支已有资源而不先 pick-to。
不要在分支任务中省略
```
--branch <branchName>
```
。
不要在用户未确认时 merge、create merge-request 或审批 merge request。
不要删除、归档分支，除非用户明确要求。
遇到
```
Automation caller branch required
```
时，必须停下来问用户选择权限策略，不要自动创建或切换 AI 分支。

Do not create AI branches without user confirmation.
Do not modify existing source branch resources in AI branches without first using pick-to.
Do not omit
```
--branch <branchName>
```
in branch tasks.
Do not merge, create merge-requests, or approve merge requests without user confirmation.
Do not delete or archive branches unless explicitly requested by the user.
When encountering
```
Automation caller branch required
```
, stop and ask the user to choose a permission strategy; do not automatically create or switch AI branches.

常见恢复

Common Troubleshooting

现象	处理
get 不带 branch 找不到资源	带 `--branch <branchName>` 重试
AI 分支里找不到源资源	先 `branch pick-to` 导入
`projectBranchState` 有计数但 AI 分支页面为空	不要误判为已导入；AI 分支仍需 pick-to
run-config 在分支下 404	确认 case/endpoint/environment/branch 均存在后转 `apifox-cli-checkup`
merge 被保护分支拦截	改走 `merge-request`

Phenomenon	Solution
Cannot find resources when using `get` without `branch`	Retry with `--branch <branchName>`
Cannot find source resources in AI branch	Import first with `branch pick-to`
`projectBranchState` has counts but AI branch page is empty	Do not misjudge as imported; AI branch still requires pick-to
run-config returns 404 under branch	Confirm that case/endpoint/environment/branch all exist, then switch to `apifox-cli-checkup`
Merge is blocked by protected branch	Switch to `merge-request`