docs: restructure README — dual quick-start paths, audience section, community co-maintenance

This commit is contained in:
Star 2026-03-06 17:51:24 +08:00
parent bb02d21e88
commit e7e08b54e4
3 changed files with 138 additions and 110 deletions

View file

@ -4,13 +4,30 @@
![Star Office UI Cover](docs/screenshots/readme-cover-2.jpg)
**A pixel office dashboard for multi-agent collaboration** — visualize your AI assistants' (OpenClaw / "lobster") work status in real time, so you can see at a glance who's doing what, what they did yesterday, and whether they're online.
**A pixel-art AI office dashboard** — visualize your AI assistant's work status in real time, so you can see at a glance who's doing what, what they did yesterday, and whether they're online.
> This is a **co-created project by Ring Hyacinth and Simon Lee**.
Supports multi-agent collaboration, trilingual UI (CN/EN/JP), AI-powered room design, and desktop pet mode.
Best experienced with [OpenClaw](https://openclaw.com), but also works standalone as a status dashboard.
> This project was co-created by **[Ring Hyacinth](https://x.com/ring_hyacinth)** and **[Simon Lee](https://x.com/simonxxoo)**, and is continuously maintained and improved together with community contributors.
> Issues and PRs are welcome — thank you to everyone who contributes.
---
## ✨ 30-Second Quick Start
## ✨ Quick Start
### Option 1: Let your lobster deploy it (recommended for OpenClaw users)
If you're using [OpenClaw](https://openclaw.com), just send this to your lobster:
```text
Please follow this SKILL.md to deploy Star Office UI for me:
https://github.com/ringhyacinth/Star-Office-UI/blob/master/SKILL.md
```
Your lobster will automatically clone the repo, install dependencies, start the backend, configure status sync, and send you the access URL.
### Option 2: 30-second manual setup
```bash
# 1) Clone the repo
@ -40,6 +57,19 @@ python3 set_state.py idle "Standing by"
---
## 🤔 Who is this for?
### Users with OpenClaw / an AI Agent
This is the **full experience**. Your agent automatically switches status as it works, and the pixel character walks to the corresponding office area in real time — just open the page and see what your AI is doing right now.
### Users without OpenClaw
You can still deploy and use it. You can:
- Use `set_state.py` or the API to push status manually or via scripts
- Use it as a pixel-art personal status page or remote work dashboard
- Connect any system that can send HTTP requests to drive the status
---
## 📋 Features
1. **Status Visualization** — 6 states (`idle` / `writing` / `researching` / `executing` / `syncing` / `error`) mapped to different office areas with animated sprites and speech bubbles
@ -47,7 +77,7 @@ python3 set_state.py idle "Standing by"
3. **Multi-Agent Collaboration** — Invite other agents to join your office via join keys and see everyone's status in real time
4. **Trilingual UI** — Switch between Chinese, English, and Japanese with one click; all UI text, bubbles, and loading messages update instantly
5. **Custom Art Assets** — Manage characters, scenes, and decorations through the sidebar; dynamic frame sync prevents flickering
6. **AI-Powered Room Design** — Connect your own Gemini API to generate new office backgrounds (recommended: `nanobanana-pro` / `nanobanana-2`); core features work fine without an API
6. **AI-Powered Room Design** — Connect your own Gemini API to generate new office backgrounds; core features work fine without an API
7. **Mobile-Friendly** — Open on your phone for a quick status check on the go
8. **Security Hardening** — Sidebar password protection, weak-password blocking in production, hardened session cookies
9. **Flexible Public Access** — Use Cloudflare Tunnel for instant public access, or bring your own domain / reverse proxy
@ -55,7 +85,7 @@ python3 set_state.py idle "Standing by"
---
## 🚀 Getting Started
## 🚀 Detailed Setup Guide
### 1) Install dependencies
@ -100,33 +130,21 @@ Share the `https://xxx.trycloudflare.com` link with anyone.
### 6) Verify your installation (optional)
While the backend is running, you can run a lightweight smoke test to confirm that the core endpoints are healthy:
```bash
python3 scripts/smoke_test.py --base-url http://127.0.0.1:19000
```
If all checks report `OK`, your Star Office UI service is wired up correctly for basic status flows.
If all checks report `OK`, your deployment is good to go.
---
## 🦞 For OpenClaw Users
## 🦞 OpenClaw Deep Integration
> If you're using [OpenClaw](https://openclaw.com), these three steps deeply integrate your lobster with the pixel office.
> The following section is for [OpenClaw](https://openclaw.com) users. If you don't use OpenClaw, feel free to skip this.
### 4.1 Install the Skill
### Automatic Status Sync
Copy `SKILL.md` from the repo into your OpenClaw workspace:
```bash
cp SKILL.md ~/.openclaw/workspace/SKILL.md
```
Your lobster will read it automatically and follow the deployment guide — starting the backend, setting up a public link, and prompting you for passwords and API keys.
### 4.2 Automatic Status Sync
Add the following rule to your `SOUL.md` (or agent config) so your lobster updates its status automatically:
Add the following rule to your `SOUL.md` (or agent config) so your agent updates its status automatically:
```markdown
## Star Office Status Sync Rules
@ -145,7 +163,7 @@ Add the following rule to your `SOUL.md` (or agent config) so your lobster updat
| `syncing` | 💻 Workspace | Syncing data / pushing |
| `error` | 🐛 Bug Corner | Error / debugging |
### 4.3 Invite Other Lobsters to Your Office
### Invite Other Agents to Your Office
**Step 1: Prepare join keys**
@ -165,11 +183,11 @@ OFFICE_URL = "https://office.hyacinth.im" # Your office URL
python3 office-agent-push.py
```
The script auto-joins and pushes status every 15 seconds. The guest's lobster will appear on the dashboard, moving to the appropriate area based on its state.
The script auto-joins and pushes status every 15 seconds. The guest will appear on the dashboard, moving to the appropriate area based on their state.
**Step 3 (optional): Guest installs a Skill**
Guests can also use `frontend/join-office-skill.md` as a Skill — their lobster will handle setup and pushing automatically.
Guests can also use `frontend/join-office-skill.md` as a Skill — their agent will handle setup and pushing automatically.
> See [`frontend/join-office-skill.md`](./frontend/join-office-skill.md) for full guest onboarding instructions.
@ -229,15 +247,6 @@ Please keep attribution when redistributing or demoing, and follow the original
---
## 👥 Authors
This project is co-created and maintained by **Ring Hyacinth** and **Simon Lee**.
- **Ring Hyacinth** — [@ring_hyacinth](https://x.com/ring_hyacinth)
- **Simon Lee** — [@simonxxoo](https://x.com/simonxxoo)
---
## 📝 Changelog
| Date | Summary | Details |

View file

@ -4,13 +4,30 @@
![Star Office UI カバー](docs/screenshots/readme-cover-2.jpg)
**マルチ Agent 協調のためのピクセル・オフィス・ダッシュボード** —— AI アシスタントOpenClaw / ロブスター)の作業状態をリアルタイムで可視化し、「誰が何をしているか」「昨日何をしたか」「今オンラインか」を直感的に把握できます。
**ピクセルアート風 AI オフィスダッシュボード** —— AI アシスタントの作業状態をリアルタイムで可視化し、「誰が何をしているか」「昨日何をしたか」「今オンラインか」を直感的に把握できます。
> 本プロジェクトは **Ring Hyacinth と Simon Lee の共同制作co-created project** です。
マルチ Agent 協調、中英日 3 言語、AI 画像生成による模様替え、デスクトップペットモードに対応。
[OpenClaw](https://openclaw.com) との統合で最高の体験が得られますが、単体でもステータスダッシュボードとして利用可能です。
> 本プロジェクトは **[Ring Hyacinth](https://x.com/ring_hyacinth)** と **[Simon Lee](https://x.com/simonxxoo)** の共同制作co-created projectであり、コミュニティの開発者とともに継続的にメンテナンス・改善を行っています。
> Issue や PR を歓迎します。貢献してくださるすべての方に感謝いたします。
---
## ✨ 30 秒クイックスタート
## ✨ クイックスタート
### 方法 1ロブスターにデプロイしてもらうOpenClaw ユーザー向け)
[OpenClaw](https://openclaw.com) をご利用中なら、以下のメッセージをロブスターに送るだけ:
```text
この SKILL.md に従って Star Office UI をデプロイしてください:
https://github.com/ringhyacinth/Star-Office-UI/blob/master/SKILL.md
```
ロブスターが自動的にリポジトリのクローン、依存関係のインストール、バックエンドの起動、ステータス同期の設定を行い、アクセス URL をお知らせします。
### 方法 230 秒手動セットアップ
```bash
# 1) リポジトリをクローン
@ -30,8 +47,6 @@ python3 app.py
**http://127.0.0.1:19000** を開き、状態を切り替えてみましょう:
> ✅ ローカル開発ではデフォルト設定のままで構いませんが、本番環境では `.env.example``.env` にコピーし、`FLASK_SECRET_KEY` と `ASSET_DRAWER_PASS` に十分な長さのランダム値を設定することをおすすめします(弱いパスワードやセッション漏洩を防ぐため)。
```bash
python3 set_state.py writing "ドキュメント整理中"
python3 set_state.py error "問題を検出、調査中"
@ -42,24 +57,27 @@ python3 set_state.py idle "待機中"
---
## ✅ インストール確認(任意)
## 🤔 誰に向いている?
バックエンドが起動している状態で、簡単な smoke test を実行して主要エンドポイントが正常かどうかを確認できます:
### OpenClaw / AI Agent をお持ちの方
これが**フル体験**です。Agent が作業中に自動でステータスを切り替え、ピクセルキャラクターがリアルタイムで対応エリアに移動します。ページを開くだけで、AI が今何をしているかがわかります。
```bash
python3 scripts/smoke_test.py --base-url http://127.0.0.1:19000
```
### OpenClaw をお持ちでない方
デプロイして使うことも全く問題ありません:
- `set_state.py` や API で手動 / スクリプトからステータスを更新
- ピクセルアート風の個人ステータスページやリモートワークダッシュボードとして利用
- HTTP リクエストを送れるシステムなら何でもステータスを駆動可能
すべてのチェックが `OK` と表示されれば、Star Office UI の基本的なステータスフローが正しく動作していることを意味します。
---
## 📋 機能一覧
1. **ステータス可視化** —— 6 種類の状態(`idle` / `writing` / `researching` / `executing` / `syncing` / `error`)がオフィスの各エリアに自動マッピングされ、アニメーションと吹き出しでリアルタイム表示
2. **昨日メモ** —— `memory/*.md` から直近の作業記録を自動取得し、匿名化して「昨日メモ」カードとして表示
3. **マルチ Agent 協調** —— join key で他のロブスターをオフィスに招待し、全員のステータスをリアルタイム確認
3. **マルチ Agent 協調** —— join key で他の Agent をオフィスに招待し、全員のステータスをリアルタイム確認
4. **中英日 3 言語対応** —— CN / EN / JP をワンクリック切替、UI テキスト・吹き出し・ローディング表示すべてが連動
5. **アート資産カスタマイズ** —— サイドバーからキャラクター / 背景 / 装飾素材を管理、動的フレーム同期でちらつき防止
6. **AI 画像生成による模様替え** —— 自前の Gemini API を接続してオフィス背景を AI 生成(推奨: `nanobanana-pro` / `nanobanana-2`; API 未接続でもコア機能は利用可能
6. **AI 画像生成による模様替え** —— Gemini API を接続してオフィス背景を AI 生成; API 未接続でもコア機能は利用可能
7. **モバイル対応** —— スマホからそのまま閲覧可能、外出先からのクイックチェックに最適
8. **セキュリティ強化** —— サイドバーのパスワード保護、本番環境での弱パスワード拒否、Session Cookie 強化
9. **柔軟な公開アクセス** —— Cloudflare Tunnel でワンステップ公開、独自ドメイン / リバースプロキシにも対応
@ -67,7 +85,7 @@ python3 scripts/smoke_test.py --base-url http://127.0.0.1:19000
---
## 🚀 セットアップ
## 🚀 詳細セットアップガイド
### 1) 依存関係インストール
@ -91,6 +109,8 @@ python3 app.py
`http://127.0.0.1:19000` を開く
> ✅ ローカル開発ではデフォルト設定のままで構いませんが、本番環境では `.env.example``.env` にコピーし、`FLASK_SECRET_KEY` と `ASSET_DRAWER_PASS` に十分な長さのランダム値を設定してください。
### 4) ステータス切替
```bash
@ -108,25 +128,23 @@ cloudflared tunnel --url http://127.0.0.1:19000
`https://xxx.trycloudflare.com` のリンクを共有するだけで OK。
---
## 🦞 OpenClaw ユーザー向け
> [OpenClaw](https://openclaw.com) をご利用中なら、以下の 3 ステップでロブスターとピクセルオフィスを深く連携できます。
### 4.1 Skill をインストール
リポジトリ内の `SKILL.md` を OpenClaw のワークスペースにコピーします:
### 6) インストール確認(任意)
```bash
cp SKILL.md ~/.openclaw/workspace/SKILL.md
python3 scripts/smoke_test.py --base-url http://127.0.0.1:19000
```
ロブスターが自動的に読み込み、デプロイガイドに沿ってバックエンド起動・公開リンク設定・パスワードと API の案内まで進めてくれます。
すべてのチェックが `OK` と表示されればデプロイ成功です。
### 4.2 ステータス自動同期
---
`SOUL.md`(またはエージェント設定ファイル)に以下のルールを追加すると、ロブスターがステータスを自動で更新します:
## 🦞 OpenClaw 連携
> 以下は [OpenClaw](https://openclaw.com) ユーザー向けの内容です。OpenClaw を使用していない場合はスキップしてください。
### ステータス自動同期
`SOUL.md`またはエージェント設定ファイルに以下のルールを追加すると、Agent がステータスを自動で更新します:
```markdown
## Star Office ステータス同期ルール
@ -145,7 +163,7 @@ cp SKILL.md ~/.openclaw/workspace/SKILL.md
| `syncing` | 💻 ワークエリア | データ同期 / プッシュ |
| `error` | 🐛 バグコーナー | エラー / デバッグ |
### 4.3 他のロブスターをオフィスに招待
### 他の Agent をオフィスに招待
**Step 1join key を準備**
@ -165,11 +183,11 @@ OFFICE_URL = "https://office.hyacinth.im" # あなたのオフィス URL
python3 office-agent-push.py
```
スクリプトが自動で参加し、15 秒ごとにステータスをプッシュします。ゲストのロブスターがダッシュボードに表示され、状態に応じて該当エリアに移動します。
スクリプトが自動で参加し、15 秒ごとにステータスをプッシュします。ゲストがダッシュボードに表示され、状態に応じて該当エリアに移動します。
**Step 3任意ゲストも Skill をインストール**
ゲストは `frontend/join-office-skill.md` を Skill として使うこともできます。ロブスターが設定とプッシュを自動で行います。
ゲストは `frontend/join-office-skill.md` を Skill として使うこともできます。Agent が設定とプッシュを自動で行います。
> 詳しいゲスト参加手順は [`frontend/join-office-skill.md`](./frontend/join-office-skill.md) を参照。
@ -229,15 +247,6 @@ npm run dev
---
## 👥 プロジェクト作者
本プロジェクトは **Ring Hyacinth****Simon Lee** の共同制作・共同メンテナンスです。
- **Ring Hyacinth** — [@ring_hyacinth](https://x.com/ring_hyacinth)
- **Simon Lee** — [@simonxxoo](https://x.com/simonxxoo)
---
## 📝 更新履歴
| 日付 | 概要 | 詳細 |

View file

@ -4,13 +4,30 @@
![Star Office UI 封面](docs/screenshots/readme-cover-2.jpg)
**一个面向多 Agent 协作的像素办公室看板** —— 把 AI 助手OpenClaw / 龙虾)的工作状态实时可视化,让你直观看到"谁在做什么、昨天做了什么、现在是否在线"。
**一个像素风格的 AI 办公室看板** —— 把 AI 助手的工作状态实时可视化,让你直观看到"谁在做什么、昨天做了什么、现在是否在线"。
> 本项目为 **Ring Hyacinth 与 Simon Lee 的共同项目co-created project**
支持多 Agent 协作、中英日三语、AI 生图装修、桌面宠物模式。
与 [OpenClaw](https://openclaw.com) 深度集成时体验最佳,也可以独立部署作为状态看板使用。
> 本项目由 **[Ring Hyacinth](https://x.com/ring_hyacinth)** 与 **[Simon Lee](https://x.com/simonxxoo)** 共同创建co-created project并与社区开发者一起持续维护和共建。
> 欢迎提交 Issue 和 PR也感谢每一位贡献者的支持。
---
## ✨ 30 秒快速体验
## ✨ 快速体验
### 方式一:让龙虾帮你部署(推荐给 OpenClaw 用户)
如果你正在使用 [OpenClaw](https://openclaw.com),直接把下面这句话发给你的龙虾:
```text
请按照这个 SKILL.md 帮我完成 Star Office UI 的部署:
https://github.com/ringhyacinth/Star-Office-UI/blob/master/SKILL.md
```
龙虾会自动完成 clone、安装依赖、启动后端、配置状态同步并把访问地址发给你。
### 方式二30 秒手动部署
```bash
# 1) 下载仓库
@ -38,16 +55,30 @@ python3 set_state.py idle "待命中"
![Star Office UI 预览](docs/screenshots/readme-cover-1.jpg)
---
## 🤔 适合谁用?
### 有 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 邀请其他龙虾加入你的办公室,实时查看多人状态
3. **多 Agent 协作** —— 通过 join key 邀请其他 Agent 加入你的办公室,实时查看多人状态
4. **中英日三语** —— CN / EN / JP 一键切换,界面文案、气泡、加载提示全部联动
5. **美术资产自定义** —— 侧边栏管理角色 / 场景 / 装饰素材,支持动态帧同步,避免闪烁
6. **AI 生图装修** —— 接入自有 Gemini API用 AI 给办公室换背景(推荐 `nanobanana-pro` / `nanobanana-2`);不接入 API 也能正常使用核心功能
6. **AI 生图装修** —— 接入 Gemini API用 AI 给办公室换背景;不接入 API 也能正常使用核心功能
7. **移动端适配** —— 手机直接打开即可查看,适合外出时快速瞄一眼
8. **安全加固** —— 侧边栏密码保护、生产环境弱密码拦截、Session Cookie 加固
9. **灵活公网访问** —— 推荐 Cloudflare Tunnel 一键公网化,也可用自有域名 / 反向代理
@ -55,7 +86,7 @@ python3 set_state.py idle "待命中"
---
## 🚀 快速开始
## 🚀 详细部署指南
### 1) 安装依赖
@ -79,7 +110,7 @@ python3 app.py
打开 `http://127.0.0.1:19000`
> ✅ 如果你是首次部署可以先保留默认的开发配置;在生产环境中,请复制 `.env.example``.env` 并设置强随机的 `FLASK_SECRET_KEY``ASSET_DRAWER_PASS`,避免弱密码和会话泄露。
> ✅ 首次部署可以先保留默认配置;在生产环境中,请复制 `.env.example``.env` 并设置强随机的 `FLASK_SECRET_KEY``ASSET_DRAWER_PASS`,避免弱密码和会话泄露。
### 4) 切换状态
@ -100,33 +131,21 @@ cloudflared tunnel --url http://127.0.0.1:19000
### 6) 验证安装(可选)
在后端运行中时,可以执行一次轻量级的 smoke test确认核心接口是否正常工作
```bash
python3 scripts/smoke_test.py --base-url http://127.0.0.1:19000
```
如果所有检查都显示 `OK`,说明后端路由和基础状态流转已经就绪
所有检查显示 `OK` 即表示部署成功
---
## 🦞 给 OpenClaw 用户
## 🦞 OpenClaw 深度集成
> 如果你正在使用 [OpenClaw](https://openclaw.com),以下三步可以让你的龙虾和像素办公室深度联动
> 以下内容面向 [OpenClaw](https://openclaw.com) 用户。如果你不使用 OpenClaw可以跳过这一节
### 4.1 安装 Skill
### 状态自动同步
把仓库中的 `SKILL.md` 复制到你的 OpenClaw workspace 目录:
```bash
cp SKILL.md ~/.openclaw/workspace/SKILL.md
```
龙虾会自动读取并按照指引完成部署——包括启动后端、配置公网链接、提醒你设置密码和 API。
### 4.2 状态自动同步
在你的 `SOUL.md`(或 Agent 规则文件)中加入以下规则,让龙虾自觉维护状态:
在你的 `SOUL.md`(或 Agent 规则文件)中加入以下规则,让 Agent 自觉维护状态:
```markdown
## Star Office 状态同步规则
@ -145,13 +164,13 @@ cp SKILL.md ~/.openclaw/workspace/SKILL.md
| `syncing` | 💻 工作区 | 同步数据 / 推送 |
| `error` | 🐛 Bug 区 | 报错 / 异常排查 |
### 4.3 邀请其他龙虾加入你的办公室
### 邀请其他 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让访客龙虾运行推送脚本**
**Step 2让访客 Agent 运行推送脚本**
访客只需下载 `office-agent-push.py`,填写 3 个变量即可:
@ -165,11 +184,11 @@ OFFICE_URL = "https://office.hyacinth.im" # 你的办公室地址
python3 office-agent-push.py
```
脚本会自动加入办公室并每 15 秒推送一次状态。访客龙虾会出现在看板上,根据状态自动走到对应区域。
脚本会自动加入办公室并每 15 秒推送一次状态。访客会出现在看板上,根据状态自动走到对应区域。
**Step 3可选访客安装 Skill**
访客也可以把 `frontend/join-office-skill.md` 作为 Skill 使用,龙虾会自动完成配置和推送。
访客也可以把 `frontend/join-office-skill.md` 作为 Skill 使用,Agent 会自动完成配置和推送。
> 详细的访客接入说明见 [`frontend/join-office-skill.md`](./frontend/join-office-skill.md)
@ -229,15 +248,6 @@ npm run dev
---
## 👥 项目作者
本项目由 **Ring Hyacinth****Simon Lee** 共同创作与维护。
- **Ring Hyacinth** — [@ring_hyacinth](https://x.com/ring_hyacinth)
- **Simon Lee** — [@simonxxoo](https://x.com/simonxxoo)
---
## 📝 更新日志
| 日期 | 概要 | 详情 |