AgentSystemLabs/agent-office · 上手攻略

  • 仓库：AgentSystemLabs/agent-office
  • 链接：https://github.com/AgentSystemLabs/agent-office
  • 分类：AI Agent · 开发环境与团队协作
  • 作者：Tom
  • 更新：2026-10-02

§1 是什么

agent-office 是一个共享 3D 虚拟办公室，把你的代码团队（包括 Claude Code、Codex、OpenCode、Grok、Muse、DeepSeek Harness、Pi、Cursor 等 AI 编程 Agent）放进一个卡通风格的 3D 世界里。每个 GitHub 仓库对应一栋楼的一层，AI Worker 坐在工位上，实时显示各自的终端——你和团队成员可以随时走过去、旁观打字、或者直接接手操作。

它既是一个多 Agent 可视化管理界面，也是一个团队实时协作空间，内置语音、聊天、白板、GitHub Issues 和 PR 看板。

⚠️ 注意：项目处于活跃开发中（WIP），作者声明这是为自己个人工作流打造的，版本间可能有 breaking change，不建议在生产环境直接依赖。

§2 解决什么问题

痛点：当你同时运行多个 AI Coding Agent（Claude Code、Cursor 等）时，缺乏统一界面来： - 看到每个 Agent 在做什么（终端状态） - 在多个项目/仓库之间快速切换 - 给某个 Agent 分配 GitHub Issue 或 PR 任务 - 让多个 Agent 协作处理跨仓库任务 - 实时与同事讨论某个 Agent 的进度

解决方案：用 3D 办公室的隐喻，把所有 Agent 和项目映射为「楼层」和「工位」，让协作像走进真实办公室一样自然。

§3 快速安装

系统依赖

  • Node.js 20+
  • git
  • GitHub CLI（需提前登录：gh auth login）
  • 至少一个 Agent CLI（Claude Code、Codex、OpenCode、Grok、Muse、DeepSeek Harness、Pi 或 Cursor CLI），且已用运行 office 的用户账号登录

一键安装（Linux/macOS）

curl -fsSL https://raw.githubusercontent.com/AgentSystemLabs/agent-office/main/install.sh | bash

一键安装（Windows PowerShell）

irm https://raw.githubusercontent.com/AgentSystemLabs/agent-office/main/install.ps1 | iex

安装脚本会将 agent-office 命令加入 PATH，后续直接运行 agent-office 即可。重复运行安装脚本可更新版本。

从源码运行

git clone https://github.com/AgentSystemLabs/agent-office && cd agent-office
npm install          # 同时构建客户端和服务端
npm install -g .    # 全局安装，put agent-office on PATH
agent-office

§4 核心用法

首次启动引导

首次运行 agent-office 会自动进入交互式引导（在终端里完成）：

  1. 项目存放位置：建议已有的代码目录（如 ~/Workspace、~/code），或默认 ~/agent-office
  2. GitHub 登录：若 gh 未认证，脚本会帮你跑 gh auth login
  3. 第一个项目：从 gh 能看到的仓库列表里选一个编号，或直接输入 owner/name

然后 office 在浏览器打开，用一次性链接或终端里显示的密码登录。

常用命令选项

agent-office ~/code/my-project   # 用已有项目作为第一层楼
agent-office --password 'correct horse'   # 自定义登录密码
agent-office --port 4700         # 指定端口
agent-office --agent pi          # 默认 Agent 类型（claude/codex/opencode/grok/muse/dsh/pi/cursor-agent）
agent-office --no-open           # 不自动打开浏览器，只打印登录链接
agent-office setup              # 重新运行首次引导（office 需停止）

常用操作快捷键

操作 说明
E 与物体交互（坐工位、开咖啡机等）
WASD 移动
Space 跳跃
N 直接跳转到等待你的 Worker
T 打开聊天
B 在空工位打开共享登录 shell
O 给 Worktree Worker 推送 PR
Ctrl+Space / 🎤 语音输入（对着麦克风说话，自动打字）

3D 办公室结构

  • 楼层 = GitHub 仓库：每层有独立的工位、Worker、Issue 看板、PR 看板、任务队列
  • 电梯：切换不同楼层（仓库）
  • 工位：每个 Worker 有一台笔记本电脑，实时显示其终端
  • 红色信标：Worker 停下来等你响应时亮起 + 声音警报
  • 跳跃庆祝：Worker 完成任务时跳跃 + 叮声
  • /lite：手机或低性能机器的 2D 版本，每位 Worker 及其等待状态一目了然

GitHub 看板

  • Issue 和 PR 挂在软木板墙上
  • 把 Issue 交给 Worker 处理，任务自动入队
  • Worker 凭自己的 git worktree 开分支、提交 PR
  • 支持跨仓库任务：Worker 同时持有多个项目的工作树

语音和屏幕共享

  • 语音：按住 Ctrl+Space 或点击工位/输入框的 🎤 说话
  • 屏幕共享：在 lounge 区打开 TV 共享屏幕
  • 白板：共享协作白板

§5 典型适用场景

  1. 多 Agent 并行开发管理：同时跑 Claude Code（做前端）、Codex（做后端）、Cursor（做测试），在一个 3D 办公室看到所有人状态
  2. AI + 人类混合团队协作：人类工程师走进某个 Worker 工位，接手 Agent 做不到的复杂决策
  3. 跨仓库任务分配：一个任务涉及 frontend、backend、infra 三个仓库，Worker 自动持有三个工作树并开关联 PR
  4. 演示与 Code Review：在办公室的大屏/电视 上共享屏幕，团队成员一起看某个 Agent 的工作过程
  5. 远程团队沉浸式 standup：通过 3D 移动、语音、聊天进行更像物理空间的异步 standup

§6 坑与注意

⚠️ 以下为高风险点，务必在上手前阅读：

  1. Breaking changes 频繁：作者明确说「Expect breaking changes between releases」，keys 位置、界面布局、API 可能在版本间变化。生产环境使用前务必 fork 固定版本。

  2. Node.js 20+ 严格：低于 20 可能运行不正常，PowerShell 用户注意 Node 版本。

  3. gh auth 未登录则无法克隆仓库：gh auth login 必须在 office 运行前完成，否则楼层克隆会直接失败。

  4. Worktree 隔离边界：启用独立 git worktree 的 Worker 在分支删除时（别人 force-push 后）会进入「lost」状态等待重建，需运行 worker.rebuild。

  5. 3D 性能要求：3D 渲染需要 GPU，低配置机器建议使用 /lite 2D 版本。

  6. 语音功能依赖浏览器麦克风权限：Chrome/Edge 推荐，Firefox 可能存在 WebRTC 兼容问题。

  7. 数据安全：所有 Agent 的 hook server 绑定在 127.0.0.1（loopback），不会暴露到外网，但通过 tunnel 功能访问本地服务时需注意端口安全。

  8. 多人模式下数据隔离：每个楼层的数据（Worker 状态、队列）是独立的，但共享办公室的语音/聊天数据需要正确配置权限。

  9. Windows 支持：PowerShell 安装脚本存在，但部分 Node 原生模块在 Windows 上可能需要额外编译依赖。

§7 与同类对比

方案 定位 优势 劣势
agent-office 3D 沉浸式多 Agent 可视化 直观、实时终端、强协作 资源消耗大、WIP、仅支持特定 Agent CLI
Cursor 内置 Agent 面板 单项目 / 单 Agent 集成度高、稳定 不支持多仓库、不适合团队
Claude Code (claude) 单用户 CLI 成熟、稳定 无可视化、多 Agent 管理靠脚本
Devika 浏览器 UI 的 Agent 开源、多 Agent 协作 非 3D、界面较传统
OpenDevin Browser-based AI Developer 成熟度高、社区活跃 无 3D、无实时终端镜像

核心差异：agent-office 是目前唯一把多 Agent 工作流做进 3D 可视化空间的项目，适合想要「看到」团队在干什么的队长/lead 开发者。

§8 一句话推荐结论

如果你同时跑多个 AI Coding Agent 并且需要可视化团队协作，agent-office 提供了一种独特的沉浸式解法；但因其处于 WIP 阶段且资源消耗不小，建议先用 /lite 模式或固定版本试用，核心项目仍慎用。