AI Branch (Beta)

AI Branch 是一種特殊類型的 Sprint Branch。

所有從 Apidog CLI 發起的編輯操作，預設都會視為由 AI / AI Agents 發起。

AI Branch 旨在為 AI Agents 在 Apidog 專案中提供隔離的編輯分支。透過 AI Branch，AI 可以建立和更新專案資源，而不會直接變更主分支或標準 sprint branch。變更完成後，使用者可以在客戶端或 CLI 中檢視差異，然後直接將結果合併到目標分支，或透過合併請求進行合併。

為什麼需要 AI Branch

AI 發起的編輯可能難以預測，而 Apidog CLI 提供了廣泛的編輯能力。AI Branch 是為這些較高風險的 AI 發起編輯操作而設計，允許 AI Agents 在受控範圍內編輯專案資源。

你也可以升級到 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 Agents 可以用它們依業務領域、迭代或功能處理資料。

自動封存：為了防止專案協作期間 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 目前支援資源類型的候選差異。它不是完整的資源 diff。在最終合併前，我們仍建議在客戶端中確認重要資源內容。

合併 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 或客戶端 diff 檢視來確認資源內容與相依關係。

明確選擇合併範圍：合併命令只會處理提供的資源清單。對於 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