# DobotAI External Architecture ## Boundary ```text DingTalk / WeCom / Web / Software -> DobotAI ingress and workflows -> WeKnora Adapter -> official WeKnora REST API -> official WeKnora RAG and Agent ``` DobotAI PostgreSQL owns channel identities, external messages, session mappings, turns, feedback, coverage decisions, support cases, human replies, FAQ workflow state, and content-source mappings. WeKnora owns only its official data model. ## Session policy Default policy: - direct: one long-lived session per tenant + channel + Agent + external user; - group: one shared session per tenant + channel + Agent + external group; - group messages are admitted only when the bot is mentioned or an explicit command triggers it; - sender display name is prefixed to the query so a shared Agent can distinguish speakers; - future controls must include idle rotation and an explicit new-conversation command; - confidential channels may switch to `per_user`, yielding group + user sessions. Shared group sessions are the common collaboration-bot pattern because all members see the same conversation. Group+user sessions provide stronger context isolation but make replies less coherent for collaborative group discussions. ## Agent binding Agents are configuration-owned. Channel callers cannot choose an arbitrary `agent_id`. Resolution order: 1. exact `:` binding; 2. channel wildcard `:*`; 3. fail closed when no binding exists. ## Image failure policy Before enabling image traffic, the WeKnora Adapter must run a contract test against the selected official release and configured vision model. If any image path fails: 1. do not resend the question without the image; 2. do not return partial model output as success; 3. return a typed `vision_unavailable` failure to the channel adapter; 4. DingTalk tells the user that image recognition is temporarily unavailable and asks them to retry or send text; 5. emit an operational alert to verify Agent image upload settings, selected vision model, provider connectivity, and model capability; 6. keep image traffic disabled until the contract test passes. No WeKnora source patch is allowed as a workaround. ## Service ownership - `internal/weknora`: official REST/SSE compatibility only. - `internal/qa`: business orchestration and terminal-state ownership. - `internal/session`: external-to-WeKnora session policy. - `internal/store/postgres`: DobotAI business persistence only. - `internal/channels/dingtalk`: DingTalk Stream ingress (official SDK), text-only robot callbacks, fail-closed session webhook replies (`https`, `*.dingtalk.com`, no redirects). Wired in `cmd/dobotai`; enabled only when `DINGTALK_CLIENT_ID`, `DINGTALK_CLIENT_SECRET`, and `DOBOTAI_TENANT_KEY` are all set. Group messages require an @-mention; direct chats map to one long-lived session per user, groups to one shared session per group. Images, OpenAPI fallback, and card replies are not implemented yet. - future `channels/*`: platform callbacks and outbound replies. - future `content-sync/*`: DingTalk KB, NAS, and CMS synchronization. - model gateway: token accounting, routing, quotas, circuit breaking, and provider observability. - Redis: queue, retry, short leases, and temporary stream state only. ## Upgrade contract For every official WeKnora upgrade: 1. update the pinned official release/tag; 2. run official database migrations against WeKnora only; 3. run DobotAI Adapter contract tests; 4. verify text Agent Chat, references, terminal errors, Stop, images, ingestion, and FAQ; 5. promote the official image only after the contract suite passes.