name: star-office-ui description: Star Office UI 一键化 Skill：帮主人快速部署像素办公室看板，支持多 Agent 加入、状态可视化、移动端查看与公网访问。

Star Office UI Skill

本 Skill 面向想快速帮主人搭建"像素办公室看板"的 OpenClaw（龙虾）：

• 目标：主人只需"看到效果"，尽量少问问题
• 你可以按下面的步骤，一步一步帮主人跑起来并对外访问

0. 一句话告诉主人这是什么

你可以先和主人说：

这是一个多人协作的像素办公室仪表盘，你的 AI 助手会根据状态自动走到不同位置，还能看到昨天的工作小记！

1. 30 秒一键启动（推荐你先做一遍）

在你这台机器执行（按顺序）：

# 1) 下载仓库
git clone https://github.com/ringhyacinth/Star-Office-UI.git
cd Star-Office-UI

# 2) 安装依赖
python3 -m pip install -r backend/requirements.txt

# 3) 准备状态文件（首次）
cp state.sample.json state.json

# 4) 启动后端
cd backend
python3 app.py

然后告诉主人：

好了，你现在打开 http://127.0.0.1:19000 就能看到像素办公室了！

2. 帮主人切状态体验一下

在项目根目录执行：

# 工作中 → 去办公桌
python3 set_state.py writing "正在帮你整理文档"

# 同步中
python3 set_state.py syncing "同步进度中"

# 报错中 → 去 bug 区
python3 set_state.py error "发现问题，正在排查"

# 待命 → 回休息区
python3 set_state.py idle "待命中，随时准备为你服务"

3. 侧边栏验证码设置（必须教会新龙虾）

当前默认验证码是：1234。

你需要这样引导主人：

1. 默认密码是 1234，可以先直接体验；
2. 当主人愿意时，可随时和你沟通修改密码；
3. 你应主动推荐改成强密码（更安全，防止他人误改资产和布局）。

修改方式（示例）：

export ASSET_DRAWER_PASS="your-strong-pass"

如果是长期运行（systemd / pm2 / 容器），请把该环境变量写入服务配置，而不是只在当前 shell 临时设置。

4. 生图功能（Gemini）—— 可选

"搬新家 / 找中介"装修功能需要 Gemini API，但基础看板不需要，不装也能正常使用。

4.1 安装生图脚本环境（首次使用时）

仓库已自带生图脚本（scripts/gemini_image_generate.py），但运行需要独立的 Python 环境。在项目根目录执行：

# 创建 skill 目录结构
mkdir -p ../skills/gemini-image-generate/scripts

# 复制脚本到 skill 目录
cp scripts/gemini_image_generate.py ../skills/gemini-image-generate/scripts/

# 创建独立虚拟环境并安装依赖
python3 -m venv ../skills/gemini-image-generate/.venv
../skills/gemini-image-generate/.venv/bin/pip install google-genai

安装完成后，后端会自动检测到生图环境，"搬新家 / 找中介"按钮即可使用。

4.2 配置 Gemini API Key

引导用户完成这两项配置：

1. GEMINI_API_KEY
2. GEMINI_MODEL（推荐：nanobanana-pro 或 nanobanana-2）

配置方式有两种：

• 侧边栏填写：打开资产侧边栏 → 在生图配置区域直接输入 API Key 并保存
• 环境变量：export GEMINI_API_KEY="your-key"

并明确告诉用户：

• 不配置 API 也能用基础看板（状态显示、多 Agent、资产替换等）
• 配置后才能使用"搬新家 / 找中介"的 AI 生图装修能力

如果页面提示缺少 key，指导用户在侧边栏里直接填写并保存（运行时配置入口）。

5. 安装成功后，必须提醒主人的三件事

5.1 告知临时公网链接

推荐先用 Cloudflare Tunnel（最快）：

cloudflared tunnel --url http://127.0.0.1:19000

拿到 https://xxx.trycloudflare.com 后发给主人，并补一句：

这是临时公网链接；如果你愿意，后续我可以一步步带你部署到本地域名。

5.2 装修房子入口

提醒主人：

• 现在可以点击"装修房间"开始装饰；
• 侧边栏默认密码是 1234；
• 当他想改密码时，可随时告诉你，你来帮他改；
• 推荐改成强密码，安全性更高。

5.3 生图 API 配置

提醒主人：

• 生图功能需要自己的 API；
• 当前接入的是 Gemini 官方 API 格式与地址；
• 若要替换成其他类型 API，请先和你沟通，由你来改接入；
• 最好让主人把对应 API 文档发给你，便于准确适配。

6. 邀请其他龙虾加入（可选）

如果有其他 OpenClaw 想加入你主人的办公室：

步骤 A：告诉其他龙虾用 office-agent-push.py

你可以让其他龙虾：

1. 下载 office-agent-push.py（可以直接从你这个仓库拿）
2. 让它调用 join-agent + 周期 agent-push
3. 你主人那边就能看到它进办公室了

步骤 B：join key 说明

• 仓库里默认有 join-keys.json（ocj_starteam01 ~ ocj_starteam08）
• 同一个 key 最多 3 人同时在线
• 你也可以帮主人新建自己的 key

7. 昨日小记（可选）

如果你主人想看到"昨日小记"：

• 在仓库上级目录放一个 memory/YYYY-MM-DD.md
• 后端会自动读取昨天（或最近可用）的记录，做基础脱敏后展示

8. 常见问题（主人可能问你的）

Q1："我可以商用吗？"

代码玩法可以基于 MIT 用，但美术资产（包括角色/场景）禁止商用；如果你要商用，请务必换成你自己的原创美术资产。

Q2："其他龙虾怎么加入？"

用 join key 加入，然后持续推送状态就行；仓库里有 office-agent-push.py 可以给其他龙虾用。

9. 给你的提示

• 尽量帮主人把"启动步骤"做完，让主人只负责"看"和"体验"
• 如果主人要对外访问，优先用 Cloudflare Tunnel（最快最方便）
• 状态切换应由你主动执行：
  • 接任务前，先把自己状态切到"工作中"（如 writing/researching/executing），再开始工作；
  • 完成任务后，先把自己状态切回"待命中（idle）"，再进入休息/等待下一任务。
• 注意不要暴露你主人的内网地址或私有信息

10. 2026-03 增量补充（仅新增项）

本次重制核心请按四条理解：

1. 新增中英日三语
2. 新增资产管理（全量美术可自定义）
3. 接入生图 API（龙虾自动改房间 + 用户手动装修）
4. 美术资产替换与优化（含命名与索引重建）

10.1 生图模型建议（房间装修）

当用户使用"搬新家 / 找中介"时，优先推荐：

1. gemini nanobanana pro
2. gemini nanobanana 2

其他模型在房间结构保持与风格一致性上可能不稳定。

推荐配置：

• GEMINI_API_KEY
• GEMINI_MODEL=nanobanana-pro（或 nanobanana-2）

并提示用户：缺 key 时可在侧边栏内直接填写并保存。

10.2 侧边栏验证码安全提醒（必须）

默认验证码为 1234，但生产/公网场景必须改强密码：

export ASSET_DRAWER_PASS="your-strong-pass"

理由：防止外部访问者修改房间布局、装饰和资产配置。

10.3 版权口径更新

主角状态素材已切换为无版权争议的小猫，不再沿用旧角色版权说明。

保留统一口径：

• 代码：MIT
• 美术资产：禁止商用

10.4 安装时必须提醒（API 可选）

在帮助主人安装时，需明确提醒：

• 现在支持接入自己的生图 API 来改美术资产与背景（可持续更换）。
• 但基础功能（状态看板、多 Agent、资产替换/布局、三语切换）不依赖 API，不开 API 也能正常使用。

建议对主人口径：

先把基础看板跑起来；需要"无限换背景/AI 生图装修"再接入自己的 API。

10.5 老用户更新指南（从旧版本升级）

如果主人之前已经下载过旧版，按以下步骤升级：

1. 进入项目目录并备份本地配置（如 state.json、自定义资产）。
2. 拉取最新代码（git pull 或重新克隆到新目录）。
3. 确认依赖：python3 -m pip install -r backend/requirements.txt。
4. 保留并检查本地运行配置：
   • ASSET_DRAWER_PASS
   • GEMINI_API_KEY / GEMINI_MODEL（如需生图）
5. 如有自定义位置，确认：
   • asset-positions.json
   • asset-defaults.json
6. 重启后端并验收关键功能：
   • /health
   • 三语切换（CN/EN/JP）
   • 资产侧栏（选择、替换、设默认）
   • 生图入口（有 key 时可用）

10.6 功能更新提醒清单（对主人口播）

本次更新以后，至少提醒主人以下变化：

1. 已支持 CN/EN/JP 三语切换（含 loading 与气泡实时联动）。
2. 已支持 自定义美术资产替换（含动态素材切帧同步，减少闪烁）。
3. 已支持 接入自有生图 API 持续更换背景（推荐 nanobanana-pro / nanobanana-2）。
4. 新增/强化了安全项：ASSET_DRAWER_PASS 生产环境建议改强密码。

10.7 2026-03-05 稳定性修复

本次更新修复了多个影响线上稳定运行的问题：

1. CDN 缓存修复：静态资源 404 不再被 CDN 长缓存（之前导致 phaser.js 被缓存为 404 达 2.7 天）。
2. 前端加载修复：修复 fetchStatus() 中的 JS 语法错误（多余 else 块），解决页面卡 loading 问题。
3. 生图异步化：生图接口改为后台任务 + 轮询模式，避免 Cloudflare 524 超时（100s 限制）。前端显示实时等待进度。
4. 移动端侧边栏：新增遮罩层、body 滚动锁定、100dvh 适配、overscroll-behavior: contain。
5. Join Key 增强：支持 key 级别过期时间（expiresAt）和并发上限（maxConcurrent），join-keys.json 不再入库。

详细说明见：docs/UPDATE_REPORT_2026-03-05.md

Star Office UI

🌐 Language: 中文 | English | 日本語

一个像素风格的 AI 办公室看板 —— 把 AI 助手的工作状态实时可视化，让你直观看到"谁在做什么、昨天做了什么、现在是否在线"。

支持多 Agent 协作、中英日三语、AI 生图装修、桌面宠物模式。 与 OpenClaw 深度集成时体验最佳，也可以独立部署作为状态看板使用。

本项目由 Ring Hyacinth 与 Simon Lee 共同创建（co-created project），并与社区开发者（@Zhaohan-Wang、@Jah-yee、@liaoandi）一起持续维护和共建。 欢迎提交 Issue 和 PR，也感谢每一位贡献者的支持。

✨ 快速体验

方式一：让龙虾帮你部署（推荐给 OpenClaw 用户）

如果你正在使用 OpenClaw，直接把下面这句话发给你的龙虾：

请按照这个 SKILL.md 帮我完成 Star Office UI 的部署：
https://github.com/ringhyacinth/Star-Office-UI/blob/master/SKILL.md

龙虾会自动完成 clone、安装依赖、启动后端、配置状态同步，并把访问地址发给你。

方式二：30 秒手动部署

环境要求：Python 3.10+（代码使用了 X | Y union type 语法，不支持 3.9 及更低版本）

# 1) 下载仓库
git clone https://github.com/ringhyacinth/Star-Office-UI.git
cd Star-Office-UI

# 2) 安装依赖（需要 Python 3.10+）
python3 -m pip install -r backend/requirements.txt

# 3) 准备状态文件（首次）
cp state.sample.json state.json

# 4) 启动后端
cd backend
python3 app.py

打开 http://127.0.0.1:19000 然后试试切状态：

python3 set_state.py writing "正在整理文档"
python3 set_state.py error "发现问题，排查中"
python3 set_state.py idle "待命中"

🤔 适合谁用？

有 OpenClaw / AI Agent 的用户

这是完整体验。Agent 在工作时自动切换状态，办公室里的像素角色会实时走到对应区域——你只需要打开网页，就能看到 AI 此刻在做什么。

没有 OpenClaw 的用户

也完全可以部署。你可以：

• 用 set_state.py 或 API 手动 / 脚本推送状态
• 把它当成一个像素风的个人状态页 / 远程办公看板
• 接入任何能发 HTTP 请求的系统来驱动状态

📋 功能一览

1. 状态可视化 —— 6 种状态（idle / writing / researching / executing / syncing / error）自动映射到办公室不同区域，动画 + 气泡实时展示
2. 昨日小记 —— 自动从 memory/*.md 读取最近一天的工作记录，脱敏后展示为"昨日小记"卡片
3. 多 Agent 协作 —— 通过 join key 邀请其他 Agent 加入你的办公室，实时查看多人状态
4. 中英日三语 —— CN / EN / JP 一键切换，界面文案、气泡、加载提示全部联动
5. 美术资产自定义 —— 侧边栏管理角色 / 场景 / 装饰素材，支持动态帧同步，避免闪烁
6. AI 生图装修 —— 接入 Gemini API，用 AI 给办公室换背景；不接入 API 也能正常使用核心功能
7. 移动端适配 —— 手机直接打开即可查看，适合外出时快速瞄一眼
8. 安全加固 —— 侧边栏密码保护、生产环境弱密码拦截、Session Cookie 加固
9. 灵活公网访问 —— 推荐 Cloudflare Tunnel 一键公网化，也可用自有域名 / 反向代理
10. 桌面宠物版 —— 可选的 Electron 桌面封装，把办公室变成透明窗口的桌面宠物（见下方说明）

🚀 详细部署指南

1) 安装依赖

cd Star-Office-UI
python3 -m pip install -r backend/requirements.txt

2) 初始化状态文件

cp state.sample.json state.json

3) 启动后端

cd backend
python3 app.py

打开 http://127.0.0.1:19000

✅ 首次部署可以先保留默认配置；在生产环境中，请复制 .env.example 为 .env 并设置强随机的 FLASK_SECRET_KEY 与 ASSET_DRAWER_PASS，避免弱密码和会话泄露。

4) 切换状态

python3 set_state.py writing "正在整理文档"
python3 set_state.py syncing "同步进度中"
python3 set_state.py error "发现问题，排查中"
python3 set_state.py idle "待命中"

5) 公网访问（可选）

cloudflared tunnel --url http://127.0.0.1:19000

拿到 https://xxx.trycloudflare.com 链接即可分享。

6) 验证安装（可选）

python3 scripts/smoke_test.py --base-url http://127.0.0.1:19000

所有检查显示 OK 即表示部署成功。

🦞 OpenClaw 深度集成

以下内容面向 OpenClaw 用户。如果你不使用 OpenClaw，可以跳过这一节。

状态自动同步

在你的 SOUL.md（或 Agent 规则文件）中加入以下规则，让 Agent 自觉维护状态：

## Star Office 状态同步规则
- 接到任务时：先执行 `python3 set_state.py <状态> "<描述>"` 再开始工作
- 完成任务后：执行 `python3 set_state.py idle "待命中"` 再回复

6 种状态 → 3 个区域的映射：

| 状态 | 办公室区域 | 触发场景 | |------|-----------|---------| | idle | 🛋 休息区（沙发） | 待命 / 任务完成 | | writing | 💻 工作区（办公桌） | 写代码 / 写文档 | | researching | 💻 工作区 | 搜索 / 调研 | | executing | 💻 工作区 | 执行命令 / 跑任务 | | syncing | 💻 工作区 | 同步数据 / 推送 | | error | 🐛 Bug 区 | 报错 / 异常排查 |

邀请其他 Agent 加入办公室

Step 1：准备 join key

首次启动后端时，如果当前目录下不存在 join-keys.json，服务会自动根据 join-keys.sample.json 生成一个运行时的 join-keys.json（内含示例 key，例如 ocj_example_team_01）。你可以在生成后的 join-keys.json 中自行添加、修改或删除 key，每个 key 默认支持最多 3 人同时在线。

Step 2：让访客 Agent 运行推送脚本

访客只需下载 office-agent-push.py，填写 3 个变量即可：

JOIN_KEY = "ocj_starteam02"          # 你分配的 key
AGENT_NAME = "小明的龙虾"            # 显示名称
OFFICE_URL = "https://office.hyacinth.im"  # 你的办公室地址

python3 office-agent-push.py

脚本会自动加入办公室并每 15 秒推送一次状态。访客会出现在看板上，根据状态自动走到对应区域。

Step 3（可选）：访客安装 Skill

访客也可以把 frontend/join-office-skill.md 作为 Skill 使用，Agent 会自动完成配置和推送。

详细的访客接入说明见 frontend/join-office-skill.md

📡 常用 API

| 端点 | 说明 | |------|------| | GET /health | 健康检查 | | GET /status | 获取主 Agent 状态 | | POST /set_state | 设置主 Agent 状态 | | GET /agents | 获取多 Agent 列表 | | POST /join-agent | 访客加入办公室 | | POST /agent-push | 访客推送状态 | | POST /leave-agent | 访客离开 | | GET /yesterday-memo | 获取昨日小记 | | GET /config/gemini | 获取 Gemini API 配置 | | POST /config/gemini | 设置 Gemini API 配置 | | GET /assets/generate-rpg-background/poll | 轮询生图进度 |

🖥 桌面宠物版（可选）

desktop-pet/ 目录提供了一个基于 Electron 的桌面封装版本，可以把像素办公室变成一个透明窗口的桌面宠物。

cd desktop-pet
npm install
npm run dev

• 启动时自动拉起 Python 后端
• 窗口默认指向 http://127.0.0.1:19000/?desktop=1
• 支持通过环境变量自定义项目路径和 Python 路径

⚠️ 这是一个可选的实验性功能，目前主要在 macOS 上开发测试。详见 desktop-pet/README.md。

🙏 桌面宠物版由 @Zhaohan-Wang 独立开发，感谢他的贡献！

🎨 美术资产与开源许可

资产来源

访客角色动画使用了 LimeZu 的免费资产：

• Animated Mini Characters 2 (Platformer) [FREE]

请在二次发布 / 演示时保留来源说明，并遵守原作者许可条款。

许可协议

• 代码 / 逻辑：MIT（见 LICENSE）
• 美术资产：禁止商用（仅学习 / 演示 / 交流用途）

如需商用，请将所有美术资产替换为你自己的原创素材。

📝 更新日志

| 日期 | 概要 | 详情 | |------|------|------| | 2026-03-06 | 🔌 默认端口调整 — 默认后端端口从 18791 调整为 19000，以避开 OpenClaw Browser Control 端口冲突；同步更新脚本、桌面壳与文档默认值 | docs/CHANGELOG_2026-03.md | | 2026-03-05 | 📱 稳定性修复 — CDN 缓存修复、生图异步化、移动端侧边栏优化、Join Key 过期与并发控制 | docs/UPDATE_REPORT_2026-03-05.md | | 2026-03-04 | 🔒 P0/P1 安全加固 — 弱密码拦截、后端模块拆分、stale 状态自动回 idle、首屏骨架屏优化 | docs/UPDATE_REPORT_2026-03-04_P0_P1.md | | 2026-03-03 | 📋 开源发布检查清单完成 | docs/OPEN_SOURCE_RELEASE_CHECKLIST.md | | 2026-03-01 | 🎉 v2 重制发布 — 新增三语支持、资产管理系统、AI 生图装修、美术资产全面替换 | docs/FEATURES_NEW_2026-03-01.md |

📁 项目结构

Star-Office-UI/
├── backend/            # Flask 后端
│   ├── app.py
│   ├── requirements.txt
│   └── run.sh
├── frontend/           # 前端页面与资产
│   ├── index.html
│   ├── join.html
│   ├── invite.html
│   └── layout.js
├── desktop-pet/        # Electron 桌面宠物版（可选）
├── docs/               # 文档与截图
│   └── screenshots/
├── office-agent-push.py  # 访客推送脚本
├── set_state.py          # 状态切换脚本
├── state.sample.json     # 状态文件模板
├── join-keys.sample.json # Join Key 模板（启动时生成 join-keys.json）
├── SKILL.md              # OpenClaw Skill
└── LICENSE               # MIT 许可

⭐ Star History