Nhánh AI: Thay đổi dự án an toàn hơn với Tác nhân AI

Đây là một loạt bài gồm 10 phần chia sẻ cách Apidog đã phát triển Apidog CLI, một công cụ dòng lệnh để kiểm thử API và quản lý vòng đời API. Bạn có thể đọc theo thứ tự hoặc chuyển đến bất kỳ bài viết nào bạn quan tâm:

Khi một Agent sửa đổi tài nguyên dự án, tính an toàn và khả năng xem xét là rất quan trọng. Nhánh AI cung cấp một môi trường chỉnh sửa biệt lập—các thay đổi chỉ được đưa vào nhánh mục tiêu sau khi có xác nhận của con người.

Thử thách bảo mật

Khi AI Agent tham gia vào quá trình phát triển và kiểm thử API, chúng có thể tạo, cập nhật và xóa tài nguyên dự án thông qua các lệnh CLI.

Quyền năng này đi kèm với rủi ro.

Làm thế nào để bạn cho phép Agent làm việc trên các dự án thực mà không gây rủi ro cho nhánh chính?

Nhánh AI: Lớp an toàn

Nhánh AI là một loại Nhánh Sprint đặc biệt được thiết kế dành riêng cho các hoạt động AI và CLI bên ngoài.

Khái niệm chính:

Tất cả các thao tác chỉnh sửa được khởi tạo từ Apidog CLI đều được coi là do AI / AI Agent khởi tạo theo mặc định.

Nhánh AI cung cấp cho AI Agent một nhánh chỉnh sửa biệt lập. Các thay đổi sẽ nằm trong Nhánh AI cho đến khi có người xem xét và hợp nhất chúng.

Agent thực hiện thay đổi qua CLI
        ↓
Các thay đổi được lưu trữ trong Nhánh AI (biệt lập)
        ↓
Người dùng xem xét sự khác biệt
        ↓
Người dùng xác nhận phạm vi tài nguyên
        ↓
Hợp nhất vào nhánh mục tiêu (trực tiếp hoặc yêu cầu hợp nhất)

Nhánh chính vẫn không bị ảnh hưởng cho đến khi bạn phê duyệt.

Tại sao cần Nhánh AI

Các chỉnh sửa do AI khởi tạo có thể không thể đoán trước. Apidog CLI cung cấp nhiều khả năng chỉnh sửa—điểm cuối, lược đồ, kịch bản kiểm thử, bộ kiểm thử, v.v.

Nhánh AI đượ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 này.

Nó cho phép AI Agent chỉnh sửa tài nguyên dự án trong một phạm vi kiểm soát:

Nhánh AI là gì?

Nhánh AI là một nhánh sprint đặc biệt với các đặc điểm cụ thể:

Đặc điểm chính

Cách hoạt động

Việc chỉnh sửa 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à các quy tắc bảo vệ nhánh.

Các trường hợp sử dụng

Nhánh AI phù hợp khi AI cần tham gia vào việc bảo trì dự án trong khi vẫn duy trì sự biệt lập của nhánh và xác nhận của con người.

Quy trình làm việc cơ bản

Một quy trình làm việc điển hình của Nhánh AI:

┌─────────────────────────────────────────────────────────────────┐
│                     QUY TRÌNH LÀM VIỆC CỦA NHÁNH AI              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Bước 1: Tạo Nhánh AI                                            │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch create --type ai             │                  │
│  │ --name "ai/20260312-from-main-feature"     │                  │
│  │ --from main                                │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Bước 2: Nhập hoặc Tạo Tài nguyên                                │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch pick-to (nhập tài nguyên hiện có)    │                  │
│  │ HOẶC                                         │                  │
│  │ apidog endpoint create (tạo mới)        │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Bước 3: AI sửa đổi Tài nguyên                                   │
│  ┌───────────────────────────────────────────┐                  │
│  │ Agent sử dụng CLI để cập nhật điểm cuối,       │                  │
│  │ lược đồ, kịch bản kiểm thử, v.v.             │                  │
│  │ (tham số --branch chỉ định Nhánh AI)  │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Bước 4: Người dùng xem xét sự khác biệt                         │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog merge-request preview              │                  │
│  │ HOẶC                                         │                  │
│  │ Xem trong client Apidog                     │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Bước 5: Hợp nhất vào Nhánh mục tiêu                             │
│  ┌───────────────────────────────────────────┐                  │
│  │ Hợp nhất trực tiếp (nhánh không được bảo vệ)         │                  │
│  │ HOẶC                                         │                  │
│  │ Yêu cầu hợp nhất (nhánh được bảo vệ)          │                  │
│  └───────────────────────────────────────────┘                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Tạo một Nhánh AI

Sử dụng branch create --type ai:

apidog branch create \
  --project 123456 \
  --type ai \
  --name "ai/20260312-from-main-userRegister" \
  --from main

Đề xuất đặt tên: ai/YYYYMMDD-from-sourceBranch-featureOrModule

Chỉnh sửa Tài nguyên trong một Nhánh AI

Khi CLI ghi tài nguyên dự án, hãy sử dụng tham số --branch để ghi vào Nhánh AI:

Quy trình làm việc được đề xuất:

# 1. Lấy lược đồ
apidog cli-schema get endpoint-create

# 2. Xác thực trước khi ghi
apidog cli-schema validate endpoint-create --file ./endpoint.json

# 3. Ghi vào Nhánh AI (không phải nhánh chính)
apidog endpoint create \
  --project 123456 \
  --branch "ai/20260312-from-main-userRegister" \
  --file ./endpoint.json

Nhập Tài nguyên hiện có

Để sửa đổi các tài nguyên hiện có, trước tiên hãy nhập chúng từ nhánh nguồn:

apidog branch pick-to \
  --project 123456 \
  --from main \
  --to "ai/20260312-from-main-userRegister" \
  --endpoint-ids 1001,1002

Điều này đảm bảo AI làm việc với phiên bản cơ sở chính xác.

Xem xét Thay đổi trước khi Hợp nhất

Trước khi hợp nhất, hãy xem trước sự khác biệt:

apidog merge-request preview \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main

Hoặc xem toàn bộ sự khác biệt trong client Apidog.

Hợp nhất một Nhánh AI

Sau khi xem xét, hợp nhất các thay đổi:

Hợp nhất trực tiếp (Nhánh không được bảo vệ)

apidog branch merge \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --endpoint-ids 1001,1002

Yêu cầu hợp nhất (Nhánh được bảo vệ)

apidog merge-request create \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --reviewer-ids 20001,20002 \
  --endpoint-ids 1001,1002

Quan trọng: Các lệnh hợp nhất chỉ xử lý danh sách tài nguyên được cung cấp rõ ràng. Xác nhận các phần phụ thuộc (thư mục, mô hình, thành phần phản hồi, kiểm thử) trước khi hợp nhất.

Lưu trữ và Xóa

Sau khi các thay đổi được hợp nhất hoặc không còn cần thiết:

# Lưu trữ
apidog branch archive "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

# Xóa (sau khi lưu trữ)
apidog branch delete "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

Quyền chỉnh sửa AI bên ngoài

Theo mặc định, CLI ghi vào Nhánh AI. Điều này giữ cho các thay đổi do AI tạo ra được biệt lập cho đến khi người dùng xác nhận.

Để bật chỉnh sửa trực tiếp nhánh chính:

Project Settings → Feature Settings → AI Feature Settings → External AI Edit Permissions

Khuyến nghị: Giữ tính năng biệt lập của Nhánh AI được bật. Chỉ bật chỉnh sửa trực tiếp khi quy trình làm việc tự động hóa thực sự cần đến.

Các phương pháp hay nhất

Nhánh AI trong Quy trình làm việc CLI + SKILL

Nhánh AI tích hợp tự nhiên với CLI + SKILL:

Mọi thao tác ghi đều đi qua Nhánh AI → xem xét của con người → hợp nhất.

Tóm tắt bảo mật

Cùng với nhau, các lớp này tạo ra một vòng lặp an toàn hơn cho các thay đổi dự án do Agent điều khiển.

Tiếp theo là gì

Với Nhánh AI cung cấp lớp an toàn, tất cả các mảnh ghép đã ở đúng vị trí:

• MCP để kết nối công cụ (Phần 1)
• CLI + SKILL để thực thi quy trình làm việc (Phần 2-5)
• Kết quả xác thực (Phần 6)
• Các quy trình làm việc thực tế (Phần 7)
• Nền tảng CI/CD (Phần 8)
• Nhánh AI để đảm bảo an toàn (Phần 9)

Bây giờ là lúc cho tầm nhìn.

Trong Phần 10, "Thiết kế theo đặc tả" là chuyện của ngày hôm qua. Chào mừng đến với "Thiết kế theo kỹ năng"., chúng ta sẽ phác thảo cách phát triển API tiến hóa cùng với AI Agent—và những gì các nhóm nên làm tiếp theo.

Những điểm chính

• Nhánh AI cung cấp khả năng chỉnh sửa biệt lập cho các hoạt động AI/CLI
• Các thay đổi không ảnh hưởng đến nhánh chính cho đến khi có xác nhận của con người
• Tạo bằng branch create --type ai, ghi bằng tham số --branch
• Nhập tài nguyên hiện có bằng branch pick-to trước khi chỉnh sửa
• Xem trước bằng merge-request preview, sau đó hợp nhất hoặc tạo yêu cầu hợp nhất
• Quyền chỉnh sửa trực tiếp có thể bỏ qua Nhánh AI—hãy sử dụng cẩn thận
• Thực hành tốt nhất: một Nhánh AI cho mỗi tác vụ, xác thực trước khi ghi, xem xét trước khi hợp nhất

Tải xuống Apidog để thiết kế, giả lập, kiểm thử, và tạo tài liệu API trong một không gian làm việc. Tìm hiểu thêm về Apidog CLI để kiểm thử API dòng lệnh, tự động hóa CI và quy trình làm việc của AI Agent.

nút