Hướng dẫn tự lưu trữ SkyDot: Xây dựng không gian làm việc AI đa Dot từ đầu

SkyDot là gì

SkyDot là một bộ công cụ Agent đa người dùng, mã nguồn mở và tự lưu trữ, được xây dựng trên Pi Agent Runtime. Bạn có thể tạo nhiều Dot có tên và cấu hình riêng để đảm nhiệm các vai trò khác nhau; đồng thời đưa nhiều Dot vào nhóm trò chuyện, rồi mở rộng khả năng làm việc lâu dài bằng tác vụ định kỳ, Skills, MCP, Plugins và Memory.

Đây không chỉ là một trang trò chuyện. Workspace chịu trách nhiệm phân tách tệp, phiên, bộ nhớ và ranh giới thực thi; Backend xử lý xác thực, quyền hạn, hàng đợi, lập lịch, Provider và kênh tin nhắn; còn Host hoặc Docker Runner thực sự thực thi Agent. Các yêu cầu cấp quyền công cụ, yêu cầu thiết bị và tiến độ tác vụ cần người dùng xác nhận cũng được trả về cùng một bộ công cụ.

Kiến trúc cốt lõi và ranh giới thực thi

SkyDot tách biệt giao diện, mặt phẳng điều khiển và mặt phẳng thực thi, phù hợp cho cả sử dụng cá nhân lẫn triển khai tự lưu trữ trong nhóm.

• Backend: Được xây dựng trên Node.js, TypeScript, Hono, SQLite và WebSocket, chịu trách nhiệm xác thực, lưu trữ, hàng đợi, lập lịch, Provider, kênh và cấp quyền.
• Runner: Sử dụng Pi Agent Runtime để thực thi các tác vụ Agent thực tế, hỗ trợ chế độ Host trên máy cục bộ hoặc container Docker không chạy root.
• Workspace: Quyết định tệp, Session, Memory, liên kết kênh và ranh giới vận hành.
• Web, PWA và Electron: Dùng chung frontend nghiệp vụ React. Electron Renderer chỉ phụ trách giao diện, không trực tiếp truy cập cơ sở dữ liệu, hệ thống tệp, thông tin xác thực, Docker hoặc quyền shell/process.

Quyền hạn không tự động vượt qua các ranh giới khác chỉ vì một tầng đã cho phép. Trước khi triển khai môi trường nhóm, bạn nên đọc ma trận quyền hạn và chính sách bảo mật.

Tính năng chính

Dot cá nhân và phiên trò chuyện

Mỗi Dot có thể được thiết lập độc lập về tên, ảnh đại diện, Prompt, model, cấp độ suy luận, Skills, MCP và chính sách thực thi. Cuộc trò chuyện hỗ trợ đầu ra theo luồng, Markdown, khối mã, tệp đính kèm, hủy tác vụ, tin nhắn tiếp theo và khôi phục phiên.

Các Workspace được cô lập với nhau. Tệp, phiên, bộ nhớ, liên kết kênh và quyền thực thi không bị dùng lẫn chỉ vì được mở trong cùng một giao diện. Khi thực thi, bạn có thể chọn chế độ Host hoặc Container.

Trò chuyện nhóm và cộng tác nhiều Dot

Sau khi bật trò chuyện nhóm nguyên bản, bạn có thể xem tin nhắn, phản hồi tác vụ, tiến độ và kết quả của nhiều Dot trên cùng một dòng thời gian. Việc đề cập rõ ràng và ủy quyền có kiểm soát giúp giới hạn phạm vi cộng tác; kết nối lại hoặc mở lại trang chỉ đọc trạng thái, không tự động gửi tác vụ mới.

Trò chuyện nhóm mặc định bị tắt. Để bật trò chuyện nhóm nguyên bản, cần thiết lập SKYDOT_BOT_GROUPS=true; nếu muốn cho phép các Bot cộng tác thực thi, cần thiết lập thêm SKYDOT_BOT_HANDOFFS=true, đồng thời quản trị viên phải cấu hình quyền thực thi và ngân sách gọi.

Tác vụ định kỳ, Skills và Memory

Scheduler hỗ trợ Cron, khoảng thời gian cố định và tác vụ một lần, đồng thời cung cấp các chức năng chạy ngay, tạm dừng, hủy, xem lịch sử chạy và gửi kết quả. Skills, MCP và Plugins có thể được quản lý tập trung, sau đó cấu hình phạm vi bật theo từng Dot.

Memory lưu theo Workspace các sự kiện, tùy chọn, quyết định, kinh nghiệm và việc cần theo dõi; hỗ trợ tìm kiếm, tạo mới, chỉnh sửa, quên và xem lịch sử phiên bản. Session lưu ngữ cảnh trò chuyện cụ thể, còn Workspace Memory lưu kiến thức có thể tái sử dụng giữa các Session. Hai loại này độc lập với nhau.

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

• Node.js: Phiên bản 22.19 trở lên, khuyến nghị Node.js 24 LTS. Bộ nhớ Pi Durable cần SQLite tích hợp trong Node.js.
• npm: Được cài cùng Node.js, dùng để cài đặt các dependency của từng dự án con.
• Docker: Chỉ cần khi sử dụng chế độ thực thi Container.
• Model Provider: Để trò chuyện AI thực tế, cần một Model Provider khả dụng; chưa có API Key vẫn có thể khởi động giao diện trước.
• GNU Make: Tùy chọn, dùng cho kiểm tra kiểu, sao lưu và các lệnh vận hành.

Cài đặt SkyDot từ đầu

1. Sao chép repository và cài đặt dependency

Chạy các lệnh sau trong terminal để lần lượt cài đặt dependency của dự án chính, frontend Web và Agent Runner:

git clone https://github.com/2SinceJuly/SkyDot.git
cd SkyDot

npm install
npm --prefix web install
npm --prefix container/agent-runner install

2. Xây dựng và khởi động dịch vụ

Sau khi cài đặt dependency, xây dựng toàn bộ thành phần và khởi động Backend:

npm run build:all
npm start

Mở http://127.0.0.1:3000 và làm theo hướng dẫn trên trang để khởi tạo quản trị viên. Provider và kênh tin nhắn có thể cấu hình sau, nhưng nếu chưa có cấu hình model thì không thể chạy trò chuyện AI thực tế.

3. Khởi động môi trường phát triển

Trong quá trình phát triển, có thể khởi động đồng thời Backend và Vite Web Client:

npm run dev:all

Địa chỉ mặc định của trang phát triển là http://127.0.0.1:5173. Nếu chỉ muốn nhanh chóng xem giao diện trên máy cục bộ, có thể sử dụng Demo không cần đăng nhập qua địa chỉ loopback:

SKYDOT_DEMO_OPEN=true PROVIDER_SETUP_SKIPPED=true npm start

Không bật chế độ Demo trên mạng công cộng hoặc mạng không đáng tin cậy. Xem giới hạn đầy đủ của chế độ này trong DEMO.md của repository.

Cấu hình Model Provider

SkyDot cho phép hoàn tất khởi tạo giao diện trước, rồi bổ sung Provider trong phần cài đặt. Khi kết nối model thực tế, cần chuẩn bị API Key, Session Cookie hoặc thông tin xác thực tương ứng, đồng thời tránh ghi thông tin xác thực vào ảnh chụp màn hình, lịch sử dòng lệnh hoặc repository Git.

Nếu sử dụng giao diện OpenAI Completions của bên thứ ba, có thể thiết lập biến môi trường tùy chỉnh trong Provider:

SKYDOT_MODEL_API=openai-completions

Giao thức mặc định là anthropic-messages. Thiết lập này được dùng đồng thời cho Host của cuộc trò chuyện Dot thông thường và Container Runner.

Chọn chế độ thực thi Agent

Chế độ Host

Chế độ Host sử dụng trực tiếp Runner trên máy cục bộ, không cần Docker, phù hợp cho phát triển cục bộ và kiểm tra nhanh. Quyền thực thi vẫn chịu giới hạn của Workspace, người dùng và chính sách vận hành.

Chế độ Container

Chế độ Container cần Docker khả dụng và phải chuẩn bị image Agent Runner. Image mặc định là 2sincejuly/skydot-agent:latest, cũng có thể xây dựng từ mã nguồn hiện tại:

docker build --pull -t 2sincejuly/skydot-agent:latest container

Nếu cần sử dụng image khác, có thể thiết lập SKYDOT_CONTAINER_IMAGE; tùy chọn cấu hình tương thích là CONTAINER_IMAGE. Dịch vụ và quá trình xây dựng image phải kết nối tới cùng một Docker daemon. make start hoặc make dev sẽ ưu tiên sử dụng image cục bộ, nếu thiếu thì thử tải về.

Chạy ứng dụng Electron trên máy tính

Nếu Backend và Vite đã khởi động, có thể chạy Electron trong một terminal khác:

SKYDOT_RENDERER_URL=http://127.0.0.1:5173 npm run desktop:dev

Nếu Backend đã cung cấp trang được xây dựng, cũng có thể chạy trực tiếp:

npm run desktop:dev

Electron cũng có thể kết nối tới Backend từ xa:

SKYDOT_SERVER_URL=https://your-skydot.example.com npm run desktop:dev

Có thể đóng gói cục bộ bằng các lệnh sau:

npm run desktop:package:dir
npm run desktop:package

Dự án mặc định cung cấp cấu hình đóng gói cho macOS arm64, đồng thời giữ lại các mục tiêu Windows và Linux. Trước khi phát hành chính thức, cần cấu hình ký và công chứng cho nền tảng mục tiêu.

Biến môi trường quan trọng

• WEB_PORT: Cổng Backend lắng nghe, giá trị mặc định là 3000.
• SKYDOT_SERVER_URL: Địa chỉ Backend mà Electron kết nối, giá trị mặc định là http://127.0.0.1:3000.
• SKYDOT_RENDERER_URL: Địa chỉ Renderer mà Electron tải.
• SKYDOT_CONTAINER_IMAGE: Image container của Agent Runner.
• PROVIDER_SETUP_SKIPPED: Bỏ qua hướng dẫn Provider khi không có tệp cài đặt hệ thống.
• SKYDOT_BOT_GROUPS: Bật trò chuyện nhóm nhiều Dot nguyên bản.
• SKYDOT_BOT_HANDOFFS: Bật cộng tác thực thi giữa các Bot trong trò chuyện nhóm.
• SKYDOT_PERSONAL_GOALS: Bật tính năng thử nghiệm Goal cá nhân.

Goal cá nhân và Durable Runtime mặc định bị tắt. Tác vụ định kỳ thông thường không phụ thuộc vào các công tắc này. Xem tài liệu Goals and Tasks để biết các điều kiện vận hành cụ thể.

Quy trình sử dụng cơ bản

1. Đăng nhập SkyDot và hoàn tất khởi tạo quản trị viên.
2. Cấu hình Model Provider khả dụng trong phần cài đặt.
3. Tạo một Dot, thiết lập tên, Prompt, model và chính sách thực thi cho Dot đó.
4. Chọn Workspace cho Dot, đảm bảo ranh giới tệp và bộ nhớ đúng như mong đợi.
5. Gửi tác vụ trong cuộc trò chuyện, theo dõi đầu ra theo luồng, cấp quyền công cụ và kết quả thực thi.
6. Nếu cần chạy lâu dài, tạo tác vụ Cron, khoảng thời gian cố định hoặc tác vụ một lần.
7. Khi cần cộng tác nhiều vai trò, bật tính năng trò chuyện nhóm và cấu hình rõ quyền cộng tác của Bot.

Ví dụ, có thể tạo một Dot chuyên phân tích mã nguồn và một Dot chuyên sắp xếp tài liệu, sau đó thêm chúng vào cùng một cuộc trò chuyện nhóm. Bằng cách đề cập rõ ràng hoặc ủy nhiệm có kiểm soát để phân công nhiệm vụ, người dùng có thể xem tiến độ và kết quả trong cùng một dòng thời gian, đồng thời duy trì ranh giới quyền hạn riêng của từng Workspace.

Đề xuất vận hành và bảo mật

Dữ liệu thời gian chạy mặc định được lưu trong thư mục data/ của kho lưu trữ, bao gồm SQLite, Workspace, Session, Memory và cấu hình chạy. Thư mục này không được đưa vào Git, nhưng bản sao lưu có thể chứa cấu hình nhạy cảm và cơ sở dữ liệu, vì vậy cần được bảo vệ tương đương dữ liệu gốc.

• Dùng make status để xem trạng thái Backend, nhật ký và Docker.
• Dùng make stop để dừng dịch vụ SkyDot trên cổng hiện tại.
• Dùng make backup để tạo bản sao lưu dữ liệu thời gian chạy.
• Dùng make restore FILE=... để khôi phục bản sao lưu được chỉ định.
• Dùng make typecheck để kiểm tra Backend, Web, Agent Runner và tài liệu.
• Dùng npm test -- --run để chạy các bài kiểm thử Vitest.

Khi triển khai từ xa, cần sử dụng HTTPS và WSS, đồng thời cấu hình đúng reverse proxy, Cookie và kiểm soát truy cập. Không được trực tiếp để Renderer, cơ sở dữ liệu hoặc Docker daemon lộ ra cho người dùng không đáng tin cậy, cũng không nên bật Demo công khai chỉ để thuận tiện.

Mở rộng thêm

Thư viện capability của SkyDot hỗ trợ các nguồn tích hợp sẵn, máy chủ, dự án, người dùng, Workspace và Plugin. Trước khi Agent chạy, hệ thống sẽ tạo danh sách capability hợp lệ và đưa Prompt, tài nguyên cùng ngữ cảnh vào theo chính sách. Dự án cũng hỗ trợ snapshot phiên bản Plugin, Subagents, cùng ranh giới capability nhất quán giữa Host và Container.

Về các điểm tiếp nhận tin nhắn, Web, PWA và Electron dùng chung một frontend nghiệp vụ, đồng thời có thể kết nối với Feishu, Telegram, QQ, DingTalk, WeChat, Discord, WhatsApp và các kênh khác. Kênh có thể được liên kết với Workspace hoặc Session cụ thể.

Tóm tắt

SkyDot tích hợp trò chuyện với nhiều Dot, cô lập Workspace, thực thi Agent, tác vụ định kỳ, capability mở rộng và quyền nhóm vào một workbench tự lưu trữ. Sau khi hoàn tất việc chuẩn bị môi trường Node.js, cài đặt dependency, build, khởi động và cấu hình Provider theo bài viết này, bạn có thể bắt đầu chạy Dot cá nhân, rồi từng bước bật các capability như Docker, Electron, trò chuyện nhóm, Scheduler, Skills, MCP và Memory.

Vì dự án vẫn đang được phát triển liên tục, model thực tế, Docker, các kênh bên ngoài và triển khai từ xa đều phụ thuộc vào credential và môi trường chạy tương ứng. Các capability thử nghiệm như Goal, Durable hoặc Cloud Runtime cũng không nên được xem là tính năng được bật mặc định.