Poco 使用手册
平台说明

IM 多通道设计 (待实现)

Poco IM 多通道接入与产物可视化总体架构方案（v1）

  • 更新时间：2026-03-04
  • 适用范围：backend、frontend、executor_manager、executor（最小改动优先）

1. 背景与目标

当前项目已具备：

  • OpenAI 兼容 API 访问能力
  • Poco Agent 流式输入输出能力
  • WebHook 能力
  • Web 端完整会话与产物能力

本方案目标：

  1. 在不复制推理链路的前提下接入 IM（飞书优先，后续钉钉/企业微信）。
  2. 同时支持“支持流式”和“不支持流式”的客户端。
  3. 让 IM 端可查看任务产物，体验优于“命令拉取”与“直接发文件刷屏”。
  4. 控制复杂度：先上 Redis，不上 MQ；先逻辑网关，后必要时再拆服务。

2. 一句话架构决策（唯一方案）

采用 “单体内嵌 IM Gateway（逻辑层）+ 复用现有流式推理内核 + Redis 可靠性层 + 产物摘要卡片交互” 的方案。

3. 总体架构

3.1 逻辑分层

  • IM Gateway：接收 IM 入站、验签/解密、幂等、快速 ACK、异步分发。
  • Session Router：把 IM 请求转成现有会话输入，统一进入当前推理链路。
  • Stream Fanout：一份流式事件同时供 Web 与 IM 使用。
  • Channel Renderer：按通道能力渲染输出，不改模型层。
  • Delivery：发送、重试、降级与日志。

3.2 输出模式（能力协商）

  • FINAL_ONLY：不支持流式客户端仅发送最终消息。
  • STREAM_WINDOWED：按时间窗聚合输出（例如 300ms），避免逐 token 推送。

3.3 通道策略

  • 飞书：优先应用机器人（可双向会话）。
  • 钉钉/企业微信：复用同一抽象接口，仅新增 adapter。

4. 产物在 IM 端查看（本次新增重点）

不采用“用户输入命令拉取列表”，也不采用“直接批量发文件”。

采用 “主动推送产物摘要卡片 + 卡片内交互浏览 + Web 深度查看”：

  1. 任务完成或里程碑完成时，主动推送一张“产物摘要卡片”。
  2. 默认展示 Top N 产物（名称、类型、大小、更新时间、状态）。
  3. 卡片动作固定：快速预览、下载、查看更多。
  4. 查看更多 通过卡片回调分页更新同一消息，避免刷屏。
  5. 小文本产物支持片段预览（前 100~200 行）；大文件仅给元信息与下载链接。
  6. 深度查看统一跳转 Web 工作台深链（带 session_id / artifact_id）。

体验定位：

  • IM 负责“通知与轻交互”
  • Web 负责“完整浏览、编辑、批量操作”

5. 模块改造清单

5.1 Backend（主要改造）

新增目录建议：backend/app/im/

  • adapters/：base.py、feishu_adapter.py、dingtalk_adapter.py、wecom_adapter.py
  • inbound/：回调接收、验签、解密、challenge 校验
  • routing/：IM 请求转会话输入
  • renderer/：文本/卡片/产物摘要渲染
  • delivery/：发送、重试、降级、日志
  • capability/：通道能力与输出模式选择

新增 API（内部/管理）：

  • POST /api/v1/im/inbound/{platform}
  • POST /api/v1/im/channels
  • GET /api/v1/im/channels/{id}/health
  • POST /api/v1/im/channels/{id}/send-test

5.2 Frontend（最小改造）

  • 新增 IM 通道配置页：连接状态、最近错误、测试发送。
  • 新增“产物卡片跳转”深链处理页（或复用现有会话页参数）。

5.3 Executor / Executor Manager（可选最小触达）

  • 复用现有完成事件，不新增第二套完成回调机制。
  • 若现有事件缺少产物摘要字段，则补充 artifact_manifest 引用字段。

6. 数据模型设计

建议新增表（最小集合）：

  1. im_channel
  2. im_conversation_binding
  3. im_delivery_log
  4. im_artifact_view_state

字段建议：

  • im_channel：id, platform, tenant_id, status, secret_ref, capability_json, created_at, updated_at
  • im_conversation_binding：id, platform, chat_id, session_id, user_id, last_active_at
  • im_delivery_log：id, session_id, platform, chat_id, message_id, delivery_type, status, error_code, retry_count, created_at
  • im_artifact_view_state：id, session_id, platform, chat_id, cursor, updated_at

说明：

  • artifact_manifest 优先复用现有产物接口数据（/openapi/v1/sessions/{session_id}/artifacts），不重复存储文件本体。

7. Redis 设计（先 Redis，不上 MQ）

Key 设计建议：

  • 幂等：im:idem:{platform}:{event_id}（TTL 24h）
  • 限流：im:rate:{platform}:{target}（令牌桶）
  • 短队列：im:outbox:{platform}（list 或 stream）
  • 发送锁：im:sendlock:{platform}:{chat_id}

结论：

  • 现阶段 Redis 足够支撑 ACK 异步化、去重、限流、短时削峰。
  • MQ 触发条件：持续高积压、复杂多消费者编排、跨服务严格顺序。

8. 关键流程

8.1 入站流程

  1. 接收回调 -> 验签/解密 -> 幂等检查 -> 立即 ACK（目标 < 300ms）。
  2. 异步写入处理队列。
  3. 路由到会话输入，进入现有推理链路。

8.2 出站流程

  1. 订阅统一流式事件。
  2. 按 channel_capability 决定 FINAL_ONLY 或 STREAM_WINDOWED。
  3. 发送失败时降级 webhook 最终消息兜底。
  4. 记录 im_delivery_log，便于追踪与重试。

8.3 产物流程

  1. 任务完成事件触发“产物摘要卡片”推送。
  2. 用户点击卡片动作 -> 回调入站 -> 分页更新卡片。
  3. 下载链接使用短时签名；深度查看跳转 Web 工作台。

9. 安全与合规

  1. 平台密钥只在服务端保存，前端不暴露明文。
  2. 回调验签失败直接拒绝，所有失败日志可审计。
  3. 下载链接使用短时签名（建议 10 分钟），并绑定租户与会话。
  4. 多租户隔离：tenant_id + session_id 双重校验。

10. 对现有网页对话影响评估

结论：低风险、可控。

  • 不改变现有 Web 会话协议与主流程。
  • 仅新增流式旁路分发，正常情况下延迟增加为毫秒级。
  • 模型链路故障修复后，Web 与 IM 同时受益（同一推理内核）。

潜在风险与建议：

  • 风险：IM 发送阻塞影响主链路。
  • 建议：IM 发送全异步，主链路与 IM 解耦，超时快速失败并记录日志。

11. 分阶段实施计划（可直接开工）

Phase 1（1~1.5 周）MVP

  • 完成飞书入站、幂等、快速 ACK、FINAL_ONLY 输出。
  • 完成 im_channel / im_conversation_binding / im_delivery_log。
  • 完成通道管理页最小功能。

Phase 2（1 周）流式与产物体验

  • 完成 STREAM_WINDOWED 输出模式。
  • 完成“产物摘要卡片 + 分页回调 + 深链跳转”。
  • 完成 webhook 兜底与失败重试。

Phase 3（1 周）多通道抽象

  • 完成 adapter 抽象稳定化。
  • 接入钉钉/企业微信骨架（至少跑通发送测试）。

Phase 4（0.5 周）灰度与稳定性

  • 补齐监控告警、压测、回归与发布手册。
  • 灰度放量并验证 SLO。

12. 验收标准（上线门槛）

  1. 入站 ACK：P99 < 500ms。
  2. 重复消息率：< 0.1%。
  3. 任务完成后 3 秒内可看到产物摘要卡片（P95）。
  4. 失败自动降级到最终消息，不影响主会话完成。
  5. 用户侧新增配置步骤为 0（平台托管模式）。

13. 开工清单（第一个迭代）

  1. 建表迁移与 Redis key 约定落地。
  2. 飞书入站接口与 challenge/验签实现。
  3. 输出模式选择器与 FINAL_ONLY 发送器。
  4. 产物摘要卡片渲染器（先支持飞书）。
  5. 通道管理页 + 健康检查接口。
  6. 端到端联调：IM 入站 -> 推理 -> IM 出站 -> 产物卡片回调。

14. 备注

  • 本方案已纳入“产物可在 IM 端查看”的补充设计。
  • 若后续流量增长明显，再评估将 IM Gateway 从 backend 逻辑模块拆分为独立服务。

15. 飞书对接文档清单（实施必看）

以下均为飞书开放平台官方文档，建议按“先总览、后接口、再细节”的顺序阅读。

15.1 总览与事件订阅

15.2 回调订阅（Webhook / 长连接）

15.3 消息发送与更新

15.4 机器人类型与能力边界

15.5 鉴权与访问凭证

15.6 飞书卡片（产物卡片交互相关）

15.7 常见问题

浏览器登录态设计

基于 Auth State 的浏览器登录态架构说明

长期记忆架构

Poco 基于 Mem0 v2、PGVector 与内置实体关联的长期记忆实现

On this page

1. 背景与目标2. 一句话架构决策（唯一方案）3. 总体架构3.1 逻辑分层3.2 输出模式（能力协商）3.3 通道策略4. 产物在 IM 端查看（本次新增重点）5. 模块改造清单5.1 Backend（主要改造）5.2 Frontend（最小改造）5.3 Executor / Executor Manager（可选最小触达）6. 数据模型设计7. Redis 设计（先 Redis，不上 MQ）8. 关键流程8.1 入站流程8.2 出站流程8.3 产物流程9. 安全与合规10. 对现有网页对话影响评估11. 分阶段实施计划（可直接开工）Phase 1（1~1.5 周）MVPPhase 2（1 周）流式与产物体验Phase 3（1 周）多通道抽象Phase 4（0.5 周）灰度与稳定性12. 验收标准（上线门槛）13. 开工清单（第一个迭代）14. 备注15. 飞书对接文档清单（实施必看）15.1 总览与事件订阅15.2 回调订阅（Webhook / 长连接）15.3 消息发送与更新15.4 机器人类型与能力边界15.5 鉴权与访问凭证15.6 飞书卡片（产物卡片交互相关）15.7 常见问题