Đây là phần 9 trong loạt 10 bài về cách Apidog phát triển Apidog CLI, 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 đi thẳng đến phần phù hợp với vấn đề bạn đang xử lý.
| Phần | Tiêu đề | Trọng tâm |
|---|---|---|
| 1 | Chúng tôi đã xây dựng 126 Công cụ MCP. Nhưng đó không phải là Giải pháp tốt nhất cho Agent | Khám phá vấn đề |
| 2 | Tại sao chúng tôi phát triển Apidog CLI hoàn toàn mới | Phát triển kiến trúc |
| 3 | Quy tắc vàng: CLI tạo ra dữ kiện, Mô hình hành động dựa trên dữ kiện | Triết lý cốt lõi |
| 4 | agentHints: Dạy CLI giao tiếp với Agent |
Kết quả có cấu trúc |
| 5 | SKILL: Chuyển giao kinh nghiệm vận hành dưới dạng mã | Kinh nghiệm vận hành |
| 6 | Những con số không nói dối: Giảm 30% lượt gọi công cụ, giảm 25% token | Kết quả định lượng |
| 7 | Từ PRD đến Vòng lặp kiểm thử: Quy trình làm việc Agent hoàn chỉnh với Apidog CLI | Hướng dẫn thực hành |
| 8 | Tại sao Khả năng tương thích CI/CD là không thể thiếu đối với các công cụ Agent | Góc nhìn DevOps |
| 9 | Nhánh AI: Thay đổi dự án an toàn hơn với AI Agent | Lớp bảo mật |
| 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". | Tầm nhìn & tương lai |
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à bắt buộc. Nhánh AI cung cấp một môi trường chỉnh sửa biệt lập: 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.
Vấn đề: Agent có thể ghi vào tài nguyên dự án
Khi AI Agent tham gia phát triển và kiểm thử API, chúng có thể gọi CLI để:
- tạo endpoint
- cập nhật schema
- sửa test scenario
- tạo test suite
- thay đổi tài liệu hoặc cấu trúc tài nguyên
Quyền ghi này hữu ích, nhưng cũng tạo rủi ro.
| Rủi ro | Điều gì có thể xảy ra |
|---|---|
| Đầu ra không thể đoán trước | Agent ghi nội dung không mong muốn |
| Lỗi trường | Thiếu tham số, sai định dạng, xác nhận sai |
| Mở rộng phạm vi | Agent sửa tài nguyên ngoài nhiệm vụ |
| Không có dấu vết xem xét | Thay đổi xuất hiện trực tiếp trên nhánh chính |
| Gián đoạn nhóm | Nhánh cộng tác bị thay đổi đột ngột |
Câu hỏi thực tế là:
Làm thế nào để cho phép Agent làm việc trên dự án thật mà không để nó ghi thẳng vào nhánh chính?
Nhánh AI là gì?
Nhánh AI là một loại Nhánh Sprint đặc biệt, được thiết kế cho thao tác từ AI và CLI bên ngoài.
Nguyên tắc chính:
Tất cả thao tác chỉnh sửa được khởi tạo từ Apidog CLI được coi là thao tác do AI / AI Agent khởi tạo theo mặc định.
Thay vì ghi trực tiếp vào nhánh chính, Agent ghi vào một nhánh biệt lập.
Agent thực hiện thay đổi qua CLI
↓
Thay đổi được lưu trong Nhánh AI
↓
Người dùng xem diff
↓
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
Nhánh chính không bị ảnh hưởng cho đến khi bạn phê duyệt.
Khi nào nên dùng Nhánh AI?
Dùng Nhánh AI cho các thao tác ghi do AI khởi tạo, đặc biệt khi Agent có thể sửa nhiều loại tài nguyên:
- endpoint
- schema
- test scenario
- test suite
- tài liệu API
- thư mục hoặc cấu trúc tài nguyên
| Không có Nhánh AI | Với Nhánh AI |
|---|---|
| Agent ghi trực tiếp vào nhánh chính | Agent ghi vào nhánh biệt lập |
| Thay đổi xuất hiện ngay lập tức | Thay đổi chờ được xem xét |
| Không có lưới an toàn | Cần xác nhận của con người |
| Dễ sửa ngoài phạm vi | Có thể giới hạn phạm vi tài nguyên |
Đặc điểm chính của Nhánh AI
| Đặc điểm | Mô tả |
|---|---|
| Chỉnh sửa biệt lập | Thay đổi nằm trong Nhánh AI, không ảnh hưởng nhánh chính hoặc nhánh nguồn |
| Nguồn rõ ràng | Không tạo từ client; đến từ CLI/MCP và ghi lại nhánh nguồn |
| Xác nhận của con người | Phải được xem xét trước khi hợp nhất |
| Không giới hạn số lượng | Có thể tạo nhiều Nhánh AI cho nhiều tác vụ |
| Lưu trữ tự động | Nhánh không có diff được lưu trữ sau mỗi 24 giờ |
Luồng hoạt động thường gặp:
| Thao tác | Nơi diễn ra |
|---|---|
| AI tạo endpoint | Trong Nhánh AI |
| AI cập nhật test scenario | Trong Nhánh AI |
| Nhóm xem thay đổi | Trong client hoặc qua CLI preview |
| Người dùng phê duyệt merge | Hành động của người dùng |
| Thay đổi vào nhánh mục tiêu | Sau khi xác nhận |
Lưu ý: chỉnh sửa thông thường trong client bởi người dùng vẫn tuân theo quyền thành viên dự án và quy tắc bảo vệ nhánh.
Các trường hợp sử dụng thực tế
Nhánh AI phù hợp khi bạn muốn Agent hỗ trợ bảo trì dự án nhưng vẫn cần review trước khi merge.
| Kịch bản | Nhánh AI hỗ trợ như thế nào |
|---|---|
| Tạo bản nháp API từ mã | AI tạo endpoint trong Nhánh AI; người dùng xác nhận trước khi merge |
| Tổ chức tài nguyên API hàng loạt | AI điều chỉnh thư mục, mô tả, model mà không ảnh hưởng nhánh cộng tác |
| Tạo test draft tự động | AI tạo test scenario/test case để tester review |
| Bổ sung tài liệu API | AI điền trường còn thiếu dựa trên lỗi hoặc triển khai |
| Ghi hàng loạt trong CI/CD | Workflow tự động ghi vào Nhánh AI, chờ người dùng merge |
Quy trình làm việc cơ bản
Một workflow an toàn với Nhánh AI thường gồm 5 bước:
1. Tạo Nhánh AI
apidog branch create --type ai --name "ai/20260312-from-main-feature" --from main
2. Nhập hoặc tạo tài nguyên
apidog branch pick-to
hoặc
apidog endpoint create
3. Agent sửa tài nguyên
dùng --branch để ghi vào Nhánh AI
4. Xem diff
apidog merge-request preview
hoặc xem trong client Apidog
5. Merge vào nhánh mục tiêu
branch merge
hoặc merge-request create
Bước 1: Tạo Nhánh AI
Dùng branch create --type ai:
apidog branch create \
--project 123456 \
--type ai \
--name "ai/20260312-from-main-userRegister" \
--from main
Quy ước đặt tên nên rõ ràng:
ai/YYYYMMDD-from-sourceBranch-featureOrModule
Ví dụ:
ai/20260312-from-main-userRegister
ai/20260313-from-develop-orderDocs
ai/20260314-from-main-paymentTests
Các lệnh thường dùng:
| Lệnh | Mục đích |
|---|---|
branch create --type ai |
Tạo Nhánh AI |
branch list --type ai |
Xem các Nhánh AI trong dự án |
branch list --type all |
Xem tất cả loại nhánh |
branch get --type ai |
Xem chi tiết Nhánh AI |
Bước 2: Ghi tài nguyên vào Nhánh AI
Khi CLI ghi tài nguyên dự án, luôn truyền --branch để chỉ định Nhánh AI.
| Tài nguyên | Ví dụ lệnh |
|---|---|
| HTTP endpoint | apidog endpoint create --project <id> --branch <aiBranchName> --file ./endpoint.json |
| Data model | apidog schema update <schemaId> --project <id> --branch <aiBranchName> --file ./schema.json |
| Test scenario | apidog test-scenario update <scenarioId> --project <id> --branch <aiBranchName> --file ./scenario.json |
| Test suite | apidog test-suite create --project <id> --branch <aiBranchName> --file ./suite.json |
Workflow khuyến nghị:
# 1. Lấy schema của lệnh cần dùng
apidog cli-schema get endpoint-create
# 2. Validate payload trước khi ghi
apidog cli-schema validate endpoint-create --file ./endpoint.json
# 3. Ghi vào Nhánh AI, không ghi vào main
apidog endpoint create \
--project 123456 \
--branch "ai/20260312-from-main-userRegister" \
--file ./endpoint.json
Điểm quan trọng: Agent có thể tạo JSON, nhưng bạn nên validate trước khi ghi vào dự án.
Bước 3: Nhập tài nguyên hiện có trước khi sửa
Nếu Agent cần sửa tài nguyên đã tồn tại, hãy nhập tài nguyên từ nhánh nguồn vào Nhánh AI trước.
apidog branch pick-to \
--project 123456 \
--from main \
--to "ai/20260312-from-main-userRegister" \
--endpoint-ids 1001,1002
Cách này giúp Agent làm việc trên phiên bản cơ sở đúng, tránh sửa nhầm hoặc tạo bản sao không cần thiết.
Bước 4: Xem thay đổi trước khi merge
Trước khi hợp nhất, xem diff bằng CLI:
apidog merge-request preview \
--project 123456 \
--from "ai/20260312-from-main-userRegister" \
--to main
Hoặc xem toàn bộ thay đổi trong client Apidog.
| Lệnh | Mục đích |
|---|---|
merge-request preview |
Quét các thay đổi ứng cử viên |
branch get --type ai |
Xem thông tin Nhánh AI |
Checklist trước khi merge:
- endpoint nào được tạo hoặc sửa?
- schema liên quan có thay đổi không?
- test scenario/test suite có phụ thuộc tài nguyên khác không?
- thư mục, response component hoặc model liên quan có cần merge cùng không?
- nội dung do AI tạo có đúng chuẩn dự án không?
Bước 5: Hợp nhất Nhánh AI
Sau khi review, bạn có hai cách hợp nhất.
Cách 1: Merge trực tiếp vào 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
Cách 2: Tạo merge request cho 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
Các lệnh liên quan:
| Lệnh | Mục đích |
|---|---|
branch merge |
Merge trực tiếp vào nhánh không được bảo vệ |
merge-request create |
Tạo yêu cầu hợp nhất để review |
merge-request approve |
Phê duyệt yêu cầu hợp nhất |
merge-request reject |
Từ chối yêu cầu hợp nhất |
Quan trọng: các lệnh merge chỉ xử lý danh sách tài nguyên được cung cấp rõ ràng. Hãy xác nhận dependency như thư mục, model, response component và test trước khi merge.
Lưu trữ hoặc xóa Nhánh AI
Sau khi thay đổi đã được merge hoặc không còn cần thiết, lưu trữ nhánh:
apidog branch archive "ai/20260312-from-main-userRegister" \
--project 123456 \
--type ai
Nếu cần 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ữ thay đổi do AI tạo ra trong vùng biệt lập cho đến khi người dùng xác nhận.
Nếu muốn bật chỉnh sửa trực tiếp, cấu hình tại:
Project Settings
→ Feature Settings
→ AI Feature Settings
→ External AI Edit Permissions
| Quyền | Cho phép gì |
|---|---|
| Chỉnh sửa trực tiếp nhánh chính | CLI ghi trực tiếp vào nhánh chính, bỏ qua Nhánh AI |
| Chỉnh sửa trực tiếp nhánh sprint tiêu chuẩn | CLI ghi trực tiếp vào nhánh sprint |
| Chỉnh sửa trực tiếp nhánh chung | CLI ghi trực tiếp vào nhánh chung |
| Chỉnh sửa trực tiếp Nhánh AI | CLI ghi vào Nhánh AI |
Khuyến nghị: giữ cơ chế biệt lập bằng Nhánh AI. Chỉ bật chỉnh sửa trực tiếp khi workflow tự động hóa thực sự cần và đã có lớp kiểm soát khác.
Best practices khi dùng Nhánh AI
| Thực hành | Lý do |
|---|---|
| Một Nhánh AI cho mỗi tác vụ | Giữ phạm vi rõ ràng: đăng ký người dùng, tài liệu đơn hàng, test thanh toán |
| Nhập trước khi sửa | Dùng pick-to cho tài nguyên hiện có để tránh nhầm nguồn |
| Validate trước khi ghi | Dùng cli-schema validate để phát hiện lỗi cấu trúc |
| Preview trước khi merge | Dùng merge-request preview hoặc xem diff trong client |
| Merge theo phạm vi rõ ràng | Xác nhận endpoint, model, thư mục và test liên quan |
| Giữ review của con người | API definition và test script nên được kiểm tra trước khi merge |
| Lưu trữ kịp thời | Giữ danh sách nhánh gọn sau khi merge hoặc hủy |
Nhánh AI trong workflow CLI + SKILL
Nhánh AI phù hợp tự nhiên với quy trình CLI + SKILL:
| Giai đoạn | CLI + SKILL + Nhánh AI |
|---|---|
| Đọc |
endpoint get từ bất kỳ nhánh nào |
| Tạo | Agent tạo JSON |
| Validate |
cli-schema validate cục bộ |
| Ghi |
endpoint create --branch <aiBranchName> vào Nhánh AI |
| Review | merge-request preview |
| Merge | Người dùng xác nhận, sau đó branch merge
|
| Xác minh |
apidog run trên tài nguyên đã merge |
Mẫu an toàn là:
Mọi thao tác ghi → Nhánh AI → review của con người → merge
Tóm tắt lớp bảo vệ
| Lớp | Bảo vệ |
|---|---|
cli-schema validate |
Phát hiện lỗi cấu trúc trước khi ghi |
agentHints |
Hướng dẫn Agent thực hiện bước tiếp theo an toàn |
| Nhánh AI | Biệt lập thay đổi khỏi nhánh chính |
| Review của con người | Xác nhận nội dung trước khi merge |
| Phạm vi merge | Người dùng chọn tài nguyên nào được hợp nhất |
Kết hợp lại, các lớp này tạo ra một vòng lặp an toàn hơn cho thay đổi dự án do Agent điều khiển.
Tiếp theo là gì?
Với Nhánh AI, các thành phần chính của workflow đã đầy đủ:
- MCP để kết nối công cụ — Phần 1
- CLI + SKILL để thực thi quy trình — Phần 2 đến 5
- Kết quả xác thực — Phần 6
- Workflow 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
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ẽ xem cách phát triển API tiến hóa cùng AI Agent và các nhóm nên chuẩn bị gì tiếp theo.
Những điểm chính
- Nhánh AI cung cấp vùng chỉnh sửa biệt lập cho thao tác AI/CLI.
- Thay đổi không ảnh hưởng nhánh chính cho đến khi có xác nhận của con người.
- Tạo Nhánh AI bằng
branch create --type ai. - Ghi tài nguyên vào Nhánh AI bằng tham số
--branch. - Nhập tài nguyên hiện có bằng
branch pick-totrước khi chỉnh sửa. - Xem trước bằng
merge-request preview, sau đó merge hoặc tạo merge request. - Quyền chỉnh sửa trực tiếp có thể bỏ qua Nhánh AI, nên dùng cẩn thận.
- Workflow an toàn: một Nhánh AI cho mỗi tác vụ, validate trước khi ghi, review trước khi merge.
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à workflow AI Agent.
Top comments (0)