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

安全挑战

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

这种能力伴随着风险。

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

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

AI 分支：安全层

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

创建 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. 获取 Schemaapifox 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 分支	将变更与主分支隔离
人工评审	在合并前确认内容
合并范围	用户选择要合并哪些资源

这些层级共同为 Agent 驱动的项目变更创建了一个更安全的闭环。

下一步

有了 AI 分支提供的安全层，所有的拼图都已就位：

• 用于工具连接的 MCP（第 1 部分）
• 用于工作流执行的 CLI + SKILL（第 2-5 部分）
• 验证结果（第 6 部分）
• 实战工作流（第 7 部分）
• CI/CD 基础（第 8 部分）
• 用于安全的 AI 分支（第 9 部分）

现在是时候展示愿景了。

在第 10 部分 [Spec-First 已成往事，欢迎来到 Skill-First 时代] 中，我们将概述 API 开发如何随 AI Agent 演进，以及团队接下来应该做什么。

核心要点

• AI 分支为 AI/CLI 操作提供隔离的编辑环境。
• 在人工确认之前，变更不会影响主分支。
• 使用 branch create --type ai 创建，使用 --branch 参数写入。
• 编辑前使用 branch pick-to 导入现有资源。
• 使用 merge-request preview 预览，然后合并或创建合并请求。
• 直接编辑权限可以绕过 AI 分支 —— 请谨慎使用。
• 最佳实践：每个任务一个 AI 分支，写入前验证，合并前评审。

下载 Apifox，在一个工作区内完成 API 的 设计、Mock、测试 和 文档 编写。了解更多关于 Apifox CLI 的信息，助力命令行 API 测试、CI 自动化和 AI Agent 工作流。

开发必备：API 全流程管理神器 Apifox

介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。

如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。

值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。