Update: 将子项目从 submodule 转为完整内容

- 移除 GovAI, nomifun-tauri, 算力盒子 的 submodule 引用
- 添加所有子项目的完整源代码
- 保留原始 .git 为 .git.bak 备份
This commit is contained in:
freedak
2026-07-04 19:20:46 +08:00
parent 54d6465fa7
commit f7a720204a
3360 changed files with 802660 additions and 3 deletions
@@ -0,0 +1,173 @@
---
name: star-office-helper
description: Install, start, connect, and troubleshoot visualization companion projects for Nomi/OpenClaw, with Star-Office-UI as the default recommendation. Use when users ask for Star Office setup, URL/port connection, Unauthorized page diagnosis, Python venv/pip issues (PEP 668), preview panel wiring, real-time monitor wake-up checks, or similar open-source visualizer alternatives.
---
# Star Office Helper
Guide users from zero to usable visualization integration in Nomi. Prefer Star-Office-UI first, then provide alternatives only when requested or when Star Office does not fit.
## What is Star Office
Star Office UI is a **third-party** local visualization companion for OpenClaw / NomiFun.
- Project: <https://github.com/ringhyacinth/Star-Office-UI>
- License boundary: project code is MIT, but the bundled art assets are
non-commercial only. For commercial or public product use, replace the art
assets with original/licensed assets and keep the upstream attribution.
- It turns chat-side agent status (idle / writing / researching / executing / syncing / error) into a live, interactive office-themed monitor view.
- It is **not** built-in to NomiFun — it runs as a separate local service (default `http://127.0.0.1:19000`).
- OpenClaw works independently without Star Office; Star Office only animates when its own backend+frontend and event bridge are active.
**Capabilities when connected:**
- Real-time visualization of conversation state changes
- Interactive office scene that reflects agent activity
- Live monitor accessible via the TV icon in the chat header
When a user asks "what is Star Office" or triggers the install flow, introduce it clearly with the above context before proceeding.
## Connection Guidance
When Star Office is **already detected** on the local machine:
1. Confirm the detected URL (e.g. `http://127.0.0.1:19000`).
2. Guide the user to click the TV icon in the chat header to open the live monitor.
3. Explain available interactions: real-time status view, office scene animation.
4. If connection fails despite detection, enter troubleshooting (check port, process, auth, logs).
When Star Office is **not detected**:
1. Follow the Install Workflow below.
2. After install completes, guide the user to verify via the TV icon.
## Workflow
1. Confirm objective:
- Install and run a visualization companion locally (default: Star-Office-UI).
- Connect Nomi preview/monitor URL to a running visualizer service.
- Diagnose why UI does not animate or shows `Unauthorized`.
2. Run environment diagnosis first:
- Execute `skills/star-office-helper/scripts/star_office_doctor.sh`.
- If `python3 -m pip install` fails with `externally-managed-environment`, switch to venv flow.
3. Install/repair setup:
- Execute `skills/star-office-helper/scripts/star_office_setup.sh`.
- This creates `.venv`, installs backend dependencies, and ensures `state.json` exists.
4. Start services and verify:
- Start backend and frontend from Star-Office-UI repo.
- Confirm preview URL (default recommend `http://127.0.0.1:19000`).
- Re-run doctor to verify port and HTTP response.
5. Connect in Nomi:
- Open OpenClaw mode preview panel (TV icon).
- Input URL and save.
- If still blank/Unauthorized, inspect backend auth and state config with doctor output.
6. Recommend alternatives when needed:
- If user asks for "similar/open-source alternatives", follow `references/discovery.md`.
- Keep Star-Office-UI as the baseline option in comparison.
- Return 3-5 candidate projects with:
- repo link
- integration mechanism match (event/state bridge + web preview)
- setup complexity
- maintenance signals (recent commits/issues activity)
- risk notes
## Install Mode Rules
When the user triggers one-stop install/repair (e.g. via the TV icon), follow these rules:
- Star Office UI is a THIRD-PARTY local project. It is NOT built-in to Nomi/OpenClaw and NOT a required core service.
- If launched from a clearly labeled install/repair UI, the user has already
consented to automated install/repair actions. In all other chat flows, ask
for explicit confirmation before cloning, installing dependencies, starting
services, or repairing files.
- Stay focused on installing, starting, detecting, repairing, uninstalling, and reconnecting Star Office UI.
- **Your job is to DO it, not to TEACH it.** Execute every command yourself using your tools. Your response must never contain commands for the user to copy-paste or steps for the user to follow. If the user sees a shell command in your reply, you have failed. The only exception is when an OS-level permission dialog (e.g. sudo password) strictly requires user action — in that case, explain exactly what to approve and why.
- After each major step, tell the user whether they can click the TV icon to verify live monitor.
- Stream concise progress updates in real time. At minimum output one short line before and after each major step.
### Verification Rules (Strict)
- Treat Star Office as running **only** if at least one strict signal matches:
1. Local port 19000 is listening, OR
2. Health endpoint responds from candidate URL, OR
3. Process command/path clearly points to Star-Office-UI repo/backend.
- If strict signals are absent, report Star Office as not running/uninstalled; do not claim residual runtime based only on generic Python workers.
- Do NOT treat generic `python`/`python3` processes as Star Office residuals unless their command/path explicitly references Star-Office-UI or its backend app.
- Do NOT claim "openclaw-gateway/Nomi auto-restarts Star Office app.py" unless you have explicit evidence from process parent chain, Nomi config, or logs in this session.
- Never claim Star Office is "built-in", "bound to Nomi", or "cannot be independently uninstalled" without explicit product evidence from this repo.
### Install Workflow
You MUST execute every step yourself. Each step should include a short progress message.
1. **Checking environment** — Run `bash skills/star-office-helper/scripts/star_office_doctor.sh`, report findings.
2. **Installing / repairing** — Run `bash skills/star-office-helper/scripts/star_office_setup.sh`, report success or failure.
3. **Starting service** — Execute these commands yourself (do NOT tell the user to run them):
- Backend: `cd ~/Star-Office-UI/backend && nohup ../.venv/bin/python app.py > /dev/null 2>&1 &`
- Frontend: `cd ~/Star-Office-UI/frontend && npm install && nohup npm run dev > /dev/null 2>&1 &`
- Wait a few seconds, then verify both processes are running.
4. **Detecting port** — Verify `http://127.0.0.1:19000/health` responds. Report detected URL.
5. **Troubleshooting** (if needed) — Diagnose unauthorized, port conflict, missing process. Auto-fix and retry.
6. **Completed** — Confirm service is reachable. You MUST explicitly tell the user that installation is complete and the service is running at `http://127.0.0.1:19000`. Do NOT end your response without confirming the final URL.
### Uninstall Workflow
"Uninstall" means **stop all services AND remove all files**. You MUST run the uninstall script — do NOT manually delete the directory without stopping services first.
1. **Run uninstall script** — Execute `bash skills/star-office-helper/scripts/star_office_uninstall.sh`. This script handles the full sequence: kill processes, free ports, remove directory, and verify cleanup.
2. **Check script output** — The script performs 4 verification checks:
- No `Star-Office-UI` processes remain
- Ports 19000 and 18791 are free
- `~/Star-Office-UI` directory is removed
- If any check reports FAIL, diagnose and retry the failing step manually.
3. **Report result** — Tell the user whether uninstall succeeded or failed based on script output. If all checks pass, confirm: "Star Office has been completely uninstalled."
## Ground Rules
- Do not use `pip --break-system-packages` unless user explicitly asks for system-wide install.
- Prefer venv install on macOS/Homebrew Python.
- Treat OpenClaw task execution and Star Office animation as two systems:
- OpenClaw can work without Star Office.
- Star Office only animates when its own backend/frontend and event path are active.
## Quick Commands
```bash
# Diagnose current machine and ports
bash skills/star-office-helper/scripts/star_office_doctor.sh
# Bootstrap Star-Office-UI in ~/Star-Office-UI
bash skills/star-office-helper/scripts/star_office_setup.sh
# Bootstrap in a custom folder
bash skills/star-office-helper/scripts/star_office_setup.sh /path/to/Star-Office-UI
# Uninstall Star-Office-UI (stop services + remove files + verify)
bash skills/star-office-helper/scripts/star_office_uninstall.sh
# Uninstall from a custom folder
bash skills/star-office-helper/scripts/star_office_uninstall.sh /path/to/Star-Office-UI
```
## References
- Read `references/troubleshooting.md` for:
- `Unauthorized` root causes
- wrong port (`18791` vs `19000`)
- why "connected but not moving"
- Nomi preview URL mapping checklist
- Read `references/discovery.md` for:
- how to find similar visualization open-source projects
- filtering rules for mechanism compatibility
- recommendation output format
@@ -0,0 +1,46 @@
# Similar Project Discovery
Use this when users ask for alternatives to Star-Office-UI.
## Target mechanism
Only recommend projects that are close to this mechanism:
- Real-time or near-real-time visual status UI for agent/task execution.
- Locally runnable web UI (`http://127.0.0.1:<port>` style).
- Can be integrated in Nomi preview panel via URL embed.
- Has a bridge path (API/event/webhook/polling) to accept external task status.
## Discovery steps
1. Search GitHub with combinations of:
- `agent visualizer`
- `ai task monitor ui`
- `workflow live dashboard open source`
- `openclaw` / `claude code` / `agent runtime` + `visual`
2. Exclude projects that are:
- only static design templates
- archived or clearly abandoned
- not open source
- impossible to run locally
3. Validate each candidate quickly:
- has README with run instructions
- has backend/frontend or realtime channel docs
- recent maintenance signals (commits/issues)
## Recommendation format
For each candidate provide:
1. Name + GitHub URL
2. Why mechanism matches (1 sentence)
3. Setup effort (`low`/`medium`/`high`)
4. Integration risk (port/auth/event bridge complexity)
5. Best use case
Always list `Star-Office-UI` first unless user explicitly asks to exclude it.
@@ -0,0 +1,59 @@
# Star Office Troubleshooting
## 1. `Unauthorized` on `127.0.0.1:<port>`
Common causes:
- Backend started but session/auth state not initialized.
- Opened backend port directly instead of frontend port.
- `state.json` missing or invalid.
Actions:
1. Ensure `state.json` exists (copy from `state.sample.json` if needed).
2. Start backend with venv Python:
- `cd backend && ../.venv/bin/python app.py`
3. Open frontend URL (usually `http://127.0.0.1:19000`) instead of backend API port.
4. Run `bash skills/star-office-helper/scripts/star_office_doctor.sh` and check port + HTTP status.
## 2. `pip install` fails with `externally-managed-environment`
Cause:
- macOS/Homebrew Python follows PEP 668 and blocks system-wide pip write.
Fix:
1. `python3 -m venv .venv`
2. `.venv/bin/python -m pip install --upgrade pip`
3. `.venv/bin/python -m pip install -r backend/requirements.txt`
Avoid:
- `--break-system-packages` unless user explicitly requires system install.
## 3. Nomi connected but preview does not move
Cause:
- Nomi can talk to OpenClaw, but Star Office is only a visualization layer.
- No event bridge from OpenClaw task stream to Star Office backend.
- Wrong preview URL.
Checklist:
1. Confirm Star Office frontend port (default `19000`) is reachable.
2. Confirm backend is running and receiving events.
3. Confirm Nomi preview panel URL exactly matches frontend URL.
4. Trigger a real OpenClaw task and observe backend logs.
## 4. Port confusion (`18791` vs `19000`)
Typical mapping:
- `18791`: backend/service/auth endpoint (may return `Unauthorized`).
- `19000`: frontend visual UI for browser preview.
Rule:
- In Nomi preview panel, use frontend URL.
@@ -0,0 +1,90 @@
#!/usr/bin/env bash
set -euo pipefail
TARGET_DIR="${1:-$HOME/Star-Office-UI}"
PORT_FRONTEND="${PORT_FRONTEND:-19000}"
PORT_BACKEND="${PORT_BACKEND:-18791}"
URL_FRONTEND="http://127.0.0.1:${PORT_FRONTEND}"
URL_BACKEND="http://127.0.0.1:${PORT_BACKEND}"
echo "[star-office-doctor] target: $TARGET_DIR"
echo "[star-office-doctor] frontend: $URL_FRONTEND"
echo "[star-office-doctor] backend: $URL_BACKEND"
echo
check_cmd() {
local c="$1"
if command -v "$c" >/dev/null 2>&1; then
echo "OK command: $c"
else
echo "MISS command: $c"
fi
}
check_http() {
local url="$1"
local name="$2"
local code
code="$(curl -s -o /tmp/star_office_doctor_body.txt -w "%{http_code}" "$url" || true)"
if [ "$code" = "200" ] || [ "$code" = "401" ]; then
echo "OK $name http=$code url=$url"
if rg -q "Unauthorized" /tmp/star_office_doctor_body.txt 2>/dev/null; then
echo "WARN $name returns Unauthorized (likely backend auth/session not ready)"
fi
else
echo "FAIL $name http=$code url=$url"
fi
}
check_port() {
local p="$1"
if lsof -nP -iTCP:"$p" -sTCP:LISTEN >/tmp/star_office_port_"$p".txt 2>/dev/null; then
echo "OK port $p listening"
head -n 3 /tmp/star_office_port_"$p".txt
else
echo "FAIL port $p not listening"
fi
}
check_cmd python3
check_cmd git
check_cmd curl
check_cmd lsof
check_cmd rg
echo
if [ -d "$TARGET_DIR" ]; then
echo "OK directory exists: $TARGET_DIR"
else
echo "FAIL directory missing: $TARGET_DIR"
fi
if [ -f "$TARGET_DIR/backend/requirements.txt" ]; then
echo "OK backend requirements found"
else
echo "FAIL backend requirements missing"
fi
if [ -d "$TARGET_DIR/.venv" ]; then
echo "OK .venv exists"
else
echo "WARN .venv missing (run setup script)"
fi
echo
check_port "$PORT_FRONTEND"
check_port "$PORT_BACKEND"
echo
check_http "$URL_FRONTEND" "frontend"
check_http "$URL_BACKEND" "backend-root"
echo
cat <<'EOF'
Checklist:
1) If pip failed with externally-managed-environment, use:
python3 -m venv .venv && .venv/bin/python -m pip install -r backend/requirements.txt
2) If browser shows Unauthorized, backend may be running but not initialized/session missing.
3) If frontend opens but no animation, verify OpenClaw events are actually flowing to Star Office backend.
4) In Nomi preview panel, use exact URL of running frontend (usually http://127.0.0.1:19000).
EOF
@@ -0,0 +1,43 @@
#!/usr/bin/env bash
set -euo pipefail
TARGET_DIR="${1:-$HOME/Star-Office-UI}"
REPO_URL="${STAR_OFFICE_REPO_URL:-https://github.com/ringhyacinth/Star-Office-UI.git}"
echo "[star-office-setup] target: $TARGET_DIR"
if ! command -v python3 >/dev/null 2>&1; then
echo "ERROR: python3 not found"
exit 1
fi
if ! command -v git >/dev/null 2>&1; then
echo "ERROR: git not found"
exit 1
fi
if [ ! -d "$TARGET_DIR/.git" ]; then
echo "[star-office-setup] cloning repo..."
git clone "$REPO_URL" "$TARGET_DIR"
else
echo "[star-office-setup] repo exists, skip clone"
fi
cd "$TARGET_DIR"
if [ ! -d ".venv" ]; then
echo "[star-office-setup] creating .venv"
python3 -m venv .venv
fi
echo "[star-office-setup] installing backend requirements in .venv"
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r backend/requirements.txt
if [ ! -f "state.json" ] && [ -f "state.sample.json" ]; then
cp state.sample.json state.json
echo "[star-office-setup] created state.json from sample"
fi
echo ""
echo "[star-office-setup] Done. Proceed to start backend and frontend."
@@ -0,0 +1,160 @@
#!/usr/bin/env bash
set -euo pipefail
TARGET_DIR="${1:-$HOME/Star-Office-UI}"
PORT_FRONTEND="${PORT_FRONTEND:-19000}"
PORT_BACKEND="${PORT_BACKEND:-18791}"
echo "[star-office-uninstall] target: $TARGET_DIR"
echo
# --- Step 1: Kill processes matching the target directory ---
echo "[step 1/5] Stopping Star-Office-UI processes..."
killed_any=false
kill_matching() {
local pattern="$1"
local label="$2"
local pids
pids="$(pgrep -f "$pattern" 2>/dev/null || true)"
if [ -z "$pids" ]; then
return
fi
for pid in $pids; do
echo " stopping $label PID=$pid (SIGTERM)"
kill "$pid" 2>/dev/null || true
killed_any=true
done
}
# Match processes by the actual target directory path
kill_matching "$TARGET_DIR/backend" "backend"
kill_matching "$TARGET_DIR/frontend" "frontend"
# Also match by directory basename in case cwd differs from full path
dir_basename="$(basename "$TARGET_DIR")"
kill_matching "$dir_basename/backend" "backend"
kill_matching "$dir_basename/frontend" "frontend"
if [ "$killed_any" = true ]; then
echo " waiting for graceful shutdown..."
sleep 2
# Force kill any survivors
for pattern in "$TARGET_DIR/backend" "$TARGET_DIR/frontend" "$dir_basename/backend" "$dir_basename/frontend"; do
pids="$(pgrep -f "$pattern" 2>/dev/null || true)"
for pid in $pids; do
echo " force killing PID=$pid (SIGKILL)"
kill -9 "$pid" 2>/dev/null || true
done
done
else
echo " no Star-Office-UI processes found"
fi
echo
# --- Step 2: Check and clean ports ---
echo "[step 2/5] Checking ports $PORT_FRONTEND and $PORT_BACKEND..."
for port in "$PORT_FRONTEND" "$PORT_BACKEND"; do
pids="$(lsof -ti :"$port" 2>/dev/null || true)"
if [ -z "$pids" ]; then
echo " OK port $port is free"
continue
fi
for pid in $pids; do
# Check if process is related to Star Office before killing
cmd="$(ps -p "$pid" -o args= 2>/dev/null || true)"
if echo "$cmd" | grep -qi "star.office\|$dir_basename" 2>/dev/null; then
echo " killing Star-Office process on port $port, PID=$pid ($cmd)"
kill -9 "$pid" 2>/dev/null || true
else
echo " WARN port $port occupied by non-Star-Office process PID=$pid ($cmd)"
echo " skipping — kill manually if needed"
fi
done
done
sleep 1
echo
# --- Step 3: Remove directory ---
echo "[step 3/5] Removing directory $TARGET_DIR..."
if [ -d "$TARGET_DIR" ]; then
rm -rf "$TARGET_DIR"
echo " OK directory removed"
else
echo " SKIP directory does not exist"
fi
echo
# --- Step 4: Clean up temp files left by doctor script ---
echo "[step 4/5] Cleaning temp files..."
cleaned=false
for f in /tmp/star_office_doctor_body.txt /tmp/star_office_port_*.txt; do
if [ -f "$f" ]; then
rm -f "$f"
echo " removed $f"
cleaned=true
fi
done
if [ "$cleaned" = false ]; then
echo " no temp files to clean"
fi
echo
# --- Step 5: Final verification ---
echo "[step 5/5] Final verification..."
errors=0
# Check processes
if pgrep -f "$TARGET_DIR" >/dev/null 2>&1 || pgrep -f "$dir_basename/backend\|$dir_basename/frontend" >/dev/null 2>&1; then
echo " FAIL Star-Office-UI processes still running:"
pgrep -af "$TARGET_DIR" 2>/dev/null || true
pgrep -af "$dir_basename" 2>/dev/null || true
errors=$((errors + 1))
else
echo " OK no Star-Office-UI processes"
fi
# Check ports
for port in "$PORT_FRONTEND" "$PORT_BACKEND"; do
occupant="$(lsof -ti :"$port" 2>/dev/null || true)"
if [ -n "$occupant" ]; then
cmd="$(ps -p "$occupant" -o args= 2>/dev/null || true)"
if echo "$cmd" | grep -qi "star.office\|$dir_basename" 2>/dev/null; then
echo " FAIL port $port still occupied by Star-Office process"
errors=$((errors + 1))
else
echo " OK port $port occupied by unrelated process (not a Star-Office residual)"
fi
else
echo " OK port $port free"
fi
done
# Check directory
if [ -d "$TARGET_DIR" ]; then
echo " FAIL directory still exists: $TARGET_DIR"
errors=$((errors + 1))
else
echo " OK directory gone"
fi
echo
if [ "$errors" -eq 0 ]; then
echo "[star-office-uninstall] Done. Star Office has been completely uninstalled."
else
echo "[star-office-uninstall] Completed with $errors issue(s). Review output above."
fi