AI 分支
为什么需要 AI 分支 ？
什么是 AI 分支 ？
1.
2.
3.
4.
5.
提示
适用场景
| 场景 | 说明 |
|---|---|
| 根据代码生成接口草稿 | AI 读取代码后，在 AI 分支中创建或更新 HTTP API 接口，用户确认后再合并。 |
| 批量整理接口资源 | AI 可调整接口目录、补充说明、更新数据模型或响应组件，避免直接影响当前协作分支。 |
| 生成自动化测试草稿 | AI 可在 AI 分支中创建场景用例、测试用例或测试数据，后续由测试人员确认。 |
| 修复接口文档缺口 | AI 可根据错误报告、接口实现或 OpenAPI 文件补充缺 失字段。 |
| 在 CI/CD 中批量写入 | 自动化流程可将生成结果写入 AI 分支，等待用户审核后合并。 |
基本流程
创建 AI 分支，并指定它基于哪个来源分支创建。
将需要编辑的资源导入 AI 分支，或在 AI 分支中创建新的资源。
AI Agent、CLI 或自动化脚本在 AI 分支中完成资源修改。
用户查看 AI 分支与来源分支之间的差异，确认要合并的资源范围。
根据目标分支保护规则，直接合并或创建合并请求。
创建 AI 分支
sprint-branch create --ai 创建 AI 分支。sprint-branch、sb、branch 是等价入口。| 命令 | 说明 | 示例 |
|---|---|---|
sprint-branch create --ai | 创建 AI 分支。 | apifox sprint-branch create --project <projectId> --name "ai/20260312-from-main-userRegister" --ai |
sprint-branch list | 查看项目中的普通迭代分支和 AI 分支。 | apifox sprint-branch list --project <projectId> |
sprint-branch view | 查看指定分支详情，包括分支类型和来源信息。 | apifox sprint-branch view <branchName> --project <projectId> |
提示
ai/年月日-from-来源分支名-功能或模块名，例如 ai/20260312-from-main-userRegister。清晰的命名有助于团队理解分支来源、用途和创建时间。在 AI 分支中编辑资源
| 资源类型 | 常用命令 | 示例 |
|---|---|---|
| HTTP API 接口 | endpoint create、endpoint update | apifox endpoint create --project <projectId> --branch <aiBranchName> --file ./endpoint.json |
| 数据模型 | schema create、schema update | apifox schema update <schemaId> --project <projectId> --branch <aiBranchName> --file ./schema.json |
| Markdown 文档 | doc create、doc update | apifox doc create --project <projectId> --branch <aiBranchName> --file ./doc.json |
| 场景用例 | test-scenario create、test-scenario update | apifox test-scenario update <scenarioId> --project <projectId> --branch <aiBranchName> --file ./scenario.json |
| 测试套件 | test-suite create、test-suite update | apifox test-suite create --project <projectId> --branch <aiBranchName> --file ./suite.json |
| 测试数据 | test-data create、test-data update | apifox test-data create --project <projectId> --branch <aiBranchName> --file ./test-data.json |
cli-schema 查看并校验数据结构。从来源分支导入资源
sprint-branch pick-to 将来源分支中的资源导入 AI 分支。导入后，AI 可在 AI 分支中继续编辑这些资源。| 命令 | 说明 | 示例 |
|---|---|---|
sprint-branch pick-to | 从源分支导入资源到目标 AI 分支。 | apifox sprint-branch pick-to --project <projectId> --from <sourceBranchName> --to <aiBranchName> --endpoint-ids <ids> |
提示
pick-to 只会导入命令中显式传入的资源。需要目录、数据模型、响应组件或其他关联资源时，请在导入前确认资源范围。查看 AI 分支改动
merge-request preview 扫描当前支持的资源类型，客户端中也可以查看更完整的分支差异。| 命令 | 说明 | 示例 |
|---|---|---|
merge-request preview | 扫描候选改动，用于合并前确认资源范围。 | apifox merge-request preview --project <projectId> --from <aiBranchName> --to <targetBranchName> |
sprint-branch view | 查看 AI 分支基本信息。 | apifox sprint-branch view <aiBranchName> --project <projectId> |
提示
merge-request preview 用于扫描 CLI 当前支持资源类型的候选差异。它不是完整资源 diff，正式合并前仍建议在客户端中确认关键资源内容。合并 AI 分支
sprint-branch merge 直接合并；受保护主分支通常使用 merge-request create 创建合并请求并走审核流程。| 命令 | 说明 | 示例 |
|---|---|---|
sprint-branch merge | 直接合并 AI 分支中的指定资源。 | apifox sprint-branch merge --project <projectId> --from <aiBranchName> --to <targetBranchName> --endpoint-ids <ids> |
merge-request create | 创建合并请求。 | apifox merge-request create --project <projectId> --from <aiBranchName> --to <targetBranchName> --reviewer-ids <userIds> --endpoint-ids <ids> |
merge-request approve | 批准合并请求。 | apifox merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json |
merge-request reject | 拒绝合并请求。 | apifox merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName> |
提示
归档和删除 AI 分支
| 命令 | 说明 | 示例 |
|---|---|---|
sprint-branch archive | 归档 AI 分支。 | apifox sprint-branch archive <aiBranchName> --project <projectId> |
sprint-branch delete | 删除已归档的 AI 分支。 | apifox sprint-branch delete <aiBranchName> --project <projectId> |
外部 AI 编辑权限
项目设置 - 功能设置 - AI 功能设置 - 外部 AI 编辑权限| 权限项 | 说明 |
|---|---|
| 主分支直接编辑权限 | 允许外部 AI 或 CLI 直接写入主分支。 |
| 标准迭代分支直接编辑权限 | 允许外部 AI 或 CLI 直接写入普通迭代分支。 |
| 通用分支直接编辑权限 | 允许外部 AI 或 CLI 直接写入通用分支。 |
| AI 分支直接编辑权限 | 允许外部 AI 或 CLI 写入由 AI 创建和维护的 AI 分支。通常保持开启。 |
提示
最佳实践
1.
2.
pick-to 导入资源，再在 AI 分支中更新，避免混淆来源。3.
merge-request preview 或客户端差异视图确认资源内容和依赖关系。4.
5.
6.