Star Office UI

一个面向多 Agent 协作的像素办公室看板：把 AI 助手（OpenClaw / 龙虾）的工作状态实时可视化，帮助团队直观看到“谁在做什么、昨天做了什么、现在是否在线”。

本项目为 Ring Hyacinth 与 Simon Lee 的共同项目（co-created project）。

---

这是个什么项目？（一句话）

Star Office UI 是一个“多人协作状态看板”——你可以把它想象成：

一个实时更新的“像素办公室仪表盘”：你的 AI 助手（和你邀请的其他 Agent）会根据状态自动走到不同位置（休息区 / 工作区 / bug 区），你还能看到他们昨天的工作小记。

---

✨ 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) （推荐）准备本地环境变量
cp .env.example .env
# 然后编辑 .env：至少设置 FLASK_SECRET_KEY 与 ASSET_DRAWER_PASS

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

打开：http://127.0.0.1:18791

切状态试试（在项目根目录执行）：

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

---

1、这个项目实现了什么

Star Office UI 目前实现了：

1. 可视化龙虾工作状态

   • 状态：idle（闲置）、writing（工作）、researching（研究）、executing（执行）、syncing（同步）、error（报 bug）
   • 状态会映射到办公室里的不同区域，并通过动画/气泡展示。

2. “昨日小记”微型总结

   • 前端展示“昨日小记”卡片。
   • 后端从 memory/*.md 中读取昨天（或最近可用）的记录，做基础脱敏后展示。

3. 支持邀请其他访客加入办公室（功能持续迭代中）

   • 通过 join key 加入。
   • 访客可持续 push 自己状态到办公室看板。
   • 当前已可用，但整体仍在持续优化交互与接入体验。

4. 已适配手机端访问

   • 移动端可直接打开与查看状态（适合外出时快速查看）。

5. 支持中英日三语切换

   • 已支持 CN / EN / JP 三语切换。
   • 语言切换会实时作用于界面文案、加载提示与角色气泡。

6. 支持自定义美术资产

   • 支持在资产侧边栏替换角色/场景素材。
   • 支持动态素材重切帧与参数同步（frame size / frame range）以避免闪烁。

7. 支持接入自己的生图 API（可无限换背景）

   • 支持接入自有生图 API 进行“搬新家/找中介”式背景更新。
   • 推荐模型：nanobanana-pro 或 nanobanana-2（结构保持更稳定）。
   • 基础看板功能不依赖 API；不接入 API 也可正常使用核心状态看板与资产管理。

8. 公网访问方式灵活

   • Skill 默认建议使用 Cloudflare Tunnel 快速公网化。
   • 也可以使用你自己的公网域名 / 反向代理方案。

---

2、本次重制（2026-03）核心变化

本次版本不是零散修补，而是基于原项目的一次完整重制。核心变化集中在以下 4 个方向：

1. 新增中英日三语（CN / EN / JP）

   • 全局界面文案三语化
   • 状态文案、提示文案、资产显示名可联动切换

2. 新增资产管理功能（用户可自定义全量美术资产）

   • 资产侧边栏支持选择、替换、默认值管理
   • 用户可自定义角色、场景、装饰、按钮等素材

3. 接入生图 API（支持房间智能装修 + 用户手动装修）

   • 支持“搬新家 / 找中介 / 自己装”等装修流
   • 龙虾可基于生图能力更换房间设计，用户也可手动输入主题改造

4. 美术资产替换与优化（重点）

   • 核心资产完成大规模替换与重绘
   • 重建资产命名与索引映射，提升替换稳定性与维护性
   • 动态素材切帧与展示逻辑优化，减少错帧/缓存干扰

---

3、快速开始

1) 安装依赖

cd star-office-ui
python3 -m pip install -r backend/requirements.txt

2) 初始化状态文件

cp state.sample.json state.json

3) （推荐）准备本地环境变量

cp .env.example .env
# 编辑 .env：至少设置 FLASK_SECRET_KEY 与 ASSET_DRAWER_PASS

4) 启动后端

cd backend
python3 app.py

打开：http://127.0.0.1:18791

4) 切换主 Agent 状态（示例）

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

---

3.1、安全自检（推荐上线前执行）

python3 scripts/security_check.py

• 返回 Result: OK 才建议进入公网部署。
• 在生产模式（STAR_OFFICE_ENV=production）下，请务必配置强密码：
  • FLASK_SECRET_KEY（>=24 位随机字符串）
  • ASSET_DRAWER_PASS（不要使用 1234）

3.2、真实状态自动采集（避免手动切状态）

默认推荐使用 office-agent-push.py 持续推送本地 state.json，无需每次手动改地图状态。

• 优先读取：/root/.openclaw/workspace/Star-Office-UI/state.json
• 若本地状态长期未更新，会自动回 idle（避免“假工作中”）
• 可用环境变量调节过期阈值（秒）：

export OFFICE_STALE_STATE_TTL=600

---

4、常用 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：昨日小记

---

5、美术资产使用说明（请务必阅读）

访客角色资产来源

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

• Animated Mini Characters 2 (Platformer) [FREE]
• https://limezu.itch.io/animated-mini-characters-2-platform-free

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

商用限制（重要）

• 代码玩法可以基于 MIT 使用与二次开发。
• 本仓库所有美术资产（含主角色/场景/素材整包）禁止商用。
• 若你要做商用，请务必制作并替换成你自己的原创美术资产。

---

6、开源许可与声明

• Code / Logic：MIT（见 LICENSE）
• Art Assets：非商用，仅学习/演示用途

欢迎 Fork、交流玩法、提 PR；但请严格遵守资产使用边界。

---

7、期待更多玩法交流

欢迎你基于这个框架扩展：

• 更丰富的状态语义与自动编排
• 多房间/多团队协作地图
• 任务看板、时间线、日报自动生成
• 更完整的访问控制与权限体系

如果你做了有趣改造，欢迎分享！

---

8、项目作者

本项目由 Ring Hyacinth 与 Simon Lee 共同创作与维护。

9、作者社交账号

• X：Ring Hyacinth (@ring_hyacinth)
  https://x.com/ring_hyacinth
• X：Simon Lee (@simonxxoo)
  https://x.com/simonxxoo

---

项目结构（简版）

star-office-ui/
  backend/
    app.py
    requirements.txt
    run.sh
  frontend/
    index.html
    join.html
    invite.html
    layout.js
    ...assets
  docs/
    screenshots/
  scripts/
    security_check.py
  office-agent-push.py
  set_state.py
  state.sample.json
  join-keys.sample.json
  .env.example
  SKILL.md
  README.md
  LICENSE

---

---

---

Star Office UI

A pixel office dashboard for multi-agent collaboration: visualize your AI assistants’ (OpenClaw / "lobster") work status in real-time, helping the team intuitively see "who is doing what, what they did yesterday, and whether they are online now."

This project is a co-created work by Ring Hyacinth and Simon Lee.

---

What is this project? (In one sentence)

Star Office UI is a "multi-person collaboration status dashboard"—think of it as:

A real-time "pixel office dashboard": your AI assistants (and other agents you invite) automatically move to different areas based on their status (breakroom / desk / bug area), and you can also see a micro-summary of their work from yesterday.

---

✨ 30-second Quick Start (Recommended)

# 1) Clone repository
git clone https://github.com/ringhyacinth/Star-Office-UI.git
cd Star-Office-UI

# 2) Install dependencies
python3 -m pip install -r backend/requirements.txt

# 3) Initialize state file (first run)
cp state.sample.json state.json

# 4) (Recommended) prepare local env file
cp .env.example .env
# Then edit .env: set at least FLASK_SECRET_KEY and ASSET_DRAWER_PASS

# 5) Start backend
cd backend
python3 app.py

Open: http://127.0.0.1:18791

Try changing states (run from project root):

python3 set_state.py writing "Organizing documents"
python3 set_state.py syncing "Syncing progress"
python3 set_state.py error "Found an issue, debugging"
python3 set_state.py idle "Standing by"

---

I. What does this project do?

Star Office UI currently provides:

1. Visualize lobster work status

   • States: idle, writing, researching, executing, syncing, error
   • States map to different areas in the office and are shown with animations / bubbles.

2. "Yesterday Memo" micro-summary

   • A "Yesterday Memo" card in the UI.
   • Backend reads yesterday’s (or most recent available) records from memory/*.md and displays them after basic privacy sanitization.

3. Support inviting other guests to join the office (feature ongoing)

   • Join via join key.
   • Guests can continuously push their status to the office dashboard.
   • Currently usable, but overall interaction and onboarding experience are still being optimized.

4. Mobile-friendly access

   • Mobile devices can directly open and view status (great for quick checks on the go).

5. Flexible public access options

   • Skill defaults to using Cloudflare Tunnel for quick public access.
   • You can also use your own public domain / reverse proxy setup.

---

II. Main changes in this update

This release adds/upgrades the following compared to the early base version:

• Added multi-agent mechanism: /join-agent, /agent-push, /leave-agent, /agents
• Added "Yesterday Memo" endpoint and UI: /yesterday-memo
• More complete state system: supports visualization for syncing, error, etc.
• Scene and character animation upgrade: added lots of pixel art assets (including guest roles)
• Rewrote docs and Skill: more beginner-friendly for external programmers
• Cleaned up release structure: removed temp files / cache / logs to lower comprehension barrier
• Added open-source notice: code under MIT, but art assets are non-commercial

---

III. Quick Start

1) Install dependencies

cd star-office-ui
python3 -m pip install -r backend/requirements.txt

2) Initialize state file

cp state.sample.json state.json

3) (Recommended) prepare local env file

cp .env.example .env
# Then edit .env: set at least FLASK_SECRET_KEY and ASSET_DRAWER_PASS

4) Start backend

cd backend
python3 app.py

Open: http://127.0.0.1:18791

4) Switch main Agent status (example)

python3 set_state.py writing "Organizing documents"
python3 set_state.py syncing "Syncing progress"
python3 set_state.py error "Found an issue, debugging"
python3 set_state.py idle "Standing by"

---

III.1 Security preflight (recommended before public deployment)

python3 scripts/security_check.py

• Only deploy publicly when it returns Result: OK.
• In production mode (STAR_OFFICE_ENV=production), set strong values for:
  • FLASK_SECRET_KEY (>=24 random chars)
  • ASSET_DRAWER_PASS (do not use 1234)

---

IV. Common APIs

• GET /health: Health check
• GET /status: Main agent status
• POST /set_state: Set main agent status
• GET /agents: Get multi-agent list
• POST /join-agent: Guest joins
• POST /agent-push: Guest pushes status
• POST /leave-agent: Guest leaves
• GET /yesterday-memo: Yesterday Memo

---

V. Art Asset Usage Notes (Please Read)

Guest character asset source

Guest character animations use LimeZu’s free assets:

• Animated Mini Characters 2 (Platformer) [FREE]
• https://limezu.itch.io/animated-mini-characters-2-platform-free

Please keep the source attribution and follow the original author’s license terms when redistributing / demonstrating.

Other asset notes & disclaimer (Important)

• Main character (Starmie) & homophone note:

  • “Starmie” is an existing character IP from Nintendo/Pokémon, not original to this project.
  • This project is non-commercial fan creation only: this character was chosen because of a fun homophone between “Starmie” and the author’s Chinese name “海辛” (Hǎi Xīn).
  • All fan-created content in this project is for learning, demonstration, and idea sharing only, with no commercial use.
  • Nintendo, Pokémon, and “Starmie” are trademarks or registered trademarks of Nintendo/The Pokémon Company.
  • If you plan to use any content related to this project, please use your own original characters/art assets.

• Office scene & other assets: created by the project author team.

Commercial restriction (Important)

• Code/logic may be used and modified under MIT.
• All art assets in this repo (including main character / scene / full pack) are NOT for commercial use.
• If you want to use this commercially, please create and replace with your own original art assets.

---

VI. Open-source License & Notice

• Code / Logic: MIT (see LICENSE)
• Art Assets: non-commercial, for learning / demo only

Forks, idea sharing, and PRs are welcome; please strictly respect the asset usage boundaries.

---

VII. Looking forward to more idea sharing

Feel free to extend this framework with:

• Richer state semantics and auto-orchestration
• Multi-room / multi-team collaboration maps
• Task boards, timelines, auto-generated daily reports
• More complete access control and permission systems

If you make an interesting modification, please share!

---

VIII. Author social accounts

• X: Ring Hyacinth (@ring_hyacinth)
  https://x.com/ring_hyacinth
• X: Simon Lee (@simonxxoo)
  https://x.com/simonxxoo

---

Project structure (simplified)

star-office-ui/
  backend/
    app.py
    requirements.txt
    run.sh
  frontend/
    index.html
    join.html
    invite.html
    layout.js
    ...assets
  docs/
    screenshots/
  scripts/
    security_check.py
  office-agent-push.py
  set_state.py
  state.sample.json
  join-keys.sample.json
  .env.example
  SKILL.md
  README.md
  LICENSE

---

10、2026-03 增量更新（在原版基础上补充）

本节仅记录“新增/变化”，其余内容保持原版结构不变。

A) 房间装修生图模型推荐（新增）

在“搬新家 / 找中介”能力中，建议优先接入你自己的 Gemini 并使用：

1. gemini nanobanana pro
2. gemini nanobanana 2

其他模型在“保持原房间结构 + 风格迁移一致性”上可能不如预期。

建议配置：

• GEMINI_API_KEY
• GEMINI_MODEL（建议 nanobanana-pro 或 nanobanana-2）

此外，项目已支持运行时配置入口：

• GET /config/gemini
• POST /config/gemini

当 API key 缺失时，侧边栏会出现填写入口，用户可直接补填后重试。

B) 资产编辑侧边栏验证码（新增）

侧边栏可以修改布局、装饰、默认位置。

当前默认值：

• ASSET_DRAWER_PASS=1234

推荐引导用户口径：

1. 默认密码 1234 可先用于体验；
2. 用户可随时和你沟通修改密码；
3. 建议尽快改成强密码，这样更安全。

示例：

export ASSET_DRAWER_PASS="your-strong-pass"

必要性：

• 防止拿到访问链接的人修改你的房间布局与素材。

C) 安装成功后给主人的三条提醒（新增）

1. 临时公网链接

   • 将 trycloudflare 临时链接发给主人；
   • 并告知后续可继续部署到本地域名，你可以一步步带他操作。

2. 装修房子入口

   • 提醒主人可点击“装修房间”开始；
   • 默认密码 1234；
   • 主人若想改密码，可随时告诉你，你来协助修改；
   • 建议改成强密码。

3. 生图 API 配置

   • 生图需要使用用户自己的 API；
   • 当前接入是 Gemini 官方 API 格式与地址；
   • 若需改为其他 API 类型，请先沟通并提供相关 API 文档，便于你适配。

D) 运行状态使用建议（新增）

建议 Agent 主动维护自己的状态：

1. 接任务前，先切换到“工作中”（如 writing / researching / executing），再开始执行任务；
2. 完成任务后，先切换到“待命中（idle）”，再进入休息/等待下一任务。

这样主人在办公室看板里看到的状态会更真实、连续。

E) 美术与版权口径更新（重要）

本次重制重点之一是美术资产系统升级（大规模替换 + 命名与索引重建）。

保留原则：

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