在自己的电脑上，
跑一间会动的 像素办公室

一行代码都不用复制。你唯一要复制的，是交给 AI 工具的工单（提示词）。

1 · 我能用它做什么？

跟着做，你能在自己电脑上运行一个有角色来回走动的像素办公室，还能改颜色、人数、房间名和家具。把设计素材想成装修材料箱，Claude Code 想成装修师傅，提示词想成交给师傅的工单。遇到问题也不用改代码，把第 6 节的万能工单原样交出去即可。

2 · 3 分钟，用比喻理解

设计素材 = 装了地板、墙壁、桌子、角色的材料箱。Claude Code 等 AI 编程工具 = 帮你组装修整的装修师傅。提示词 = 交给师傅的工单，写「请把地板换成薄荷色」这样的目标就行。终端 = 和师傅沟通的窗口；浏览器地址 = 完工后的门牌地址。记住一件事：复制的是工单，不是代码。

3 · 两样准备材料

① 获取材料箱

1. 点击 直接下载 ZIP；想先看仓库可打开 GitHub 页面。
2. 若没自动下载，在 GitHub 页点绿色 Code → Download ZIP。
3. 找到 ZIP，全部解压，新文件夹就是材料箱。

解压后若直接显示 package.json 和 src 文件夹，就是正确的材料箱；若只看到一个同名文件夹，请再打开一层。

② 请来装修师傅（三选一）

• Claude Code：本指南默认选择
• Codex：如果你在用付费 ChatGPT 套餐
• Antigravity：如果你想免费开始

4 · 第一次运行（工单 #1）

确认解压文件夹处于打开状态（里面直接有 package.json 和 src）。把下面工单整段复制粘贴给 AI 工具并发送。

当前打开的文件夹是一个像素办公室设计演示。请在浏览器中运行这个演示。如果电脑上没有 Node.js 之类的运行工具，请先帮我安装，并用简单的话逐步告诉我进展。全部完成后，请告诉我要打开的浏览器地址。

5 · 五张装修工单

每次复制交出一张，确认画面变化后再下一张（看不到变化就刷新一次浏览器）。

请将屏幕上显示的公司名称改为 [我的公司名称]。请不要更改公司名称以外的设置和画面。

请把办公室地板颜色改成比现在更亮的薄荷色。只能修改 src/game/office-world.ts 文件中 OFFICE_THEMES 里的地板（floor）颜色。

请把屏幕上显示的员工人数增加到 35 人。

请把简报室的名称改为"作战会议室"。如果需要五种语言的名称，也请自然地翻译并补全其他语言。

请在办公室里看起来比较空的位置再放两盆植物。

效果和想象不同，就继续说「请把薄荷色再调浅一点」——不必重写工单，像现场跟师傅说话一样，说具体点就行。

6 · 遇到问题时（万能工单）

错误消息只是一张检查记录，不用害怕。把方括号内容替换成实际错误消息再发送。

我会把屏幕上的错误消息原样粘贴过来：[在这里粘贴错误消息]。请找出原因并修好，然后用一句话告诉我问题是什么。

没有错误消息，但目前是[没有显示地址 / 画面一片空白 / 看起来卡住了]的状态。请查明原因并修复，修好后请用简单易懂的话告诉我如何确认问题已经正确解决。

很难复制错误就截屏发送，说「帮我修复这个画面中的错误」，完成后刷新浏览器确认。

7 · 完成确认

角色能走动，且公司名 / 颜色 / 人数 / 房间名中至少有一项变了，本次练习就完成了。

给至少用过一次 Claude Code / Cursor 的朋友——跳过比喻，直接开跑。

5 分钟开始

1. 获取仓库：从 GitHub git clone 或 Download ZIP。
2. 用 AI 编程工具打开文件夹，粘贴下面内容：

先运行 npm install，再用 npm run dev 启动演示，然后告诉我要打开的地址。

想自己来就在终端跑 npm install && npm run dev（Node 22+）。浏览器打开显示地址（默认 http://localhost:5173），看到角色走动即成功。

10 分钟自定义

UI 颜色 / 房间名 / 员工数据在 src/company.config.ts；地板墙壁等主题预设色在 src/game/office-world.ts 的 OFFICE_THEMES。

在 src/game/office-world.ts 的 OFFICE_THEMES 中，把地板（floor）颜色改成浅薄荷色。不要修改其他文件。

把简报室（WORKSPACES 中的 briefing）的五种语言名称都改成"作战会议室"一类的自然表达。

请说明屏幕顶部的状态预览按钮有什么作用。然后把创意室改成 running 状态，并展示屏幕上会发生什么变化。

右上角 Customize my office 按钮会打开无需改代码的编辑器：3 种预设、5～35 人、家具摆放 / 旋转 / 调色。

如何下好指令（本项目实际用的模式）

目标：（一句话）
当前状态：（以文件和行为为准）
完成定义：（看到什么或实现什么才算完成）
禁止：（不能修改的文件）
验证：（宣布完成前要运行的内容）

包含这五行的指令，比「你看着弄漂亮点」效果好得多。详细制作方式见仓库 guide/built-with-claude-code.md。

遇到问题

• 端口被占用：npm run dev -- --port 5200
• 页面空白：复制浏览器控制台里的红色错误，告诉 AI「帮我修好」
• 这个公开演示不含 AI 内容生成功能。

代码地图：四个文件就是全部

src/game/workflow.ts 和 office-events.ts 是类型桩——这里没有真正的 AI 工作流引擎。

三个练习任务

任务 1 — 添加新颜色预设：在现有预设（暖意工作室 / 薄荷实验室 / 紫罗兰休息室）外加第四种，先在 office-world.ts 找到预设定义位置。

任务 2 — 改一个房间的家具布局：在 office-world.ts 找家具摆放模式（item("briefing-desk-1","DESK",…)），给简报室加一张桌子。放到门前保护图块上会被拒绝，这是正常行为。

任务 3 — 加一种语言（较难）：在 LOCALES 加语言后，所有用 LocalizedText 的数据都会变成编译错误——这份错误列表就是待办列表，类型系统替你算好了工作范围。

需要提前知道的坑

• 不要直接在 CSS 里写颜色。UI 颜色从 THEME 令牌流向 CSS 变量（--color-*），办公室主题色由 OFFICE_THEMES 控制。
• 扩大网格（72×30）比看上去影响更大。舞台是信箱式布局，增加行数会让图块变小、名字标签重叠，座位 / 路径 / 电梯坐标都会连锁变化。
• 两种修改保存方式不同。用 AI 编程工具改的代码文件会保留；屏幕上家具编辑器改的布局和人数不会永久保存。
• 角色大小和名字标签缩放由 rAF 计算，在 CSS 改缩放会冲突。

权利边界：设计和代码仅供查看与学习。像素素材和部分移动逻辑来自第三方（MIT/CC0，见 THIRD-PARTY.md）。Fork 后作为服务发布需要获得许可。

数据驱动的世界 + 事件驱动的表现

① 世界就是数据。office-world.ts 用代码声明图块、墙、门、座位、家具、保护通道，寻路和座位分配读的是同一份数据，所以画面和行为不会脱节。

② 表现由事件驱动。渲染器接收 OfficeEvent（arrive / depart / say / activity…）流据此移动人物。演示传入空数组，因此只跑默认规则（就座 + 20～40% 走动概率）。想接外部编排器，这个事件流就是接入点。

渲染器为什么绕过 React

• 35 人以 60fps 行走时 React 重渲染开销太大，所以 rAF 循环直接改每个角色 DOM 的 style.transform（translate3d + scale）。
• 对话气泡和状态徽章靠替换 data-* 属性处理，React 状态只用于结构变化。
• 名字标签用 --label-counter 反向缩放恢复可读性，因此角色 scale 与标签可分别调整。
• 启用 prefers-reduced-motion 后移动停止，改为静态显示。

Props 接口（外部连接点）

workspaceStatuses  各房间状态（idle/running/…）— 房间灯光和徽章会响应
activeWorkspaceId  镜头和高亮跟随的房间
workflowStatus     整体状态 — 触发全员专注效果
officeEvents       表现事件流（见上文）
officeSession      值变化时全员重新到岗（供应者替换信号）
motionTimeScale    播放倍速（与行走同一时间轴）

顶部状态预览按钮正是直接操作这些 props。完整示例是 src/DemoApp.tsx 的 30 行代码。

这里没有的内容（有意省略）

此公开演示不含 AI 工作流引擎、供应商集成、审批流程、定时运行或永久保存。workflow.ts / office-events.ts 只是保留类型表面的桩文件，用于展示渲染器与外部通信的契约。制作细节见仓库 guide/built-with-claude-code.md。