docs: add eba adapter migration records

2026-06-02 12:05:54 +00:00 · 2026-05-07 18:44:05 +08:00
parent 05f370ca49
commit 503d29ffed
3 changed files with 246 additions and 0 deletions
--- a/docs/event-based-agents/adapters/00-index.md
+++ b/docs/event-based-agents/adapters/00-index.md
@@ -0,0 +1,26 @@
+# EBA Adapter Migration Records
+
+This directory records adapter-level migration details for the Event-Based Agents architecture. Each adapter document should be kept close to the implementation and must answer four questions:
+
+1. What changed in the adapter structure.
+2. Which configuration fields are required.
+3. Which events and APIs are supported.
+4. What has been verified end to end.
+
+## Adapter Documents
+
+| Adapter | Status | Document |
+|---------|--------|----------|
+| Telegram | Migrated and live-tested | [Telegram](./telegram.md) |
+| Discord | In progress | [Discord](./discord.md) |
+
+## Documentation Checklist
+
+When migrating a new adapter, add one document here with:
+
+- Configuration table matching the adapter manifest.
+- Supported event list.
+- Supported common API list.
+- Supported `call_platform_api` action list.
+- Known unsupported APIs and the reason.
+- Live test notes, including platform, channel type, destructive operations, and residual risks.
--- a/docs/event-based-agents/adapters/discord.md
+++ b/docs/event-based-agents/adapters/discord.md
@@ -0,0 +1,108 @@
+# Discord EBA Adapter
+
+## Status
+
+Discord is currently being migrated from the legacy source adapter:
+
+```text
+src/langbot/pkg/platform/sources/discord.py
+src/langbot/pkg/platform/sources/discord.yaml
+```
+
+Target EBA directory:
+
+```text
+src/langbot/pkg/platform/adapters/discord/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+├── types.py
+└── voice.py
+```
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `client_id` | Yes | `""` | Discord application client ID. |
+| `token` | Yes | `""` | Discord bot token. |
+
+The bot needs gateway permissions and intents for the target test server. Message content intent is required for message-based EBA events.
+
+## Planned Events
+
+Initial EBA migration should support:
+
+- `message.received`
+- `message.edited`
+- `message.deleted`
+- `message.reaction`
+- `group.member_joined`
+- `group.member_left`
+- `bot.invited_to_group`
+- `bot.removed_from_group`
+- `platform.specific`
+
+Discord-specific events that do not map cleanly to common events should be surfaced as `platform.specific`.
+
+## Planned Common APIs
+
+| API | Expected Status | Notes |
+|-----|-----------------|-------|
+| `send_message` | Supported | Text plus attachment files. |
+| `reply_message` | Supported | Uses Discord message references. |
+| `edit_message` | Supported | Bot can edit its own messages. |
+| `delete_message` | Supported | Requires message management permissions for non-bot messages. |
+| `forward_message` | Emulated | Discord has no native forward API; copy content and attachments when possible. |
+| `get_group_info` | Supported | Maps Discord guild/channel metadata into EBA group info depending on target ID. |
+| `get_group_member_list` | Supported | Requires member cache or guild member fetch permissions. |
+| `get_group_member_info` | Supported | Maps Discord roles/permissions into EBA member roles. |
+| `get_user_info` | Supported | Uses Discord user fetch/cache. |
+| `upload_file` | Not standalone | Discord uploads files as message attachments; standalone upload should raise `NotSupportedError` unless a storage-backed design is added. |
+| `get_file_url` | Supported for attachment URLs | Discord attachment URLs are already downloadable URLs. |
+| `mute_member` | Supported where possible | Prefer Discord timeout API for guild members. |
+| `unmute_member` | Supported where possible | Clears timeout. |
+| `kick_member` | Supported | Destructive; test only with a disposable account/bot. |
+| `leave_group` | Supported | Bot leaves a guild; destructive and should run last. |
+| `call_platform_api` | Supported | Discord-specific actions live here. |
+
+## Planned Platform-Specific APIs
+
+Initial actions to expose through `call_platform_api`:
+
+- `get_channel`
+- `get_guild`
+- `get_guild_channels`
+- `get_guild_roles`
+- `create_invite`
+- `pin_message`
+- `unpin_message`
+- `add_reaction`
+- `remove_reaction`
+- `typing`
+
+Voice actions should stay Discord-specific:
+
+- `join_voice_channel`
+- `leave_voice_channel`
+- `get_voice_connection_status`
+- `list_active_voice_connections`
+- `get_voice_channel_info`
+
+## Live Test Plan
+
+Use the LangBot Discord server debug channel for end-to-end verification:
+
+1. Create or reuse a Discord bot application.
+2. Invite it to the LangBot server with message, member, reaction, and moderation permissions needed by the test.
+3. Run the Discord EBA adapter in standalone test mode.
+4. Send a message in the debug channel and verify `message.received`.
+5. Verify send/reply/edit/delete/forward message APIs.
+6. Verify attachment/file URL behavior.
+7. Verify guild/channel/member info APIs.
+8. Verify platform-specific APIs such as typing, pin/unpin, invite, reaction.
+9. Verify moderation APIs against a disposable target member if available.
+10. Run destructive `leave_group` only at the very end or skip it when preserving the server membership matters.
--- a/docs/event-based-agents/adapters/telegram.md
+++ b/docs/event-based-agents/adapters/telegram.md
@@ -0,0 +1,112 @@
+# Telegram EBA Adapter
+
+## Status
+
+Telegram has been migrated to the EBA adapter directory:
+
+```text
+src/langbot/pkg/platform/adapters/telegram/
+├── adapter.py
+├── api_impl.py
+├── event_converter.py
+├── manifest.yaml
+├── message_converter.py
+├── platform_api.py
+└── types.py
+```
+
+The adapter is registered as `telegram-eba`.
+
+## Configuration
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `token` | Yes | `""` | Telegram Bot API token from BotFather. |
+| `markdown_card` | No | `true` | Whether to render Markdown card style replies. |
+| `enable-stream-reply` | Yes | `false` | Whether to use Telegram streaming reply mode. |
+
+## Events
+
+Telegram declares these EBA events:
+
+- `message.received`
+- `message.edited`
+- `message.reaction`
+- `group.member_joined`
+- `group.member_left`
+- `group.member_banned`
+- `bot.invited_to_group`
+- `bot.removed_from_group`
+- `bot.muted`
+- `bot.unmuted`
+- `platform.specific`
+
+`platform.specific` is currently used for Telegram-only callback and chat-member update payloads that do not yet have a more specific common event type.
+
+## Common APIs
+
+| API | Status | Notes |
+|-----|--------|-------|
+| `send_message` | Supported | Supports text, image, file, and mixed message chains. |
+| `reply_message` | Supported | Supports quoted replies through the original message event. |
+| `edit_message` | Supported | Uses Telegram message editing APIs. |
+| `delete_message` | Supported | Deletes messages where bot permissions allow it. |
+| `forward_message` | Supported | Forwards a message between Telegram chats. |
+| `get_group_info` | Supported | Uses Telegram chat metadata. |
+| `get_group_member_list` | Supported | Telegram only exposes administrators through the Bot API; this returns the available member set. |
+| `get_group_member_info` | Supported | Maps Telegram member status to EBA member roles. |
+| `get_user_info` | Supported | Uses Telegram `get_chat` for user chat metadata. |
+| `upload_file` | Not supported | Telegram has no standalone upload endpoint; files are uploaded as part of messages. The adapter raises `NotSupportedError`. |
+| `get_file_url` | Supported | Returns the Bot API file URL. Test output redacts the bot token. |
+| `mute_member` | Supported | Requires a supergroup and bot moderation permission. |
+| `unmute_member` | Supported | Uses current `telegram.ChatPermissions` fields. |
+| `kick_member` | Supported | Destructive; should only be run against disposable users/bots in tests. |
+| `leave_group` | Supported | Destructive; should run at the end of a live test. |
+| `call_platform_api` | Supported | See below. |
+
+## Platform-Specific APIs
+
+`call_platform_api(action, params)` supports:
+
+- `pin_message`
+- `unpin_message`
+- `unpin_all_messages`
+- `get_chat_administrators`
+- `set_chat_title`
+- `set_chat_description`
+- `get_chat_member_count`
+- `send_chat_action`
+- `create_chat_invite_link`
+- `answer_callback_query`
+
+## Live Test Record
+
+The live probe is:
+
+```bash
+uv run python tests/e2e/live_telegram_eba_probe.py --help
+```
+
+It supports private chat tests, group/supergroup tests, moderation tests, destructive tests, and a callback-only mode.
+
+Verified on May 7, 2026:
+
+- Private chat message APIs: send, reply, edit, delete, forward.
+- Private chat media APIs: image/file sending and `get_file_url`.
+- User API: `get_user_info`.
+- Supergroup APIs: group info, member list, member info, administrators, member count, invite link.
+- Supergroup mutation APIs: pin, unpin, unpin all, set title, restore title, set description, restore description.
+- Moderation APIs: mute and unmute against a non-owner target bot.
+- Destructive APIs: kick a disposable target bot, then make the test bot leave the test group.
+- Event conversion observed for `message.received`, `group.member_banned`, `group.member_left`, `bot.removed_from_group`, and Telegram-specific chat-member updates.
+
+The test fixed one real compatibility issue: `unmute_member` previously used Telegram's removed `can_send_media_messages` permission field. It now uses the split media permission fields required by current `python-telegram-bot`.
+
+## Notes for Future Adapters
+
+Telegram is the reference implementation for:
+
+- Keeping platform-specific actions behind `call_platform_api`.
+- Treating unsupported common APIs as explicit `NotSupportedError`.
+- Marking destructive live test operations behind CLI flags.
+- Redacting access tokens from live probe output.