Tất cả các thao tác chỉnh sửa được khởi tạo từ Apidog CLI đều được mặc định xem là do AI / AI Agents khởi tạo.AI Branch được thiết kế để cung cấp cho AI Agents một nhánh chỉnh sửa tách biệt trong các dự án Apidog. Với AI Branch, AI có thể tạo và cập nhật tài nguyên dự án mà không trực tiếp thay đổi nhánh chính hoặc một sprint branch tiêu chuẩn. Sau khi các thay đổi hoàn tất, người dùng có thể xem xét các khác biệt trong client hoặc CLI, sau đó hợp nhất kết quả vào nhánh đích trực tiếp hoặc thông qua một merge request.Vì sao cần AI Branch#
Các chỉnh sửa do AI khởi tạo có thể khó dự đoán, trong khi Apidog CLI cung cấp nhiều khả năng chỉnh sửa. AI Branch được thiết kế cho các thao tác chỉnh sửa do AI khởi tạo có rủi ro cao hơn này, cho phép AI Agents chỉnh sửa tài nguyên dự án trong một phạm vi được kiểm soát.Bạn cũng có thể nâng cấp lên Apidog 2.8.31 hoặc phiên bản mới hơn và bật quyền chỉnh sửa trực tiếp cho nhánh chính, sprint branch tiêu chuẩn và nhánh thông thường khi cần trong Project Settings -> Feature Settings -> External AI Edit Permissions. Sau khi được bật, các quyền này sẽ bỏ qua những hạn chế chỉnh sửa trực tiếp vốn thường yêu cầu AI Branch.AI Branch là gì?#
AI Branch là một sprint branch đặc biệt. Giống như sprint branch tiêu chuẩn, nó lưu trữ các thay đổi đối với tài nguyên dự án. Tuy nhiên, theo mặc định, nó được dùng cho các thao tác AI bên ngoài, chẳng hạn như chỉnh sửa dựa trên CLI, và duy trì một bước xác nhận của con người trước khi các thay đổi được hợp nhất.Các đặc điểm chính của AI Branch bao gồm:1.
Chỉnh sửa tách biệt: Các thay đổi được thực hiện từ CLI đối với các tài nguyên như API, tài liệu, mô hình dữ liệu và kịch bản kiểm thử được lưu trữ trong AI Branch và không ảnh hưởng trực tiếp đến nhánh chính hoặc nhánh nguồn.
2.
Nguồn rõ ràng: AI Branches không thể được tạo trực tiếp trong Apidog client. Chúng phải được tạo từ nguồn CLI hoặc MCP. Một AI Branch ghi nhận nhánh nguồn của nó và thường được hợp nhất trở lại nhánh nguồn đó, giúp dễ hiểu hơn về ngữ cảnh của các thay đổi do AI tạo ra.
3.
Xác nhận của con người: Các thay đổi trong AI Branch phải được người dùng xác nhận trước khi được hợp nhất. Người dùng có thể xem xét khác biệt, chọn phạm vi tài nguyên và quyết định hợp nhất trực tiếp hoặc tạo một merge request.
4.
Không giới hạn số lượng: Hiện tại không có giới hạn đang áp dụng đối với số lượng AI Branches có thể được tạo. AI Agents có thể sử dụng chúng để xử lý dữ liệu theo miền nghiệp vụ, vòng lặp phát triển hoặc tính năng.
5.
Tự động lưu trữ: Để ngăn AI Branches tăng trưởng không kiểm soát trong quá trình cộng tác dự án, mỗi AI Branch được so sánh với nhánh nguồn của nó mỗi 24 giờ. Nếu không tìm thấy khác biệt, nó sẽ tự động được lưu trữ. Bạn có thể khôi phục AI Branches đã lưu trữ trong Apidog bất cứ lúc nào, hoặc tạo lại AI Branches mới từ Apidog CLI, không có bất kỳ giới hạn nào.
AI Branch được dùng để lưu trữ kết quả ghi từ các thao tác AI bên ngoài hoặc CLI. Việc chỉnh sửa, hợp nhất và xem xét thông thường trong client bởi người dùng vẫn tuân theo quyền của thành viên dự án và quy tắc bảo vệ nhánh.
Trường hợp sử dụng#
AI Branch phù hợp khi AI cần tham gia vào việc bảo trì tài nguyên dự án trong khi vẫn phải duy trì tách biệt nhánh và xác nhận của con người.| Kịch bản | Mô tả |
|---|
| Tạo bản nháp API từ mã nguồn | Sau khi đọc mã nguồn, AI tạo hoặc cập nhật các HTTP API endpoints trong một AI Branch. Người dùng xác nhận các thay đổi trước khi hợp nhất. |
| Tổ chức tài nguyên API hàng loạt | AI có thể điều chỉnh thư mục API, thêm mô tả và cập nhật mô hình dữ liệu hoặc thành phần phản hồi mà không ảnh hưởng trực tiếp đến nhánh cộng tác hiện tại. |
| Tạo bản nháp kiểm thử tự động | AI có thể tạo kịch bản kiểm thử, ca kiểm thử hoặc dữ liệu kiểm thử trong AI Branch để kiểm thử viên xác nhận sau. |
| Bổ sung thiếu sót trong tài liệu API | AI có thể bổ sung các trường còn thiếu dựa trên báo cáo lỗi, triển khai API hoặc tệp OpenAPI. |
| Ghi hàng loạt trong CI/CD | Quy trình tự động có thể ghi kết quả được tạo vào AI Branch và chờ người dùng xem xét trước khi hợp nhất. |
Quy trình cơ bản#
Một quy trình AI Branch điển hình như sau:1
Tạo một AI Branch và chỉ định nhánh nguồn mà nó dựa trên.
2
Nhập các tài nguyên cần chỉnh sửa vào AI Branch, hoặc tạo tài nguyên mới trong AI Branch.
3
Một AI Agent, CLI hoặc script tự động hóa sửa đổi tài nguyên trong AI Branch.
4
Người dùng xem xét khác biệt giữa AI Branch và nhánh nguồn, sau đó xác nhận phạm vi tài nguyên sẽ được hợp nhất.
5
Tùy theo quy tắc bảo vệ nhánh đích, hợp nhất trực tiếp hoặc tạo merge request.
Tạo AI Branch#
Sử dụng branch create --type ai để tạo AI Branch. Các điểm vào cũ sprint-branch và sb vẫn tương thích, nhưng khuyến nghị sử dụng điểm vào thống nhất branch.| Lệnh | Mô tả | Ví dụ |
|---|
branch create --type ai | Tạo một AI Branch. | apidog branch create --project <projectId> --type ai --name "ai/20260312-from-main-userRegister" --from main |
branch list --type ai | Xem AI Branches trong một dự án. | apidog branch list --project <projectId> --type ai |
branch list --type all | Xem tất cả các loại nhánh trong một dự án. | apidog branch list --project <projectId> --type all |
branch get --type ai | Xem chi tiết của một AI Branch được chỉ định, bao gồm loại nhánh và thông tin nguồn. | apidog branch get <branchName> --project <projectId> --type ai |
Ví dụ: Tạo AI Branch cho API đăng ký người dùngChúng tôi khuyến nghị đặt tên AI Branches theo định dạng ai/YYYYMMDD-from-sourceBranch-featureOrModule, ví dụ: ai/20260312-from-main-userRegister. Một tên rõ ràng giúp nhóm hiểu nguồn nhánh, mục đích và thời điểm tạo.
Chỉnh sửa tài nguyên trong AI Branch#
Khi CLI ghi tài nguyên dự án, bạn có thể sử dụng các tham số nhánh để ghi những tài nguyên đó vào AI Branch. Các tham số có thể khác nhau đôi chút giữa các lệnh tài nguyên. Trước khi sử dụng, hãy kiểm tra phần trợ giúp lệnh tương ứng và JSON Schema.| Loại tài nguyên | Lệnh thường dùng | Ví dụ |
|---|
| HTTP API endpoint | endpoint create, endpoint update | apidog endpoint create --project <projectId> --branch <aiBranchName> --file ./endpoint.json |
| Mô hình dữ liệu | schema create, schema update | apidog schema update <schemaId> --project <projectId> --branch <aiBranchName> --file ./schema.json |
| Tài liệu Markdown | doc create, doc update | apidog doc create --project <projectId> --branch <aiBranchName> --file ./doc.json |
| Kịch bản kiểm thử | test-scenario create, test-scenario update | apidog test-scenario update <scenarioId> --project <projectId> --branch <aiBranchName> --file ./scenario.json |
| Bộ kiểm thử | test-suite create, test-suite update | apidog test-suite create --project <projectId> --branch <aiBranchName> --file ./suite.json |
| Dữ liệu kiểm thử | test-data create, test-data update | apidog test-data create --project <projectId> --branch <aiBranchName> --file ./test-data.json |
Khi tạo hoặc cập nhật tài nguyên phức tạp, chúng tôi khuyến nghị sử dụng cli-schema trước để xem và xác thực cấu trúc dữ liệu.Nhập tài nguyên từ nhánh nguồn#
Nếu một AI Branch cần sửa đổi các tài nguyên hiện có, trước tiên hãy sử dụng branch pick-to để nhập tài nguyên từ nhánh nguồn vào AI Branch. Sau khi nhập, AI có thể tiếp tục chỉnh sửa các tài nguyên đó trong AI Branch.| Lệnh | Mô tả | Ví dụ |
|---|
branch pick-to | Nhập tài nguyên từ nhánh nguồn vào AI Branch đích. | apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <aiBranchName> --endpoint-ids <ids> |
Ví dụ: Nhập endpoints và để AI sửa đổi chúngpick-to chỉ nhập các tài nguyên được chỉ định rõ trong lệnh. Nếu cần thư mục, mô hình dữ liệu, thành phần phản hồi hoặc các tài nguyên liên quan khác, hãy xác nhận phạm vi tài nguyên trước khi nhập.
Xem các thay đổi của AI Branch#
Trước khi hợp nhất, chúng tôi khuyến nghị xem trước các thay đổi ứng viên giữa AI Branch và nhánh đích. CLI có thể sử dụng merge-request preview để quét các loại tài nguyên hiện được hỗ trợ. Bạn cũng có thể xem khác biệt nhánh đầy đủ hơn trong client.| Lệnh | Mô tả | Ví dụ |
|---|
merge-request preview | Quét các thay đổi ứng viên để xác nhận phạm vi tài nguyên trước khi hợp nhất. | apidog merge-request preview --project <projectId> --from <aiBranchName> --to <targetBranchName> |
branch get --type ai | Xem thông tin cơ bản của AI Branch. | apidog branch get <aiBranchName> --project <projectId> --type ai |
Ví dụ: Xem trước các thay đổi ứng viên trước khi hợp nhấtmerge-request preview quét các khác biệt ứng viên cho các loại tài nguyên hiện được CLI hỗ trợ. Đây không phải là diff tài nguyên hoàn chỉnh. Trước lần hợp nhất cuối cùng, chúng tôi vẫn khuyến nghị xác nhận nội dung tài nguyên quan trọng trong client.
Hợp nhất AI Branch#
Sau khi các thay đổi trong AI Branch hoàn tất, bạn có thể hợp nhất chúng trở lại nhánh nguồn hoặc một nhánh đích khác. Đối với các nhánh đích không được bảo vệ, sử dụng branch merge để hợp nhất trực tiếp. Đối với các nhánh chính được bảo vệ, sử dụng merge-request create để tạo merge request và đi qua quy trình xem xét.| Lệnh | Mô tả | Ví dụ |
|---|
branch merge | Hợp nhất trực tiếp các tài nguyên được chỉ định từ AI Branch. | apidog branch merge --project <projectId> --from <aiBranchName> --to <targetBranchName> --endpoint-ids <ids> |
merge-request create | Tạo một merge request. | apidog merge-request create --project <projectId> --from <aiBranchName> --to <targetBranchName> --reviewer-ids <userIds> --endpoint-ids <ids> |
merge-request approve | Phê duyệt một merge request. | apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json |
merge-request reject | Từ chối một merge request. | apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName> |
Ví dụ: Hợp nhất trực tiếp các thay đổi endpointVí dụ: Tạo một merge requestCả hợp nhất trực tiếp và merge request đều chỉ hợp nhất danh sách tài nguyên được cung cấp rõ ràng. Chúng không tự động bao gồm tài nguyên được tham chiếu hoặc tài nguyên thư mục. Khi xác định phạm vi hợp nhất, hãy xác nhận các phụ thuộc giữa endpoints, thư mục, mô hình dữ liệu, thành phần phản hồi và tài nguyên kiểm thử.
Lưu trữ và xóa AI Branch#
Sau khi một AI Branch được hợp nhất hoặc không còn cần thiết, bạn có thể lưu trữ nó trước rồi xóa nó. Trước khi xóa, hãy xác nhận rằng các thay đổi trong nhánh đã được hợp nhất hoặc không còn cần thiết.| Lệnh | Mô tả | Ví dụ |
|---|
branch archive --type ai | Lưu trữ một AI Branch. | apidog branch archive <aiBranchName> --project <projectId> --type ai |
branch delete --type ai | Xóa một AI Branch đã lưu trữ. | apidog branch delete <aiBranchName> --project <projectId> --type ai |
Quyền chỉnh sửa của AI bên ngoài#
Theo mặc định, CLI khuyến nghị ghi tài nguyên dự án thông qua AI Branch. Điều này cho phép các thay đổi do AI tạo ra đi vào một nhánh tách biệt trước và chỉ được hợp nhất sau khi người dùng xác nhận.Nếu bạn muốn các thao tác AI bên ngoài hoặc CLI chỉnh sửa trực tiếp nhánh chính, sprint branch tiêu chuẩn hoặc nhánh thông thường, hãy bật các quyền tương ứng trong client:Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions
| Quyền | Mô tả |
|---|
| Quyền chỉnh sửa trực tiếp nhánh chính | Cho phép các thao tác AI bên ngoài hoặc CLI ghi trực tiếp vào nhánh chính. |
| Quyền chỉnh sửa trực tiếp sprint branch tiêu chuẩn | Cho phép các thao tác AI bên ngoài hoặc CLI ghi trực tiếp vào sprint branch tiêu chuẩn. |
| Quyền chỉnh sửa trực tiếp nhánh thông thường | Cho phép các thao tác AI bên ngoài hoặc CLI ghi trực tiếp vào nhánh thông thường. |
| Quyền chỉnh sửa trực tiếp AI Branch | Cho phép các thao tác AI bên ngoài hoặc CLI ghi vào AI Branches do AI tạo và duy trì. Quyền này thường được giữ ở trạng thái bật. |
Để bảo vệ tài nguyên dự án, chúng tôi khuyến nghị để các thao tác AI bên ngoài hoặc CLI ghi vào AI Branch trước và chỉ hợp nhất sau khi người dùng xác nhận. Chỉ bật quyền chỉnh sửa trực tiếp khi một quy trình tự động hóa rõ ràng cần sửa đổi trực tiếp nhánh đích.
Thực hành tốt nhất#
1.
Tạo một AI Branch cho mỗi tác vụ: Mỗi AI Branch nên tương ứng với một tác vụ rõ ràng, chẳng hạn như hoàn thiện API đăng ký người dùng, tổ chức tài liệu mô-đun đơn hàng hoặc tạo kịch bản kiểm thử thanh toán.
2.
Nhập trước khi chỉnh sửa: Khi sửa đổi tài nguyên hiện có, sử dụng pick-to để nhập chúng trước, sau đó c ập nhật chúng trong AI Branch nhằm tránh nhầm lẫn về nguồn.
3.
Xem trước khác biệt trước khi hợp nhất: Sử dụng merge-request preview hoặc chế độ xem diff trong client để xác nhận nội dung tài nguyên và các phụ thuộc.
4.
Chọn rõ phạm vi hợp nhất: Các lệnh hợp nhất chỉ xử lý danh sách tài nguyên được cung cấp. Đối với các tài nguyên liên quan như thư mục API, mô hình dữ liệu, thành phần phản hồi và ca kiểm thử, hãy xác nhận chúng cùng nhau.
5.
Duy trì xem xét của con người: Định nghĩa API, script kiểm thử và mô hình dữ liệu do AI tạo nên được thành viên dự án xem xét trước khi hợp nhất.
6.
Lưu trữ nhánh kịp thời: AI Branches đã được hợp nhất hoặc bị bỏ nên được lưu trữ kịp thời để giữ danh sách nhánh rõ ràng.
FAQ#
AI Branch là một sprint branch đặc biệt, chủ yếu được dùng để lưu trữ kết quả ghi từ AI bên ngoài, thao tác CLI hoặc script tự động hóa. Nó ghi nhận nhánh nguồn và khuyến khích người dùng xác nhận khác biệt trước khi hợp nhất. Sprint branch tiêu chuẩn thường được dùng cho cộng tác hằng ngày giữa các thành viên trong nhóm.
Không. Các thay đổi trong AI Branch trước tiên được lưu trong chính AI Branch đó. Các tài nguyên liên quan chỉ đi vào nhánh đích sau khi người dùng thực hiện hợp nhất trực tiếp hoặc tạo và phê duyệt merge request.
Trong một dự án Apidog, hãy đi tới Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions, sau đó bật quyền chỉnh sửa trực tiếp cho nhánh chính, sprint branch tiêu chuẩn hoặc nhánh thông thường khi cần. Sau khi các quyền này được bật, các thao tác AI bên ngoài hoặc CLI có thể ghi trực tiếp trong phạm vi nhánh tương ứng.
Không. Cả branch merge và merge-request create đều được thực thi theo danh sách tài nguyên được cung cấp rõ ràng. Nếu endpoints tham chiếu đến mô hình dữ liệu, thành phần phản hồi, thư mục hoặc tài nguyên kiểm thử, hãy xác nhận và thêm phạm vi tài nguyên tương ứng trước khi hợp nhất.
Không. Việc xóa không bắt buộc. Chúng tôi khuyến nghị lưu trữ nhánh sau khi xác nhận rằng các thay đổi của nó đã được hợp nhất hoặc không còn cần thiết, rồi quyết định có xóa nó hay không theo quy ước của nhóm bạn để tránh tích lũy lâu dài các nhánh lịch sử.
