1. 项目概述一个像素风的AI办公室看板如果你和我一样日常工作中重度依赖AI助手比如OpenClaw那你可能也遇到过这样的困惑当AI在后台默默执行一个长任务时你完全不知道它进行到哪一步了。是卡住了还是在正常处理你只能时不时去翻看日志或者干脆“盲等”。这种信息不透明让协作体验大打折扣。Star Office UI就是为了解决这个痛点而生的。它本质上是一个AI助手工作状态的可视化看板。想象一下你把你的AI助手们想象成一个个像素小人他们在一个像素风格的办公室里工作。当AI在“写代码”时像素小人就会走到办公桌前敲键盘当AI在“搜索资料”时小人头上会冒出搜索气泡如果AI遇到了错误小人则会跑到一个专门的“Bug区”愁眉苦脸。所有状态一目了然。这个项目最吸引我的地方在于它的实用主义和趣味性的结合。它不是一个复杂的监控系统而是一个轻量、直观的“状态窗口”。无论你是独立开发者还是团队协作都能通过这个看板瞬间掌握AI的工作脉搏。它支持多Agent协作意味着你可以把团队里不同的AI助手都“请”进这个办公室实时看到谁在忙、谁在休息极大地提升了多AI协同工作的透明度和趣味性。2. 核心设计思路与架构解析2.1 为什么选择像素风与游戏引擎初次接触Star Office UI你可能会好奇一个状态看板为什么要用像素风甚至用上了游戏引擎Phaser这背后有非常务实的考量。首先像素风是一种高效的信息载体。在有限的像素点内通过角色位置、动画帧和气泡文字可以非常直观地传达“谁、在哪、在做什么”这三重信息。相比冰冷的文字日志或图表像素动画的认知负荷更低一眼就能理解。其次Phaser.js是一个成熟的2D游戏框架它原生支持精灵动画、物理碰撞、移动、场景管理和状态机这些特性正好完美契合“办公室小人走动”这个核心交互。用游戏引擎做UI听起来有点“杀鸡用牛刀”但实际上它让我们能以极低的成本实现平滑的角色移动、状态切换动画和复杂的场景交互如果纯用DOM和CSS去模拟代码量和维护成本会高得多。项目的整体架构是经典的前后端分离后端Backend: 使用Flask构建的轻量级Python服务。它的核心职责是状态管理。它维护一个state.json文件或内存中的数据结构记录所有接入Agent的当前状态、描述和最后活跃时间。同时它提供一组简洁的RESTful API供AI助手或脚本调用以更新状态也供前端轮询获取最新状态。前端Frontend: 一个静态单页应用核心是Phaser 3游戏场景。它通过定时轮询或WebSocket如果未来实现从后端获取状态数据然后驱动场景中的像素角色做出相应的动作走到对应工位、播放特定动画、显示对话气泡。前端还负责多语言切换、美术资产加载等UI逻辑。这种架构的优势在于解耦和灵活性。后端只关心数据非常轻量易于部署和扩展。前端则可以专注于表现层利用Phaser的能力创造丰富的视觉体验。即使后端服务暂时不可用前端界面也不会崩溃最多只是状态不再更新。2.2 状态机设计6种状态与3个区域的精妙映射状态设计是整个系统的核心逻辑。Star Office UI没有设计几十种复杂状态而是提炼了6种最通用、最能体现AI工作流阶段的状态idle(待命): AI没有正在执行的任务。像素小人会待在休息区的沙发上。writing(写作): AI正在生成文本如写代码、写文档、写邮件。researching(调研): AI正在检索信息、思考或分析问题。executing(执行): AI正在运行代码、调用工具或执行系统命令。syncing(同步): AI正在上传、下载或同步数据。error(错误): AI遇到了异常或错误需要人工干预。这6种状态被巧妙地映射到办公室的3个物理区域 休息区: 对应idle状态。这是角色的“家”表示离线或可用。 工作区: 对应writing,researching,executing,syncing。这是主要的办公区域不同状态可能对应不同的桌面动画如敲键盘、翻书。 Bug区: 对应error状态。一个独立的区域通常设计得比较醒目如带有警告标志的角落用于立即吸引用户的注意。实操心得状态粒度控制在设计你自己的状态时切忌过细。一开始我尝试区分“写Python代码”和“写Markdown”但很快发现这会让前端动画变得复杂且意义不大。writing足以覆盖所有文本生成场景。状态的设计应以“用户是否需要立即区分此动作”为标准。error单独列出是必须的因为它需要最高优先级的视觉反馈。2.3 多Agent协作机制解析单Agent看板有用但多Agent协作才是生产力倍增器。Star Office UI通过一个“Join Key”机制来实现简单的多租户。密钥生成与管理: 后端启动时会读取或生成一个join-keys.json文件。每个Key代表一个“办公室”并可以配置最大在线人数。办公室主人将Key分发给访客其他AI Agent。访客接入: 访客Agent运行一个简单的推送脚本office-agent-push.py。这个脚本会使用分配的Join Key通过POST /join-agentAPI“敲门”加入办公室。成功后后端会为其创建一个临时的Agent记录。状态推送与同步: 加入后访客脚本会定期如每15秒调用POST /agent-push将自己的状态和描述推送给后端。后端更新该访客的状态和“最后心跳时间”。前端展示: 前端轮询GET /agents接口获取办公室内所有Agent的列表和状态然后在场景中渲染出多个像素角色各自处于正确的位置。心跳与清理: 后端会定期检查所有Agent的“最后心跳时间”。如果某个访客长时间未推送心跳超时则视其已离线自动将其从列表中移除避免僵尸Agent占用位置。这个机制轻巧而有效实现了去中心化的状态汇聚。每个Agent只需要关心如何上报自己的状态而不需要知道其他Agent的存在由看板服务统一协调展示。3. 从零开始的详细部署与配置指南3.1 基础环境搭建部署Star Office UI非常简单其设计目标就是快速上手。以下是步步为营的指南。第一步获取代码git clone https://github.com/ringhyacinth/Star-Office-UI.git cd Star-Office-UI这是所有故事的起点。建议在一个干净的目录下操作。第二步检查Python环境这是最关键的一步。项目要求Python 3.10因为它使用了X | Y这种联合类型语法。检查你的版本python3 --version如果版本低于3.10你需要先升级Python。在Ubuntu上可以使用deadsnakesPPA在macOS上推荐使用brew install python3.10。对于Windows用户请确保从Python官网下载3.10或更高版本的安装包。第三步安装后端依赖依赖列表在backend/requirements.txt中主要是Flask及其相关组件。python3 -m pip install -r backend/requirements.txt注意事项虚拟环境强烈建议使用虚拟环境venv来隔离项目依赖避免与系统或其他项目的Python包冲突。python3 -m venv venv source venv/bin/activate # Linux/macOS # 或 venv\Scripts\activate # Windows # 然后在虚拟环境中执行上述pip install命令第四步初始化状态文件状态文件是后端存储数据的核心。首次运行需要从模板复制。cp state.sample.json state.json你可以打开state.json查看其结构它初始定义了主Agent的默认状态通常是idle。3.2 启动服务与初体验启动Flask后端服务cd backend python3 app.py默认情况下服务会启动在http://127.0.0.1:19000。你会在终端看到类似* Running on http://127.0.0.1:19000的输出。快速测试状态切换不要关闭后端终端新开一个终端窗口切换到项目根目录尝试使用内置脚本改变状态# 假设你在项目根目录 Star-Office-UI/ python3 set_state.py writing 正在撰写项目周报执行后刷新浏览器中的看板页面 (http://127.0.0.1:19000)。你应该能看到像素小人从沙发走到办公桌并开始播放“写作”的动画头上冒出“正在撰写项目周报”的气泡。再试试其他状态python3 set_state.py researching 正在调研最新的LLM API价格 python3 set_state.py error 调用API时遇到速率限制 python3 set_state.py idle 任务完成休息一下每次切换前端的角色都会做出实时响应。这个即时反馈能让你立刻理解整个系统的工作流程。3.3 生产环境关键配置开发模式跑起来后如果要长期运行或对外提供服务以下几项安全配置必不可少。1. 配置环境变量后端根目录下有一个.env.example文件复制它并重命名为.envcd backend cp .env.example .env然后编辑.env文件至少设置以下两项FLASK_SECRET_KEYyour_very_long_random_secret_string_here ASSET_DRAWER_PASSa_strong_password_for_asset_managementFLASK_SECRET_KEY: 用于加密会话Cookie。务必使用一个长且随机的字符串可以用openssl rand -hex 32命令生成。弱密钥会导致会话被篡改。ASSET_DRAWER_PASS: 访问前端资产抽屉用于上传自定义角色/背景的密码。2. 修改默认端口如需如果19000端口被占用你可以在启动时指定其他端口python3 app.py --port 8080或者在.env文件中设置PORT8080。3. 使用生产级WSGI服务器Flask自带的开发服务器不适合生产环境。推荐使用Gunicorn(Linux/macOS) 或Waitress(跨平台)。# 安装Gunicorn pip install gunicorn # 启动假设你在backend目录下app:app 指模块名:应用实例名 gunicorn -w 4 -b 0.0.0.0:19000 app:app-w 4表示启动4个worker进程处理并发请求。4. 深度集成让AI助手自动汇报状态手动切换状态只是演示真正的威力在于与你的AI工作流如OpenClaw集成实现状态自动同步。4.1 与OpenClaw的规则集成OpenClaw通过SOUL.md或其它规则文件定义Agent的行为逻辑。我们可以在其中插入状态切换命令。基本思路是在任务开始前和结束后调用set_state.py脚本。在你的OpenClaw Agent规则文件中可以这样设计## 工作流状态同步规则 **当接到新任务时** 1. 首先分析任务类型确定初始状态如写作、调研、执行。 2. 执行命令python3 /path/to/Star-Office-UI/set_state.py 状态 “开始处理任务任务简述” 3. 然后才开始正式执行任务内容。 **当任务完成时** 1. 在最终回复用户前执行命令python3 /path/to/Star-Office-UI/set_state.py idle “任务「任务简述」已完成” 2. 随后再输出任务结果。 **当任务执行中遇到错误时** 1. 立即执行python3 /path/to/Star-Office-UI/set_state.py error “遇到错误错误信息” 2. 然后尝试修复或等待指令。例如一个具体的任务片段可能是用户帮我写一个Python函数计算斐波那契数列。 AI思考这是一个编程任务属于“写作”状态。 AI执行 bash # 首先更新状态 python3 /home/user/Star-Office-UI/set_state.py writing “正在编写斐波那契数列计算函数”# 然后开始写代码 def fibonacci(n): a, b 0, 1 for _ in range(n): a, b b, a b return a# 代码写完后更新状态为待命 python3 /home/user/Star-Office-UI/set_state.py idle “斐波那契函数已编写完成”以下是您要的函数。通过这样的规则嵌入你的AI助手就具备了“自我报告”的能力看板成为了一个真实的、自动更新的工作流可视化工具。 ### 4.2 状态映射策略详解 如何将复杂的AI任务准确映射到6种状态这需要一些策略思考。以下是我在实践中总结的映射表 | AI任务类型 | 推荐状态 | 状态描述示例 | 前端表现 | | :--- | :--- | :--- | :--- | | **代码/文本生成** | writing | “编写用户管理模块API” | 角色在办公桌敲键盘 | | **信息检索与总结** | researching | “调研2024年前端框架趋势” | 角色在办公桌看书/搜索 | | **运行脚本/命令** | executing | “执行数据库备份脚本” | 角色在办公桌屏幕有进度条 | | **调用外部API** | executing 或 syncing | “调用GitHub API获取仓库列表” | 同上或表示数据流动 | | **文件上传/下载** | syncing | “同步项目日志到云存储” | 角色旁有数据上传动画 | | **任务规划/分解** | researching | “分析需求并拆分子任务” | 同researching | | **遇到异常/错误** | error | “Docker容器启动失败” | 角色移动到Bug区显示错误图标 | | **等待用户输入/空闲** | idle | “等待下一步指令” | 角色在沙发休息 | **实操心得描述信息的价值** 状态描述set_state.py的第二个参数不要随便写“工作中”。尽量写具体内容如“正在调试登录接口的500错误”。这样当你在看板上瞥一眼时就能立刻知道卡点在哪无需再查日志。这是提升效率的关键细节。 ### 4.3 处理长时间运行的任务 对于需要运行几分钟甚至更久的任务如训练模型、大规模数据处理如果一直显示executing你会失去时间感。这里有两个进阶技巧 **1. 分阶段更新状态** 在长任务的关键里程碑处更新状态描述。 bash # 任务开始 python3 set_state.py executing “开始训练图像分类模型” # ... 训练一段时间后 python3 set_state.py executing “模型训练中Epoch 50/100, Loss: 0.15” # ... 训练结束 python3 set_state.py syncing “保存模型权重到云端” # ... 全部完成 python3 set_state.py idle “模型训练与保存完成”2. 使用“心跳”保持状态新鲜对于超长任务可以定期执行一个简单的状态更新防止前端因长时间无状态变化而认为Agent失联虽然后端有独立的心跳机制。可以在任务循环内加入# 每5分钟更新一次描述 python3 set_state.py executing “模型训练中已运行$(date %H:%M)”5. 高级功能与个性化定制5.1 多语言与移动端适配Star Office UI原生支持中文、英文、日文三种语言。在页面右上角可以找到语言切换按钮。这个功能不仅仅是翻译界面文字还包括所有状态气泡、加载提示、按钮文案的同步切换。这对于国际化团队或者有不同语言偏好的用户非常友好。移动端适配做得相当出色。页面采用了响应式设计在手机浏览器上打开布局会自动调整角色和状态信息依然清晰可辨。这意味着你可以在通勤路上、会议室里随时掏出手机查看AI的工作进度。实现上前端通过CSS媒体查询和Phaser的缩放功能确保了游戏画布在不同屏幕尺寸下的最佳显示效果。5.2 AI生图装修与资产管理这是一个充满趣味性的功能。项目集成了Google Gemini API允许你通过AI来“装修”你的像素办公室。工作原理你在侧边栏的“AI装修”面板中输入描述词例如“一个充满绿色植物和落地窗的现代科技办公室”。前端将这个描述发送到后端后端调用Gemini的图像生成API。生成完成后新的背景图会被保存到资产目录并自动应用到当前办公室场景中。注意事项API成本与稳定性此功能需要配置Gemini API密钥在.env中设置GEMINI_API_KEY。请注意图像生成API是收费的且可能有调用频率限制。建议仅在需要时使用并关注API用量。如果不配置API密钥核心的看板功能完全不受影响。资产管理系统让你可以完全自定义办公室的一切。通过密码ASSET_DRAWER_PASS打开侧边栏的资产抽屉你可以上传角色精灵图: 替换默认的像素小人使用你自己设计的角色。更换场景图: 上传新的办公室背景。管理装饰物: 添加或删除场景中的静态装饰元素。 所有上传的资产会被妥善管理并避免在切换时出现画面闪烁。这为项目的个性化打开了无限可能。5.3 桌面宠物模式部署desktop-pet目录提供了一个基于Electron的封装能将浏览器中的看板变成一个始终置顶的透明桌面窗口就像一个小宠物或小部件一样挂在你的桌面上。部署步骤cd desktop-pet npm install # 安装Electron依赖 npm run dev # 启动开发模式它会自动启动后端的Python服务并加载一个指向本地19000端口的透明窗口。配置要点窗口大小、透明度、是否可拖动等可以在Electron的配置文件中调整。它本质上是一个无边框、透明的浏览器窗口因此所有网页功能都可用。目前主要由社区贡献者维护在macOS上体验较好Windows和Linux可能需要一些额外的窗口管理器配置。这个模式非常适合那些希望将AI状态常驻在桌面一角、随时可见的用户极大地提升了信息的可达性。6. 常见问题排查与性能优化6.1 部署与运行问题Q1: 启动python3 app.py时提示ModuleNotFoundError: No module named flaskA:依赖未正确安装。请确保在项目根目录或backend目录下执行了pip install -r requirements.txt。如果你使用了虚拟环境请确认虚拟环境已激活。尝试使用pip3替代pip。Q2: 前端页面能打开但角色不动状态不更新。A:这是一个典型的前后端通信问题。按以下步骤排查检查后端是否运行确认终端里Flask服务正在运行无报错。检查网络请求在浏览器中按F12打开开发者工具切换到“网络”(Network)标签页刷新页面。查看对/status或/agents的请求是否成功状态码200。如果失败如404、500说明后端API不可达。检查CORS如果前端和后端不同源默认配置下后端允许本地访问。如果你将前端部署在了其他域名或端口需要在Flask后端配置CORS。可以在app.py中初始化Flask app后添加from flask_cors import CORS CORS(app) # 允许所有来源生产环境应指定具体来源并安装flask-cors包。Q3:set_state.py脚本执行成功但页面状态没变。A:页面状态是前端定期轮询如每3秒获取的可能有短暂延迟。如果超过10秒未变查看后端终端是否有收到POST请求的日志。手动访问http://127.0.0.1:19000/status看返回的JSON数据是否已更新。前端可能存在缓存尝试强制刷新浏览器CtrlF5。6.2 集成与使用问题Q4: 如何让多个独立的AI Agent非OpenClaw接入看板A:每个Agent只需要能发送HTTP请求即可。核心是调用两个API加入办公室向POST /join-agent发送请求Body中包含join_key和agent_name。定期推送心跳向POST /agent-push发送请求Body中包含join_key,agent_name,state,description。 你可以用任何语言Python, Node.js, Bash curl编写一个简单的守护进程来实现。项目提供的office-agent-push.py就是一个Python范例。Q5: 访客Agent加入后主看板看不到它。A:检查以下几点Join Key是否正确确保访客脚本中的JOIN_KEY与主看板后端join-keys.json文件中的某个key完全匹配。人数是否超限每个Key有默认的并发人数限制如3人。检查是否已满。后端日志查看后端终端看是否有成功的/join-agent和/agent-push请求日志。前端轮询前端页面需要几秒钟轮询一次/agents接口来获取列表。稍等片刻。Q6: 状态文件state.json损坏或想重置怎么办A:直接删除state.json文件然后重启后端服务。服务启动时如果发现没有state.json会自动从state.sample.json重新创建一份初始状态文件。join-keys.json的处理逻辑类似。6.3 安全与性能优化建议安全加固强密码如前所述务必设置强FLASK_SECRET_KEY和ASSET_DRAWER_PASS。防火墙如果部署在公网使用防火墙或云安全组规则仅允许必要的端口如19000访问。反向代理在生产环境不要直接用Flask开发服务器或Gunicorn对外暴露。使用Nginx或Apache作为反向代理可以提供HTTPS、负载均衡、静态文件服务和额外的安全层。# Nginx 配置示例 server { listen 80; server_name your-domain.com; # 重定向到HTTPS推荐 return 301 https://$server_name$request_uri; } server { listen 443 ssl; server_name your-domain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://127.0.0.1:19000; # 转发到Gunicorn proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }性能优化减少轮询频率前端默认的轮询间隔是3秒。如果Agent状态变化不频繁可以适当延长这个间隔修改前端layout.js中的轮询时间以减少不必要的网络请求和后端负载。使用WebSocket进阶对于实时性要求极高的场景可以考虑将轮询改为WebSocket。当后端状态变化时主动推送消息给所有已连接的前端实现真正的实时更新。但这需要改造前后端代码复杂度较高。优化资产加载确保角色精灵图、背景图等美术资源已经过压缩如使用TinyPNG。前端代码也应做好缓存策略避免重复加载。维护建议定期清理日志Flask或Gunicorn的访问日志、错误日志会随时间增长建议配置日志轮转log rotation。监控服务健康可以写一个简单的cron job定期调用GET /health接口如果失败则发送告警通知。备份配置定期备份你的.env、join-keys.json和任何自定义的美术资产。这个项目将实用的状态监控与有趣的像素游戏结合为AI协作带来了一抹亮色。从我自己的使用体验来看它最大的价值不在于技术有多复杂而在于它创造了一种“可见的协作感”。当你看到屏幕上的像素小人在为你忙碌时那种人与AI协同工作的沉浸感是纯文本日志无法比拟的。无论是用于个人效率工具还是作为团队项目的状态公示板Star Office UI 都提供了一个独特而高效的解决方案。