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

KOOK EBA Adapter

Status

KOOK has been migrated to the EBA adapter directory:

src/langbot/pkg/platform/adapters/kook/
├── adapter.py
├── api_impl.py
├── event_converter.py
├── manifest.yaml
├── message_converter.py
├── platform_api.py
└── types.py

The adapter is registered as kook-eba.

Configuration

Field	Required	Default	Description
token	Yes	""	KOOK bot token.
enable-stream-reply	Yes	false	Reserved for shared platform configuration compatibility.

Events

Event	Evidence	Notes
message.received	plugin-e2e-ui	Real KOOK UI channel message reached EBAEventProbe as MessageReceivedEvent.
platform.specific	plugin-e2e-ui	KOOK gateway event without a common EBA mapping reached EBAEventProbe as PlatformSpecificEventReceived.

Common APIs

API	Evidence	Notes
send_message	plugin-e2e-outbound	Probe plugin sent channel messages through SDK send_message; KOOK returned message IDs.
reply_message	unit	Supports reply_msg_id and optional quoted replies when the source message ID is available.
get_message	plugin-e2e-outbound	Probe plugin fetched the cached triggering message.
get_group_info	plugin-e2e-outbound	Probe plugin received cached KOOK channel info.
get_group_list	plugin-e2e-outbound	Probe plugin received cached channel/group entities observed by the adapter.
get_group_member_info	plugin-e2e-outbound	Probe plugin received cached sender info as a group member.
get_user_info	plugin-e2e-outbound	Probe plugin received cached sender user info.
get_friend_list	plugin-e2e-outbound	Probe plugin received cached users.
upload_file	unit	Uses KOOK asset/create and returns URL/ID.
get_file_url	unit	KOOK media IDs are URL-like in the adapter path; returns the ID unchanged.
delete_message	unit	Calls KOOK delete endpoints. Live permission verification is still required.
forward_message	plugin-e2e-outbound	Probe plugin sent flattened forward content through SDK send_message.
call_platform_api	plugin-e2e-outbound	Probe plugin called safe KOOK platform-specific APIs through SDK call_platform_api.

Platform-Specific APIs

Action	Evidence	Notes
get_current_user	plugin-e2e-outbound	Probe plugin called user/me.
get_user	plugin-e2e-outbound	Probe plugin called user/view for the triggering sender.
get_channel	plugin-e2e-outbound	Probe plugin called channel/view for the triggering channel.
get_guild	plugin-e2e-outbound	Probe plugin called guild/view; gateway URLs redact token query values.
get_gateway	plugin-e2e-outbound	Probe plugin called gateway/index; returned token query values are redacted.
send_direct_message	unit	Calls direct-message/create.

Components

Component	Receive Evidence	Send Evidence	Notes
Source	plugin-e2e-ui	N/A	KOOK message ID and timestamp are preserved.
Plain	plugin-e2e-ui	plugin-e2e-outbound	Text and KMarkdown are represented as plain common text.
At	plugin-e2e-ui	plugin-e2e-outbound	KOOK (met)<id>(met) mentions map to common At.
AtAll	unit	plugin-e2e-outbound	KOOK (met)all(met) maps to common AtAll; real inbound UI AtAll was not tested.
Image	unit	unit	URL/image ID based path only; live rendering still needs verification.
Voice	unit	unit	URL based path only; live rendering still needs verification.
File	unit	unit	URL based path only; upload API is exposed separately.
Forward	unit	unit	Outbound forwards are flattened; inbound structured forwards are not exposed by current legacy implementation.
Unknown	unit	N/A	Unsupported KOOK message types become Unknown or PlatformSpecificEvent.

Acceptance Record

Test date: June 4, 2026.

Plugin E2E verified on June 4, 2026 with EBAEventProbe, SDK standalone runtime, KOOK WebSocket adapter, and a real KOOK channel UI message.

Evidence:

• JSONL: data/temp/kook_eba_plugin_probe.jsonl
• Plugin log: data/logs/eba-probe-kook.log

Observed and verified:

• A real KOOK UI channel message reached the plugin as MessageReceived with bot_uuid=7ab5b065-6e4e-4def-95f0-3c265366e26f, adapter_name=kook, common sender/group/chat fields, and common MessageChain components.
• KOOK gateway-specific event reached the plugin as PlatformSpecificEventReceived.
• Probe plugin called SDK send_message; KOOK returned message IDs for text, At, AtAll, image URL/base64 fallback path, quote fallback, file fallback, and flattened forward cases.
• Probe plugin called common API methods through the SDK path: get_message, get_user_info, get_friend_list, get_group_info, get_group_list, and get_group_member_info.
• Probe plugin called safe KOOK platform-specific APIs through SDK call_platform_api: get_current_user, get_user, get_channel, get_gateway, and get_guild.

Run:

uv run pytest tests/unit_tests/platform/test_kook_eba_adapter.py
git diff --check

Blocked or partial items:

• plugin-e2e-ui inbound coverage for image, file, voice, AtAll, quote, and forward.
• plugin-e2e-outbound visual verification in KOOK UI for image/file/voice rendering. KOOK returned message IDs, but UI inspection was not performed in this run.
• reply_message and delete_message live permission verification.
• Destructive or permission-sensitive APIs were not declared beyond delete; KOOK mute/kick/leave remain explicit NotSupportedError paths until a safe fixture is available.