# 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.