Chuyển đến nội dung chính
Hướng dẫn AI

Hướng dẫn Agent Office 3D: Biến AI Coding Agent thành nhân viên văn phòng 3D

Hướng dẫn này sẽ giúp bạn cài đặt Agent Office 3D, khởi động văn phòng mẫu, thiết lập thông tin công ty và nhân viên, sau đó kết nối với Herdr hoặc chọn Minecraft, đồng thời nắm được trạng thái Agent, đầu ra terminal và các thiết lập bảo mật.

Thời gian đọc khoảng 20 phút
Hướng dẫn Agent Office 3D: Biến AI Coding Agent thành nhân viên văn phòng 3D

Agent Office 3D là gì?

Agent Office 3D là một văn phòng 3D low-poly chạy cục bộ, hiển thị các AI Coding Agent như những nhân viên trong văn phòng. Bạn có thể nhanh chóng xem từng Agent đang làm việc, nhàn rỗi, hoàn thành và chờ nhiệm vụ mới, hay bị kẹt ở lời nhắc cần xác nhận quyền.

Dự án mặc định sử dụng dữ liệu minh họa, không cần kết nối Agent trước. Nhân viên nhàn rỗi sẽ pha cà phê, uống nước, sử dụng máy chạy bộ, vươn vai, ngủ gật hoặc chơi mini-game tích hợp; sau khi bật Minecraft, nhân viên cũng có thể vào thế giới cục bộ thông qua bot Mineflayer.

Nhân viên, nhiệm vụ, dự án và số tiền trên màn hình đều là dữ liệu minh họa, không phải thông tin kinh doanh thực tế.

Tính năng chính

  • Trạng thái nhân viên theo thời gian thực: Mỗi Agent có chỗ ngồi, đèn trạng thái và bảng tên riêng; khi cần xác nhận, bảng tên màu đỏ cùng dấu chấm than sẽ hiển thị cảnh báo.
  • Màn hình terminal chỉ đọc: Nhấp vào nhân viên để xem đầu ra terminal gần đây, nhưng không thể gửi lệnh từ giao diện văn phòng.
  • Bảng thông báo: Hiển thị mục tiêu năm, KPI, trọng tâm trong tuần, dòng tiền và danh sách việc cần làm; có thể đánh dấu trực tiếp các việc đã hoàn thành.
  • Cơ sở dữ liệu dự án trên giá sách: Mỗi cuốn sách tương ứng với một thư mục dự án, nơi bạn có thể đọc tài liệu Markdown và ảnh chụp màn hình.
  • Danh sách nhiệm vụ: Xem các tệp và toàn bộ nội dung trong thư mục nhiệm vụ từ phía bên phải.
  • Hoạt động nghỉ ngơi trong Minecraft: Nhân viên nhàn rỗi có thể dùng bot Mineflayer riêng để khai khoáng, chặt cây và xây nhà; góc nhìn thứ nhất cũng được hiển thị trên màn hình bàn làm việc.

Trang chủ bảng thông báo: dòng tiền và mục tiêu năm

Nhấp vào bảng thông báo để mở giao diện toàn màn hình, xem dữ liệu công ty và các việc cần làm.

Giá sách: cơ sở dữ liệu dự án

Giá sách cung cấp cách duyệt dự án ở chế độ chỉ đọc, phù hợp để nhanh chóng xem tài liệu và tài nguyên dự án.

Yêu cầu hệ thống

  • Node.js 20 trở lên: Điều kiện cần để chạy văn phòng.
  • Java 21 trở lên: Chỉ cần khi bật tính năng Minecraft.
  • Trình duyệt hỗ trợ WebGL: Chrome, Edge, Safari và Firefox đều được hỗ trợ.

macOS và Linux là các nền tảng được hỗ trợ chính. Windows hiện chỉ được hỗ trợ thử nghiệm. Mặc dù CI sẽ chạy các bài kiểm tra cài đặt, kiểm tra cú pháp và chế độ minh họa, tác giả chưa xác minh trên môi trường Windows thực tế; Minecraft cũng chưa được kiểm thử trên Windows.

Cài đặt và khởi động văn phòng minh họa

macOS và Linux

git clone https://github.com/jefferysha0627/agent-office-3d.git agent-office-3d
cd agent-office-3d
npm ci
npm start

Windows PowerShell

git clone https://github.com/jefferysha0627/agent-office-3d.git agent-office-3d
cd agent-office-3d
npm ci
npm start

Sau khi khởi động, chương trình sẽ mở http://127.0.0.1:4870/. Mặc định sử dụng chế độ demo, trạng thái nhân viên sẽ tự động luân phiên, vì vậy bạn không cần chuẩn bị hoặc kết nối Agent trước. Sau khi trải nghiệm xong, nhấn Ctrl+C trong terminal để dừng.

Cài đặt bằng AI Coding Agent

Nếu sử dụng các AI Coding Agent như Claude Code, Codex hoặc Cursor, bạn cũng có thể mở Agent trong thư mục dự án trước rồi dán lệnh sau:

Hãy đọc AGENTS.md của repo này, cài đặt Agent Office và mở bản demo Minecraft cho tôi.

Agent sẽ dựa trên AGENTS.md để chạy npm run doctor, hỗ trợ cài đặt và khởi động bản demo, đồng thời hỏi bạn có muốn kết nối Herdr hay không và muốn tùy chỉnh công ty cũng như nhân viên thế nào. Agent sẽ hỏi trước khi cài đặt phần mềm hệ thống như Node.js hoặc Java; đối với EULA Minecraft, chính bạn phải đọc và nhập yes, AI Agent sẽ không thay bạn chấp thuận. Người dùng Claude Code cũng có thể nhập /setup-office.

Cấu hình công ty, nhân viên và nguồn dữ liệu

Trước tiên, sao chép tệp cấu hình mẫu:

cp office.config.example.json office.config.json

Windows PowerShell có thể dùng:

Copy-Item office.config.example.json office.config.json

office.config.json sẽ không được đưa vào kiểm soát phiên bản. Nếu tệp không tồn tại, chương trình sẽ trực tiếp sử dụng cấu hình mẫu. Các trường thường dùng:

  • port: Cổng dịch vụ, mặc định là 4870.
  • openBrowser: Có tự động mở trình duyệt sau khi khởi động hay không.
  • company.name: Tên dùng trong thanh tiêu đề và biển hiệu công ty.
  • company.currency: Ký hiệu tiền tệ hiển thị trên bảng thông báo, chẳng hạn $ hoặc NT$.
  • company.logo và company.mark: Đường dẫn đến logo ngang và biểu tượng nhỏ của công ty.
  • owner.name, owner.title: Tên và chức danh của nhân vật tại bàn quản lý; bàn quản lý chỉ mang tính trang trí và không nhận trạng thái Agent.
  • cat.name: Tên chú mèo trong văn phòng.
  • staff[]: Danh sách nhân viên, gồm id, title và color của đồng phục, tối đa 8 người.
  • source.type: Nguồn trạng thái, có thể đặt là demo hoặc herdr.
  • data.board, data.projects, data.tasks: Vị trí dữ liệu bảng thông báo, dự án và nhiệm vụ.

staff[].id của nhân viên phải trùng với tên Agent trong nguồn trạng thái. Để tham khảo định dạng dữ liệu bảng thông báo và giá sách, hãy xem docs/board-format.md.

Kết nối Agent thực: chế độ Herdr

Herdr là công cụ ghép kênh terminal dành cho Coding Agent. Để kết nối Herdr, trước tiên hãy khởi động Agent bằng Herdr, sau đó chỉnh sửa cấu hình:

{
  "source": {
    "type": "herdr"
  },
  "staff": [
    {
      "id": "Tên Herdr Agent của bạn",
      "title": "Chức danh",
      "color": "#4f8cff"
    }
  ]
}

Sau đó chạy:

npm start

Văn phòng chỉ gọi các lệnh Herdr ở chế độ chỉ đọc là herdr agent list và herdr agent read. Danh sách cho phép tích hợp sẽ chặn các lệnh khác, vì vậy văn phòng sẽ không gửi phím thay bạn hoặc thay bạn xác nhận quyền.

Nếu muốn kết nối công cụ trạng thái khác, hãy thêm adapter trong lib/sources.js để trả về cùng định dạng danh sách nhân viên, bao gồm tên, trạng thái và vài dòng cuối của đầu ra terminal.

Bật bản demo Minecraft

Nếu chỉ muốn nhanh chóng xem nhân viên minh họa chơi Minecraft, hãy chạy:

npm run demo:minecraft

Tính năng này cần Node.js 20 trở lên và Java 21 trở lên. Lần chạy đầu tiên sẽ kiểm tra Java, yêu cầu bạn đọc và chấp nhận Minecraft EULA, tải tệp máy chủ phiên bản 1.21.4 từ danh sách phiên bản chính thức của Mojang và xác minh SHA-1. Việc tạo thế giới thường mất khoảng 1～2 phút.

Bạn phải tự nhập yes để ghi eula=true. Nhập nội dung khác sẽ hủy quy trình và không tải xuống bất kỳ tệp Mojang nào. Điều này là do EULA của phần mềm máy chủ Minecraft phải được chính người thực thi chấp thuận.

Để bật Minecraft trong chế độ văn phòng thông thường, trước tiên hãy chạy:

npm run minecraft:setup

Sau khi hoàn tất, đổi minecraft.enabled trong tệp cấu hình thành true, rồi chạy npm start. Máy chủ Minecraft sẽ liên kết với 127.0.0.1 và sử dụng danh sách cho phép để giới hạn kết nối. Khi nhân viên trở lại làm việc, bot tương ứng sẽ dừng hoạt động; bot chỉ chạy khi nhân viên nhàn rỗi và có người mở giao diện văn phòng.

Trang chủ bảng thông báo: dòng tiền và mục tiêu năm

Xem nhân viên trong trò chơi Minecraft

Nếu sở hữu Minecraft Java Edition, bạn có thể thêm tên người chơi của mình vào minecraft.guests:

{
  "minecraft": {
    "guests": ["YourName"]
  }
}

Bạn cũng có thể sử dụng biến môi trường:

MC_GUESTS=YourName npm run demo:minecraft

Windows PowerShell có thể dùng:

$env:MC_GUESTS="YourName"; npm run demo:minecraft
  1. Mở Minecraft Java Edition 1.21.4 trên cùng máy tính.
  2. Vào trò chơi nhiều người chơi, chọn kết nối trực tiếp và nhập localhost:25570.
  3. Sau khi vào, bạn sẽ tự động chuyển sang chế độ quan sát, có thể bay và đi xuyên tường mà không thay đổi thế giới.
  4. Nhấn phím số 1 hoặc dùng nút chuột giữa để mở menu quan sát, sau đó chọn nhân viên cần xem.

Tên người chơi trong cấu hình sẽ cùng bot được thêm vào danh sách cho phép; những người chơi khác không thể kết nối. Máy chủ chạy ở chế độ ngoại tuyến và chỉ lắng nghe trên máy cục bộ, không nên thay đổi địa chỉ liên kết hoặc mở máy chủ ra bên ngoài.

Lệnh phát triển và chẩn đoán

Dự án cung cấp một số lệnh phù hợp để kiểm tra môi trường và xác minh thay đổi:

npm run doctor  # Kiểm tra môi trường ở chế độ chỉ đọc
npm run check   # Kiểm tra cú pháp JavaScript và định dạng JSON
npm run smoke   # Kiểm thử smoke ở chế độ demo

npm run doctor trả về mã thoát 0 khi mọi mục đã sẵn sàng; trả về 2 khi Minecraft chưa sẵn sàng; và trả về 1 khi văn phòng không thể chạy. Thêm -- --json để xuất kết quả ở định dạng JSON.

Trong quá trình phát triển, bạn cũng có thể sử dụng tham số URL, chẳng hạn ?fast để tăng tốc hành động, ?idle=coffee để nhân viên nhàn rỗi thực hiện hành động指定, và ?cat=nap để điều chỉnh lịch trình của mèo. Tên hành động khả dụng được tham khảo trong public/behavior.js.

Lưu ý an toàn

  • Văn phòng sẽ đọc đầu ra terminal của Agent, trong đó có thể chứa mã nguồn, đường dẫn hoặc thông tin nhạy cảm.
  • Máy chủ chỉ liên kết với 127.0.0.1 và kiểm tra tiêu đề Host; không để lộ dịch vụ qua proxy ngược, đường hầm hoặc mạng công cộng.
  • Chức năng ghi duy nhất của văn phòng là đánh dấu các việc cần làm trên bảng thông báo; mọi trạng thái Agent và dữ liệu terminal khác đều chỉ ở chế độ đọc.
  • Giá sách chỉ đọc thư mục đã cấu hình, đồng thời ngăn chặn việc duyệt đường dẫn vượt thư mục và liên kết tượng trưng trỏ ra ngoài thư mục; tuy vậy, bạn vẫn không nên đặt mật khẩu hoặc token trong thư mục dự án.
  • Máy chủ Minecraft chỉ lắng nghe kết nối cục bộ và bật danh sách cho phép; không chuyển sang kết nối từ bên ngoài.

Lời kết

Agent Office 3D chuyển trạng thái Agent vốn phân tán trong terminal thành một văn phòng 3D dễ hiểu. Bạn có thể bắt đầu bằng npm start để trải nghiệm chế độ trình diễn, sau đó tùy chỉnh công ty và nhân viên qua office.config.json, rồi kết nối với Herdr để xem trạng thái Agent thực tế. Nếu muốn tăng tính tương tác, bạn có thể dùng npm run demo:minecraft để xem nhân viên nhàn rỗi hoạt động trong thế giới Minecraft cục bộ.

Xin nhớ rằng dự án này được cấp phép theo MIT License và không liên quan đến Mojang hay Microsoft; khi sử dụng Minecraft, bạn vẫn cần tự đọc và chấp nhận EULA của trò chơi.