Back to search
star-office-ui
SkillWorks with Claude CodeGitHub
Star Office UI 一键化 Skill:帮主人快速部署像素办公室看板,支持多 Agent 加入、状态可视化、移动端查看与公网访问。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/ringhyacinth--star-office-ui)HTML
<a href="/listings/ringhyacinth--star-office-ui"><img src="/api/listings/ringhyacinth--star-office-ui/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 295 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: star-office-ui
- description: Star Office UI 一键化 Skill:帮主人快速部署像素办公室看板,支持多 Agent 加入、状态可视化、移动端查看与公网访问。
- ---
- # Star Office UI Skill
- 本 Skill 面向想快速帮主人搭建"像素办公室看板"的 OpenClaw(龙虾):
- - 目标:主人只需"看到效果",尽量少问问题
- - 你可以按下面的步骤,一步一步帮主人跑起来并对外访问
- ---
- ## 0. 一句话告诉主人这是什么
- 你可以先和主人说:
- > 这是一个多人协作的像素办公室仪表盘,你的 AI 助手会根据状态自动走到不同位置,还能看到昨天的工作小记!
- ---
- ## 1. 30 秒一键启动(推荐你先做一遍)
- 在你这台机器执行(按顺序):
- ```bash
- # 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. 帮主人切状态体验一下
- 在项目根目录执行:
- ```bash
- # 工作中 → 去办公桌
- 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. 你应主动推荐改成强密码(更安全,防止他人误改资产和布局)。
- 修改方式(示例):
- ```bash
- export ASSET_DRAWER_PASS="your-strong-pass"
- ```
- 如果是长期运行(systemd / pm2 / 容器),请把该环境变量写入服务配置,而不是只在当前 shell 临时设置。
- ---
- ## 4. 生图功能(Gemini)—— 可选
- "搬新家 / 找中介"装修功能需要 Gemini API,但**基础看板不需要**,不装也能正常使用。
- ### 4.1 安装生图脚本环境(首次使用时)
- 仓库已自带生图脚本(`scripts/gemini_image_generate.py`),但运行需要独立的 Python 环境。在项目根目录执行:
- ```bash
- # 创建 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(最快):
- ```bash
- 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`,但生产/公网场景必须改强密码:
- ```bash
- 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`
README.md · README · 295 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Star Office UI
- 🌐 Language: **中文** | [English](./README.en.md) | [日本語](./README.ja.md)
- 
- **一个像素风格的 AI 办公室看板** —— 把 AI 助手的工作状态实时可视化,让你直观看到"谁在做什么、昨天做了什么、现在是否在线"。
- 支持多 Agent 协作、中英日三语、AI 生图装修、桌面宠物模式。
- 与 [OpenClaw](https://github.com/openclaw/openclaw) 深度集成时体验最佳,也可以独立部署作为状态看板使用。
- > 本项目由 **[Ring Hyacinth](https://x.com/ring_hyacinth)** 与 **[Simon Lee](https://x.com/simonxxoo)** 共同创建(co-created project),并与社区开发者([@Zhaohan-Wang](https://github.com/Zhaohan-Wang)、[@Jah-yee](https://github.com/Jah-yee)、[@liaoandi](https://github.com/liaoandi))一起持续维护和共建。
- > 欢迎提交 Issue 和 PR,也感谢每一位贡献者的支持。
- ---
- ## ✨ 快速体验
- ### 方式一:让龙虾帮你部署(推荐给 OpenClaw 用户)
- 如果你正在使用 [OpenClaw](https://github.com/openclaw/openclaw),直接把下面这句话发给你的龙虾:
- ```text
- 请按照这个 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 及更低版本)
- ```bash
- # 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** 然后试试切状态:
- ```bash
- 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) 安装依赖
- ```bash
- cd Star-Office-UI
- python3 -m pip install -r backend/requirements.txt
- ```
- ### 2) 初始化状态文件
- ```bash
- cp state.sample.json state.json
- ```
- ### 3) 启动后端
- ```bash
- cd backend
- python3 app.py
- ```
- 打开 `http://127.0.0.1:19000`
- > ✅ 首次部署可以先保留默认配置;在生产环境中,请复制 `.env.example` 为 `.env` 并设置强随机的 `FLASK_SECRET_KEY` 与 `ASSET_DRAWER_PASS`,避免弱密码和会话泄露。
- ### 4) 切换状态
- ```bash
- python3 set_state.py writing "正在整理文档"
- python3 set_state.py syncing "同步进度中"
- python3 set_state.py error "发现问题,排查中"
- python3 set_state.py idle "待命中"
- ```
- ### 5) 公网访问(可选)
- ```bash
- cloudflared tunnel --url http://127.0.0.1:19000
- ```
- 拿到 `https://xxx.trycloudflare.com` 链接即可分享。
- ### 6) 验证安装(可选)
- ```bash
- python3 scripts/smoke_test.py --base-url http://127.0.0.1:19000
- ```
- 所有检查显示 `OK` 即表示部署成功。
- ---
- ## 🦞 OpenClaw 深度集成
- > 以下内容面向 [OpenClaw](https://github.com/openclaw/openclaw) 用户。如果你不使用 OpenClaw,可以跳过这一节。
- ### 状态自动同步
- 在你的 `SOUL.md`(或 Agent 规则文件)中加入以下规则,让 Agent 自觉维护状态:
- ```markdown
- ## 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 个变量即可:
- ```python
- JOIN_KEY = "ocj_starteam02" # 你分配的 key
- AGENT_NAME = "小明的龙虾" # 显示名称
- OFFICE_URL = "https://office.hyacinth.im" # 你的办公室地址
- ```
- ```bash
- python3 office-agent-push.py
- ```
- 脚本会自动加入办公室并每 15 秒推送一次状态。访客会出现在看板上,根据状态自动走到对应区域。
- **Step 3(可选):访客安装 Skill**
- 访客也可以把 `frontend/join-office-skill.md` 作为 Skill 使用,Agent 会自动完成配置和推送。
- > 详细的访客接入说明见 [`frontend/join-office-skill.md`](./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** 的桌面封装版本,可以把像素办公室变成一个透明窗口的桌面宠物。
- ```bash
- cd desktop-pet
- npm install
- npm run dev
- ```
- - 启动时自动拉起 Python 后端
- - 窗口默认指向 `http://127.0.0.1:19000/?desktop=1`
- - 支持通过环境变量自定义项目路径和 Python 路径
- > ⚠️ 这是一个**可选的实验性功能**,目前主要在 macOS 上开发测试。详见 [`desktop-pet/README.md`](./desktop-pet/README.md)。
- >
- > 🙏 桌面宠物版由 [@Zhaohan-Wang](https://github.com/Zhaohan-Wang) 独立开发,感谢他的贡献!
- ---
- ## 🎨 美术资产与开源许可
- ### 资产来源
- 访客角色动画使用了 **LimeZu** 的免费资产:
- - [Animated Mini Characters 2 (Platformer) [FREE]](https://limezu.itch.io/animated-mini-characters-2-platform-free)
- 请在二次发布 / 演示时保留来源说明,并遵守原作者许可条款。
- ### 许可协议
- - **代码 / 逻辑:MIT**(见 [`LICENSE`](./LICENSE))
- - **美术资产:禁止商用**(仅学习 / 演示 / 交流用途)
- > 如需商用,请将所有美术资产替换为你自己的原创素材。
- ---
- ## 📝 更新日志
- | 日期 | 概要 | 详情 |
- |------|------|------|
- | 2026-03-06 | 🔌 默认端口调整 — 默认后端端口从 18791 调整为 19000,以避开 OpenClaw Browser Control 端口冲突;同步更新脚本、桌面壳与文档默认值 | [`docs/CHANGELOG_2026-03.md`](./docs/CHANGELOG_2026-03.md) |
- | 2026-03-05 | 📱 稳定性修复 — CDN 缓存修复、生图异步化、移动端侧边栏优化、Join Key 过期与并发控制 | [`docs/UPDATE_REPORT_2026-03-05.md`](./docs/UPDATE_REPORT_2026-03-05.md) |
- | 2026-03-04 | 🔒 P0/P1 安全加固 — 弱密码拦截、后端模块拆分、stale 状态自动回 idle、首屏骨架屏优化 | [`docs/UPDATE_REPORT_2026-03-04_P0_P1.md`](./docs/UPDATE_REPORT_2026-03-04_P0_P1.md) |
- | 2026-03-03 | 📋 开源发布检查清单完成 | [`docs/OPEN_SOURCE_RELEASE_CHECKLIST.md`](./docs/OPEN_SOURCE_RELEASE_CHECKLIST.md) |
- | 2026-03-01 | 🎉 **v2 重制发布** — 新增三语支持、资产管理系统、AI 生图装修、美术资产全面替换 | [`docs/FEATURES_NEW_2026-03-01.md`](./docs/FEATURES_NEW_2026-03-01.md) |
- ---
- ## 📁 项目结构
- ```text
- 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
- [](https://www.star-history.com/?repos=ringhyacinth%2FStar-Office-UI&type=date&legend=top-left)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.