Hướng dẫn AI

Hướng dẫn phát triển ZCode: Thiết lập môi trường lập trình AI trên máy tính, Web và thiết bị đầu cuối

Hướng dẫn này giới thiệu cách thiết lập môi trường phát triển ZCode, chạy ứng dụng Electron trên máy tính, không gian làm việc Web và Agent CLI, đồng thời cấu hình thêm tài nguyên từ xa, xác thực truy cập và gói phát hành.

21 tháng 9, 2026Thời gian đọc khoảng 26 phút

Hướng dẫn phát triển ZCode: Thiết lập môi trường lập trình AI trên máy tính, Web và thiết bị đầu cuối

Giới thiệu về ZCode

Logo dự án ZCode

ZCode là một môi trường làm việc lập trình AI, đồng thời cung cấp ứng dụng desktop Electron, giao diện trình duyệt và Agent trên terminal. Kho lưu trữ được tổ chức theo mô hình workspace, tập trung quản lý mã nguồn của client, dịch vụ backend, UI dùng chung, Agent CLI, TUI và runtime.

Dự án cung cấp ba điểm vào phát triển chính:

Desktop: Ứng dụng desktop Electron, khởi động bằng pnpm dev:desktop.
Web: Đồng thời khởi động workspace trên trình duyệt và backend cục bộ bằng pnpm dev:web.
Agent CLI: Phát triển trực tiếp Agent trên terminal hoặc TUI bằng pnpm --filter @zcode/cli dev.

Ngoài ra, ZCode có thể được xây dựng thành gói phát hành dòng lệnh thống nhất. Sau khi cài đặt, chạy zcode để vào TUI, hoặc chạy zcode --web để khởi động workspace Web cục bộ.

Tính năng chính

Cung cấp ba phương thức sử dụng: desktop, trình duyệt và terminal.
Frontend Web, backend HTTP/WebSocket và Agent có thể kết hợp trên máy cục bộ thành một quy trình làm việc hoàn chỉnh.
Desktop và Web dùng chung runtime của Agent CLI.
Hỗ trợ phát triển trên workspace từ xa như SSH và WSL.
Dùng chung component React, hooks, state Zustand, kiểu dữ liệu giao thức, framework RPC và SDK client của Agent.
Có thể xây dựng riêng gói cài đặt desktop và gói phát hành dòng lệnh ZCode thống nhất.
Khi lắng nghe kết nối bên ngoài, Web hỗ trợ tự động tạo access token, đồng thời cho phép cấu hình token xác thực rõ ràng.

Chuẩn bị môi trường phát triển

Cài đặt công cụ cần thiết

Trước khi bắt đầu, hãy chuẩn bị các công cụ sau. Phiên bản cụ thể được quy định trong mise.toml ở thư mục gốc của kho lưu trữ:

Git
Node.js 24.14.0
pnpm 10.33.2

Sau khi clone kho lưu trữ và chuyển vào thư mục gốc, chạy lệnh khởi tạo được khuyến nghị:

pnpm bootstrap

pnpm bootstrap sẽ cài đặt các dependency của workspace, chuẩn bị tài nguyên chạy cục bộ cho desktop và thực thi build:bootstrap. Agent CLI và runtime đã nằm trong apps/zcode-cli/, không cần khởi tạo Git submodule bổ sung.

Bootstrap mặc định bỏ qua việc chuẩn bị tài nguyên từ xa, nên phù hợp hơn cho phát triển desktop cục bộ. Chỉ khi cần SSH, WSL hoặc tài nguyên phát hành từ xa mới cần chạy các lệnh liên quan đến tài nguyên từ xa.

Chọn lệnh khởi tạo theo nhu cầu

pnpm install: Chỉ cài đặt dependency.
pnpm prepare:desktop-runtime: Chuẩn bị tài nguyên runtime cho desktop, mặc định bao gồm việc chuẩn bị tài nguyên từ xa.
pnpm prepare:remote-assets: Chỉ chuẩn bị tài nguyên runtime từ xa.
pnpm bootstrap:with-remote: Khởi tạo dependency, tài nguyên cục bộ và từ xa, đồng thời build tuần tự các package liên quan, nhưng bỏ qua bundle ứng dụng desktop.
pnpm build: Đệ quy thực thi script build của từng package trong workspace, bao gồm các bước chuẩn bị tài nguyên bên trong package.

Chạy phiên bản desktop

Sau khi hoàn tất khởi tạo, khởi động ứng dụng desktop Electron tại thư mục gốc của kho lưu trữ:

pnpm dev:desktop

pnpm dev:desktop mặc định tương đương với pnpm dev:desktop:prod, sử dụng cấu hình dịch vụ production. Script khởi động sẽ chuẩn bị tài nguyên runtime cục bộ, build Agent cho desktop, sau đó khởi động Electron và theo dõi thay đổi mã nguồn.

Nếu muốn sử dụng môi trường test, có thể chạy:

pnpm dev:desktop:test

Cô lập dữ liệu phát triển

Để tránh trộn lẫn dữ liệu phát triển với dữ liệu sử dụng hằng ngày, có thể chỉ định thư mục gốc dữ liệu riêng bằng ZCODE_DATA_BASE_DIR. Dữ liệu ứng dụng sẽ được ghi vào .zcode/ bên trong thư mục đó:

ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test

Cú pháp này áp dụng cho macOS và Linux.

Chạy workspace Web

Khi chỉnh sửa mã nguồn frontend hoặc backend Web, nên sử dụng chế độ phát triển kết hợp:

pnpm dev:web

Lệnh này sẽ đồng thời khởi động:

Server phát triển Web, địa chỉ mặc định là http://localhost:5173.
Backend cục bộ, địa chỉ mặc định là http://localhost:3030.

Trình duyệt nên truy cập địa chỉ frontend. Server phát triển sẽ proxy /ws và các request /api thông thường đến backend cục bộ; /api/v1/oauth/token sẽ được proxy riêng đến dịch vụ sản phẩm hiện được cấu hình.

Chỉ định workspace backend

Trên macOS hoặc Linux, có thể chỉ định thư mục dự án mà backend Web sử dụng thông qua biến môi trường:

ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web

Nếu đã chỉnh sửa mã nguồn Agent, cần build lại CLI cùng các dependency trong workspace, sau đó khởi động lại dịch vụ:

pnpm --filter @zcode/cli... build

Phát triển Agent CLI và TUI

Nếu chủ yếu phát triển giao diện terminal hoặc Agent, có thể chạy trực tiếp entry point của mã nguồn:

pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli dev

Sau khi build CLI và các dependency, cũng có thể chạy trực tiếp file CommonJS đã tạo:

pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

Entry point của mã nguồn này chạy trực tiếp Agent CLI và không thực hiện phân luồng --web trong lệnh phát hành thống nhất. Để phát triển Web, hãy dùng pnpm dev:web; để kiểm thử lệnh zcode thống nhất, cần build và giải nén gói phát hành dòng lệnh.

Sử dụng phiên bản dòng lệnh ZCode

Gói phát hành dòng lệnh kết hợp TUI, Web, backend và Agent, đồng thời khởi động thống nhất thông qua zcode. Gói này không phụ thuộc vào Electron, nhưng runtime vẫn yêu cầu Node.js phù hợp với quy định trong mise.toml.

Lệnh cơ bản

# Vào giao diện tương tác terminal
zcode

# Khởi động workspace Web
zcode --web

# Chỉ định dự án và cổng, đồng thời không tự động mở trình duyệt
zcode --web --workspace /path/to/project --port 3030 --no-open

# Xem trợ giúp
zcode --help
zcode --web --help

Chế độ Web mặc định sử dụng thư mục hiện tại làm thư mục làm việc, lắng nghe trên 127.0.0.1, tự động chọn cổng còn trống và mở trình duyệt. Theo mặc định, access token không được bật. Sau khi sử dụng xong, có thể nhấn Ctrl+C trong terminal để dừng dịch vụ.

Truy cập trong mạng cục bộ

Nếu cần cho thiết bị khác truy cập, có thể đổi địa chỉ lắng nghe thành 0.0.0.0:

zcode --web --host 0.0.0.0

Khi lắng nghe trên địa chỉ không phải máy cục bộ, ZCode mặc định sẽ tạo access token. Hãy sử dụng liên kết có token được in trong terminal để truy cập dịch vụ. Cũng có thể chỉ định token bằng --token, hoặc tắt xác thực token bằng --no-token.

Khi trực tiếp khởi động entry point HTTP của dịch vụ Web chung, có thể cấu hình xác thực API và WebSocket thông qua ZCODE_SERVER_AUTH_TOKEN; khi tạo dịch vụ thông qua API lập trình, hãy sử dụng tùy chọn authToken.

Cấu hình biến môi trường

.env.example ở thư mục gốc của kho lưu trữ cung cấp ví dụ về địa chỉ dịch vụ và cấu hình build. Có thể sao chép thành .env khi cần, đồng thời đặt các giá trị ghi đè chỉ dùng cục bộ trong .env.local.

ZCODE_DATA_BASE_DIR: Thư mục gốc dữ liệu ứng dụng; dữ liệu được ghi vào .zcode/ bên trong thư mục này.
ZCODE_SERVER_WORKSPACE: Chỉ định đường dẫn workspace của backend Web.
ZCODE_BUILTIN_PROVIDER_CONFIG_FILE: Chỉ định file cấu hình Provider cục bộ; nếu chưa thiết lập, cấu hình tích hợp sẵn sẽ được sử dụng.
ZCODE_DIST_BASE_URL: Địa chỉ gốc tải xuống được script cài đặt dòng lệnh sử dụng.

Các biến runtime này cũng có thể được đặt trực tiếp trong môi trường của lệnh khởi động. Cấu hình dịch vụ phát triển của Desktop được lựa chọn thông qua dev:desktop:test và dev:desktop:prod.

Phát triển tính năng từ xa qua SSH và WSL

Trước khi phát triển tính năng workspace từ xa, hãy chuẩn bị tài nguyên từ xa:

pnpm bootstrap:with-remote
pnpm dev:desktop

Khi kết nối đến dự án từ xa, hãy chọn tài nguyên “Tải xuống cục bộ rồi tải lên”. Môi trường phát triển sẽ lấy tài nguyên từ packages/desktop/mock-cdn cục bộ và các sản phẩm build cục bộ, sau đó tải lên máy chủ từ xa qua SFTP, không truy cập CDN.

Build gói cài đặt desktop

Chạy lệnh sau để build phiên bản desktop:

pnpm bundle:desktop

Mục tiêu mặc định là macOS arm64, thư mục đầu ra là packages/desktop/dist/. Cũng có thể chỉ định hệ điều hành và kiến trúc CPU:

pnpm bundle:desktop -- --os win --arch x64
pnpm bundle:desktop -- --help

--os hỗ trợ mac, win và linux; --arch hỗ trợ x64 và arm64. Việc đóng gói và ký thực tế vẫn cần các công cụ và cấu hình tương ứng với nền tảng mục tiêu.

Trên macOS, có thể mở DMG được tạo và kéo ZCode vào “Applications”. Nếu bản build cục bộ chưa được ký bị hệ thống chặn khi khởi động lần đầu, có thể thực thi:

sudo xattr -rd com.apple.quarantine /Applications/ZCode.app

Build gói phát hành dòng lệnh

Entry point để build gói phát hành dòng lệnh là pnpm build:zcode. Trước khi build, bắt buộc phải thiết lập địa chỉ gốc tải xuống ZCODE_DIST_BASE_URL; cũng có thể truyền trực tiếp thông qua --base-url:

pnpm build:zcode --base-url https://downloads.example.com/zcode/

# Khi đã cấu hình ZCODE_DIST_BASE_URL
pnpm build:zcode

# Tái sử dụng sản phẩm build hiện có, chỉ đóng gói lại
pnpm build:zcode --skip-build

# Xem các tùy chọn
pnpm build:zcode --help

Địa chỉ tải xuống trong ví dụ chỉ là địa chỉ giữ chỗ; khi phát hành chính thức, cần thay thế bằng địa chỉ lưu trữ thực tế. Script build sẽ lần lượt xử lý CLI/TUI, backend và Web, thu thập thư viện native, worker cùng các dependency runtime, sau đó đóng gói thành bản phát hành.

Phiên bản mặc định lấy từ package.json ở thư mục gốc; thư mục đầu ra là dist/zcode/, bao gồm:

releases/<version>/zcode-<version>.tar.gz: gói chạy.
releases/<version>/sha256.txt: giá trị băm kiểm tra.
latest.json: chỉ mục phiên bản.
install.sh: script cài đặt.

Mặc định, script cài đặt sẽ cài runtime vào ~/.zcode/runtime và tạo lệnh zcode trong ~/.local/bin. Có thể lần lượt thay đổi hai vị trí này thông qua ZCODE_DIST_HOME và ZCODE_DIST_BIN_DIR.

Xác minh gói phát hành cục bộ

Không cần tải tệp lên hoặc chạy script cài đặt, bạn vẫn có thể giải nén và chạy trực tiếp kết quả build:

zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" \
  -C dist/zcode/debug

# Khởi động TUI
node dist/zcode/debug/zcode/bin/zcode.mjs

# Khởi động Web
node dist/zcode/debug/zcode/bin/zcode.mjs --web \
  --workspace "$PWD" --port 3030 --no-open

Sau đó truy cập http://127.0.0.1:3030 để xác minh toàn bộ luồng, trong đó cùng một backend cung cấp trang Web và Agent. Cổng phải đang ở trạng thái trống; nếu pnpm dev:web đang sử dụng cổng này, hãy dùng --port để chuyển sang cổng khác.

Đề xuất phát triển nâng cao

Ưu tiên sử dụng đúng entry point: dùng dev:desktop cho tính năng desktop, dev:web để phát triển đồng thời frontend và backend, và lệnh dev của CLI workspace cho Agent và TUI.
Build lại sau khi sửa Agent: dịch vụ Web không tự động nhận được toàn bộ kết quả build của Agent; sau khi sửa, cần chạy pnpm --filter @zcode/cli... build và khởi động lại dịch vụ.
Cô lập dữ liệu kiểm thử: dùng ZCODE_DATA_BASE_DIR để tạo các thư mục dữ liệu độc lập cho từng ngữ cảnh phát triển.
Giữ xác thực khi lắng nghe kết nối bên ngoài: sau khi dùng --host 0.0.0.0, nên ưu tiên giữ token được tạo tự động hoặc thiết lập rõ ràng --token.
Kiểm tra nguồn của lệnh: pnpm build:zcode chỉ tạo gói phát hành, không thay thế zcode hiện có trong PATH của hệ thống. Trên macOS và Linux có thể chạy command -v zcode; trên Windows có thể chạy where.exe zcode.
Phân biệt xác minh phát triển và phát hành: pnpm dev:web phù hợp cho việc lặp lại trong quá trình phát triển mã nguồn; bin/zcode.mjs sau khi giải nén phù hợp hơn để xác minh lệnh thống nhất cuối cùng và toàn bộ quy trình phát hành.

Tổng quan nhanh về cấu trúc repository

packages/desktop: Electron Main, Host, Renderer và đóng gói desktop.
packages/web: client Web.
packages/server: dịch vụ HTTP, WebSocket và kết nối từ xa.
packages/zcode-server-cli: khởi động Server độc lập và quản lý tiến trình.
packages/ui: component React dùng chung, hooks và state Zustand.
packages/services: dịch vụ nghiệp vụ và lưu trữ bền vững.
packages/shared、packages/rpc、packages/client: giao thức và kiểu dùng chung, framework RPC cùng SDK client Agent.
packages/provider、packages/provider-node: năng lực dùng chung của Provider và phần triển khai Node.js.
apps/zcode-cli: Agent CLI, TUI, runtime và công cụ.
scripts、config、third-party: script bảo trì build, cấu hình tích hợp sẵn và tài liệu khai báo bên thứ ba.

Tóm tắt

ZCode tích hợp desktop, Web, backend và Agent CLI trong cùng một workspace. Khi bắt đầu phát triển, có thể chạy pnpm bootstrap, sau đó chọn entry point phù hợp với mục tiêu: pnpm dev:desktop, pnpm dev:web hoặc mã nguồn CLI. Khi cần kiểm thử workspace từ xa hoặc phát hành chính thức, hãy chuẩn bị tài nguyên từ xa rồi build gói cài đặt desktop hoặc dòng lệnh tương ứng.