DobotAI 外部集成架构

系统边界

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

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

默认策略：

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

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

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

解析顺序：

首位管理员绑定由部署服务器终端发起，而非网页发码。钉钉 Stream 机器人已正常运行且当前不存在有效管理员时，操作人员执行：

dobotai bootstrap-admin

命令只连接 DobotAI PostgreSQL，使用加密随机数创建一个有效期10分钟、最多5次错误尝试的六码挑战，并在终端持续等待。候选用户必须私聊机器人发送：

/setting <六码绑定码>

验证码匹配后，渠道侧只记录候选身份；终端轮询并事务性将该候选用户写为 super_admin/active，然后显示成功并退出。已有有效管理员时该命令拒绝执行，避免任意用户通过终端绑定流程被提权。DobotAI 不提供网页管理面，钉钉凭据和运行配置由部署环境文件管理。

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

任一图片路径失败时：

不得通过修改 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 时：