AI教程

Agent Office 3D 教學：把 AI Coding Agent 變成 3D 辦公室員工

本教學將帶你安裝 Agent Office 3D、啟動示範辦公室、設定公司與員工資料，並進一步接上 Herdr 或選用 Minecraft，掌握 Agent 狀態、終端輸出與安全設定。

AI我搜编辑部2026年10月30日阅读约 10 分钟

Agent Office 3D 教學：把 AI Coding Agent 變成 3D 辦公室員工

Agent Office 3D 是什麼？

Agent Office 3D 是一個在本機執行的低多邊形 3D 辦公室，會把 AI Coding Agent 顯示成辦公室裡的員工。你可以一眼查看每位 Agent 正在工作、閒置、完成待命，或卡在需要確認的權限提示。

專案預設使用示範資料，不需要先連接任何 Agent。閒置員工會倒咖啡、喝水、使用跑步機、伸懶腰、打瞌睡或玩內建小遊戲；啟用 Minecraft 後，員工也能透過 Mineflayer 機器人進入本機世界。

畫面中的員工、任務、專案與金額都是示範資料，並非真實業務資訊。

主要功能

即時員工狀態：每位 Agent 有自己的座位、狀態燈與名牌；需要確認時會以紅色名牌與驚嘆號提示。
唯讀終端畫面：點選員工即可查看最近的終端輸出，但不能從辦公室介面傳送指令。
布告欄：展示年度目標、KPI、本週重點、現金流與待辦清單，待辦可以直接勾選。
書架專案資料庫：每本書對應一個專案資料夾，可閱讀 Markdown 文件與截圖。
任務清單：從右側查看任務資料夾裡的檔案與全文內容。
Minecraft 休息活動：閒置員工可使用各自的 Mineflayer 機器人挖礦、砍樹與蓋房子，並在辦公桌螢幕顯示第一人稱視角。

布告欄首頁：現金流與年度目標

點選布告欄後，會開啟全螢幕介面查看公司資料與待辦事項。

書架：專案資料庫

書架則提供唯讀的專案瀏覽方式，適合快速查看文件與專案素材。

環境需求

Node.js 20 以上：執行辦公室的必要條件。
Java 21 以上：只有啟用 Minecraft 功能時才需要。
支援 WebGL 的瀏覽器：Chrome、Edge、Safari 與 Firefox 均可。

macOS 與 Linux 是主要支援平台。Windows 目前屬於實驗性支援，雖然 CI 會執行安裝、語法檢查與示範模式測試，但作者未在實體 Windows 環境驗證，Minecraft 也尚未在 Windows 上實測。

安裝與啟動示範辦公室

macOS 與 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

啟動後，程式會開啟 http://127.0.0.1:4870/。預設使用 demo 模式，員工狀態會自動輪播，因此不需要先準備或連接 Agent。完成體驗後，在終端機按下 Ctrl+C 即可停止。

使用 AI Coding Agent 安裝

如果你使用 Claude Code、Codex 或 Cursor 等 AI Coding Agent，也可以先在專案資料夾中開啟它，再貼上以下指令：

請讀這個 repo 的 AGENTS.md，幫我把 Agent Office 裝好並打開麥塊示範。

Agent 會依照 AGENTS.md 執行 npm run doctor、協助安裝與啟動示範，並詢問是否要連接 Herdr 以及如何客製公司與員工。安裝 Node.js 或 Java 等系統軟體前會先詢問你；Minecraft EULA 則必須由你本人閱讀並輸入 yes，AI Agent 不會代為同意。Claude Code 使用者也可以輸入 /setup-office。

設定公司、員工與資料來源

先複製範例設定檔：

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

Windows PowerShell 可使用：

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

office.config.json 不會進入版本控制。若檔案不存在，程式會直接使用範例設定。常用欄位如下：

port：服務連接埠，預設為 4870。
openBrowser：啟動後是否自動開啟瀏覽器。
company.name：標題列與公司招牌使用的名稱。
company.currency：布告欄顯示的貨幣符號，例如 $ 或 NT$。
company.logo 與 company.mark：公司寬版 Logo 與小圖示的路徑。
owner.name、owner.title：主管桌人物的名稱與職稱；主管桌只是裝飾，不會接收 Agent 狀態。
cat.name：辦公室貓的名字。
staff[]：員工清單，包含 id、title 與制服 color，最多 8 位。
source.type：狀態來源，可設為 demo 或 herdr。
data.board、data.projects、data.tasks：布告欄、專案與任務資料的位置。

員工的 staff[].id 必須與狀態來源中的 Agent 名稱一致。相關的布告欄與書架資料格式，可參考 docs/board-format.md。

接上真實 Agent：Herdr 模式

Herdr 是一個供 Coding Agent 使用的終端機多工工具。要接上 Herdr，先用 Herdr 啟動你的 Agent，然後修改設定：

{
  "source": {
    "type": "herdr"
  },
  "staff": [
    {
      "id": "你的 Herdr Agent 名稱",
      "title": "職稱",
      "color": "#4f8cff"
    }
  ]
}

接著執行：

npm start

辦公室只會呼叫 Herdr 的唯讀指令 herdr agent list 與 herdr agent read。內建白名單會阻擋其他指令，因此辦公室不會替你傳送按鍵或代替你按下權限確認。

如果要接其他狀態工具，可以在 lib/sources.js 新增 adapter，讓它回傳相同格式的員工清單，包括名稱、狀態與終端機最後幾行輸出。

啟用 Minecraft 示範

若只想快速觀看示範員工玩 Minecraft，可執行：

npm run demo:minecraft

此功能需要 Node.js 20 以上與 Java 21 以上。第一次執行會進行 Java 檢查、要求你閱讀並接受 Minecraft EULA、從 Mojang 官方版本清單下載 1.21.4 伺服器檔案並驗證 SHA-1。世界通常需要約 1～2 分鐘建立。

你必須親自輸入 yes 才會寫入 eula=true。輸入其他內容會取消流程，也不會下載任何 Mojang 檔案。這是因為 Minecraft 伺服器軟體的 EULA 必須由實際執行者本人同意。

若要在一般辦公室模式中啟用 Minecraft，先執行：

npm run minecraft:setup

完成後，將設定檔中的 minecraft.enabled 改為 true，再執行 npm start。Minecraft 伺服器會綁定在 127.0.0.1，並使用白名單限制連線。當員工恢復工作時，對應的機器人會停止活動；只有員工閒置且有人開啟辦公室畫面時，機器人才會運作。

布告欄首頁：現金流與年度目標

從 Minecraft 遊戲內觀看員工

如果你擁有 Minecraft Java 版，可以把自己的玩家名稱加入 minecraft.guests：

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

也可以使用環境變數：

MC_GUESTS=YourName npm run demo:minecraft

Windows PowerShell 可使用：

$env:MC_GUESTS="YourName"; npm run demo:minecraft

在同一台電腦開啟 Minecraft Java 版 1.21.4。
進入多人遊戲，選擇直接連線，輸入 localhost:25570。
進入後會自動切換到觀察者模式，可以飛行與穿牆而不改變世界。
按數字鍵 1 或使用滑鼠中鍵開啟觀察者選單，再選擇員工觀看。

設定中的玩家名稱會與機器人一同加入白名單，其他玩家無法連入。伺服器採離線模式且只監聽本機，不應修改綁定位址或對外開放。

開發與診斷指令

專案提供幾個適合檢查環境與驗證修改的指令：

npm run doctor  # 唯讀環境檢查
npm run check   # JavaScript 語法與 JSON 格式檢查
npm run smoke   # 示範模式冒煙測試

npm run doctor 在所有項目就緒時回傳結束碼 0；Minecraft 尚未就緒時回傳 2；辦公室無法執行時回傳 1。加入 -- --json 可以輸出 JSON 格式結果。

開發時也能使用網址參數，例如 ?fast 加速動作、?idle=coffee 讓閒置員工執行指定動作，以及 ?cat=nap 調整貓的行程。可用動作名稱需參考 public/behavior.js。

安全注意事項

辦公室會讀取 Agent 的終端輸出，其中可能包含程式碼、路徑或敏感資訊。
伺服器只綁定 127.0.0.1，並檢查 Host 標頭；不要透過反向代理、通道或公開網路暴露服務。
辦公室唯一的寫入功能是勾選布告欄待辦事項，其他 Agent 狀態與終端資料皆為唯讀。
書架只會讀取設定的資料夾，並防止路徑穿越與跳出目錄的符號連結；仍不建議把密碼或 token 放在專案資料夾中。
Minecraft 伺服器只監聽本機並啟用白名單，請不要改成對外連線。

結語

Agent Office 3D 把原本分散在終端機中的 Agent 狀態，轉換成容易理解的 3D 辦公室。你可以先用 npm start 體驗示範模式，再透過 office.config.json 客製公司與員工，最後接上 Herdr 查看真實 Agent 狀態。若想增加互動性，則可用 npm run demo:minecraft 觀看閒置員工在本機 Minecraft 世界中活動。

請記住，這個專案以 MIT License 授權，且與 Mojang 或 Microsoft 無關；使用 Minecraft 時仍需自行閱讀並接受其 EULA。