135 lines
3.8 KiB
Markdown
135 lines
3.8 KiB
Markdown
# 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.
|