AI 分支：借助 AI Agent 实现更安全的项目变更
AI 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分支，写入前验证，合并前评审。
AI分支通过隔离编辑、人工评审和明确合并范围，为Agent驱动的项目变更构建了安全闭环。遵循最佳实践，团队可在保障主分支安全的同时，高效利用AI提升开发效率。