AI 分支：通过 AI Agent 实现更安全的项目变更

当 Agent 修改项目资源时，安全性和可评审性至关重要。AI 分支（AI Branch）提供了一个隔离的编辑环境——变更只有在经过人工确认后才会进入目标分支。

安全挑战

当 AI Agent 参与 API 开发和测试时，它们可以通过 CLI 命令创建、更新和删除项目资源。

这种能力伴随着风险。

风险	可能发生的情况
不可预测的输出	Agent 写入了非预期的内容
字段错误	错误的断言、缺失的参数
范围蔓延	Agent 修改了任务范围之外的资源
缺乏评审轨迹	变更直接出现在主分支中
团队协作干扰	共享的协作分支突然被更改

如何让 Agent 在真实项目中工作，同时又不危及主分支的安全？

AI 分支：安全层

AI 分支 (AI Branch) 是一种特殊类型的迭代分支 (Sprint Branch)，专门为外部 AI 和 CLI 操作而设计。

核心概念：

默认情况下，所有从 Apifox CLI 发起的编辑操作都被视为由 AI / AI Agent 发起。

AI 分支为 AI Agent 提供了一个隔离的编辑分支。变更会保留在 AI 分支中，直到人工评审并合并它们。

Agent 通过 CLI 进行变更
        ↓
变更存储在 AI 分支中（隔离）
        ↓
用户评审差异 (Diff)
        ↓
用户确认资源范围
        ↓
合并到目标分支（直接合并或通过合并请求）

在您批准之前，主分支将保持不变。

为什么需要 AI 分支

AI 发起的编辑可能是不可预测的。Apifox CLI 提供了广泛的编辑能力——接口 (Endpoints)、数据模型 (Schemas)、测试场景 (Test Scenarios)、测试套件 (Test Suites) 等。

AI 分支专为这些高风险的 AI 发起编辑操作而设计。

它允许 AI Agent 在受控范围内编辑项目资源：

无 AI 分支	有 AI 分支
Agent 直接写入主分支	Agent 写入隔离分支
变更立即生效	变更等待评审
无安全网	需要人工确认
存在意外修改的风险	范围限制在特定资源内

什么是 AI 分支？

AI 分支是一个具有特定特征的特殊迭代分支：

核心特征

特征	描述
隔离编辑	变更存储在 AI 分支中，不影响主分支或源分支
来源明确	无法在客户端创建——必须来自 CLI/MCP；记录源分支
人工确认	变更在合并前必须经过确认
无数量限制	可根据不同任务需要创建任意数量的 AI 分支
自动归档	无差异的分支每 24 小时自动归档一次

工作原理

操作	发生位置
AI 创建接口	在 AI 分支中
AI 更新测试场景	在 AI 分支中
团队评审变更	在客户端或 CLI 预览中
用户批准合并	用户操作，而非 AI
变更进入目标分支	确认之后

用户在客户端进行的常规编辑仍遵循项目成员权限和分支保护规则。

使用场景

当 AI 需要参与项目维护，同时又要保持分支隔离和人工确认时，AI 分支非常适用。

场景	AI 分支如何提供帮助
从代码生成 API 草稿	AI 在 AI 分支中创建接口；用户在合并前确认
批量整理 API 资源	AI 调整目录、描述、模型，而不影响协作分支
生成自动化测试草稿	AI 在 AI 分支中创建测试场景/用例，供测试人员评审
完善 API 文档	AI 根据错误报告或实现情况补充缺失字段
CI/CD 中的批量写入	自动化工作流写入 AI 分支，等待用户合并

基本工作流

一个典型的 AI 分支工作流：

┌─────────────────────────────────────────────────────────────────┐
│                     AI 分支工作流                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  步骤 1: 创建 AI 分支                                             │
│  ┌───────────────────────────────────────────┐                  │
│  │ apifox branch create --type ai             │                  │
│  │ --name "ai/20260312-from-main-feature"     │                  │
│  │ --from main                                │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  步骤 2: 导入或创建资源                                           │
│  ┌───────────────────────────────────────────┐                  │
│  │ apifox branch pick-to (导入现有资源)         │                  │
│  │ 或                                          │                  │
│  │ apifox endpoint create (创建新资源)          │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  步骤 3: AI 修改资源                                              │
│  ┌───────────────────────────────────────────┐                  │
│  │ Agent 使用 CLI 更新接口、数据模型、测试场景等   │                  │
│  │ (--branch 参数指定 AI 分支)                  │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  步骤 4: 用户评审差异                                             │
│  ┌───────────────────────────────────────────┐                  │
│  │ apifox merge-request preview              │                  │
│  │ 或                                          │                  │
│  │ 在 Apifox 客户端中查看                       │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  步骤 5: 合并到目标分支                                           │
│  ┌───────────────────────────────────────────┐                  │
│  │ 直接合并 (非保护分支)                         │                  │
│  │ 或                                          │                  │
│  │ 合并请求 (保护分支)                           │                  │
│  └───────────────────────────────────────────┘                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

创建 AI 分支

使用 branch create --type ai：

apifox branch create \
  --project 123456 \
  --type ai \
  --name "ai/20260312-from-main-userRegister" \
  --from main

命名建议： ai/YYYYMMDD-from-源分支-功能或模块名

命令	用途
`branch create --type ai`	创建 AI 分支
`branch list --type ai`	查看项目中的 AI 分支
`branch list --type all`	查看所有分支类型
`branch get --type ai`	查看 AI 分支详情

在 AI 分支中编辑资源

当 CLI 写入项目资源时，使用 --branch 参数写入 AI 分支：

资源	命令示例
HTTP 接口	`apifox endpoint create --project <id> --branch <aiBranchName> --file ./endpoint.json`
数据模型	`apifox schema update <schemaId> --project <id> --branch <aiBranchName> --file ./schema.json`
测试场景	`apifox test-scenario update <scenarioId> --project <id> --branch <aiBranchName> --file ./scenario.json`
测试套件	`apifox test-suite create --project <id> --branch <aiBranchName> --file ./suite.json`

推荐工作流：

# 1. 获取 Schema
apifox cli-schema get endpoint-create

# 2. 写入前验证
apifox cli-schema validate endpoint-create --file ./endpoint.json

# 3. 写入 AI 分支（而非主分支）
apifox endpoint create \
  --project 123456 \
  --branch "ai/20260312-from-main-userRegister" \
  --file ./endpoint.json

导入现有资源

要修改现有资源，请先从源分支导入它们：

apifox branch pick-to \
  --project 123456 \
  --from main \
  --to "ai/20260312-from-main-userRegister" \
  --endpoint-ids 1001,1002

这确保了 AI 基于正确的基础版本进行工作。

合并前评审变更

在合并之前，预览差异：

apifox merge-request preview \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main

或者在 Apifox 客户端中查看完整的 Diff。

命令	用途
`merge-request preview`	扫描待变更内容
`branch get --type ai`	查看 AI 分支信息

合并 AI 分支

评审后，合并变更：

直接合并（非保护分支）

apifox branch merge \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --endpoint-ids 1001,1002

合并请求（保护分支）

apifox merge-request create \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --reviewer-ids 20001,20002 \
  --endpoint-ids 1001,1002

命令	用途
`branch merge`	直接合并到非保护分支
`merge-request create`	创建合并请求以供评审
`merge-request approve`	批准合并请求
`merge-request reject`	拒绝合并请求

重要提示： 合并命令仅处理显式提供的资源列表。在合并前请确认依赖项（目录、模型、响应组件、测试）。

归档与删除

当变更已合并或不再需要时：

# 归档
apifox branch archive "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

# 删除（归档后）
apifox branch delete "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

外部 AI 编辑权限

默认情况下，CLI 写入 AI 分支。这使得 AI 生成的变更在用户确认前保持隔离。

若要启用直接编辑主分支：

项目设置 → 功能设置 → AI 功能设置 → 外部 AI 编辑权限

权限	允许的操作
主分支直接编辑	CLI 直接写入主分支（跳过 AI 分支）
标准迭代分支直接编辑	CLI 直接写入迭代分支
普通分支直接编辑	CLI 直接写入普通分支
AI 分支直接编辑	CLI 写入 AI 分支（通常保持启用）

建议： 保持 AI 分支隔离功能开启。仅在自动化工作流明确需要时才启用直接编辑。

最佳实践

实践	原因
每个任务一个 AI 分支	范围明确：用户注册 API、订单模块文档、支付测试
编辑前先导入	对现有资源使用 `pick-to` —— 避免来源混淆
写入前验证	使用 `cli-schema validate` 在写入 AI 分支前捕获错误
合并前预览	使用 `merge-request preview` 或客户端 Diff 视图
明确合并范围	同时确认接口、模型、目录和测试
保留人工评审	API 定义、测试脚本在合并前应经过评审
及时归档	合并或放弃后保持分支列表整洁

CLI + SKILL 工作流中的 AI 分支

AI 分支与 CLI + SKILL 自然集成：

阶段	CLI + SKILL + AI 分支
读取	从任何分支执行 `endpoint get`
生成	Agent 创建 JSON
验证	本地执行 `cli-schema validate`
写入	使用 `endpoint create --branch <aiBranchName>` 写入 AI 分支
评审	执行 `merge-request preview`
合并	用户确认，然后执行 `branch merge`
验证	在合并后的资源上执行 `apifox run`

每一次写入都会经过：AI 分支 → 人工评审 → 合并。

安全总结

层级	保护作用
`cli-schema validate`	在写入前捕获结构性错误
`agentHints`	引导 Agent 采取安全的下一步行动
AI 分支	将变更与主分支隔离
人工评审	在合并前确认内容
合并范围	用户选择要合并哪些资源