Cách sử dụng Apidog CLI trong DeepSeek Harness

DeepSeek Harness là một vòng lặp tác tử: agent đọc workspace, sửa tệp, chạy lệnh qua bash và quyết định bước tiếp theo dựa trên đầu ra. Nếu kiểm thử API chỉ nằm trong giao diện Apidog và chỉ chạy khi ai đó nhớ nhấp chuột, chúng không bao giờ tham gia vào vòng lặp đó. Mục tiêu của hướng dẫn này là đưa kịch bản Apidog vào cùng chu trình sửa mã → chạy kiểm thử → đọc lỗi → sửa lại.

Dùng thử Apidog ngay hôm nay

Apidog CLI là gói npm apidog-cli, cho phép chạy các kịch bản kiểm thử đã tạo trong Apidog trực tiếp từ terminal. Khi DeepSeek Harness biết lệnh này, agent có thể chạy kiểm thử API như chạy unit test: thực thi lệnh, đọc mã thoát và sửa mã khi kiểm thử thất bại.

Cách này cũng tiết kiệm ngữ cảnh cho agent. Thay vì đọc lại route, handler và suy luận về response để đoán API có đúng không, agent chỉ cần chạy một lệnh. CLI biến câu hỏi “API có đúng không?” thành đầu ra kiểm thử và mã thoát rõ ràng.

Hướng dẫn này tập trung vào phần tích hợp với harness:

• DeepSeek Harness đọc tệp hướng dẫn nào.
• Cách để agent chạy apidog run.
• Cách xác minh agent thực sự đã chạy kiểm thử.
• Cách giữ vòng lặp kiểm thử đáng tin cậy.

Trước khi bắt đầu, hãy đảm bảo lệnh sau hoạt động:

apidog --version

Bạn cũng cần xác thực Apidog CLI trước đó. Nếu chưa cài đặt, xem Cách cài đặt Apidog CLI với một agent mã hóa AI.

DeepSeek Harness này là về điều gì

DeepSeek Harness, với lệnh CLI là dsh, là công cụ harness agent mã nguồn mở mà DeepSeek phát hành vào ngày 13 tháng 8 năm 2026, cùng với V4-Pro trên API.

Dự án được cấp phép MIT và đặt tại github.com/deepseek-ai/deepseek-harness. Tính đến ngày 20 tháng 8, dự án đã vượt 169k sao.

Khởi động giao diện web cục bộ bằng lệnh:

npx @deepseek-ai/dsh web

Sau đó mở:

http://127.0.0.1:3080

Trong giao diện này, chọn workspace là thư mục dự án của bạn. Agent sẽ làm việc trong workspace đó: đọc và sửa tệp, chạy lệnh, đồng thời yêu cầu phê duyệt cho những thao tác bị chặn bởi chính sách quyền hạn.

DeepSeek Harness là bản xem trước dành cho nhà phát triển. README cảnh báo có thể xuất hiện thay đổi phá vỡ tương thích. Hãy kiểm tra lại tài liệu trong repo nếu tên tệp hoặc khóa cấu hình trong bài không còn hoạt động.

Dsh được xây dựng trên kiến trúc plugin Cordis. Điều này quan trọng vì việc nạp quy tắc dự án, chạy bash và tích hợp MCP đều được xử lý qua plugin.

Để biết thêm bối cảnh, xem DeepSeek Harness là gì và DeepSeek Harness so với Claude Code.

Bước 1: Thêm lệnh Apidog CLI vào AGENTS.md

DeepSeek Harness đọc hướng dẫn workspace qua plugin @deepseek-ai/dsh-agent-instructions.

Theo mã nguồn plugin và danh mục cấu hình, trình tải sẽ:

1. Bắt đầu từ thư mục làm việc của phiên agent.
2. Đi ngược lên đến thư mục gốc Git, được đánh dấu bằng .git.
3. Tải AGENTS.md, sau đó là CLAUDE.md, ở từng cấp thư mục.
4. Tải các lớp phủ cục bộ sau tệp cơ sở:
   • AGENTS.local.md
   • CLAUDE.local.md
5. Áp dụng thêm AGENTS.md toàn cục trong $DSH_HOME, mặc định là ~/.dsh.

Các tệp lớn hơn 1 MiB sẽ bị bỏ qua.

Nếu repository đã có AGENTS.md cho Codex hoặc CLAUDE.md cho Claude Code, DeepSeek Harness có thể dùng lại tệp đó. Thêm một khối hướng dẫn ngắn gọn như sau:

## API testing with the Apidog CLI
- To test the API, run the Apidog scenario. Do not click through the GUI.
- Command: apidog run -t <scenario_id> -e <env_id> -r cli
- Exit code 0 means every assertion passed. Non-zero means a failure; read the report and fix the code.
- The machine is already authenticated. Never add an --access-token flag and never put a token in this file.

Thay <scenario_id> và <env_id> bằng ID thực tế của dự án.

Ví dụ:

## API testing with the Apidog CLI
- Run this command after changing API handlers:
  apidog run -t 123456 -e 789012 -r cli
- Exit code 0 means all API assertions passed.
- For a non-zero exit code, inspect the failed assertion, fix the code, then run the command again.
- Do not add access tokens to this file. The machine is already authenticated.

Đặt lệnh trong AGENTS.md thay vì chỉ gửi trong chat có lợi ích rõ ràng:

• Hướng dẫn được tải trong mọi phiên mới.
• Đồng đội clone repository cũng nhận cùng quy trình.
• Agent không phải đoán ID kịch bản hoặc môi trường.
• Quy trình kiểm thử API trở thành một phần của repository.

Nếu làm việc với nhiều dự án, dùng ~/.dsh/AGENTS.md cho quy tắc chung, ví dụ:

Always verify API changes using the project's `apidog run` command.

Sau đó lưu ID kịch bản cụ thể trong AGENTS.md của từng repository.

Bước 2: Lấy lệnh chính xác từ Apidog

Không tự đoán ID kịch bản hoặc ID môi trường.

Trong Apidog:

1. Mở kịch bản kiểm thử.
2. Chuyển đến tab CI/CD.
3. Sao chép lệnh do Apidog tạo.

Lệnh thường có dạng:

apidog run -t 123456 -e 789012 -r cli

Ý nghĩa các cờ:

Cờ	Ý nghĩa
-t	ID kịch bản kiểm thử
-e	ID môi trường
-r cli	In báo cáo trực tiếp ra terminal

Dán nguyên lệnh đó vào AGENTS.md. Đây là cách tránh để agent tự tạo hoặc nhớ nhầm ID.

Bước 3: Yêu cầu agent chạy kiểm thử

Mở phiên DeepSeek Harness với workspace đã chọn. Vì AGENTS.md đã được nạp vào ngữ cảnh, agent biết cần dùng Apidog CLI.

Sau khi agent sửa một handler, route hoặc logic liên quan đến API, yêu cầu rõ ràng:

Chạy kịch bản kiểm thử Apidog và cho tôi biết mã thoát.

Hoặc:

Sau khi sửa endpoint này, hãy chạy lệnh Apidog trong AGENTS.md. Nếu thất bại, đọc lỗi, sửa mã và chạy lại.

Agent sẽ chạy lệnh qua công cụ bash.

Theo danh mục công cụ, bash mặc định trong dsh chạy mỗi lệnh trong một shell mới. Điều này có nghĩa là:

• cd ở lệnh trước không còn hiệu lực ở lệnh sau.
• Biến môi trường shell cục bộ không được giữ giữa các lần gọi.
• Hàm shell cũng không được giữ.
• Lệnh chạy từ workspace của phiên, trừ khi công cụ nhận workdir.

Vì vậy, tránh hướng dẫn agent làm như sau:

cd services/api
apidog run -t 123456 -e 789012 -r cli

Thay vào đó, nếu cần chạy từ thư mục con, đặt toàn bộ lệnh trên một dòng:

cd services/api && apidog run -t 123456 -e 789012 -r cli

Hoặc cấu hình workdir nếu công cụ bash của phiên hỗ trợ tham số đó.

Khi lệnh thất bại, dsh hiển thị dấu hiệu rõ ràng:

[exit code: 1]

Mã thoát này vẫn hữu ích ngay cả khi đầu ra dài bị cắt ngắn.

Một số chính sách sandbox có thể chặn thao tác ghi tệp. Lệnh apidog run chỉ đọc thường ít gặp vấn đề, nhưng báo cáo HTML có thể ghi vào ./apidog-reports và có thể cần phê duyệt hoặc quyền ghi phù hợp.

Theo hướng dẫn người dùng, giao diện web sẽ yêu cầu phê duyệt cho các thao tác bị chính sách giới hạn. Khi được hỏi về lệnh apidog run trên môi trường staging, hãy kiểm tra lệnh và phê duyệt nếu phù hợp với quy trình của bạn.

Bước 4: Đọc báo cáo và sửa lỗi

Với -r cli, agent nhận được báo cáo trực tiếp trong terminal, bao gồm:

• Từng request.
• Từng assertion.
• Assertion nào thất bại.
• Giá trị mong đợi và giá trị thực tế.
• Mã trạng thái hoặc trường response không đúng.

Ví dụ, agent có thể thấy lỗi như:

Expected status: 200
Actual status: 500

Expected field: total
Actual: field is missing

Từ đó, agent có thể xác định handler hoặc phần mapping response cần sửa mà không cần bạn diễn giải lại lỗi.

Nếu cần báo cáo để mở trên trình duyệt hoặc gửi cho đồng đội, thêm reporter HTML:

apidog run -t 123456 -e 789012 -r cli,html

Reporter html ghi báo cáo độc lập vào:

./apidog-reports

Nên giữ cli trong danh sách reporter để agent vẫn có đầu ra terminal phục vụ quyết định bước tiếp theo.

Vòng lặp từ đầu đến cuối

Ví dụ, agent đang sửa payment handler.

Không có Apidog CLI, vòng lặp thường dừng ở đây:

Sửa mã → mã trông có vẻ đúng → báo hoàn thành

Có Apidog CLI trong AGENTS.md, vòng lặp trở thành:

Sửa payment handler
→ chạy apidog run -t 123456 -e 789012 -r cli
→ đọc mã thoát
→ đọc assertion thất bại nếu có
→ sửa mã
→ chạy lại

Nếu kiểm thử xanh:

[exit code: 0]

Agent có thể tiếp tục.

Nếu kiểm thử đỏ:

[exit code: 1]

Agent cần đọc lỗi cụ thể, ví dụ:

• API trả 500 thay vì 200.
• Thiếu trường total.
• Mã tiền tệ sai.
• Response không đúng schema.

Sau đó sửa handler và chạy lại đúng cùng kịch bản.

Điểm quan trọng là agent không cần đọc lại mọi route để tự thuyết phục rằng API hoạt động. Kịch bản Apidog đã mã hóa hành vi mong đợi. Agent chỉ cần dùng kết quả kiểm thử để xác minh thay đổi.

Phân công công việc rõ ràng:

• DeepSeek Harness viết và sửa mã.
• Apidog CLI xác minh hành vi API.
• Bạn hoặc đội API xây dựng kịch bản trực quan trong Apidog.

Xác minh dsh thực sự đã chạy kiểm thử

Không chỉ tin vào câu trả lời “đã chạy kiểm thử thành công” từ agent. Kiểm tra theo ba bước.

1. Kiểm tra lệnh bash thực tế

Giao diện web dsh hiển thị tool call và đầu ra trong phiên.

Tìm lệnh như sau:

apidog run -t 123456 -e 789012 -r cli

Nếu agent nói đã chạy kiểm thử nhưng không có tool call tương ứng, yêu cầu chạy lại và hiển thị đầu ra thô.

2. Kiểm tra mã thoát

Hỏi trực tiếp:

Mã thoát của lệnh apidog run là gì?

Khi thất bại, harness cung cấp dấu hiệu:

[exit code: N]

Nếu agent nói “kiểm thử đã qua” nhưng mã thoát khác 0, hãy tin mã thoát, không tin phần tóm tắt.

3. Kiểm tra ID kịch bản và môi trường

Lỗi kiểu “không tìm thấy kịch bản” thường xảy ra khi agent dùng ID tự đoán.

So sánh:

• Giá trị -t trong lệnh agent chạy.
• Giá trị -e trong lệnh agent chạy.
• Lệnh trong tab CI/CD của Apidog.
• Lệnh đã lưu trong AGENTS.md.

AGENTS.md phải là nguồn sự thật cho agent.

Tùy chọn: Thêm máy chủ Apidog MCP để truy cập đặc tả

Apidog CLI giải quyết phần xác minh bằng kiểm thử. Nếu bạn cũng muốn agent đọc đặc tả API trong lúc viết mã, MCP là lớp bổ sung phù hợp.

Tính đến cuối tháng 8 năm 2026, hỗ trợ MCP không được ghi lại trong README hoặc hướng dẫn người dùng cốt lõi của DeepSeek Harness. Tuy nhiên, có plugin cộng đồng hyqhyq3/dsh-mcp-manager, được phát hiện qua chủ đề GitHub dsh-plugin.

Plugin này:

• Thêm trang MCP trong phần Settings.
• Hỗ trợ máy chủ HTTP từ xa và stdio cục bộ.
• Đăng ký công cụ với tên dạng mcp__<name>__*.
• Đọc cấu hình theo dự án từ:

<workspace>/.dsh/dshmm/mcp.json

Qua plugin này, bạn có thể kết nối máy chủ Apidog MCP. Máy chủ MCP giúp agent truy cập đặc tả API thực tế trước khi viết handler hoặc mapping response.

Tuy nhiên, đây là tích hợp plugin cộng đồng chạy cùng một harness đang ở giai đoạn preview. Có thể phát sinh lỗi tương thích khi một trong hai bên cập nhật.

Vì vậy, hãy xem MCP là lớp bổ sung. Đường dẫn chính vẫn nên là Apidog CLI vì nó chỉ cần shell, xác thực và lệnh apidog run.

Lưu ý về bản preview và tính di động của quy trình

DeepSeek Harness thay đổi nhanh. Những phần có khả năng đổi nhiều nhất gồm:

• Danh sách tệp hướng dẫn mà plugin nạp.
• Hành vi sandbox của bash.
• Cấu hình plugin MCP cộng đồng.

Dù vậy, mô hình triển khai vẫn có thể áp dụng cho nhiều harness:

1. Lưu lệnh kiểm thử trong tệp quy tắc của repository.
2. Để agent chạy lệnh sau khi thay đổi API.
3. Dùng mã thoát và báo cáo làm tín hiệu xác minh.
4. Chỉ báo hoàn thành sau khi kiểm thử thành công.

Đây cũng là lý do cách làm tương tự hoạt động với Claude Code và các agent harness khác: agent có thể đọc đầu ra lệnh tốt hơn là tự suy luận rằng API “có lẽ” hoạt động.

Bắt đầu bằng các bước sau:

1. Tải xuống Apidog.
2. Tạo kịch bản kiểm thử API trong Apidog.
3. Sao chép lệnh apidog run ở tab CI/CD.
4. Thêm lệnh đó vào AGENTS.md.
5. Yêu cầu DeepSeek Harness chạy lệnh sau mỗi thay đổi API.

Lần tiếp theo agent sửa mã API, nó có thể tự kiểm tra công việc trước khi báo hoàn thành.

FAQ

DeepSeek Harness có đọc AGENTS.md nguyên bản không?

Có. Plugin @deepseek-ai/dsh-agent-instructions tải AGENTS.md, hoặc CLAUDE.md làm phương án dự phòng, từ thư mục gốc dự án và các thư mục nằm giữa thư mục làm việc của phiên với root Git.

Plugin cũng hỗ trợ:

• AGENTS.local.md
• CLAUDE.local.md
• ~/.dsh/AGENTS.md cho quy tắc toàn cục theo người dùng

Nếu repository đã có AGENTS.md cho agent khác, dsh có thể sử dụng mà không cần thay đổi.

Tôi có cần gói DeepSeek trả phí để dùng Apidog CLI trong dsh không?

Không. Harness là mã nguồn mở theo giấy phép MIT và bạn tự chọn mô hình hoặc nhà cung cấp.

Các nhà cung cấp được liệt kê gồm Anthropic, OpenAI, Bedrock, Vertex và Azure. Gateway tùy chỉnh có thể cấu hình qua settings.yaml, như mô tả trong cách chạy bất kỳ mô hình nào trong DeepSeek Harness.

Apidog CLI là gói npm miễn phí. Bạn cần kịch bản kiểm thử Apidog và xác thực CLI, không cần một mô hình cụ thể.

Tại sao lệnh thứ hai của agent quên thư mục mà lệnh đầu tiên đã cd đến?

Đó là hành vi theo thiết kế. Công cụ bash mặc định của dsh chạy mỗi lệnh trong một shell mới, nên cd không tồn tại giữa các lần gọi.

Cách xử lý:

cd services/api && apidog run -t 123456 -e 789012 -r cli

Hoặc truyền workdir nếu công cụ bash hỗ trợ tham số này.

Dsh có thể chạy kịch bản mà không hỏi phê duyệt mỗi lần không?

Điều đó phụ thuộc vào chính sách quyền hạn đang hoạt động. Giao diện web sẽ yêu cầu phê duyệt cho các thao tác thuộc diện bị kiểm soát bởi chính sách đó.

Hướng dẫn người dùng không liệt kê chi tiết từng cấp chính sách, vì vậy hãy kiểm tra Settings trong bản cài đặt của bạn. Khi dsh yêu cầu phê duyệt cho apidog run trên môi trường staging, hãy kiểm tra lệnh và phê duyệt theo quy trình bảo mật của đội.