Sebastian Petrus

Posted on Jul 6 • Originally published at apidog.com

Apidog CLI + SKILL hoàn toàn mới: Tại sao chúng tôi phát triển

Đây là chuỗi 10 phần chia sẻ 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 chuyển đến phần phù hợp với nhu cầu triển khai của mình:

Thử Apidog ngay hôm nay

	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	Phát hiện 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 sự thật, Model hành động dựa trên sự thật	Triết lý cốt lõi
4	`agentHints`: Dạy CLI giao tiếp với Agent	Đầu ra có cấu trúc
5	SKILL: Chuyển đổi kinh nghiệm vận hành thành mã	Kinh nghiệm vận hành
6	Những con số không biết nói dối: Giảm 30% số lần gọi công cụ, giảm 25% số lượng 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à điều không thể thiếu đối với các công cụ Agent	Góc nhìn DevOps
9	AI Branch: Thay đổi dự án an toàn hơn với AI Agent	Lớp bảo mật
10	Spec-First đã là quá khứ. Chào mừng đến với Skill-First.	Tầm nhìn & tương lai

Chúng tôi xây dựng CLI + SKILL để xử lý những gì MCP không tối ưu: quy trình làm việc phức tạp, có cổng xác thực và thực thi có cấu trúc.

MCP vẫn phù hợp cho đúng loại tác vụ

Trước khi đi vào CLI + SKILL, cần làm rõ: Apidog MCP vẫn khả dụng và được duy trì.

MCP cung cấp kết nối công cụ theo giao thức tiêu chuẩn. Cách tiếp cận này hữu ích khi bạn cần:

Gọi các công cụ đơn giản, được xác định rõ
Làm việc trong workflow ưu tiên MCP
Tích hợp với các client tương thích MCP

CLI + SKILL không thay thế MCP. Nó bổ sung cho MCP.

Khác biệt nằm ở loại workflow. MCP mạnh ở kết nối công cụ. Nhưng với workflow R&D nhiều bước — ví dụ tạo test, xác thực schema, ghi lại vào dự án, rồi chạy kiểm thử — Agent cần một quy trình kỹ thuật có thể thực thi ổn định hơn.

Loại tác vụ	Cách tiếp cận khuyến nghị
Gọi công cụ đơn giản, ví dụ lấy endpoint	MCP hoặc CLI
Workflow nhiều bước, ví dụ tạo test → xác thực → chạy	CLI + SKILL
Tích hợp CI/CD	CLI
Tích hợp hệ sinh thái MCP	MCP

CLI cũ: chạy kiểm thử ở cuối pipeline

Apidog CLI trước đây chủ yếu là điểm vào dòng lệnh để chạy kiểm thử API:

apidog run --project <projectId> --test-scenario <scenarioId> --environment <environmentId>

Cách dùng này vẫn quan trọng trong automation:

Chạy API test từ terminal
Tạo báo cáo trong CI pipeline
Giữ quality gate trong quy trình release

Trong mô hình cũ, CLI thường xuất hiện ở cuối workflow:

Thiết kế → Tài liệu → Mock → Gỡ lỗi → Kiểm thử → [CLI chạy kiểm thử]

Nói cách khác, CLI là bước thực thi sau khi phần lớn công việc đã hoàn tất.

Yêu cầu mới: Agent cần đọc, ghi và xác minh

Phát triển API đang thay đổi vì AI Agent bắt đầu tham gia sớm hơn vào vòng đời API.

Giai đoạn	Hoạt động của Agent
Thiết kế API	Tạo định nghĩa endpoint từ PRD
Tạo kiểm thử	Tạo test case từ đặc tả API
Gỡ lỗi	Phân tích lỗi, đề xuất cách sửa
Di chuyển	Di chuyển API giữa các dự án
Bảo trì	Cập nhật kiểm thử khi API thay đổi

Với các workflow này, CLI không thể chỉ chạy các test đã có. Nó cần hỗ trợ Agent thực hiện các bước kỹ thuật an toàn hơn:

Đọc tài sản API: endpoint, schema, environment
Tạo hoặc cập nhật tài sản kiểm thử: test case, test scenario
Xác thực cấu trúc trước khi ghi
Ghi thay đổi trở lại dự án
Chạy xác minh sau khi thay đổi

Đây là lý do CLI mới được mở rộng thành lớp workflow, không chỉ là công cụ chạy test.

Mở rộng có hệ thống thay vì thêm lệnh rời rạc

Apidog CLI mới không chỉ thêm vài command vào CLI cũ. Mục tiêu là đưa các khả năng cốt lõi của Apidog vào CLI để developer, script và AI Agent có thể thao tác với dự án theo cách ổn định.

CLI cũ hỏi	CLI mới hỏi
“Làm cách nào để chạy test Apidog bên ngoài?”	“Làm cách nào để AI Agent sử dụng Apidog ổn định?”

Điểm thay đổi nằm ở ranh giới kiến trúc: CLI giờ không chỉ là runner, mà là lớp thực thi workflow có xác thực.

MCP vs CLI + SKILL: so sánh chuỗi thực thi

Lộ trình MCP: phù hợp cho kết nối công cụ

Một workflow MCP điển hình có thể trông như sau:

Khởi tạo phiên MCP
        ↓
Tải danh sách công cụ + mô tả công cụ
        ↓
Agent chọn công cụ
        ↓
Tìm kiếm thêm công cụ (listOpenApiEndpoints)
        ↓
Lấy schema (getOpenApiDetails)
        ↓
Thực thi cuộc gọi HTTP (executeOpenApi)

Điểm mạnh: MCP cung cấp giao thức tiêu chuẩn để kết nối công cụ với Agent.

Phần phức tạp: Agent phải giữ nhiều thông tin trong ngữ cảnh model:

Danh sách công cụ
Mô tả công cụ
Schema đầu vào
Thứ tự gọi
Cấu trúc trả về

MCP hoạt động tốt khi ánh xạ giữa tác vụ và công cụ rõ ràng. Nó trở nên khó hơn khi Agent phải điều phối nhiều bước, hiểu ngữ nghĩa sản phẩm và xử lý xác thực.

Lộ trình CLI + SKILL: phù hợp cho workflow phức tạp

Với CLI + SKILL, workflow được đưa vào hệ thống kỹ thuật nhiều hơn:

SKILL đánh giá loại tác vụ
        ↓
CLI thực thi các lệnh theo ngữ nghĩa sản phẩm
        ↓
cli-schema xác thực cấu trúc
        ↓
agentHints gợi ý bước tiếp theo
        ↓
Vòng lặp xác minh: đọc lại hoặc apidog run

Điểm mạnh: CLI + SKILL phân tách trách nhiệm rõ ràng:

SKILL: phương pháp luận và hướng dẫn workflow
CLI: thực thi hành động theo ngữ nghĩa sản phẩm
cli-schema: xác thực cấu trúc trước khi ghi
agentHints: định hướng bước tiếp theo sau khi thực thi

Cách này phù hợp hơn với workflow nhiều bước, có cổng xác thực và cần chạy kiểm thử xác minh.

Khác biệt chính: sự phức tạp nằm ở đâu?

Cách tiếp cận	Nơi sự phức tạp tồn tại	Phù hợp nhất cho
MCP	Ngữ cảnh model + bước chọn công cụ	Gọi công cụ đơn giản, hệ sinh thái MCP
CLI + SKILL	Hệ thống kỹ thuật: SKILL, CLI, xác thực, gợi ý	Workflow phức tạp, thao tác nhiều bước

Với MCP, model cần tự xử lý:

Công cụ nào nên dùng
Mô tả công cụ có ý nghĩa gì
Field nào bắt buộc
Trình tự nào đúng
Kết quả trả về nên được diễn giải ra sao

Với CLI + SKILL, hệ thống kỹ thuật hỗ trợ nhiều phần hơn:

SKILL xác định loại tác vụ
CLI thực thi lệnh phù hợp
cli-schema kiểm tra cấu trúc hợp lệ
agentHints hướng dẫn bước tiếp theo

Cách này giảm tải suy luận cho model trong các workflow cần đọc lại, xác thực và xác minh.

Ví dụ workflow CLI + SKILL

Một workflow thực tế có thể bắt đầu bằng việc đọc trạng thái hiện tại, xác thực thay đổi, rồi chạy kiểm thử:

# Bước 1: Đọc sự thật từ dự án
apidog endpoint get <endpointId> --project <projectId>

# Bước 2: Xác thực cấu trúc trước khi ghi
apidog cli-schema validate test-case-create --file ./test-case-create.json

# Bước 3: Chạy xác minh
apidog run --project <projectId> --out-dir ./apidog-reports

Ba lệnh này tương ứng với ba hành động kỹ thuật quan trọng:

Lệnh	Hành động
`endpoint get`	Đọc dữ liệu hiện tại từ dự án
`cli-schema validate`	Xác thực cấu trúc trước khi ghi
`apidog run`	Chạy kiểm thử để xác minh

Cấu trúc này giúp Agent tránh ghi thay đổi dựa trên giả định. Thay vào đó, Agent đọc trạng thái hiện có, tạo thay đổi dựa trên dữ liệu thật, xác thực, rồi mới chạy kiểm thử.

Lộ trình Agent cho workflow phức tạp

Nếu dùng MCP

Chọn công cụ → Hiểu schema → Điều phối trình tự → Xử lý lỗi

Agent phải:

Chọn công cụ phù hợp từ nhiều lựa chọn
Hiểu mô tả công cụ và schema
Tự điều phối trình tự gọi
Xử lý lỗi bằng thử lại hoặc điều chỉnh prompt

Cách này có thể hoạt động, nhưng mỗi điểm quyết định đều phụ thuộc nhiều vào suy luận của model.

Nếu dùng CLI + SKILL

Đọc sự thật → Tạo thay đổi → Xác thực cấu trúc → Ghi → Chạy xác minh

Agent được hướng dẫn theo một quy trình kỹ thuật rõ hơn:

Đọc dữ liệu hiện có trước
Tạo thay đổi dựa trên dữ liệu đã đọc
Xác thực cấu trúc bằng cli-schema
Ghi thay đổi vào dự án
Chạy xác minh bằng apidog run hoặc đọc lại kết quả

Cả hai lộ trình đều có thể hoàn thành tác vụ. Khác biệt là CLI + SKILL chuyển nhiều phần phức tạp từ ngữ cảnh model sang hệ thống kỹ thuật.

CLI hiện bao gồm những gì?

Với bản nâng cấp, CLI bao phủ nhiều tài nguyên Apidog cốt lõi hơn:

Tài nguyên	Khả năng CLI
Dự án & metadata	Liệt kê, đọc
API & định nghĩa API	Lấy, tạo, cập nhật
Môi trường & biến	Liệt kê, quản lý
Test case	Tạo, cập nhật, xác thực
Test scenario	Tạo, cập nhật, nhập bước, lấy chi tiết
Test suite	Quản lý
Báo cáo	Tạo từ `apidog run`
Nhập/xuất	Xuất dự án, nhập tệp

Điều này thay đổi vai trò của Apidog CLI.

CLI không chỉ chạy test sau khi mọi thứ hoàn thành. Nó có thể tham gia sớm hơn vào vòng lặp phát triển, nơi Agent cần:

Hiểu cấu trúc dự án
Tạo hoặc cập nhật test asset
Xác thực thay đổi trước khi ghi
Chạy kiểm thử để xác minh kết quả

Tóm tắt kiến trúc

Khía cạnh	MCP	CLI + SKILL
Điểm mạnh chính	Kết nối công cụ	Thực thi workflow
Nơi phức tạp tồn tại	Ngữ cảnh model	Hệ thống kỹ thuật
Lộ trình Agent cho tác vụ phức tạp	Chọn, điều phối, thử lại	Đọc, xác thực, ghi, xác minh
Phạm vi bao phủ	126 công cụ được tạo ra + công cụ gốc	Quản lý tài nguyên đầy đủ + xác thực
Phù hợp nhất	Thao tác đơn giản, hệ sinh thái MCP	Workflow phức tạp, CI/CD

Cả MCP và CLI + SKILL đều có sẵn. Hãy chọn theo độ phức tạp của tác vụ.

Khi nào nên chọn MCP, khi nào nên chọn CLI + SKILL?

Dùng MCP khi:

Tác vụ chỉ cần một hoặc vài lần gọi công cụ
Bạn đang làm việc trong hệ sinh thái MCP
Mapping giữa tác vụ và công cụ rõ ràng
Không có nhiều bước xác thực hoặc ghi thay đổi

Dùng CLI + SKILL khi:

Workflow có nhiều bước phụ thuộc nhau
Agent cần đọc dữ liệu hiện có trước khi tạo thay đổi
Bạn cần xác thực cấu trúc trước khi ghi
Quy trình cần chạy trong CI/CD
Bạn muốn có vòng lặp xác minh rõ ràng sau khi thay đổi

Một quy tắc thực tế:

Nếu tác vụ là “gọi công cụ”, MCP phù hợp.
Nếu tác vụ là “thực thi workflow”, CLI + SKILL phù hợp hơn.

Tiếp theo là gì?

Sau khi xác định cách CLI + SKILL bổ sung cho MCP, câu hỏi tiếp theo là:

Nguyên tắc cốt lõi nào giúp CLI + SKILL hiệu quả cho workflow phức tạp?

Trong Phần 3, Quy tắc vàng: CLI tạo ra sự thật, Model hành động dựa trên sự thật, chúng ta sẽ đi vào triết lý thiết kế định hướng CLI + SKILL — bắt đầu với cli-schema validate, cổng chất lượng giúp phát hiện lỗi trước khi chúng trở thành các lần ghi thất bại.

Những điểm chính

MCP vẫn được duy trì và phù hợp cho thao tác đơn giản hoặc tích hợp hệ sinh thái MCP.
CLI + SKILL bổ sung cho MCP bằng cách hỗ trợ workflow nhiều bước có xác thực.
Khác biệt chính là nơi đặt sự phức tạp: ngữ cảnh model hoặc hệ thống kỹ thuật.
CLI + SKILL giảm tải cho model bằng xác thực, hướng dẫn và vòng lặp xác minh.
CLI hiện bao phủ dự án, API, môi trường, test case, test scenario, test suite, báo cáo và nhập/xuất.
Chọn MCP hay CLI + SKILL dựa trên độ phức tạp của tác vụ, không phải theo tư duy “cái nào thay thế cái nào”.

Tải xuống Apidog để thiết kế, mock, kiểm thử và tài liệu hóa API trong một workspace duy nhất. Tìm hiểu thêm về Apidog CLI để kiểm thử API bằng dòng lệnh, tự động hóa CI và xây dựng workflow cho AI Agent.

DEV Community