LangBot/docs/event-based-agents/adapters/qqofficial.md

# QQOfficial EBA Adapter

Adapter directory: `src/langbot/pkg/platform/adapters/qqofficial/`

Manifest name: `qqofficial-eba`

Status: partial migration. The EBA adapter structure, manifest, converters, cache-backed safe APIs, platform API map, unit tests, and direct live probe scaffold are in place. A real QQ Official WebSocket bot on `dev.rockchin.top` received an inbound user message and drove LangBot into the normal pipeline path; the response path was blocked by the test environment model service returning `model_not_found` for `deepseek-v3`.

## Config

| Field | Required | Notes |
| --- | --- | --- |
| `appid` | yes | QQ Official app ID. |
| `secret` | yes | QQ Official app secret. |
| `token` | yes | QQ Official callback token. |
| `enable-webhook` | yes | Uses LangBot unified webhook when true; otherwise uses the QQ WebSocket gateway. |
| `enable-stream-reply` | yes | Enables C2C streaming replies when supported by the QQ Official endpoint. |
| `webhook_url` | no | Generated by LangBot and copied into the QQ Official callback settings in webhook mode. |

## Events

| Event | Evidence | Notes |
| --- | --- | --- |
| `message.received` | adapter-live, unit | `C2C_MESSAGE_CREATE`, `DIRECT_MESSAGE_CREATE`, `GROUP_AT_MESSAGE_CREATE`, and `AT_MESSAGE_CREATE` map to common `MessageReceivedEvent`. A real WebSocket-mode QQ Official bot reached the LangBot pipeline on `dev.rockchin.top`; plugin JSONL evidence remains pending. |
| `platform.specific` | unit, blocked | Unmapped gateway events are emitted as structured `PlatformSpecificEvent`; live evidence is pending. |

## Common APIs

| API | Evidence | Notes |
| --- | --- | --- |
| `send_message` | unit, blocked | Sends private C2C, group, and text-only channel messages through the existing QQ Official client. Live outbound UI verification is pending because the test pipeline failed before producing a bot response. |
| `reply_message` | unit, blocked | Replies using the source `QQOfficialEvent` message ID when available. Live reply was blocked by the test environment model service returning `model_not_found`. |
| `get_message` | unit | Returns cached inbound `MessageReceivedEvent`. |
| `get_user_info` | unit | Returns cached inbound sender. |
| `get_friend_list` | unit | Returns cached private senders. |
| `get_group_info` | unit | Returns cached group/channel metadata from inbound events. |
| `get_group_member_info` | unit | Returns cached group sender as a common member. |
| `get_group_member_list` | unit | Returns cached group members observed by the adapter. |
| `call_platform_api` | unit, blocked | Safe diagnostic actions are implemented; live calls are pending credentials. |

## Platform APIs

| Action | Evidence | Notes |
| --- | --- | --- |
| `check_access_token` | unit, blocked | Calls the existing client token check. |
| `refresh_access_token` | unit, blocked | Forces token refresh. |
| `get_gateway_url` | unit, blocked | Fetches the WebSocket gateway URL. |
| `get_mode` | unit | Returns webhook and stream-reply mode. |

## Components

| Receive Component | Evidence | Notes |
| --- | --- | --- |
| `Source` | unit | Uses QQ message/event IDs and timestamp. |
| `Plain` | unit | Preserves text content. |
| `At` | unit | Group and channel mention events insert an adapter bot mention marker. |
| `Image` | unit | QQ image attachment URL is converted to common `Image`; falls back to URL if download fails. |
| `Unknown` | unit | Unsupported/empty native payloads become `Unknown`. |
| `Voice`, `File`, `Quote`, `Face`, `Forward`, mixed chain | blocked | Current native parser only exposes text and image attachments; live endpoint behavior still needs verification. |

| Send Component | Evidence | Notes |
| --- | --- | --- |
| `Plain` | unit, blocked | Sends through private, group, or channel text APIs. |
| `At`, `AtAll` | unit, blocked | Converted to readable mention text. |
| `Image` | unit, blocked | Sends through the QQ Official rich media upload/send path for C2C and group targets. |
| `Voice` | unit, blocked | Sends through the QQ Official rich media upload/send path for C2C and group targets. |
| `File` | unit, blocked | Sends through the QQ Official rich media upload/send path for C2C and group targets. |
| `Quote`, `Forward`, mixed chain | unit, blocked | Flattened to ordered send payloads where possible. |
| `Face` | not-supported | No common QQ Official face mapping is implemented. |

## Verification Record

Test date: 2026-06-02

Endpoint/simulator: `dev.rockchin.top` with a real QQ Official WebSocket bot (`qqofficial-eba`, bot UUID `80a5560b-52b1-40e7-b7d6-4a2341eb4780`) and LangBot running from `/home/wgc/LangBotxg/LangBotEbaTest`.

Observed evidence:

- The QQ Official WebSocket bot was enabled with `enable-webhook=false`.
- A real user message reached LangBot and entered the standard pipeline path.
- The response path stopped at the model layer with `model_not_found` for `deepseek-v3`; this is a model/provider configuration issue, not an adapter conversion failure.
- `qq-webhook.langbot.dev` was temporarily routed through Caddy to `127.0.0.1:5301` for webhook checks, but the observed EBA bot used WebSocket mode.

Standalone runtime command:

```bash
cd langbot-plugin-sdk
uv run python -m langbot_plugin.cli.__init__ rt --debug-only --ws-control-port 5400 --ws-debug-port 5401 --skip-deps-check
```

Probe plugin: `data/plugins/LangBot__EBAEventProbe` when live credentials are available.

Adapter live probe:

```bash
uv run python -m py_compile tests/e2e/live_qqofficial_eba_probe.py
QQOFFICIAL_APPID=... QQOFFICIAL_SECRET=... QQOFFICIAL_TOKEN=... uv run python tests/e2e/live_qqofficial_eba_probe.py
```

Webhook-mode probe:

```bash
QQOFFICIAL_APPID=... QQOFFICIAL_SECRET=... QQOFFICIAL_TOKEN=... uv run python tests/e2e/live_qqofficial_eba_probe.py --webhook --host 0.0.0.0 --port 5312
```

Evidence JSONL path: `data/temp/qqofficial_eba_probe.jsonl` for direct adapter live probe; plugin E2E evidence should use `data/temp/qqofficial_eba_plugin_probe.jsonl`.

Destructive operations: none implemented.

Blocked items:

- `plugin-e2e-ui`: standalone probe plugin JSONL evidence is still pending; the observed live run reached LangBot core/pipeline but was not recorded by the EBA probe plugin.
- `plugin-e2e-outbound`: waiting for visible QQ client verification of plugin `send_message`/`reply_message` output after a working model/provider is configured.
- Inbound non-text media and platform lifecycle events require endpoint evidence before they can be marked complete.