# DobotAI 外部集成架构 ## 系统边界 ```text 钉钉 / 企业微信 / 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. 精确 `:` 绑定; 2. 渠道通配 `:*`; 3. 没有任何绑定时失败关闭。 ## 首位管理员终端绑定 首位管理员绑定由部署服务器终端发起,而非网页发码。钉钉 Stream 机器人已正常运行且当前不存在有效管理员时,操作人员执行: ```bash dobotai bootstrap-admin ``` 命令只连接 DobotAI PostgreSQL,使用加密随机数创建一个有效期10分钟、最多5次错误尝试的六码挑战,并在终端持续等待。候选用户必须私聊机器人发送: ```text /setting <六码绑定码> ``` 验证码匹配后,渠道侧只记录候选身份;终端轮询并事务性将该候选用户写为 `super_admin/active`,然后显示成功并退出。已有有效管理员时该命令拒绝执行,避免任意用户通过终端绑定流程被提权。DobotAI 不提供网页管理面,钉钉凭据和运行配置由部署环境文件管理。 ## 图片失败策略 启用图片流量前,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 迁移、钉钉单消费者切换和生产部署是独立变更边界,必须各自备份、演练和验收。