3.8 KiB
DobotAI External Architecture
Boundary
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:
- exact
<channel>:<external_chat_id>binding; - channel wildcard
<channel>:*; - 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:
- do not resend the question without the image;
- do not return partial model output as success;
- return a typed
vision_unavailablefailure to the channel adapter; - DingTalk tells the user that image recognition is temporarily unavailable and asks them to retry or send text;
- emit an operational alert to verify Agent image upload settings, selected vision model, provider connectivity, and model capability;
- 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/coverage: v1 covered/uncovered evaluation, durable support-case dispatch, finite retries, and stable failure codes. Notification failures never change a successful QA result.internal/channels/dingtalk: DingTalk Stream ingress (official SDK), text-only robot callbacks, fail-closed session webhook replies (https,*.dingtalk.com, no redirects). Wired incmd/dobotai; enabled only whenDINGTALK_CLIENT_ID,DINGTALK_CLIENT_SECRET, andDOBOTAI_TENANT_KEYare 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:
- update the pinned official release/tag;
- run official database migrations against WeKnora only;
- run DobotAI Adapter contract tests;
- verify text Agent Chat, references, terminal errors, Stop, images, ingestion, and FAQ;
- promote the official image only after the contract suite passes.