Files
dobotai-platform/docs/architecture.md
2026-07-20 13:01:59 +08:00

3.6 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:

  1. exact <channel>:<external_chat_id> binding;
  2. channel wildcard <channel>:*;
  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.