Cách cài đặt DeepSeek Harness (dsh): Lệnh một dòng npx, Biên dịch từ mã nguồn, Headless và Plugin

To install Deep​Seek Harness (dsh), the open-source agent runtime Deep​Seek shipped on August 13, 2026, run npx @deepseek-ai/dsh web on a machine with Node.js 22.19 or newer. That one command downloads the 0.1.0-rc.6 preview, starts a local web UI at http://127.0.0.1:3080, and walks you through adding a model API key and a workspace on first launch. Two things to know before you start: dsh is not a model — it's the harness layer that connects a model to tools, files, and a terminal — and it's a developer preview, so expect breaking changes between releases. This guide covers both official install methods, headless mode, plugins, MCP, and the honest rough edges.

Deep​Seek Harness là gì — và điều nó không phải

Công thức nội bộ của Deep​Seek, được xác nhận bởi nhà nghiên cứu cấp cao Chen Deli, là Model + Harness = Agent. Mô hình là bộ não; harness là mọi thứ biến nó thành thứ có thể hoàn thành công việc: quản lý ngữ cảnh và bộ nhớ, gọi công cụ, lập kế hoạch tác vụ, đọc và ghi tệp, thực thi terminal, phản hồi lỗi, và quyết định khi nào tác vụ hoàn thành. Deep​Seek Harness là lớp đó, được phát hành mã nguồn mở theo giấy phép MIT vào ngày 13 tháng 8 năm 2026 — cùng ngày bản build DeepSeek V4 Pro 0813 xuất hiện trên Deep​Seek API.

Hai sự thật định nghĩa trải nghiệm cài đặt. Thứ nhất, kiến trúc là "mọi thứ đều là plugin," được xây dựng trên Cordis, một bộ chứa plugin TypeScript — vì vậy những gì bạn cài đặt là một lõi nhỏ cộng với một tập hợp các plugin cung cấp bộ điều hợp mô hình, công cụ, phiên và giao diện người dùng. Thứ hai, phiên bản trên npm hiện nay là 0.1.0-rc.6, một bản phát hành ứng viên mà chính dự án đánh dấu là bản xem trước dành cho nhà phát triển: README cảnh báo, bằng chữ in hoa, rằng sắp có những thay đổi phá vỡ khả năng tương thích. Mức độ phổ biến là có thật — 50.000 sao GitHub trong 12 giờ đầu tiên, 100.000 trong khoảng 42 giờ, và vượt 120.000 vào ngày 16 tháng 8 theo báo giới công nghệ Trung Quốc — nhưng số sao đo lường sự quan tâm, không phải sự ổn định. Hãy lên kế hoạch cài đặt như bạn lên kế hoạch cho một bản xem trước: nhanh để thử, rẻ để vứt bỏ.

Trước khi bắt đầu: các yêu cầu hệ thống thực tế

Yêu cầu cứng duy nhất là Node.js. Dự án hỗ trợ phạm vi engine ^22.19.0 || >=24.0.0 — nói đơn giản, Node 22.19 trở lên, hoặc bất kỳ Node 24.x nào. Kiểm tra phiên bản của bạn bằng node --version. Nếu bạn đang dùng Node cũ hơn, quá trình cài đặt npx sẽ thất bại hoặc hoạt động sai, chứ không tự giảm cấp an toàn.

Mọi thứ khác đều nhẹ nhàng hơn những gì đám đông ưu tiên mô hình giả định:

• Một khóa API của mô hình. dsh chạy một mô hình thực; nó cần khóa cho API của Deep​Seek hoặc bất kỳ nhà cung cấp tương thích Open​AI nào bạn cấu hình. Bạn có thể thêm một khóa trong giao diện web sau lần khởi động đầu tiên.

• pnpm — chỉ dành cho bản build từ mã nguồn. Cài đặt một lần bằng npm install -g pnpm.

• ~1 GB dung lượng đĩa trống cho gói npm, không gian làm việc và nhật ký phiên, cộng với bất cứ thứ gì mô hình cục bộ cần (bản thân dsh không chạy trọng số).

• Hệ điều hành: cách dùng npm hoạt động trên Windows, macOS và Linux. Python SDK có phạm vi hẹp hơn (Linux x64/arm64, macOS 14+ arm64 — không có Windows gốc), được trình bày bên dưới.

Bạn không cần GPU. Harness chỉ điều phối; mô hình chạy từ xa thông qua API.

Phương pháp 1 — lệnh npx một dòng (được khuyến nghị cho hầu hết mọi người)

Hướng dẫn khởi động nhanh chính thức chỉ là một lệnh, và thực sự chỉ là một lệnh:

npx @deepseek-ai/dsh web

npx fetches the @deepseek-ai/dsh package (current version 0.1.0-rc.6), installs it into npm's cache, and starts the Web UI profile. Watch the output for the line that tells you it's listening — by default that is http://127.0.0.1:3080. Open it in your browser. Note the 127.0.0.1 loopback address: the UI binds to localhost only, which is the right default for a tool that can read and write files in your workspace — it also means you won't casually expose it on your network.

Lần khởi chạy đầu tiên có đúng hai bước thiết lập:

• Thêm khóa mô hình.Cài đặt → Mô hình → nhập khóa API của bạn. Nó được lưu trong $DSH_HOME/.credentials.yaml và không hiển thị dưới dạng văn bản thuần sau đó. Trên bản cài đặt tiêu chuẩn, DSH_HOME mặc định là ~/.dsh.

• Chọn một không gian làm việc.Thêm thư mục dự án mà dsh được phép làm việc. Đầu vào vẫn bị khóa cho đến khi hoàn tất cả hai bước.

Sau đó, hãy gửi một tác vụ đầu tiên — một bài kiểm tra khói tốt là "Tóm tắt kho lưu trữ này và xác định các gói chính của nó." Nếu bản tóm tắt được trả về và các lệnh gọi công cụ xuất hiện trong dấu vết chạy, thì cài đặt của bạn đã hoạt động.

Phương pháp 2 — biên dịch từ mã nguồn

Bạn muốn chạy từ repository? Đường dẫn chính thức là:

git clone https://github.com/deepseek-ai/deepseek-harness.git

cd deepseek-harness

pnpm install

pnpm run build

pnpm dsh web

Bạn cần pnpm cho việc này (các nhà đóng góp cố định pnpm 11.7.0). Chọn bản build từ mã nguồn nếu bạn muốn chạy bản mới nhất trên nhánh main thay vì bản phát hành thử nghiệm đã công bố, nếu bạn định đọc hoặc sửa bộ khung (harness), hoặc nếu bạn muốn xây dựng preset tùy chỉnh từ thư mục apps/cli/config/agent-presets/ trong repo. Còn với mọi người khác, cách dùng npx là cùng một phần mềm nhưng ít nghi thức hơn — bản build từ mã nguồn không mở khóa tính năng nào mà gói npm thiếu.

Ba chế độ: web, headless và tui.

dsh có ba cấu hình chạy, và bạn dùng cái nào tùy thuộc vào nơi công việc diễn ra:

• web (mặc định) — giao diện trình duyệt đầy đủ trên cổng 3080. Đây là thứ mà npx @deepseek-ai/dsh web khởi động, và đây là cấu hình mà hầu hết mọi người sẽ cài đặt đầu tiên.

• headless — một tác vụ, rồi thoát. dsh --profile headless "run the test suite and report failures" bắt đầu một phiên, chạy tác vụ, ghi lại kết quả và kết thúc. Headless runtime được thiết kế rõ ràng là một quy trình một tác vụ: bạn không thể chèn thêm các yêu cầu tiếp theo giữa lúc chạy, và các chỉnh sửa là một lần chạy mới trên cùng một workspace. Đây là profile để tích hợp vào các script và CI.

• tui — giao diện terminal cho các phiên điều khiển bằng bàn phím: dsh --profile tui.

Cả ba đều dùng chung cấu hình (~/.dsh/profiles/<name>/) và cùng một hệ thống plugin, vì vậy việc chuyển một tác vụ từ giao diện web sang headless chỉ là thay lệnh, chứ không phải cài đặt lại.

Thêm plugin

Quản lý plugin là một lệnh CLI hạng nhất, không phải là việc chỉnh sửa tại chỗ:

npx @deepseek-ai/dsh plugin --profile web add <source>

Nguồn có thể là tên gói npm, một kho GitHub (github:user/repo), một tệp tar, hoặc một thư mục cục bộ. Bản cài đặt đầu tiên hữu ích nhất là chợ plugin chính thức, nơi biến việc khám phá plugin thành một giao diện người dùng:

npx @deepseek-ai/dsh plugin --profile web add dshmarket

Sau đó, khởi động lại dịch vụ web và mở mục Settings → Plugin Market để duyệt và cài đặt một chạm từ danh mục. Có hai quy tắc thường khiến người dùng vấp phải: các gói plugin được mount khi profile khởi động, vì vậy một plugin vừa được thêm vào cần khởi động lại dsh web; còn một lệnh npm install thông thường không đăng ký plugin vào profile — bạn phải dùng dsh plugin. Hệ sinh thái còn non trẻ nhưng không trống rỗng: danh sách awesome-dsh-plugin do cộng đồng duy trì đã liệt kê hàng trăm plugin thuộc nhiều hạng mục như UI, kỹ năng, công cụ, nhà cung cấp và thông báo.

MCP, bốn cài đặt trước, và phát lại quỹ đạo

Ba tính năng quan trọng khi bạn đã vượt qua bước cài đặt cơ bản:

MCP. dsh giao tiếp bằng Model Context Protocol thông qua một @deepseek-ai/dsh-mcp-client plugin tích hợp sẵn. Hiện tại, việc này được cấu hình trong các tệp, không phải trong giao diện người dùng: bạn chỉnh sửa ~/.dsh/profiles/web/cordis.patch.yml (hoặc một bản vá cục bộ của dự án) và khai báo phương thức truyền tải của từng máy chủ — stdio cho các lệnh cục bộ như npx @playwright/mcp@latest, streamable-http cho các URL từ xa. Nó hoạt động, nhưng đây là phần kém trau chuốt nhất trong bản xem trước; hãy chuẩn bị cho tình trạng thỉnh thoảng không ổn định và không có GUI để bật/tắt máy chủ.

Các bộ cài đặt sẵn. dsh tải một trong bốn bộ cài đặt sẵn cho tác nhân trong mỗi phiên, và mỗi bộ là một sự đánh đổi khác nhau:

• Standard — bộ công cụ đầy đủ: chỉnh sửa tệp, shell, truy xuất tệp và web, kỹ năng, lập kế hoạch, subagents, quy trình làm việc. Lựa chọn mặc định hàng ngày.

• PTC (Gọi Công Cụ Theo Chương Trình) — Bản Standard cộng với SDK Code Mode cho phép mô hình viết các chương trình TypeScript để điều phối các cuộc gọi công cụ qua nhiều vòng. Mạnh mẽ hơn, nhiều tác dụng phụ hơn.

• Tối giản — chỉ bash và một trình soạn thảo file, không gì khác. Được xây dựng để benchmark mô hình và tái tạo tối thiểu; chế độ mà tài liệu API DeepSeek V4 Flash đã đề cập khi họ công bố điểm số agent của chính họ chạy trên "Deep​Seek Harness minimal mode."

• Sáng tạo — một sân chơi runtime: kiểm tra và tải các plugin Cordis vào bộ nhớ, thử nghiệm và củng cố một tổ hợp hoạt động thành một preset mới.

Phát lại quỹ đạo. Mỗi lần chạy ghi một nhật ký phiên chỉ nối thêm — lời nhắc hệ thống, lý luận, các lời gọi công cụ và kết quả của chúng, lập lịch cho tác tử con. Chế độ xem Quỹ đạo cho phép bạn kiểm tra theo nguồn, tiếp tục, rẽ nhánh, tìm kiếm và phát lại một lần chạy. Đó chính là trình gỡ lỗi cho công việc tác tử: khi một tác vụ thất bại, bạn không chạy lại và hy vọng; bạn phát lại quỹ đạo đã thất bại, rẽ nhánh tại bước lỗi và kiểm tra bản sửa mà không vứt bỏ bản gốc.

Tùy chọn SDK Python

Nếu bạn muốn vận hành harness bằng Python thay vì bằng trình duyệt, thì có một SDK chính thức: pip install deepseek-harness-sdk. SDK này đi kèm với runtime dsh (gói wheel pip mang theo runtime Node, nên không cần cài Node riêng), và cách dùng là một context manager: hãy tạo một Deep​SeekHarness instance, rồi gọi run("task"). Nó kế thừa các biến môi trường chuẩn như DEEPSEEK_API_KEY và DEEPSEEK_BASE_URL, nên việc đổi nhà cung cấp chỉ là một thay đổi cấu hình. Điểm hạn chế: nó yêu cầu Python 3.10+ và chỉ hỗ trợ Linux x64/arm64 và macOS 14+ arm64 — không có wheel Windows gốc, đây là một thiếu sót thực sự nếu Windows là hệ điều hành chính của bạn. Trên Windows, hãy dùng theo hướng npm.

Trỏ dsh vào các mô hình bạn trả phí

dsh cần một API key cho mô hình, và nó được thiết kế có chủ đích là không phụ thuộc vào nhà cung cấp: Settings → Models chấp nhận một nhà cung cấp tùy chỉnh với URL gốc tương thích Open​AI (trong settings.yaml, đó là api: openai-completions, baseURL, và một models list). Mặc định là API riêng của Deep​Seek; một nhà cung cấp tùy chỉnh là nơi mà một cổng định tuyến trở nên hữu ích.

OrcaRouter is an Open​AI-compatible endpoint that passes Deep​Seek's list price through with zero markup — https://api.orcarouter.ai/v1. That gives you DeepSeek V4 Flash (deepseek/deepseek-v4-flash-0731, about $0.15 per million input tokens and $0.29 per million output) and DeepSeek V4 Pro (about $0.44/$0.88), both at provider list price with no token markup, plus automatic failover if a provider wobbles. For dsh, the practical win is that you can run the cheap V4 Flash for the bulk of everyday agent tasks and switch the same harness to V4 Pro for the hard passes — one key, one base URL, and the swap is a model name in the settings, not a reinstall.

Để nói rõ về ranh giới: OrcaRouter lưu trữ các mô hình lệnh gọi dsh; nó không lưu trữ chính dsh. dsh là một môi trường chạy tác tử cục bộ, và bạn chạy nó trên máy của chính bạn.

Hướng dẫn này sai ở đâu đối với bạn — những vấn đề thẳng thắn về bản xem trước

Một hướng dẫn cài đặt chỉ cho bạn biết phải gõ gì thì mới làm được một nửa công việc. Đây là những gì bản xem trước hiện đang sai, để bạn không phải phát hiện ra lúc 2 giờ sáng:

• Thay đổi phá vỡ là một lời hứa, không phải lời cảnh báo. Bạn đang ở phiên bản 0.1.0-rc.6. Các khóa cấu hình, API plugin và định dạng preset đều có thể thay đổi mà không báo trước. Hãy coi ~/.dsh như trạng thái có thể vứt bỏ — chi phí cho một bản cập nhật lỗi chỉ là cài lại, và điều đó chấp nhận được ở giai đoạn này chỉ vì việc cài đặt chỉ là một lệnh.

• Bạn không cần dsh để sử dụng các mô hình Deep​Seek như một agent. Nếu mục tiêu duy nhất của bạn hôm nay là DeepSeek V4 Flash hoặc DeepSeek V4 Pro bên trong một agent, endpoint tương thích Anthro​pic của Deep​Seek đã hoạt động trong Claude Code và các công cụ agent khác mà không cần phần mềm mới nào. dsh là một tùy chọn chính thống, không phải điều kiện tiên quyết. Hãy bỏ qua bước cài đặt này cho đến khi bạn thực sự muốn sử dụng bộ khung gốc.

• MCP được cấu hình qua tệp tin và thỉnh thoảng không ổn định. Không có GUI, không có nút bật/tắt cho từng máy chủ, và các báo cáo thực tế mô tả những lỗi chập chờn. Hãy dành thời gian gỡ lỗi YAML nếu quy trình làm việc của bạn phụ thuộc vào các máy chủ MCP.

• Tin cậy plugin là một quyết định bảo mật. Plugin bên thứ ba chạy bên trong tiến trình lõi của harness và không có xác minh chữ ký hay nguồn gốc khi cài đặt. Chỉ cài đặt những plugin bạn đã đọc hoặc đến từ nguồn bạn tin cậy, và kiểm thử chúng trong một không gian làm việc dùng một lần trước khi sử dụng cho công việc thực tế. Hồ sơ sandbox danger-full-access có thể sửa đổi bất kỳ tệp tin hiển thị nào — chỉ dùng cho các bản checkout tạm thời.

• Bản xem trước có các lỗi đã biết. Vòng lặp bash bị treo là một chế độ lỗi đã được ghi nhận (ngắt và thử lại), và hành vi liên quan đến các phiên chạy lâu vẫn đang được ổn định.

• Các bản dựng desktop không chính thức là một cái bẫy. Một số trình bao bọc cộng đồng đóng gói dsh thành ứng dụng desktop cài đặt bằng một cú nhấp chuột với Node runtime đi kèm. Chúng hoạt động được, nhưng không được ký số và không được Deep​Seek bảo trì; nếu bạn dùng một trong số đó, bạn đang tin tưởng một bên thứ ba với một công cụ có thể nắm giữ quyền hạn trên hệ thống tệp của bạn.

• Nếu bạn cần sự ổn định cho production, hãy chờ bản phát hành không phải rc. Bộ harness này mạnh mẽ nhưng còn non trẻ. Đối với một hệ thống agent production, một bộ harness trưởng thành, đã qua thử thách — hoặc phương án endpoint tương thích Anthro​pic — là lựa chọn hợp lý cho đến khi dsh đạt được tag ổn định.

Kết luận

Việc cài đặt Deep​Seek Harness thực sự chỉ là một lệnh duy nhất trên bất kỳ máy nào có Node 22.19+: npx @deepseek-ai/dsh web, sau đó thêm khóa mô hình và một không gian làm việc, gửi một tác vụ thử nghiệm. Chỉ chọn bản dựng nguồn nếu bạn muốn sửa đổi hoặc theo dõi main; dùng bản headless cho các script; thêm chợ plugin ngay từ đầu; và coi MCP như một thứ đang trong quá trình hoàn thiện. Lời cảnh báo trung thực cũng chính là điều mà dự án nêu trong README của chính nó: đây là bản xem trước 0.1.0-rc và nó sẽ làm hỏng vài thứ trên con đường tiến tới bản ổn định. Đó là sự đánh đổi hợp lý nếu bạn muốn thấy Deep​Seek đang đưa tầng tác tử (agent layer) về đâu — và các mô hình mà nó chạy, DeepSeek V4 Flash và DeepSeek V4 Pro, đều có sẵn ngay hôm nay với giá niêm yết qua OrcaRouter, sẵn sàng cung cấp sức mạnh cho bộ khung sau khi cài đặt.