Hướng dẫn nhập môn Lancer: Xây dựng không gian làm việc AI trên máy tính để bàn song song, có khả năng truy xuất

Lancer là gì

Lancer là một không gian làm việc AI trên máy tính được phát triển dựa trên pi-gui và pi. Ứng dụng tập trung hội thoại, các nhánh song song, quá trình chạy và tệp bàn giao trong cùng một giao diện, giúp bạn theo dõi toàn bộ quá trình của một nhiệm vụ từ lúc tạo, chia nhỏ đến khi bàn giao.

Quan trọng: Lancer hiện đang ở giai đoạn Alpha, trong đó macOS Apple Silicon là nền tảng được kiểm thử chính. Linux và Windows có cấu hình đóng gói, nhưng điều đó không có nghĩa mọi khả năng gốc đã được kiểm thử đầy đủ. Gói nén mã nguồn cũng không phải là gói cài đặt máy tính có thể chạy bằng cách nhấp đúp trực tiếp.

Tính năng cốt lõi

Phiên và nhiệm vụ mô-đun

Phiên thông thường có thể chạy độc lập. Phiên mô-đun cho phép cấu hình các giai đoạn, mô hình, Skill, mục tiêu và yêu cầu bàn giao, phù hợp với những nhiệm vụ phức tạp có các bước rõ ràng và cần nghiệm thu kết quả.

Nhánh song song và tổng hợp kết quả

Một trợ lý có thể quản lý nhiều phiên. Nhiệm vụ có thể tạo các nhánh con và nhánh cháu; sau khi hoàn tất, kết quả của từng nhánh sẽ được trả về phiên cha để tổng hợp. Cấu trúc này phù hợp với nghiên cứu song song, so sánh phương án và sản xuất nội dung nhiều giai đoạn.

Đồ thị sự kiện nhiệm vụ GitTree

GitTree ở bên phải giao diện có thể hiển thị đồng thời nhiều dòng phiên, nhánh, thao tác hợp nhất và các nút bàn giao, đồng thời cũng có thể tập trung vào phiên hiện tại. Cần lưu ý rằng GitTree biểu diễn đồ thị sự kiện nhiệm vụ; các nút trong đó không phải tất cả đều đại diện cho một lần commit Git thực tế.

Phản hồi khi chạy và hiệu ứng tia sáng

Các bong bóng hoạt động và dòng tiến trình sẽ hiển thị viền chuyển động, còn đầu ra của mô hình và thao tác bàn giao sẽ gửi các tia sáng cùng màu đến nút tương ứng. Những phản hồi trực quan này dùng để thể hiện nhiệm vụ đang chạy và hướng luân chuyển kết quả.

Mô hình, tài khoản và tiếp quản Doubao

Lancer kết nối với tài khoản thuê bao, khóa API và endpoint tùy chỉnh thông qua pi, đồng thời quản lý riêng thương hiệu mô hình và gateway. Trên macOS, ứng dụng còn có thể liên kết với một phiên Doubao App đang mở để nhận phản hồi và video. Tính năng tiếp quản Doubao cần quyền trợ năng trên máy; các cập nhật giao diện của phiên bản Doubao dành cho máy tính có thể ảnh hưởng đến khả năng tương thích.

Quy trình phân tích video

Quy trình video có thể tải xuống hoặc nhận video, trích xuất khung hình chính và tạo các tệp phân tích, bàn giao có kèm bằng chứng. Tuy nhiên, hiện chưa thể đảm bảo việc tự động tái tạo sẽ giống mẫu 1:1. Tiếp quản Doubao, phân tích mô hình, hoạt ảnh bằng mã và biên tập cuối cùng là các công đoạn khác nhau, cần được nghiệm thu riêng.

Chuẩn bị trước khi cài đặt

Trước khi bắt đầu, hãy xác nhận môi trường phát triển đáp ứng các yêu cầu sau:

• Node.js >=22.19.0 và <26, khuyến nghị sử dụng Node.js 24.
• pnpm 10.34.9.
• Git.
• macOS cần Xcode Command Line Tools.
• Linux cần Python 3, make, trình biên dịch C++, môi trường máy tính đồ họa và các thư viện runtime hệ thống cần thiết cho Electron.
• Các dependency gốc trên Windows có thể cần Python và Visual Studio Build Tools có workload C++, nhưng phiên bản hiện tại chưa kiểm thử đầy đủ hành vi gốc trên Windows.

Khi macOS thiếu công cụ dòng lệnh, bạn có thể chạy:

xcode-select --install

Debian hoặc Ubuntu có thể cài đặt các dependency biên dịch Linux:

sudo apt-get install build-essential python3

Cài đặt và khởi chạy từ mã nguồn

Giải nén hoặc clone mã nguồn vào một thư mục mới, truy cập thư mục gốc của repository, sau đó lần lượt chạy:

npx --yes pnpm@10.34.9 run doctor
npx --yes pnpm@10.34.9 install --frozen-lockfile
npx --yes pnpm@10.34.9 dev

Các lệnh này cố định sử dụng pnpm 10.34.9, không cần chạy corepack enable và không yêu cầu cài pnpm toàn cục. Nếu hệ thống đã cài đúng phiên bản này, bạn có thể thay tiền tố lệnh bằng pnpm.

Tải dependency cần kết nối mạng. Nếu bỏ qua các script của dependency trong quá trình cài đặt, tệp nhị phân Electron có thể không tồn tại. Sau khi xác nhận mạng có thể truy cập nguồn tải Electron, hãy chạy:

npx --yes pnpm@10.34.9 run setup:electron
npx --yes pnpm@10.34.9 dev

Không nên cho phép hoặc tắt toàn bộ script dependency một cách không chọn lọc để sửa lỗi cài đặt Electron; trước tiên hãy kiểm tra nhật ký cài đặt và lỗi mạng.

Hoàn tất cấu hình lần đầu

1. Khởi động Lancer và mở phần cài đặt.
2. Kết nối tài khoản mô hình, nhà cung cấp hoặc endpoint tùy chỉnh được hỗ trợ. Mã nguồn không đi kèm thông tin xác thực cá nhân.
3. Thêm hoặc chọn một workspace.
4. Tạo phiên thông thường hoặc tạo phiên mô-đun có giai đoạn, mô hình, Skill, mục tiêu và yêu cầu bàn giao tùy theo nhiệm vụ.
5. Sau khi chạy nhiệm vụ, theo dõi dòng phiên, nhánh phát sinh, các nút tổng hợp và bàn giao trong GitTree.

Có thể chỉ định ngôn ngữ giao diện bằng biến môi trường:

LANCER_LOCALE=zh-CN npx --yes pnpm@10.34.9 dev

Để sử dụng giao diện tiếng Anh, đặt giá trị thành en.

Nạp cấu hình môi trường tùy chọn

Cấu hình tùy chọn được ghi trong .env.example của repository, nhưng script khởi động máy tính không tự động đọc tệp này. Trên macOS hoặc Linux, bạn có thể sao chép mẫu và nạp trong terminal hiện tại:

cp .env.example .env.local
set -a
. ./.env.local
set +a
npx --yes pnpm@10.34.9 dev

Người dùng PowerShell có thể đặt từng biến môi trường, ví dụ:

$env:LANCER_LOCALE = "en"

Tài khoản mô hình thực tế nên được kết nối trong phần cài đặt ứng dụng. Không commit khóa API, tệp xác thực, endpoint riêng tư, hội thoại thực hoặc bản ghi màn hình phiên vào repository công khai.

Cấu hình công cụ video

Chỉ sử dụng giao diện hội thoại thì không cần công cụ media. Để chạy quy trình tải video, trích xuất khung hình chính và phân tích media, cần có FFmpeg, FFprobe và yt-dlp có thể thực thi.

pnpm run doctor --media

Nếu các công cụ này không nằm trong PATH, có thể chỉ định đường dẫn tuyệt đối qua các biến môi trường FFMPEG, FFPROBE và YT_DLP, hoặc cấu hình đường dẫn trong video-learn-tools.json ở thư mục dữ liệu người dùng.

Lệnh chẩn đoán sẽ thực sự chạy lệnh phiên bản của từng công cụ, vì vậy không chỉ phát hiện tệp bị thiếu mà còn nhận diện trường hợp “tệp thực thi tồn tại nhưng thiếu thư viện động”. Trước khi xác minh đầy đủ, bạn có thể kiểm tra thủ công:

ffmpeg -version
ffprobe -version

Kiểm tra, build và test

Khi chuẩn bị gửi thay đổi hoặc đánh giá trạng thái mã nguồn, có thể chạy các bước kiểm tra sau:

pnpm check
pnpm build
pnpm audit:dependencies
pnpm verify:install-copy
pnpm verify:release-config
pnpm --filter @lancer/desktop run test:e2e:core

Trong quá trình phát triển, bạn cũng có thể kiểm tra việc reload ứng dụng máy tính:

pnpm --filter @lancer/desktop run test:dev:reload

Test Core chạy giao diện Electron thực với dữ liệu cô lập, nhưng vượt qua test Core không chứng minh rằng mô hình thực tế, quyền gốc, gói cài đặt, hiệu năng hoặc khả năng tương thích trên mọi nền tảng đã được xác minh đầy đủ. Các test liên quan đến media cũng yêu cầu FFmpeg và FFprobe hoạt động bình thường.

Tái sử dụng riêng Lancer Light UI

Nếu chỉ cần hiệu ứng tia sáng kết nối mô hình hoặc bong bóng với cây công việc, có thể xuất Lancer Light UI. Thành phần này không phụ thuộc vào Electron, CLI hay dịch vụ mô hình, đồng thời cung cấp các ví dụ về một dòng, rẽ nhánh hợp nhất và nhiều phiên chạy song song.

pnpm export:light-ui /absolute/new/lancer-light-ui
cd /absolute/new/lancer-light-ui
npm install && npm run dev

Đường dẫn xuất phải được thay bằng đường dẫn tuyệt đối trên máy đích. Xem thêm hướng dẫn trong Light UI README của repository.

Build ứng dụng cục bộ trên macOS

Gói mã nguồn không bao gồm .app có thể chạy bằng cách nhấp đúp trực tiếp và bản tải xuống ứng dụng độc lập cũng chưa được phát hành. Sau khi cài dependency, có thể chạy script build cục bộ:

bash scripts/build-mac-lancer.sh --skip-install --dir

Gói cài đặt cục bộ yêu cầu cấu hình trước chứng chỉ ký lâu dài. Script không tự động tạo chứng chỉ, chuyển sang ký tạm thời hoặc thực hiện công chứng. Kết quả build được lưu trong thư mục độc lập apps/desktop/release-local-*/.

Sau khi xác minh ứng dụng ứng viên, có thể thêm --install để cài vào /Applications:

bash scripts/build-mac-lancer.sh --skip-install --dir --install

Trình cài đặt yêu cầu ứng dụng cũ thoát bình thường, sẽ kiểm tra chữ ký và giữ lại phiên bản cũ có thể khôi phục, đồng thời không xóa dữ liệu phiên. Phân phối công khai vẫn cần Developer ID, công chứng và nghiệm thu trên máy sạch; chữ ký cục bộ không thể được xem là đã hoàn tất chứng nhận phát hành công khai.

Sử dụng nâng cao và khuyến nghị bảo mật

Hiểu vị trí dữ liệu runtime

Dữ liệu phiên và tài khoản sử dụng ~/.pi/agent của pi. Trên macOS, trạng thái giao diện Lancer nằm ở ~/Library/Application Support/Lancer. Sao chép mã nguồn sang thư mục khác không cô lập các dữ liệu runtime này; nếu cần kiểm thử thủ công hoàn toàn cô lập, hãy sử dụng một người dùng hệ điều hành riêng.

Thiết kế nhánh cho nhiệm vụ phức tạp

Có thể tách nghiên cứu, phân tích, triển khai và nghiệm thu thành các nhánh con khác nhau, sau đó để phiên cha tổng hợp. Khi sử dụng GitTree, nên hiểu các nút là sự kiện nhiệm vụ và quan hệ bàn giao, không mặc định xem mỗi nút là một lần commit mã nguồn.

Nghiệm thu riêng từng công đoạn video

Đối với dự án video, cần kiểm tra riêng đầu vào tiếp quản, phân tích mô hình, hoạt ảnh bằng mã và biên tập cuối cùng. Không nên chỉ dựa vào việc một công đoạn thành công để suy ra rằng sản phẩm cuối cùng có thể tự động giống hoàn toàn mẫu tham chiếu.

Xuất gói mã nguồn ứng viên có thể kiểm tra

Khi chuẩn bị phát hành mã nguồn, có thể xuất một thư mục ứng viên mới và danh sách SHA-256:

pnpm export:source /absolute/path/to/new/lancer-source

Lệnh này loại trừ .git, sản phẩm phiên cục bộ, tệp khóa và đầu ra build, nhưng giữ lại workspace hiện tại, ảnh chụp màn hình lịch sử và bản ghi màn hình. Xuất thành công không có nghĩa là có thể công khai phát hành ngay; vẫn cần con người kiểm tra quyền sử dụng tư liệu và nội dung nhạy cảm.

Câu hỏi thường gặp

• Corepack báo lỗi quyền: sử dụng lệnh phiên bản cố định npx --yes pnpm@10.34.9, không cần sửa shim toàn cục.
• Electron chưa được cài đặt đúng: kiểm tra mạng và lỗi cài đặt, sau đó chạy run setup:electron.
• Linux báo thiếu make hoặc trình biên dịch: trước tiên cài Python 3, make và công cụ build C++, sau đó cài lại dependency.
• Kiểm tra công cụ video thất bại: chạy pnpm doctor --media và xác nhận tệp thực thi cùng các thư viện động của chúng đều khả dụng.
• Không thể sử dụng mô hình: kết nối tài khoản hoặc nhà cung cấp được hỗ trợ trong phần cài đặt; mã nguồn không chứa thông tin xác thực cá nhân.

Tóm tắt

Lancer tập hợp các phiên AI song song, phân nhánh đệ quy, phản hồi quá trình và tổ chức tệp bàn giao trong cùng một không gian làm việc trên máy tính. Hãy làm theo hướng dẫn này để hoàn tất việc kiểm tra môi trường, khởi chạy mã nguồn, kết nối tài khoản và cấu hình công cụ đa phương tiện, sau đó bạn có thể bắt đầu xây dựng quy trình tác vụ có thể truy vết. Vì dự án vẫn đang ở giai đoạn Alpha, bạn cần tự kiểm chứng việc sử dụng trong môi trường sản xuất, khả năng tương thích đa nền tảng, tính năng tiếp quản bởi Doubao và kết quả tái tạo video.