75 lines
3.8 KiB
Markdown
75 lines
3.8 KiB
Markdown
# 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 `<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/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 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.
|