okooooooo/Star-Office-UI
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restructure README for all 3 languages (zh/en/ja)

Browse Source 
- Merge feature list + refresh notes into unified feature overview
- Add 'For OpenClaw Users' section (Skill, auto-sync, invite guests)
- Add Desktop Pet section
- Merge art assets + license sections
- Compress changelog into concise update log with doc links
This commit is contained in:
Star committed 2026-03-06 00:04:52 +08:00
1 parent 5338bad92d
commit e03082629a
3 files changed
+503 -803
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.en.md
+166 -266
View File
@@ -2,25 +2,18 @@
🌐 Language: [中文](./README.md) | **English** | [日本語](./README.ja.md)
![Star Office UI Cover 2](docs/screenshots/readme-cover-2.jpg)
![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, helping teams intuitively see "who is doing what, what they did yesterday, and whether they are online now."
**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.
> This is a **co-created project 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)
## ✨ 30-Second Quick Start
```bash
# 1) Clone repository
# 1) Clone the repo
git clone https://github.com/ringhyacinth/Star-Office-UI.git
cd Star-Office-UI
@@ -30,91 +23,44 @@ python3 -m pip install -r backend/requirements.txt
# 3) Initialize state file (first run)
cp state.sample.json state.json
# 4) Start backend
# 4) Start the backend
cd backend
python3 app.py
```
Open: **http://127.0.0.1:18791**
Open **http://127.0.0.1:18791** and try switching states:
Try changing states (run from project root):
```bash
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"
```
![Star Office UI Cover 1](docs/screenshots/readme-cover-1.jpg)
---
## 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. **Trilingual UI (Chinese / English / Japanese)**
- CN / EN / JP language switching.
- Language changes apply in real time to UI text, loading prompts, and character bubbles.
6. **Customizable art assets**
- Replace character/scene assets via the asset sidebar.
- Safe frame cuts and parameter sync (frame size / frame range) to avoid flickering.
7. **Bring-your-own image API (infinite background changes)**
- Connect your own image-generation API for "move to new home / find agent" style background updates.
- Recommended models: `nanobanana-pro` or `nanobanana-2` (more stable structure preservation).
- Core dashboard functionality does not depend on an API; you can use the core status dashboard and asset management without connecting an API.
8. **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.
![Star Office UI Preview](docs/screenshots/readme-cover-1.jpg)
---
## II. Core changes in this rebuild (2026-03)
## 📋 Features
This version is not a patchwork update—it is a complete rebuild based on the original project. The core changes are focused on four areas:
1. **Added trilingual support (CN / EN / JP)**
- Full UI localization in three languages.
- State text, prompts, and asset display names switch together.
2. **Added asset management (full user customization of art assets)**
- Asset sidebar supports selecting, replacing, and managing defaults.
- Users can customize characters, scenes, decorations, buttons, and more.
3. **Integrated image generation API (smart room renovation + manual renovation)**
- Supports workflows like "Move Home / Find Agent / DIY Decor."
- OpenClaw can redesign rooms via image generation; users can also manually input themes.
4. **Art asset replacement & optimization (key focus)**
- Core assets were replaced/redrawn at scale.
- Rebuilt naming and index mapping for better stability and maintainability.
- Optimized frame-cutting and rendering logic to reduce wrong-frame/cache interference.
1. **Status Visualization** — 6 states (`idle` / `writing` / `researching` / `executing` / `syncing` / `error`) mapped to different office areas with animated sprites and speech bubbles
2. **Yesterday Memo** — Automatically reads the latest daily log from `memory/*.md`, sanitizes it, and displays it as a "Yesterday Memo" card
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
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
10. **Desktop Pet Mode** — Optional Tauri desktop wrapper that turns the office into a transparent desktop widget (see below)
---
## III. Quick Start
## 🚀 Getting Started
### 1) Install dependencies
```bash
cd star-office-ui
cd Star-Office-UI
python3 -m pip install -r backend/requirements.txt
```
@@ -124,16 +70,16 @@ python3 -m pip install -r backend/requirements.txt
cp state.sample.json state.json
```
### 3) Start backend
### 3) Start the backend
```bash
cd backend
python3 app.py
```
Open: `http://127.0.0.1:18791`
Open `http://127.0.0.1:18791`
### 4) Switch main Agent status (example)
### 4) Switch states
```bash
python3 set_state.py writing "Organizing documents"
@@ -142,227 +88,181 @@ python3 set_state.py error "Found an issue, debugging"
python3 set_state.py idle "Standing by"
```
---
### 5) Public access (optional)
## IV. Common APIs
```bash
cloudflared tunnel --url http://127.0.0.1:18791
```
- `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
Share the `https://xxx.trycloudflare.com` link with anyone.
---
## V. Art asset usage notes (please read)
## 🦞 For OpenClaw Users
### Guest character asset source
> If you're using [OpenClaw](https://openclaw.com), these three steps deeply integrate your lobster with the pixel office.
Guest character animations use LimeZu’s free assets:
- **Animated Mini Characters 2 (Platformer) [FREE]**
- https://limezu.itch.io/animated-mini-characters-2-platform-free
### 4.1 Install the Skill
Please keep attribution when redistributing/demoing, and follow the original license terms.
Copy `SKILL.md` from the repo into your OpenClaw workspace:
### Commercial restriction (important)
```bash
cp SKILL.md ~/.openclaw/workspace/SKILL.md
```
- Code logic can be used/extended under MIT.
- **All art assets in this repo (including main character/scene/full pack) are non-commercial.**
- For commercial use, please replace all assets with your own original art.
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:
```markdown
## Star Office Status Sync Rules
- When starting a task: run `python3 set_state.py <state> "<description>"` before beginning work
- When finishing a task: run `python3 set_state.py idle "Standing by"` before replying
```
**6 states → 3 office areas:**
| State | Office Area | When to use |
|-------|-------------|-------------|
| `idle` | 🛋 Breakroom (sofa) | Standing by / task complete |
| `writing` | 💻 Workspace (desk) | Writing code or docs |
| `researching` | 💻 Workspace | Searching / researching |
| `executing` | 💻 Workspace | Running commands / tasks |
| `syncing` | 💻 Workspace | Syncing data / pushing |
| `error` | 🐛 Bug Corner | Error / debugging |
### 4.3 Invite Other Lobsters to Your Office
**Step 1: Prepare join keys**
The repo ships with `join-keys.json` (containing `ocj_starteam01` through `ocj_starteam08`), each supporting up to 3 concurrent users. Feel free to add your own keys.
**Step 2: Have the guest run the push script**
The guest only needs to download `office-agent-push.py` and fill in 3 variables:
```python
JOIN_KEY = "ocj_starteam02" # The key you assign
AGENT_NAME = "Alice's Lobster" # Display name
OFFICE_URL = "https://office.hyacinth.im" # Your office URL
```
```bash
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.
**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.
> See [`frontend/join-office-skill.md`](./frontend/join-office-skill.md) for full guest onboarding instructions.
---
## VI. Open-source license & notice
## 📡 API Reference
- **Code / Logic: MIT** (see `LICENSE`)
- **Art Assets: non-commercial, learning/demo only**
Forks, idea sharing, and PRs are welcome. Please strictly respect asset-usage boundaries.
| Endpoint | Description |
|----------|-------------|
| `GET /health` | Health check |
| `GET /status` | Get main agent status |
| `POST /set_state` | Set main agent status |
| `GET /agents` | List all agents |
| `POST /join-agent` | Guest joins the office |
| `POST /agent-push` | Guest pushes status |
| `POST /leave-agent` | Guest leaves |
| `GET /yesterday-memo` | Get yesterday's memo |
| `GET /config/gemini` | Get Gemini API config |
| `POST /config/gemini` | Set Gemini API config |
| `GET /assets/generate-rpg-background/poll` | Poll image generation progress |
---
## VII. Looking forward to more creative extensions
## 🖥 Desktop Pet Mode (Optional)
You can extend this framework with:
- richer state semantics and automation orchestration
- multi-room / multi-team collaboration maps
- task boards, timelines, auto daily reports
- more complete access control and permissions
The `desktop-pet/` directory contains a **Tauri**-based desktop wrapper that turns the pixel office into a transparent desktop widget.
If you build something cool, feel free to share!
```bash
cd desktop-pet
npm install
npm run dev
```
- Auto-launches the Python backend on startup
- Window points to `http://127.0.0.1:18791/?desktop=1` by default
- Customizable via environment variables for project path and Python path
> ⚠️ This is an **optional, experimental feature**, primarily developed and tested on macOS. See [`desktop-pet/README.md`](./desktop-pet/README.md) for details.
---
## VIII. Project authors
## 🎨 Art Assets & License
### Asset Attribution
Guest character animations use free assets by **LimeZu**:
- [Animated Mini Characters 2 (Platformer) [FREE]](https://limezu.itch.io/animated-mini-characters-2-platform-free)
Please keep attribution when redistributing or demoing, and follow the original license terms.
### License
- **Code / Logic: MIT** (see [`LICENSE`](./LICENSE))
- **Art Assets: Non-commercial use only** (learning / demo / sharing)
> For commercial use, replace all art assets with your own original artwork.
---
## 👥 Authors
This project is co-created and maintained by **Ring Hyacinth** and **Simon Lee**.
- **X: Ring Hyacinth (@ring_hyacinth)**
https://x.com/ring_hyacinth
- **X: Simon Lee (@simonxxoo)**
https://x.com/simonxxoo
- **Ring Hyacinth** — [@ring_hyacinth](https://x.com/ring_hyacinth)
- **Simon Lee** — [@simonxxoo](https://x.com/simonxxoo)
---
## IX. 2026-03 Incremental Updates (added on top of the original version)
## 📝 Changelog
> This section records only new/changed items. Other parts keep the original structure.
### A) Recommended image models for room renovation (New)
For the “Move Home / Find Agent” workflow, it is recommended to connect your own Gemini API and prioritize:
1. **gemini nanobanana pro**
2. **gemini nanobanana 2**
Other models may be less stable for preserving room structure + style consistency.
Recommended config:
- `GEMINI_API_KEY`
- `GEMINI_MODEL` (recommend `nanobanana-pro` or `nanobanana-2`)
Runtime config endpoints are also supported:
- `GET /config/gemini`
- `POST /config/gemini`
If API key is missing, the sidebar will show an input entry so users can fill it in and retry directly.
### B) Asset drawer passcode (New)
The asset sidebar can modify layout, decoration, and default positions.
Current default:
- `ASSET_DRAWER_PASS=1234`
Suggested user-facing guidance:
1. Use default password `1234` for quick trial first;
2. Users can ask you to change the password anytime;
3. Recommend switching to a strong password as soon as possible.
Example:
```bash
export ASSET_DRAWER_PASS="your-strong-pass"
```
Why this matters:
- Prevents anyone with the public link from changing your room layout/assets.
### C) Three reminders for the owner after successful install (New)
1. **Temporary public link**
- Send the `trycloudflare` temporary link to the owner.
- Explain that you can later migrate to their own domain step by step.
2. **Room renovation entry**
- Remind the owner to click “装修房间” to start.
- Default password is `1234`.
- If they want to change password, they can ask you anytime.
- Recommend upgrading to a strong password.
3. **Image API setup**
- Image generation uses the user’s own API.
- Current integration uses Gemini official API format/address.
- If switching to another API provider, ask for API docs first so you can adapt correctly.
### D) Runtime status usage recommendation (New)
Recommend that the Agent proactively maintains status:
1. Before taking a task, switch to a working state (`writing` / `researching` / `executing`) first;
2. After task completion, switch to `idle` first, then enter rest/waiting mode.
This makes the office dashboard feel more real-time and continuous.
### E) Art & copyright wording update (Important)
A major focus of this rebuild is the asset system upgrade (large-scale replacement + naming/index remapping).
Policy remains:
- Code logic: MIT
- Art assets: non-commercial (learning/demo/sharing only)
| Date | Summary | Details |
|------|---------|---------|
| 2026-03-01 | 🎉 **v2 Rebuild** — Trilingual support, asset management system, AI room design, full art asset overhaul | [`docs/FEATURES_NEW_2026-03-01.md`](./docs/FEATURES_NEW_2026-03-01.md) |
| 2026-03-03 | 📋 Open-source release checklist completed | [`docs/OPEN_SOURCE_RELEASE_CHECKLIST.md`](./docs/OPEN_SOURCE_RELEASE_CHECKLIST.md) |
| 2026-03-04 | 🔒 P0/P1 Security hardening — weak password blocking, backend refactor, stale-state auto-idle, skeleton loading | [`docs/UPDATE_REPORT_2026-03-04_P0_P1.md`](./docs/UPDATE_REPORT_2026-03-04_P0_P1.md) |
| 2026-03-05 | 📱 Stability fixes — CDN cache fix, async image generation, mobile sidebar UX, join key expiration & concurrency | [`docs/UPDATE_REPORT_2026-03-05.md`](./docs/UPDATE_REPORT_2026-03-05.md) |
---
### F) 2026-03-04 P0/P1 Security & Stability Update (New)
This patch focuses on **production readiness + truthful status sync**, while preserving existing core features:
1. **P0 Security baseline**
- Added production hardening checks (weak secret / weak password guard)
- Hardened session cookie settings
- Added `scripts/security_check.py` for pre-deploy checks
2. **P1 Refactor (no behavior change)**
- Split backend helpers into `security_utils.py`, `memo_utils.py`, `store_utils.py`
- Reduced `app.py` coupling and improved maintainability
3. **Status-sync & UX improvements**
- Fixed state-source path priority
- Added stale-state auto-idle to reduce false-working states
- Improved first-screen UX (skeleton + deferred non-critical init)
4. **Service stability fixes**
- Unified and stabilized `star-office-ui.service` on port 18888
- Better coordination with `star-office-push.service` to reduce 502 risk
> Detailed notes: `docs/UPDATE_REPORT_2026-03-04_P0_P1.md`
### G) 2026-03-05 Stability Fixes & Mobile Optimization (New)
This update covers 8 commits, focusing on "frontend loading fixes + async image generation + mobile UX":
1. **Frontend loading fixes**
- Fixed CDN caching 404 responses causing page load failure (long-cache now only for 2xx)
- Fixed stray `else` block in `fetchStatus()` causing JS syntax error
2. **Async image generation**
- Room background generation now runs as a background task + frontend polling, avoiding Cloudflare 524 timeout
- New `GET /assets/generate-rpg-background/poll` endpoint
- Frontend shows real-time generation progress
3. **Mobile sidebar optimization**
- Added backdrop overlay; tap to close drawer
- Body scroll lock when drawer is open, scroll position restored on close
- Drawer moves completely off-screen when closed (`right: -100vw`)
- Adapted `100dvh` + `overscroll-behavior: contain`
4. **Join Key expiration & concurrency control**
- Key-level `expiresAt` expiration support
- `maxConcurrent` to control per-key concurrent online limit
- `join-keys.json` added to `.gitignore` (runtime data excluded from repo)
> Detailed notes: `docs/UPDATE_REPORT_2026-03-05.md`
## Project structure (simplified)
## 📁 Project Structure
```text
star-office-ui/
backend/
app.py
requirements.txt
run.sh
frontend/
index.html
join.html
invite.html
layout.js
...assets
docs/
screenshots/
office-agent-push.py
set_state.py
state.sample.json
join-keys.json
SKILL.md
README.md
README.en.md
README.ja.md
LICENSE
Star-Office-UI/
├── backend/ # Flask backend
│ ├── app.py
│ ├── requirements.txt
│ └── run.sh
├── frontend/ # Frontend pages & assets
│ ├── index.html
│ ├── join.html
│ ├── invite.html
│ └── layout.js
├── desktop-pet/ # Tauri desktop wrapper (optional)
├── docs/ # Documentation & screenshots
│ └── screenshots/
├── office-agent-push.py # Guest push script
├── set_state.py # Status switch script
├── state.sample.json # State file template
├── join-keys.json # Join key config
├── SKILL.md # OpenClaw Skill
└── LICENSE # MIT License
```
---
## ⭐ Star History
[![Star History Chart](https://api.star-history.com/image?repos=ringhyacinth/Star-Office-UI&type=date&legend=top-left)](https://www.star-history.com/?repos=ringhyacinth%2FStar-Office-UI&type=date&legend=top-left)
README.ja.md
+175 -275
View File
@@ -2,22 +2,15 @@
🌐 Language: [中文](./README.md) | [English](./README.en.md) | **日本語**
![Star Office UI カバー 2](docs/screenshots/readme-cover-2.jpg)
![Star Office UI カバー](docs/screenshots/readme-cover-2.jpg)
複数 Agent 協調向けのピクセル・オフィス可視化ダッシュボードです。AI アシスタント（OpenClaw / 「ロブスター」）の状態をリアルタイム表示し、「誰が何をしているか」「昨日何をしたか」「オンラインかどうか」を直感的に把握できます。
**マルチ Agent 協調のためのピクセル・オフィス・ダッシュボード** —— AI アシスタント（OpenClaw / ロブスター）の作業状態をリアルタイムで可視化し、「誰が何をしているか」「昨日何をしたか」「今オンラインか」を直感的に把握できます。
> このプロジェクトは **Ring Hyacinth と Simon Lee の共同制作プロジェクト（co-created project）** です。
> 本プロジェクトは **Ring Hyacinth と Simon Lee の共同制作（co-created project）** です。
---
## このプロジェクトは？（一言で）
Star Office UI は「複数人協調状態ダッシュボード」—— 次のように考えられます：
> リアルタイム更新の「ピクセル・オフィス・ダッシュボード」：AI アシスタント（および招待した他の Agent）は状態に応じて自動的に別のエリア（休憩室 / 作業机 / バグエリア）に移動し、昨日の作業ミニサマリーも確認できます。
---
## ✨ 30秒クイックスタート（推奨）
## ✨ 30 秒クイックスタート
```bash
# 1) リポジトリをクローン
@@ -27,7 +20,7 @@ cd Star-Office-UI
# 2) 依存関係をインストール
python3 -m pip install -r backend/requirements.txt
# 3) 状態ファイルを初期化（初回）
# 3) 状態ファイルを初期化（初回のみ）
cp state.sample.json state.json
# 4) バックエンドを起動
@@ -35,86 +28,39 @@ cd backend
python3 app.py
```
開く：**http://127.0.0.1:18791**
**http://127.0.0.1:18791** を開き、状態を切り替えてみましょう：
状態を切り替えてみましょう（プロジェクトルートで実行）：
```bash
python3 set_state.py writing "ドキュメント整理中"
python3 set_state.py syncing "進捗同期中"
python3 set_state.py error "問題を検出、調査中"
python3 set_state.py idle "待機中"
```
![Star Office UI カバー 1](docs/screenshots/readme-cover-1.jpg)
---
## I. このプロジェクトが実現していること
Star Office UI は現在、次の機能を提供しています：
1. **ロブスター作業状態の可視化**
- 状態：`idle`（待機）、`writing`（作業中）、`researching`（調査中）、`executing`（実行中）、`syncing`（同期中）、`error`（エラー）
- 状態はオフィス内の各エリアにマッピングされ、アニメーション/吹き出しで表示されます。
2. **「昨日メモ」ミニサマリー**
- フロントエンドに「昨日メモ」カードを表示。
- バックエンドは `memory/*.md` から昨日（または最近利用可能な記録）を読み、簡易な匿名化を行って表示します。
3. **他ゲストの参加対応（継続改善中）**
- join key で参加。
- ゲストは自身の状態を継続的に push 可能。
- 現在利用可能ですが、導線や体験は継続最適化中です。
4. **モバイル対応**
- スマホから直接アクセスして状態確認が可能。
5. **中英日 3言語切替**
- CN / EN / JP に対応。
- UI 文言、読み込み文言、キャラ吹き出しが連動して切替。
6. **アートアセットのカスタマイズ**
- サイドバーからキャラ/シーン素材を差し替え可能。
- フレームサイズ/範囲同期によりチラつきを低減。
7. **画像生成 API 連携（背景を無限更新）**
- 「引っ越し / 仲介探し」型の背景更新が可能。
- 推奨モデル：`nanobanana-pro` または `nanobanana-2`。
- API 未接続でもコア機能（状態看板/資産管理）は利用可能。
8. **公開アクセスが柔軟**
- Cloudflare Tunnel で素早く公開可能。
- 独自ドメイン / リバースプロキシにも対応。
![Star Office UI プレビュー](docs/screenshots/readme-cover-1.jpg)
---
## II. 今回のリビルド（2026-03）核心変更
## 📋 機能一覧
今回の版は小修正ではなく、元プロジェクトに基づく全面リビルドです。主な変化は4方向：
1. **中英日 3言語追加（CN / EN / JP）**
- 全体 UI の3言語化
- 状態文言・提示文言・資産表示名の連動切替
2. **資産管理機能追加（全アセットのユーザー定義）**
- サイドバーで選択・差し替え・デフォルト管理
- キャラ・背景・装飾・ボタン等を自由に差し替え
3. **画像生成 API 接続（智能装修 + 手動装修）**
- 「引っ越し / 仲介探し / 自分で装修」導線
- OpenClaw で部屋スタイルを生成変更、手動テーマ入力にも対応
4. **アート資産の置換と最適化（重点）**
- 中核資産の大規模置換・再描画
- 命名と索引マッピングを再構築し、安定性・保守性向上
- 動的素材の切り帧・表示ロジック最適化で誤帧/キャッシュ干渉を低減
1. **ステータス可視化** —— 6 種類の状態（`idle` / `writing` / `researching` / `executing` / `syncing` / `error`）がオフィスの各エリアに自動マッピングされ、アニメーションと吹き出しでリアルタイム表示
2. **昨日メモ** —— `memory/*.md` から直近の作業記録を自動取得し、匿名化して「昨日メモ」カードとして表示
3. **マルチ Agent 協調** —— join key で他のロブスターをオフィスに招待し、全員のステータスをリアルタイム確認
4. **中英日 3 言語対応** —— CN / EN / JP をワンクリック切替、UI テキスト・吹き出し・ローディング表示すべてが連動
5. **アート資産カスタマイズ** —— サイドバーからキャラクター / 背景 / 装飾素材を管理、動的フレーム同期でちらつき防止
6. **AI 画像生成による模様替え** —— 自前の Gemini API を接続してオフィス背景を AI 生成（推奨: `nanobanana-pro` / `nanobanana-2`）; API 未接続でもコア機能は利用可能
7. **モバイル対応** —— スマホからそのまま閲覧可能、外出先からのクイックチェックに最適
8. **セキュリティ強化** —— サイドバーのパスワード保護、本番環境での弱パスワード拒否、Session Cookie 強化
9. **柔軟な公開アクセス** —— Cloudflare Tunnel でワンステップ公開、独自ドメイン / リバースプロキシにも対応
10. **デスクトップペット版** —— オプションの Tauri デスクトップラッパーで、オフィスを透明ウィンドウのデスクトップペットに（下記参照）
---
## III. クイックスタート
## 🚀 セットアップ
### 1) 依存関係インストール
```bash
cd star-office-ui
cd Star-Office-UI
python3 -m pip install -r backend/requirements.txt
```
@@ -131,9 +77,9 @@ cd backend
python3 app.py
```
開く：`http://127.0.0.1:18791`
`http://127.0.0.1:18791` を開く
### 4) メイン Agent 状態切替（例）
### 4) ステータス切替
```bash
python3 set_state.py writing "ドキュメント整理中"
@@ -142,227 +88,181 @@ python3 set_state.py error "問題を検出、調査中"
python3 set_state.py idle "待機中"
```
---
## IV. よく使う API
- `GET /health`：ヘルスチェック
- `GET /status`：メイン Agent 状態
- `POST /set_state`：メイン Agent 状態設定
- `GET /agents`：マルチ Agent リスト取得
- `POST /join-agent`：ゲスト参加
- `POST /agent-push`：ゲスト状態 push
- `POST /leave-agent`：ゲスト離脱
- `GET /yesterday-memo`：昨日メモ
---
## V. アート資産利用について（必読）
### ゲストキャラ資産の出典
LimeZu の無料素材を利用：
- **Animated Mini Characters 2 (Platformer) [FREE]**
- https://limezu.itch.io/animated-mini-characters-2-platform-free
再配布/デモ時は出典表示を残し、原作者ライセンスに従ってください。
### 商用制限（重要）
- コード/ロジックは MIT で利用・改変可能。
- **本リポジトリ内の美術資産（主役/背景/素材一式）は商用不可。**
- 商用利用時は必ずオリジナル資産へ差し替えてください。
---
## VI. オープンソースライセンスと声明
- **Code / Logic：MIT**（`LICENSE` 参照）
- **Art Assets：非商用、学習/デモ用途限定**
Fork、アイデア共有、PR は歓迎。資産利用境界は厳守してください。
---
## VII. さらなる拡張へ
このフレームワークを基に、例えば：
- 状態意味の拡張と自動編排
- 多部屋/多チーム協業マップ
- タスク看板、時間線、日報自動生成
- より完備したアクセス制御・権限体系
面白い改造をしたらぜひ共有してください。
---
## VIII. プロジェクト作者
本プロジェクトは **Ring Hyacinth** と **Simon Lee** の共同制作・共同保守です。
- **X：Ring Hyacinth (@ring_hyacinth)**
https://x.com/ring_hyacinth
- **X：Simon Lee (@simonxxoo)**
https://x.com/simonxxoo
---
## IX. 2026-03 増分アップデート（原版に追記）
> 本節は「追加・変更点」のみを記録します。その他の構成は原版のままです。
### A) 部屋リフォーム用の画像生成モデル推奨（新規）
「引っ越し / 仲介探し」フローでは、独自の Gemini API を接続し、以下を優先することを推奨します：
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. できるだけ早く強いパスワードへ変更推奨。
例：
### 5) 公開アクセス（任意）
```bash
export ASSET_DRAWER_PASS="your-strong-pass"
cloudflared tunnel --url http://127.0.0.1:18791
```
必要性：
- 公開リンクを知っている第三者によるレイアウト/素材改変を防ぐため。
### C) インストール成功後にオーナーへ伝える3点（新規）
1. **一時公開リンク**
- `trycloudflare` の一時リンクをオーナーへ共有。
- 後で独自ドメインへ移行できることを案内。
2. **部屋リフォーム入口**
- 「装修房间」から開始できることを案内。
- 初期パスワードは `1234`。
- 変更希望があればいつでもサポート可能。
- 強固なパスワードへの変更を推奨。
3. **画像 API 設定**
- 画像生成にはユーザー自身の API を使用。
- 現在は Gemini 公式 API 形式/アドレスに対応。
- 他 API へ切替時は、先に API ドキュメント共有を依頼してから適配。
### D) 実行時ステータス運用の推奨（新規）
Agent はステータスを能動的に更新することを推奨：
1. タスク着手前に `writing / researching / executing` へ切替；
2. タスク完了後にまず `idle` へ戻してから待機。
これにより、オフィス看板上の状態がより自然で連続的に見えます。
### E) 美術・著作権表記の更新（重要）
今回の重制の重点の一つは、美術アセットシステムの刷新（大規模置換 + 命名/索引再構築）です。
維持する原則：
- コードロジック：MIT
- 美術アセット：商用不可（学習/デモ/共有用途のみ）
`https://xxx.trycloudflare.com` のリンクを共有するだけで OK。
---
## 🦞 OpenClaw ユーザー向け
### F) 2026-03-04 P0/P1 セキュリティ・安定性アップデート（新規）
> [OpenClaw](https://openclaw.com) をご利用中なら、以下の 3 ステップでロブスターとピクセルオフィスを深く連携できます。
本アップデートは、**本番運用の安定性**と**状態同期の信頼性**を高めることを目的に、既存機能を維持したまま以下を実施しました。
### 4.1 Skill をインストール
1. **P0 セキュリティ基盤**
- 本番モードでの安全チェックを追加（弱い secret / パスワードを拒否）
- Session Cookie 設定を強化
- デプロイ前検査 `scripts/security_check.py` を追加
リポジトリ内の `SKILL.md` を OpenClaw のワークスペースにコピーします：
2. **P1 構造改善（挙動変更なし）**
- backend を `security_utils.py` / `memo_utils.py` / `store_utils.py` に分割
- `app.py` の結合度を下げ、保守性を向上
```bash
cp SKILL.md ~/.openclaw/workspace/SKILL.md
```
3. **状態同期・UX 改善**
- 状態ソース読み取り優先順位を修正
- stale 状態の自動 `idle` 復帰を追加（偽作業中を低減）
- 初期表示体験を改善（スケルトン表示、非重要初期化の遅延）
ロブスターが自動的に読み込み、デプロイガイドに沿ってバックエンド起動・公開リンク設定・パスワードと API の案内まで進めてくれます。
4. **サービス安定性修正**
- `star-office-ui.service`（18888）の常駐動作を統一・安定化
- `star-office-push.service` との連携を改善し、502 リスクを低減
### 4.2 ステータス自動同期
> 詳細は `docs/UPDATE_REPORT_2026-03-04_P0_P1.md` を参照してください。
`SOUL.md`（またはエージェント設定ファイル）に以下のルールを追加すると、ロブスターがステータスを自動で更新します：
### G) 2026-03-05 安定性修正・モバイル最適化（新規）
```markdown
## Star Office ステータス同期ルール
- タスク開始時：`python3 set_state.py <状態> "<説明>"` を実行してから作業開始
- タスク完了時：`python3 set_state.py idle "待機中"` を実行してから返答
```
本アップデートは 8 コミットにわたり、「フロントエンド読み込み修正 + 画像生成の非同期化 + モバイル UX」に注力しています：
**6 種類のステータス → 3 つのエリア：**
1. **フロントエンド読み込み修正**
- CDN が 404 レスポンスをキャッシュしてページ読み込みが失敗する問題を修正（長期キャッシュは 2xx のみに適用）
- `fetchStatus()` 内の不要な `else` ブロックによる JS 構文エラーを修正
| ステータス | オフィスエリア | 使用場面 |
|-----------|--------------|---------|
| `idle` | 🛋 休憩エリア（ソファ） | 待機 / タスク完了 |
| `writing` | 💻 ワークエリア（デスク） | コーディング / ドキュメント作成 |
| `researching` | 💻 ワークエリア | 検索 / リサーチ |
| `executing` | 💻 ワークエリア | コマンド実行 / タスク処理 |
| `syncing` | 💻 ワークエリア | データ同期 / プッシュ |
| `error` | 🐛 バグコーナー | エラー / デバッグ |
2. **画像生成の非同期化**
- ルーム背景生成をバックグラウンドタスク + フロントエンドポーリング方式に変更、Cloudflare 524 タイムアウトを回避
- 新規 `GET /assets/generate-rpg-background/poll` エンドポイント追加
- フロントエンドにリアルタイム生成進捗を表示
### 4.3 他のロブスターをオフィスに招待
3. **モバイルサイドバー最適化**
- バックドロップオーバーレイ追加：タップで drawer を閉じる
- drawer 展開時に body スクロールをロック、閉じた際にスクロール位置を復元
- 閉じた drawer を完全に画面外に移動（`right: -100vw`）
- `100dvh` + `overscroll-behavior: contain` に対応
**Step 1：join key を準備**
4. **Join Key 有効期限・同時接続制御**
- Key レベルの `expiresAt` 有効期限をサポート
- `maxConcurrent` で Key ごとの同時接続数を制御
- `join-keys.json` を `.gitignore` に追加（ランタイムデータをリポジトリから除外）
リポジトリには `join-keys.json`（`ocj_starteam01` 〜 `ocj_starteam08`）が含まれており、各キーで最大 3 名まで同時接続可能。独自のキーを追加することもできます。
> 詳細は `docs/UPDATE_REPORT_2026-03-05.md` を参照してください。
**Step 2：ゲストにプッシュスクリプトを実行してもらう**
## プロジェクト構成（簡易）
ゲストは `office-agent-push.py` をダウンロードし、3 つの変数を入力するだけ：
```python
JOIN_KEY = "ocj_starteam02" # あなたが割り当てたキー
AGENT_NAME = "太郎のロブスター" # 表示名
OFFICE_URL = "https://office.hyacinth.im" # あなたのオフィス URL
```
```bash
python3 office-agent-push.py
```
スクリプトが自動で参加し、15 秒ごとにステータスをプッシュします。ゲストのロブスターがダッシュボードに表示され、状態に応じて該当エリアに移動します。
**Step 3（任意）：ゲストも Skill をインストール**
ゲストは `frontend/join-office-skill.md` を Skill として使うこともできます。ロブスターが設定とプッシュを自動で行います。
> 詳しいゲスト参加手順は [`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/` ディレクトリには **Tauri** ベースのデスクトップラッパーが含まれており、ピクセルオフィスを透明ウィンドウのデスクトップペットにできます。
```bash
cd desktop-pet
npm install
npm run dev
```
- 起動時に Python バックエンドを自動起動
- デフォルトで `http://127.0.0.1:18791/?desktop=1` を表示
- 環境変数でプロジェクトパスや Python パスをカスタマイズ可能
> ⚠️ これは**オプションの実験的機能**であり、現在は主に macOS で開発・テストされています。詳細は [`desktop-pet/README.md`](./desktop-pet/README.md) を参照。
---
## 🎨 アート資産とライセンス
### 資産の出典
ゲストキャラクターのアニメーションには **LimeZu** のフリー素材を使用しています：
- [Animated Mini Characters 2 (Platformer) [FREE]](https://limezu.itch.io/animated-mini-characters-2-platform-free)
再配布やデモの際は出典を明記し、原作者のライセンス条項に従ってください。
### ライセンス
- **コード / ロジック：MIT**（[`LICENSE`](./LICENSE) を参照）
- **アート資産：非商用のみ**（学習 / デモ / 共有用途）
> 商用利用の場合は、すべてのアート資産をオリジナル素材に差し替えてください。
---
## 👥 プロジェクト作者
本プロジェクトは **Ring Hyacinth** と **Simon Lee** の共同制作・共同メンテナンスです。
- **Ring Hyacinth** — [@ring_hyacinth](https://x.com/ring_hyacinth)
- **Simon Lee** — [@simonxxoo](https://x.com/simonxxoo)
---
## 📝 更新履歴
| 日付 | 概要 | 詳細 |
|------|------|------|
| 2026-03-01 | 🎉 **v2 リビルド公開** — 3 言語対応、資産管理システム、AI 画像生成による模様替え、アート資産全面刷新 | [`docs/FEATURES_NEW_2026-03-01.md`](./docs/FEATURES_NEW_2026-03-01.md) |
| 2026-03-03 | 📋 オープンソース公開チェックリスト完了 | [`docs/OPEN_SOURCE_RELEASE_CHECKLIST.md`](./docs/OPEN_SOURCE_RELEASE_CHECKLIST.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-05 | 📱 安定性修正 — CDN キャッシュ修正、画像生成非同期化、モバイルサイドバー UX 改善、join key 有効期限・同時接続制御 | [`docs/UPDATE_REPORT_2026-03-05.md`](./docs/UPDATE_REPORT_2026-03-05.md) |
---
## 📁 プロジェクト構成
```text
star-office-ui/
backend/
app.py
requirements.txt
run.sh
frontend/
index.html
join.html
invite.html
layout.js
...assets
docs/
screenshots/
office-agent-push.py
set_state.py
state.sample.json
join-keys.json
SKILL.md
README.md
README.en.md
README.ja.md
LICENSE
Star-Office-UI/
├── backend/ # Flask バックエンド
│ ├── app.py
│ ├── requirements.txt
│ └── run.sh
├── frontend/ # フロントエンドページ & 資産
│ ├── index.html
│ ├── join.html
│ ├── invite.html
│ └── layout.js
├── desktop-pet/ # Tauri デスクトップラッパー（任意）
├── docs/ # ドキュメント & スクリーンショット
│ └── screenshots/
├── office-agent-push.py # ゲストプッシュスクリプト
├── set_state.py # ステータス切替スクリプト
├── state.sample.json # 状態ファイルテンプレート
├── join-keys.json # Join Key 設定
├── SKILL.md # OpenClaw Skill
└── LICENSE # MIT ライセンス
```
---
## ⭐ Star History
[![Star History Chart](https://api.star-history.com/image?repos=ringhyacinth/Star-Office-UI&type=date&legend=top-left)](https://www.star-history.com/?repos=ringhyacinth%2FStar-Office-UI&type=date&legend=top-left)
README.md
+162 -262
View File
@@ -2,22 +2,15 @@
🌐 Language: **中文** | [English](./README.en.md) | [日本語](./README.ja.md)
![Star Office UI 封面 2](docs/screenshots/readme-cover-2.jpg)
![Star Office UI 封面](docs/screenshots/readme-cover-2.jpg)
一个面向多 Agent 协作的像素办公室看板：把 AI 助手（OpenClaw / 龙虾）的工作状态实时可视化，帮助团队直观看到“谁在做什么、昨天做了什么、现在是否在线”。
**一个面向多 Agent 协作的像素办公室看板** —— 把 AI 助手（OpenClaw / 龙虾）的工作状态实时可视化，让你直观看到"谁在做什么、昨天做了什么、现在是否在线"。
> 本项目为 **Ring Hyacinth 与 Simon Lee 的共同项目（co-created project）**。
---
## 这是个什么项目？（一句话）
Star Office UI 是一个“多人协作状态看板”——你可以把它想象成：
> 一个实时更新的“像素办公室仪表盘”：你的 AI 助手（和你邀请的其他 Agent）会根据状态自动走到不同位置（休息区 / 工作区 / bug 区），你还能看到他们昨天的工作小记。
---
## ✨ 30 秒快速体验（推荐先看这里）
## ✨ 30 秒快速体验
```bash
# 1) 下载仓库
@@ -35,86 +28,39 @@ cd backend
python3 app.py
```
打开：**http://127.0.0.1:18791**
打开 **http://127.0.0.1:18791**，然后试试切状态：
切状态试试（在项目根目录执行）：
```bash
python3 set_state.py writing "正在整理文档"
python3 set_state.py syncing "同步进度中"
python3 set_state.py error "发现问题，排查中"
python3 set_state.py idle "待命中"
```
![Star Office UI 封面 1](docs/screenshots/readme-cover-1.jpg)
---
## 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 快速公网化。
- 也可以使用你自己的公网域名 / 反向代理方案。
![Star Office UI 预览](docs/screenshots/readme-cover-1.jpg)
---
## 2、本次重制（2026-03）核心变化
## 📋 功能一览
本次版本不是零散修补，而是基于原项目的一次完整重制。核心变化集中在以下 4 个方向：
1. **新增中英日三语（CN / EN / JP）**
- 全局界面文案三语化
- 状态文案、提示文案、资产显示名可联动切换
2. **新增资产管理功能（用户可自定义全量美术资产）**
- 资产侧边栏支持选择、替换、默认值管理
- 用户可自定义角色、场景、装饰、按钮等素材
3. **接入生图 API（支持房间智能装修 + 用户手动装修）**
- 支持“搬新家 / 找中介 / 自己装”等装修流
- 龙虾可基于生图能力更换房间设计，用户也可手动输入主题改造
4. **美术资产替换与优化（重点）**
- 核心资产完成大规模替换与重绘
- 重建资产命名与索引映射，提升替换稳定性与维护性
- 动态素材切帧与展示逻辑优化，减少错帧/缓存干扰
1. **状态可视化** —— 6 种状态（`idle` / `writing` / `researching` / `executing` / `syncing` / `error`）自动映射到办公室不同区域，动画 + 气泡实时展示
2. **昨日小记** —— 自动从 `memory/*.md` 读取最近一天的工作记录，脱敏后展示为"昨日小记"卡片
3. **多 Agent 协作** —— 通过 join key 邀请其他龙虾加入你的办公室，实时查看多人状态
4. **中英日三语** —— CN / EN / JP 一键切换，界面文案、气泡、加载提示全部联动
5. **美术资产自定义** —— 侧边栏管理角色 / 场景 / 装饰素材，支持动态帧同步，避免闪烁
6. **AI 生图装修** —— 接入自有 Gemini API，用 AI 给办公室换背景（推荐 `nanobanana-pro` / `nanobanana-2`）；不接入 API 也能正常使用核心功能
7. **移动端适配** —— 手机直接打开即可查看，适合外出时快速瞄一眼
8. **安全加固** —— 侧边栏密码保护、生产环境弱密码拦截、Session Cookie 加固
9. **灵活公网访问** —— 推荐 Cloudflare Tunnel 一键公网化，也可用自有域名 / 反向代理
10. **桌面宠物版** —— 可选的 Tauri 桌面封装，把办公室变成透明窗口的桌面宠物（见下方说明）
---
## 3、快速开始
## 🚀 快速开始
### 1) 安装依赖
```bash
cd star-office-ui
cd Star-Office-UI
python3 -m pip install -r backend/requirements.txt
```
@@ -131,9 +77,9 @@ cd backend
python3 app.py
```
打开：`http://127.0.0.1:18791`
打开 `http://127.0.0.1:18791`
### 4) 切换主 Agent 状态（示例）
### 4) 切换状态
```bash
python3 set_state.py writing "正在整理文档"
@@ -142,227 +88,181 @@ python3 set_state.py error "发现问题，排查中"
python3 set_state.py idle "待命中"
```
---
### 5) 公网访问（可选）
## 4、常用 API
```bash
cloudflared tunnel --url http://127.0.0.1:18791
```
- `GET /health`：健康检查
- `GET /status`：主 Agent 状态
- `POST /set_state`：设置主 Agent 状态
- `GET /agents`：获取多 Agent 列表
- `POST /join-agent`：访客加入
- `POST /agent-push`：访客推送状态
- `POST /leave-agent`：访客离开
- `GET /yesterday-memo`：昨日小记
拿到 `https://xxx.trycloudflare.com` 链接即可分享。
---
## 5、美术资产使用说明（请务必阅读）
## 🦞 给 OpenClaw 用户
### 访客角色资产来源
> 如果你正在使用 [OpenClaw](https://openclaw.com)，以下三步可以让你的龙虾和像素办公室深度联动。
访客角色动画使用了 LimeZu 的免费资产：
- **Animated Mini Characters 2 (Platformer) [FREE]**
- https://limezu.itch.io/animated-mini-characters-2-platform-free
### 4.1 安装 Skill
请在二次发布/演示时保留来源说明，并遵守原作者许可条款。
把仓库中的 `SKILL.md` 复制到你的 OpenClaw workspace 目录：
### 商用限制（重要）
```bash
cp SKILL.md ~/.openclaw/workspace/SKILL.md
```
- 代码玩法可以基于 MIT 使用与二次开发。
- **本仓库所有美术资产（含主角色/场景/素材整包）禁止商用。**
- 若你要做商用，请务必制作并替换成你自己的原创美术资产。
龙虾会自动读取并按照指引完成部署——包括启动后端、配置公网链接、提醒你设置密码和 API。
### 4.2 状态自动同步
在你的 `SOUL.md`（或 Agent 规则文件）中加入以下规则，让龙虾自觉维护状态：
```markdown
## Star Office 状态同步规则
- 接到任务时：先执行 `python3 set_state.py <状态> "<描述>"` 再开始工作
- 完成任务后：执行 `python3 set_state.py idle "待命中"` 再回复
```
**6 种状态 → 3 个区域的映射：**
| 状态 | 办公室区域 | 触发场景 |
|------|-----------|---------|
| `idle` | 🛋 休息区（沙发） | 待命 / 任务完成 |
| `writing` | 💻 工作区（办公桌） | 写代码 / 写文档 |
| `researching` | 💻 工作区 | 搜索 / 调研 |
| `executing` | 💻 工作区 | 执行命令 / 跑任务 |
| `syncing` | 💻 工作区 | 同步数据 / 推送 |
| `error` | 🐛 Bug 区 | 报错 / 异常排查 |
### 4.3 邀请其他龙虾加入你的办公室
**Step 1：准备 join key**
仓库默认提供 `join-keys.json`（含 `ocj_starteam01` ~ `ocj_starteam08`），每个 key 最多 3 人同时在线。你也可以自行编辑添加新 key。
**Step 2：让访客龙虾运行推送脚本**
访客只需下载 `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 使用，龙虾会自动完成配置和推送。
> 详细的访客接入说明见 [`frontend/join-office-skill.md`](./frontend/join-office-skill.md)
---
## 6、开源许可与声明
## 📡 常用 API
- **Code / Logic：MIT**（见 `LICENSE`）
- **Art Assets：非商用，仅学习/演示用途**
欢迎 Fork、交流玩法、提 PR；但请严格遵守资产使用边界。
| 端点 | 说明 |
|------|------|
| `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` | 轮询生图进度 |
---
## 7、期待更多玩法交流
## 🖥 桌面宠物版（可选）
欢迎你基于这个框架扩展：
- 更丰富的状态语义与自动编排
- 多房间/多团队协作地图
- 任务看板、时间线、日报自动生成
- 更完整的访问控制与权限体系
`desktop-pet/` 目录提供了一个基于 **Tauri** 的桌面封装版本，可以把像素办公室变成一个透明窗口的桌面宠物。
如果你做了有趣改造，欢迎分享！
```bash
cd desktop-pet
npm install
npm run dev
```
- 启动时自动拉起 Python 后端
- 窗口默认指向 `http://127.0.0.1:18791/?desktop=1`
- 支持通过环境变量自定义项目路径和 Python 路径
> ⚠️ 这是一个**可选的实验性功能**，目前主要在 macOS 上开发测试。详见 [`desktop-pet/README.md`](./desktop-pet/README.md)。
---
## 8、项目作者
## 🎨 美术资产与开源许可
### 资产来源
访客角色动画使用了 **LimeZu** 的免费资产：
- [Animated Mini Characters 2 (Platformer) [FREE]](https://limezu.itch.io/animated-mini-characters-2-platform-free)
请在二次发布 / 演示时保留来源说明，并遵守原作者许可条款。
### 许可协议
- **代码 / 逻辑：MIT**（见 [`LICENSE`](./LICENSE)）
- **美术资产：禁止商用**（仅学习 / 演示 / 交流用途）
> 如需商用，请将所有美术资产替换为你自己的原创素材。
---
## 👥 项目作者
本项目由 **Ring Hyacinth** 与 **Simon Lee** 共同创作与维护。
- **X：Ring Hyacinth (@ring_hyacinth)**
https://x.com/ring_hyacinth
- **X：Simon Lee (@simonxxoo)**
https://x.com/simonxxoo
- **Ring Hyacinth** — [@ring_hyacinth](https://x.com/ring_hyacinth)
- **Simon Lee** — [@simonxxoo](https://x.com/simonxxoo)
---
## 9、2026-03 增量更新（在原版基础上补充）
## 📝 更新日志
> 本节仅记录“新增/变化”，其余内容保持原版结构不变。
| 日期 | 概要 | 详情 |
|------|------|------|
| 2026-03-01 | 🎉 **v2 重制发布** — 新增三语支持、资产管理系统、AI 生图装修、美术资产全面替换 | [`docs/FEATURES_NEW_2026-03-01.md`](./docs/FEATURES_NEW_2026-03-01.md) |
| 2026-03-03 | 📋 开源发布检查清单完成 | [`docs/OPEN_SOURCE_RELEASE_CHECKLIST.md`](./docs/OPEN_SOURCE_RELEASE_CHECKLIST.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-05 | 📱 稳定性修复 — CDN 缓存修复、生图异步化、移动端侧边栏优化、Join Key 过期与并发控制 | [`docs/UPDATE_REPORT_2026-03-05.md`](./docs/UPDATE_REPORT_2026-03-05.md) |
### 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. 建议尽快改成强密码，这样更安全。
示例：
```bash
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
- 美术资产：禁止商用（仅学习/演示/交流用途）
### F) 2026-03-04 P0/P1 安全与稳定性更新（新增）
本次补丁聚焦“可上线稳定运行 + 状态同步真实性”，在不减少既有功能前提下完成以下更新：
1. **P0 安全基线**
- 增加生产模式安全校验（弱 secret / 弱口令阻止启动）
- Session Cookie 安全参数加固
- 新增 `scripts/security_check.py`（上线前安全自检）
2. **P1 结构优化（无行为变化）**
- 后端拆分：`security_utils.py` / `memo_utils.py` / `store_utils.py`
- 降低 `app.py` 耦合度，提升后续维护效率
3. **状态同步与体验优化**
- 修复状态源读取路径优先级
- stale 状态自动回 `idle`，减少“假工作中”
- 优化首屏加载体感（骨架屏、非关键初始化延后）
4. **服务稳定性修复**
- 修复并统一 `star-office-ui.service` 常驻运行（18888）
- 与 `star-office-push.service` 联动，降低 502 风险
> 详细说明见：`docs/UPDATE_REPORT_2026-03-04_P0_P1.md`
### G) 2026-03-05 稳定性修复与移动端优化（新增）
本次更新覆盖 8 个 commit，聚焦「前端加载修复 + 生图异步化 + 移动端体验」：
1. **前端加载修复**
- 修复 CDN 缓存 404 导致页面无法加载（仅 2xx 响应设长缓存）
- 修复 `fetchStatus()` 中多余 `else` 块导致的 JS 语法错误
2. **生图接口异步化**
- 生图改为后台任务 + 前端轮询模式，避免 Cloudflare 524 超时
- 新增 `GET /assets/generate-rpg-background/poll` 轮询端点
- 前端显示实时等待进度
3. **移动端侧边栏优化**
- 新增遮罩层（backdrop），点击即关闭 drawer
- 打开 drawer 时锁定 body 滚动，关闭后恢复位置
- Drawer 关闭时完全移出视口（`right: -100vw`）
- 适配 `100dvh` + `overscroll-behavior: contain`
4. **Join Key 过期与并发控制**
- 支持 key 级别的 `expiresAt` 过期时间
- 支持 `maxConcurrent` 控制单 key 并发在线数
- `join-keys.json` 加入 `.gitignore`（运行时数据不入库）
> 详细说明见：`docs/UPDATE_REPORT_2026-03-05.md`
## 项目结构（简版）
## 📁 项目结构
```text
star-office-ui/
backend/
app.py
requirements.txt
run.sh
frontend/
index.html
join.html
invite.html
layout.js
...assets
docs/
screenshots/
office-agent-push.py
set_state.py
state.sample.json
join-keys.json
SKILL.md
README.md
LICENSE
Star-Office-UI/
├── backend/ # Flask 后端
│ ├── app.py
│ ├── requirements.txt
│ └── run.sh
├── frontend/ # 前端页面与资产
│ ├── index.html
│ ├── join.html
│ ├── invite.html
│ └── layout.js
├── desktop-pet/ # Tauri 桌面宠物版（可选）
├── docs/ # 文档与截图
│ └── screenshots/
├── office-agent-push.py # 访客推送脚本
├── set_state.py # 状态切换脚本
├── state.sample.json # 状态文件模板
├── join-keys.json # Join Key 配置
├── SKILL.md # OpenClaw Skill
└── LICENSE # MIT 许可
```
## Star History
---
## ⭐ Star History
[![Star History Chart](https://api.star-history.com/image?repos=ringhyacinth/Star-Office-UI&type=date&legend=top-left)](https://www.star-history.com/?repos=ringhyacinth%2FStar-Office-UI&type=date&legend=top-left)