1. 项目概述一个像素风的AI办公室看板如果你和我一样日常工作中需要和多个AI助手打交道或者管理着一个小型的AI Agent团队那你肯定遇到过这样的困扰你只知道它们在工作但具体在干什么、进度如何、有没有卡住心里完全没底。要么得去翻冗长的日志要么得手动发指令去问效率很低也缺乏那种“掌控感”。Star Office UI 就是为了解决这个痛点而生的。它本质上是一个实时状态可视化看板但用了一种非常讨喜的方式——像素艺术风格的虚拟办公室。你可以把它想象成一个数字版的“办公室沙盘”你手下的每一个AI助手Agent都会化身为一个像素小人在办公室里走来走去。当Agent在写代码时小人会走到办公桌前敲键盘当Agent在调研时小人会走到书架前如果出错了小人则会跑到一个专门的“Bug区”蹲着。所有状态一目了然而且充满趣味。这个项目最初是为 OpenClaw 这个AI Agent框架深度优化的两者结合能实现状态自动同步体验最完整。但它的设计非常灵活即便你没有任何AI框架只是单纯想有一个酷炫的个人状态页或者想可视化某个脚本、服务的运行状态也完全可以独立部署和使用。它支持多Agent协作、中英日三语界面、AI生图装修甚至还有个可选的“桌面宠物”模式能把办公室变成一个悬浮在桌面的透明窗口。接下来我会从一个实际部署和使用者的角度带你彻底拆解这个项目。我会详细说明它的核心设计思路、每一步的部署细节、如何与现有工作流集成以及我在实际使用中踩过的坑和总结出的技巧。无论你是想快速搭起来玩玩还是打算把它深度集成到你的生产环境中这篇文章都能给你提供一份可靠的“操作手册”。2. 核心设计思路与架构拆解在动手部署之前理解它的设计思路和架构能帮你更好地使用和定制它。Star Office UI 不是一个简单的静态页面而是一个前后端分离、状态驱动、支持扩展的轻量级系统。2.1 状态驱动与场景映射把抽象任务“可视化”项目的核心逻辑是“状态驱动”。它将AI助手复杂的工作流抽象为有限的几种状态。目前定义了6种基础状态idle空闲、writing写作、researching调研、executing执行、syncing同步、error错误。这6种状态并非随意定义而是精心映射到办公室的三个物理区域休息区沙发对应idle状态。代表Agent没有任务处于待命状态。工作区办公桌对应writing、researching、executing、syncing状态。这是Agent的主要活动区域虽然状态不同但位置相同通过角色动画和头顶的气泡文字来区分具体在做什么例如writing时是打字动画researching时是翻书动画。Bug区一个带有虫子图标的地毯区域对应error状态。一旦Agent报错或进入异常处理流程其像素形象就会走到这个区域非常直观地警示用户。这种设计的巧妙之处在于它用最直观的视觉隐喻降低了认知成本。你不需要理解复杂的日志看一眼办公室就知道整体是“一片繁忙”还是“有人卡bug了”。对于管理多个Agent的团队来说这种全局视角的价值尤其大。2.2 技术栈选型轻量、易上手与可扩展项目的技术选型充分考虑了易用性和社区生态后端Backend采用Flask。这是一个极其轻量级的Python Web框架学习曲线平缓依赖少启动快。对于Star Office UI这种核心是状态管理和提供API的服务来说Flask完全够用也便于开发者快速理解和二次开发。后端主要负责提供RESTful API接收状态更新、管理多Agent的会话和状态、读取“昨日小记”文件、以及处理AI生图等异步任务。前端Frontend核心渲染引擎是Phaser 3。这是一个专门用于制作2D浏览器游戏的框架性能优秀社区活跃。选择Phaser而非普通的DOM操作或React/Vue是因为它原生支持精灵图Sprite、动画Animation、物理碰撞本项目未使用等游戏开发概念能非常高效、流畅地实现像素小人的走动、状态切换动画等效果。前端通过WebSocket或短轮询与后端通信实时更新办公室内所有Agent的状态和位置。桌面端可选提供了基于Electron的封装。Electron允许使用Web技术HTML, CSS, JS来开发桌面应用。这个“桌面宠物”模式本质上是一个内置了Chromium浏览器内核的透明窗口将网页版的办公室直接包装成了一个可以置顶显示、鼠标穿透可选的桌面应用实现了“常驻桌面”的效果。这个技术栈组合Flask Phaser Electron在保证功能实现的前提下最大程度地降低了参与门槛。一个懂点Python和JavaScript的开发者就能轻松驾驭整个项目。2.3 多Agent协作机制安全的“访客”系统单Agent显示只是基础多Agent协作才是亮点。项目设计了一个基于Join Key加入密钥的访客系统既灵活又安全。工作流程如下办公室主人部署Star Office UI后端后端会管理一个join-keys.json文件里面存储了有效的密钥列表。每个Key可以设置最大同时在线人数默认3人。访客Agent获得一个有效的Join Key后运行一个独立的推送脚本office-agent-push.py。这个脚本会做两件事注册使用Join Key调用/join-agentAPI将自己的信息名称、初始状态注册到办公室。保活与推送随后以固定间隔如15秒调用/agent-pushAPI上报自己的当前状态实现“心跳”保活和状态同步。看板显示后端维护所有活跃访客的列表和状态。前端办公室场景里会为每个访客生成一个对应的像素小人并根据其状态将其放置在正确的区域。这个机制的好处是解耦。访客不需要知道办公室后端的内部实现只需要调用几个简单的API办公室后端也无需为每个访客维护复杂的连接只需处理HTTP请求即可。这种设计使得它可以接入任何能发送HTTP请求的系统不仅是OpenClaw Agent也可以是CI/CD流水线、服务器监控脚本甚至是另一个独立的程序。3. 从零开始的详细部署与配置指南理论讲完我们进入实战环节。我会假设你从一个全新的Linux/macOS环境开始带你一步步完成部署并解释每个步骤背后的原因。3.1 环境准备与依赖安装首先确保你的系统已安装Python 3.10 或更高版本。这是硬性要求因为项目代码中使用了X | Y这种Union Type语法这在Python 3.10中才被引入。# 检查Python版本 python3 --version # 应显示 Python 3.10.x 或更高如果版本过低需要先升级Python。在Ubuntu上可以使用deadsnakesPPA在macOS上推荐使用brew install python3.10。接着获取项目代码并安装Python依赖# 1. 克隆仓库 git clone https://github.com/ringhyacinth/Star-Office-UI.git cd Star-Office-UI # 2. 安装后端依赖 python3 -m pip install -r backend/requirements.txt注意强烈建议在虚拟环境venv或conda中操作避免污染系统Python环境。可以使用python3 -m venv venv创建然后source venv/bin/activate激活。安装过程会拉取Flask、requests等核心库。如果遇到网络问题可以考虑配置pip镜像源如清华源、阿里云源。3.2 初始化配置与首次启动项目运行需要两个核心的配置文件状态文件和环境变量文件。# 1. 复制状态样本文件 cp state.sample.json state.jsonstate.json文件定义了主Agent的初始状态。你可以打开它查看结构但首次启动无需修改。# 2. 生产环境必做复制环境变量样本文件并配置 cp .env.example .env.env文件用于配置敏感信息和运行参数。在生产环境中修改此文件是安全加固的关键一步。用文本编辑器打开.env# .env 示例 FLASK_SECRET_KEYyour_very_strong_random_secret_key_here ASSET_DRAWER_PASSyour_asset_drawer_password # GEMINI_API_KEYyour_google_gemini_api_key_optionalFLASK_SECRET_KEY用于加密Flask的session cookie。务必使用一个强随机字符串可以用命令生成openssl rand -hex 32。弱密码或默认值会导致会话被伪造的安全风险。ASSET_DRAWER_PASS侧边栏资产管理器的访问密码。同样需要设置为强密码。GEMINI_API_KEY如果你想使用“AI生图装修”功能需要在此填入你的Google Gemini API Key。此功能是可选的不配置不影响核心使用。配置完成后启动后端服务cd backend python3 app.py如果一切正常终端会输出类似* Running on http://127.0.0.1:19000的信息。现在打开浏览器访问http://127.0.0.1:19000你应该能看到一个空旷的像素风办公室你的主Agent默认名称为“Agent”正站在休息区的沙发上。3.3 基础功能测试手动切换状态服务跑起来了我们试试如何改变状态。项目根目录下提供了一个便捷脚本set_state.py。打开一个新的终端窗口保持后端服务在另一个终端运行进入项目目录执行# 语法python3 set_state.py 状态 描述 python3 set_state.py writing 正在撰写项目周报刷新浏览器页面你会发现“Agent”小人已经从沙发走到了办公桌并且头上出现了“正在撰写项目周报”的气泡。这个脚本本质上是向后端的/set_stateAPI发送了一个POST请求。再试试其他状态python3 set_state.py researching 调研最新的LLM API价格 python3 set_state.py error 依赖安装失败请检查网络 python3 set_state.py idle 任务完成休息中每次执行后刷新页面观察小人的位置和动画变化。这就是Star Office UI最核心的交互通过API驱动视觉变化。3.4 进阶部署公网访问与安全考量本地运行只能自己看。如果你想在团队内分享或者在外出时用手机查看就需要将服务暴露到公网。强烈推荐使用 Cloudflare Tunnel它是最简单、最安全的方式之一无需拥有公网IP或配置复杂的路由器端口转发。安装cloudflared命令行工具请参考Cloudflare官方文档。在项目根目录下执行一条命令创建隧道cloudflared tunnel --url http://127.0.0.1:19000cloudflared会分配一个如https://your-random-subdomain.trycloudflare.com的临时域名。将这个链接分享给他人他们就能访问你的办公室了。重要安全提示一旦将服务暴露到公网.env中的强密码设置就至关重要。项目代码中已经包含了生产环境弱密码检查逻辑如果检测到FLASK_SECRET_KEY或ASSET_DRAWER_PASS使用的是示例中的弱密码后端会拒绝启动并报错强制你进行修改。这是项目一个非常负责任的安全设计。另一种方式是使用自有域名和反向代理如Nginx这更适合长期、稳定的部署。Nginx配置示例片段如下server { listen 80; server_name office.yourdomain.com; # 你的域名 location / { proxy_pass http://127.0.0.1:19000; # 转发到本地的Flask服务 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # 如果前端使用WebSocket还需要添加以下headers proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }配置好后还需设置SSL证书例如使用Let‘s Encrypt的certbot来启用HTTPS保证数据传输安全。4. 深度集成与OpenClaw或自定义工作流联动让手动执行脚本切换状态太原始了。真正的威力在于与自动化工作流集成。4.1 与OpenClaw无缝融合对于OpenClaw用户集成非常简单。OpenClaw的Agent在执行任务时会遵循你定义的规则SOUL.md。你只需要在规则中加入状态切换的指令。在你的Agent规则文件中可以这样定义## 工作流规则 - 当我收到任何任务指令时我应当 1. 首先分析任务类型并确定对应的Star Office状态如写作、调研、执行。 2. 然后执行命令python3 /path/to/Star-Office-UI/set_state.py 对应状态 “开始处理任务简述”。 3. 接着才开始正式执行任务。 - 当我完成任务并准备回复用户时我应当 1. 在发送回复之前执行命令python3 /path/to/Star-Office-UI/set_state.py idle “任务完成待命”。 2. 然后再发送回复。这样你的Agent在生命周期内就会自动维护自己在办公室的状态。你作为管理者只需要打开办公室页面就能看到所有Agent是正在忙碌在办公区还是已经空闲在沙发区或者遇到了问题在Bug区。4.2 接入自定义脚本或CI/CD流程即使不用OpenClaw你也可以将状态推送集成到任何脚本中。核心就是调用那个简单的HTTP API。例如你有一个自动化的数据备份脚本backup.sh可以在其中加入状态上报#!/bin/bash # 备份脚本开始 BACKUP_DIR/path/to/data OFFICE_APIhttp://localhost:19000/set_state # 1. 上报“执行中”状态 curl -X POST $OFFICE_API \ -H Content-Type: application/json \ -d {state:executing, message:开始执行数据备份任务} # 2. 执行实际的备份命令这里用rsync示例 rsync -avz $BACKUP_DIR userremote-server:/backup/ # 3. 根据执行结果上报最终状态 if [ $? -eq 0 ]; then curl -X POST $OFFICE_API \ -H Content-Type: application/json \ -d {state:syncing, message:备份完成正在同步元信息} # ... 一些后续同步操作 curl -X POST $OFFICE_API \ -H Content-Type: application/json \ -d {state:idle, message:数据备份任务已全部完成} else curl -X POST $OFFICE_API \ -H Content-Type: application/json \ -d {state:error, message:数据备份失败请检查日志} fi这样一来这个备份任务在办公室中就有了一个“虚拟形象”它的运行状态和结果对你完全透明。4.3 管理多访客Join Key系统假设你想邀请同事的Agent加入你的办公室一起展示。生成与管理Join Key首次启动后端后会在项目根目录生成join-keys.json。你可以编辑这个文件添加新的Key并设置max_agents最大同时在线数。{ ocj_team_alpha: { max_agents: 5, created_at: 2024-01-01T00:00:00Z }, ocj_project_beta: { max_agents: 3, created_at: 2024-01-01T00:00:00Z } }分发Key与脚本将office-agent-push.py脚本和其中一个Key如ocj_project_beta发给你的同事。访客配置你的同事只需要修改脚本开头的几个变量JOIN_KEY ocj_project_beta AGENT_NAME 小李的助手 # 他希望在办公室显示的名字 OFFICE_URL https://your-office-domain.com # 你的办公室公网地址然后运行python3 office-agent-push.py。他的Agent就会出现在你的办公室看板上并根据其上报的状态在相应区域活动。5. 高级功能与个性化定制基础功能用熟了可以玩玩这些提升体验和趣味性的高级功能。5.1 AI生图装修办公室这是项目里一个非常有趣的功能。它调用Google Gemini的Image Generation API根据你的文字描述为办公室生成新的背景图。配置步骤获取Google AI Studio的API Key。将其填入.env文件的GEMINI_API_KEY中。启动服务在办公室页面点击侧边栏的“装修”图标需要输入ASSET_DRAWER_PASS密码。在生图界面输入描述词例如“cyberpunk style office at night with neon lights”。点击生成后端会异步调用Gemini API。生成完成后新的背景图会自动加载到办公室中。注意此功能依赖于外部API且有调用成本Gemini API非完全免费。生成速度受网络和API排队影响可能需要等待数十秒。如果不想用完全不配置GEMINI_API_KEY即可核心功能不受任何影响。5.2 桌面宠物模式如果你希望办公室能一直停留在桌面上可以使用桌面宠物版。cd desktop-pet npm install # 安装Electron依赖 npm run dev # 启动开发模式这个Electron应用会做两件事自动检查并启动Python后端服务如果未运行。打开一个无边框、可置顶、支持鼠标穿透点击会穿透到下层窗口的透明窗口加载办公室页面。你可以将其打包成独立的桌面应用使用npm run build并设置为开机启动这样就能拥有一个常驻桌面的AI助手状态监视器。5.3 美术资产管理与替换项目的美术资源像素小人、办公室物件、背景位于frontend/assets/目录下。如果你对自带的像素风格不满意可以替换它们。替换角色动画找到新的像素角色精灵图Sprite Sheet需要是横向或纵向排列的动画帧。替换frontend/assets/characters/目录下的对应图片文件如visitor.png。可能需要调整frontend/layout.js中关于角色动画帧的配置frameWidth,frameHeight,anims定义以匹配新图片的尺寸和动画序列。替换办公室背景将新的背景图片建议尺寸与原有背景接近放入frontend/assets/bg/。在侧边栏的“资产管理器”中可以上传并切换背景无需修改代码。重要法律提示项目使用的访客角色动画来自LimeZu的免费资源包仅限非商业用途。如果你要将此项目用于任何商业场景必须替换掉所有来自该资源包的美术素材或者确保你拥有所使用素材的商业授权。6. 常见问题排查与实战心得在实际部署和使用中你可能会遇到以下问题。这里我总结了一些排查思路和技巧。6.1 部署与启动问题Q1启动python3 app.py时报错提示 Python 语法错误例如SyntaxError: invalid syntax指向X | Y这样的代码。A1这几乎可以肯定是Python版本过低。请使用python3 --version确认版本是否为3.10。在macOS上即使你通过brew安装了新版本系统的python3命令可能仍指向旧版。可以尝试使用python3.10或python3.11明确指定版本启动或者修改你的PATH环境变量。Q2访问页面后办公室场景是黑的或者角色不显示浏览器控制台Console有404错误提示找不到assets/下的图片。A2这通常是前端资源路径问题。确保你是从Flask服务启动的地址如http://127.0.0.1:19000访问而不是直接双击打开本地的index.html文件。Flask配置了静态文件路由直接文件协议file://访问会导致路径错误。如果使用反向代理如Nginx请确保代理配置正确传递了静态文件请求。Q3使用Cloudflare Tunnel后页面能打开但状态切换不生效或者WebSocket连接失败。A3Cloudflare Tunnel默认可能对WebSocket的支持需要额外配置。确保你的cloudflared版本较新。另一种更稳定的方式是在Cloudflare Zero Trust面板中创建配置更明确的隧道并在配置中启用WebSocket。如果问题依旧可以暂时在前端代码中将通信方式从WebSocket回退到短轮询项目通常有配置项虽然实时性稍差但兼容性更好。6.2 状态同步与API调用问题Q4set_state.py脚本执行成功但办公室页面没有实时更新需要手动刷新。A4实时更新依赖于前端与后端建立的WebSocket连接。首先检查浏览器控制台是否有WebSocket连接错误。如果网络环境复杂如公司代理WebSocket可能被阻断。可以尝试刷新页面重新建立连接。检查后端日志看WebSocket握手是否成功。如前所述考虑降级到轮询模式。查看frontend/layout.js通常会有useWebSocket这类的配置变量。Q5访客Agent运行office-agent-push.py后办公室看不到它。A5按以下步骤排查检查Join Key确认访客脚本中的JOIN_KEY与办公室后端join-keys.json文件中的某个key完全一致包括大小写。检查网络连通性确认访客机器能访问OFFICE_URL。可以尝试用curl $OFFICE_URL/health测试。查看后端日志在办公室后端服务器上查看Flask的运行日志。当访客调用/join-agent和/agent-push时会有相应的日志输出可以确认是否收到请求以及处理结果。检查人数限制确认该Join Key对应的max_agents限制是否已满。6.3 性能与优化心得心得1关于状态更新频率访客脚本office-agent-push.py默认每15秒推送一次状态。这个间隔是权衡之举。太短如1秒会给后端带来不必要的压力且对于AI任务状态监控来说过于精细太长如60秒则会导致看板上的状态更新明显滞后。15秒是一个比较折中的选择。你可以根据实际需求修改脚本中的PUSH_INTERVAL变量。心得2生产环境部署建议使用进程管理器不要直接用python3 app.py在前台运行。使用systemd(Linux) 或supervisor来管理Flask进程实现开机自启、崩溃自动重启、日志轮转。systemd服务文件示例 (/etc/systemd/system/star-office-ui.service)[Unit] DescriptionStar Office UI Backend Afternetwork.target [Service] Useryour_username WorkingDirectory/path/to/Star-Office-UI EnvironmentPATH/path/to/your/venv/bin ExecStart/path/to/your/venv/bin/python backend/app.py Restartalways RestartSec10 [Install] WantedBymulti-user.target分离前端静态资源对于高并发访问可以考虑将frontend/目录下的静态文件HTML, JS, CSS, 图片托管到CDN或专门的Web服务器如Nginx减轻Flask的负担Flask只专注于API服务。定期清理日志Flask的日志和访客的推送日志会增长建议配置日志轮转策略。心得3“昨日小记”功能的依赖“昨日小记”卡片会尝试从memory/*.md文件读取内容。这个功能是为OpenClaw等能生成此类记忆文件的Agent框架设计的。如果你独立使用这个目录可能为空卡片也会显示为空。你可以选择忽略此功能。创建一个符合格式的Markdown文件放在memory/目录下进行测试。修改后端app.py中get_yesterday_memo函数的逻辑使其从你的日志系统或数据库中读取内容。这个项目最吸引我的地方在于它用一种极具创意且低门槛的方式解决了AI工作流可视化这个实际需求。它不像那些复杂的监控系统需要沉重的部署也不像简单的日志文件那样枯燥。几行命令就能搭起来一个API调用就能改变状态这种简洁和优雅正是工程师所欣赏的。我在自己的团队中使用它已经有一段时间了最大的感受是它提升了“态势感知”能力。我不再需要频繁地在多个终端或聊天窗口间切换去询问进度一瞥办公室页面所有Agent的忙碌程度、任务类型尽收眼底。当那个红色的小人跑到Bug区时我能第一时间介入而不是等错误堆积了很久才发现。如果你正在探索AI Agent的应用或者只是想给枯燥的自动化脚本增添一点乐趣我强烈建议你试试Star Office UI。从手动执行set_state.py开始感受状态驱动UI的乐趣再逐步将它集成到你的自动化流程中。你会发现让工作“看得见”本身就是一种强大的生产力。