npm run check背后的完整自动化测试循环:Agents Office AI代理办公室开发与构建流程解析
npm run check背后的完整自动化测试循环:Agents Office AI代理办公室开发与构建流程解析
Agents Office 是一个让 AI 代理在 3D 等距办公室里干活的本地应用,而它的每一次代码改动都跑在同一条自动化测试循环上:npm run check 一条命令,串联构建打包、离线逻辑自检、Playwright 无头浏览器冒烟测试和本地服务器接口检查,红色项修到变绿才算改完。本文将完整拆解这条循环的每个环节,带你看清 Agents Office 的开发与构建流程。
为什么要"一键体检":改动 → 运行 → 修红 → 重复
Agents Office 的官方口号很简单:change something, run it, fix what is red, repeat(改点什么,跑一遍,修掉红的,再来)。这句话就写在 check.mjs 的注释里,也是整个 Beta 版本赖以构建的节奏。
package.json 中只注册了与这条循环直接相关的两条命令:
npm run check # 构建 + 离线冒烟 + 服务器冒烟,不调用 Claude
npm run check:live # 额外让 Claude 真实跑一遍任务、例行公事和对话
每一步检查都打印 ✓ 或 ✗ 加上一句人话原因;只要有任何失败,进程退出码就是 1。项目文档 CLAUDE.md 里把它定为铁律:"run it after any change to code; fix what is red"。下面按执行顺序拆解四大阶段。
阶段一:构建打包,先保证"办公室能打开"
构建入口是 build.mjs,它做两件事:
- 烘焙 Brain 图谱:先调用 graph-build.mjs 扫描笔记文件夹里的
<a href="https://link.gitcode.com/i/b9735d56554b121bf230a67e0b051d35" target="_blank">[wiki links]],把图谱数据烘焙进 [src/braingraph.js,这样前端打开就是"活的"笔记关系网; - esbuild 单文件打包:把 src/main.js 连同 three.js 打成压缩 IIFE,注入 src/shell.html 的
<!--APP-->占位符,产出 dist/command-centre-v2.html——一个双击就能运行的自包含页面。
npm run check 并不信任构建脚本"说自己成功了",而是独立复核(check.mjs):
- 产物必须大于 500KB,且包含
AGENTS OFFICE字样,防止打空包; - 图谱必须有节点和连线,且具备楼层布局,防止 Brain 图空白。
阶段二:离线逻辑自检,把业务规则当"单元测试"
这是循环里最密集的一环,全部在本地完成、不消耗任何 Claude 额度。检查方式非常直接:import 真实模块,喂进去精心构造的正常与异常输入,断言输出。临时文件一律放进 os.tmpdir() 并在用完后清理,不污染工作区。
主要检查组一览(对应源码见 check.mjs):
| 检查组 | 验证什么 | 对应模块 |
|---|---|---|
| 📋 花名册 roster | 35 名代理齐全;改 id/department/lead 会被拒绝而不是静默生效;超长的 brief 截断到 2000 字符并给出警告 |
roster.mjs + office.agents.json |
| 🛠 技能 skills | 自带技能能加载并绑定到正确代理;坏技能(无效绑定、缺文件)被拒绝并逐条报告;brain 中的同名技能覆盖自带版本 | skills.mjs |
| 📝 教训 lessons | revise: 纠正被记录,常设规则(standing rule)在提示词中原样返回 |
learn.mjs |
| 🎤 部门访谈 | 对部门主管说 "set up",五问之后把 brief 和技能写入 brain,越界代理被点名拒绝 | onboard.mjs |
| 🔌 连接器 | claude mcp list 输出被正确解析:连接、需鉴权、未识别三类状态 |
mcp.mjs |
| ⏱ 例行公事 routines | "every weekday at 8am…" 等自然语言变成时间表;缺时间会反问、"morning" 默认 08:00;错过两小时补跑一次并标记 LATE;Marketing 部门建例行会被拒绝 | routines.mjs + src/when.js |
| 🧮 模型与用量 | Sonnet/Opus/Fable 三模型名、五级 effort 的四级优先级(task > routine > agent > office)、CLI 参数正确;用量仪表解析 Claude 的百分比与重置时间,断线时退回办公室自己的 5 小时窗口计数 | src/models.js + usage.mjs |
| 👥 团队任务 | "as a team" 意图识别不误伤普通句子;计划拆分的去重、人数上限、单人任务回落到主管 | teams.mjs |
| 🌐 浏览器 | tools.browser 开 → --chrome,关 → --no-chrome;deny 名单能把 Chrome 挡在代理手外 |
mcp.mjs |
| 📅 日历 | 例行可从某日期开始,向后逐日投影;过去的开始日期被忽略 | src/when.js |
| ⚙️ 配置默认值 | browser 与 teams 默认开启,团队上限 4(config.mjs 读取 office.config.json) | config.mjs |
这些用例的共同点是断言"拒绝"和断言"接受"同样重要:一个坏花名册、一个坏技能、一条越权例行,被响亮地拒绝,比被悄悄吞掉重要得多。
阶段三:Playwright 无头浏览器冒烟测试
打包产物必须真的能渲染。检查脚本优先 import('playwright'),退回 playwright-core(package.json 的 devDependencies 里就是它),两者都没有时只报告一条 ✗ 提示安装,而不是让整个循环崩溃(check.mjs)。
随后启动 Chromium(带 swiftshader 软件渲染参数,失败则改用本机 Chrome 通道),以 1512×900 视口直接打开 file:// 下的 dist/command-centre-v2.html,并全程收集 pageerror 和控制台 error。接下来是一串模拟真人操作的断言:
- 35 名代理全部"坐"在工位上,六个部门卡片 + Brain 标签齐全;
- 在任务栏用普通话添加一个 demo 任务,能看到 "Added" 提示和新任务行;
- 输入 "as a team, …",主管接旗、件卡落到各工位、TEAM/PIECE 徽章正确;
- 输入例行语句,任务落进 SCHEDULED,看板(B)出现 SCHEDULED 列,RUN NOW 能触发任务;
- 日历(P)打开后,月视图格数正确、例行任务逐日投影、点击某一天可以排任务、Marketing 例行被拒;
- G 打开 Brain 图谱、审批流进入面板、跑完一整轮后仍然零页面错误。
阶段四:本地服务器接口冒烟测试
前端页面之外,Agents Office 的"心脏"是本地服务器 serve.mjs。测试脚本会挑一个 4600–4899 之间的随机端口拉起它(check.mjs),轮询 /api/health 最多 10 秒,然后像真实用户一样打一遍 API:
/返回的页面包含办公室本体;/api/brain有活图谱;/api/health带上 35 人花名册、默认模型 sonnet、effort 五档列表;/api/mcp如实列出这台机器自己的连接器;/api/skills、/api/routines、/api/lessons结构完整;- 拒绝类检查:给 Marketing 建例行 → 400 且回一句 "later release";缺时间 → 400 且
needsTime;排到过去时间的任务 → 400 且提示 "passed";空任务 → 400。
这一阶段结束时服务器立即被 kill,不留后台进程。
阶段五(可选):CHECK_LIVE=1 的真实 Claude 运行
npm run check:live 会追加一组花真钱的检查:让 Claude 真实路由一个任务并交付、把笔记写进 brain;一条"每 2 分钟"例行准时开火并落地;指定 Opus 的任务确认跑在 Opus 上;提前 75 秒的定时任务准点开火;一个团队任务多工位并行、主管汇总;甚至让代理驱动你本机 Chrome 打开 example.com 并读回标题(check.mjs)。因为消耗你的 Claude 套餐用量,日常开发跑 npm run check 就够,发版前才值得来一次 live。
汇总与退出码:红色就是红灯
循环最后输出总账:✓ 34/34 checks passed 这样的一行,失败则列出每一项 ✗ 的名称,process.exit(1)(check.mjs)。这个退出码让它可以无缝接进任何脚本或钩子——红了,就别合。
它还与发布流程咬合:scripts/release.mjs 打公网包时只用白名单文件、强制从示例 brain 重建图谱,并且会核对 serve.mjs 的每一个 import 都在发布清单里——这条校验正是被 3.2.0-beta.2 漏发 teams.mjs 的教训逼出来的(见 CHANGELOG.md)。而新机器上的一键安装 setup 在收尾时也会拉起一次 serve.mjs 并 curl /api/health,和冒烟测试同源。
自己跑一遍:最快上手步骤
环境要求:Node.js 20+、git、已登录的 Claude Code(README.md "What you need")。
git clone https://gitcode.com/gh_mirrors/ag/agents-office
cd agents-office
npm install
npm run check # 完整离线循环:构建 + 浏览器/服务器冒烟
npm run check:live # 追加真实 Claude 运行(消耗套餐用量)
小贴士:
- 没装 Playwright 时,浏览器冒烟会跳过并打印
npm i -D playwright-core(复用你的 Chrome); - 检查完全离线,不需要 Claude 登录即可看到构建、roster、skills、routines 等大部分 ✓;
- 输出全是人话:
✗ roster: agents: 33这种一行定位,不需要翻日志。
关键文件速查
| 文件 | 在循环中的角色 |
|---|---|
| check.mjs | 测试循环本体:构建复核、离线断言、双冒烟、live 追加 |
| build.mjs | esbuild 单文件打包 + Brain 图谱烘焙 |
| serve.mjs | 被冒烟的本地服务器:路由、交付、聊天、活图谱 |
| config.mjs | 配置合并与默认值,被"配置默认值"检查盯住 |
| roster.mjs · office.agents.json | 35 名代理的加载与校验 |
| scripts/release.mjs | 白名单组装发布包,防漏文件 |
一条命令,四条战线(打包、逻辑、浏览器、服务器),外加随时可开启的真实运行——这就是 npm run check 背后的完整自动化测试循环,也是 Agents Office 这个 AI 代理办公室在 Beta 阶段保持"红就修、绿才走"节奏的底气所在。

