openclaw/extensions/feishu/spec/tasks.md

Tasks: Add Feishu (飞书) channel extension

1. Extension scaffold

• Create extensions/feishu/ workspace package (package.json, clawdbot.plugin.json, index.ts, src/).
• Add plugin catalog metadata in extensions/feishu/package.json (clawdbot.channel + clawdbot.install) so onboarding can install it.

2. Config + normalization

• Define Feishu config Zod schema (extension-local) and expose it as configSchema via buildChannelConfigSchema.
• Add mode: http | ws to select HTTP callback vs long connection.
• Implement target normalization (user:<open_id>, chat:<chat_id>) and allowlist formatting.
• Implement account model (start with default account; keep accounts extensible).

3. Token manager + API client

• Implement tenant access token fetch + cache (/auth/v3/tenant_access_token/internal).
• Implement Feishu “bot info” fetch (/bot/v3/info) for mention gating.
• Implement send message (/im/v1/messages) and reply message (/im/v1/messages/:message_id/reply).

4. Webhook handler

• Implement handleFeishuWebhookRequest(req,res) and register via api.registerHttpHandler.
• Support url_verification challenge response (plain + encrypted).
• Implement secure validation:
  • Raw-body capture with size limit.
  • Signature verification when encryptKey is configured.
  • Verification token checks when encryptKey is not configured.
• Implement decrypt for payloads with encrypt.

5. Event processing + routing

• Handle im.message.receive_v1 (text-only V1):
  • DM policy + pairing store integration (mirror GoogleChat monitor behavior).
  • Group policy allowlists + mention gating integration.
  • Control command gating for group chats.
• Build inbound context via runtime.channel.reply.finalizeInboundContext and dispatch replies via buffered dispatcher.

6. Outbound adapters

• Implement outbound.sendText for clawdbot message send and heartbeats.

7. Status + probe

• Implement status adapter snapshot + summary.
• Implement probeAccount to validate credentials (token + bot info).

8. Onboarding

• Add onboarding adapter with prompts for app id/secret and delivery mode.

9. Long connection (WebSocket)

• Implement long connection transport (mode="ws") for event subscriptions.
• Acknowledge events quickly and process messages asynchronously.

10. Tests

• Add unit tests for: signature, decrypt, target normalization.
• Add unit tests for: url_verification, event parsing.
• Add unit tests for: long connection frame codec + monitor lifecycle.