Đóng gói DeepSeek Harness thành trình cài đặt Windows một tệp không cần Node.js

Giới thiệu dự án

DeepSeek Harness Easy-Setup là một dự án đóng gói dành cho Windows. Dự án tích hợp chương trình dòng lệnh @deepseek-ai/dsh, runtime Node.js portable, trình khởi chạy và trình dừng vào một trình cài đặt duy nhất.

Người dùng cuối không cần cài sẵn Node.js, npm hoặc các dependency khác. Sau khi cài đặt, có thể khởi chạy dsh web bằng shortcut trên desktop hoặc menu Start; trình duyệt sẽ tự động mở khi dịch vụ sẵn sàng.

Tính năng sau khi cài đặt

• Tạo shortcut “DeepSeek Harness” trên desktop và menu Start.
• Tạo shortcut “Đóng DeepSeek Harness” để dừng dịch vụ đang chạy.
• Trình khởi chạy thực thi dsh web và tự động mở trình duyệt sau khi dịch vụ khởi động.
• Menu Start cung cấp mục gỡ cài đặt; chương trình cũng xuất hiện trong danh sách “Ứng dụng” của Windows.
• Sử dụng favicon hình cá voi đi kèm frontend dsh làm biểu tượng ứng dụng.
• Cài đặt cho người dùng hiện tại, không yêu cầu nâng quyền UAC.

Thư mục cài đặt mặc định:

%LOCALAPPDATA%\Programs\DeepSeekHarness

Người dùng cũng có thể chọn thư mục khác trong trình hướng dẫn cài đặt.

Tìm hiểu cấu trúc thư mục dự án

Trước khi bắt đầu build, hãy tìm hiểu công dụng của một số thư mục và tệp quan trọng:

• build\build.ps1: điểm vào build chính, chịu trách nhiệm lấy dsh, tải Node.js portable, tạo biểu tượng, biên dịch trình khởi chạy và trình dừng, rồi tạo gói cài đặt.
• build\fetch-nsis.ps1: tải NSIS 3.11 portable và thử các mirror khác khi mirror SourceForge không khả dụng.
• src\Launcher.cs: mã nguồn trình khởi chạy, sau khi biên dịch tạo DeepSeekHarness.exe.
• src\Stopper.cs: mã nguồn trình dừng, sau khi biên dịch tạo DeepSeekHarnessStop.exe.
• src\installer.nsi: tập lệnh cài đặt NSIS.
• src\icon\build-icon.js: sử dụng sharp đi kèm dsh để chuyển SVG hình cá voi thành ICO nhiều kích thước.
• test\test-install.ps1: thực hiện kiểm thử cài đặt im lặng, kiểm tra tệp, khởi chạy, dừng, kiểm tra HTTP và gỡ cài đặt.
• work\: lưu các tệp trung gian như gói Node.js, NSIS và staging; có thể xóa hoặc giữ lại để tăng tốc các lần build sau.
• out\: lưu trình cài đặt một tệp cuối cùng.

Chuẩn bị môi trường build

Máy build cần đáp ứng các điều kiện sau:

• Windows 10 hoặc Windows 11 x64.
• PowerShell 5.1.
• .NET Framework 4.x.
• Đã cài Node.js và bảo đảm có thể tìm thấy node.exe từ PATH, hoặc chỉ định rõ đường dẫn khi build.
• Có thể truy cập nodejs.org và SourceForge.

Dự án sử dụng trình biên dịch C# có sẵn trong hệ thống để biên dịch hai tệp thực thi. Đường dẫn mặc định:

C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe

Nếu hệ thống chưa cài NSIS 3.x, tập lệnh build sẽ tự động tải bản portable vào work\nsis.

Quan trọng: Đường dẫn dự án không được chứa khoảng trắng vì các tham số định nghĩa dòng lệnh của makensis không xử lý chính xác đường dẫn có khoảng trắng.

Bước 1: Cài đặt dsh

Mặc định, tập lệnh build đọc @deepseek-ai/dsh từ thư mục npm toàn cục. Trước tiên, hãy chạy trên máy build:

npm i -g @deepseek-ai/dsh

Thư mục gói mặc định:

%APPDATA%\npm\node_modules\@deepseek-ai\dsh

Nếu dsh nằm ở vị trí khác, bạn có thể chỉ định bằng tham số -DshSource sau đó.

Bước 2: Build trình cài đặt một tệp

Chuyển đến thư mục gốc của dự án và chạy:

powershell -ExecutionPolicy Bypass -File build\build.ps1

Tập lệnh sẽ lần lượt chuẩn bị tệp dsh, Node.js portable, biểu tượng ứng dụng, trình khởi chạy C#, trình dừng và gói cài đặt NSIS. Sản phẩm mặc định có dạng:

out\DeepSeekHarness-Setup-0.1.1.exe

README cho biết kích thước gói cài đặt mẫu khoảng 44 MB.

Các tham số build thường dùng

• -DshSource <thư mục>: chỉ định thư mục gói dsh.
• -NodeExe <đường dẫn>: chỉ định node.exe trên máy build.
• -AppVersion <phiên bản>: ghi đè số phiên bản của gói cài đặt.
• -WorkDir <thư mục>: thay đổi thư mục tệp trung gian.
• -OutDir <thư mục>: thay đổi thư mục xuất gói cài đặt.

Ví dụ, sử dụng đường dẫn dsh, Node.js và số phiên bản tùy chỉnh:

powershell -ExecutionPolicy Bypass -File build\build.ps1 -DshSource C:\dev\dsh -NodeExe C:\nodejs\node.exe -AppVersion 0.1.1 -OutDir C:\dsh-output

Mặc định, số phiên bản được lấy từ package.json của dsh. Phiên bản phát hành trước sẽ được chuyển thành phiên bản cơ sở; chẳng hạn 0.1.1-rc.2 sẽ tạo ra 0.1.1.

Các tệp trong work\ được giữ lại và tái sử dụng. Sau khi tải xong gói Node.js, gói này sẽ không được tải lại; thư mục NSIS đã giải nén cũng tiếp tục được sử dụng.

Bước 3: Cài đặt và sử dụng cơ bản

Sau khi build xong, nhấp đúp vào trình cài đặt trong thư mục out\ và hoàn tất theo hướng dẫn. Vì sử dụng chế độ cài đặt cho người dùng hiện tại, mặc định sẽ không xuất hiện yêu cầu nâng quyền UAC.

1. Nhấp đúp vào “DeepSeek Harness” trên desktop hoặc menu Start.
2. Trình khởi chạy thực thi dsh web.
3. Khi dịch vụ khả dụng, trình duyệt mặc định sẽ tự động mở trang tương ứng.
4. Khi cần dừng dịch vụ, chạy “Đóng DeepSeek Harness”.
5. Khi cần xóa chương trình, gỡ cài đặt từ mục tương ứng trong menu Start hoặc danh sách “Ứng dụng” của Windows.

Bạn cũng có thể cài đặt ở chế độ im lặng vào thư mục mặc định:

out\DeepSeekHarness-Setup-0.1.1.exe /S

Bước 4: Chạy kiểm thử tự động

Dự án cung cấp tập lệnh kiểm thử bao phủ toàn bộ quy trình cài đặt:

powershell -ExecutionPolicy Bypass -File test\test-install.ps1

Tập lệnh kiểm thử sẽ thực hiện:

1. Cài đặt im lặng vào testinstall\ trong dự án.
2. Lần lượt kiểm tra tệp cài đặt và shortcut.
3. Sử dụng các entry point mô phỏng để xác minh hoạt động của trình khởi chạy và trình dừng.
4. Thực sự khởi chạy dsh web một lần bằng Node.js portable trong thư mục cài đặt.
5. Kiểm tra phản hồi HTTP 200 qua cổng kiểm thử mặc định 3999, tránh chiếm cổng phổ biến 3080.
6. Thực hiện gỡ cài đặt và kiểm tra kết quả.

Đầu ra sẽ xuất hiện nhiều dòng thông tin kiểm tra bắt đầu bằng ###. Dòng cuối cùng phải là:

ALL CHECKS PASSED

Nếu kiểm thử thất bại, cuối đầu ra sẽ hiển thị số lượng mục thất bại.

Lưu ý: Shortcut do kiểm thử tạo có tên hoàn toàn giống bản cài đặt chính thức. Vì vậy, khi chạy kiểm thử, shortcut trên desktop và menu Start của người dùng hiện tại sẽ tạm thời trỏ đến testinstall\ và bị xóa trong giai đoạn gỡ cài đặt. Sau khi kiểm thử hoàn tất, nếu cần khôi phục bản cài đặt chính thức, hãy chạy lại lệnh cài đặt im lặng.

Nhật ký chạy và xử lý sự cố

Các tệp trạng thái quan trọng trong quá trình chạy được lưu tại:

%LOCALAPPDATA%\DeepSeekHarness\pid.txt
%LOCALAPPDATA%\DeepSeekHarness\run.log

• pid.txt lưu ID tiến trình dsh đang chạy; trình dừng dựa vào đó để xác định tiến trình mục tiêu.
• run.log lưu đầu ra tiêu chuẩn và lỗi tiêu chuẩn của dsh.

Nếu khởi chạy thất bại, trình khởi chạy sẽ hiển thị vị trí của run.log trong hộp thoại. Khi xử lý sự cố, trước tiên hãy xem nhật ký này để kiểm tra xung đột cổng, lỗi tải dependency hoặc lỗi khởi động dịch vụ.

Mẹo nâng cao và lưu ý triển khai

Bảo đảm phiên bản Node.js tương thích với module native

Các dependency của dsh bao gồm những module native như node-pty, sharp và koffi. Node.js portable phải tương thích với các module này, vì vậy tập lệnh build mặc định chọn cùng phiên bản Node.js với máy build. Khi thay đổi -NodeExe, cần xác nhận lại rằng gói cài đặt có thể khởi chạy bình thường.

Tránh khởi chạy dịch vụ trùng lặp

Khi dsh đã chạy trên cổng mặc định 3080, việc nhấp đúp trình khởi chạy lần nữa sẽ không tạo instance thứ hai. Trình khởi chạy kiểm tra xem tiến trình trong tệp pid còn hoạt động hay không và trực tiếp mở trang dịch vụ hiện có.

Không để trình khởi chạy thoát quá sớm

Sau khi khởi chạy dsh, trình khởi chạy tiếp tục hoạt động như một tiến trình máy chủ trong nền, liên tục ghi đầu ra tiêu chuẩn và lỗi tiêu chuẩn vào run.log cho đến khi dsh thoát. Nếu trình khởi chạy kết thúc ngay, pipe đầu ra sẽ bị ngắt và dsh có thể gặp EPIPE khi tiếp tục ghi nhật ký.

Chờ đúng quá trình gỡ cài đặt NSIS

Trình gỡ cài đặt NSIS trước tiên sao chép chính nó vào %TEMP%, sau đó tiếp tục chạy từ thư mục tạm; tiến trình gỡ cài đặt ban đầu sẽ nhanh chóng thoát. Vì vậy, tập lệnh tự động không thể chỉ chờ tiến trình ban đầu kết thúc mà nên liên tục kiểm tra xem thư mục cài đặt đã biến mất hay chưa. test-install.ps1 của dự án đã cung cấp cách triển khai tương ứng.

Lưu ý về mã hóa tập lệnh cài đặt

installer.nsi phải sử dụng UTF-8 BOM hoặc UTF-16LE, nếu không NSIS sẽ báo lỗi Bad text encoding. Tệp nguồn trong repository là UTF-8 không BOM; build.ps1 sẽ chuyển đổi tệp sang UTF-16LE trước khi gọi makensis.

Kiểm soát kích thước gói cài đặt

Quá trình đóng gói sẽ loại bỏ các tệp không được môi trường Windows x64 tải, bao gồm tệp biên dịch sẵn Darwin, Linux, ARM64 của node-pty và phiên bản WASM của sharp. README cho biết cách xử lý này có thể tiết kiệm khoảng 30 MB.

Thông tin giấy phép

Bản thân dsh sử dụng giấy phép MIT; xem nội dung cụ thể trong LICENSE của gói dsh. Tập lệnh gói cài đặt của dự án này cũng được phát hành theo giấy phép MIT. Biểu tượng cá voi lấy từ tài nguyên frontend của dsh, bản quyền thuộc về DeepSeek.

Tóm tắt

DeepSeek Harness Easy-Setup tích hợp dsh, Node.js portable, các chương trình khởi động và dừng trên Windows cùng quy trình cài đặt NSIS. Sau khi chuẩn bị môi trường, chỉ cần cài dsh toàn cục và chạy build\build.ps1 để tạo trình cài đặt một tệp mà máy đích không cần cài sẵn Node.js. Trước khi phát hành, nên chạy đầy đủ tập lệnh kiểm thử và đặc biệt kiểm tra nhật ký, khả năng tương thích phiên bản Node.js cũng như việc khôi phục shortcut.