release: public alpha 0.6.0 baseline

2026-10-15 03:58:31 +08:00
commit d4242ae07c
238 changed files with 37724 additions and 0 deletions
@@ -0,0 +1,134 @@
+# Edge Runbook
+
+JWeBot Edge is the local source of truth for accepted events, command state,
+provider work, acknowledgements, and final delivery.
+
+## Routes
+
+| Input after mention removal | Route | Execution |
+|---|---|---|
+| `/...` | Local | Kernel command or reviewed plugin |
+| ordinary text | Chat | Direct DeepSeek client |
+| `#...` | Cloud | Optional configured cloud agent |
+
+The bot mention is read from the active profile. The public default is
+`@JWeBot`.
+
+## Steam
+
+Commands:
+
+```text
+/steam
+/steam在线
+/steam游戏
+/steam全部
+/steam刷新
+/steam时长 游戏名
+/steam时长游戏名
+/steam时长游戏名、玩家名
+/steam时长游戏名人=玩家名
+```
+
+The configured Steam account supplies the owner ID and API key. At runtime the
+provider:
+
+1. uses private per-person SteamID mappings when configured, otherwise fetches
+   the public friend list;
+2. batches public player summaries in groups of 100;
+3. labels mapped accounts with their group display IDs and accepts their
+   private Steam query aliases;
+4. fuzzy matches the requested game against the owner's public library;
+5. falls back to scoped public libraries if the owner has no match;
+6. requests the selected AppID for every scoped account with bounded
+   concurrency;
+7. sorts public playtime descending and summarizes private/unavailable data.
+
+For a player-specific query, `、`, `，`, `,`, `@`, or `人=` explicitly separates
+the game from the player. The provider matches the live persona name and only
+requests that account's game library; ambiguous matches are rejected instead
+of guessed.
+
+Steam access is fixed to `api.steampowered.com` through the configured loopback
+Mihomo HTTP proxy. There is no direct-network fallback.
+
+## Config
+
+Inspect active profile metadata without printing values:
+
+```sh
+./tools/jwebot-config.py status
+```
+
+Validate and atomically regenerate:
+
+```sh
+./tools/jwebot-config.py activate <profile>
+```
+
+Services read:
+
+```text
+~/.config/jwebot/current/generated/runtime.env
+```
+
+Private context, debug state, incidents, and root evidence live outside Git as
+documented in `config/README.md`.
+
+## Health
+
+```sh
+runtime_python=${JWEBOT_RUNTIME_PYTHON:-/opt/jwebot/venv/bin/python}
+
+printf '%s\n' '{"op":"health"}' |
+  "$runtime_python" ~/.local/lib/wechat-health-watch/jwebot_edge.py respond
+
+"$runtime_python" ~/.local/lib/wechat-health-watch/jwebot_edge.py status
+```
+
+Expected:
+
+- Edge and adaptive recorder active;
+- `NRestarts=0` after the settle window;
+- OCR queues empty;
+- direct/cloud outboxes empty or actively progressing;
+- SQLite `PRAGMA quick_check` returns `ok`;
+- legacy OCR services disabled and inactive.
+
+## Delivery Contract
+
+- Fast ACK is persisted before GUI delivery.
+- Final work starts independently from final GUI delivery.
+- A final reply is not delivered until its ACK is visibly confirmed.
+- Steam uses a dedicated progress ACK.
+- ACK/local work may pass a queued final that has not started.
+- Active GUI work is non-preemptive.
+- The GUI sender remains strictly serial.
+- Every final send rechecks the selected group fingerprint.
+
+## Failure Handling
+
+Provider failure:
+
+- keep credentials and provider payloads out of logs;
+- record only bounded error classes;
+- retry through durable queue policy;
+- do not bypass the configured proxy.
+
+GUI uncertainty:
+
+- never blindly replay a send after `send_started`;
+- preserve the uncertain artifact in private incident state;
+- require visual/operator confirmation before retry.
+
+Group mismatch:
+
+- skip delivery;
+- keep the event ledgered;
+- do not select or navigate to another group automatically.
+
+## Telemetry
+
+Telemetry may include step name, status, elapsed time, queue state, retry count,
+and hashed event/group IDs. It must never include message bodies, sender names,
+reply text, environment values, credentials, SteamIDs, or provider payloads.