AI Branch（Beta）

AI Branch 是一种特殊类型的 Sprint Branch。

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

AI Branch 旨在为 AI Agent 在 Apidog 项目中提供一个隔离的编辑分支。借助 AI Branch，AI 可以创建和更新项目资源，而不会直接更改主分支或标准 Sprint Branch。更改完成后，用户可以在客户端或 CLI 中查看差异，然后将结果直接合并到目标分支，或通过合并请求进行合并。

为什么需要 AI Branch

AI 发起的编辑可能具有不可预测性，而 Apidog CLI 提供了广泛的编辑能力。AI Branch 专为这些风险较高的 AI 发起编辑操作而设计，允许 AI Agent 在受控范围内编辑项目资源。

你也可以升级到 Apidog 2.8.31 或更高版本，并根据需要在 Project Settings -> Feature Settings -> External AI Edit Permissions 下为主分支、标准 Sprint Branch 和普通分支启用直接编辑权限。启用后，这些权限会绕过通常需要 AI Branch 的直接编辑限制。

什么是 AI Branch？

AI Branch 是一个特殊的 Sprint Branch。与标准 Sprint Branch 一样，它用于存储对项目资源的更改。不过，它默认面向外部 AI 操作，例如基于 CLI 的编辑，并在更改合并前保留人工确认步骤。

AI Branch 的主要特点包括：

隔离编辑：从 CLI 对 API、文档、数据模型和测试场景等资源所做的更改会存储在 AI Branch 中，不会直接影响主分支或源分支。

来源清晰：AI Branch 不能直接在 Apidog 客户端中创建。它们必须从 CLI 或 MCP 来源创建。AI Branch 会记录其源分支，并且通常会合并回该源分支，从而更容易理解 AI 生成更改的上下文。

人工确认：AI Branch 中的更改必须由用户确认后才能合并。用户可以查看差异、选择资源范围，并决定是直接合并还是创建合并请求。

无数量限制：目前对可创建的 AI Branch 数量没有有效限制。AI Agent 可以使用它们按业务域、迭代或功能处理数据。

自动归档：为防止项目协作期间 AI Branch 无控制增长，每个 AI Branch 都会每 24 小时与其源分支进行比较。如果未发现差异，它会被自动归档。你可以随时在 Apidog 中恢复已归档的 AI Branch，或从 Apidog CLI 重新创建新的 AI Branch，没有任何限制。

TIP

AI Branch 用于存储来自外部 AI 或 CLI 操作的写入结果。用户在客户端内的正常编辑、合并和审查仍然遵循项目成员权限和分支保护规则。

使用场景

当 AI 需要参与项目资源维护，同时仍必须保留分支隔离和人工确认时，AI Branch 非常适用。

场景	描述
从代码生成 API 草稿	AI 读取代码后，在 AI Branch 中创建或更新 HTTP API 端点。用户在合并前确认更改。
批量整理 API 资源	AI 可以调整 API 目录、添加描述，并更新数据模型或响应组件，而不会直接影响当前协作分支。
生成自动化测试草稿	AI 可以在 AI Branch 中创建测试场景、测试用例或测试数据，供测试人员后续确认。
补全 API 文档缺口	AI 可以基于缺陷报告、API 实现或 OpenAPI 文件补充缺失字段。
在 CI/CD 中批量写入	自动化工作流可以将生成结果写入 AI Branch，并在合并前等待用户审查。

基本工作流

典型的 AI Branch 工作流如下：

创建一个 AI Branch，并指定它所基于的源分支。

将需要编辑的资源导入 AI Branch，或在 AI Branch 中创建新资源。

AI Agent、CLI 或自动化脚本修改 AI Branch 中的资源。

用户查看 AI Branch 与源分支之间的差异，然后确认要合并的资源范围。

根据目标分支保护规则，直接合并或创建合并请求。

创建 AI Branch

使用 branch create --type ai 创建 AI Branch。旧版 sprint-branch 和 sb 入口点仍保持兼容，但推荐使用统一的 branch 入口点。

命令	描述	示例
`branch create --type ai`	创建 AI Branch。	`apidog branch create --project <projectId> --type ai --name "ai/20260312-from-main-userRegister" --from main`
`branch list --type ai`	查看项目中的 AI Branch。	`apidog branch list --project <projectId> --type ai`
`branch list --type all`	查看项目中的所有分支类型。	`apidog branch list --project <projectId> --type all`
`branch get --type ai`	查看指定 AI Branch 的详细信息，包括其分支类型和来源信息。	`apidog branch get <branchName> --project <projectId> --type ai`

示例：为用户注册 API 创建 AI Branch

TIP

我们建议按 ai/YYYYMMDD-from-sourceBranch-featureOrModule 格式命名 AI Branch，例如 ai/20260312-from-main-userRegister。清晰的名称有助于团队了解分支来源、用途和创建时间。

在 AI Branch 中编辑资源

当 CLI 写入项目资源时，你可以使用分支参数将这些资源写入 AI Branch。不同资源命令的参数略有不同。使用前，请查看对应的命令帮助和 JSON Schema。

资源类型	常用命令	示例
HTTP API 端点	`endpoint create`, `endpoint update`	`apidog endpoint create --project <projectId> --branch <aiBranchName> --file ./endpoint.json`
数据模型	`schema create`, `schema update`	`apidog schema update <schemaId> --project <projectId> --branch <aiBranchName> --file ./schema.json`
Markdown 文档	`doc create`, `doc update`	`apidog doc create --project <projectId> --branch <aiBranchName> --file ./doc.json`
测试场景	`test-scenario create`, `test-scenario update`	`apidog test-scenario update <scenarioId> --project <projectId> --branch <aiBranchName> --file ./scenario.json`
测试套件	`test-suite create`, `test-suite update`	`apidog test-suite create --project <projectId> --branch <aiBranchName> --file ./suite.json`
测试数据	`test-data create`, `test-data update`	`apidog test-data create --project <projectId> --branch <aiBranchName> --file ./test-data.json`

创建或更新复杂资源时，我们建议先使用 cli-schema 查看并验证数据结构。

从源分支导入资源

如果 AI Branch 需要修改现有资源，请先使用 branch pick-to 将资源从源分支导入 AI Branch。导入后，AI 可以继续在 AI Branch 中编辑这些资源。

命令	描述	示例
`branch pick-to`	将资源从源分支导入目标 AI Branch。	`apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <aiBranchName> --endpoint-ids <ids>`

示例：导入端点并让 AI 修改它们

TIP

pick-to 仅导入命令中明确指定的资源。如果需要目录、数据模型、响应组件或其他相关资源，请在导入前确认资源范围。

查看 AI Branch 更改

合并前，我们建议预览 AI Branch 与目标分支之间的候选更改。CLI 可以使用 merge-request preview 扫描当前支持的资源类型。你也可以在客户端中查看更完整的分支差异。

命令	描述	示例
`merge-request preview`	扫描候选更改，以便在合并前确认资源范围。	`apidog merge-request preview --project <projectId> --from <aiBranchName> --to <targetBranchName>`
`branch get --type ai`	查看 AI Branch 基本信息。	`apidog branch get <aiBranchName> --project <projectId> --type ai`

示例：合并前预览候选更改

TIP

merge-request preview 会扫描 CLI 当前支持的资源类型的候选差异。它不是完整的资源差异。在最终合并前，我们仍建议在客户端中确认重要资源内容。

合并 AI Branch

AI Branch 更改完成后，你可以将其合并回源分支或其他目标分支。对于未受保护的目标分支，使用 branch merge 直接合并。对于受保护的主分支，使用 merge-request create 创建合并请求并完成审查流程。

命令	描述	示例
`branch merge`	从 AI Branch 直接合并指定资源。	`apidog branch merge --project <projectId> --from <aiBranchName> --to <targetBranchName> --endpoint-ids <ids>`
`merge-request create`	创建合并请求。	`apidog merge-request create --project <projectId> --from <aiBranchName> --to <targetBranchName> --reviewer-ids <userIds> --endpoint-ids <ids>`
`merge-request approve`	批准合并请求。	`apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json`
`merge-request reject`	拒绝合并请求。	`apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName>`

示例：直接合并端点更改

示例：创建合并请求

TIP

直接合并和合并请求都只会合并明确提供的资源列表。它们不会自动包含被引用的资源或目录资源。定义合并范围时，请确认端点、目录、数据模型、响应组件和测试资源之间的依赖关系。

归档和删除 AI Branch

AI Branch 合并后或不再需要时，你可以先将其归档，然后删除。删除前，请确认分支中的更改已合并或不再需要。

命令	描述	示例
`branch archive --type ai`	归档 AI Branch。	`apidog branch archive <aiBranchName> --project <projectId> --type ai`
`branch delete --type ai`	删除已归档的 AI Branch。	`apidog branch delete <aiBranchName> --project <projectId> --type ai`

外部 AI 编辑权限

默认情况下，CLI 建议通过 AI Branch 写入项目资源。这样可以让 AI 生成的更改先进入隔离分支，并且仅在用户确认后才合并。

如果你希望外部 AI 或 CLI 操作直接编辑主分支、标准 Sprint Branch 或普通分支，请在客户端中启用对应权限：

Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions

这些开关控制外部 AI、CLI 或自动化调用在项目分支中的直接写入范围。启用前，请确认团队的协作规则和项目数据安全要求。

权限	描述
主分支直接编辑权限	允许外部 AI 或 CLI 操作直接写入主分支。
标准 Sprint Branch 直接编辑权限	允许外部 AI 或 CLI 操作直接写入标准 Sprint Branch。
普通分支直接编辑权限	允许外部 AI 或 CLI 操作直接写入普通分支。
AI Branch 直接编辑权限	允许外部 AI 或 CLI 操作写入由 AI 创建和维护的 AI Branch。通常会保持启用。

TIP

为保护项目资源，我们建议让外部 AI 或 CLI 操作先写入 AI Branch，并仅在用户确认后合并。只有当自动化工作流明确需要直接修改目标分支时，才启用直接编辑权限。

最佳实践

每个任务创建一个 AI Branch：每个 AI Branch 都应对应一个明确任务，例如完成用户注册 API、整理订单模块文档或生成支付测试场景。

编辑前先导入：修改现有资源时，先使用 pick-to 导入资源，然后在 AI Branch 中更新它们，以避免混淆来源。

合并前预览差异：使用 merge-request preview 或客户端差异视图确认资源内容和依赖关系。

明确选择合并范围：合并命令只处理提供的资源列表。对于 API 目录、数据模型、响应组件和测试用例等相关资源，请一起确认。

保留人工审查：AI 生成的 API 定义、测试脚本和数据模型应在合并前由项目成员审查。

及时归档分支：已合并或已放弃的 AI Branch 应及时归档，以保持分支列表清晰。

FAQ

AI Branch 和标准 Sprint Branch 有什么区别？

AI Branch 是一种特殊的 Sprint Branch，主要用于存储来自外部 AI、CLI 操作或自动化脚本的写入结果。它会记录源分支，并鼓励用户在合并前确认差异。标准 Sprint Branch 通常用于团队成员之间的日常协作。

AI Branch 会直接影响主分支吗？

不会。AI Branch 中的更改会先保存在该 AI Branch 中。只有在用户执行直接合并，或创建并批准合并请求后，相关资源才会进入目标分支。

CLI 如何跳过 AI Branch 并直接编辑项目数据？

在 Apidog 项目中，进入 Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions，然后根据需要为主分支、标准 Sprint Branch 或普通分支启用直接编辑权限。启用这些权限后，外部 AI 或 CLI 操作即可在对应分支范围内直接写入。

合并 AI Branch 时会自动包含被引用的资源吗？

不会。branch merge 和 merge-request create 都会根据明确提供的资源列表执行。如果端点引用了数据模型、响应组件、目录或测试资源，请在合并前确认并添加对应的资源范围。

更改完成后必须删除 AI Branch 吗？

不需要。删除不是强制性的。我们建议在确认其更改已合并或不再需要后归档分支，然后根据团队约定决定是否删除，以避免历史分支长期累积。

为什么需要 AI Branch#

什么是 AI Branch？#

使用场景#

基本工作流#

创建 AI Branch#

在 AI Branch 中编辑资源#

从源分支导入资源#

查看 AI Branch 更改#

合并 AI Branch#

归档和删除 AI Branch#

外部 AI 编辑权限#

最佳实践#

FAQ#

为什么需要 AI Branch

什么是 AI Branch？

使用场景

基本工作流

创建 AI Branch

在 AI Branch 中编辑资源

从源分支导入资源

查看 AI Branch 更改

合并 AI Branch

归档和删除 AI Branch

外部 AI 编辑权限

最佳实践

FAQ