Branch Collaboration & AI Writing

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

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

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

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 Branch Workflow

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

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 Rules

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

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

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

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`

apifox-branch

NPX Install

Tags

SKILL.md Content (Chinese)