feat(officialaccount): add eba adapter

2026-06-04 21:06:03 +00:00 · 2026-05-28 16:59:26 +08:00
parent 4b9aa20985
commit 8a42fd8b21
16 changed files with 1099 additions and 4 deletions
--- a/docs/event-based-agents/adapters/00-index.md
+++ b/docs/event-based-agents/adapters/00-index.md
@@ -22,6 +22,7 @@ Current acceptance report: [EBA Adapter Acceptance Report](./acceptance-report.m
 | Lark / Feishu | Migrated; partial live text E2E, media-inbound gap remains | [Lark / Feishu](./lark.md) |
 | 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) |

 ## Documentation Checklist

--- a/docs/event-based-agents/adapters/acceptance-report.md
+++ b/docs/event-based-agents/adapters/acceptance-report.md
@@ -12,6 +12,7 @@ Scope:
 - `wecom-eba`
 - `wecombot-eba`
 - `wecomcs-eba`
+- `officialaccount-eba`

 This report follows `acceptance-checklist.md`. Evidence levels are intentionally strict:

@@ -34,6 +35,7 @@ This report follows `acceptance-checklist.md`. Evidence levels are intentionally
 | WeCom | Partial EBA acceptance | Regular WeCom application-message adapter is split into the EBA directory with manifest, converters, API mixin, platform API map, and unit tests. Private text reached `EBAEventProbe` through standalone runtime and the real WeCom client; safe plugin APIs passed. Real inbound media and broader event coverage remain pending. |
 | 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. |

 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.

@@ -52,6 +54,7 @@ Telegram and DingTalk now have real user-side UI image/file upload evidence in p
 | Lark / Feishu unit | local mocked Feishu SDK/client paths | `tests/unit_tests/platform/test_lark_eba_adapter.py` |
 | 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` |

 All plugin runs used SDK standalone runtime ports `5400/5401`, LangBot `--standalone-runtime`, and the real plugin at `langbot-plugin-demo/EBAEventProbe`.

--- a/docs/event-based-agents/adapters/officialaccount.md
+++ b/docs/event-based-agents/adapters/officialaccount.md
@@ -0,0 +1,101 @@
+# OfficialAccount EBA Adapter
+
+Adapter directory: `src/langbot/pkg/platform/adapters/officialaccount/`
+
+Manifest name: `officialaccount-eba`
+
+Status: partial migration. Unit/API-shape coverage is present, and private text `plugin-e2e-ui` plus safe API evidence has been verified against the `dev.rockchin.top` Official Account fixture. Proactive outbound `send_message` remains not supported by this adapter because WeChat Official Account replies must be tied to inbound webhook windows.
+
+## Config
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `webhook_url` | no | Generated by LangBot and copied into the Official Account callback settings. |
+| `token` | yes | WeChat callback token. |
+| `EncodingAESKey` | yes | WeChat message encryption key. |
+| `AppID` | yes | Official Account app ID. |
+| `AppSecret` | yes | Official Account app secret. |
+| `Mode` | yes | `drop` waits for an in-callback reply; `passive` returns the loading text first and queues the answer for the user's next message. |
+| `LoadingMessage` | no | Only used by `passive` mode. |
+| `api_base_url` | no | Optional API base URL for proxy deployments. |
+
+## Events
+
+| Event | Evidence | Notes |
+| --- | --- | --- |
+| `message.received` | plugin-e2e-ui, unit | Text UI message verified through WeChat Official Account on `dev.rockchin.top`; image and voice webhook payloads are covered by unit tests. |
+| `platform.specific` | unit | Subscribe/menu/etc. native events are emitted as structured `PlatformSpecificEvent`. |
+
+## Common APIs
+
+| API | Evidence | Notes |
+| --- | --- | --- |
+| `reply_message` | unit | Queues/passively returns text through the inbound webhook source event. |
+| `get_message` | plugin-e2e-ui, unit | Cached inbound message retrieved by `EBAEventProbe` platform API sweep. |
+| `get_user_info` | plugin-e2e-ui, unit | Cached inbound sender retrieved by `EBAEventProbe` platform API sweep. |
+| `get_friend_list` | plugin-e2e-ui, unit | Cached inbound sender list retrieved by `EBAEventProbe` platform API sweep. |
+| `call_platform_api` | plugin-e2e-ui, unit | Safe diagnostic actions verified through `get_mode` and `get_cached_response_status`. |
+| `send_message` | not-supported | Official Account customer-service proactive messaging is not implemented by the existing SDK adapter; only webhook reply is supported here. |
+
+## Platform APIs
+
+| Action | Evidence | Notes |
+| --- | --- | --- |
+| `get_mode` | plugin-e2e-ui, unit | Returned `{"mode": "drop", "longer_response": false}` in live probe. |
+| `get_cached_response_status` | plugin-e2e-ui, unit | Returned `{"pending": false}` in live probe. |
+
+## Components
+
+| Receive Component | Evidence | Notes |
+| --- | --- | --- |
+| `Source` | plugin-e2e-ui, unit | Uses `MsgId` and `CreateTime`; live UI text message included `Source`. |
+| `Plain` | plugin-e2e-ui, unit | Live UI text message mapped to `Plain`. |
+| `Image` | unit | `PicUrl` and `MediaId` map to common `Image`. |
+| `Voice` | unit | `MediaId` maps to common `Voice`. |
+| `Unknown` | unit | Unsupported message/event types do not crash. |
+| `At`, `AtAll`, `File`, `Quote`, `Face`, `Forward`, mixed chain | not-supported | WeChat Official Account inbound webhook payloads used by the current SDK do not expose these as common structured components. |
+
+| Send Component | Evidence | Notes |
+| --- | --- | --- |
+| `Plain` | unit | Sent as webhook reply text. |
+| `Image`, `Voice`, `File`, `Quote`, `At`, `AtAll`, `Face`, `Forward`, mixed chain | not-supported | Existing SDK reply path is text XML only; non-text components degrade to readable placeholders in tests and are not declared as supported outbound components. |
+
+## Verification Record
+
+Test date: 2026-05-28
+
+Endpoint/simulator: `dev.rockchin.top` with WeChat desktop client and a real subscribed Official Account conversation. The running EBA test stack used SDK standalone runtime ports `5400/5401`, LangBot from `/home/wgc/LangBotxg/LangBotEbaTest`, and `EBAEventProbe`.
+
+Verified UI message: `EBA officialaccount single probe 2026-05-28 16:53`
+
+Observed event/API evidence:
+
+- `MessageReceived`: `bot_uuid=d7c46880-a9f8-431a-9172-5d3e0d663dbc`, `adapter_name=officialaccount-eba`, `chat_type=private`, `chat_id=ovH9L7OW6hNpWZWvp_NMmypVh26w`, `message_chain=[Source, Plain]`.
+- Common safe APIs through probe platform sweep: `get_message`, `get_user_info`, `get_friend_list`.
+- Platform APIs through `call_platform_api`: `get_mode`, `get_cached_response_status`.
+- `send_message` and outbound component sweep returned explicit `NotSupportedError: send_message:official_account_requires_inbound_webhook_reply`, as expected for this adapter.
+
+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_officialaccount_eba_probe.py
+OFFICIALACCOUNT_TOKEN=... OFFICIALACCOUNT_ENCODING_AES_KEY=... OFFICIALACCOUNT_APP_SECRET=... OFFICIALACCOUNT_APP_ID=... uv run python tests/e2e/live_officialaccount_eba_probe.py
+```
+
+Evidence JSONL path: `/home/wgc/LangBotxg/LangBotEbaTest/data/temp/officialaccount_eba_plugin_probe.jsonl` for plugin E2E, or `data/temp/officialaccount_eba_probe.jsonl` for direct adapter live probe.
+
+Destructive operations: none.
+
+Blocked items:
+
+- `plugin-e2e-outbound`: proactive `send_message` is not supported for this adapter; Official Account responses must be produced through the inbound webhook reply window.
+- Inbound image and voice live UI evidence remains pending; webhook conversion is covered by unit tests.