docs: clarify features, update skill, add screenshot and asset/non-commercial notices

2026-04-21 13:27:19 +00:00 · 2026-03-01 15:10:55 +08:00 · 2026-03-01 15:10:55 +08:00 · a68d87af8f
commit a68d87af8f
parent e3006ca9b3
11 changed files with 301 additions and 164 deletions
--- a/.gitignore
+++ b/.gitignore
@ -14,7 +14,7 @@ venv/
 # Runtime / local files
 state.json
 agents-state.json
-join-keys.json
+# keep join-keys.json in repo for first-run demo
 *.log
 *.out
 *.pid
--- a/README.md
+++ b/README.md
@ -1,83 +1,54 @@
 # Star Office UI

-一个可视化 **AI 助手（OpenClaw）协作看板**：把龙虾们的实时状态渲染成像素办公室中的角色行为，支持多 Agent 加入、移动端查看、以及“昨日小记”展示。
+一个面向多 Agent 协作的像素办公室看板：把 AI 助手（OpenClaw / 龙虾）的工作状态实时可视化，帮助团队直观看到“谁在做什么、昨天做了什么、现在是否在线”。

-## 项目实现了什么
+![Star Office UI 预览](docs/screenshots/office-preview-20260301.jpg)

-Star Office UI 解决的是“多智能体协作过程看不见”的问题：
+---

- 把抽象状态（`idle / writing / researching / executing / syncing / error`）转成可见位置和动画
- 让多个远端 OpenClaw 通过 join key 加入同一个办公室
- 用轻量后端管理状态流、授权、并发、离线回收
- 在 UI 中展示“昨日小记”（从 `memory/*.md` 提取可展示内容）
+## 一、这个项目实现了什么

-## 核心功能
+Star Office UI 目前实现了：

-### 1) 可视化龙虾工作状态
+1. **可视化龙虾工作状态**
+   - 状态：`idle`（闲置）、`writing`（工作）、`researching`（研究）、`executing`（执行）、`syncing`（同步）、`error`（报 bug）
+   - 状态会映射到办公室里的不同区域，并通过动画/气泡展示。

-支持以下状态，并映射到办公室区域：
+2. **“昨日小记”微型总结**
+   - 前端展示“昨日小记”卡片。
+   - 后端从 `memory/*.md` 中读取昨天（或最近可用）的记录，做基础脱敏后展示。

- `idle`：待命 / 休息区
- `writing`：工作区
- `researching`：工作区
- `executing`：工作区
- `syncing`：同步区（同属工作流）
- `error`：Bug 区
+3. **支持邀请其他访客加入办公室（功能持续迭代中）**
+   - 通过 join key 加入。
+   - 访客可持续 push 自己状态到办公室看板。
+   - 当前已可用，但整体仍在持续优化交互与接入体验。

-此外支持：
- 多 Agent 同屏渲染
- 状态气泡与随机思考文案
- 动画精灵角色与移动端浏览
+4. **已适配手机端访问**
+   - 移动端可直接打开与查看状态（适合外出时快速查看）。

-### 2) 昨日小记（Yesterday Memo）
+5. **公网访问方式灵活**
+   - Skill 默认建议使用 Cloudflare Tunnel 快速公网化。
+   - 也可以使用你自己的公网域名 / 反向代理方案。

-UI 会读取 `memory/` 下的日记文件，优先展示“昨天”的记录；若昨天缺失，会回退到最近可用日期。
+> 你上面列的点是对的，我补充了“状态枚举 + 昨日小记回退机制 + 访客功能仍在迭代”这几项，便于外部开发者理解预期。

-后端提供接口：
- `GET /yesterday-memo`
+---

-用于在看板中展示昨日工作摘要（已做基础隐私清理）。
+## 二、本次更新相比上次的主要内容

-## 项目截图（可在此补充）
+本次发布相对早期基础版，新增/升级重点如下：

-> 建议你把截图放到 `docs/screenshots/`，然后在这里引用。
+- 新增多 Agent 机制：`/join-agent`、`/agent-push`、`/leave-agent`、`/agents`
+- 新增“昨日小记”接口与前端展示：`/yesterday-memo`
+- 状态体系更完整：支持 `syncing`、`error` 等状态可视化
+- 场景与角色动画升级：补充大量像素动画资产（含访客角色）
+- 文档与 Skill 重写：更适合外部程序员快速上手
+- 清理发布结构：去除临时文件 / 缓存 / 日志，降低阅读门槛
+- 补充开源声明：代码 MIT、但美术资产禁止商用

-示例：
+---

-```md
-![主界面](docs/screenshots/office-main.png)
-![多Agent状态](docs/screenshots/multi-agent.png)
-![昨日小记](docs/screenshots/yesterday-memo.png)
-```
-
-## 架构概览
-
-```text
-star-office-ui/
-  backend/
-    app.py                # Flask API + 页面服务
-    requirements.txt
-    run.sh
-  frontend/
-    index.html            # 主 UI（Phaser）
-    join.html             # 加入说明页面
-    invite.html           # 邀请说明页面
-    layout.js             # 场景布局
-    ...assets
-  docs/
-    FEATURES_NEW_2026-03-01.md
-    PROJECT_SUMMARY_2026-03-01.md
-    STAR_OFFICE_UI_OVERVIEW.md
-  office-agent-push.py    # 远端 agent 状态推送脚本
-  set_state.py            # 本地主 agent 状态切换脚本
-  state.sample.json       # 示例状态文件
-  join-keys.json          # join key 配置（可复用）
-  LICENSE
-  SKILL.md
-  README.md
-```
-
-## 快速开始
+## 三、快速开始

 ### 1) 安装依赖

@ -86,7 +57,7 @@ cd star-office-ui
 python3 -m pip install -r backend/requirements.txt
 ```

-### 2) 准备状态文件（首次）
+### 2) 初始化状态文件

 ```bash
 cp state.sample.json state.json
@ -99,49 +70,105 @@ cd backend
 python3 app.py
 ```

-打开：
- `http://127.0.0.1:18791`
+打开：`http://127.0.0.1:18791`

-### 4) 切换主 Agent 状态
-
-在项目根目录执行：
+### 4) 切换主 Agent 状态（示例）

 ```bash
 python3 set_state.py writing "正在整理文档"
-python3 set_state.py syncing "同步数据中"
-python3 set_state.py error "发现异常，排查中"
+python3 set_state.py syncing "同步进度中"
+python3 set_state.py error "发现问题，排查中"
 python3 set_state.py idle "待命中"
 ```

-## 多 Agent 加入（简要）
+---

- 远端 Agent 先调用 `/join-agent` 获取 `agentId`
- 然后周期调用 `/agent-push` 推送状态
- UI 通过 `/agents` 拉取并渲染
-
-详细接入可参考：
- `frontend/join-office-skill.md`
- `office-agent-push.py`
-
-## API（常用）
+## 四、常用 API

 - `GET /health`：健康检查
- `GET /status`：主 agent 状态
- `POST /set_state`：设置主 agent 状态
- `GET /agents`：获取多 agent 列表
- `POST /join-agent`：加入办公室
- `POST /agent-push`：推送 agent 状态
- `POST /leave-agent`：离开办公室
- `GET /yesterday-memo`：读取昨日小记
+- `GET /status`：主 Agent 状态
+- `POST /set_state`：设置主 Agent 状态
+- `GET /agents`：获取多 Agent 列表
+- `POST /join-agent`：访客加入
+- `POST /agent-push`：访客推送状态
+- `POST /leave-agent`：访客离开
+- `GET /yesterday-memo`：昨日小记

-## 开源与资产说明
+---

- 代码遵循仓库 LICENSE（MIT）
- **美术素材版权归原作者/工作室所有**
- 本仓库素材仅用于学习与演示，**未经授权禁止商用**
+## 五、美术资产使用说明（请务必阅读）

-## 安全建议
+### 访客角色资产来源

- 不要在 `detail` 中写入敏感信息
- 公网演示请加鉴权/网关限制
- `state.json` / `agents-state.json` 属于运行态文件，不建议提交
+访客角色动画使用了 LimeZu 的免费资产：
+- **Animated Mini Characters 2 (Platformer) [FREE]**
+- https://limezu.itch.io/animated-mini-characters-2-platform-free
+
+请在二次发布/演示时保留来源说明，并遵守原作者许可条款。
+
+### 其他资产来源
+
+- 主角色动画与办公室场景：由本项目作者团队自行制作。
+
+### 商用限制（重要）
+
+- 代码玩法可以基于 MIT 使用与二次开发。
+- **本仓库美术资产（含主角色/场景/素材整包）禁止商用。**
+- 若你要做商用，请务必制作并替换成你自己的美术资产。
+
+---
+
+## 六、开源许可与声明
+
+- **Code / Logic：MIT**（见 `LICENSE`）
+- **Art Assets：非商用，仅学习/演示用途**
+
+欢迎 Fork、交流玩法、提 PR；但请严格遵守资产使用边界。
+
+---
+
+## 七、期待更多玩法交流
+
+欢迎你基于这个框架扩展：
+- 更丰富的状态语义与自动编排
+- 多房间/多团队协作地图
+- 任务看板、时间线、日报自动生成
+- 更完整的访问控制与权限体系
+
+如果你做了有趣改造，欢迎分享！
+
+---
+
+## 八、作者社交账号
+
+- **X：Ring Hyacinth (@ring_hyacinth)**  
+  https://x.com/ring_hyacinth
+- **X：Simon Lee (@simonxxoo)**  
+  https://x.com/simonxxoo
+
+---
+
+## 项目结构（简版）
+
+```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
+```
--- a/SKILL.md
+++ b/SKILL.md
@ -1,86 +1,147 @@
 ---
 name: star-office-ui
-description: 多 Agent 像素办公室看板：可视化状态、远端加入、昨日小记展示。用于部署、联调、接入与开源发布。
+description: Star Office UI 使用手册：多 Agent 像素办公室部署、状态接入、移动端查看、公网发布与安全边界。
 ---

 # Star Office UI Skill

-## 目标
-
-把 OpenClaw / AI 助手的协作状态可视化为“像素办公室”中的动态角色，支持：
-
-1. 主 Agent 状态展示（idle / writing / researching / executing / syncing / error）
-2. 多 Agent 远端加入与实时同步
-3. 昨日小记展示（从 `memory/*.md` 提取）
+本 Skill 面向两类用户：
+1) 想快速跑起可视化办公室的人
+2) 想让自己的 OpenClaw（龙虾）加入协作看板的人

 ---

-## 核心能力
+## 1. 你能做什么

-### A. 状态可视化
- 状态归一化：`working -> writing`，`sync -> syncing` 等
- 区域映射：
-  - `idle -> breakroom`
-  - `writing/researching/executing/syncing -> writing`
-  - `error -> error`
- UI 动画：主角色 + 访客角色 + 状态气泡
-
-### B. 多 Agent 协作
- `POST /join-agent`：加入办公室（基于 join key）
- `POST /agent-push`：持续推送状态
- `GET /agents`：前端拉取并渲染
- `POST /leave-agent`：离开与回收
-
-### C. 昨日小记
- `GET /yesterday-memo` 从 `memory/` 中找昨日/最近日记
- 对展示文本做基础隐私清理（路径、ID、邮箱、IP 等）
+- 在办公室里可视化主 Agent 状态（工作 / 闲置 / 同步 / 报错）
+- 邀请其他 Agent 加入并实时显示状态
+- 在 UI 展示“昨日小记”微型总结
+- 在手机端查看办公室动态
+- 用 Cloudflare Tunnel 或你自己的公网地址对外访问

 ---

-## 目录与关键文件
+## 2. 状态规范（建议统一）

- 后端：`backend/app.py`
- 前端：`frontend/index.html`、`frontend/layout.js`
- 主状态：`state.json`（运行时）
- 多 Agent 状态：`agents-state.json`（运行时）
- join key：`join-keys.json`
- 主状态切换：`set_state.py`
- 远端推送：`office-agent-push.py`
+支持状态：
+- `idle`
+- `writing`
+- `researching`
+- `executing`
+- `syncing`
+- `error`
+
+区域映射：
+- `idle -> breakroom`
+- `writing/researching/executing/syncing -> writing`
+- `error -> error`

 ---

-## 快速联调流程（10 分钟）
+## 3. 本地快速启动

-1. 启动服务：
-   - `python3 -m pip install -r backend/requirements.txt`
-   - `cd backend && python3 app.py`
-2. 浏览器打开 `/`，确认 UI 可见
-3. 本地切状态：`python3 set_state.py writing "联调中"`
-4. 远端执行 join + push，确认访客进入工作区
-5. 访问 `/yesterday-memo`，确认能返回摘要
+```bash
+cd star-office-ui
+python3 -m pip install -r backend/requirements.txt
+cp state.sample.json state.json
+cd backend && python3 app.py
+```
+
+打开：`http://127.0.0.1:18791`
+
+切状态示例：
+```bash
+python3 set_state.py writing "工作中"
+python3 set_state.py idle "待命"
+```

 ---

-## 常见问题
+## 4. 邀请访客（其他龙虾）加入

-### 1) 访客一直在休息区
- 远端推送是否持续是 `idle`
- 远端是否读取错了状态源
- `/agent-push` 是否返回成功
+### 步骤 A：join
+调用 `POST /join-agent`，提交：
+- `name`
+- `joinKey`
+- `state`（可选，默认 idle）
+- `detail`（可选）

-### 2) join 失败（403 / 429）
+成功后会返回 `agentId`。
+
+### 步骤 B：push
+定时调用 `POST /agent-push`，提交：
+- `agentId`
+- `joinKey`
+- `state`
+- `detail`（可选）
+
+建议 10~20 秒推一次。
+
+### 步骤 C：leave（可选）
+调用 `POST /leave-agent` 离开房间。
+
+---
+
+## 5. 昨日小记说明
+
+- 接口：`GET /yesterday-memo`
+- 数据来源：工作区上级目录的 `memory/*.md`
+- 行为：优先读取“昨天”；若没有则回退最近可用日期
+- 会做基础隐私清理（ID / 路径 / 邮箱 / IP）
+
+---
+
+## 6. 公网访问建议
+
+### 推荐：Cloudflare Tunnel
+优点：快、便捷、无需改路由。
+
+```bash
+cloudflared tunnel --url http://127.0.0.1:18791
+```
+
+### 也可以使用你自己的公网方案
+例如：
+- Nginx/Caddy 反向代理
+- 自有域名 + HTTPS
+- 任何你熟悉的公网入口
+
+> 注意：请勿在仓库中硬编码私有域名。
+
+---
+
+## 7. 常见问题
+
+### Q1：访客一直在休息区
+- 远端是否一直 push `idle`
+- 是否读取错状态源文件
+- `/agent-push` 是否成功返回
+
+### Q2：join 报 403 / 429
 - 403：join key 无效或不匹配
 - 429：同 key 并发达到上限（默认 3）

-### 3) 之前在线的 Agent 突然掉线
- 超过 5 分钟无推送会被标记 `offline`
- 恢复推送可自动回到 `approved`
+### Q3：状态文件删了怎么办
+- `state.json` / `agents-state.json` 是运行态文件
+- 可由脚本运行时自动生成，或从 `state.sample.json` 复制
+- 这类文件不建议提交到 GitHub

 ---

-## 开源发布注意事项
+## 8. 开源与版权边界（必须遵守）

- 不提交运行时文件：`state.json`、`agents-state.json`、`*.log`、`*.out`、`*.pid`
- 不提交本地环境与缓存：`.venv/`、`__pycache__/`
- README 需写清楚素材版权与非商用限制
- 对外默认使用示例配置（`state.sample.json`）
+- 代码逻辑：MIT
+- 美术资产：仅学习/演示用途，禁止商用
+- 访客角色资产来源：LimeZu
+  - https://limezu.itch.io/animated-mini-characters-2-platform-free
+- 若要商用，请替换成你自己的美术资产
+
+---
+
+## 9. 给贡献者的建议
+
+如果你想做二次开发，推荐优先从这几块下手：
+- 更强的权限模型（管理员/访客分级）
+- 多房间与团队组织
+- 状态事件回放与日报自动生成
+- 更标准的 API 文档与 SDK
--- a/agent-invite-template.txt
+++ b/agent-invite-template.txt
@ -1,7 +1,7 @@
 # 海辛办公室 · Agent 加入指南

 ## 你收到的信息
- 邀请页：https://office.hyacinth.im/join
+- 邀请页：https://office.example.com/join
 - 接入密钥（join key）：[请填入对方给你的 ocj_xxx]
 - 你想要在办公室里显示的名字：[请填入你的名字]

@ -10,7 +10,7 @@
 > “我将把我的工作状态（idle/writing/researching/executing/syncing/error）定时发送到海辛的办公室看板，用于可视化协作；不含具体内容/隐私；随时可停。是否授权？”

 ### 2. 主人同意后：
- 调用 `POST https://office.hyacinth.im/join-agent`，payload：
+- 调用 `POST https://office.example.com/join-agent`，payload：
  ```json
  {
    "name": "[你的名字]",
@ -20,7 +20,7 @@
  }
  ```
 - 拿到返回的 `agentId`
- 调用 `POST https://office.hyacinth.im/agent-approve`，payload：
+- 调用 `POST https://office.example.com/agent-approve`，payload：
  ```json
  {
    "agentId": "[刚才拿到的 agentId]"
@ -28,7 +28,7 @@
  ```
 - 启动定时推送器（每 30s 一次，或者只在状态变化时）：
  ```json
-  POST https://office.hyacinth.im/agent-push
+  POST https://office.example.com/agent-push
  {
    "agentId": "[你的 agentId]",
    "joinKey": "[ocj_xxx]",
@ -40,7 +40,7 @@

 ### 3. 主人想退出时：
 - 停止定时推送器
- 调用 `POST https://office.hyacinth.im/leave-agent`，payload：
+- 调用 `POST https://office.example.com/leave-agent`，payload：
  ```json
  {
    "name": "[你的名字]"
--- a/docs/OPEN_SOURCE_RELEASE_CHECKLIST.md
+++ b/docs/OPEN_SOURCE_RELEASE_CHECKLIST.md
@ -28,7 +28,7 @@

 ### 发现潜在敏感内容
 - 代码内含绝对路径 `/root/...`（建议改为相对路径或环境变量）
- 文档与脚本含私有域名 `office.hyacinth.im`（可保留为示例，但建议改成占位域名）
+- 文档与脚本含私有域名 `office.example.com`（可保留为示例，但建议改成占位域名）

 ## 2. 必改项（提交前）

@ -80,7 +80,7 @@ star-office-ui/
 ```

 ## 4. 发布前最终核对（给海辛确认）
- [ ] 是否保留私有域名示例（`office.hyacinth.im`）
+- [ ] 是否保留私有域名示例（`office.example.com`）
 - [ ] 哪些美术资源允许公开（逐项确认）
 - [ ] README 非商用声明是否满足你的预期措辞
 - [ ] 是否需要将“阿文龙虾联调脚本”单独放 examples 目录
--- a/docs/screenshots/office-preview-20260301.jpg
+++ b/docs/screenshots/office-preview-20260301.jpg
--- a/frontend/invite.html
+++ b/frontend/invite.html
@ -122,7 +122,7 @@
                    <strong>确认信息</strong><br>
                    你应该已经收到两样东西：
                    <ul>
-                        <li>邀请链接：<code>https://office.hyacinth.im/join</code></li>
+                        <li>邀请链接：<code>https://office.example.com/join</code></li>
                        <li>一次性接入密钥（join key）：<code>ocj_xxx</code></li>
                    </ul>
                </div>
--- a/frontend/join-office-skill.md
+++ b/frontend/join-office-skill.md
@ -6,7 +6,7 @@
 ## Prerequisites
 - 你必须从海辛处获得一次性接入密钥（格式：`ocj_xxx`）
 - 你的主人已同意授权你推送状态到海辛办公室
- 你能访问 `https://office.hyacinth.im`
+- 你能访问 `https://office.example.com`

 ## Steps
 1. 向你的主人确认授权：
@ -15,7 +15,7 @@
 2. 主人同意后：
   - 使用你想在办公室显示的名字作为 `AGENT_NAME`
   - 使用海辛给你的密钥作为 `JOIN_KEY`
-   - 下载或复制 `office-agent-push.py`（可以访问：https://office.hyacinth.im/static/office-agent-push.py）
+   - 下载或复制 `office-agent-push.py`（可以访问：https://office.example.com/static/office-agent-push.py）
   - **最简单推荐**：直接运行脚本（已内置 state.json 自动发现）
     - 会自动尝试以下路径：
       - `/root/.openclaw/workspace/star-office-ui/state.json`
--- a/frontend/join.html
+++ b/frontend/join.html
@ -120,7 +120,7 @@
        状态与状态细节会由 agent 后续自动推送同步
        <br><br>
        📌 邀请说明：
-        <a href="/invite" style="color:#ffd700; text-decoration: underline;">https://office.hyacinth.im/invite</a>
+        <a href="/invite" style="color:#ffd700; text-decoration: underline;">https://office.example.com/invite</a>
    </div>

    <script>
--- a/join-keys.json
+++ b/join-keys.json
@ -0,0 +1,49 @@
+{
+  "keys": [
+    {
+      "key": "ocj_starteam01",
+      "name": "团队成员 01",
+      "maxConcurrent": 3,
+      "used": true,
+      "usedBy": "阿龙虾",
+      "usedByAgentId": "agent_1772347959385_px4w",
+      "usedAt": "2026-03-01T14:52:39.385922",
+      "reusable": true
+    },
+    {
+      "key": "ocj_starteam02",
+      "name": "团队成员 02",
+      "maxConcurrent": 3
+    },
+    {
+      "key": "ocj_starteam03",
+      "name": "团队成员 03",
+      "maxConcurrent": 3
+    },
+    {
+      "key": "ocj_starteam04",
+      "name": "团队成员 04",
+      "maxConcurrent": 3
+    },
+    {
+      "key": "ocj_starteam05",
+      "name": "团队成员 05",
+      "maxConcurrent": 3
+    },
+    {
+      "key": "ocj_starteam06",
+      "name": "团队成员 06",
+      "maxConcurrent": 3
+    },
+    {
+      "key": "ocj_starteam07",
+      "name": "团队成员 07",
+      "maxConcurrent": 3
+    },
+    {
+      "key": "ocj_starteam08",
+      "name": "团队成员 08",
+      "maxConcurrent": 3
+    }
+  ]
+}
--- a/office-agent-push.py
+++ b/office-agent-push.py
@ -18,7 +18,7 @@ from datetime import datetime
 # === 你需要填入的信息 ===
 JOIN_KEY = ""   # 必填：你的一次性 join key
 AGENT_NAME = "" # 必填：你在办公室里的名字
-OFFICE_URL = "https://office.hyacinth.im"  # 海辛办公室地址（一般不用改）
+OFFICE_URL = "https://office.example.com"  # 海辛办公室地址（一般不用改）

 # === 推送配置 ===
 PUSH_INTERVAL_SECONDS = 15  # 每隔多少秒推送一次（更实时）