Cách sửa lỗi cài đặt và phiên bản DeepSeek Harness

Bản chất thực sự của việc cài đặt DeepSeek Harness

Việc cài đặt DeepSeek Harness chỉ gói gọn trong một lệnh: npx @deepseek-ai/dsh web. Không có trình cài đặt nào cả, cũng không có service nào cần cấu hình. Hầu hết các vấn đề người dùng gặp phải không nằm ở khâu cài đặt. Đó là vấn đề phân giải phiên bản: bản build nào của @deepseek-ai/dsh mà npx quyết định chạy hôm nay, và liệu phiên bản Node.js của bạn có chạy được nó hay không.

Hai sự thật dưới đây quyết định mọi thứ. Thứ nhất, mọi phiên bản @deepseek-ai/dsh được xuất bản lên npm cho đến nay đều là bản release candidate, và tag latest đang trỏ vào một trong số đó. Tính đến ngày 18 tháng 8 năm 2026, đó là phiên bản 0.1.0-rc.7, được xuất bản vào ngày 17 tháng 8 năm 2026. Thứ hai, README của dự án cho biết harness này đang ở giai đoạn developer preview, đang lặp lại nhanh chóng và sẽ có những thay đổi gây mất tương thích. Một flag hoạt động tuần trước có thể biến mất trong tuần này. Hãy ghim (pin) phiên bản trước khi bạn xây dựng bất cứ thứ gì trên đó.

Trước tiên là một số thuật ngữ. dsh là công cụ dòng lệnh của DeepSeek Harness. Node.js là JavaScript runtime mà nó yêu cầu. npx là trình chạy package đi kèm với npm (node package manager), nó sẽ tải package theo yêu cầu thay vì cài đặt vĩnh viễn.

dsh cần Node.js phiên bản nào?

File root package.json của repository khai báo "engines": {"node": "^22.19.0 || >=24.0.0"}, được đọc vào ngày 18 tháng 8 năm 2026 tại phiên bản 0.1.0-rc.7. Do đó, bạn cần Node 22.19.0 hoặc mới hơn trong nhánh 22, hoặc Node 24 trở lên. Node 20 không được hỗ trợ.

Hãy kiểm tra phiên bản bạn đang có trước khi thực hiện bất cứ thao tác nào.

node -v
npm -v

Đây là phần gây ngạc nhiên cho nhiều người. Gói @deepseek-ai/dsh được publish không chứa trường engines riêng. Chỉ có file root của monorepo mới khai báo trường này, và file root đó không bao giờ được publish lên npm. Vì vậy, npm không có gì để kiểm tra, nó không in ra cảnh báo EBADENGINE nào và cũng không từ chối cài đặt. Trên Node 20, quá trình cài đặt trông có vẻ thành công, nhưng lỗi sẽ xuất hiện sau đó, khi code được load đụng tới cú pháp hoặc API mà runtime của bạn không hỗ trợ. Không có một chuỗi lỗi ổn định nào để tìm kiếm, vì dòng code nào lỗi trước phụ thuộc vào việc module nào được load trước. Hãy đọc node -v thay vì cố gắng đọc thông báo crash.

Nếu phiên bản Node của bạn quá cũ, nvm (node version manager) là cách sửa ít xâm lấn nhất trên VPS, vì nó cài đặt trong thư mục home của bạn và không làm ảnh hưởng đến Node của hệ thống.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
exec $SHELL -l
nvm install 24
nvm use 24
node -v

node -v bây giờ sẽ in ra một phiên bản bắt đầu bằng v24.. Nếu shell vẫn báo phiên bản cũ, nghĩa là hàm shell của nvm chưa được load, hãy mở một login shell mới và thử lại. Node 24.19.0 là bản phát hành LTS (long term support) đang hoạt động tính đến tháng 8 năm 2026, và đây là mục tiêu tốt hơn vì lý do thứ hai được đề cập bên dưới.

Tại sao npx chạy một phiên bản khác nhau mỗi ngày?

npx @deepseek-ai/dsh web không chỉ định phiên bản, nên npx yêu cầu registry cung cấp bất cứ thứ gì mà tag latest đang trỏ tới. Tag đó thay đổi liên tục. Khi DeepSeek phát hành 0.1.0-rc.8, lệnh nằm trong ghi chú của bạn bắt đầu chạy mã nguồn khác, mà không có bất kỳ thông báo hay changelog nào hiển thị trước mặt bạn.

Bạn có thể kiểm tra mọi thành phần đang thay đổi từ CLI.

npm view @deepseek-ai/dsh dist-tags
npm view @deepseek-ai/dsh versions --json
npm view @deepseek-ai/dsh time --json

dist-tags hiển thị nơi latest đang trỏ tới ngay lúc này. Vào ngày 18 tháng 8 năm 2026, cả latest và next đều trỏ tới 0.1.0-rc.7, vì vậy không có kênh stable riêng biệt nào để chuyển sang. Danh sách versions thú vị hơn vì nó có các khoảng trống: 0.0.1-rc.1, 0.0.1-rc.2, 0.0.1-rc.5, 0.1.0-rc.2, 0.1.0-rc.3, 0.1.0-rc.6, 0.1.0-rc.7. Các con số bị thiếu trong chuỗi đó vì một số bản release candidate chưa bao giờ được publish. Việc đoán -rc.N tiếp theo trong script deploy sẽ thất bại, vì vậy hãy đọc danh sách thay vì đếm tăng dần.

Tại sao npx vẫn chạy phiên bản cũ?

Đây là vấn đề ngược lại, và cả hai trường hợp đều đúng, tùy thuộc vào phiên bản npm bạn đang chạy.

npx lưu trữ thư mục package riêng, tách biệt với tarball cache, trong một thư mục có tên _npx nằm bên trong npm cache. Hãy in đường dẫn đó ra và kiểm tra.

npm config get cache
ls "$(npm config get cache)/_npx"

Trong nhiều năm, npx tái sử dụng bất cứ thứ gì nó tìm thấy ở đó cho một tên package đơn thuần và không bao giờ truy vấn lại registry. npm 11.2.0 đã thay đổi điều đó. Khi spec là một tên đơn thuần hoặc một dải phiên bản, npx giờ đây sẽ lấy manifest và chỉ tái sử dụng bản sao trong cache khi tarball đã phân giải khớp với những gì registry vừa trả về.

Hành vi bạn nhận được được quyết định bởi bản phát hành Node của bạn, vì Node đi kèm với một phiên bản npm cụ thể:

• Node 20.20.2 đi kèm npm 10.8.2.
• Node 22.19.0 đi kèm npm 10.9.3.
• Node 22.23.2, bản phát hành 22 mới nhất, đi kèm npm 10.9.8.
• Node 24.19.0 đi kèm npm 11.17.0.

Vì vậy, toàn bộ dòng Node 22, vốn được harness hỗ trợ chính thức, sử dụng phiên bản npm cũ hơn 11.2.0. Trên Node 22, một lệnh npx @deepseek-ai/dsh web đơn thuần sẽ tiếp tục chạy bản release candidate mà nó đã lưu trong cache từ nhiều tuần trước. Cùng một lệnh đó trên Node 24 sẽ phân giải lại trong mỗi lần chạy. Một lệnh, hai hành vi, và không có cảnh báo nào cho bạn. Hãy hỏi công cụ xem nó là phiên bản nào:

npx @deepseek-ai/dsh --version

Xóa cache của npx

Trên npm 11.2.0 trở lên, có các subcommand chuyên dụng.

npm cache npx ls
npm cache npx rm --force

Nếu không có --force, npm sẽ từ chối xóa mọi thứ và in ra Please use --force to remove entire npx cache. Hãy sử dụng npm cache npx ls trước khi bạn muốn xóa một mục theo key thay vì xóa tất cả.

Trên npm 10, các subcommand này không tồn tại, vì vậy hãy tự xóa thư mục đó.

rm -rf "$(npm config get cache)/_npx"

npm cache clean --force không giúp ích gì trong trường hợp này. Nó xóa _cacache, nơi lưu trữ tarball, và để nguyên _npx. Sự tách biệt đó chính là lý do tại sao npm sau này đã thêm các subcommand npm cache npx. Việc xóa _npx cũng không gây mất mát vĩnh viễn: nó chỉ chứa các package đã tải xuống, trong khi trạng thái harness của bạn nằm dưới $DSH_HOME/profiles/<name> và không bị ảnh hưởng.

Làm thế nào để ghim một bản release candidate cụ thể?

Hãy chỉ định đầy đủ chuỗi phiên bản, bao gồm cả phần -rc.N.

npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

--yes rất quan trọng trong script, vì nếu không, npx sẽ hiển thị một prompt trước khi cài đặt gói chưa từng thấy và chờ đợi câu trả lời không bao giờ đến.

Một phiên bản chính xác cũng là con đường nhanh nhất. npx sử dụng chuỗi đặc tả bạn nhập làm khóa cho thư mục cache, và với một phiên bản chính xác, nó sẽ so sánh chuỗi đó với ID gói đã cài đặt sẵn ở đó rồi chạy ngay mà không cần thực hiện bất kỳ truy vấn nào tới registry. Trên npm 11.2.0 trở lên, việc chỉ dùng tên gói sẽ khiến bạn mất một lần fetch manifest mỗi khi khởi chạy.

Cài đặt global cũng ghim theo cách tương tự và cung cấp cho bạn một lệnh ngắn gọn.

npm install -g @deepseek-ai/dsh@0.1.0-rc.7
dsh --version

Không tìm thấy phiên bản khớp cho @deepseek-ai/dsh@^0.1.0

Dải phiên bản sử dụng dấu caret hoặc tilde sẽ thất bại với gói này. npm install -g @deepseek-ai/dsh@^0.1.0 phản hồi với mã lỗi ETARGET và dòng No matching version found for @deepseek-ai/dsh@^0.1.0. Registry vẫn hoạt động bình thường. Đây là quy tắc semver: một dải phiên bản sẽ không khớp với phiên bản prerelease trừ khi chính dải đó chỉ định một prerelease. Mọi bản build đã xuất bản của gói này đều là -rc.N, vốn là một prerelease, vì vậy ^0.1.0 không khớp với bất kỳ thứ gì. Hãy viết phiên bản chính xác.

Quy tắc đó có một tác dụng phụ hữu ích. Vì các dải phiên bản không thể tự động chuyển sang một release candidate mới, nên không tồn tại trạng thái "ghim nửa vời" cần phải cân nhắc. Bạn chỉ có thể chọn giữa việc dùng phiên bản chính xác hoặc dùng một tag thay đổi liên tục.

Tôi nên dùng npx hay cài đặt dsh toàn cục?

Hãy dùng npx để dùng thử, vì nó không để lại gì ngoài một thư mục cache mà bạn đã biết cách xóa. Hãy dùng cài đặt toàn cục với phiên bản cố định (pinned) cho bất kỳ thứ gì cần hoạt động sau khi reboot, ví dụ như một coding agent bạn chạy trên VPS.

Hai cách này có thể gây xung đột trên máy chủ nếu bạn dùng cả hai, vì vậy hãy kiểm tra kỹ.

which dsh
dsh --version
npx @deepseek-ai/dsh --version

which dsh không tìm thấy lệnh ngay sau khi cài đặt toàn cục thành công gần như luôn có nghĩa là thư mục bin toàn cục của npm bị thiếu trong PATH của bạn. Chạy npm prefix -g để in ra thư mục root, các file binary sẽ nằm trong thư mục bin bên dưới nó.

Một lưu ý về bảo mật. npx tải và thực thi code từ registry mỗi khi nó phân giải một thứ gì đó mới, đây là một rủi ro thực tế trên máy chủ chứ không chỉ là lý thuyết. Cố định phiên bản (pinning) là một phần của giải pháp. Phần còn lại nằm ở cách các cuộc tấn công chuỗi cung ứng npm xâm nhập vào máy chủ.

Ý nghĩa của developer preview đối với tính tái lập

0.1.0-rc.6 được phát hành vào ngày 13 tháng 8 năm 2026 và 0.1.0-rc.7 vào ngày 17 tháng 8 năm 2026. Cách nhau bốn ngày. Với tốc độ này, các hướng dẫn viết từ một tháng trước có thể mô tả một CLI không còn tồn tại, bao gồm cả trang này. Hãy ghi ngày cho mọi tuyên bố về phiên bản mà bạn viết ra, kể cả ghi chú cá nhân.

Hai thói quen giúp bạn sống sót với bản preview. Hãy ghim (pin) phiên bản chính xác trong mọi lệnh và mọi script, để việc xây dựng lại server tạo ra cùng một môi trường. Sau đó, hãy đọc output trợ giúp từ bản build đã ghim thay vì từ bất kỳ hướng dẫn nào.

npx @deepseek-ai/dsh@0.1.0-rc.7 --help
npx @deepseek-ai/dsh@0.1.0-rc.7 web --dump-config

Một nửa còn lại của tính tái lập là profile. dsh --profile <name> khởi động profile được lưu tại $DSH_HOME/profiles/<name>, còn các profile web và headless tự tạo ra từ các template có sẵn khi sử dụng lần đầu. Thư mục đó cũng là nơi harness đọc API key, model và các thiết lập endpoint của nó, vì vậy một phiên bản đã ghim và một cấu hình hoạt động là hai thứ riêng biệt cần phải làm đúng. Các bundle có sẵn trong hộp (in-box) được phân giải từ bản cài đặt dsh đang chạy, nghĩa là việc thay đổi phiên bản đã ghim cũng làm thay đổi các bundle đó. Các plugin ngoài (out-of-tree) hoạt động khác biệt. Chúng nằm trong thư mục profile, và dsh plugin --profile <name> add <package> chuyển tiếp các đối số của nó tới pnpm để cài đặt chúng. Vì vậy, pnpm phải có trong PATH của bạn, và dsh sẽ thông báo rõ ràng khi không tìm thấy nó. File package.json của chính profile là thứ ghim các plugin đó, vì vậy một bản ghim hoàn chỉnh bao gồm hai file, không phải một.

Sự phân tách này sẽ trở nên quen thuộc nếu bạn đã từng quản lý các công cụ Python trong môi trường cô lập trên server: công cụ và những thứ bạn thêm vào nó được ghim ở các vị trí riêng biệt. Khi harness đã khởi động, câu hỏi tiếp theo thường là về networking thay vì phiên bản, đó là lúc truy cập dsh Web UI trên một VPS từ xa và hướng dẫn chi tiết hơn trong cài đặt DeepSeek Harness trên VPS bắt đầu.

Các lỗi đối số bạn sẽ thực sự gặp phải

Những lỗi này xuất phát từ trình phân tích cú pháp của chính CLI, vì vậy chúng ổn định qua các phiên bản release candidate và mỗi lỗi đều chỉ rõ vấn đề chính xác.

error: --profile <name> is required

Bạn đã chạy npx @deepseek-ai/dsh mà không có subcommand và không có profile. Lệnh cơ bản này khởi động một profile, vì vậy nó cần một tên. dsh web là subcommand không yêu cầu --profile, vì nó tự khởi động profile web đi kèm cho bạn.

error: --patch needs a path

--patch được truyền vào mà không có gì theo sau. Flag này có thể lặp lại và mỗi lần xuất hiện cần một đường dẫn file.

error: --dump-config and --dump-default-config are mutually exclusive

Hãy chọn một. --dump-default-config in ra các lớp bundle đi kèm và không chấp nhận --patch. --dump-config in ra cấu hình đã được tổng hợp cho một profile. Cả hai đều in thông tin và thoát mà không khởi động harness, đây là cách an toàn để xem phiên bản release candidate mới đã thay đổi những gì.

error: plugin needs pnpm arguments to forward (e.g. add <package>)

dsh plugin --profile <name> không nhận được gì để chuyển tiếp. Subcommand này khởi tạo profile khi nó bị thiếu, sau đó chuyển phần còn lại của dòng lệnh cho pnpm, vì vậy nó cần các đối số như add @scope/dsh-plugin-example.

FAQ

DeepSeek Harness cần Node.js phiên bản nào?

Repository khai báo ^22.19.0 || >=24.0.0 trong package.json tại thư mục gốc, cập nhật ngày 18 tháng 8 năm 2026 ở phiên bản 0.1.0-rc.7. Do đó, bạn cần Node 22.19.0 trở lên thuộc nhánh 22, hoặc Node 24 trở lên. Node 20 sẽ không hoạt động. Gói npm được xuất bản không có trường engines riêng, nên npm không cảnh báo và không chặn quá trình cài đặt, lỗi sẽ chỉ xuất hiện khi runtime. Hãy kiểm tra node -v trước. Dù sao thì Node 24 vẫn là lựa chọn tốt hơn vì nó đi kèm npm 11, giúp khắc phục vấn đề tái sử dụng phiên bản của npx.

Làm thế nào để ép npx sử dụng bản dsh mới nhất thay vì bản trong cache?

Trên npm 11.2.0 trở lên, npx @deepseek-ai/dsh đã tự động kiểm tra lại registry cho tên gói mỗi khi chạy. Trên npm 10, phiên bản đi kèm với mọi bản phát hành Node 22, nó không làm vậy. Hãy xóa cache của npx bằng npm cache npx rm --force trên npm 11, hoặc xóa thư mục bằng rm -rf "$(npm config get cache)/_npx" trên npm 10. Sau đó xác nhận lại bằng npx @deepseek-ai/dsh --version. Lưu ý rằng npm cache clean --force xóa một thư mục khác và sẽ không giải quyết được vấn đề này.

Tại sao cài đặt @deepseek-ai/dsh@^0.1.0 lại thất bại?

npm trả về mã lỗi ETARGET với dòng No matching version found for @deepseek-ai/dsh@^0.1.0.. Mọi bản build được xuất bản đều là bản prerelease như 0.1.0-rc.7, và dải semver không khớp với các phiên bản prerelease trừ khi chính dải đó chỉ định cụ thể. Hãy cài đặt chính xác chuỗi phiên bản, bao gồm cả hậu tố -rc.N. Chạy npm view @deepseek-ai/dsh versions --json để xem những phiên bản nào hiện có, vì chuỗi này có những khoảng trống nơi các bản release candidate chưa từng được xuất bản.

Tôi nên cài đặt dsh toàn cục hay chạy qua npx?

npx phù hợp để dùng thử lần đầu vì không có gì tồn tại lâu dài ngoại trừ thư mục cache. Một bản cài đặt toàn cục được ghim phiên bản như npm install -g @deepseek-ai/dsh@0.1.0-rc.7 phù hợp cho bất kỳ công việc nào cần sự ổn định, vì phiên bản chỉ thay đổi khi bạn chủ động thay đổi. Nếu lệnh dsh không tìm thấy sau khi cài đặt toàn cục, nghĩa là thư mục bin toàn cục của npm đang thiếu trong PATH của bạn, và npm prefix -g sẽ in ra thư mục gốc mà nó đang nằm trong đó.

DeepSeek Harness đã đủ ổn định để phát triển ứng dụng chưa?

Chưa, theo mô tả của chính dự án. README nêu rõ dự án đang trong giai đoạn developer preview, đang thay đổi nhanh chóng và sẽ có những thay đổi phá vỡ tính tương thích. Các bản release candidate 0.1.0-rc.6 và 0.1.0-rc.7 được xuất bản cách nhau bốn ngày vào tháng 8 năm 2026. Hãy ghim một phiên bản cụ thể và đọc --help từ bản build đã ghim đó thay vì từ bất kỳ hướng dẫn nào. Hãy ghi chú ngày tháng cho các ghi chép của bạn để biết chúng đã cũ đến mức nào.