在共享 3D 工作空间中设置 Agent Office 并管理 AI 编码工作者

Agent Office 的功能

Agent Office 将 AI 辅助的软件开发转变为一个共享的卡通 3D 办公室。每个 GitHub 仓库都会成为一个独立楼层，包含办公桌、编码工作者、终端、议题和拉取请求看板、任务队列、服务以及项目专属设置。

你可以在办公桌前安排一名 Claude Code、OpenCode 或 Codex 工作者，在桌上的笔记本电脑中查看其实时终端，并与队友共同打开同一个终端。工作者可以在主检出目录或隔离的 Git worktree 中运行，因此能够并行执行多个任务，而无需共享工作目录。

该应用还提供多人移动、语音、屏幕共享、持久化聊天和终端历史记录、工作者通知、机器监控、项目导航、GitHub 议题和拉取请求工作流，以及结构化的多智能体会议。

核心概念

每个仓库对应一个楼层

Agent Office 首次启动时会进入电梯，并要求你选择已通过身份验证的 GitHub CLI 账户可见的仓库。你也可以输入格式为 owner/name 的仓库。

仓库会克隆到：

~/agent-office/<owner>/<repo>

每个项目楼层都有独立的工作者、办公桌、看板、队列、服务、图片和颜色。一个楼层上的人员只能看到并听到该楼层上的其他人。

办公桌前的工作者

空办公桌可以安排 Claude Code、OpenCode、Codex 或共享登录 Shell。已占用的办公桌会显示工作者的实时终端和状态。智能体钩子或插件会报告工作者是在工作、等待输入还是已完成。

GitHub 看板和任务自动化

议题看板会将议题分为开放、进行中和已关闭三组。拉取请求看板会显示草稿、审查、批准、合并、关闭、CI 状态和差异大小。任务可以直接交给工作者，也可以添加到持久化队列中自动执行。

前置条件和安装

提供的 README 介绍了如何使用 Agent Office，但不包含包管理器安装命令。请按照仓库的分发或构建说明安装项目，然后确保 agent-office 可执行文件可在 Shell 中使用。

启动前，请对服务器应使用的 GitHub CLI 账户进行身份验证：

gh auth status

如果尚未完成身份验证，请完成 GitHub CLI 登录流程：

gh auth login

所选账户决定 Agent Office 能发现哪些仓库，以及执行发布议题评论等 GitHub 操作时使用的身份。

如果你打算雇用某种类型的工作者，还应在机器上配置至少一个受支持的编码智能体 CLI。Agent Office 支持 Claude Code、OpenCode 和 Codex 工作者。

启动你的第一个办公室

使用以下命令启动应用：

agent-office

1. 使用应用显示的地址，在浏览器中打开 Agent Office 界面。
2. 使用电梯中的项目选择器，选择可通过 gh 使用的仓库，或输入完整的 owner/name。
3. 等待 Agent Office 将仓库克隆到 ~/agent-office 下。
4. 选择角色的肤色、发型、发色和衬衫。
5. 进入新的项目楼层。

稍后若要添加或访问其他项目，请走到北墙的电梯处并按 E。你也可以点击左上角的项目名称，然后选择另一个楼层。

可选启动配置

README 记录了几项实用的服务器选项。例如：

agent-office --city Berlin --max-workers 4

--city Berlin 选项会让日出、日落和天气遵循柏林。--max-workers 4 选项会限制所有楼层同时运行的工作者总数。共享 Shell 和看板智能体也计入此限制。

团队通知可以连接到 Slack 或 Discord 的传入 Webhook：

agent-office --webhook <incoming-webhook-url>

通过 --budget 和 --budget-pause 可以使用预算警告和暂停雇用功能。这些控制只使用已跟踪的 Claude Code 支出。它们无法直接限制 OpenCode 或 Codex 的支出，但一旦达到已跟踪的雇用阈值，所有新工作者都会暂停。

了解基本控制

• WASD：在楼层中移动。
• 空格：跳跃。
• 拖动鼠标：环绕旋转摄像机。
• E：与办公桌、看板、电梯、座位、梯子及其他办公室物体互动。
• Tab：打开主菜单。
• T：阅读最近的聊天内容。
• P：在空办公桌雇用工作者前编写任务。
• B：在空办公桌打开共享登录 Shell。
• C：查看已占用办公桌上的更改。
• N：访问等待时间最长的工作者。
• R：恢复已退出的受支持工作者会话。
• /：搜索聊天记录和工作者终端历史记录。

主菜单会打开工作者、人员、议题、拉取请求、队列、服务、搜索、语音、屏幕共享、设置及其他状态面板。常用项目可以固定到顶栏，针对浏览器的布局选择也会被保留。

雇用你的第一个编码工作者

1. 走到一张空桌前。
2. 按下E。
3. 选择 Claude Code、OpenCode 或 Codex。
4. 输入你希望工作人员完成的任务。
5. 如有需要，启用独立 Git 工作树。
6. 确认雇用，然后在笔记本电脑上查看工作人员的终端出现。

当你想在选择代理之前编写任务时，可以在空桌前按P。Agent Office 提供 16 张桌子。如果桌子都已被占用，临时懒人沙发工作站最多还可容纳 12 名工作人员。

使用隔离工作树处理并行任务

当多个工作人员可能同时编辑仓库时，请启用独立 Git 工作树。Agent Office 会创建一个 office/<name> 分支，并将其检出内容放在：

.agent-office/worktrees/

这样可以避免并行工作人员修改同一份检出内容。让使用工作树的工作人员回家时，你可以保留分支和工作树、仅删除工作树，或同时删除两者。Agent Office 会提示未提交的更改，以及尚未推送到远程仓库的提交。

确认安全后，要清理保留的工作树，请运行：

agent-office prune

在工作人员终端中打开并协作

在已占用的桌前按E，即可通过 WebSockets 打开其真实的 PTY 终端。多名协作者可以同时在会话中输入，后来加入的人也能看到已有的滚动记录。

终端标题栏会显示当前打开终端的人员。其他人输入文字时，标题栏还会显示输入提示，降低协作者互相覆盖输入内容的可能性。

工作人员终端及其最近 3,000 行内容都会被保存。Agent 进程独立于主服务器运行，因此服务器重新加载或进程重启后，工作人员仍可继续工作。服务器恢复后，已打开的终端会自动重新连接。

了解工作人员的实时状态

工作人员的天线和动画会显示其状态。工作人员可能显示为工作中、需要输入或已完成。动画还会反映读取文件、编辑代码、运行测试、搜索网络或连续失败等操作。

当工作人员需要帮助或完成任务时，Agent Office 会播放通知，并将其计入等待数量。按N可前往等待时间最长的工作人员。反复按N可循环浏览等待中的工作人员。

查看更改并打开拉取请求

在已占用的桌前按C，或从终端中选择更改。更改视图会显示已修改的文件，以及相对于办公室打开时所在分支的持续刷新的差异。

在此视图中，你可以：

• 检查已更改的文件及其差异。
• 提交工作人员的更改。
• 放弃不需要的更改。
• 推送分支。
• 打开拉取请求。

对于使用隔离工作树的工作人员，工作准备就绪后，在桌前按O。Agent Office 会推送分支，并根据任务草拟标题和描述后打开拉取请求。源自 GitHub issue 的工作会包含 Closes #n 引用。再次按O可查看拉取请求。

处理 GitHub Issues

Issues 面板会显示开放、进行中和已关闭的 issue。选择一个 issue，即可阅读其描述和评论、发表评论、将其发送给工作人员，或将其添加到任务队列。

你也可以亲自拿起 issue 卡片：

1. 指向 issue 便签并按E，或在 issue 窗口中使用拿起它。
2. 将卡片带到空桌前，以雇用新的工作人员。
3. 将卡片带到已占用的桌前，交给该工作人员。
4. 将卡片带到任务队列中，将其排队。
5. 如果想将卡片放回面板，请按Q。

工作人员收到 issue 卡片后，Agent Office 会通过 GitHub 分配该 issue，并将其移至进行中状态。Issue 也可以标记为已完成或不再计划处理，并可选择添加评论。

查看并合并拉取请求

PR 面板会将拉取请求分为草稿、审核中、已批准、已合并和已关闭状态。面板还会报告 CI 状态和差异规模。

打开拉取请求并选择已更改的文件，即可检查其差异。文件可以按文件夹树或平面列表显示。审核评论会显示在其对应的代码行下方。

• 按V将文件标记为已审核。
• 使用J和K在文件之间移动。
• 选择审核，将 PR 交给工作人员。
• 选择修复评论并合并，让工作人员处理反馈、通过检查并完成合并。
• 如果分支与其基分支存在冲突，请使用修复冲突并合并。

Agent Office 可以压缩合并、普通合并或变基拉取请求。它还可以请求 GitHub 在必需检查通过后自动合并。拉取请求合并后，办公室会敲响合并锣、撒下彩带，并为活跃的工作人员播放动画。

使用任务队列自动处理工作

你可以从北墙的白板或主菜单访问任务队列。添加自由文本任务或将 issue 排入队列，然后让 Agent Office 自动分配工作。

当有空桌且队列的并发设置允许再添加一名工作人员时，下一个任务会获得一名使用隔离 Git 工作树的新工作人员。队列默认并发数为 3 名工作人员。将同时工作的工作人员数设为零即可暂停队列。

排队的问题工作会在 GitHub 上分配，生成的拉取请求出现后会关联到队列看板。已完成工作的工位会保留在原处供检查，直到队列需要该工位执行其他任务。队列状态会在重启后保留。

使用专用看板代理

问题看板、PR 看板和任务队列各有一个亭式代理。走到亭式终端前，按下 E 为它输入提示。

• 问题代理：通过 gh 查找、创建、分类、添加标签并关闭问题。
• PR 代理：总结、审查、评论并合并拉取请求。
• 队列代理：将请求转换为一个或多个排队任务，报告队列状态并移除任务。

队列代理不会自行实施代码更改。它会创建队列任务，让新的工作代理在隔离的工作树中完成工作。在亭式终端按 O 可检查其终端，按 X 可让代理离开。

运行结构化多代理会议

会议室支持由两到五名工作代理组成的小组。你可以从会议室、主菜单、问题或拉取请求启动会议。每位参与者都有一个可重命名的角色。

可用的会议模式包括：

• 辩论：工作代理提出方案、相互批评，并作出最终决定。
• 负责人和团队：负责人拆分任务、分派各部分工作，并整合结果。
• Map-reduce：映射代理分别处理文件、模块、问题或其他部分，然后由一名工作代理汇总发现。
• 红队 / 蓝队：红队工作代理识别错误、安全风险和边界情况，蓝队工作代理处理有效发现。
• 评审小组：评审者从不同角度检查拉取请求，然后由负责人整合并发布评审结果。

每次会议都会声明一个输出文件，并在自己的分支上运行。输出准备就绪后，使用 Open PR 创建拉取请求。会议设有轮数限制和整个桌面的令牌预算，防止会议无限进行。

监控服务、资源和开支

开发服务

当工作代理启动诸如 npm run dev、预览构建或 python -m http.server 这样的 Web 服务器后，几秒内就会显示在服务看板上。每个条目都会标明工作代理、分支和页面标题。选中条目后，会复制一条命令，用于从你自己的计算机打开该服务器。

机器压力和工作代理限制

西墙上的监视器显示当前 CPU 和内存使用率、五分钟历史记录以及正在运行的工作代理数量。如果内存达到 90%，或 CPU 持续以 90% 的负载运行约半分钟，Agent Office 会警告机器正承受压力。

服务器级别的 --max-workers 值提供硬性上限。管理员可以在设置中降低当前限制，但不能将其提高到启动值以上。容量已满时，手动雇用会被拒绝并显示原因，而排队任务会等待空位。

使用情况和成本报告

Claude Code 工作代理会报告已跟踪的会话成本和令牌数。OpenCode 会报告令牌数以及模型和提供商的估算值，并在可用时包含子会话。Codex 会报告记录的根会话令牌数，包括缓存和推理明细，但不报告成本或 API 调用次数。

从菜单启用 Claude 限制，即可显示 Claude 计划在五小时会话中的使用量、每周配额以及任何特定模型的每周限制。当 Claude 使用 API 密钥而非计划时，此面板会隐藏，并且不包含 OpenCode 或 Codex 的数据。

高级协作技巧

• 默认使用工作树进行并发编码：这样可以避免工作代理共享未提交的文件或互相修改分支。
• 将规划与实施分开：使用问题代理和队列代理组织工作，然后让新的工作树工作代理进行代码更改。
• 让队列并发数低于机器限制：为交互式工作代理、共享 Shell 和看板代理留出容量。
• 使用桌面通知：当办公室标签页处于后台时，通知可以直接带你前往需要输入或已经完成工作的工作代理。
• 配置团队 Webhook：Slack 或 Discord 通知可以帮助团队发现长时间无人处理的工作代理。
• 重新打开会话前先搜索：按 / 搜索聊天记录和所有保留的终端输出，包括重启前的历史记录。
• 使用共享 Shell 处理支持工作：需要用于测试、Git 命令或开发服务器的协作终端时，在空工位按 B，无需雇用 AI 工作代理。
• 让工作代理离开前先检查：查看终端历史记录和更改，然后决定是否保留或移除该工作代理的分支和工作树。

结语

Agent Office 将 AI 编码代理、Git 工作树、共享终端、GitHub 看板、队列、通知和多人协作整合在一个空间化界面中。先从一个项目楼层和一个隔离的工作代理开始，随着团队逐渐熟悉并行的 AI 辅助开发，再引入排队任务、看板代理、拉取请求工作流和结构化会议。