docs: translate documentation and environment comments to Chinese
This commit is contained in:
姚章浩
+20
-30
@@ -1,62 +1,52 @@
|
||||
# DobotAI configuration
|
||||
# DobotAI 基础配置
|
||||
DOBOTAI_LISTEN_ADDR=127.0.0.1:8090
|
||||
DOBOTAI_INGRESS_TOKEN=replace-me
|
||||
# Optional local-only audit API. Use a distinct secret from DOBOTAI_INGRESS_TOKEN.
|
||||
# When set, DOBOTAI_TENANT_KEY must be set and the listen address must be loopback-only.
|
||||
# 可选的仅本机审计 API。必须使用不同于 DOBOTAI_INGRESS_TOKEN 的独立密钥。
|
||||
# 设置后必须同时设置 DOBOTAI_TENANT_KEY，且监听地址必须仅为回环地址。
|
||||
DOBOTAI_ADMIN_TOKEN=
|
||||
DOBOTAI_GROUP_SESSION_POLICY=shared
|
||||
DOBOTAI_AGENT_BINDINGS={"dingtalk:*":"replace-with-agent-id"}
|
||||
# Required for /think routing. The base binding above remains the stable
|
||||
# Session identity; these select the execution Agent for each Turn.
|
||||
# `/think` 路由必填。上面的基础绑定保持稳定的会话身份；以下配置仅选择每个 Turn 的执行 Agent。
|
||||
DOBOTAI_QUICK_AGENT_ID=builtin-quick-answer
|
||||
DOBOTAI_REASONING_AGENT_ID=builtin-smart-reasoning
|
||||
|
||||
# Official WeKnora API only
|
||||
# 仅使用 WeKnora 官方 API
|
||||
WEKNORA_BASE_URL=http://127.0.0.1:8080
|
||||
WEKNORA_API_KEY=replace-me
|
||||
|
||||
# DingTalk Stream mode (official SDK). Leave all three empty to disable the
|
||||
# DingTalk channel; set all three to enable it. Never commit real values.
|
||||
# 钉钉 Stream 模式（官方 SDK）。三项均留空时禁用钉钉渠道；三项同时设置时启用。不得提交真实值。
|
||||
DINGTALK_CLIENT_ID=
|
||||
DINGTALK_CLIENT_SECRET=
|
||||
# Tenant key this DingTalk ingress serves (matches tenant_key used by QA).
|
||||
# 该钉钉接入服务的租户键（必须与 QA 使用的 tenant_key 一致）。
|
||||
DOBOTAI_TENANT_KEY=
|
||||
|
||||
# Optional DingTalk AI card template ID. Leave empty to use markdown-only replies.
|
||||
# When set, a successful QA answer will be delivered as an AI card; markdown
|
||||
# is only sent as a fallback when card delivery fails. Never commit real values.
|
||||
# 可选的钉钉 AI 卡片模板 ID。留空时仅使用 Markdown 回复。
|
||||
# 设置后，成功的 QA 回答优先通过 AI 卡片发送；仅当卡片发送失败时才回退 Markdown。不得提交真实值。
|
||||
DINGTALK_CARD_TEMPLATE_ID=
|
||||
# Optional, temporary DingTalk card-debug allowlist. When set, only this exact
|
||||
# DingTalk user receives _CARD_DEBUG_TOOL_ENTRY=show in per-user privateData.
|
||||
# Keep empty outside a controlled debug session; never commit a real user ID.
|
||||
# 可选、临时的钉钉卡片调试白名单。设置后，只有该指定钉钉用户会在 per-user privateData 中收到 _CARD_DEBUG_TOOL_ENTRY=show。
|
||||
# 非受控调试期间必须留空；不得提交真实用户 ID。
|
||||
DINGTALK_CARD_DEBUG_USER_ID=
|
||||
|
||||
# Optional DingTalk FAQ table workflow for uncovered questions. Set all four
|
||||
# values together; leave all four empty to disable. Required when the support
|
||||
# group notification below is enabled. Never commit real IDs.
|
||||
# 可选的钉钉 FAQ 表工作流，用于未覆盖问题。四项必须同时设置；四项均留空时禁用。
|
||||
# 启用下方人工支持群通知时，此工作流为必需项。不得提交真实 ID。
|
||||
DINGTALK_FAQ_TABLE_BASE_ID=
|
||||
DINGTALK_FAQ_TABLE_SHEET_ID=
|
||||
DINGTALK_FAQ_TABLE_VIEW_ID=
|
||||
DINGTALK_FAQ_TABLE_OPERATOR_ID=
|
||||
|
||||
# Optional PDF-answer image egress for DingTalk cards. When any value is set,
|
||||
# all five values are required. DobotAI downloads only authenticated resource://
|
||||
# images from WEKNORA_BASE_URL /files, writes content-hashed copies under
|
||||
# dobotai/im-images/, and emits private OSS GET URLs valid for 2 hours.
|
||||
# Keep the bucket private and configure an OSS lifecycle rule to delete
|
||||
# dobotai/im-images/ objects after 1 day. Never commit real credentials.
|
||||
# 可选的钉钉卡片回答图片外发。任一项设置后，以下五项都必须设置。
|
||||
# DobotAI 仅从 WEKNORA_BASE_URL 的 /files 鉴权下载 resource:// 图片，在 dobotai/im-images/ 下写入内容哈希副本，并生成有效期2小时的私有 OSS GET URL。
|
||||
# Bucket 必须保持私有，并配置 OSS 生命周期规则，在1天后删除 dobotai/im-images/ 对象。不得提交真实凭据。
|
||||
DOBOTAI_OUTBOUND_IMAGE_OSS_ENDPOINT=
|
||||
DOBOTAI_OUTBOUND_IMAGE_OSS_REGION=
|
||||
DOBOTAI_OUTBOUND_IMAGE_OSS_ACCESS_KEY_ID=
|
||||
DOBOTAI_OUTBOUND_IMAGE_OSS_ACCESS_KEY_SECRET=
|
||||
DOBOTAI_OUTBOUND_IMAGE_OSS_BUCKET=
|
||||
|
||||
# Optional support group for uncovered-answer notifications. This is the
|
||||
# group's openConversationId, not a webhook. Leave empty to record coverage
|
||||
# decisions and pending support cases without sending group notifications.
|
||||
# When enabled, the FAQ table workflow above must also be configured so the
|
||||
# ActionCard can link to the exact FAQ record. Never commit a real group ID.
|
||||
# 可选的未覆盖回答人工支持群通知。该值是群的 openConversationId，不是 webhook。
|
||||
# 留空时仍记录覆盖判定和待处理 Support Case，但不发送群通知。
|
||||
# 启用后必须同时配置上方 FAQ 表工作流，使 ActionCard 能链接到准确的 FAQ 记录。不得提交真实群 ID。
|
||||
DINGTALK_SUPPORT_GROUP_OPEN_CONVERSATION_ID=
|
||||
|
||||
# Independent DobotAI PostgreSQL; never point this at WeKnora's database
|
||||
# 独立的 DobotAI PostgreSQL；不得指向 WeKnora 数据库
|
||||
DATABASE_URL=postgres://dobotai:replace-me@127.0.0.1:5432/dobotai?sslmode=disable
|
||||
|
||||
+16
-16
@@ -1,21 +1,21 @@
|
||||
# WeKnora API Capability Gaps
|
||||
# WeKnora API 能力缺口
|
||||
|
||||
These gaps must not be solved with private WeKnora source or database changes.
|
||||
以下能力缺口不得通过修改 WeKnora 私有源码或数据库解决。
|
||||
|
||||
| Capability | Current external handling |
|
||||
| 能力 | 当前外部处理方式 |
|
||||
|---|---|
|
||||
| Like/dislike and unresolved reason | DobotAI PostgreSQL and API |
|
||||
| Formal covered/not-covered decision | DobotAI evaluation rules using references, scores, answer status, and offline calibration |
|
||||
| Support case, owner, SLA, and status | DobotAI workflow |
|
||||
| Human reply to original channel | DobotAI channel adapter; not written to WeKnora history by default |
|
||||
| Stable external turn correlation | DobotAI mapping of external message, turn, WeKnora session/request, and gateway trace |
|
||||
| Complete multi-call token usage | Model gateway/Langfuse; unknown remains null/unknown |
|
||||
| Strict image failure semantics | Adapter contract test; reject image traffic on failure |
|
||||
| Arbitrary human assistant-message append | Keep in DobotAI and submit an upstream API request only if context injection becomes necessary |
|
||||
| 点赞、点踩和未解决原因 | DobotAI PostgreSQL 与 API |
|
||||
| 正式的已覆盖/未覆盖判定 | DobotAI 基于引用、分数、回答状态和离线校准的评估规则 |
|
||||
| Support Case、负责人、SLA 和状态 | DobotAI 工作流 |
|
||||
| 向原始渠道发送人工回复 | DobotAI 渠道适配器；默认不写回 WeKnora 历史 |
|
||||
| 稳定的外部 Turn 关联 | DobotAI 映射外部消息、Turn、WeKnora 会话/请求和网关追踪 |
|
||||
| 完整的多调用 Token 用量 | 模型网关/Langfuse；未知值保持 `null/unknown` |
|
||||
| 严格的图片失败语义 | Adapter 契约测试；图片流量失败时拒绝处理 |
|
||||
| 任意人工助手消息追加 | 保留在 DobotAI；仅当确有上下文注入需求时向上游提交 API 请求 |
|
||||
|
||||
Allowed responses to a gap:
|
||||
面对能力缺口时，只允许：
|
||||
|
||||
1. adjust the product design;
|
||||
2. implement it outside WeKnora;
|
||||
3. open an upstream issue;
|
||||
4. submit a general upstream pull request.
|
||||
1. 调整产品设计；
|
||||
2. 在 WeKnora 外部实现；
|
||||
3. 提交上游 Issue；
|
||||
4. 提交通用的上游 Pull Request。
|
||||
+58
-50
@@ -1,74 +1,82 @@
|
||||
# DobotAI External Architecture
|
||||
# DobotAI 外部集成架构
|
||||
|
||||
## Boundary
|
||||
## 系统边界
|
||||
|
||||
```text
|
||||
DingTalk / WeCom / Web / Software
|
||||
-> DobotAI ingress and workflows
|
||||
钉钉 / 企业微信 / Web / 业务软件
|
||||
-> DobotAI 接入层与工作流
|
||||
-> WeKnora Adapter
|
||||
-> official WeKnora REST API
|
||||
-> official WeKnora RAG and Agent
|
||||
-> WeKnora 官方 REST API
|
||||
-> WeKnora 官方 RAG 与 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.
|
||||
DobotAI PostgreSQL 负责渠道身份、外部消息、会话映射、Turn、反馈、覆盖判定、Support Case、人工回复、FAQ 工作流状态和内容源映射。WeKnora 仅负责其官方数据模型。
|
||||
|
||||
## 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.
|
||||
- 私聊：每个 `tenant + channel + Agent + 外部用户` 使用一个长期会话；
|
||||
- 群聊：每个 `tenant + channel + Agent + 外部群` 使用一个共享会话；
|
||||
- 群消息仅在机器人被提及或命中显式命令时进入处理；
|
||||
- 将发送人显示名添加到问题前缀，使共享 Agent 能区分发言者；
|
||||
- 后续控制项必须包含空闲轮换和显式新建会话命令；
|
||||
- 保密渠道可切换为 `per_user`，形成群组加用户维度的会话。
|
||||
|
||||
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
|
||||
快速问答与智能推理必须复用同一个 WeKnora Session；`/think` 仅改变当前 Turn 的执行 Agent，不得重建会话映射。
|
||||
|
||||
Agents are configuration-owned. Channel callers cannot choose an arbitrary `agent_id`.
|
||||
## Agent 绑定
|
||||
|
||||
Resolution order:
|
||||
Agent 由配置控制，渠道调用方不得任意指定 `agent_id`。
|
||||
|
||||
1. exact `<channel>:<external_chat_id>` binding;
|
||||
2. channel wildcard `<channel>:*`;
|
||||
3. fail closed when no binding exists.
|
||||
解析顺序：
|
||||
|
||||
## Image failure policy
|
||||
1. 精确 `<channel>:<external_chat_id>` 绑定；
|
||||
2. 渠道通配 `<channel>:*`；
|
||||
3. 没有任何绑定时失败关闭。
|
||||
|
||||
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:
|
||||
启用图片流量前，WeKnora Adapter 必须针对选定的官方版本和视觉模型执行契约测试。
|
||||
|
||||
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.
|
||||
1. 不得去掉图片后重发同一问题；
|
||||
2. 不得将部分模型输出当作成功结果；
|
||||
3. 向渠道适配器返回类型化 `vision_unavailable` 错误；
|
||||
4. 钉钉提示用户图片识别暂不可用，并请其重试或发送文本；
|
||||
5. 发送运维告警，核查 Agent 图片上传设置、视觉模型、供应商连通性和模型能力；
|
||||
6. 契约测试通过前保持图片流量禁用。
|
||||
|
||||
## Service ownership
|
||||
不得通过修改 WeKnora 源码规避上述失败。
|
||||
|
||||
- `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.
|
||||
对钉钉 richText 中的图片，DobotAI 仅通过官方接口下载，验证来源、大小、媒体类型和文件签名后，才转换为 WeKnora 通用多模态请求。对回答中的 `resource://` 图片，仅可在鉴权获取、内容哈希转存私有 OSS 后外发；不得把任意外部 URL 当作可信图片。
|
||||
|
||||
## Upgrade contract
|
||||
## 服务职责
|
||||
|
||||
For every official WeKnora upgrade:
|
||||
- `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：仅用于队列、重试、短期租约和临时流状态。
|
||||
|
||||
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.
|
||||
## 升级契约
|
||||
|
||||
每次升级官方 WeKnora 时：
|
||||
|
||||
1. 更新固定的官方 Release/Tag；
|
||||
2. 仅对 WeKnora 执行官方数据库迁移；
|
||||
3. 执行 DobotAI Adapter 契约测试；
|
||||
4. 验证文本 Agent Chat、引用、终止错误、停止、图片、导入和 FAQ；
|
||||
5. 仅在契约测试通过后推广官方镜像。
|
||||
|
||||
WeKnora 升级、DobotAI 迁移、钉钉单消费者切换和生产部署是独立变更边界，必须各自备份、演练和验收。
|
||||
Reference in New Issue
Block a user