xinyin025/LangBot
1
0
Fork 0
mirror of https://github.com/langbot-app/LangBot.git synced 2026-06-11 16:26:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(platform): add qqofficial eba adapter

Browse Source
This commit is contained in:
WangCham
2026-06-02 16:51:45 +08:00
parent 8a42fd8b21
commit 7e5d74a1ad
15 changed files with 1469 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/event-based-agents/adapters/00-index.md
View File

@@ -23,6 +23,7 @@ Current acceptance report: [EBA Adapter Acceptance Report](./acceptance-report.m
| WeCom | Migrated; private text plugin E2E verified, media/group gaps remain | [WeCom](./wecom.md) |
| WeComBot | Migrated; private text and outbound/API plugin E2E verified, feedback/group gaps remain | [WeComBot](./wecombot.md) |
| Official Account | Migrated; private text plugin E2E verified, proactive outbound not supported | [Official Account](./officialaccount.md) |
| QQ Official API | Migrated; WebSocket inbound reached LangBot, model config blocked reply | [QQ Official API](./qqofficial.md) |
## Documentation Checklist

3
docs/event-based-agents/adapters/acceptance-report.md
View File

@@ -13,6 +13,7 @@ Scope:
- `wecombot-eba`
- `wecomcs-eba`
- `officialaccount-eba`
- `qqofficial-eba`
This report follows `acceptance-checklist.md`. Evidence levels are intentionally strict:
@@ -36,6 +37,7 @@ This report follows `acceptance-checklist.md`. Evidence levels are intentionally
| WeComBot | Partial EBA acceptance | WeCom AI Bot is split into the EBA directory with WebSocket long connection mode and optional webhook mode, EBA message/feedback/platform-specific conversion, cache-backed common APIs, platform API map, unit tests, and a direct live probe. Private text, outbound component sweep, safe common APIs, and all declared WeComBot platform APIs reached `EBAEventProbe`; group, real inbound media, and feedback callback evidence remain pending. |
| WeCom Customer Service | Partial EBA acceptance | WeCom Customer Service is split into the EBA directory with manifest, converters, API mixin, platform API map, unit tests, docs, and a direct live probe scaffold. Real WeChat customer-side UI text reached `EBAEventProbe`; plugin outbound text/image and safe cache-backed common APIs passed. Inbound media and platform-specific API live coverage remain pending; later fallback text sends were blocked by WeCom `95001 send msg count limit`. |
| Official Account | Partial EBA acceptance | WeChat Official Account is split into the EBA directory with manifest, converters, cache-backed safe APIs, platform API map, unit tests, and a direct live probe scaffold. Real WeChat Official Account UI private text reached `EBAEventProbe`; safe cache-backed common APIs and declared platform APIs passed. Proactive outbound `send_message` is not supported because replies must be tied to inbound webhook windows; inbound image/voice live UI evidence remains pending. |
| QQ Official API | Partial EBA acceptance | QQ Official API is split into the EBA directory with manifest, converters, cache-backed safe APIs, platform API map, unit tests, docs, and a direct live probe scaffold. A real WebSocket-mode QQ Official bot reached the LangBot pipeline on `dev.rockchin.top`; reply/outbound evidence is blocked by the test model provider returning `model_not_found` for `deepseek-v3`. |
Telegram and DingTalk now have real user-side UI image/file upload evidence in plugin JSONL. Discord and aiocqhttp do not yet have real UI inbound image/file evidence.
@@ -55,6 +57,7 @@ Telegram and DingTalk now have real user-side UI image/file upload evidence in p
| Lark / Feishu partial live | Feishu Mac, LangBot organization `LangBotDev` private chat | `data/temp/lark-plugin-e2e-ws.jsonl` |
| WeCom Customer Service | WeChat customer-side UI, `客服消息 -> 浪波智能客服` on `dev.rockchin.top` | `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/wecomcs_eba_plugin_probe.jsonl` |
| Official Account | WeChat desktop client, subscribed Official Account on `dev.rockchin.top` | `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/officialaccount_eba_plugin_probe.jsonl` |
| QQ Official API unit | local mocked QQ Official client paths | `tests/unit_tests/platform/test_qqofficial_eba_adapter.py` |
All plugin runs used SDK standalone runtime ports `5400/5401`, LangBot `--standalone-runtime`, and the real plugin at `langbot-plugin-demo/EBAEventProbe`.

114
docs/event-based-agents/adapters/qqofficial.md Normal file
View File

@@ -0,0 +1,114 @@
# 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.