# PicoBot 跨渠道交互式消息规划

规划日期：2026-06-16

## 背景

飞书交互式卡片可以让用户直接在消息卡片上点击按钮、提交选择或触发回调。这个能力很适合用于工具调用审批、快捷回复、任务确认、表单收集等 agent 交互。

参考项目调研结果：

- `reference/zeroclaw` 已实现飞书/Lark 工具审批卡片：发送 Card JSON 2.0 按钮卡片，收到 `card.action.trigger` 后解析 `approval_id` 和 `decision`，唤醒等待中的 approval future，并 PATCH 原卡片为已处理状态。
- `reference/nanobot` 主要使用飞书 CardKit 做 agent 输出展示和流式更新，适合参考消息渲染体验，但没有完整的按钮回调驱动 agent 流程。
- `reference/openlark` 是 SDK/API 封装，支持发送 interactive card 和 CardKit API，不包含完整 agent channel 编排。

PicoBot 当前飞书渠道已经会把普通 markdown 回复发送成 interactive card，但还缺少“用户在卡片上操作 -> 统一交互事件 -> Session/Agent/Tool 流程继续”的抽象。

## 目标

1. 支持飞书交互式卡片按钮回调。
2. 设计成跨渠道能力，后续 Slack、Telegram、Discord、CLI chat 等渠道可以复用同一套交互语义。
3. 支持渠道降级：不支持按钮的渠道也能用纯文本命令完成同样操作。
4. 保持 PicoBot 现有边界：Channel 只做收发和渠道适配，SessionManager 管会话，AgentLoop 执行 LLM 和工具。
5. 为工具调用审批、快捷回复和未来表单交互预留扩展点。

非目标：

- 本阶段不立即实现完整功能。
- 不把飞书卡片细节泄漏到 AgentLoop 或工具层。
- 不要求所有渠道同时支持原生交互组件。

## 核心原则

交互语义和渠道渲染分离。

Agent、工具或 Session 层只表达“我要一个 approval/quick reply/form interaction”。具体是飞书卡片按钮、Slack Block Kit、Telegram inline keyboard，还是 CLI 里显示编号选项，由 Channel 根据能力渲染。

回调也要统一。

飞书的 `card.action.trigger`、Telegram 的 `callback_query`、Slack 的 interaction payload 都应归一化成 PicoBot 内部的 `InteractionEvent`，再交给统一的处理器。

## 数据模型

建议新增一个 `interaction` 模块，定义渠道无关的数据结构。

```rust
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub enum InteractionKind {
    QuickReply,
    Approval,
    FormSubmit,
    Command,
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub enum InteractionStyle {
    Default,
    Primary,
    Danger,
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct InteractionAction {
    pub id: String,
    pub label: String,
    pub value: String,
    pub style: InteractionStyle,
}

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct InteractionPayload {
    pub interaction_id: String,
    pub kind: InteractionKind,
    pub title: Option<String>,
    pub body: String,
    pub actions: Vec<InteractionAction>,
    pub expires_at: Option<i64>,
}

#[derive(Debug, Clone)]
pub struct InteractionEvent {
    pub channel: String,
    pub chat_id: String,
    pub sender_id: String,
    pub interaction_id: String,
    pub action_id: String,
    pub action_value: String,
    pub timestamp: i64,
    pub metadata: std::collections::HashMap<String, String>,
}
```

`InteractionPayload` 用于 outbound 渲染，`InteractionEvent` 用于 inbound 回调。

## OutboundMessage 扩展

短期兼容方案：

- 继续使用 `OutboundMessage.metadata` 携带交互描述。
- 例如：
  - `interaction.kind = "approval"`
  - `interaction.id = "<uuid>"`
  - `interaction.actions = "<json>"`

长期推荐方案：

```rust
pub struct OutboundMessage {
    pub channel: String,
    pub chat_id: String,
    pub content: String,
    pub reply_to: Option<String>,
    pub media: Vec<MediaItem>,
    pub metadata: HashMap<String, String>,
    pub interaction: Option<InteractionPayload>,
}
```

推荐长期方案。它能避免把结构化交互塞进字符串 metadata，也让每个 Channel 的 `send()` 更清晰。

## Channel 能力声明

给 `Channel` 增加可选能力声明：

```rust
#[derive(Debug, Clone, Default)]
pub struct ChannelCapabilities {
    pub interactive_buttons: bool,
    pub forms: bool,
    pub message_update: bool,
    pub markdown_cards: bool,
}

pub trait Channel {
    fn capabilities(&self) -> ChannelCapabilities {
        ChannelCapabilities::default()
    }
}
```

渠道能力示例：

| 渠道 | 原生按钮 | 表单 | 更新原消息 | 降级策略 |
|------|----------|------|------------|----------|
| Feishu | 是，interactive card | 可后续支持 | 是，PATCH message/card | 文本命令 |
| Slack | 是，Block Kit | 是 | 是 | 文本命令 |
| Telegram | 是，inline keyboard | 有限 | 可编辑消息 | 文本命令 |
| Discord | 是，components | 有限 | 可编辑消息 | 文本命令 |
| CLI chat | 否 | 否 | 局部可模拟 | 编号/命令输入 |
| Webhook/Email/SMS | 否 | 否 | 通常否 | 纯文本命令或链接 |

## 渲染策略

每个 channel 实现一个渠道内的渲染函数：

```rust
async fn send_interaction(
    &self,
    chat_id: &str,
    payload: &InteractionPayload,
) -> Result<(), ChannelError>;
```

也可以先不改 trait，在 `send()` 内部判断 `msg.interaction`。

飞书渲染：

- 使用 Card JSON 2.0。
- `schema = "2.0"`。
- body 用 markdown 展示 `payload.body`。
- actions 渲染为 button。
- 每个按钮的 callback value 写入：

```json
{
  "interaction_id": "...",
  "action_id": "...",
  "action_value": "approve"
}
```

需要兼容飞书 Card 2.0 回调路径：

- `/action/value`
- `/action/behaviors/0/value`

CLI 降级渲染：

```text
需要确认：

Tool: bash
Args: cargo test --lib

可选操作：
1. Approve
2. Deny
3. Always approve

回复：
/_interaction <interaction_id> approve
/_interaction <interaction_id> deny
/_interaction <interaction_id> always
```

纯文本渠道都可以复用这个 fallback renderer。

## Inbound 回调归一化

飞书 WebSocket 当前在 `src/channels/feishu.rs` 里处理 `im.message.receive_v1`。需要新增对 `card.action.trigger` 的识别：

1. ACK 仍要尽快发送，飞书要求 3 秒内响应。
2. 如果 event type 是 `card.action.trigger`，不要走普通消息解析。
3. 从 event payload 中解析 `interaction_id`、`action_id`、`action_value`。
4. 构造 `InteractionEvent` 发布给统一处理器。
5. 对未知、过期或重复 interaction 返回成功但记录日志，不应导致渠道重连或报错。

如果短期不新增 interaction bus，可以把回调转成特殊 `InboundMessage`：

```text
content = "/_interaction <interaction_id> <action_value>"
metadata["event.kind"] = "interaction"
metadata["interaction.id"] = "<interaction_id>"
metadata["interaction.action_id"] = "<action_id>"
metadata["interaction.action_value"] = "<action_value>"
```

但必须由 SessionManager 或 InteractionManager 先拦截，不能把 `/_interaction` 当普通用户文本直接送进 LLM。

长期推荐新增 bus 通道：

```rust
pub enum InboundEvent {
    Message(InboundMessage),
    Interaction(InteractionEvent),
}
```

或者在 `MessageBus` 上增加 `interaction_tx`。

## InteractionManager

建议新增 `InteractionManager`，集中管理 pending 交互状态，而不是让每个 Channel 各自维护。

职责：

- 生成 `interaction_id`。
- 保存 pending interaction。
- 处理超时和过期。
- 接收 `InteractionEvent` 并解析成业务结果。
- 对重复点击、未知 interaction、过期 interaction 做幂等处理。
- 必要时通知 channel 更新原消息。

内部状态示例：

```rust
pub struct PendingInteraction {
    pub id: String,
    pub kind: InteractionKind,
    pub channel: String,
    pub chat_id: String,
    pub sender_id: Option<String>,
    pub session_id: Option<String>,
    pub created_at: i64,
    pub expires_at: Option<i64>,
    pub status: InteractionStatus,
    pub responder: InteractionResponder,
    pub message_ref: Option<InteractionMessageRef>,
}

pub struct InteractionMessageRef {
    pub channel: String,
    pub chat_id: String,
    pub message_id: String,
    pub metadata: HashMap<String, String>,
}
```

`InteractionResponder` 可以先支持 oneshot：

```rust
pub enum InteractionResponder {
    Approval(tokio::sync::oneshot::Sender<ApprovalDecision>),
    InboundMessage,
}
```

后续如果需要持久化长期交互，oneshot 不够，需要落库。

## 工具审批流程

工具审批是第一批最适合落地的交互类型。

推荐流程：

1. AgentLoop 准备执行需要审批的工具。
2. 调用 `InteractionManager::request_approval(...)`。
3. InteractionManager 创建 `InteractionPayload`，通过 outbound 发送到原 channel/chat。
4. AgentLoop 等待 oneshot，带 timeout。
5. 用户在飞书卡片上点击 Approve/Deny/Always。
6. FeishuChannel 收到 `card.action.trigger`，发布 `InteractionEvent`。
7. InteractionManager resolve pending approval。
8. AgentLoop 收到结果，继续执行或拒绝工具。
9. 如果 channel 支持更新消息，InteractionManager 或 Channel 把原卡片更新成 resolved 状态。

审批 action 建议：

```rust
approve -> ApprovalDecision::Approve
deny -> ApprovalDecision::Deny
always -> ApprovalDecision::AlwaysApprove
```

`DenyWithEdit` 可后续支持，适合 ACP/Web/CLI 这类能输入文本的渠道。

## 快捷回复流程

快捷回复不是阻塞工具执行，而是把用户点击转成新的用户输入。

示例：

```json
{
  "kind": "QuickReply",
  "body": "你想继续哪个操作？",
  "actions": [
    { "label": "继续分析", "value": "继续分析" },
    { "label": "生成报告", "value": "生成报告" }
  ]
}
```

用户点击后：

- `InteractionEvent.action_value` 转成一条普通 `InboundMessage.content`。
- `sender_id` 和 `chat_id` 保留原用户和会话。
- metadata 标记来源为 interaction，供审计或 UI 使用。

## 消息更新

支持原消息更新的渠道应在交互完成后更新 UI，避免重复点击。

飞书：

- 发送卡片后保存 `data.message_id`。
- resolve 后 PATCH `/im/v1/messages/{message_id}`。
- 卡片 schema 发送和更新都使用 Card JSON 2.0，参考项目指出跨版本 PATCH 可能返回成功但客户端不重渲染。

不支持更新的渠道：

- 发送一条新消息提示“已批准/已拒绝”。
- 或仅在后台幂等拒绝重复点击。

## 安全和权限

交互回调必须校验：

- `interaction_id` 是否存在。
- 是否已过期。
- 是否已处理。
- 点击用户是否允许处理该 interaction。
- 当前 channel/chat 是否匹配。

对于工具审批，默认建议只有触发该 agent turn 的用户或允许列表用户可以审批。群聊里要特别注意 `sender_id`，不能只看 `chat_id`。

日志中避免记录原始飞书回调敏感字段：

- callback token
- operator open_id/union_id/user_id/tenant_key
- open_chat_id/open_message_id

可以记录脱敏后的 payload shape，用于排查飞书回调字段变化。

## 持久化策略

第一阶段可以只做内存 pending map：

- 适合短时工具审批。
- 进程重启后旧按钮点击会变成 unknown/expired。
- 实现简单。

后续如果要支持长期任务或跨重启交互，需要持久化：

- `interactions` 表保存 id、kind、channel、chat_id、sender_id、status、payload、created_at、expires_at。
- `interaction_actions` 可选，或直接 JSON 存在 payload 中。
- resolve 时事务更新 status，防止重复点击竞态。

## 与现有架构的关系

现有数据流：

```text
Channel -> MessageBus -> SessionManager -> AgentLoop -> tools -> SessionManager -> MessageBus -> OutboundDispatcher -> Channel
```

加入 interaction 后建议：

```text
Outbound:
AgentLoop/Tool approval -> InteractionManager -> MessageBus outbound -> OutboundDispatcher -> Channel renderer

Inbound:
Channel callback -> InteractionEvent -> InteractionManager -> pending waiter / synthetic InboundMessage
```

Channel 仍然只做渠道协议适配：

- 飞书负责 Card JSON 和 `card.action.trigger`。
- Slack 负责 Block Kit 和 signing secret。
- Telegram 负责 callback query。
- CLI 负责文本命令 fallback。

InteractionManager 负责语义：

- 这是 approval 还是 quick reply。
- 是否过期。
- 是否有权限。
- 应该唤醒哪个等待者。

SessionManager/AgentLoop 不需要知道飞书卡片格式。

## 分阶段实施计划

### 阶段 1：模型和 fallback

- 新增 `src/interaction/` 模块。
- 定义 `InteractionPayload`、`InteractionAction`、`InteractionEvent`。
- 增加 fallback text renderer。
- 为 `OutboundMessage` 增加 `interaction: Option<InteractionPayload>`，或短期使用 metadata。
- 增加单元测试覆盖序列化和 fallback 文本。

### 阶段 2：Feishu card action

- Feishu outbound 支持把 `InteractionPayload` 渲染为 Card JSON 2.0。
- Feishu inbound 在 WebSocket frame 中识别 `card.action.trigger`。
- 解析 `/action/value` 和 `/action/behaviors/0/value`。
- 发布统一 `InteractionEvent`。
- 保存 `message_id`，支持完成后 PATCH resolved card。
- 增加 fixtures 测试真实/模拟的 `card.action.trigger` payload。

### 阶段 3：InteractionManager 和审批

- 新增内存版 `InteractionManager`。
- 支持 request/resolve/timeout。
- 接入工具执行前审批点。
- 支持 Approve/Deny/AlwaysApprove。
- 未知、过期、重复点击保持幂等。
- 增加 agent/tool 审批单元测试。

### 阶段 4：其他渠道兼容

- CLI chat 支持 `/_interaction <id> <value>` fallback。
- 其他不支持原生按钮的渠道使用纯文本 fallback。
- 后续按需实现 Slack/Telegram/Discord 原生按钮。

### 阶段 5：持久化和高级交互

- 需要时落库 pending interaction。
- 支持 quick reply 生成 synthetic inbound message。
- 支持表单提交。
- 支持 `DenyWithEdit`。
- 支持长期任务交互和重启恢复。

## 测试计划

单元测试：

- `InteractionPayload` 序列化。
- fallback text renderer 输出。
- Feishu Card JSON 包含正确 callback value。
- Feishu 回调同时支持 `/action/value` 和 `/action/behaviors/0/value`。
- unknown/expired interaction 不报错。
- 重复点击只 resolve 一次。

集成测试：

- 模拟 Feishu `card.action.trigger`，验证 pending approval 被唤醒。
- 模拟超时，验证默认 deny。
- CLI fallback 输入 `/_interaction`，验证能 resolve。
- 不支持按钮的 channel 能收到可读 fallback 文本。

手工验证：

- 飞书群聊点击 Approve/Deny/Always。
- 私聊点击。
- 点击后原卡片更新为 resolved。
- 重复点击不会重复执行工具。
- 非触发用户点击时按权限策略处理。

## 开放问题

1. 工具审批应该由 AgentLoop 直接调用 InteractionManager，还是通过 SessionManager 代理？
2. 群聊中是否只允许原始触发者审批，还是允许配置中的所有 allowed user 审批？
3. `AlwaysApprove` 的作用域是本次会话、本 dialog、本 chat，还是全局工具策略？
4. 是否需要第一阶段就修改 `OutboundMessage` 结构，还是先用 metadata 降低改动面？
5. 飞书 CardKit 流式输出是否要与交互卡片统一，还是继续保持普通回复卡片和交互卡片两套路径？