dobotai-platform/docs/architecture.md

DobotAI 外部集成架构

系统边界

钉钉 / 企业微信 / Web / 业务软件
  -> DobotAI 接入层与工作流
  -> WeKnora Adapter
  -> WeKnora 官方 REST API
  -> WeKnora 官方 RAG 与 Agent

DobotAI PostgreSQL 负责渠道身份、外部消息、会话映射、Turn、反馈、覆盖判定、Support Case、人工回复、FAQ 工作流状态和内容源映射。WeKnora 仅负责其官方数据模型。

会话策略

默认策略：

• 私聊：每个 tenant + channel + Agent + 外部用户 使用一个长期会话；
• 群聊：每个 tenant + channel + Agent + 外部群 使用一个共享会话；
• 群消息仅在机器人被提及或命中显式命令时进入处理；
• 将发送人显示名添加到问题前缀，使共享 Agent 能区分发言者；
• 后续控制项必须包含空闲轮换和显式新建会话命令；
• 保密渠道可切换为 per_user，形成群组加用户维度的会话。

共享群会话符合协作机器人场景：所有成员能看到相同上下文。群组加用户会话能增强上下文隔离，但会削弱协作讨论中的回复连贯性。

快速问答与智能推理必须复用同一个 WeKnora Session；/think 仅改变当前 Turn 的执行 Agent，不得重建会话映射。

Agent 绑定

Agent 由配置控制，渠道调用方不得任意指定 agent_id。

解析顺序：

1. 精确 <channel>:<external_chat_id> 绑定；
2. 渠道通配 <channel>:*；
3. 没有任何绑定时失败关闭。

图片失败策略

启用图片流量前，WeKnora Adapter 必须针对选定的官方版本和视觉模型执行契约测试。

任一图片路径失败时：

1. 不得去掉图片后重发同一问题；
2. 不得将部分模型输出当作成功结果；
3. 向渠道适配器返回类型化 vision_unavailable 错误；
4. 钉钉提示用户图片识别暂不可用，并请其重试或发送文本；
5. 发送运维告警，核查 Agent 图片上传设置、视觉模型、供应商连通性和模型能力；
6. 契约测试通过前保持图片流量禁用。

不得通过修改 WeKnora 源码规避上述失败。

对钉钉 richText 中的图片，DobotAI 仅通过官方接口下载，验证来源、大小、媒体类型和文件签名后，才转换为 WeKnora 通用多模态请求。对回答中的 resource:// 图片，仅可在鉴权获取、内容哈希转存私有 OSS 后外发；不得把任意外部 URL 当作可信图片。

服务职责

• internal/weknora：仅处理 WeKnora 官方 REST/SSE 兼容；解析普通引用和智能推理工具结果引用；
• internal/qa：业务编排与 Turn 终态归属；
• internal/session：外部渠道到 WeKnora 的会话策略；
• internal/store/postgres：仅保存 DobotAI 业务数据；
• internal/coverage：已覆盖/未覆盖/纯视觉识别判定、持久化 Support Case、有限重试和稳定错误码；通知失败不得改变成功问答的结果；
• internal/channels/dingtalk：钉钉 Stream 接入、richText 与多图片归一化、AI 流式卡片、命令路由、反馈与通知。仅在 DINGTALK_CLIENT_ID、DINGTALK_CLIENT_SECRET 和 DOBOTAI_TENANT_KEY 均已设置时启用。群聊必须 @ 机器人；私聊按用户映射长期会话，群聊默认映射共享会话；sessionWebhook 必须是 https、*.dingtalk.com、443端口且不允许重定向；
• internal/reasoningmode：/think 单次与持续推理、轮数、空闲到期、提示和首次使用引导；
• internal/outboundimage：WeKnora resource:// 图片的受控鉴权下载和私有 OSS 外发；
• future channels/*：其他平台的回调与外发回复；
• future content-sync/*：钉钉知识库、NAS 与 CMS 同步；
• 模型网关：Token 统计、路由、配额、熔断和供应商可观测性；
• Redis：仅用于队列、重试、短期租约和临时流状态。

升级契约

每次升级官方 WeKnora 时：

1. 更新固定的官方 Release/Tag；
2. 仅对 WeKnora 执行官方数据库迁移；
3. 执行 DobotAI Adapter 契约测试；
4. 验证文本 Agent Chat、引用、终止错误、停止、图片、导入和 FAQ；
5. 仅在契约测试通过后推广官方镜像。

WeKnora 升级、DobotAI 迁移、钉钉单消费者切换和生产部署是独立变更边界，必须各自备份、演练和验收。