fix(deploy): make clone installer build dependencies reliably

Reviewed-on: #12

.dockerignore

@@ -0,0 +1,9 @@
+.git
+.env
+.env.*
+!.env.example
+bin/
+.acceptance-canary/
+.hermes/
+__pycache__/
+*.pyc

.env.example

@@ -1,31 +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"}
+# `/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=
 
-# Independent DobotAI PostgreSQL; never point this at WeKnora's database
+# 可选的钉钉 FAQ 表工作流，用于未覆盖问题。四项必须同时设置；四项均留空时禁用。
+# 启用下方人工支持群通知时，此工作流为必需项。不得提交真实 ID。
+DINGTALK_FAQ_TABLE_BASE_ID=
+DINGTALK_FAQ_TABLE_SHEET_ID=
+DINGTALK_FAQ_TABLE_VIEW_ID=
+DINGTALK_FAQ_TABLE_OPERATOR_ID=
+
+# 可选的钉钉卡片回答图片外发。任一项设置后，以下五项都必须设置。
+# 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=
+
+# 可选的未覆盖回答人工支持群通知。该值是群的 openConversationId，不是 webhook。
+# 留空时仍记录覆盖判定和待处理 Support Case，但不发送群通知。
+# 启用后必须同时配置上方 FAQ 表工作流，使 ActionCard 能链接到准确的 FAQ 记录。不得提交真实群 ID。
+DINGTALK_SUPPORT_GROUP_OPEN_CONVERSATION_ID=
+
+# 独立的 DobotAI PostgreSQL；不得指向 WeKnora 数据库
 DATABASE_URL=postgres://dobotai:replace-me@127.0.0.1:5432/dobotai?sslmode=disable

.gitignore

@@ -5,6 +5,17 @@
 *.local
 coverage.out
 
+# Local deployment, backup, and production diagnostic artifacts
+/.deploy/
+/backups/
+/check-live-dobotai.py
+
+# Transient local validation and legacy test-deployment artifacts
+/dobotai
+/.acceptance-canary/
+/.hermes/
+/deploy_stable_images_test.py
+
 # Editors and OS
 .idea/
 .vscode/

Dockerfile

@@ -0,0 +1,22 @@
+FROM golang:1.26.5-bookworm AS build
+
+WORKDIR /src
+COPY go.mod go.sum ./
+ARG GOPROXY=https://goproxy.cn,direct
+RUN GOPROXY=$GOPROXY go mod download
+COPY . ./
+
+ARG VERSION=dev
+ARG COMMIT_SHA=unknown
+ARG BUILD_TIME=unknown
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath \
+    -ldflags "-s -w -X main.version=${VERSION} -X main.commitSHA=${COMMIT_SHA} -X main.buildTime=${BUILD_TIME}" \
+    -o /out/dobotai ./cmd/dobotai
+
+FROM debian:bookworm-slim
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+COPY --from=build /out/dobotai /usr/local/bin/dobotai
+USER 10001:10001
+ENTRYPOINT ["/usr/local/bin/dobotai"]

README.md

@@ -1,76 +1,240 @@
-# DobotAI Platform
+# DobotAI 平台
 
-DobotAI is the external enterprise integration layer for official WeKnora. It does not import WeKnora packages, modify WeKnora source, or access the WeKnora database.
+DobotAI 是 WeKnora 的企业外部渠道集成层，负责钉钉协议、身份与会话映射、消息编排、流式卡片、媒体收发、覆盖判定和人工支持通知。它只通过 WeKnora 官方 REST/SSE API 调用知识问答与 Agent Chat：不导入 WeKnora 私有包、不修改 WeKnora 源码，也不访问 WeKnora 数据库。
 
-Current milestone: channel-bound Agent QA core.
+## 当前能力
 
-Implemented:
+- 通过官方 `POST /api/v1/sessions` 与 `POST /api/v1/agent-chat/:session_id` 调用 WeKnora；
+- 严格解析 SSE 的 `answer`、`references`、`tool_call`、`tool_result`、`error` 与终止事件；`error + done=false` 被视为可恢复的工具错误，不会提前结束钉钉卡片；
+- 解析普通引用及智能推理工具结果中的检索证据，供覆盖判定与后端审计使用；
+- 按渠道、会话和用户维护长期 WeKnora Session，并保证回调幂等；
+- 钉钉 Stream 机器人支持文本、richText 以及多图片输入；图片下载经过钉钉官方接口、大小与文件签名校验后，才以 WeKnora 通用多模态请求发送；
+- 钉钉 AI 流式卡片与最终消息回退；通道侧保留原始回答，不修改 WeKnora 持久化消息；
+- 默认快速问答，支持 `/think <问题>` 单次推理、`/think on` 持续推理、`/think off` 或 `/rag` 关闭推理；快速问答与智能推理共用同一 WeKnora Session；
+- 用户级推理轮次、空闲到期、提示开关和首次使用指引；
+- 成功回答的覆盖判定、持久化 Support Case、FAQ Outbox 与钉钉人工支持群通知；
+- 对已覆盖答案点踩时创建 `feedback_down` 人工处理提醒；对已先因未覆盖创建 Case 的同一问题保持“一题一个 Case”幂等；
+- 可选的钉钉问题表异步写入；写入失败不会改变问答成功状态；
+- 可选的回答图片外发：仅将 WeKnora `resource://` 图片通过鉴权下载、内容哈希转存到私有 OSS 后，以受控 HTTPS 地址提供给钉钉。
 
-- official `POST /api/v1/sessions` adapter;
-- official `POST /api/v1/agent-chat/:session_id` adapter;
-- fail-closed SSE parsing for `references`, `answer`, `error`, and terminal `done`;
-- per-channel/per-conversation Agent binding;
-- long-lived direct-user sessions;
-- shared-group sessions, with optional group+user policy;
-- external-message idempotency;
-- independent PostgreSQL session/turn storage;
-- authenticated internal `POST /v1/qa` ingress endpoint.
-- DingTalk Stream text ingress (official SDK) wired into `cmd/dobotai`.
+## 架构边界
 
-## DingTalk channel (Stream, text only)
+```text
+钉钉 / 内部调用方
+        ↓
+     DobotAI
+        ├─ 钉钉 Stream、richText、图片、AI 卡片、反馈与通知
+        ├─ 独立 PostgreSQL：渠道身份、消息、会话映射、Turn、覆盖与支持流程
+        └─ WeKnora 官方 REST / SSE API
+                              ↓
+                    WeKnora：检索、Agent、知识与引用
+```
 
-- Uses the official DingTalk Stream SDK (`dingtalk-stream-sdk-go`); no public webhook endpoint is exposed.
-- Text messages only for now. Images, OpenAPI fallback, and card replies are not implemented yet.
-- Group chats are handled only when the bot is @-mentioned; other group messages are ignored.
-- Sessions: direct chats use one long-lived session per user; group chats share one session per group (default `shared` policy).
-- Replies are sent via the callback's `sessionWebhook`, which is fail-closed: only `https` URLs on `*.dingtalk.com` (port 443, no redirects) are accepted.
-- Required env vars to enable (all three or none): `DINGTALK_CLIENT_ID`, `DINGTALK_CLIENT_SECRET`, `DOBOTAI_TENANT_KEY`. Partial configuration is a fatal startup error.
+责任边界：
 
-## WeKnora baseline
+- **DobotAI**：钉钉协议、媒体收发、会话映射、命令路由、卡片、覆盖判定、人工支持、渠道审计。
+- **WeKnora**：通用 Agent Chat、检索、知识存储、引用与模型调用。
+- **DobotAI PostgreSQL**：只保存渠道与业务编排数据，不保存 WeKnora 知识正文。
+- **Redis**：仅用于队列、重试、幂等租约和短期状态。
 
-Target policy: latest stable official Release/Tag. The newest locally fetched stable tag is `v0.6.3`. Online GitHub verification is pending because DNS/proxy access was unavailable during initialization.
+## 目录结构
 
-## Run
+```text
+.
+├── cmd/
+│   ├── dobotai/                 主程序入口、运行时装配与后台 Worker
+│   └── directory-import/        钉钉通讯录导入命令
+├── internal/
+│   ├── channels/dingtalk/       钉钉 Stream、卡片、媒体、反馈与群通知
+│   ├── qa/                      问答主流程、WeKnora 调用和检索信号记录
+│   ├── weknora/                 SSE、工具结果和引用解析
+│   ├── coverage/                覆盖判定、Support Case 和人工提醒
+│   ├── reasoningmode/           /think 推理模式
+│   ├── settings/                /setting 与首位管理员绑定
+│   ├── outboundimage/           resource:// 图片私有 OSS 外发
+│   ├── questiontable/           问题表工作流
+│   ├── faqtable/                FAQ 表工作流
+│   ├── directory/               钉钉通讯录查询与导入
+│   ├── audit/                   审计查询
+│   ├── httpapi/                 /healthz、/version、/v1/qa 与审计 API
+│   ├── core/                    核心领域类型
+│   ├── session/                 会话键和会话标题
+│   ├── agentbinding/            渠道到 WeKnora Agent 的绑定
+│   ├── feedback/                点赞/点踩领域逻辑
+│   ├── secretstore/             本地密钥引用存储
+│   ├── dingtalkconfig/          钉钉凭据校验
+│   ├── runtime/                 运行时管理
+│   └── store/postgres/          PostgreSQL 持久化实现
+├── db/migrations/               SQL 迁移及其契约测试
+├── deploy/dobotai-dingtalk/     容器 Compose、安装/配置/启动/绑定脚本和部署手册
+├── docs/                        架构说明与 API 边界文档
+├── scripts/                     本地部署与部署资产契约测试
+├── Dockerfile                   DobotAI 容器镜像构建
+├── .env.example                 无真实凭据的配置示例
+└── README.md                    项目功能、边界和开发说明
+```
 
-1. Create an independent PostgreSQL database named `dobotai`.
-2. Apply `db/migrations/000001_core.up.sql` to that database only.
-3. Copy `.env.example` to a local `.env` and supply secrets outside Git.
-4. Export the variables and run:
+目录职责规则：`cmd/`只装配进程，`internal/`承载业务模块，`internal/store/postgres/`只实现数据库持久化，`db/migrations/`只放Schema变更，`deploy/`只放容器运行资产。历史计划、备份、镜像归档和真实环境文件均不进入Git。
+
+## 部署方式
+
+| 方式 | 适用场景 | 入口 | 数据库与迁移 | 推荐程度 |
+| --- | --- | --- | --- | --- |
+| 源码/原生二进制 | 本地开发、快速调试、临时问题定位 | `go run ./cmd/dobotai` 或受控构建的二进制 | 操作人员准备独立PostgreSQL并显式执行迁移 | 仅开发 |
+| Docker Compose | 测试、预发布、生产候选 | 仓库根目录`install-docker.sh` | 脚本构建镜像、创建`dobotai-postgres`和`dobotai-postgres-data`，并按序执行迁移 | 推荐 |
+
+### 源码/原生部署
+
+```bash
+# 开发机：使用Git外的环境文件注入真实配置
+go run ./cmd/dobotai
+curl http://127.0.0.1:8090/healthz
+```
+
+源码方式不自动创建数据库、不管理密钥目录、不自动执行SQL迁移，也不适合作为长期测试或生产运行方式。
+
+### Docker Compose 部署
+
+```bash
+# 克隆后进入仓库根目录执行：自动安装Docker/Compose（如缺失）、构建镜像、
+# 准备目录、独立PostgreSQL、命名卷、env模板和迁移。
+sudo bash ./install-docker.sh
+
+# 配置WeKnora和钉钉后自动启动应用
+sudo dobotai-dingtalk-configure
+
+# 仅首次且没有有效管理员时执行
+sudo dobotai-dingtalk-bind-admin
+```
+
+完整的安装、现有数据库迁移、备份、回滚和验收说明见 [Docker 部署手册](deploy/dobotai-dingtalk/README.md)。
+
+## 钉钉 Stream
+
+使用官方 `dingtalk-stream-sdk-go`，不暴露公网回调入口。
+
+- 群聊仅在机器人被 `@` 时处理；
+- 私聊按用户保持长期会话；群聊默认按群共享会话；
+- 回调 `sessionWebhook` 严格限制为 `https`、`*.dingtalk.com`、443端口且不允许重定向；
+- 启用 Stream 必须同时设置以下三项；三者均为空时渠道禁用，部分配置会失败关闭：
+
+```text
+DINGTALK_CLIENT_ID
+DINGTALK_CLIENT_SECRET
+DOBOTAI_TENANT_KEY
+```
+
+## 推理模式命令
+
+```text
+/think <问题>            仅当前问题使用智能推理
+/think on                开启持续智能推理
+/think off 或 /rag       关闭持续智能推理
+/setting rounds <1-50>   设置持续推理自动关闭轮数
+/setting hint <on|off>   设置剩余轮次提示
+/help、/帮助、/h          查看当前模式和帮助
+```
+
+持续推理默认最多10轮，成功回答才消耗轮次；10分钟无交互后逻辑到期，下一次问题自动回到快速问答。状态按 `tenant + channel + external_actor_id` 隔离。
+
+## 首位管理员终端绑定
+
+首位管理员不通过网页生成验证码。先确保钉钉 Stream 机器人已经正常运行，登录部署服务器后执行：
+
+```bash
+dobotai bootstrap-admin
+```
+
+若二进制未加入 `PATH`，使用其实际绝对路径执行。该命令只读取 `DATABASE_URL` 和 `DOBOTAI_TENANT_KEY`，不会启动 WeKnora、钉钉消费者或问答服务。
+
+命令会在终端使用加密随机数生成一个有效期10分钟的六码绑定码，并保持等待。候选管理员必须私聊机器人发送：
+
+```text
+/setting <六码绑定码>
+```
+
+验证码正确后，终端自动将该钉钉用户绑定为 `super_admin` 并显示成功。已有有效管理员时命令会拒绝执行，防止通过该入口追加或替换管理员。DobotAI 不提供网页管理面；钉钉凭据和运行配置由部署环境文件管理。
+
+## 覆盖与人工支持
+
+- 有结构化检索引用的回答标记为已覆盖；
+- 没有引用但已执行检索的回答标记为未覆盖；
+- 没有引用且未执行检索的文本标记为 `covered_non_knowledge_response`，不创建 Support Case；
+- 纯图片视觉识别单独记录为 `covered_visual_recognition`，不计入“未覆盖”；
+- 无权威知识时，产品统一回复：`当前暂无已发布的权威知识，暂不建议操作。`；
+- 人工通知只带当前问题和同一用户此前最多5个问题，不包含回答、引用或置信度；
+- 未覆盖与点踩共用幂等 Support Case，避免对同一 Turn 重复通知。
+
+## 配置
+
+复制 `.env.example` 为仅本机可读的运行时环境文件，并在 Git 外注入真实值。不得提交 API Key、数据库密码、钉钉凭据、OSS AccessKey、预签名 URL 或真实用户/群组标识。
+
+关键配置：
+
+```text
+DOBOTAI_LISTEN_ADDR
+DOBOTAI_INGRESS_TOKEN
+DOBOTAI_AGENT_BINDINGS
+DOBOTAI_QUICK_AGENT_ID
+DOBOTAI_REASONING_AGENT_ID
+WEKNORA_BASE_URL
+WEKNORA_API_KEY
+DATABASE_URL
+```
+
+可选能力必须整组配置或整组留空：
+
+- 钉钉 Stream；
+- 钉钉 AI 卡片；
+- 未覆盖问题 FAQ 表；
+- 人工支持群通知；
+- 问题表异步写入；
+- 回答图片私有 OSS 外发。
+
+任何部分配置均应在启动时失败关闭，而不是以不完整权限运行。
+
+## 数据库迁移
+
+DobotAI 使用独立 PostgreSQL，禁止指向 WeKnora 数据库。生产部署前必须按版本顺序执行并演练 `db/migrations/` 中的迁移；当前发布范围包含：
+
+```text
+000001_core ... 000018_coverage_visual_recognition_reason
+000019_reasoning_mode_state
+000020_feedback_support_trigger
+000021_coverage_non_knowledge_response_reason
+```
+
+迁移前应执行逻辑备份并验证恢复；迁移、二进制部署和钉钉渠道切换是独立步骤，不能把健康检查代替真实渠道验收。
+
+## 本地运行
 
 ```bash
 go run ./cmd/dobotai
 ```
 
-Health check:
+健康检查：
 
 ```bash
 curl http://127.0.0.1:8090/healthz
 ```
 
-Internal QA request:
+运行版本：
 
 ```bash
-curl -X POST http://127.0.0.1:8090/v1/qa \
-  -H "Authorization: Bearer $DOBOTAI_INGRESS_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "tenant_key":"default",
-    "channel":"dingtalk",
-    "conversation_type":"direct",
-    "external_user_id":"user-1",
-    "external_message_id":"message-1",
-    "query":"hello"
-  }'
+curl http://127.0.0.1:8090/version
 ```
 
-## Hard boundaries
+部署脚本应将 `version`、`commit_sha` 和 `build_time` 写入二进制，并仅在 `/version` 返回预期提交时接受部署。候选源码必须干净，避免运行版本掩盖未提交改动。
 
-- No WeKnora source modifications.
-- No custom WeKnora tables or columns.
-- No direct WeKnora database access.
-- No private WeKnora package imports.
-- All compatibility logic stays in `internal/weknora`.
-- Business data stays in DobotAI PostgreSQL.
-- Redis will be used only for queues, retries, idempotency leases, and temporary state.
+## 安全要求
 
-See `docs/architecture.md` for ownership and migration decisions.
+- 不修改 WeKnora 源码、Schema 或私有包；
+- 不直接连接 WeKnora 数据库；
+- 不将凭据、Token、预签名 URL 或知识正文写入日志；
+- 不接受任意外部图片 URL 作为可信媒体；
+- 对钉钉图片、WeKnora `resource://` 图片和 OSS 返回体均执行来源、大小、类型和签名校验；
+- 外发 OSS Bucket 保持私有；
+- 生产、测试的钉钉应用、数据库、OSS Bucket 和凭据必须相互隔离；
+- 生产上线必须使用已验收的同一构建产物，禁止在生产重新编译。
+
+更多设计与边界见 `docs/architecture.md`。

cmd/directory-import/main.go

@@ -0,0 +1,85 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/directory"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/store/postgres"
+)
+
+func main() {
+	if err := run(os.Args[1:], os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func run(args []string, out io.Writer) error {
+	flags := flag.NewFlagSet("directory-import", flag.ContinueOnError)
+	flags.SetOutput(io.Discard)
+	csvPath := flags.String("csv", "", "path to tested DingTalk directory CSV output")
+	tenant := flags.String("tenant", "", "tenant key")
+	databaseURLFile := flags.String("database-url-file", "", "file containing DATABASE_URL")
+	validateOnly := flags.Bool("validate-only", false, "validate CSV without connecting to PostgreSQL")
+	if err := flags.Parse(args); err != nil {
+		return errors.New("invalid directory import arguments")
+	}
+	if strings.TrimSpace(*csvPath) == "" || strings.TrimSpace(*tenant) == "" {
+		return errors.New("-csv and -tenant are required")
+	}
+	input, err := os.Open(*csvPath)
+	if err != nil {
+		return errors.New("open directory CSV failed")
+	}
+	defer input.Close()
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+	if *validateOnly {
+		count, importErr := directory.ImportCSV(ctx, *tenant, input, validationWriter{})
+		if importErr != nil {
+			return errors.New("directory CSV validation failed")
+		}
+		_, _ = fmt.Fprintf(out, "validated_profiles=%d\n", count)
+		return nil
+	}
+	if strings.TrimSpace(*databaseURLFile) == "" {
+		return errors.New("-database-url-file is required for import")
+	}
+	databaseURL, err := readSecretFile(*databaseURLFile)
+	if err != nil {
+		return err
+	}
+	store, err := postgres.Open(ctx, databaseURL)
+	if err != nil {
+		return errors.New("open directory database failed")
+	}
+	defer store.Close()
+	count, err := directory.ImportCSV(ctx, *tenant, input, store)
+	if err != nil {
+		return errors.New("directory CSV import failed")
+	}
+	_, _ = fmt.Fprintf(out, "imported_profiles=%d\n", count)
+	return nil
+}
+
+type validationWriter struct{}
+
+func (validationWriter) UpsertDirectoryProfiles(context.Context, string, []directory.Profile) error {
+	return nil
+}
+
+func readSecretFile(path string) (string, error) {
+	raw, err := os.ReadFile(strings.TrimSpace(path))
+	if err != nil { return "", errors.New("read database URL file failed") }
+	if len(raw) > 16<<10 { return "", errors.New("database URL file is too large") }
+	value := strings.TrimSpace(string(raw))
+	if value == "" { return "", errors.New("database URL file is empty") }
+	return value, nil
+}

cmd/directory-import/main_test.go

@@ -0,0 +1,48 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestReadSecretFileTrimsValue(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "database_url")
+	if err := os.WriteFile(path, []byte(" postgres://secret-value \n"), 0o600); err != nil { t.Fatal(err) }
+	value, err := readSecretFile(path)
+	if err != nil { t.Fatalf("readSecretFile: %v", err) }
+	if value != "postgres://secret-value" { t.Fatalf("value=%q", value) }
+}
+
+func TestReadSecretFileErrorDoesNotLeakContents(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "empty")
+	if err := os.WriteFile(path, []byte(""), 0o600); err != nil { t.Fatal(err) }
+	_, err := readSecretFile(path)
+	if err == nil { t.Fatal("expected error") }
+	if strings.Contains(err.Error(), "secret-value") { t.Fatalf("error leaked secret: %v", err) }
+}
+
+func TestRunValidateOnlyDoesNotRequireDatabase(t *testing.T) {
+	csvPath := filepath.Join(t.TempDir(), "directory.csv")
+	if err := os.WriteFile(csvPath, []byte("user_id,union_id,name,nickname,title,department_ids,dept_name\nstaff-1,,张三,,工程师,100,技术支持部\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	var out bytes.Buffer
+	err := run([]string{"-csv", csvPath, "-tenant", "tenant-a", "-validate-only"}, &out)
+	if err != nil {
+		t.Fatalf("run validate-only: %v", err)
+	}
+	if !strings.Contains(out.String(), "validated_profiles=1") {
+		t.Fatalf("output=%q", out.String())
+	}
+}
+
+func TestRunRequiresCSVAndDatabaseURLFileBeforeConnecting(t *testing.T) {
+	var out bytes.Buffer
+	for _, args := range [][]string{{}, {"-csv", "snapshot.csv"}} {
+		err := run(args, &out)
+		if err == nil { t.Fatalf("run(%v) expected error", args) }
+	}
+}

cmd/dobotai/bootstrap_admin.go

@@ -0,0 +1,89 @@
+package main
+
+import (
+	"context"
+	cryptorand "crypto/rand"
+	"errors"
+	"fmt"
+	"io"
+	"math/big"
+	"os"
+	"strings"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/settings"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/store/postgres"
+)
+
+const bootstrapAdminTTL = 10 * time.Minute
+
+type bootstrapAdminRepository interface {
+	AdministratorCount(context.Context, string) (int, error)
+	CreateBootstrapChallenge(context.Context, string, string, time.Time) error
+	ConfirmBootstrap(context.Context, string) error
+}
+
+var createBootstrapChallenge = func(ctx context.Context, repo bootstrapAdminRepository, tenant, code string, expiry time.Time) error {
+	return repo.CreateBootstrapChallenge(ctx, tenant, code, expiry)
+}
+
+func runBootstrapAdminCommand(ctx context.Context, output io.Writer) error {
+	tenant := strings.TrimSpace(os.Getenv("DOBOTAI_TENANT_KEY"))
+	store, err := postgres.Open(ctx, os.Getenv("DATABASE_URL"))
+	if err != nil {
+		return err
+	}
+	defer store.Close()
+	repository, err := postgres.NewSettingsRepository(store)
+	if err != nil {
+		return err
+	}
+	return runBootstrapAdmin(ctx, output, repository, tenant, cryptorand.Reader, time.Now, time.Second)
+}
+
+func runBootstrapAdmin(ctx context.Context, output io.Writer, repository bootstrapAdminRepository, tenant string, random io.Reader, now func() time.Time, pollInterval time.Duration) error {
+	if repository == nil || strings.TrimSpace(tenant) == "" || random == nil || now == nil || pollInterval <= 0 {
+		return errors.New("bootstrap administrator command requires repository, tenant, random source, clock, and poll interval")
+	}
+	count, err := repository.AdministratorCount(ctx, tenant)
+	if err != nil {
+		return fmt.Errorf("check active administrators: %w", err)
+	}
+	if count > 0 {
+		return errors.New("an active administrator already exists; use administrator management instead")
+	}
+	codeNumber, err := cryptorand.Int(random, big.NewInt(1_000_000))
+	if err != nil {
+		return fmt.Errorf("generate bootstrap code: %w", err)
+	}
+	code := fmt.Sprintf("%06d", codeNumber.Int64())
+	expiresAt := now().Add(bootstrapAdminTTL)
+	if err := createBootstrapChallenge(ctx, repository, tenant, code, expiresAt); err != nil {
+		return fmt.Errorf("create bootstrap challenge: %w", err)
+	}
+	fmt.Fprintf(output, "首位管理员绑定已开始。\n绑定码：%s\n请在%s前私聊钉钉机器人发送：/setting %s\n终端正在等待绑定完成；按 Ctrl+C 取消。\n", code, expiresAt.Local().Format("2006-01-02 15:04:05"), code)
+
+	waitFor := expiresAt.Sub(now())
+	if waitFor <= 0 {
+		return errors.New("bootstrap binding expiry must be in the future")
+	}
+	waitCtx, cancel := context.WithTimeout(ctx, waitFor)
+	defer cancel()
+	ticker := time.NewTicker(pollInterval)
+	defer ticker.Stop()
+	for {
+		err := repository.ConfirmBootstrap(waitCtx, tenant)
+		if err == nil {
+			fmt.Fprintln(output, "首位管理员绑定成功：候选用户已设为 super_admin。")
+			return nil
+		}
+		if !errors.Is(err, settings.ErrBootstrapCandidatePending) {
+			return fmt.Errorf("confirm bootstrap candidate: %w", err)
+		}
+		select {
+		case <-waitCtx.Done():
+			return errors.New("bootstrap binding expired or cancelled before a candidate was verified")
+		case <-ticker.C:
+		}
+	}
+}

cmd/dobotai/bootstrap_admin_test.go

@@ -0,0 +1,88 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/settings"
+)
+
+type bootstrapAdminRepoStub struct {
+	administratorCount int
+	createdCode        string
+	createdExpiry      time.Time
+	confirmCalls       int
+}
+
+func (r *bootstrapAdminRepoStub) AdministratorCount(context.Context, string) (int, error) {
+	return r.administratorCount, nil
+}
+
+func (r *bootstrapAdminRepoStub) CreateBootstrapChallenge(_ context.Context, _ string, code string, expiry time.Time) error {
+	r.createdCode, r.createdExpiry = code, expiry
+	return nil
+}
+
+func (r *bootstrapAdminRepoStub) ConfirmBootstrap(context.Context, string) error {
+	r.confirmCalls++
+	if r.confirmCalls == 1 {
+		return settings.ErrBootstrapCandidatePending
+	}
+	return nil
+}
+
+func TestRunBootstrapAdminGeneratesCodeWaitsAndConfirmsCandidate(t *testing.T) {
+	now := time.Date(2026, time.September, 10, 8, 0, 0, 0, time.UTC)
+	repo := &bootstrapAdminRepoStub{}
+	var output bytes.Buffer
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+
+	err := runBootstrapAdmin(ctx, &output, repo, "tenant-test", bytes.NewReader(make([]byte, 32)), func() time.Time { return now }, time.Millisecond)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if repo.createdCode != "000000" {
+		t.Fatalf("code=%q", repo.createdCode)
+	}
+	if !repo.createdExpiry.Equal(now.Add(10 * time.Minute)) {
+		t.Fatalf("expiry=%s", repo.createdExpiry)
+	}
+	if repo.confirmCalls < 2 {
+		t.Fatalf("confirm calls=%d", repo.confirmCalls)
+	}
+	for _, required := range []string{"/setting 000000", "绑定成功", "super_admin"} {
+		if !strings.Contains(output.String(), required) {
+			t.Fatalf("output=%q missing %q", output.String(), required)
+		}
+	}
+}
+
+func TestRunBootstrapAdminRefusesWhenAdministratorAlreadyExists(t *testing.T) {
+	repo := &bootstrapAdminRepoStub{administratorCount: 1}
+	err := runBootstrapAdmin(context.Background(), &bytes.Buffer{}, repo, "tenant-test", bytes.NewReader(make([]byte, 32)), time.Now, time.Millisecond)
+	if err == nil || !strings.Contains(err.Error(), "already exists") {
+		t.Fatalf("err=%v", err)
+	}
+	if repo.createdCode != "" || repo.confirmCalls != 0 {
+		t.Fatalf("repo mutated: %+v", repo)
+	}
+}
+
+func TestRunBootstrapAdminPropagatesChallengeCreationFailure(t *testing.T) {
+	repo := &bootstrapAdminRepoStub{}
+	original := createBootstrapChallenge
+	createBootstrapChallenge = func(context.Context, bootstrapAdminRepository, string, string, time.Time) error {
+		return errors.New("database unavailable")
+	}
+	t.Cleanup(func() { createBootstrapChallenge = original })
+
+	err := runBootstrapAdmin(context.Background(), &bytes.Buffer{}, repo, "tenant-test", bytes.NewReader(make([]byte, 32)), time.Now, time.Millisecond)
+	if err == nil || !strings.Contains(err.Error(), "database unavailable") {
+		t.Fatalf("err=%v", err)
+	}
+}

cmd/dobotai/directory_wiring_test.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"os"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+func TestMainWiresDirectoryResolverIntoDingTalkHandler(t *testing.T) {
+	raw, err := os.ReadFile("main.go")
+	if err != nil {
+		t.Fatalf("read main.go: %v", err)
+	}
+	src := string(raw)
+	for _, required := range []string{
+		"directory.NewDingTalkLookup",
+		"directory.NewResolver",
+	} {
+		if !strings.Contains(src, required) {
+			t.Errorf("main.go missing %q", required)
+		}
+	}
+	if !regexp.MustCompile(`Directory:\s*directoryResolver`).MatchString(src) {
+		t.Error("main.go does not wire directoryResolver into HandlerOptions.Directory")
+	}
+}

cmd/dobotai/faq_workflow.go

@@ -0,0 +1,92 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log"
+	"os"
+	"strings"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/faqtable"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/questiontable"
+)
+
+type faqConfig struct {
+	BaseID       string
+	SheetID      string
+	ViewID       string
+	OperatorID   string
+	FieldMapping map[string]string
+}
+
+func readFAQConfig() (faqConfig, error) {
+	cfg := faqConfig{
+		BaseID:     strings.TrimSpace(os.Getenv("DINGTALK_FAQ_TABLE_BASE_ID")),
+		SheetID:    strings.TrimSpace(os.Getenv("DINGTALK_FAQ_TABLE_SHEET_ID")),
+		ViewID:     strings.TrimSpace(os.Getenv("DINGTALK_FAQ_TABLE_VIEW_ID")),
+		OperatorID: strings.TrimSpace(os.Getenv("DINGTALK_FAQ_TABLE_OPERATOR_ID")),
+	}
+	blank := cfg.BaseID == "" && cfg.SheetID == "" && cfg.ViewID == "" && cfg.OperatorID == ""
+	complete := cfg.BaseID != "" && cfg.SheetID != "" && cfg.ViewID != "" && cfg.OperatorID != ""
+	if blank {
+		return faqConfig{}, nil
+	}
+	if !complete {
+		return faqConfig{}, errors.New("DingTalk FAQ table config must be complete or disabled")
+	}
+	return cfg, nil
+}
+
+func buildFAQDispatcher(repo faqtable.ExportRepository, clientID, clientSecret string, cfg faqConfig) (*faqtable.Dispatcher, error) {
+	if cfg.BaseID == "" {
+		return nil, nil
+	}
+	if repo == nil {
+		return nil, errors.New("FAQ dispatcher repository is required")
+	}
+	client, err := questiontable.NewClient(questiontable.Config{
+		ClientID: clientID, Secret: clientSecret, BaseID: cfg.BaseID,
+		SheetID: cfg.SheetID, OperatorID: cfg.OperatorID, FieldMapping: cfg.FieldMapping,
+	}, nil)
+	if err != nil {
+		return nil, err
+	}
+	return faqtable.NewDispatcher(repo, client, nil)
+}
+
+type faqPollerRunner interface {
+	RunOnce(context.Context) (faqtable.DispatcherStats, error)
+}
+
+func runFAQPoller(ctx context.Context, runner faqPollerRunner, interval time.Duration) {
+	if runner == nil || interval <= 0 {
+		return
+	}
+	run := func() {
+		runCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
+		stats, err := runner.RunOnce(runCtx)
+		cancel()
+		if err != nil {
+			log.Printf("FAQ table dispatch failed")
+			return
+		}
+		if stats.Claimed > 0 {
+			log.Printf("FAQ table dispatch: claimed=%d exported=%d failed=%d", stats.Claimed, stats.Exported, stats.Failed)
+		}
+	}
+	if ctx.Err() != nil {
+		return
+	}
+	run()
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			run()
+		}
+	}
+}

cmd/dobotai/faq_workflow_test.go

@@ -0,0 +1,81 @@
+package main
+
+import (
+	"context"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/faqtable"
+)
+
+type faqRepoStub struct{}
+
+func (*faqRepoStub) Claim(context.Context, int, int, time.Time) ([]faqtable.PendingExport, error) {
+	return nil, nil
+}
+func (*faqRepoStub) MarkExported(context.Context, string, string) error { return nil }
+func (*faqRepoStub) MarkFailed(context.Context, string, string) error   { return nil }
+
+func TestReadFAQConfigDisabledWhenAllBlank(t *testing.T) {
+	for _, key := range []string{"DINGTALK_FAQ_TABLE_BASE_ID", "DINGTALK_FAQ_TABLE_SHEET_ID", "DINGTALK_FAQ_TABLE_VIEW_ID", "DINGTALK_FAQ_TABLE_OPERATOR_ID"} {
+		t.Setenv(key, "")
+	}
+	cfg, err := readFAQConfig()
+	if err != nil || cfg.BaseID != "" {
+		t.Fatalf("cfg=%+v err=%v", cfg, err)
+	}
+}
+
+func TestReadFAQConfigRejectsPartialValues(t *testing.T) {
+	t.Setenv("DINGTALK_FAQ_TABLE_BASE_ID", "base")
+	t.Setenv("DINGTALK_FAQ_TABLE_SHEET_ID", "")
+	t.Setenv("DINGTALK_FAQ_TABLE_VIEW_ID", "view")
+	t.Setenv("DINGTALK_FAQ_TABLE_OPERATOR_ID", "operator")
+	if _, err := readFAQConfig(); err == nil {
+		t.Fatal("expected partial-config error")
+	}
+}
+
+func TestBuildFAQDispatcherRequiresRepositoryWhenEnabled(t *testing.T) {
+	cfg := faqConfig{BaseID: "base", SheetID: "sheet", ViewID: "view", OperatorID: "operator"}
+	if _, err := buildFAQDispatcher(nil, "client", "secret", cfg); err == nil {
+		t.Fatal("expected repository error")
+	}
+	if d, err := buildFAQDispatcher(&faqRepoStub{}, "client", "secret", cfg); err != nil || d == nil {
+		t.Fatalf("dispatcher=%v err=%v", d, err)
+	}
+}
+
+func TestMainWiresFAQExportBeforeSupportNotification(t *testing.T) {
+	data, err := os.ReadFile("main.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := string(data)
+	for _, fragment := range []string{
+		"readFAQConfig()", "postgres.NewFAQExportRepository(store)",
+		"buildFAQDispatcher(", "runFAQPoller(ctx, faqDispatcher, 5*time.Second)",
+		"faqtable.NewRecordLinkBuilder(", "buildSupportDispatcher(",
+	} {
+		if !strings.Contains(source, fragment) {
+			t.Errorf("main FAQ wiring missing %q", fragment)
+		}
+	}
+	if strings.Index(source, "runFAQPoller(ctx") > strings.Index(source, "runSupportDispatcher(ctx") {
+		t.Fatal("FAQ exporter must start before support notifications")
+	}
+}
+
+func TestEnvExampleDocumentsFAQWorkflowConfig(t *testing.T) {
+	data, err := os.ReadFile("../../.env.example")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, key := range []string{"DINGTALK_FAQ_TABLE_BASE_ID", "DINGTALK_FAQ_TABLE_SHEET_ID", "DINGTALK_FAQ_TABLE_VIEW_ID", "DINGTALK_FAQ_TABLE_OPERATOR_ID"} {
+		if !strings.Contains(string(data), key+"=") {
+			t.Errorf(".env.example missing %s", key)
+		}
+	}
+}

cmd/dobotai/main.go

@@ -8,23 +8,49 @@ import (
 	"os"
 	"os/signal"
 	"strings"
+	"sync/atomic"
 	"syscall"
 	"time"
 
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/agentbinding"
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/audit"
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/channels/dingtalk"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/coverage"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/directory"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/faqtable"
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/feedback"
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/httpapi"
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/qa"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/reasoningmode"
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/session"
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/store/postgres"
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/weknora"
 )
 
+var (
+	version   = "dev"
+	commitSHA = "unknown"
+	buildTime = "unknown"
+)
+
+func runtimeBuildInfo() httpapi.BuildInfo {
+	return httpapi.BuildInfo{
+		Version:   version,
+		CommitSHA: commitSHA,
+		BuildTime: buildTime,
+	}
+}
+
 func main() {
 	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
 	defer cancel()
+	if len(os.Args) == 2 && os.Args[1] == "bootstrap-admin" {
+		if err := runBootstrapAdminCommand(ctx, os.Stdout); err != nil {
+			log.Fatal(err)
+		}
+		return
+	}
+	var restartRequested atomic.Bool
 	storeCtx, storeCancel := context.WithTimeout(ctx, 10*time.Second)
 	defer storeCancel()
 	store, err := postgres.Open(storeCtx, os.Getenv("DATABASE_URL"))
@@ -32,6 +58,19 @@ func main() {
 		log.Fatal(err)
 	}
 	defer store.Close()
+	settingsRuntime, err := buildSettingsRuntime(storeCtx, store, os.Getenv("DOBOTAI_TENANT_KEY"))
+	if err != nil {
+		log.Fatal(err)
+	}
+	settingsRuntime.bindings.restartDelay = 300 * time.Millisecond
+	settingsRuntime.bindings.restart = func() { restartRequested.Store(true); cancel() }
+	address := strings.TrimSpace(os.Getenv("DOBOTAI_LISTEN_ADDR"))
+	if address == "" {
+		address = "127.0.0.1:8090"
+	}
+	if strings.TrimSpace(settingsRuntime.clientID) == "" || strings.TrimSpace(settingsRuntime.secret) == "" {
+		log.Fatal("DingTalk credentials are required; configure DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET in the protected runtime environment")
+	}
 	client, err := weknora.NewClient(os.Getenv("WEKNORA_BASE_URL"), os.Getenv("WEKNORA_API_KEY"), 120*time.Second)
 	if err != nil {
 		log.Fatal(err)
@@ -40,6 +79,14 @@ func main() {
 	if err != nil {
 		log.Fatal(err)
 	}
+	reasoningService, err := reasoningmode.NewService(
+		store,
+		os.Getenv("DOBOTAI_QUICK_AGENT_ID"),
+		os.Getenv("DOBOTAI_REASONING_AGENT_ID"),
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
 	groupPolicy := session.GroupPolicy(strings.TrimSpace(os.Getenv("DOBOTAI_GROUP_SESSION_POLICY")))
 	if groupPolicy == "" {
 		groupPolicy = session.GroupShared
@@ -47,33 +94,173 @@ func main() {
 	if groupPolicy != session.GroupShared && groupPolicy != session.GroupPerUser {
 		log.Fatal("DOBOTAI_GROUP_SESSION_POLICY must be shared or per_user")
 	}
-	qaService, err := qa.New(store, bindings, client, groupPolicy)
+	coverageService, err := coverage.NewService(store)
 	if err != nil {
 		log.Fatal(err)
 	}
-	address := strings.TrimSpace(os.Getenv("DOBOTAI_LISTEN_ADDR"))
-	if address == "" {
-		address = "127.0.0.1:8090"
+	qaService, err := qa.New(
+		store,
+		bindings,
+		client,
+		groupPolicy,
+		qa.WithSucceededTurnObserver(coverageService, func(err error) {
+			log.Printf("coverage persistence failed: %v", err)
+		}),
+		qa.WithReasoningModeFinalizer(reasoningService, func(err error) {
+			log.Printf("reasoning mode completion failed: %T", err)
+		}),
+	)
+	if err != nil {
+		log.Fatal(err)
 	}
 	auditOptions, err := buildAuditOptions(store, os.Getenv("DOBOTAI_TENANT_KEY"), os.Getenv("DOBOTAI_ADMIN_TOKEN"), address)
 	if err != nil {
 		log.Fatal(err)
 	}
+	auditOptions.BuildInfo = runtimeBuildInfo()
 	api, err := httpapi.NewWithOptions(qaService, os.Getenv("DOBOTAI_INGRESS_TOKEN"), auditOptions)
 	if err != nil {
 		log.Fatal(err)
 	}
 
 	dingCfg := dingtalk.StreamConfig{
-		ClientID:     os.Getenv("DINGTALK_CLIENT_ID"),
-		ClientSecret: os.Getenv("DINGTALK_CLIENT_SECRET"),
+		ClientID:     settingsRuntime.clientID,
+		ClientSecret: settingsRuntime.secret,
 		TenantKey:    os.Getenv("DOBOTAI_TENANT_KEY"),
 	}
 	if err := dingCfg.Validate(); err != nil {
 		log.Fatal(err)
 	}
+	activeBindings, err := settingsRuntime.repository.ActiveBindings(storeCtx, dingCfg.TenantKey)
+	if err != nil {
+		log.Fatal(err)
+	}
+	runtimeReady := make(chan struct{})
+	faqCfg, err := readFAQConfig()
+	if err != nil {
+		log.Fatal(err)
+	}
+	if binding, ok := activeBindings["faq_table"]; ok {
+		faqCfg = faqConfig{BaseID: binding.BaseID, SheetID: binding.SheetID, ViewID: binding.ViewID, OperatorID: binding.OperatorID, FieldMapping: binding.FieldMapping}
+	}
+	var faqWorkflowDone chan struct{}
+	var faqRecordLinks *faqtable.RecordLinkBuilder
+	if faqCfg.BaseID != "" {
+		faqRecordLinks, err = faqtable.NewRecordLinkBuilder(faqCfg.BaseID, faqCfg.SheetID, faqCfg.ViewID)
+		if err != nil {
+			log.Fatal(err)
+		}
+		faqRepo, err := postgres.NewFAQExportRepository(store)
+		if err != nil {
+			log.Fatal(err)
+		}
+		faqDispatcher, err := buildFAQDispatcher(faqRepo, dingCfg.ClientID, dingCfg.ClientSecret, faqCfg)
+		if err != nil {
+			log.Fatalf("DingTalk FAQ table dispatcher init failed: %v", err)
+		}
+		faqWorkflowDone = make(chan struct{})
+		go func() {
+			defer close(faqWorkflowDone)
+			select {
+			case <-runtimeReady:
+			case <-ctx.Done():
+				return
+			}
+			runFAQPoller(ctx, faqDispatcher, 5*time.Second)
+		}()
+		log.Printf("DingTalk FAQ table dispatcher started")
+	}
+
+	supportConversationID := os.Getenv("DINGTALK_SUPPORT_GROUP_OPEN_CONVERSATION_ID")
+	if binding, ok := activeBindings["support_group"]; ok {
+		supportConversationID = binding.ConversationID
+	}
+	supportDispatcher, err := buildSupportDispatcher(
+		store,
+		dingCfg.ClientID,
+		dingCfg.ClientSecret,
+		supportConversationID,
+		faqRecordLinks,
+	)
+	if err != nil {
+		log.Fatalf("DingTalk support notification init failed: %v", err)
+	}
+	if supportDispatcher != nil {
+		go func() {
+			select {
+			case <-runtimeReady:
+			case <-ctx.Done():
+				return
+			}
+			runSupportDispatcher(ctx, supportDispatcher, 5*time.Second)
+		}()
+		log.Printf("DingTalk support notification dispatcher started")
+	}
+
+	// Outbound image runtime (stable-image publishing) is built from environment
+	// variables independently of the Stream ingress, so both the question-table
+	// answer rewriter and the inbound-image publisher can share it.
+	outboundImages, err := buildOutboundImageRuntime(outboundImageConfig{
+		WeKnoraBaseURL:  os.Getenv("WEKNORA_BASE_URL"),
+		WeKnoraAPIKey:   os.Getenv("WEKNORA_API_KEY"),
+		Endpoint:        os.Getenv("DOBOTAI_OUTBOUND_IMAGE_OSS_ENDPOINT"),
+		Region:          os.Getenv("DOBOTAI_OUTBOUND_IMAGE_OSS_REGION"),
+		AccessKeyID:     os.Getenv("DOBOTAI_OUTBOUND_IMAGE_OSS_ACCESS_KEY_ID"),
+		AccessKeySecret: os.Getenv("DOBOTAI_OUTBOUND_IMAGE_OSS_ACCESS_KEY_SECRET"),
+		Bucket:          os.Getenv("DOBOTAI_OUTBOUND_IMAGE_OSS_BUCKET"),
+		PublicBaseURL:   os.Getenv("DOBOTAI_OUTBOUND_IMAGE_PUBLIC_BASE_URL"),
+	})
+	if err != nil {
+		log.Fatalf("DingTalk outbound image init failed: %v", err)
+	}
+
+	// Question table dispatcher (optional, fail-closed).
+	qtCfg, err := readQuestionTableConfig()
+	if err != nil {
+		log.Fatal(err)
+	}
+	if binding, ok := activeBindings["question_table"]; ok {
+		qtCfg = questionTableConfig{BaseID: binding.BaseID, SheetID: binding.SheetID, OperatorID: binding.OperatorID, FieldMapping: binding.FieldMapping}
+	}
+	store.SetExternalTableExports(qtCfg.BaseID != "", faqCfg.BaseID != "")
+	var questionTableDone chan struct{}
+	if qtCfg.BaseID != "" {
+		qtRepo, err := postgres.NewQuestionTableExportRepository(store)
+		if err != nil {
+			log.Fatal(err)
+		}
+		qtDispatcher, err := buildQuestionTableDispatcher(qtRepo, dingCfg.ClientID, dingCfg.ClientSecret, qtCfg, answerRewriterAdapter{rewriter: outboundImages.rewriter})
+		if err != nil {
+			log.Fatalf("DingTalk question table dispatcher init failed: %v", err)
+		}
+		questionTableDone = make(chan struct{})
+		go func() {
+			defer close(questionTableDone)
+			select {
+			case <-runtimeReady:
+			case <-ctx.Done():
+				return
+			}
+			runQuestionTablePoller(ctx, qtDispatcher, 5*time.Second)
+		}()
+		log.Printf("DingTalk question table dispatcher started")
+	}
 	var streamClient *dingtalk.StreamClient
 	if dingCfg.Enabled() {
+		directoryLookup, err := directory.NewDingTalkLookup(directory.DingTalkLookupConfig{
+			TokenURL:     "https://oapi.dingtalk.com/gettoken",
+			APIBaseURL:   "https://oapi.dingtalk.com",
+			ClientID:     dingCfg.ClientID,
+			ClientSecret: dingCfg.ClientSecret,
+			Timeout:      10 * time.Second,
+		})
+		if err != nil {
+			log.Fatalf("DingTalk directory lookup init failed: %v", err)
+		}
+		directoryResolver, err := directory.NewResolver(store, directoryLookup)
+		if err != nil {
+			log.Fatalf("DingTalk directory resolver init failed: %v", err)
+		}
 		feedbackService, err := feedback.NewService(dingCfg.TenantKey, "dingtalk", store)
 		if err != nil {
 			log.Fatal(err)
@@ -112,7 +299,16 @@ func main() {
 			dingtalk.TenantConfig{TenantKey: dingCfg.TenantKey, Channel: "dingtalk"},
 			qaService,
 			sender,
-			dingtalk.HandlerOptions{ImageDownloader: downloader, CardSender: cardSender},
+			dingtalk.HandlerOptions{
+				ImageDownloader:  downloader,
+				ImagePublisher:   outboundImages.publisher,
+				CardSender:       cardSender,
+				Directory:        directoryResolver,
+				OutboundRewriter: outboundImages.rewriter,
+				SettingsRouter:   &dingTalkSettingsRouter{controller: settingsRuntime.controller},
+				ReasoningRouter:  &dingTalkReasoningRouter{service: reasoningService},
+				LanguageResolver: settingsRuntime.repository,
+			},
 		)
 		if err != nil {
 			log.Fatal(err)
@@ -125,9 +321,19 @@ func main() {
 			log.Fatal(err)
 		}
 		defer streamClient.Close()
+		if err := settingsRuntime.repository.MarkDingTalkRuntimeHealthy(context.Background(), dingCfg.TenantKey, settingsRuntime.secretRef); err != nil {
+			streamClient.Close()
+			log.Fatal(err)
+		}
 		log.Printf("DingTalk Stream ingress started for tenant %s", dingCfg.TenantKey)
 	}
-	server := &http.Server{Addr: address, Handler: api.Handler(), ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 15 * time.Second, WriteTimeout: 130 * time.Second, IdleTimeout: 60 * time.Second}
+	close(runtimeReady)
+	rootHandler := http.NewServeMux()
+	rootHandler.Handle("/", api.Handler())
+	if outboundImages.handler != nil {
+		rootHandler.Handle(outboundImageRoute, outboundImages.handler)
+	}
+	server := &http.Server{Addr: address, Handler: rootHandler, ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 15 * time.Second, WriteTimeout: 130 * time.Second, IdleTimeout: 60 * time.Second}
 	go func() {
 		log.Printf("DobotAI ingress listening on %s", address)
 		if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
@@ -141,6 +347,39 @@ func main() {
 	if err := server.Shutdown(shutdownCtx); err != nil {
 		log.Printf("HTTP shutdown: %v", err)
 	}
+	if faqWorkflowDone != nil {
+		select {
+		case <-faqWorkflowDone:
+		case <-shutdownCtx.Done():
+			log.Printf("FAQ table poller shutdown timed out")
+		}
+	}
+	if questionTableDone != nil {
+		select {
+		case <-questionTableDone:
+		case <-shutdownCtx.Done():
+			log.Printf("question table poller shutdown timed out")
+		}
+	}
+	if streamClient != nil {
+		streamClient.Close()
+	}
+	if restartRequested.Load() {
+		os.Exit(75)
+	}
+}
+
+func outboundOSSConfigured() bool {
+	for _, key := range []string{
+		"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", "DOBOTAI_OUTBOUND_IMAGE_PUBLIC_BASE_URL",
+	} {
+		if strings.TrimSpace(os.Getenv(key)) == "" {
+			return false
+		}
+	}
+	return true
 }
 
 func buildAuditOptions(repo audit.TurnRepository, tenantKey, adminToken, address string) (httpapi.Options, error) {

cmd/dobotai/main_test.go

@@ -21,6 +21,20 @@ func (r *auditRepoStub) GetTurn(context.Context, string, string) (audit.TurnDeta
 	return audit.TurnDetail{}, audit.ErrNotFound
 }
 
+func TestRuntimeBuildInfoUsesLinkerVariables(t *testing.T) {
+	oldVersion, oldCommitSHA, oldBuildTime := version, commitSHA, buildTime
+	t.Cleanup(func() {
+		version, commitSHA, buildTime = oldVersion, oldCommitSHA, oldBuildTime
+	})
+	version = "2.1.0"
+	commitSHA = "abc123def456"
+	buildTime = "2026-07-27T12:00:00Z"
+	got := runtimeBuildInfo()
+	if got.Version != version || got.CommitSHA != commitSHA || got.BuildTime != buildTime {
+		t.Fatalf("build info=%+v", got)
+	}
+}
+
 func TestBuildAuditOptionsDisabledIsBackwardCompatible(t *testing.T) {
 	opts, err := buildAuditOptions(nil, "", "", "0.0.0.0:8090")
 	if err != nil {
@@ -101,3 +115,87 @@ func TestMainWiresOptionalDingTalkCardDebugUser(t *testing.T) {
 		}
 	}
 }
+
+func TestBuildOutboundImageRuntimeConfig(t *testing.T) {
+	t.Run("disabled", func(t *testing.T) {
+		runtime, err := buildOutboundImageRuntime(outboundImageConfig{})
+		if err != nil || runtime.rewriter != nil || runtime.handler != nil {
+			t.Fatalf("runtime=%+v err=%v", runtime, err)
+		}
+	})
+	t.Run("partial configuration rejected", func(t *testing.T) {
+		_, err := buildOutboundImageRuntime(outboundImageConfig{Bucket: "private-bucket"})
+		if err == nil {
+			t.Fatal("expected configuration error")
+		}
+	})
+	t.Run("complete configuration", func(t *testing.T) {
+		runtime, err := buildOutboundImageRuntime(outboundImageConfig{
+			WeKnoraBaseURL:  "http://127.0.0.1:8080",
+			WeKnoraAPIKey:   "api-key",
+			Endpoint:        "https://oss-cn-shenzhen.aliyuncs.com",
+			Region:          "cn-shenzhen",
+			AccessKeyID:     "access-key-id",
+			AccessKeySecret: "access-key-secret",
+			Bucket:          "private-bucket",
+			PublicBaseURL:   "https://weknora-api-test.dobot.cn/dingtalk/i",
+		})
+		if err != nil || runtime.rewriter == nil || runtime.handler == nil {
+			t.Fatalf("runtime=%+v err=%v", runtime, err)
+		}
+	})
+}
+
+func TestMainWiresStableOutboundImageRuntime(t *testing.T) {
+	data, err := os.ReadFile("main.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := string(data)
+	for _, fragment := range []string{
+		`buildOutboundImageRuntime(outboundImageConfig{`,
+		`PublicBaseURL:   os.Getenv("DOBOTAI_OUTBOUND_IMAGE_PUBLIC_BASE_URL")`,
+		`OutboundRewriter: outboundImages.rewriter`,
+		`rootHandler.Handle(outboundImageRoute, outboundImages.handler)`,
+	} {
+		if !strings.Contains(source, fragment) {
+			t.Errorf("main stable image wiring missing %q", fragment)
+		}
+	}
+}
+
+func TestOutboundOSSConfiguredRequiresStablePublicBaseURL(t *testing.T) {
+	for _, key := range []string{
+		"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",
+	} {
+		t.Setenv(key, "configured")
+	}
+	t.Setenv("DOBOTAI_OUTBOUND_IMAGE_PUBLIC_BASE_URL", "")
+	if outboundOSSConfigured() {
+		t.Fatal("stable public base URL must be required")
+	}
+	t.Setenv("DOBOTAI_OUTBOUND_IMAGE_PUBLIC_BASE_URL", "https://img.example/dingtalk/i")
+	if !outboundOSSConfigured() {
+		t.Fatal("complete stable image configuration should be active")
+	}
+}
+
+func TestMainDoesNotExposeWebAdministrationOrSetupOnlyMode(t *testing.T) {
+	data, err := os.ReadFile("main.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := string(data)
+	for _, forbidden := range []string{"internal/adminweb", "adminweb.", `"/admin/"`, "runSetupOnly"} {
+		if strings.Contains(source, forbidden) {
+			t.Fatalf("main must not expose web administration: found %q", forbidden)
+		}
+	}
+	if !strings.Contains(source, "DingTalk credentials are required") {
+		t.Fatal("main must fail closed when DingTalk credentials are absent")
+	}
+}

cmd/dobotai/outbound_images.go

@@ -0,0 +1,93 @@
+package main
+
+import (
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/channels/dingtalk"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/outboundimage"
+)
+
+const (
+	outboundImageMaxCount = 5
+	outboundImageMaxBytes = 10 << 20
+	outboundImagePrefix   = "dobotai/im-images"
+	outboundImageRoute    = "/dingtalk/i/"
+)
+
+type outboundImageConfig struct {
+	WeKnoraBaseURL  string
+	WeKnoraAPIKey   string
+	Endpoint        string
+	Region          string
+	AccessKeyID     string
+	AccessKeySecret string
+	Bucket          string
+	PublicBaseURL   string
+}
+
+type outboundImageRuntime struct {
+	rewriter  dingtalk.OutboundContentRewriter
+	publisher *outboundimage.StableHashPublisher
+	handler   http.Handler
+}
+
+func buildOutboundImageRuntime(cfg outboundImageConfig) (outboundImageRuntime, error) {
+	ossValues := []string{cfg.Endpoint, cfg.Region, cfg.AccessKeyID, cfg.AccessKeySecret, cfg.Bucket, cfg.PublicBaseURL}
+	enabled := false
+	for _, value := range ossValues {
+		if strings.TrimSpace(value) != "" {
+			enabled = true
+			break
+		}
+	}
+	if !enabled {
+		return outboundImageRuntime{}, nil
+	}
+	for _, value := range append([]string{cfg.WeKnoraBaseURL, cfg.WeKnoraAPIKey}, ossValues...) {
+		if strings.TrimSpace(value) == "" {
+			return outboundImageRuntime{}, errors.New("outbound image: complete WeKnora, OSS, and public URL configuration is required")
+		}
+	}
+	transport := http.DefaultTransport.(*http.Transport).Clone()
+	transport.Proxy = nil
+	fetcher, err := outboundimage.NewWeKnoraFetcher(
+		cfg.WeKnoraBaseURL,
+		cfg.WeKnoraAPIKey,
+		&http.Client{Timeout: 30 * time.Second, Transport: transport},
+		outboundImageMaxBytes,
+	)
+	if err != nil {
+		return outboundImageRuntime{}, err
+	}
+	store, err := outboundimage.NewAliyunOSSStore(
+		cfg.Endpoint,
+		cfg.Region,
+		cfg.AccessKeyID,
+		cfg.AccessKeySecret,
+		cfg.Bucket,
+	)
+	if err != nil {
+		return outboundImageRuntime{}, err
+	}
+	publisher, err := outboundimage.NewStableHashPublisher(store, outboundImagePrefix, cfg.PublicBaseURL)
+	if err != nil {
+		return outboundImageRuntime{}, err
+	}
+	handler, err := outboundimage.NewStableImageHandler(store, outboundImagePrefix, outboundImageRoute, outboundImageMaxBytes)
+	if err != nil {
+		return outboundImageRuntime{}, err
+	}
+	return outboundImageRuntime{
+		rewriter:  outboundimage.NewRewriter(fetcher, publisher, outboundImageMaxCount),
+		publisher: publisher,
+		handler:   handler,
+	}, nil
+}
+
+func buildOutboundImageRewriter(cfg outboundImageConfig) (dingtalk.OutboundContentRewriter, error) {
+	runtime, err := buildOutboundImageRuntime(cfg)
+	return runtime.rewriter, err
+}

cmd/dobotai/question_table_sync.go

@@ -0,0 +1,164 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log"
+	"os"
+	"reflect"
+	"strings"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/channels/dingtalk"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/questiontable"
+)
+
+// questionTablePollerRunner is the interface expected by the poller loop.
+type questionTablePollerRunner interface {
+	RunOnce(context.Context) (questiontable.DispatcherStats, error)
+}
+
+// questionTableConfig holds the optional Notable question-table env values.
+type questionTableConfig struct {
+	BaseID       string
+	SheetID      string
+	OperatorID   string
+	FieldMapping map[string]string
+}
+
+// readQuestionTableConfig reads the three dedicated env vars and returns
+// a validated config. All three blank => disabled (no error). Any partial
+// configuration => stable configuration error (no values echoed).
+func readQuestionTableConfig() (questionTableConfig, error) {
+	cfg := questionTableConfig{
+		BaseID:     strings.TrimSpace(os.Getenv("DINGTALK_QUESTION_TABLE_BASE_ID")),
+		SheetID:    strings.TrimSpace(os.Getenv("DINGTALK_QUESTION_TABLE_SHEET_ID")),
+		OperatorID: strings.TrimSpace(os.Getenv("DINGTALK_QUESTION_TABLE_OPERATOR_ID")),
+	}
+
+	allBlank := cfg.BaseID == "" && cfg.SheetID == "" && cfg.OperatorID == ""
+	allSet := cfg.BaseID != "" && cfg.SheetID != "" && cfg.OperatorID != ""
+
+	if allBlank {
+		return questionTableConfig{}, nil
+	}
+	if allSet {
+		return cfg, nil
+	}
+	return questionTableConfig{}, errors.New("DingTalk question table config: all three env vars must be set or all blank (DINGTALK_QUESTION_TABLE_BASE_ID, DINGTALK_QUESTION_TABLE_SHEET_ID, DINGTALK_QUESTION_TABLE_OPERATOR_ID)")
+}
+
+// buildQuestionTableDispatcher creates a validated question-table dispatcher
+// when the repo is non-nil and all required credentials are present.
+// The optional answer rewriter converts the stored answer into the same
+// outbound form used for DingTalk delivery (resource images to stable HTTPS,
+// document links, anchor cleanup). No HTTP request occurs at build time.
+// It returns (nil, nil) when the question-table feature is disabled.
+func buildQuestionTableDispatcher(repo questiontable.ExportRepository, clientID, clientSecret string, cfg questionTableConfig, rewriter questiontable.AnswerRewriter) (*questiontable.Dispatcher, error) {
+	// Disabled: all blank config.
+	if cfg.BaseID == "" && cfg.SheetID == "" && cfg.OperatorID == "" {
+		return nil, nil
+	}
+
+	if repo == nil {
+		return nil, errors.New("question table dispatcher: repository is required")
+	}
+
+	client, err := questiontable.NewClient(questiontable.Config{
+		ClientID:     clientID,
+		Secret:       clientSecret,
+		BaseID:       cfg.BaseID,
+		SheetID:      cfg.SheetID,
+		OperatorID:   cfg.OperatorID,
+		FieldMapping: cfg.FieldMapping,
+	}, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	return questiontable.NewDispatcher(repo, client, &questiontable.DispatcherOptions{
+		Rewriter:    rewriter,
+		SendTimeout: 60 * time.Second,
+	})
+}
+
+// answerRewriterAdapter adapts a blocking outbound content rewriter to the
+// AnswerRewriter contract (caller never gets an error, so the original answer
+// is always written when conversion cannot run).
+type answerRewriterAdapter struct {
+	rewriter dingtalk.OutboundContentRewriter
+}
+
+func (a answerRewriterAdapter) Rewrite(ctx context.Context, content string) (string, error) {
+	if a.rewriter == nil {
+		return content, nil
+	}
+	return a.rewriter.Rewrite(ctx, content), nil
+}
+
+// runQuestionTablePoller runs the dispatcher immediately, then every interval.
+// Non-positive interval or nil/typed-nil runner returns without calling.
+// Continues after a RunOnce error. Exits promptly on context cancellation.
+// Logging is safe: success may log only Claimed/Exported/Failed integers;
+// errors log stable stage text only, never raw errors.
+func runQuestionTablePoller(ctx context.Context, runner questionTablePollerRunner, interval time.Duration) {
+	if runner == nil || interval <= 0 {
+		return
+	}
+
+	// Guard against typed nil.
+	if isNilPoller(runner) {
+		return
+	}
+
+	runOnce := func() {
+		runCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
+		stats, err := runner.RunOnce(runCtx)
+		cancel()
+		if err != nil {
+			log.Printf("question table dispatch failed")
+			return
+		}
+		if stats.Claimed > 0 || stats.Exported > 0 || stats.Failed > 0 {
+			log.Printf("question table dispatch: claimed=%d exported=%d failed=%d", stats.Claimed, stats.Exported, stats.Failed)
+		}
+	}
+
+	if ctx.Err() != nil {
+		return
+	}
+	runOnce()
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			runOnce()
+		}
+	}
+}
+
+// isNilPoller returns true when runner is a typed nil.
+func isNilPoller(runner questionTablePollerRunner) bool {
+	if runner == nil {
+		return true
+	}
+	// reflect-based typed-nil check for the interface.
+	return isInterfaceNil(runner)
+}
+
+// isInterfaceNil returns true when v is a typed nil wrapped in an interface.
+func isInterfaceNil(v interface{}) bool {
+	if v == nil {
+		return true
+	}
+	rv := reflect.ValueOf(v)
+	switch rv.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Ptr, reflect.Slice:
+		return rv.IsNil()
+	default:
+		return false
+	}
+}

cmd/dobotai/question_table_sync_test.go

@@ -0,0 +1,377 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log"
+	"os"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/questiontable"
+)
+
+// ---------------------------------------------------------------------------
+// Test 1: disabled all blank returns nil/no error
+// ---------------------------------------------------------------------------
+
+func TestReadQuestionTableConfigDisabledAllBlank(t *testing.T) {
+	t.Setenv("DINGTALK_QUESTION_TABLE_BASE_ID", "")
+	t.Setenv("DINGTALK_QUESTION_TABLE_SHEET_ID", "")
+	t.Setenv("DINGTALK_QUESTION_TABLE_OPERATOR_ID", "")
+
+	cfg, err := readQuestionTableConfig()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if cfg.BaseID != "" || cfg.SheetID != "" || cfg.OperatorID != "" {
+		t.Errorf("expected empty config, got %+v", cfg)
+	}
+}
+
+func TestBuildQuestionTableDispatcherDisabled(t *testing.T) {
+	d, err := buildQuestionTableDispatcher(nil, "", "", questionTableConfig{}, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if d != nil {
+		t.Errorf("expected nil dispatcher for disabled config, got %v", d)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 2: every partial combination errors and does not echo sentinel config values
+// ---------------------------------------------------------------------------
+
+func TestReadQuestionTableConfigPartialErrors(t *testing.T) {
+	tests := []struct {
+		name     string
+		baseID   string
+		sheetID  string
+		operator string
+	}{
+		{"only base", "base-1", "", ""},
+		{"only sheet", "", "sheet-1", ""},
+		{"only operator", "", "", "op-1"},
+		{"base+sheet", "base-1", "sheet-1", ""},
+		{"base+operator", "base-1", "", "op-1"},
+		{"sheet+operator", "", "sheet-1", "op-1"},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Setenv("DINGTALK_QUESTION_TABLE_BASE_ID", tc.baseID)
+			t.Setenv("DINGTALK_QUESTION_TABLE_SHEET_ID", tc.sheetID)
+			t.Setenv("DINGTALK_QUESTION_TABLE_OPERATOR_ID", tc.operator)
+
+			_, err := readQuestionTableConfig()
+			if err == nil {
+				t.Fatal("expected error for partial config")
+			}
+			errStr := err.Error()
+			// Must not echo any sentinel config value.
+			for _, sentinel := range []string{"base-1", "sheet-1", "op-1"} {
+				if strings.Contains(errStr, sentinel) {
+					t.Errorf("error must not echo sentinel value %q: %q", sentinel, errStr)
+				}
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 3: enabled missing repo/client/secret fails closed; complete config builds
+// ---------------------------------------------------------------------------
+
+func TestBuildQuestionTableDispatcherEnabledMissingRepo(t *testing.T) {
+	cfg := questionTableConfig{BaseID: "b1", SheetID: "sh1", OperatorID: "op1"}
+	_, err := buildQuestionTableDispatcher(nil, "cid", "secret", cfg, nil)
+	if err == nil {
+		t.Fatal("expected error when repo is nil")
+	}
+	if !strings.Contains(err.Error(), "repository is required") {
+		t.Errorf("error = %v, want 'repository is required'", err)
+	}
+}
+
+func TestBuildQuestionTableDispatcherEnabledMissingClientID(t *testing.T) {
+	repo := &questionTableExportRepoStub{}
+	cfg := questionTableConfig{BaseID: "b1", SheetID: "sh1", OperatorID: "op1"}
+	_, err := buildQuestionTableDispatcher(repo, "", "secret", cfg, nil)
+	if err == nil {
+		t.Fatal("expected error when client id is empty")
+	}
+}
+
+func TestBuildQuestionTableDispatcherEnabledMissingSecret(t *testing.T) {
+	repo := &questionTableExportRepoStub{}
+	cfg := questionTableConfig{BaseID: "b1", SheetID: "sh1", OperatorID: "op1"}
+	_, err := buildQuestionTableDispatcher(repo, "cid", "", cfg, nil)
+	if err == nil {
+		t.Fatal("expected error when secret is empty")
+	}
+}
+
+func TestBuildQuestionTableDispatcherEnabledCompleteConfig(t *testing.T) {
+	repo := &questionTableExportRepoStub{}
+	cfg := questionTableConfig{BaseID: "b1", SheetID: "sh1", OperatorID: "op1"}
+	d, err := buildQuestionTableDispatcher(repo, "cid", "secret", cfg, nil)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if d == nil {
+		t.Fatal("expected non-nil dispatcher for complete config")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 4: immediate run + periodic repeat + cancel stop
+// ---------------------------------------------------------------------------
+
+func TestRunQuestionTablePollerImmediateAndPeriodic(t *testing.T) {
+	runner := &countingPollerRunner{}
+	ctx, cancel := context.WithCancel(context.Background())
+
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		runQuestionTablePoller(ctx, runner, 50*time.Millisecond)
+	}()
+
+	// Wait for at least 2 calls (immediate + one tick).
+	time.Sleep(120 * time.Millisecond)
+	cancel()
+	wg.Wait()
+
+	runner.mu.Lock()
+	calls := runner.calls
+	runner.mu.Unlock()
+
+	if calls < 2 {
+		t.Errorf("expected at least 2 calls, got %d", calls)
+	}
+}
+
+func TestRunQuestionTablePollerCancelledContext(t *testing.T) {
+	runner := &countingPollerRunner{}
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // already cancelled
+
+	runQuestionTablePoller(ctx, runner, 50*time.Millisecond)
+
+	runner.mu.Lock()
+	calls := runner.calls
+	runner.mu.Unlock()
+
+	if calls != 0 {
+		t.Errorf("expected 0 calls (cancelled context), got %d", calls)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test 5: continue after error and log/output security contract
+// ---------------------------------------------------------------------------
+
+func TestRunQuestionTablePollerContinuesAfterError(t *testing.T) {
+	runner := &errorThenSuccessPoller{}
+	ctx, cancel := context.WithCancel(context.Background())
+
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		runQuestionTablePoller(ctx, runner, 30*time.Millisecond)
+	}()
+
+	time.Sleep(120 * time.Millisecond)
+	cancel()
+	wg.Wait()
+
+	runner.mu.Lock()
+	calls := runner.calls
+	runner.mu.Unlock()
+
+	if calls < 2 {
+		t.Errorf("expected at least 2 calls after error, got %d", calls)
+	}
+}
+
+// Test logging contract: the runOnce function in runQuestionTablePoller logs
+// only stable stage text for errors (never raw errors via %v) and only
+// Claimed/Exported/Failed integers for success.
+func TestPollerLoggingContract(t *testing.T) {
+	// Behavioral log-capture test: runner returns an error containing unique
+	// sentinel values; the captured log must contain the stable stage text
+	// and none of those sentinels.
+	sentinel := "s3nt1n3l-op3r4t0r-t0k3n-q"
+	runner := &sentinelErrorPoller{errMsg: "questiontable dispatcher: " + sentinel}
+	ctx, cancel := context.WithCancel(context.Background())
+
+	// Save and restore global log output.
+	originalOutput := log.Writer()
+	originalFlags := log.Flags()
+	var buf strings.Builder
+	log.SetOutput(&buf)
+	log.SetFlags(0)
+	defer func() {
+		log.SetOutput(originalOutput)
+		log.SetFlags(originalFlags)
+	}()
+
+	var wg sync.WaitGroup
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		runQuestionTablePoller(ctx, runner, 50*time.Millisecond)
+	}()
+
+	time.Sleep(120 * time.Millisecond)
+	cancel()
+	wg.Wait()
+
+	output := buf.String()
+	if !strings.Contains(output, "question table dispatch failed") {
+		t.Errorf("log must contain stable stage text, got: %s", output)
+	}
+	if strings.Contains(output, sentinel) {
+		t.Errorf("log must not contain sentinel %q, got: %s", sentinel, output)
+	}
+}
+
+// sentinelErrorPoller always returns an error with the given message.
+type sentinelErrorPoller struct {
+	errMsg string
+}
+
+func (r *sentinelErrorPoller) RunOnce(ctx context.Context) (questiontable.DispatcherStats, error) {
+	return questiontable.DispatcherStats{}, errors.New(r.errMsg)
+}
+
+// ---------------------------------------------------------------------------
+// Test 6: nil/typed-nil runner and nonpositive interval safe
+// ---------------------------------------------------------------------------
+
+func TestRunQuestionTablePollerNilRunner(t *testing.T) {
+	ctx := context.Background()
+	// Should not panic, just return immediately.
+	runQuestionTablePoller(ctx, nil, 50*time.Millisecond)
+	// If we reach here without panic, test passes.
+}
+
+func TestRunQuestionTablePollerNonPositiveInterval(t *testing.T) {
+	runner := &countingPollerRunner{}
+	ctx := context.Background()
+	runQuestionTablePoller(ctx, runner, 0)
+	runQuestionTablePoller(ctx, runner, -1*time.Second)
+
+	runner.mu.Lock()
+	calls := runner.calls
+	runner.mu.Unlock()
+
+	if calls != 0 {
+		t.Errorf("expected 0 calls for non-positive interval, got %d", calls)
+	}
+}
+
+func TestRunQuestionTablePollerTypedNilInterface(t *testing.T) {
+	// The runner is nil through the interface but not at the concrete type level.
+	var typedNil *questiontable.Dispatcher = nil
+	var runner questionTablePollerRunner = typedNil
+	ctx := context.Background()
+	// Should not panic, just return immediately.
+	runQuestionTablePoller(ctx, runner, 50*time.Millisecond)
+}
+
+// ---------------------------------------------------------------------------
+// Test 7: main source wiring contract
+// ---------------------------------------------------------------------------
+
+func TestMainWiresQuestionTableEnvNames(t *testing.T) {
+	mainData, err := os.ReadFile("main.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	syncData, err := os.ReadFile("question_table_sync.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	mainSource := string(mainData)
+	syncSource := string(syncData)
+
+	for _, fragment := range []string{
+		`"DINGTALK_QUESTION_TABLE_BASE_ID"`,
+		`"DINGTALK_QUESTION_TABLE_SHEET_ID"`,
+		`"DINGTALK_QUESTION_TABLE_OPERATOR_ID"`,
+	} {
+		if !strings.Contains(syncSource, fragment) {
+			t.Errorf("question table config reader missing %q", fragment)
+		}
+	}
+
+	for _, fragment := range []string{
+		`NewQuestionTableExportRepository`,
+		`5*time.Second`,
+		`"DingTalk question table dispatcher started"`,
+	} {
+		if !strings.Contains(mainSource, fragment) {
+			t.Errorf("main wiring missing %q", fragment)
+		}
+	}
+
+	shutdownAt := strings.Index(mainSource, "server.Shutdown(shutdownCtx)")
+	waitAt := strings.Index(mainSource, "case <-questionTableDone:")
+	if shutdownAt < 0 || waitAt < 0 || waitAt <= shutdownAt {
+		t.Fatal("main must wait for question table poller after HTTP shutdown and before returning")
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Test doubles
+// ---------------------------------------------------------------------------
+
+// questionTableExportRepoStub implements questiontable.ExportRepository.
+type questionTableExportRepoStub struct{}
+
+func (r *questionTableExportRepoStub) Claim(ctx context.Context, limit int, maxAttempts int, staleBefore time.Time) ([]questiontable.PendingExport, error) {
+	return nil, nil
+}
+func (r *questionTableExportRepoStub) MarkExported(ctx context.Context, exportID, location string) error {
+	return nil
+}
+func (r *questionTableExportRepoStub) MarkFailed(ctx context.Context, exportID, failureCode string) error {
+	return nil
+}
+
+// countingPollerRunner counts calls to RunOnce.
+type countingPollerRunner struct {
+	mu    sync.Mutex
+	calls int
+}
+
+func (r *countingPollerRunner) RunOnce(ctx context.Context) (questiontable.DispatcherStats, error) {
+	r.mu.Lock()
+	r.calls++
+	r.mu.Unlock()
+	return questiontable.DispatcherStats{}, nil
+}
+
+// errorThenSuccessPoller returns an error on the first call, then succeeds.
+type errorThenSuccessPoller struct {
+	mu    sync.Mutex
+	calls int
+}
+
+func (r *errorThenSuccessPoller) RunOnce(ctx context.Context) (questiontable.DispatcherStats, error) {
+	r.mu.Lock()
+	r.calls++
+	call := r.calls
+	r.mu.Unlock()
+
+	if call == 1 {
+		return questiontable.DispatcherStats{}, errors.New("questiontable dispatcher: claim failed")
+	}
+	return questiontable.DispatcherStats{Claimed: 1, Exported: 1}, nil
+}

cmd/dobotai/reasoning_wiring.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"context"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/channels/dingtalk"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/reasoningmode"
+)
+
+type dingTalkReasoningRouter struct {
+	service *reasoningmode.Service
+}
+
+func (r *dingTalkReasoningRouter) Prepare(ctx context.Context, message dingtalk.ReasoningMessage) (dingtalk.ReasoningDecision, error) {
+	decision, err := r.service.Prepare(ctx, reasoningmode.Scope{
+		TenantKey: message.TenantKey, Channel: message.Channel, ExternalActorID: message.StaffID,
+	}, message.Text)
+	if err != nil {
+		return dingtalk.ReasoningDecision{}, err
+	}
+	return dingtalk.ReasoningDecision{
+		Handled: decision.Handled, Reply: decision.Reply, Query: decision.Query,
+		AgentID: decision.AgentID, Execution: decision.Execution, Expired: decision.Expired,
+	}, nil
+}

cmd/dobotai/reasoning_wiring_test.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestMainWiresReasoningModeRoutingAndCompletion(t *testing.T) {
+	mainSource, err := os.ReadFile("main.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	wiringSource, err := os.ReadFile("reasoning_wiring.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	mainText := string(mainSource)
+	for _, required := range []string{
+		`os.Getenv("DOBOTAI_QUICK_AGENT_ID")`,
+		`os.Getenv("DOBOTAI_REASONING_AGENT_ID")`,
+		`reasoningmode.NewService`,
+		`qa.WithReasoningModeFinalizer`,
+		`ReasoningRouter:`,
+	} {
+		if !strings.Contains(mainText, required) {
+			t.Errorf("main reasoning wiring missing %q", required)
+		}
+	}
+	for _, required := range []string{
+		"dingTalkReasoningRouter",
+		"ReasoningMessage",
+		"service.Prepare",
+	} {
+		if !strings.Contains(string(wiringSource), required) {
+			t.Errorf("reasoning adapter missing %q", required)
+		}
+	}
+}

cmd/dobotai/settings_binding_validator.go

@@ -0,0 +1,133 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/channels/dingtalk"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/questiontable"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/settings"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/store/postgres"
+)
+
+type validatedSettingsRepository struct {
+	*postgres.SettingsRepository
+	clientID      string
+	secret        string
+	testSupport   func(context.Context, settings.ResourceBinding) error
+	validateTable func(context.Context, settings.ResourceBinding) (map[string]string, error)
+	saveBinding   func(context.Context, settings.ResourceBinding) error
+	restart       func()
+	restartDelay  time.Duration
+}
+
+func (r *validatedSettingsRepository) TestAndActivateSupportGroup(ctx context.Context, binding settings.ResourceBinding) error {
+	if r.testSupport != nil {
+		if err := r.testSupport(ctx, binding); err != nil {
+			return errors.New("support_group_test_failed")
+		}
+	} else {
+		sender, err := dingtalk.NewSupportGroupSender(r.clientID, r.secret, binding.ConversationID, nil)
+		if err != nil {
+			return errors.New("support_group_test_invalid_config")
+		}
+		if err = sender.SendTest(ctx); err != nil {
+			return errors.New("support_group_test_failed")
+		}
+	}
+	binding.ValidationCode = "support_test_ok"
+	binding.Activate = true
+	var err error
+	if r.saveBinding != nil {
+		err = r.saveBinding(ctx, binding)
+	} else if r.SettingsRepository != nil {
+		err = r.SettingsRepository.SaveBinding(ctx, binding)
+	} else {
+		err = errors.New("support_group_binding_repository_unavailable")
+	}
+	if err != nil {
+		return err
+	}
+	if r.restart != nil {
+		go func() {
+			if r.restartDelay > 0 {
+				time.Sleep(r.restartDelay)
+			}
+			r.restart()
+		}()
+	}
+	return nil
+}
+
+func (r *validatedSettingsRepository) SaveBinding(ctx context.Context, binding settings.ResourceBinding) error {
+	activate := false
+	switch binding.Kind {
+	case "question_table", "faq_table":
+		var mapping map[string]string
+		var err error
+		if r.validateTable != nil {
+			mapping, err = r.validateTable(ctx, binding)
+		} else {
+			mapping, err = r.readAndMapTable(ctx, binding)
+		}
+		if err != nil {
+			return err
+		}
+		binding.FieldMapping = mapping
+		binding.ValidationCode = "schema_ok"
+		binding.Activate = true
+		activate = true
+	case "support_group":
+		binding.ValidationCode = "pending_test_message"
+		binding.Activate = false
+	default:
+		return errors.New("unsupported_binding_kind")
+	}
+	var err error
+	if r.saveBinding != nil {
+		err = r.saveBinding(ctx, binding)
+	} else if r.SettingsRepository != nil {
+		err = r.SettingsRepository.SaveBinding(ctx, binding)
+	} else {
+		err = errors.New("binding_repository_unavailable")
+	}
+	if err != nil {
+		return err
+	}
+	if activate {
+		r.requestRestart()
+	}
+	return nil
+}
+
+func (r *validatedSettingsRepository) readAndMapTable(ctx context.Context, binding settings.ResourceBinding) (map[string]string, error) {
+	client, err := questiontable.NewClient(questiontable.Config{
+		ClientID: r.clientID, Secret: r.secret, BaseID: binding.BaseID,
+		SheetID: binding.SheetID, OperatorID: binding.OperatorID,
+	}, nil)
+	if err != nil {
+		return nil, errors.New("table_binding_invalid_config")
+	}
+	fields, err := client.ReadFields(ctx)
+	if err != nil {
+		return nil, err
+	}
+	required := questiontable.QuestionSchema()
+	if binding.Kind == "faq_table" {
+		required = questiontable.FAQSchema()
+	}
+	return questiontable.MapRequiredFields(fields, required)
+}
+
+func (r *validatedSettingsRepository) requestRestart() {
+	if r.restart == nil {
+		return
+	}
+	go func() {
+		if r.restartDelay > 0 {
+			time.Sleep(r.restartDelay)
+		}
+		r.restart()
+	}()
+}

cmd/dobotai/settings_binding_validator_test.go

@@ -0,0 +1,117 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/settings"
+)
+
+func TestTableBindingRestartsOnlyAfterActiveSave(t *testing.T) {
+	restarted := make(chan struct{}, 1)
+	var saved settings.ResourceBinding
+	repo := &validatedSettingsRepository{
+		validateTable: func(_ context.Context, binding settings.ResourceBinding) (map[string]string, error) {
+			return map[string]string{"answer": "field-answer"}, nil
+		},
+		saveBinding: func(_ context.Context, binding settings.ResourceBinding) error {
+			saved = binding
+			return nil
+		},
+		restart:      func() { restarted <- struct{}{} },
+		restartDelay: 0,
+	}
+	if err := repo.SaveBinding(context.Background(), settings.ResourceBinding{Kind: "question_table", TenantKey: "tenant", BaseID: "base", SheetID: "sheet", OperatorID: "operator"}); err != nil {
+		t.Fatal(err)
+	}
+	if !saved.Activate || saved.ValidationCode != "schema_ok" || saved.FieldMapping["answer"] != "field-answer" {
+		t.Fatalf("binding=%+v", saved)
+	}
+	select {
+	case <-restarted:
+	case <-time.After(50 * time.Millisecond):
+		t.Fatal("restart not requested")
+	}
+}
+
+func TestTableBindingDoesNotRestartOnValidationOrSaveFailure(t *testing.T) {
+	for _, tc := range []struct {
+		name        string
+		validateErr error
+		saveErr     error
+	}{
+		{name: "validation failure", validateErr: errors.New("schema failed")},
+		{name: "save failure", saveErr: errors.New("save failed")},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			restarted := make(chan struct{}, 1)
+			repo := &validatedSettingsRepository{
+				validateTable: func(context.Context, settings.ResourceBinding) (map[string]string, error) {
+					return map[string]string{"answer": "field"}, tc.validateErr
+				},
+				saveBinding: func(context.Context, settings.ResourceBinding) error { return tc.saveErr },
+				restart:     func() { restarted <- struct{}{} },
+			}
+			if err := repo.SaveBinding(context.Background(), settings.ResourceBinding{Kind: "question_table"}); err == nil {
+				t.Fatal("expected failure")
+			}
+			select {
+			case <-restarted:
+				t.Fatal("must not restart after failed activation")
+			case <-time.After(50 * time.Millisecond):
+			}
+		})
+	}
+}
+
+func TestSupportGroupActivationRestartsOnlyAfterTestAndSaveSucceed(t *testing.T) {
+	for _, tc := range []struct {
+		name        string
+		testErr     error
+		saveErr     error
+		wantSaved   bool
+		wantRestart bool
+	}{
+		{name: "test fails", testErr: errors.New("send failed")},
+		{name: "save fails", saveErr: errors.New("save failed"), wantSaved: true},
+		{name: "success", wantSaved: true, wantRestart: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var saved settings.ResourceBinding
+			restarted := make(chan struct{}, 1)
+			repo := &validatedSettingsRepository{
+				testSupport: func(context.Context, settings.ResourceBinding) error { return tc.testErr },
+				saveBinding: func(_ context.Context, binding settings.ResourceBinding) error {
+					saved = binding
+					return tc.saveErr
+				},
+				restart:      func() { restarted <- struct{}{} },
+				restartDelay: 0,
+			}
+			err := repo.TestAndActivateSupportGroup(context.Background(), settings.ResourceBinding{
+				Kind: "support_group", TenantKey: "tenant", ConversationID: "group",
+			})
+			if (err != nil) != (tc.testErr != nil || tc.saveErr != nil) {
+				t.Fatalf("err=%v", err)
+			}
+			if got := saved.Kind != ""; got != tc.wantSaved {
+				t.Fatalf("saved=%v want=%v", got, tc.wantSaved)
+			}
+			if tc.wantSaved && (saved.ValidationCode != "support_test_ok" || !saved.Activate) {
+				t.Fatalf("binding=%+v", saved)
+			}
+			select {
+			case <-restarted:
+				if !tc.wantRestart {
+					t.Fatal("unexpected restart")
+				}
+			case <-time.After(50 * time.Millisecond):
+				if tc.wantRestart {
+					t.Fatal("restart not requested")
+				}
+			}
+		})
+	}
+}

cmd/dobotai/settings_wiring.go

@@ -0,0 +1,86 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/channels/dingtalk"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/secretstore"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/settings"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/store/postgres"
+)
+
+type dingTalkSettingsRouter struct{ controller *settings.Controller }
+
+func (r *dingTalkSettingsRouter) Handle(ctx context.Context, m dingtalk.SettingsMessage) (bool, string, error) {
+	if r == nil || r.controller == nil {
+		return false, "", nil
+	}
+	if !r.controller.ShouldHandle(ctx, m.TenantKey, m.StaffID, m.Text) {
+		return false, "", nil
+	}
+	out, err := r.controller.Handle(ctx, settings.SettingInput{TenantKey: m.TenantKey, Channel: m.Channel, StaffID: m.StaffID, UnionID: m.UnionID, DisplayName: m.DisplayName, Department: m.Department, Text: m.Text, ConversationType: m.ConversationType, ConversationID: m.ConversationID, ConversationTitle: m.ConversationTitle})
+	return true, strings.TrimSpace(out), err
+}
+
+type settingsRuntime struct {
+	repository *postgres.SettingsRepository
+	bindings   *validatedSettingsRepository
+	controller *settings.Controller
+	clientID   string
+	secret     string
+	secretRef  string
+}
+
+func buildSettingsRuntime(ctx context.Context, store *postgres.Store, tenantKey string) (*settingsRuntime, error) {
+	tenantKey = strings.TrimSpace(tenantKey)
+	if tenantKey == "" {
+		return nil, errors.New("DOBOTAI_TENANT_KEY is required")
+	}
+	repo, err := postgres.NewSettingsRepository(store)
+	if err != nil {
+		return nil, err
+	}
+	root := strings.TrimSpace(os.Getenv("DOBOTAI_SECRET_DIR"))
+	if root == "" {
+		home, homeErr := os.UserHomeDir()
+		if homeErr != nil {
+			return nil, homeErr
+		}
+		root = filepath.Join(home, ".config", "dobotai", "secrets")
+	}
+	secrets, err := secretstore.New(root)
+	if err != nil {
+		return nil, err
+	}
+	if _, err := repo.PrepareDingTalkRuntimeStart(ctx, tenantKey); err != nil {
+		return nil, err
+	}
+	clientID, secretRef, _, err := repo.ActiveDingTalkConfig(ctx, tenantKey)
+	if err != nil {
+		return nil, err
+	}
+	var secret string
+	if secretRef != "" {
+		secret, err = secrets.Get(secretRef)
+		if err != nil {
+			return nil, errors.New("active DingTalk secret is unavailable")
+		}
+	}
+	if clientID == "" && strings.TrimSpace(os.Getenv("DINGTALK_CLIENT_ID")) != "" && strings.TrimSpace(os.Getenv("DINGTALK_CLIENT_SECRET")) != "" {
+		clientID, secret = strings.TrimSpace(os.Getenv("DINGTALK_CLIENT_ID")), strings.TrimSpace(os.Getenv("DINGTALK_CLIENT_SECRET"))
+		secretRef, err = secrets.Put("dingtalk", secret)
+		if err != nil {
+			return nil, err
+		}
+		if err = repo.SaveDingTalkConfig(ctx, tenantKey, clientID, secretRef, true); err != nil {
+			_ = secrets.Delete(secretRef)
+			return nil, err
+		}
+	}
+	validatedRepo := &validatedSettingsRepository{SettingsRepository: repo, clientID: clientID, secret: secret}
+	return &settingsRuntime{repository: repo, bindings: validatedRepo, controller: settings.NewController(validatedRepo), clientID: clientID, secret: secret, secretRef: secretRef}, nil
+}

cmd/dobotai/support_notifications.go

@@ -0,0 +1,67 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"log"
+	"strings"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/channels/dingtalk"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/coverage"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/faqtable"
+)
+
+type supportDispatcherRunner interface {
+	RunOnce(context.Context) (coverage.DispatcherStats, error)
+}
+
+func buildSupportDispatcher(repo coverage.NotificationRepository, clientID, clientSecret, openConversationID string, recordLinks *faqtable.RecordLinkBuilder) (*coverage.Dispatcher, error) {
+	openConversationID = strings.TrimSpace(openConversationID)
+	if openConversationID == "" {
+		return nil, nil
+	}
+	if repo == nil {
+		return nil, errors.New("support notification repository is required")
+	}
+	if recordLinks == nil {
+		return nil, nil
+	}
+
+	sender, err := dingtalk.NewSupportGroupSender(clientID, clientSecret, openConversationID, nil, dingtalk.WithFAQRecordLinkBuilder(recordLinks))
+	if err != nil {
+		return nil, err
+	}
+	return coverage.NewDispatcher(repo, sender)
+}
+
+func runSupportDispatcher(ctx context.Context, dispatcher supportDispatcherRunner, interval time.Duration) {
+	if dispatcher == nil || interval <= 0 {
+		return
+	}
+
+	runOnce := func() {
+		runCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
+		stats, err := dispatcher.RunOnce(runCtx)
+		cancel()
+		if err != nil {
+			log.Printf("support notification dispatch failed: %v", err)
+			return
+		}
+		if stats.Claimed > 0 {
+			log.Printf("support notification dispatch: claimed=%d notified=%d failed=%d", stats.Claimed, stats.Notified, stats.Failed)
+		}
+	}
+
+	runOnce()
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			runOnce()
+		}
+	}
+}

cmd/dobotai/support_notifications_test.go

@@ -0,0 +1,179 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"os"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/coverage"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/faqtable"
+)
+
+type supportNotificationRepoStub struct{}
+
+func (*supportNotificationRepoStub) Claim(context.Context, int, int, time.Time) ([]coverage.PendingSupportCase, error) {
+	return nil, nil
+}
+func (*supportNotificationRepoStub) MarkNotified(context.Context, string) error       { return nil }
+func (*supportNotificationRepoStub) MarkFailed(context.Context, string, string) error { return nil }
+
+func testFAQRecordLinks(t *testing.T) *faqtable.RecordLinkBuilder {
+	t.Helper()
+	builder, err := faqtable.NewRecordLinkBuilder("base", "sheet", "view")
+	if err != nil {
+		t.Fatal(err)
+	}
+	return builder
+}
+
+type supportDispatcherStub struct {
+	mu     sync.Mutex
+	calls  int
+	errs   []error
+	callCh chan int
+}
+
+func (s *supportDispatcherStub) RunOnce(context.Context) (coverage.DispatcherStats, error) {
+	s.mu.Lock()
+	s.calls++
+	call := s.calls
+	var err error
+	if call <= len(s.errs) {
+		err = s.errs[call-1]
+	}
+	s.mu.Unlock()
+	if s.callCh != nil {
+		select {
+		case s.callCh <- call:
+		default:
+		}
+	}
+	return coverage.DispatcherStats{Claimed: 1, Notified: 1}, err
+}
+
+func TestBuildSupportDispatcherDisabledWithoutGroup(t *testing.T) {
+	dispatcher, err := buildSupportDispatcher(nil, "", "", "  ", nil)
+	if err != nil || dispatcher != nil {
+		t.Fatalf("dispatcher=%v err=%v, want disabled", dispatcher, err)
+	}
+}
+
+func TestBuildSupportDispatcherBlocksWithoutFAQLinks(t *testing.T) {
+	dispatcher, err := buildSupportDispatcher(&supportNotificationRepoStub{}, "client", "secret", "group", nil)
+	if err != nil || dispatcher != nil {
+		t.Fatalf("dispatcher=%v err=%v, want blocked without process failure", dispatcher, err)
+	}
+}
+
+func TestBuildSupportDispatcherEnabledFailsClosed(t *testing.T) {
+	repo := &supportNotificationRepoStub{}
+	links := testFAQRecordLinks(t)
+	for _, tc := range []struct {
+		name                  string
+		repo                  coverage.NotificationRepository
+		clientID, secret, gid string
+		links                 *faqtable.RecordLinkBuilder
+	}{
+		{name: "missing repo", clientID: "client", secret: "secret", gid: "group", links: links},
+		{name: "missing client", repo: repo, secret: "secret", gid: "group", links: links},
+		{name: "missing secret", repo: repo, clientID: "client", gid: "group", links: links},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if _, err := buildSupportDispatcher(tc.repo, tc.clientID, tc.secret, tc.gid, tc.links); err == nil {
+				t.Fatal("expected configuration error")
+			}
+		})
+	}
+}
+
+func TestBuildSupportDispatcherValidDoesNotSend(t *testing.T) {
+	dispatcher, err := buildSupportDispatcher(&supportNotificationRepoStub{}, " client ", " secret ", " group ", testFAQRecordLinks(t))
+	if err != nil {
+		t.Fatalf("buildSupportDispatcher: %v", err)
+	}
+	if dispatcher == nil {
+		t.Fatal("expected dispatcher")
+	}
+}
+
+func TestRunSupportDispatcherRunsImmediatelyAndStops(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	stub := &supportDispatcherStub{callCh: make(chan int, 4)}
+	done := make(chan struct{})
+	go func() {
+		runSupportDispatcher(ctx, stub, time.Hour)
+		close(done)
+	}()
+
+	select {
+	case <-stub.callCh:
+	case <-time.After(500 * time.Millisecond):
+		t.Fatal("dispatcher did not run immediately")
+	}
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(500 * time.Millisecond):
+		t.Fatal("dispatcher did not stop after context cancellation")
+	}
+}
+
+func TestRunSupportDispatcherContinuesAfterError(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	stub := &supportDispatcherStub{
+		errs:   []error{errors.New("temporary db error")},
+		callCh: make(chan int, 4),
+	}
+	done := make(chan struct{})
+	go func() {
+		runSupportDispatcher(ctx, stub, 10*time.Millisecond)
+		close(done)
+	}()
+
+	for want := 1; want <= 2; want++ {
+		select {
+		case got := <-stub.callCh:
+			if got != want {
+				t.Fatalf("call=%d, want %d", got, want)
+			}
+		case <-time.After(500 * time.Millisecond):
+			t.Fatalf("missing dispatcher call %d", want)
+		}
+	}
+	cancel()
+	<-done
+}
+
+func TestRunSupportDispatcherRejectsNonPositiveInterval(t *testing.T) {
+	stub := &supportDispatcherStub{}
+	runSupportDispatcher(context.Background(), stub, 0)
+	stub.mu.Lock()
+	defer stub.mu.Unlock()
+	if stub.calls != 0 {
+		t.Fatalf("calls=%d, want 0", stub.calls)
+	}
+}
+
+func TestMainWiresCoverageSupportNotifications(t *testing.T) {
+	data, err := os.ReadFile("main.go")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := string(data)
+	for _, fragment := range []string{
+		`os.Getenv("DINGTALK_SUPPORT_GROUP_OPEN_CONVERSATION_ID")`,
+		`coverage.NewService(store)`,
+		`qa.WithSucceededTurnObserver`,
+		`case <-runtimeReady:`,
+		`runSupportDispatcher(ctx, supportDispatcher, 5*time.Second)`,
+	} {
+		if !strings.Contains(source, fragment) {
+			t.Errorf("main support notification wiring missing %q", fragment)
+		}
+	}
+}

db/migrations/000007_coverage_decisions.down.sql

@@ -0,0 +1,5 @@
+-- 000007_coverage_decisions down migration
+-- Drop support_cases first (child table), then coverage_decisions (parent table).
+
+DROP TABLE IF EXISTS support_cases;
+DROP TABLE IF EXISTS coverage_decisions;

db/migrations/000007_coverage_decisions.up.sql

@@ -0,0 +1,49 @@
+-- 000007_coverage_decisions up migration
+-- Creates coverage_decisions and support_cases tables for B3.1 persistence.
+
+CREATE TABLE IF NOT EXISTS coverage_decisions (
+    id                TEXT PRIMARY KEY,
+    tenant_key        TEXT NOT NULL,
+    channel           TEXT NOT NULL,
+    turn_id           TEXT NOT NULL REFERENCES turns(id),
+    evaluator_version TEXT NOT NULL DEFAULT 'v1',
+    verdict           TEXT NOT NULL CHECK (verdict IN ('covered', 'uncovered')),
+    reason_code       TEXT NOT NULL CHECK (reason_code IN (
+        'covered_has_references',
+        'uncovered_no_references',
+        'uncovered_explicit_no_answer'
+    )),
+    reference_count   INTEGER NOT NULL DEFAULT 0 CHECK (reference_count >= 0),
+    top_score         DOUBLE PRECISION NOT NULL DEFAULT 0,
+    created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (tenant_key, channel, turn_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_coverage_decisions_tenant_channel
+    ON coverage_decisions (tenant_key, channel, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_coverage_decisions_verdict
+    ON coverage_decisions (verdict) WHERE verdict = 'uncovered';
+
+CREATE TABLE IF NOT EXISTS support_cases (
+    id                           TEXT PRIMARY KEY,
+    tenant_key                   TEXT NOT NULL,
+    channel                      TEXT NOT NULL,
+    turn_id                      TEXT NOT NULL REFERENCES turns(id),
+    coverage_decision_id         TEXT NOT NULL REFERENCES coverage_decisions(id),
+    status                       TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'notifying', 'notification_failed', 'notified', 'resolved')),
+    notification_attempts        INTEGER NOT NULL DEFAULT 0 CHECK (notification_attempts >= 0),
+    last_notification_failure_code TEXT NOT NULL DEFAULT '',
+    last_notification_at         TIMESTAMPTZ,
+    notified_at                  TIMESTAMPTZ,
+    created_at                   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at                   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (tenant_key, channel, turn_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_support_cases_notification_pending
+    ON support_cases (status, created_at, id) WHERE status IN ('pending', 'notification_failed');
+
+CREATE INDEX IF NOT EXISTS idx_support_cases_notifying_stale
+    ON support_cases (status, last_notification_at) WHERE status = 'notifying';

db/migrations/000007_coverage_decisions_contract_test.go

@@ -0,0 +1,179 @@
+// Package migrations_test contains source-level contract tests for the
+// 000007_coverage_decisions migration. No real database connection is used.
+package migrations_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func read007Migration(t *testing.T, direction string) string {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join(".", "000007_coverage_decisions."+direction+".sql"))
+	if err != nil {
+		t.Fatalf("read 000007 %s migration: %v", direction, err)
+	}
+	return string(data)
+}
+
+func TestUp007CreatesCoverageDecisionsTable(t *testing.T) {
+	up := strings.ToUpper(read007Migration(t, "up"))
+	required := []string{
+		"CREATE TABLE IF NOT EXISTS COVERAGE_DECISIONS",
+		"ID", "TENANT_KEY", "CHANNEL", "TURN_ID",
+		"EVALUATOR_VERSION", "VERDICT", "REASON_CODE", "REFERENCE_COUNT", "TOP_SCORE",
+		"CREATED_AT", "UPDATED_AT",
+	}
+	for _, fragment := range required {
+		if !strings.Contains(up, fragment) {
+			t.Errorf("up migration missing %q", fragment)
+		}
+	}
+}
+
+func TestUp007CoverageDecisionsConstraints(t *testing.T) {
+	up := strings.ToUpper(read007Migration(t, "up"))
+	// REFERENCES turns(id)
+	if !strings.Contains(up, "REFERENCES TURNS(ID)") {
+		t.Error("coverage_decisions.turn_id must reference turns(id)")
+	}
+	// UNIQUE (tenant_key, channel, turn_id)
+	if !strings.Contains(up, "UNIQUE (TENANT_KEY, CHANNEL, TURN_ID)") {
+		t.Error("coverage_decisions must have UNIQUE (tenant_key, channel, turn_id)")
+	}
+	// verdict CHECK
+	if !strings.Contains(up, "COVERED") || !strings.Contains(up, "UNCOVERED") {
+		t.Error("verdict CHECK must include 'covered' and 'uncovered'")
+	}
+	// reason_code CHECK
+	for _, code := range []string{"COVERED_HAS_REFERENCES", "UNCOVERED_NO_REFERENCES", "UNCOVERED_EXPLICIT_NO_ANSWER"} {
+		if !strings.Contains(up, code) {
+			t.Errorf("reason_code CHECK missing %q", code)
+		}
+	}
+}
+
+func TestUp007CreatesSupportCasesTable(t *testing.T) {
+	up := strings.ToUpper(read007Migration(t, "up"))
+	required := []string{
+		"CREATE TABLE IF NOT EXISTS SUPPORT_CASES",
+		"ID", "TENANT_KEY", "CHANNEL", "TURN_ID",
+		"COVERAGE_DECISION_ID", "STATUS", "CREATED_AT", "UPDATED_AT",
+	}
+	for _, fragment := range required {
+		if !strings.Contains(up, fragment) {
+			t.Errorf("up migration missing %q", fragment)
+		}
+	}
+	// Notification fields must be present
+	notificationFields := []string{
+		"NOTIFICATION_ATTEMPTS", "LAST_NOTIFICATION_FAILURE_CODE",
+		"LAST_NOTIFICATION_AT", "NOTIFIED_AT",
+	}
+	for _, fragment := range notificationFields {
+		if !strings.Contains(up, fragment) {
+			t.Errorf("up migration missing notification field %q", fragment)
+		}
+	}
+}
+
+func TestUp007SupportCasesConstraints(t *testing.T) {
+	up := strings.ToUpper(read007Migration(t, "up"))
+	// FK to coverage_decisions
+	if !strings.Contains(up, "REFERENCES COVERAGE_DECISIONS(ID)") {
+		t.Error("support_cases.coverage_decision_id must reference coverage_decisions(id)")
+	}
+	// FK to turns
+	if !strings.Contains(up, "REFERENCES TURNS(ID)") {
+		t.Error("support_cases.turn_id must reference turns(id)")
+	}
+	// UNIQUE (tenant_key, channel, turn_id)
+	if !strings.Contains(up, "UNIQUE (TENANT_KEY, CHANNEL, TURN_ID)") {
+		t.Error("support_cases must have UNIQUE (tenant_key, channel, turn_id)")
+	}
+	// status CHECK
+	for _, status := range []string{"PENDING", "NOTIFYING", "NOTIFICATION_FAILED", "NOTIFIED", "RESOLVED"} {
+		if !strings.Contains(up, status) {
+			t.Errorf("status CHECK must include %q", status)
+		}
+	}
+}
+
+func TestUp007CreatesQueryIndexes(t *testing.T) {
+	up := strings.ToUpper(read007Migration(t, "up"))
+	// Pending/retry query index and stale notifying index
+	if !strings.Contains(up, "IDX_SUPPORT_CASES_NOTIFICATION_PENDING") ||
+		!strings.Contains(up, "WHERE STATUS IN ('PENDING', 'NOTIFICATION_FAILED')") {
+		t.Error("up migration must index pending and notification_failed support_cases")
+	}
+	if !strings.Contains(up, "IDX_SUPPORT_CASES_NOTIFYING_STALE") ||
+		!strings.Contains(up, "WHERE STATUS = 'NOTIFYING'") {
+		t.Error("up migration must index stale notifying support_cases")
+	}
+	// Coverage decisions listing index
+	if !strings.Contains(up, "IDX_COVERAGE_DECISIONS_TENANT_CHANNEL") {
+		t.Error("up migration must create index on coverage_decisions (tenant_key, channel, created_at DESC)")
+	}
+	// Uncovered verdict index
+	if !strings.Contains(up, "WHERE VERDICT = 'UNCOVERED'") {
+		t.Error("up migration must create partial index on uncovered coverage_decisions")
+	}
+}
+
+func TestUp007CoverageNoReservedWords(t *testing.T) {
+	up := read007Migration(t, "up")
+	// Check for bare "references" as column name in CREATE TABLE statements
+	lines := strings.Split(up, "\n")
+	for _, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		upperLine := strings.ToUpper(trimmed)
+		if strings.HasPrefix(upperLine, "REFERENCES ") && !strings.Contains(upperLine, "REFERENCES TURNS") && !strings.Contains(upperLine, "REFERENCES COVERAGE") {
+			t.Errorf("reserved word 'references' used as column name in: %s", trimmed)
+		}
+	}
+}
+
+func TestUp007NoForbiddenOperations(t *testing.T) {
+	up := strings.ToUpper(read007Migration(t, "up"))
+	for _, forbidden := range []string{
+		"DROP TABLE", "DROP COLUMN", "TRUNCATE", "DELETE FROM",
+		"ALTER TABLE", "RAW_PAYLOAD", "SESSIONWEBHOOK", "TOKEN",
+		"RAW_RESPONSE", "RAW_ERROR",
+	} {
+		if strings.Contains(up, forbidden) {
+			t.Errorf("up migration contains forbidden operation %q", forbidden)
+		}
+	}
+}
+
+func TestUp007NoQuestionAnswerBodies(t *testing.T) {
+	up := strings.ToUpper(read007Migration(t, "up"))
+	for _, forbidden := range []string{"QUESTION", "ANSWER_TEXT", "REFERENCE_CONTENT", "ANSWER_CONTENT"} {
+		if strings.Contains(up, forbidden) {
+			t.Errorf("coverage/support tables must not duplicate question/answer/reference bodies: found %q", forbidden)
+		}
+	}
+}
+
+func TestDown007DropsInSafeOrder(t *testing.T) {
+	down := strings.ToUpper(read007Migration(t, "down"))
+	supportAt := strings.Index(down, "DROP TABLE IF EXISTS SUPPORT_CASES")
+	coverageAt := strings.Index(down, "DROP TABLE IF EXISTS COVERAGE_DECISIONS")
+	if supportAt < 0 || coverageAt < 0 {
+		t.Fatal("down migration must drop both tables")
+	}
+	if supportAt > coverageAt {
+		t.Fatal("down migration must drop support_cases (child) before coverage_decisions (parent)")
+	}
+}
+
+func TestDown007DoesNotDropBaselineTables(t *testing.T) {
+	down := strings.ToUpper(read007Migration(t, "down"))
+	for _, table := range []string{"TURNS", "MESSAGES", "SESSION_MAPPINGS", "CHANNEL_ACTORS", "CHANNEL_CONVERSATIONS"} {
+		if strings.Contains(down, "DROP TABLE IF EXISTS "+table) {
+			t.Errorf("down migration must not drop baseline table %q", table)
+		}
+	}
+}

db/migrations/000008_session_display_title.down.sql

@@ -0,0 +1,2 @@
+ALTER TABLE session_mappings
+    DROP COLUMN IF EXISTS display_title;

db/migrations/000008_session_display_title.up.sql

@@ -0,0 +1,2 @@
+ALTER TABLE session_mappings
+    ADD COLUMN IF NOT EXISTS display_title TEXT NOT NULL DEFAULT '';

db/migrations/000008_session_display_title_test.go

@@ -0,0 +1,28 @@
+package migrations
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestSessionDisplayTitleMigration(t *testing.T) {
+	up, err := os.ReadFile(filepath.Join("000008_session_display_title.up.sql"))
+	if err != nil {
+		t.Fatalf("read up migration: %v", err)
+	}
+	down, err := os.ReadFile(filepath.Join("000008_session_display_title.down.sql"))
+	if err != nil {
+		t.Fatalf("read down migration: %v", err)
+	}
+	upper := strings.ToUpper(string(up))
+	for _, required := range []string{"ALTER TABLE SESSION_MAPPINGS", "ADD COLUMN IF NOT EXISTS DISPLAY_TITLE", "TEXT NOT NULL", "DEFAULT ''"} {
+		if !strings.Contains(upper, required) {
+			t.Errorf("up migration missing %q", required)
+		}
+	}
+	if !strings.Contains(strings.ToUpper(string(down)), "DROP COLUMN IF EXISTS DISPLAY_TITLE") {
+		t.Error("down migration must drop display_title")
+	}
+}

db/migrations/000009_directory_profiles.down.sql

@@ -0,0 +1,7 @@
+ALTER TABLE messages
+    DROP COLUMN IF EXISTS region_snapshot;
+
+ALTER TABLE messages
+    DROP COLUMN IF EXISTS department_snapshot;
+
+DROP TABLE IF EXISTS directory_profiles;

db/migrations/000009_directory_profiles.up.sql

@@ -0,0 +1,26 @@
+CREATE TABLE IF NOT EXISTS directory_profiles (
+    tenant_key TEXT NOT NULL,
+    staff_id TEXT NOT NULL,
+    union_id TEXT NOT NULL DEFAULT '',
+    name TEXT NOT NULL,
+    nickname TEXT NOT NULL DEFAULT '',
+    job_title TEXT NOT NULL DEFAULT '',
+    department_ids JSONB NOT NULL DEFAULT '[]'::JSONB,
+    department_name TEXT NOT NULL DEFAULT '',
+    main_department_name TEXT NOT NULL DEFAULT '',
+    region TEXT NOT NULL DEFAULT '',
+    employment_status TEXT NOT NULL DEFAULT '',
+    source TEXT NOT NULL CHECK (source IN ('full_sync','on_demand')),
+    synced_at TIMESTAMPTZ NOT NULL,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (tenant_key, staff_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_directory_profiles_tenant_name
+    ON directory_profiles (tenant_key, name);
+
+ALTER TABLE messages
+    ADD COLUMN IF NOT EXISTS department_snapshot TEXT NOT NULL DEFAULT '';
+
+ALTER TABLE messages
+    ADD COLUMN IF NOT EXISTS region_snapshot TEXT NOT NULL DEFAULT '';

db/migrations/000009_directory_profiles_test.go

@@ -0,0 +1,42 @@
+package migrations
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestDirectoryProfilesMigration(t *testing.T) {
+	up, err := os.ReadFile(filepath.Join("000009_directory_profiles.up.sql"))
+	if err != nil {
+		t.Fatalf("read up migration: %v", err)
+	}
+	down, err := os.ReadFile(filepath.Join("000009_directory_profiles.down.sql"))
+	if err != nil {
+		t.Fatalf("read down migration: %v", err)
+	}
+	upper := strings.ToUpper(string(up))
+	for _, required := range []string{
+		"CREATE TABLE IF NOT EXISTS DIRECTORY_PROFILES",
+		"PRIMARY KEY (TENANT_KEY, STAFF_ID)",
+		"DEPARTMENT_IDS JSONB",
+		"REGION TEXT",
+		"SOURCE TEXT",
+		"ADD COLUMN IF NOT EXISTS DEPARTMENT_SNAPSHOT",
+		"ADD COLUMN IF NOT EXISTS REGION_SNAPSHOT",
+	} {
+		if !strings.Contains(upper, required) {
+			t.Errorf("up migration missing %q", required)
+		}
+	}
+	for _, forbidden := range []string{"MOBILE", "EMAIL", "CLIENT_SECRET", "ACCESS_TOKEN", "RAW_PAYLOAD"} {
+		if strings.Contains(upper, forbidden) {
+			t.Errorf("up migration contains forbidden sensitive field %q", forbidden)
+		}
+	}
+	downUpper := strings.ToUpper(string(down))
+	if !strings.Contains(downUpper, "DROP TABLE IF EXISTS DIRECTORY_PROFILES") || !strings.Contains(downUpper, "DROP COLUMN IF EXISTS REGION_SNAPSHOT") {
+		t.Error("down migration must remove directory table and snapshot columns")
+	}
+}

db/migrations/000010_question_table_exports.down.sql

@@ -0,0 +1,9 @@
+-- 000010_question_table_exports down migration
+-- Drop in reverse dependency order: first drop export table, then remove column
+
+DROP TABLE IF EXISTS question_table_exports;
+
+ALTER TABLE messages
+    DROP COLUMN IF EXISTS trigger_person_snapshot;
+ALTER TABLE messages
+    DROP COLUMN IF EXISTS actor_union_id_snapshot;

db/migrations/000010_question_table_exports.up.sql

@@ -0,0 +1,40 @@
+-- 000010_question_table_exports: durable outbox for Notable question table async sync
+-- Add trigger_person_snapshot and actor_union_id_snapshot to messages and create question_table_exports table
+
+-- 1. Add trigger_person_snapshot and actor_union_id_snapshot columns to messages
+ALTER TABLE messages
+    ADD COLUMN IF NOT EXISTS trigger_person_snapshot TEXT NOT NULL DEFAULT '';
+ALTER TABLE messages
+    ADD COLUMN IF NOT EXISTS actor_union_id_snapshot TEXT NOT NULL DEFAULT '';
+
+-- 2. Create question_table_exports outbox table
+CREATE TABLE IF NOT EXISTS question_table_exports (
+    id TEXT PRIMARY KEY,
+    tenant_key TEXT NOT NULL,
+    channel TEXT NOT NULL,
+    turn_id TEXT NOT NULL REFERENCES turns(id),
+    status TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending', 'exporting', 'exported', 'export_failed')),
+    attempts INTEGER NOT NULL DEFAULT 0,
+    last_attempt_at TIMESTAMPTZ,
+    next_attempt_at TIMESTAMPTZ,
+    exported_at TIMESTAMPTZ,
+    failure_code TEXT NOT NULL DEFAULT '',
+    external_record_id TEXT NOT NULL DEFAULT '',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (tenant_key, channel, turn_id)
+);
+
+-- 3. Index for claim query: pending/export_failed/exporting ordered by created_at
+--    Covers pending, export_failed (when next_attempt_at is NULL or <= NOW()),
+--    and stale exporting (when last_attempt_at < staleBefore).
+CREATE INDEX IF NOT EXISTS idx_question_table_exports_claim
+    ON question_table_exports (status, next_attempt_at, created_at, id)
+    WHERE status IN ('pending', 'export_failed')
+       OR (status = 'exporting' AND last_attempt_at IS NOT NULL);
+
+-- 4. Index for stale exporting recovery
+CREATE INDEX IF NOT EXISTS idx_question_table_exports_stale
+    ON question_table_exports (status, last_attempt_at)
+    WHERE status = 'exporting';

db/migrations/000010_question_table_exports_contract_test.go

@@ -0,0 +1,161 @@
+// Package migrations_test contains source-level contract tests for the
+// 000010_question_table_exports migration. No real database connection is used.
+package migrations_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func read010Migration(t *testing.T, direction string) string {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join(".", "000010_question_table_exports."+direction+".sql"))
+	if err != nil {
+		t.Fatalf("read 000010 %s migration: %v", direction, err)
+	}
+	return string(data)
+}
+
+func TestUp010AddsTriggerPersonSnapshot(t *testing.T) {
+	up := strings.ToUpper(read010Migration(t, "up"))
+	if !strings.Contains(up, "ALTER TABLE MESSAGES") {
+		t.Fatal("up migration must alter messages")
+	}
+	if !strings.Contains(up, "ADD COLUMN IF NOT EXISTS TRIGGER_PERSON_SNAPSHOT") {
+		t.Error("up migration must add trigger_person_snapshot column")
+	}
+	if !strings.Contains(up, "ADD COLUMN IF NOT EXISTS ACTOR_UNION_ID_SNAPSHOT") {
+		t.Error("up migration must add actor_union_id_snapshot column")
+	}
+	if !strings.Contains(up, "TEXT NOT NULL DEFAULT ''") {
+		t.Error("snapshot columns must be TEXT NOT NULL DEFAULT ''")
+	}
+}
+
+func TestUp010CreatesQuestionTableExports(t *testing.T) {
+	up := strings.ToUpper(read010Migration(t, "up"))
+	required := []string{
+		"CREATE TABLE IF NOT EXISTS QUESTION_TABLE_EXPORTS",
+		"ID", "TENANT_KEY", "CHANNEL", "TURN_ID",
+		"STATUS", "ATTEMPTS", "LAST_ATTEMPT_AT", "NEXT_ATTEMPT_AT", "EXPORTED_AT",
+		"FAILURE_CODE", "EXTERNAL_RECORD_ID",
+		"CREATED_AT", "UPDATED_AT",
+	}
+	for _, fragment := range required {
+		if !strings.Contains(up, fragment) {
+			t.Errorf("up migration missing %q", fragment)
+		}
+	}
+}
+
+func TestUp010QuestionTableExportsConstraints(t *testing.T) {
+	up := strings.ToUpper(read010Migration(t, "up"))
+	// FK to turns
+	if !strings.Contains(up, "REFERENCES TURNS(ID)") {
+		t.Error("question_table_exports.turn_id must reference turns(id)")
+	}
+	// UNIQUE (tenant_key, channel, turn_id)
+	if !strings.Contains(up, "UNIQUE (TENANT_KEY, CHANNEL, TURN_ID)") {
+		t.Error("question_table_exports must have UNIQUE (tenant_key, channel, turn_id)")
+	}
+	// status CHECK
+	for _, status := range []string{"PENDING", "EXPORTING", "EXPORTED", "EXPORT_FAILED"} {
+		if !strings.Contains(up, status) {
+			t.Errorf("status CHECK must include %q", status)
+		}
+	}
+}
+
+func TestUp010ClaimIndexes(t *testing.T) {
+	up := strings.ToUpper(read010Migration(t, "up"))
+	if !strings.Contains(up, "IDX_QUESTION_TABLE_EXPORTS_CLAIM") {
+		t.Error("up migration must create claim index")
+	}
+	if !strings.Contains(up, "WHERE STATUS IN ('PENDING', 'EXPORT_FAILED')") {
+		t.Error("claim index must include pending and export_failed statuses")
+	}
+	if !strings.Contains(up, "IDX_QUESTION_TABLE_EXPORTS_STALE") {
+		t.Error("up migration must create stale exporting index")
+	}
+	if !strings.Contains(up, "WHERE STATUS = 'EXPORTING'") {
+		t.Error("stale index must filter exporting status")
+	}
+}
+
+func TestUp010HasNextAttemptAtColumn(t *testing.T) {
+	up := strings.ToUpper(read010Migration(t, "up"))
+	if !strings.Contains(up, "NEXT_ATTEMPT_AT TIMESTAMPTZ") {
+		t.Error("question_table_exports must have next_attempt_at column for retry backoff")
+	}
+}
+
+func TestUp010HasExternalRecordID(t *testing.T) {
+	up := strings.ToUpper(read010Migration(t, "up"))
+	if !strings.Contains(up, "EXTERNAL_RECORD_ID TEXT NOT NULL DEFAULT ''") {
+		t.Error("question_table_exports must have external_record_id column (not a1_notation)")
+	}
+	if strings.Contains(up, "A1_NOTATION") {
+		t.Error("question_table_exports must not have stale a1_notation column")
+	}
+}
+
+func TestUp010ClaimIndexCoversNextAttemptAt(t *testing.T) {
+	up := strings.ToUpper(read010Migration(t, "up"))
+	if !strings.Contains(up, "NEXT_ATTEMPT_AT") {
+		t.Error("claim index must cover next_attempt_at for retry backoff filtering")
+	}
+}
+
+func TestDown010DropsInSafeOrder(t *testing.T) {
+	down := strings.ToUpper(read010Migration(t, "down"))
+	dropExportAt := strings.Index(down, "DROP TABLE IF EXISTS QUESTION_TABLE_EXPORTS")
+	dropTriggerAt := strings.Index(down, "DROP COLUMN IF EXISTS TRIGGER_PERSON_SNAPSHOT")
+	dropUnionAt := strings.Index(down, "DROP COLUMN IF EXISTS ACTOR_UNION_ID_SNAPSHOT")
+	if dropExportAt < 0 || dropTriggerAt < 0 || dropUnionAt < 0 {
+		t.Fatal("down migration must drop export table and both snapshot columns")
+	}
+	if dropExportAt > dropTriggerAt || dropTriggerAt > dropUnionAt {
+		t.Fatal("down migration must drop export table before snapshot columns")
+	}
+}
+
+func TestDown010DoesNotDropBaselineTables(t *testing.T) {
+	down := strings.ToUpper(read010Migration(t, "down"))
+	for _, table := range []string{"TURNS", "MESSAGES", "SESSION_MAPPINGS", "CHANNEL_ACTORS", "CHANNEL_CONVERSATIONS"} {
+		if strings.Contains(down, "DROP TABLE IF EXISTS "+table) {
+			t.Errorf("down migration must not drop baseline table %q", table)
+		}
+	}
+}
+
+func TestUp010ExportsNoFormulaColumns(t *testing.T) {
+	up := read010Migration(t, "up")
+	// Check that the CREATE TABLE body does not contain user/AI content columns
+	lines := strings.Split(up, "\n")
+	inTable := false
+	for _, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		upper := strings.ToUpper(trimmed)
+		if strings.HasPrefix(upper, "CREATE TABLE IF NOT EXISTS QUESTION_TABLE_EXPORTS") {
+			inTable = true
+			continue
+		}
+		if inTable && trimmed == ");" {
+			inTable = false
+			continue
+		}
+		if !inTable {
+			continue
+		}
+		for _, forbidden := range []string{
+			"QUESTION", "ANSWER_TEXT", "RAW_PAYLOAD", "SESSIONWEBHOOK", "TOKEN",
+			"RAW_RESPONSE", "RAW_ERROR", "ACCESS_TOKEN", "APP_SECRET",
+		} {
+			if strings.Contains(upper, forbidden) {
+				t.Errorf("question_table_exports column must not contain %q", forbidden)
+			}
+		}
+	}
+}

db/migrations/000011_faq_exports.down.sql

@@ -0,0 +1,11 @@
+DROP INDEX IF EXISTS idx_support_cases_faq_export_stale;
+DROP INDEX IF EXISTS idx_support_cases_faq_export_claim;
+
+ALTER TABLE support_cases
+    DROP COLUMN IF EXISTS faq_record_id,
+    DROP COLUMN IF EXISTS faq_failure_code,
+    DROP COLUMN IF EXISTS faq_exported_at,
+    DROP COLUMN IF EXISTS faq_next_attempt_at,
+    DROP COLUMN IF EXISTS faq_last_attempt_at,
+    DROP COLUMN IF EXISTS faq_export_attempts,
+    DROP COLUMN IF EXISTS faq_export_status;

db/migrations/000011_faq_exports.up.sql

@@ -0,0 +1,24 @@
+-- Durable FAQ export state for uncovered support cases.
+ALTER TABLE support_cases
+    ADD COLUMN IF NOT EXISTS faq_export_status TEXT NOT NULL DEFAULT 'not_applicable'
+        CHECK (faq_export_status IN ('not_applicable', 'pending', 'exporting', 'exported', 'export_failed')),
+    ADD COLUMN IF NOT EXISTS faq_export_attempts INTEGER NOT NULL DEFAULT 0
+        CHECK (faq_export_attempts >= 0),
+    ADD COLUMN IF NOT EXISTS faq_last_attempt_at TIMESTAMPTZ,
+    ADD COLUMN IF NOT EXISTS faq_next_attempt_at TIMESTAMPTZ,
+    ADD COLUMN IF NOT EXISTS faq_exported_at TIMESTAMPTZ,
+    ADD COLUMN IF NOT EXISTS faq_failure_code TEXT NOT NULL DEFAULT '',
+    ADD COLUMN IF NOT EXISTS faq_record_id TEXT NOT NULL DEFAULT '';
+
+-- Existing cases are intentionally not backfilled. Only cases created after
+-- this migration enter the FAQ workflow automatically.
+ALTER TABLE support_cases
+    ALTER COLUMN faq_export_status SET DEFAULT 'pending';
+
+CREATE INDEX IF NOT EXISTS idx_support_cases_faq_export_claim
+    ON support_cases (faq_export_status, faq_next_attempt_at, created_at, id)
+    WHERE faq_export_status IN ('pending', 'export_failed');
+
+CREATE INDEX IF NOT EXISTS idx_support_cases_faq_export_stale
+    ON support_cases (faq_export_status, faq_last_attempt_at)
+    WHERE faq_export_status = 'exporting';

db/migrations/000011_faq_exports_contract_test.go

@@ -0,0 +1,74 @@
+package migrations_test
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func read011Migration(t *testing.T, direction string) string {
+	t.Helper()
+	data, err := os.ReadFile(filepath.Join(".", "000011_faq_exports."+direction+".sql"))
+	if err != nil {
+		t.Fatalf("read 000011 %s migration: %v", direction, err)
+	}
+	return strings.ToUpper(string(data))
+}
+
+func TestUp011AddsDurableFAQExportStateToSupportCases(t *testing.T) {
+	up := read011Migration(t, "up")
+	for _, fragment := range []string{
+		"ALTER TABLE SUPPORT_CASES",
+		"FAQ_EXPORT_STATUS", "FAQ_EXPORT_ATTEMPTS", "FAQ_LAST_ATTEMPT_AT",
+		"FAQ_NEXT_ATTEMPT_AT", "FAQ_EXPORTED_AT", "FAQ_FAILURE_CODE", "FAQ_RECORD_ID",
+		"PENDING", "EXPORTING", "EXPORTED", "EXPORT_FAILED",
+	} {
+		if !strings.Contains(up, fragment) {
+			t.Errorf("up migration missing %q", fragment)
+		}
+	}
+	for _, forbidden := range []string{"FAQ_QUESTION", "FAQ_ANSWER", "RAW_RESPONSE", "ACCESS_TOKEN"} {
+		if strings.Contains(up, forbidden) {
+			t.Errorf("migration must not duplicate business or secret field %q", forbidden)
+		}
+	}
+}
+
+func TestUp011DoesNotBackfillHistoricalSupportCases(t *testing.T) {
+	up := read011Migration(t, "up")
+	if !strings.Contains(up, "DEFAULT 'NOT_APPLICABLE'") {
+		t.Fatal("existing support cases must start as not_applicable")
+	}
+	if !strings.Contains(up, "ALTER COLUMN FAQ_EXPORT_STATUS SET DEFAULT 'PENDING'") {
+		t.Fatal("future support cases must default to pending")
+	}
+}
+
+func TestUp011AddsBoundedClaimIndexes(t *testing.T) {
+	up := read011Migration(t, "up")
+	for _, fragment := range []string{
+		"IDX_SUPPORT_CASES_FAQ_EXPORT_CLAIM",
+		"FAQ_NEXT_ATTEMPT_AT", "FAQ_LAST_ATTEMPT_AT",
+		"WHERE FAQ_EXPORT_STATUS IN ('PENDING', 'EXPORT_FAILED')",
+	} {
+		if !strings.Contains(up, fragment) {
+			t.Errorf("up migration missing claim index fragment %q", fragment)
+		}
+	}
+}
+
+func TestDown011OnlyRemovesFAQExportState(t *testing.T) {
+	down := read011Migration(t, "down")
+	for _, column := range []string{
+		"FAQ_EXPORT_STATUS", "FAQ_EXPORT_ATTEMPTS", "FAQ_LAST_ATTEMPT_AT",
+		"FAQ_NEXT_ATTEMPT_AT", "FAQ_EXPORTED_AT", "FAQ_FAILURE_CODE", "FAQ_RECORD_ID",
+	} {
+		if !strings.Contains(down, "DROP COLUMN IF EXISTS "+column) {
+			t.Errorf("down migration missing %s", column)
+		}
+	}
+	if strings.Contains(down, "DROP TABLE") {
+		t.Fatal("down migration must not drop baseline tables")
+	}
+}

db/migrations/000012_system_settings.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS config_audit_events; DROP TABLE IF EXISTS system_resource_bindings; DROP TABLE IF EXISTS administrators; DROP TABLE IF EXISTS system_config_revisions;

db/migrations/000012_system_settings.up.sql

@@ -0,0 +1,19 @@
+CREATE TABLE IF NOT EXISTS system_config_revisions (
+ id TEXT PRIMARY KEY, tenant_key TEXT NOT NULL, kind TEXT NOT NULL, revision INTEGER NOT NULL CHECK(revision>0),
+ state TEXT NOT NULL CHECK(state IN ('draft','validated','active','retired','failed')), public_config JSONB NOT NULL DEFAULT '{}'::JSONB,
+ secret_ref TEXT NOT NULL DEFAULT '', validation_status TEXT NOT NULL DEFAULT 'pending', validation_code TEXT NOT NULL DEFAULT '',
+ validated_at TIMESTAMPTZ, activated_at TIMESTAMPTZ, created_by_staff_id TEXT NOT NULL DEFAULT '', created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ UNIQUE(tenant_key,kind,revision));
+CREATE UNIQUE INDEX IF NOT EXISTS uq_system_config_active ON system_config_revisions(tenant_key,kind) WHERE state='active';
+CREATE TABLE IF NOT EXISTS administrators (
+ id TEXT PRIMARY KEY, tenant_key TEXT NOT NULL, staff_id TEXT NOT NULL, union_id TEXT NOT NULL DEFAULT '', display_name TEXT NOT NULL DEFAULT '',
+ department TEXT NOT NULL DEFAULT '', role TEXT NOT NULL CHECK(role IN ('super_admin','admin')), status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active','disabled')),
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), UNIQUE(tenant_key,staff_id));
+CREATE TABLE IF NOT EXISTS system_resource_bindings (
+ id TEXT PRIMARY KEY, tenant_key TEXT NOT NULL, kind TEXT NOT NULL, revision INTEGER NOT NULL CHECK(revision>0), state TEXT NOT NULL CHECK(state IN ('draft','validated','active','retired','failed')),
+ public_config JSONB NOT NULL DEFAULT '{}'::JSONB, validation_code TEXT NOT NULL DEFAULT '', validated_at TIMESTAMPTZ, activated_at TIMESTAMPTZ,
+ created_by_staff_id TEXT NOT NULL DEFAULT '', created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), UNIQUE(tenant_key,kind,revision));
+CREATE UNIQUE INDEX IF NOT EXISTS uq_resource_binding_active ON system_resource_bindings(tenant_key,kind) WHERE state='active';
+CREATE TABLE IF NOT EXISTS config_audit_events (
+ id TEXT PRIMARY KEY, tenant_key TEXT NOT NULL, actor_staff_id TEXT NOT NULL DEFAULT '', action TEXT NOT NULL, target_kind TEXT NOT NULL,
+ target_revision INTEGER NOT NULL DEFAULT 0, result_code TEXT NOT NULL, metadata JSONB NOT NULL DEFAULT '{}'::JSONB, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW());

db/migrations/000012_system_settings_contract_test.go

@@ -0,0 +1,25 @@
+package migrations_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestUp012CreatesSettingsWithoutSecrets(t *testing.T) {
+	b, e := os.ReadFile("000012_system_settings.up.sql")
+	if e != nil {
+		t.Fatal(e)
+	}
+	s := strings.ToUpper(string(b))
+	for _, x := range []string{"SYSTEM_CONFIG_REVISIONS", "ADMINISTRATORS", "SYSTEM_RESOURCE_BINDINGS", "CONFIG_AUDIT_EVENTS", "PUBLIC_CONFIG"} {
+		if !strings.Contains(s, x) {
+			t.Errorf("missing %s", x)
+		}
+	}
+	for _, x := range []string{"CLIENT_SECRET JSON", "ACCESS_TOKEN JSON", "API_KEY JSON"} {
+		if strings.Contains(s, x) {
+			t.Errorf("forbidden %s", x)
+		}
+	}
+}

db/migrations/000013_admin_bootstrap.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS admin_bootstrap_challenges;

db/migrations/000013_admin_bootstrap.up.sql

@@ -0,0 +1,5 @@
+CREATE TABLE IF NOT EXISTS admin_bootstrap_challenges (
+ id TEXT PRIMARY KEY, tenant_key TEXT NOT NULL, code_hash TEXT NOT NULL, expires_at TIMESTAMPTZ NOT NULL, attempts INTEGER NOT NULL DEFAULT 0 CHECK(attempts>=0), max_attempts INTEGER NOT NULL DEFAULT 5 CHECK(max_attempts BETWEEN 1 AND 10),
+ candidate_staff_id TEXT NOT NULL DEFAULT '', candidate_union_id TEXT NOT NULL DEFAULT '', candidate_display_name TEXT NOT NULL DEFAULT '', candidate_department TEXT NOT NULL DEFAULT '',
+ status TEXT NOT NULL CHECK(status IN ('pending','candidate_detected','confirmed','expired','locked')), created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW());
+CREATE UNIQUE INDEX IF NOT EXISTS uq_admin_bootstrap_pending ON admin_bootstrap_challenges(tenant_key) WHERE status IN ('pending','candidate_detected');

db/migrations/000013_admin_bootstrap_contract_test.go

@@ -0,0 +1,18 @@
+package migrations_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestUp013StoresOnlyBootstrapHash(t *testing.T) {
+	b, e := os.ReadFile("000013_admin_bootstrap.up.sql")
+	if e != nil {
+		t.Fatal(e)
+	}
+	s := strings.ToUpper(string(b))
+	if !strings.Contains(s, "CODE_HASH") || strings.Contains(s, " CODE TEXT") {
+		t.Fatal("bootstrap must store hash only")
+	}
+}

db/migrations/000014_setting_sessions.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS setting_sessions;

db/migrations/000014_setting_sessions.up.sql

@@ -0,0 +1,5 @@
+CREATE TABLE IF NOT EXISTS setting_sessions (
+ tenant_key TEXT NOT NULL, staff_id TEXT NOT NULL, conversation_id TEXT NOT NULL, conversation_type TEXT NOT NULL CHECK(conversation_type IN ('direct','group')),
+ current_step TEXT NOT NULL, pending_action TEXT NOT NULL DEFAULT '', draft_config JSONB NOT NULL DEFAULT '{}'::JSONB, expires_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ PRIMARY KEY(tenant_key,staff_id));
+CREATE INDEX IF NOT EXISTS idx_setting_sessions_expiry ON setting_sessions(expires_at);

db/migrations/000014_setting_sessions_contract_test.go

@@ -0,0 +1,20 @@
+package migrations_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestUp014CreatesExpiringSettingSessions(t *testing.T) {
+	b, e := os.ReadFile("000014_setting_sessions.up.sql")
+	if e != nil {
+		t.Fatal(e)
+	}
+	s := strings.ToUpper(string(b))
+	for _, x := range []string{"SETTING_SESSIONS", "EXPIRES_AT", "DRAFT_CONFIG"} {
+		if !strings.Contains(s, x) {
+			t.Errorf("missing %s", x)
+		}
+	}
+}

db/migrations/000015_user_preferences.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS user_preferences;

db/migrations/000015_user_preferences.up.sql

@@ -0,0 +1,3 @@
+CREATE TABLE IF NOT EXISTS user_preferences (
+ tenant_key TEXT NOT NULL, channel TEXT NOT NULL, external_actor_id TEXT NOT NULL, language_mode TEXT NOT NULL DEFAULT 'auto' CHECK(language_mode IN ('auto','fixed')),
+ locale TEXT NOT NULL DEFAULT 'auto' CHECK(locale IN ('auto','zh-CN','en','ja','ko','es')), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), PRIMARY KEY(tenant_key,channel,external_actor_id));

db/migrations/000015_user_preferences_contract_test.go

@@ -0,0 +1,20 @@
+package migrations_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestUp015ScopesPreferencesByTenantAndActor(t *testing.T) {
+	b, e := os.ReadFile("000015_user_preferences.up.sql")
+	if e != nil {
+		t.Fatal(e)
+	}
+	s := strings.ToUpper(string(b))
+	for _, x := range []string{"USER_PREFERENCES", "TENANT_KEY", "EXTERNAL_ACTOR_ID", "LANGUAGE_MODE", "LOCALE"} {
+		if !strings.Contains(s, x) {
+			t.Errorf("missing %s", x)
+		}
+	}
+}

db/migrations/000016_question_image_urls.down.sql

@@ -0,0 +1,3 @@
+-- 000016_question_image_urls down migration.
+ALTER TABLE turns
+    DROP COLUMN IF EXISTS question_image_urls_json;

db/migrations/000016_question_image_urls.up.sql

@@ -0,0 +1,6 @@
+-- 000016_question_image_urls: stable published URLs for inbound question images.
+-- Stores the object-storage HTTPS URLs of images a user sent in a question,
+-- so the question-table export can render a readable, traceable record without
+-- persisting download codes or data URIs.
+ALTER TABLE turns
+    ADD COLUMN IF NOT EXISTS question_image_urls_json JSONB NOT NULL DEFAULT '[]'::JSONB;

db/migrations/000017_knowledge_searched.down.sql

@@ -0,0 +1,3 @@
+-- 000017_knowledge_searched down migration.
+ALTER TABLE turns
+    DROP COLUMN IF EXISTS knowledge_searched;

db/migrations/000017_knowledge_searched.up.sql

@@ -0,0 +1,6 @@
+-- 000017_knowledge_searched: records whether a turn actually triggered a
+-- knowledge-base search (knowledge_search tool call). Coverage classification
+-- uses this to distinguish pure visual recognition from a searched-but-missed
+-- knowledge question.
+ALTER TABLE turns
+    ADD COLUMN IF NOT EXISTS knowledge_searched BOOLEAN NOT NULL DEFAULT FALSE;

db/migrations/000018_coverage_visual_recognition_reason.down.sql

@@ -0,0 +1,11 @@
+-- 000018_coverage_visual_recognition_reason down migration.
+ALTER TABLE coverage_decisions
+    DROP CONSTRAINT IF EXISTS coverage_decisions_reason_code_check;
+
+ALTER TABLE coverage_decisions
+    ADD CONSTRAINT coverage_decisions_reason_code_check
+    CHECK (reason_code IN (
+        'covered_has_references',
+        'uncovered_no_references',
+        'uncovered_explicit_no_answer'
+    ));

db/migrations/000018_coverage_visual_recognition_reason.up.sql

@@ -0,0 +1,14 @@
+-- 000018_coverage_visual_recognition_reason: extend the coverage_decisions
+-- reason_code allowlist with the new image-visual-recognition reason emitted by
+-- coverage Evaluator v3 (visual recognition is not a knowledge-coverage miss).
+ALTER TABLE coverage_decisions
+    DROP CONSTRAINT IF EXISTS coverage_decisions_reason_code_check;
+
+ALTER TABLE coverage_decisions
+    ADD CONSTRAINT coverage_decisions_reason_code_check
+    CHECK (reason_code IN (
+        'covered_has_references',
+        'uncovered_no_references',
+        'uncovered_explicit_no_answer',
+        'covered_visual_recognition'
+    ));

db/migrations/000019_reasoning_mode_state.down.sql

@@ -0,0 +1,3 @@
+-- 000019_reasoning_mode_state down migration.
+DROP TABLE IF EXISTS reasoning_mode_turns;
+DROP TABLE IF EXISTS reasoning_mode_states;

db/migrations/000019_reasoning_mode_state.up.sql

@@ -0,0 +1,43 @@
+-- 000019_reasoning_mode_state: actor-scoped /think state and
+-- per-turn idempotency for successful reasoning-mode completions.
+
+CREATE TABLE IF NOT EXISTS reasoning_mode_states (
+    tenant_key          TEXT NOT NULL,
+    channel             TEXT NOT NULL,
+    external_actor_id   TEXT NOT NULL,
+    mode                TEXT NOT NULL DEFAULT 'quick'
+                        CHECK (mode IN ('quick', 'reasoning')),
+    max_rounds          INTEGER NOT NULL DEFAULT 10
+                        CHECK (max_rounds BETWEEN 1 AND 50),
+    rounds_used         INTEGER NOT NULL DEFAULT 0
+                        CHECK (rounds_used >= 0 AND rounds_used <= max_rounds),
+    hint_enabled        BOOLEAN NOT NULL DEFAULT TRUE,
+    last_activity_at    TIMESTAMPTZ,
+    expires_at          TIMESTAMPTZ,
+    onboarding_shown_at TIMESTAMPTZ,
+    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (tenant_key, channel, external_actor_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_reasoning_mode_states_expiry
+    ON reasoning_mode_states (expires_at)
+    WHERE mode = 'reasoning' AND expires_at IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS reasoning_mode_turns (
+    id                   TEXT PRIMARY KEY,
+    tenant_key           TEXT NOT NULL,
+    channel              TEXT NOT NULL,
+    turn_id              TEXT NOT NULL REFERENCES turns(id),
+    external_actor_id    TEXT NOT NULL,
+    execution_mode       TEXT NOT NULL
+                         CHECK (execution_mode IN ('quick', 'reasoning', 'reasoning_single')),
+    round_number         INTEGER NOT NULL DEFAULT 0 CHECK (round_number >= 0),
+    showed_hint          BOOLEAN NOT NULL DEFAULT FALSE,
+    auto_closed          BOOLEAN NOT NULL DEFAULT FALSE,
+    showed_onboarding    BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at           TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (tenant_key, channel, turn_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_reasoning_mode_turns_actor_created
+    ON reasoning_mode_turns (tenant_key, channel, external_actor_id, created_at DESC);

db/migrations/000019_reasoning_mode_state_contract_test.go

@@ -0,0 +1,79 @@
+package migrations_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestUp019CreatesActorScopedReasoningModeState(t *testing.T) {
+	data, err := os.ReadFile("000019_reasoning_mode_state.up.sql")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := strings.ToUpper(string(data))
+	for _, required := range []string{
+		"REASONING_MODE_STATES",
+		"TENANT_KEY",
+		"CHANNEL",
+		"EXTERNAL_ACTOR_ID",
+		"MODE",
+		"MAX_ROUNDS",
+		"ROUNDS_USED",
+		"HINT_ENABLED",
+		"EXPIRES_AT",
+		"ONBOARDING_SHOWN_AT",
+		"PRIMARY KEY (TENANT_KEY, CHANNEL, EXTERNAL_ACTOR_ID)",
+		"MODE IN ('QUICK', 'REASONING')",
+		"MAX_ROUNDS BETWEEN 1 AND 50",
+	} {
+		if !strings.Contains(source, required) {
+			t.Errorf("reasoning state migration missing %q", required)
+		}
+	}
+}
+
+func TestUp019CreatesTurnIdempotencyLedger(t *testing.T) {
+	data, err := os.ReadFile("000019_reasoning_mode_state.up.sql")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := strings.ToUpper(string(data))
+	for _, required := range []string{
+		"REASONING_MODE_TURNS",
+		"TURN_ID",
+		"EXTERNAL_ACTOR_ID",
+		"EXECUTION_MODE",
+		"ROUND_NUMBER",
+		"SHOWED_HINT",
+		"AUTO_CLOSED",
+		"SHOWED_ONBOARDING",
+		"UNIQUE (TENANT_KEY, CHANNEL, TURN_ID)",
+		"REFERENCES TURNS(ID)",
+	} {
+		if !strings.Contains(source, required) {
+			t.Errorf("reasoning turn ledger migration missing %q", required)
+		}
+	}
+}
+
+func TestDown019RemovesOnlyReasoningModeObjects(t *testing.T) {
+	data, err := os.ReadFile("000019_reasoning_mode_state.down.sql")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := strings.ToUpper(string(data))
+	for _, required := range []string{
+		"DROP TABLE IF EXISTS REASONING_MODE_TURNS",
+		"DROP TABLE IF EXISTS REASONING_MODE_STATES",
+	} {
+		if !strings.Contains(source, required) {
+			t.Errorf("reasoning down migration missing %q", required)
+		}
+	}
+	for _, forbidden := range []string{"DROP TABLE TURNS", "DROP TABLE USER_PREFERENCES"} {
+		if strings.Contains(source, forbidden) {
+			t.Errorf("reasoning down migration must not contain %q", forbidden)
+		}
+	}
+}

db/migrations/000020_feedback_support_trigger.down.sql

@@ -0,0 +1,5 @@
+-- 000020_feedback_support_trigger down migration.
+DROP INDEX IF EXISTS idx_support_cases_trigger_type_created;
+ALTER TABLE support_cases
+    DROP COLUMN IF EXISTS trigger_feedback_id,
+    DROP COLUMN IF EXISTS trigger_type;

db/migrations/000020_feedback_support_trigger.up.sql

@@ -0,0 +1,11 @@
+-- 000020_feedback_support_trigger: let an existing support-case workflow be
+-- triggered by a downvote while preserving one case per successful Turn.
+
+ALTER TABLE support_cases
+    ALTER COLUMN coverage_decision_id DROP NOT NULL,
+    ADD COLUMN IF NOT EXISTS trigger_type TEXT NOT NULL DEFAULT 'coverage_uncovered'
+        CHECK (trigger_type IN ('coverage_uncovered', 'feedback_down')),
+    ADD COLUMN IF NOT EXISTS trigger_feedback_id TEXT REFERENCES answer_feedback(id);
+
+CREATE INDEX IF NOT EXISTS idx_support_cases_trigger_type_created
+    ON support_cases (trigger_type, created_at DESC);

db/migrations/000020_feedback_support_trigger_contract_test.go

@@ -0,0 +1,50 @@
+package migrations_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestUp020AddsFeedbackSupportTriggerAndMakesCoverageDecisionOptional(t *testing.T) {
+	data, err := os.ReadFile("000020_feedback_support_trigger.up.sql")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := strings.ToUpper(string(data))
+	for _, required := range []string{
+		"ALTER TABLE SUPPORT_CASES",
+		"TRIGGER_TYPE",
+		"COVERAGE_UNCOVERED",
+		"FEEDBACK_DOWN",
+		"TRIGGER_FEEDBACK_ID",
+		"REFERENCES ANSWER_FEEDBACK(ID)",
+		"ALTER COLUMN COVERAGE_DECISION_ID DROP NOT NULL",
+	} {
+		if !strings.Contains(source, required) {
+			t.Errorf("feedback support migration missing %q", required)
+		}
+	}
+	if strings.Contains(source, "DROP CONSTRAINT SUPPORT_CASES_COVERAGE_DECISION_ID_FKEY") {
+		t.Fatal("feedback support must retain the coverage decision foreign-key contract")
+	}
+}
+
+func TestDown020RemovesOnlyFeedbackSupportColumns(t *testing.T) {
+	data, err := os.ReadFile("000020_feedback_support_trigger.down.sql")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := strings.ToUpper(string(data))
+	for _, required := range []string{
+		"DROP COLUMN IF EXISTS TRIGGER_FEEDBACK_ID",
+		"DROP COLUMN IF EXISTS TRIGGER_TYPE",
+	} {
+		if !strings.Contains(source, required) {
+			t.Errorf("feedback support down migration missing %q", required)
+		}
+	}
+	if strings.Contains(source, "DROP TABLE") {
+		t.Fatal("feedback support down migration must not drop shared tables")
+	}
+}

db/migrations/000021_coverage_non_knowledge_response_reason.down.sql

@@ -0,0 +1,18 @@
+-- 000021_coverage_non_knowledge_response_reason down migration.
+-- Map the v4 covered reason to the pre-v4 covered code before restoring the
+-- legacy allowlist, so rollback remains valid with persisted v4 decisions.
+UPDATE coverage_decisions
+SET reason_code = 'covered_has_references'
+WHERE reason_code = 'covered_non_knowledge_response';
+
+ALTER TABLE coverage_decisions
+    DROP CONSTRAINT IF EXISTS coverage_decisions_reason_code_check;
+
+ALTER TABLE coverage_decisions
+    ADD CONSTRAINT coverage_decisions_reason_code_check
+    CHECK (reason_code IN (
+        'covered_has_references',
+        'uncovered_no_references',
+        'uncovered_explicit_no_answer',
+        'covered_visual_recognition'
+    ));

db/migrations/000021_coverage_non_knowledge_response_reason.up.sql

@@ -0,0 +1,14 @@
+-- 000021_coverage_non_knowledge_response_reason: distinguish text turns that
+-- did not invoke knowledge search from actual retrieval misses.
+ALTER TABLE coverage_decisions
+    DROP CONSTRAINT IF EXISTS coverage_decisions_reason_code_check;
+
+ALTER TABLE coverage_decisions
+    ADD CONSTRAINT coverage_decisions_reason_code_check
+    CHECK (reason_code IN (
+        'covered_has_references',
+        'uncovered_no_references',
+        'uncovered_explicit_no_answer',
+        'covered_visual_recognition',
+        'covered_non_knowledge_response'
+    ));

db/migrations/000021_coverage_non_knowledge_response_reason_contract_test.go

@@ -0,0 +1,44 @@
+package migrations_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestUp021AddsCoveredNonKnowledgeResponseReason(t *testing.T) {
+	data, err := os.ReadFile("000021_coverage_non_knowledge_response_reason.up.sql")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := strings.ToUpper(string(data))
+	for _, required := range []string{
+		"ALTER TABLE COVERAGE_DECISIONS",
+		"DROP CONSTRAINT IF EXISTS COVERAGE_DECISIONS_REASON_CODE_CHECK",
+		"COVERED_NON_KNOWLEDGE_RESPONSE",
+		"COVERED_VISUAL_RECOGNITION",
+	} {
+		if !strings.Contains(source, required) {
+			t.Errorf("up migration missing %q", required)
+		}
+	}
+}
+
+func TestDown021MapsNewCoveredReasonBeforeRestoringLegacyConstraint(t *testing.T) {
+	data, err := os.ReadFile("000021_coverage_non_knowledge_response_reason.down.sql")
+	if err != nil {
+		t.Fatal(err)
+	}
+	source := strings.ToUpper(string(data))
+	for _, required := range []string{
+		"UPDATE COVERAGE_DECISIONS",
+		"COVERED_NON_KNOWLEDGE_RESPONSE",
+		"COVERED_HAS_REFERENCES",
+		"ALTER TABLE COVERAGE_DECISIONS",
+		"DROP CONSTRAINT IF EXISTS COVERAGE_DECISIONS_REASON_CODE_CHECK",
+	} {
+		if !strings.Contains(source, required) {
+			t.Errorf("down migration missing %q", required)
+		}
+	}
+}

deploy/dobotai-dingtalk/README.md

@@ -0,0 +1,262 @@
+# DobotAI DingTalk Docker 部署手册
+
+> 适用范围：DobotAI 的 Docker Compose 部署。容器名固定为 `dobotai-dingtalk`，数据库容器名固定为 `dobotai-postgres`。
+>
+> 本文面向测试/预发布。生产必须使用已验收的同一镜像、独立备份和独立审批，禁止在生产重新编译。
+
+## 1. 定位
+
+DobotAI 是钉钉渠道的对话编排与交付层，不是知识库、文档解析器或模型平台。
+
+```text
+DobotAI 负责：
+钉钉 Stream、富文本/图片、会话映射、WeKnora Agent 调用、卡片交付、
+/think、/setting、覆盖判定、Support Case、反馈、渠道审计。
+
+DobotAI 不负责：
+WeKnora 文档/Chunk/向量/图谱/解析/模型；钉钉应用创建；知识库治理。
+```
+
+## 2. Docker 架构
+
+```text
+钉钉用户/群
+      │ DingTalk Stream（出站长连接）
+      ▼
+┌────────────────────────────────────────┐
+│ dobotai-dingtalk                        │
+│ 消息、会话、卡片、覆盖与支持流程        │
+│ 仅映射到宿主机 127.0.0.1:8090            │
+└───────┬──────────────────────┬───────────┘
+        │ Compose 网络          │ host.docker.internal
+        ▼                       ▼
+┌────────────────────┐   已有 WeKnora 服务
+│ dobotai-postgres   │   Agent / 检索 / 知识 / 模型
+│ dobotai 独立数据库 │
+│ 命名卷持久化       │
+└────────────────────┘
+```
+
+Compose 管理的资源：
+
+| 资源 | 名称 | 数据策略 |
+| --- | --- | --- |
+| 应用容器 | `dobotai-dingtalk` | 可重建，不保存业务数据卷 |
+| PostgreSQL容器 | `dobotai-postgres` | 可重建，数据在命名卷 |
+| PostgreSQL命名卷 | `dobotai-postgres-data` | 持久数据，禁止常规删除 |
+| Compose网络 | `dobotai-network` | 应用与数据库内部通信 |
+| 宿主机密钥目录 | `<DOBOTAI_HOME>/secrets` | bind mount，不进入Git |
+
+关键Compose属性：
+
+```yaml
+services:
+  dobotai-postgres:
+    container_name: dobotai-postgres
+    volumes:
+      - dobotai-postgres-data:/var/lib/postgresql/data
+
+  dobotai-dingtalk:
+    container_name: dobotai-dingtalk
+    depends_on:
+      dobotai-postgres:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:8090:8090"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+```
+
+应用不使用 `network_mode: host`：它以`dobotai-postgres:5432`访问Compose数据库，以`http://host.docker.internal:8080`访问宿主机的WeKnora。
+
+## 3. 自动安装准备
+
+`install-docker.sh`自动完成：
+
+```text
+检查 Docker、Docker Compose 和已导入的候选镜像
+创建 <DOBOTAI_HOME>/container、config、secrets、backups、migrations
+生成权限0600的 config/postgres.env 与 config/dobotai.env
+生成独立数据库密码、Ingress Token、Admin Token
+创建并启动 dobotai-postgres
+等待 PostgreSQL healthcheck
+按顺序应用 db/migrations/*.up.sql
+在 dobotai_schema_migrations 记录版本、名称和时间
+安装 configure / start / bind-admin 三条短命令
+```
+
+它不会：
+
+```text
+启动尚未配置的钉钉应用容器
+覆盖已有配置或数据库数据
+删除任何 Docker 卷
+输出密码、API Key、Token 或连接串
+```
+
+默认安装根目录：
+
+```text
+/opt/dobotai
+├── container/    Compose、脚本、SQL迁移、运行参数
+├── config/       dobotai.env、postgres.env（0600）
+├── secrets/      DobotAI SecretStore（0700）
+└── backups/      逻辑备份和SHA清单
+```
+
+可以用`DOBOTAI_HOME=/绝对路径`改安装位置。测试环境建议使用独立目录，例如`/opt/dobotai-test-compose`。
+
+## 4. 前置条件
+
+```text
+部署用户具有 sudo 和 Docker daemon 访问权限
+宿主机 WeKnora 已健康，容器可经 host.docker.internal:8080 访问
+```
+
+Docker与Docker Compose缺失时由根安装脚本自动安装（当前支持APT系统）。不必手工构建、导入或命名镜像。
+
+## 5. 全新安装
+
+从源码仓库克隆后，进入仓库根目录执行唯一安装入口：
+
+```bash
+sudo bash ./install-docker.sh
+```
+
+脚本内部以当前Git提交构建固定内部镜像名：
+
+```text
+dobotai-dingtalk:local-<当前Git短SHA>
+```
+
+镜像名、PostgreSQL镜像和构建元数据只由根目录`install-docker.sh`维护，用户不传`DOBOTAI_IMAGE`。脚本完成后数据库和迁移已就绪，应用尚未启动。然后执行：
+
+构建期Go依赖使用脚本内置的公开模块代理`https://goproxy.cn,direct`；它只存在于镜像构建命令，不写入DobotAI运行配置。
+
+```bash
+sudo dobotai-dingtalk-configure
+```
+
+配置器逐项显示用途和脱敏格式示例；已有值不会回显，直接回车表示保留。数据库连接串、数据库密码、Ingress Token和Admin Token由安装脚本生成，交互配置器不要求输入。
+
+主要业务连接配置：
+
+| 变量 | 用途 | 示例 |
+| --- | --- | --- |
+| `WEKNORA_BASE_URL` | Docker内访问宿主机WeKnora | `http://host.docker.internal:8080` |
+| `WEKNORA_API_KEY` | DobotAI专用WeKnora API Key | `<你的WeKnora API Key>` |
+| `DOBOTAI_TENANT_KEY` | DobotAI租户隔离键 | `dobotai` |
+| `DOBOTAI_AGENT_BINDINGS` | 渠道到WeKnora Agent映射 | `{"dingtalk:*":"你的Agent ID"}` |
+| `DINGTALK_CLIENT_ID` | 钉钉应用Client ID/AppKey | `dingxxxxxxxx` |
+| `DINGTALK_CLIENT_SECRET` | 钉钉应用Secret/AppSecret | `<你的钉钉 AppSecret>` |
+
+配置器成功后自动启动`dobotai-dingtalk`，并检查PostgreSQL健康、`http://127.0.0.1:8090/healthz`和容器运行状态。
+
+## 7. 首位管理员绑定
+
+仅在租户没有有效管理员时执行：
+
+```bash
+sudo dobotai-dingtalk-bind-admin
+```
+
+终端显示10分钟有效的一次性六码。候选管理员私聊钉钉机器人：
+
+```text
+/setting <六码绑定码>
+```
+
+终端自动确认后写入`super_admin/active`。已有管理员时命令拒绝执行，防止意外提权。
+
+## 8. 迁移现有DobotAI实例
+
+旧实例已有Turn、会话、Support Case、管理员或反馈时，不能直接新建空库后切换。先安装目标Compose基础设施，再运行：
+
+```bash
+sudo DOBOTAI_HOME=/opt/dobotai-compose \
+  SOURCE_POSTGRES_CONTAINER=dobotai-test-postgres \
+  SOURCE_APP_CONTAINER=dobotai-dingtalk \
+  SOURCE_DOBOTAI_ENV=/etc/dobotai-test/dobotai.env \
+  /opt/dobotai-compose/container/migrate-existing-database.sh
+```
+
+迁移脚本固定顺序：
+
+```text
+启动目标 dobotai-postgres 并等待健康
+→ 停止并改名旧应用容器（不删除）
+→ pg_dump -Fc 导出旧数据库
+→ pg_restore --list 验证备份可读
+→ 写入备份SHA-256
+→ 复制旧应用配置，只替换数据库、监听和WeKnora地址
+→ 恢复到 dobotai-postgres-data
+→ 应用缺失迁移
+→ 启动新 dobotai-dingtalk
+→ 健康失败则恢复旧容器名称和旧容器
+```
+
+源数据库不会删除。成功后旧应用容器会以`*-legacy-*`保留，确认稳定前不得删除旧容器或旧数据库。
+
+## 9. 数据库迁移
+
+DobotAI应用本身不扫描SQL。安装/迁移流程由：
+
+```bash
+sudo /opt/dobotai/container/apply-migrations.sh
+```
+
+执行`migrations/*.up.sql`，每个成功迁移在同一事务写入：
+
+```text
+dobotai_schema_migrations(version, name, applied_at)
+```
+
+任何数据库升级前都必须有经`pg_restore --list`验证的逻辑备份。`.down.sql`只能在审查通过后用于数据库回滚，不能用应用镜像回滚替代数据库回滚。
+
+## 10. 日常运行与升级
+
+```bash
+# 健康与版本
+curl --noproxy '*' -fsS http://127.0.0.1:8090/healthz
+curl --noproxy '*' -fsS http://127.0.0.1:8090/version
+
+# Compose状态
+sudo docker compose --env-file /opt/dobotai/container/runtime.env \
+  -f /opt/dobotai/container/compose.yaml ps
+
+# 日志：不要转发含用户内容或凭据的原始上下文
+sudo docker logs --since 10m dobotai-dingtalk
+
+# 数据库状态
+sudo docker inspect -f '{{.State.Health.Status}}|{{.RestartCount}}' dobotai-postgres
+```
+
+升级顺序：导入候选镜像 → 备份并应用必要迁移 → 更新`runtime.env`中的`DOBOTAI_IMAGE` → 执行：
+
+```bash
+sudo dobotai-dingtalk-start
+```
+
+应用健康失败时启动器恢复上一应用镜像；数据库迁移仍必须按审查过的SQL回滚流程处理。
+
+## 11. 覆盖判定边界
+
+```text
+有结构化引用                         → covered_has_references
+实际检索过但没有引用                 → uncovered_no_references → Support Case
+明确无权威知识/无答案                → uncovered_explicit_no_answer → Support Case
+图片未检索、纯视觉识别               → covered_visual_recognition
+文本未检索、闲聊/普通非知识响应      → covered_non_knowledge_response
+```
+
+因此“在吗”“你好”“谢谢”等未触发知识检索的文本不会创建Support Case或发送未覆盖提醒。
+
+## 12. 禁止操作
+
+```text
+docker compose down -v
+docker volume rm dobotai-postgres-data
+docker system prune --volumes
+把 config/*.env、secrets/、备份Dump、真实Token或凭据提交Git
+在生产重新编译或使用未经测试的镜像
+```

deploy/dobotai-dingtalk/apply-migrations.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+home="${DOBOTAI_HOME:-/opt/dobotai}"
+container_dir="$home/container"
+compose_file="$container_dir/compose.yaml"
+runtime_env="$container_dir/runtime.env"
+migrations_dir="$container_dir/migrations"
+
+if [[ ! -r "$compose_file" || ! -r "$runtime_env" || ! -d "$migrations_dir" ]]; then
+  echo "迁移运行文件未安装。请先执行 install-docker.sh。" >&2
+  exit 1
+fi
+
+compose=(docker compose --env-file "$runtime_env" -f "$compose_file")
+"${compose[@]}" up -d --no-build dobotai-postgres
+for _ in $(seq 1 30); do
+  status=$(docker inspect -f '{{.State.Health.Status}}' dobotai-postgres 2>/dev/null || true)
+  [[ "$status" == "healthy" ]] && break
+  sleep 1
+done
+[[ "${status:-}" == "healthy" ]] || { echo "PostgreSQL 未健康，拒绝迁移。" >&2; exit 1; }
+
+psql_db() {
+  "${compose[@]}" exec -T dobotai-postgres psql -v ON_ERROR_STOP=1 -U dobotai -d dobotai "$@"
+}
+
+psql_db -c 'CREATE TABLE IF NOT EXISTS dobotai_schema_migrations (version INTEGER PRIMARY KEY, name TEXT NOT NULL, applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW())'
+
+for file in "$migrations_dir"/*.up.sql; do
+  [[ -f "$file" ]] || continue
+  base="$(basename "$file")"
+  version_text="${base%%_*}"
+  version=$((10#$version_text))
+  name="${base#*_}"
+  name="${name%.up.sql}"
+  case "$name" in *[!a-z0-9_]* ) echo "非法迁移文件名：$base" >&2; exit 1;; esac
+  applied=$(psql_db -At -c "SELECT EXISTS(SELECT 1 FROM dobotai_schema_migrations WHERE version=$version)")
+  [[ "$applied" == "t" ]] && continue
+  {
+    printf 'BEGIN;\n'
+    cat "$file"
+    printf "\nINSERT INTO dobotai_schema_migrations(version,name) VALUES (%s,'%s');\nCOMMIT;\n" "$version" "$name"
+  } | "${compose[@]}" exec -T dobotai-postgres psql -v ON_ERROR_STOP=1 -U dobotai -d dobotai
+  echo "已应用迁移：$base"
+done

deploy/dobotai-dingtalk/compose.yaml

@@ -0,0 +1,56 @@
+services:
+  dobotai-postgres:
+    image: ${DOBOTAI_POSTGRES_IMAGE:-postgres:16-alpine}
+    container_name: dobotai-postgres
+    env_file:
+      - ${DOBOTAI_POSTGRES_ENV_FILE:?set DOBOTAI_POSTGRES_ENV_FILE in runtime.env}
+    volumes:
+      - dobotai-postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+    restart: unless-stopped
+    security_opt:
+      - no-new-privileges:true
+    networks:
+      - dobotai-network
+
+  dobotai-dingtalk:
+    image: ${DOBOTAI_IMAGE:?set DOBOTAI_IMAGE in runtime.env}
+    container_name: dobotai-dingtalk
+    depends_on:
+      dobotai-postgres:
+        condition: service_healthy
+    env_file:
+      - ${DOBOTAI_ENV_FILE:?set DOBOTAI_ENV_FILE in runtime.env}
+    environment:
+      DOBOTAI_SECRET_DIR: /var/lib/dobotai/secrets
+    volumes:
+      - type: bind
+        source: ${DOBOTAI_SECRET_DIR_HOST:?set DOBOTAI_SECRET_DIR_HOST in runtime.env}
+        target: /var/lib/dobotai/secrets
+        read_only: false
+    ports:
+      - "127.0.0.1:8090:8090"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    restart: unless-stopped
+    init: true
+    read_only: true
+    tmpfs:
+      - /tmp:rw,noexec,nosuid,size=32m
+    security_opt:
+      - no-new-privileges:true
+    networks:
+      - dobotai-network
+
+volumes:
+  dobotai-postgres-data:
+    name: dobotai-postgres-data
+
+networks:
+  dobotai-network:
+    name: dobotai-network
+    driver: bridge

deploy/dobotai-dingtalk/configure_env.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+import argparse
+import getpass
+import os
+from pathlib import Path
+import sys
+
+FIELDS = (
+    ("WEKNORA_BASE_URL", "WeKnora 地址", "Docker 容器访问宿主机 WeKnora 时使用 host.docker.internal。", "http://host.docker.internal:8080", False),
+    ("WEKNORA_API_KEY", "WeKnora API Key", "在 WeKnora 中为 DobotAI 创建的独立 API Key。", "<你的WeKnora API Key>", True),
+    ("DOBOTAI_INGRESS_TOKEN", "DobotAI Ingress Token", "调用 /v1/qa 时使用的独立长随机令牌。", "<随机长字符串>", True),
+    ("DOBOTAI_TENANT_KEY", "DobotAI 租户键", "同一 DobotAI 数据库内的渠道隔离键。", "dobotai", False),
+    ("DOBOTAI_AGENT_BINDINGS", "DobotAI Agent Bindings JSON", "钉钉会话匹配到 WeKnora Agent 的映射。", '{"dingtalk:*":"你的Agent ID"}', False),
+    ("DINGTALK_CLIENT_ID", "钉钉 Client ID", "钉钉应用的 Client ID/AppKey。", "dingxxxxxxxx", False),
+    ("DINGTALK_CLIENT_SECRET", "钉钉 Client Secret", "钉钉应用的 Client Secret/AppSecret。", "<你的钉钉 AppSecret>", True),
+)
+
+
+def parse_env(path: Path):
+    lines = path.read_text(encoding="utf-8").splitlines()
+    values = {}
+    for line in lines:
+        if line and not line.lstrip().startswith("#") and "=" in line:
+            key, value = line.split("=", 1)
+            values[key.strip()] = value
+    return lines, values
+
+
+def prompt(label: str, description: str, example: str, secret: bool, configured: bool) -> str:
+    suffix = "（已配置，直接回车保留）" if configured else "（必填）"
+    print(f"\n{label}\n用途：{description}\n格式示例：{example}")
+    if secret:
+        return getpass.getpass(f"{label}{suffix}: ").strip()
+    return input(f"{label}{suffix}: ").strip()
+
+
+def write_env(path: Path, lines, values):
+    rendered = []
+    written = set()
+    for line in lines:
+        if line and not line.lstrip().startswith("#") and "=" in line:
+            key = line.split("=", 1)[0].strip()
+            if key in values:
+                rendered.append(f"{key}={values[key]}")
+                written.add(key)
+                continue
+        rendered.append(line)
+    for key, value in values.items():
+        if key not in written:
+            rendered.append(f"{key}={value}")
+    temporary = path.with_name(path.name + ".new")
+    temporary.write_text("\n".join(rendered) + "\n", encoding="utf-8")
+    os.chmod(temporary, 0o600)
+    os.replace(temporary, path)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="配置 DobotAI Docker 应用连接")
+    parser.add_argument("--env-file", required=True)
+    parser.add_argument("--start-script", required=True)
+    args = parser.parse_args()
+    env_file = Path(args.env_file)
+    if not env_file.is_file():
+        raise SystemExit("DobotAI 环境文件不存在，请先完成 Docker 安装。")
+    lines, values = parse_env(env_file)
+    for key, label, description, example, secret in FIELDS:
+        entered = prompt(label, description, example, secret, bool(values.get(key, "").strip()))
+        if entered:
+            values[key] = entered
+    missing = [label for key, label, _, _, _ in FIELDS if not values.get(key, "").strip()]
+    if missing:
+        raise SystemExit("以下必填项未配置：" + "、".join(missing))
+    write_env(env_file, lines, values)
+    os.execv(args.start_script, [args.start_script])
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        sys.exit(130)

deploy/dobotai-dingtalk/dobotai-dingtalk-bind-admin

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+home="${DOBOTAI_HOME:-/opt/dobotai}"
+container_dir="$home/container"
+if [[ "$(docker inspect --format '{{.State.Running}}' dobotai-dingtalk 2>/dev/null || true)" != "true" ]]; then
+  echo "DobotAI 容器未运行。请先执行：sudo dobotai-dingtalk-configure" >&2
+  exit 1
+fi
+exec docker exec -it dobotai-dingtalk /usr/local/bin/dobotai bootstrap-admin

deploy/dobotai-dingtalk/dobotai-dingtalk-configure

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+exec python3 /opt/dobotai-test/container/configure_env.py \
+  --env-file /etc/dobotai-test/dobotai.env \
+  --start-script /usr/local/sbin/dobotai-dingtalk-start

deploy/dobotai-dingtalk/dobotai-dingtalk-start

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+home="${DOBOTAI_HOME:-/opt/dobotai}"
+container_dir="$home/container"
+compose_file="$container_dir/compose.yaml"
+runtime_env="$container_dir/runtime.env"
+health_url="http://127.0.0.1:8090/healthz"
+
+if [[ ! -r "$compose_file" || ! -r "$runtime_env" ]]; then
+  echo "Docker 运行文件未安装。请先执行 install-docker.sh。" >&2
+  exit 1
+fi
+
+compose=(docker compose --env-file "$runtime_env" -f "$compose_file")
+previous_image="$(docker inspect --format '{{.Config.Image}}' dobotai-dingtalk 2>/dev/null || true)"
+
+set_runtime_image() {
+  local image="$1"
+  python3 - "$runtime_env" "$image" <<'PY'
+from pathlib import Path
+import os
+import sys
+path = Path(sys.argv[1])
+image = sys.argv[2]
+lines = path.read_text(encoding="utf-8").splitlines()
+rendered = ["DOBOTAI_IMAGE=" + image if line.startswith("DOBOTAI_IMAGE=") else line for line in lines]
+if not any(line.startswith("DOBOTAI_IMAGE=") for line in lines):
+    rendered.append("DOBOTAI_IMAGE=" + image)
+temporary = path.with_name(path.name + ".new")
+temporary.write_text("\n".join(rendered) + "\n", encoding="utf-8")
+os.chmod(temporary, 0o600)
+os.replace(temporary, path)
+PY
+}
+
+rollback() {
+  "${compose[@]}" rm -sf dobotai-dingtalk >/dev/null 2>&1 || true
+  if [[ -n "$previous_image" ]]; then
+    set_runtime_image "$previous_image"
+    "${compose[@]}" up -d --no-build --force-recreate dobotai-dingtalk >/dev/null 2>&1 || true
+  fi
+}
+trap rollback ERR
+
+"${compose[@]}" up -d --no-build dobotai-postgres
+"${compose[@]}" up -d --no-build --force-recreate dobotai-dingtalk
+for _ in $(seq 1 30); do
+  if curl --noproxy '*' --fail --silent --max-time 2 "$health_url" >/dev/null; then
+    trap - ERR
+    echo "DobotAI 容器已启动：dobotai-dingtalk"
+    exit 0
+  fi
+  sleep 1
+done
+
+echo "DobotAI 容器健康检查失败，已回滚到上一容器镜像（如存在）。" >&2
+exit 1

deploy/dobotai-dingtalk/install-docker.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source_root="${DOBOTAI_SOURCE_ROOT:-$(cd "$script_dir/../.." && pwd)}"
+home="${DOBOTAI_HOME:-/opt/dobotai}"
+container_dir="$home/container"
+config_dir="$home/config"
+secret_dir="$home/secrets"
+backup_dir="$home/backups"
+app_env="$config_dir/dobotai.env"
+postgres_env="$config_dir/postgres.env"
+runtime_env="$container_dir/runtime.env"
+image="${DOBOTAI_IMAGE:?set DOBOTAI_IMAGE to a reviewed DobotAI image tag}"
+postgres_image="${DOBOTAI_POSTGRES_IMAGE:-postgres:16-alpine}"
+bin_dir="${DOBOTAI_BIN_DIR:-/usr/local/sbin}"
+
+if [[ ${EUID} -ne 0 ]]; then
+  echo "请使用 sudo 执行 Docker 安装脚本。" >&2
+  exit 1
+fi
+command -v docker >/dev/null || { echo "Docker 未安装。" >&2; exit 1; }
+docker compose version >/dev/null || { echo "Docker Compose 未安装。" >&2; exit 1; }
+docker image inspect "$image" >/dev/null 2>&1 || { echo "候选应用镜像不存在：$image" >&2; exit 1; }
+
+install -d -m 0750 "$home" "$container_dir" "$config_dir" "$backup_dir"
+install -d -m 0700 -o 10001 -g 10001 "$secret_dir"
+install -d -m 0750 "$container_dir/migrations"
+install -m 0644 "$script_dir/compose.yaml" "$container_dir/compose.yaml"
+install -m 0700 "$script_dir/configure_env.py" "$container_dir/configure_env.py"
+install -m 0750 "$script_dir/dobotai-dingtalk-start" "$container_dir/dobotai-dingtalk-start"
+install -m 0750 "$script_dir/dobotai-dingtalk-bind-admin" "$container_dir/dobotai-dingtalk-bind-admin"
+install -m 0750 "$script_dir/apply-migrations.sh" "$container_dir/apply-migrations.sh"
+install -m 0750 "$script_dir/migrate-existing-database.sh" "$container_dir/migrate-existing-database.sh"
+install -m 0644 "$source_root"/db/migrations/*.up.sql "$container_dir/migrations/"
+install -m 0644 "$source_root"/db/migrations/*.down.sql "$container_dir/migrations/"
+
+if [[ ! -f "$postgres_env" || ! -f "$app_env" ]]; then
+  umask 077
+  python3 - "$postgres_env" "$app_env" <<'PY'
+from pathlib import Path
+import os
+import secrets
+import sys
+
+postgres_env = Path(sys.argv[1])
+app_env = Path(sys.argv[2])
+password = secrets.token_urlsafe(32)
+ingress = secrets.token_urlsafe(32)
+admin = secrets.token_urlsafe(32)
+postgres_env.write_text(
+    "POSTGRES_DB=dobotai\n"
+    "POSTGRES_USER=dobotai\n"
+    f"POSTGRES_PASSWORD={password}\n",
+    encoding="utf-8",
+)
+os.chmod(postgres_env, 0o600)
+app_env.write_text(
+    "DOBOTAI_LISTEN_ADDR=0.0.0.0:8090\n"
+    f"DATABASE_URL=postgres://dobotai:{password}@dobotai-postgres:5432/dobotai?sslmode=disable\n"
+    f"DOBOTAI_INGRESS_TOKEN={ingress}\n"
+    f"DOBOTAI_ADMIN_TOKEN={admin}\n"
+    "DOBOTAI_GROUP_SESSION_POLICY=shared\n"
+    "DOBOTAI_TENANT_KEY=dobotai\n"
+    "DOBOTAI_AGENT_BINDINGS=\n"
+    "DOBOTAI_QUICK_AGENT_ID=builtin-quick-answer\n"
+    "DOBOTAI_REASONING_AGENT_ID=builtin-smart-reasoning\n"
+    "WEKNORA_BASE_URL=http://host.docker.internal:8080\n"
+    "WEKNORA_API_KEY=\n"
+    "DINGTALK_CLIENT_ID=\n"
+    "DINGTALK_CLIENT_SECRET=\n",
+    encoding="utf-8",
+)
+os.chmod(app_env, 0o600)
+PY
+fi
+
+umask 077
+cat > "$runtime_env" <<EOF
+DOBOTAI_IMAGE=$image
+DOBOTAI_POSTGRES_IMAGE=$postgres_image
+DOBOTAI_ENV_FILE=$app_env
+DOBOTAI_POSTGRES_ENV_FILE=$postgres_env
+DOBOTAI_SECRET_DIR_HOST=$secret_dir
+DOBOTAI_MIGRATIONS_DIR=$container_dir/migrations
+EOF
+chmod 0600 "$runtime_env"
+
+install -d -m 0755 "$bin_dir"
+cat > "$bin_dir/dobotai-dingtalk-configure" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+export DOBOTAI_HOME='$home'
+exec python3 '$container_dir/configure_env.py' --env-file '$app_env' --start-script '$bin_dir/dobotai-dingtalk-start'
+EOF
+cat > "$bin_dir/dobotai-dingtalk-start" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+export DOBOTAI_HOME='$home'
+exec '$container_dir/dobotai-dingtalk-start'
+EOF
+cat > "$bin_dir/dobotai-dingtalk-bind-admin" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+export DOBOTAI_HOME='$home'
+exec '$container_dir/dobotai-dingtalk-bind-admin'
+EOF
+chmod 0750 "$bin_dir/dobotai-dingtalk-configure" "$bin_dir/dobotai-dingtalk-start" "$bin_dir/dobotai-dingtalk-bind-admin"
+
+compose=(docker compose --env-file "$runtime_env" -f "$container_dir/compose.yaml")
+"${compose[@]}" up -d dobotai-postgres
+for _ in $(seq 1 30); do
+  status=$(docker inspect -f '{{.State.Health.Status}}' dobotai-postgres 2>/dev/null || true)
+  [[ "$status" == "healthy" ]] && break
+  sleep 1
+done
+[[ "${status:-}" == "healthy" ]] || { echo "PostgreSQL 初始化失败。" >&2; exit 1; }
+DOBOTAI_HOME="$home" "$container_dir/apply-migrations.sh"
+
+echo "Docker 基础设施已准备完成：数据库与迁移已就绪，应用尚未启动。"
+echo "下一步执行：sudo dobotai-dingtalk-configure"

deploy/dobotai-dingtalk/install-test.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$script_dir/install-docker.sh" "$@"

deploy/dobotai-dingtalk/migrate-existing-database.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+home="${DOBOTAI_HOME:-/opt/dobotai}"
+container_dir="$home/container"
+config_dir="$home/config"
+runtime_env="$container_dir/runtime.env"
+compose_file="$container_dir/compose.yaml"
+source_container="${SOURCE_POSTGRES_CONTAINER:-dobotai-test-postgres}"
+source_app_container="${SOURCE_APP_CONTAINER:-dobotai-dingtalk}"
+source_env="${SOURCE_DOBOTAI_ENV:-/etc/dobotai-test/dobotai.env}"
+app_env="$config_dir/dobotai.env"
+backup_dir="$home/backups"
+stamp="$(date -u '+%Y%m%dT%H%M%SZ')"
+legacy_app="${source_app_container}-legacy-${stamp}"
+
+[[ ${EUID} -eq 0 ]] || { echo "请使用 sudo 执行现有数据库迁移脚本。" >&2; exit 1; }
+[[ -r "$runtime_env" && -r "$compose_file" && -r "$source_env" ]] || { echo "运行文件或旧环境文件不存在。请先执行 install-docker.sh。" >&2; exit 1; }
+docker inspect "$source_container" >/dev/null 2>&1 || { echo "源 PostgreSQL 容器不存在：$source_container" >&2; exit 1; }
+docker inspect "$source_app_container" >/dev/null 2>&1 || { echo "源 DobotAI 容器不存在：$source_app_container" >&2; exit 1; }
+
+source_pg_user=$(docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' "$source_container" | python3 -c "import sys; print(next((x.strip().split('=',1)[1] for x in sys.stdin if x.startswith('POSTGRES_USER=')), ''))")
+source_pg_db=$(docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' "$source_container" | python3 -c "import sys; print(next((x.strip().split('=',1)[1] for x in sys.stdin if x.startswith('POSTGRES_DB=')), ''))")
+test -n "$source_pg_user" && test -n "$source_pg_db"
+install -d -m 0700 "$backup_dir"
+dump="$backup_dir/pre-compose-adoption-${stamp}.dump"
+
+compose=(docker compose --env-file "$runtime_env" -f "$compose_file")
+"${compose[@]}" up -d dobotai-postgres
+for _ in $(seq 1 30); do
+  status=$(docker inspect -f '{{.State.Health.Status}}' dobotai-postgres 2>/dev/null || true)
+  [[ "$status" == "healthy" ]] && break
+  sleep 1
+done
+[[ "${status:-}" == "healthy" ]] || { echo "目标 PostgreSQL 未健康。" >&2; exit 1; }
+
+old_running=$(docker inspect -f '{{.State.Running}}' "$source_app_container")
+rollback() {
+  docker compose --env-file "$runtime_env" -f "$compose_file" rm -sf dobotai-dingtalk >/dev/null 2>&1 || true
+  if docker inspect "$legacy_app" >/dev/null 2>&1; then
+    docker rename "$legacy_app" "$source_app_container" || true
+    [[ "$old_running" == "true" ]] && docker start "$source_app_container" >/dev/null 2>&1 || true
+  fi
+}
+trap rollback ERR
+
+[[ "$old_running" == "true" ]] && docker stop "$source_app_container" >/dev/null
+docker rename "$source_app_container" "$legacy_app"
+docker exec -e PGUSER="$source_pg_user" "$source_container" pg_dump -Fc --no-owner -d "$source_pg_db" > "$dump"
+test -s "$dump"
+docker exec -i dobotai-postgres pg_restore --list < "$dump" >/dev/null
+sha256sum "$dump" > "$dump.sha256"
+
+# Replace only deployment-managed endpoints; preserve all existing application credentials.
+python3 - "$source_env" "$app_env" "$config_dir/postgres.env" <<'PY'
+from pathlib import Path
+import os
+import sys
+source, target, postgres_env = map(Path, sys.argv[1:])
+password = next(line.split('=', 1)[1].strip() for line in postgres_env.read_text().splitlines() if line.startswith('POSTGRES_PASSWORD='))
+values = {}
+for line in source.read_text().splitlines():
+    if line and not line.startswith('#') and '=' in line:
+        key, value = line.split('=', 1)
+        values[key] = value
+values['DOBOTAI_LISTEN_ADDR'] = '0.0.0.0:8090'
+values['DATABASE_URL'] = f'postgres://dobotai:{password}@dobotai-postgres:5432/dobotai?sslmode=disable'
+values['WEKNORA_BASE_URL'] = 'http://host.docker.internal:8080'
+temporary = target.with_name(target.name + '.new')
+temporary.write_text('\n'.join(f'{k}={v}' for k, v in values.items()) + '\n', encoding='utf-8')
+os.chmod(temporary, 0o600)
+os.replace(temporary, target)
+PY
+
+"${compose[@]}" exec -T dobotai-postgres psql -v ON_ERROR_STOP=1 -U dobotai -d dobotai -c 'DROP SCHEMA public CASCADE; CREATE SCHEMA public;'
+docker exec -i dobotai-postgres pg_restore -U dobotai -d dobotai --no-owner < "$dump"
+DOBOTAI_HOME="$home" "$container_dir/apply-migrations.sh"
+"${compose[@]}" up -d --no-build dobotai-dingtalk
+for _ in $(seq 1 30); do
+  if curl --noproxy '*' --fail --silent --max-time 2 http://127.0.0.1:8090/healthz >/dev/null; then
+    trap - ERR
+    echo "现有DobotAI数据库已迁移到 dobotai-postgres-data；旧应用容器保留为 $legacy_app。"
+    exit 0
+  fi
+  sleep 1
+done
+
+echo "迁移后的应用健康检查失败，正在恢复旧容器。" >&2
+exit 1

deploy/dobotai-dingtalk/runtime.env.example

@@ -0,0 +1,7 @@
+# 非敏感运行参数；由 install-docker.sh 生成实际文件。
+DOBOTAI_IMAGE=dobotai-dingtalk:test
+DOBOTAI_POSTGRES_IMAGE=postgres:16-alpine
+DOBOTAI_ENV_FILE=/opt/dobotai/config/dobotai.env
+DOBOTAI_POSTGRES_ENV_FILE=/opt/dobotai/config/postgres.env
+DOBOTAI_SECRET_DIR_HOST=/opt/dobotai/secrets
+DOBOTAI_MIGRATIONS_DIR=/opt/dobotai/container/migrations

docs/api-gaps.md

@@ -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。

docs/architecture.md

@@ -1,73 +1,98 @@
-# 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:
+首位管理员绑定由部署服务器终端发起，而非网页发码。钉钉 Stream 机器人已正常运行且当前不存在有效管理员时，操作人员执行：
 
-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.
+```bash
+dobotai bootstrap-admin
+```
 
-No WeKnora source patch is allowed as a workaround.
+命令只连接 DobotAI PostgreSQL，使用加密随机数创建一个有效期10分钟、最多5次错误尝试的六码挑战，并在终端持续等待。候选用户必须私聊机器人发送：
 
-## Service ownership
+```text
+/setting <六码绑定码>
+```
 
-- `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.
+验证码匹配后，渠道侧只记录候选身份；终端轮询并事务性将该候选用户写为 `super_admin/active`，然后显示成功并退出。已有有效管理员时该命令拒绝执行，避免任意用户通过终端绑定流程被提权。DobotAI 不提供网页管理面，钉钉凭据和运行配置由部署环境文件管理。
 
-## Upgrade contract
+## 图片失败策略
 
-For every official WeKnora upgrade:
+启用图片流量前，WeKnora Adapter 必须针对选定的官方版本和视觉模型执行契约测试。
 
-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.
+任一图片路径失败时：
+
+1. 不得去掉图片后重发同一问题；
+2. 不得将部分模型输出当作成功结果；
+3. 向渠道适配器返回类型化 `vision_unavailable` 错误；
+4. 钉钉提示用户图片识别暂不可用，并请其重试或发送文本；
+5. 发送运维告警，核查 Agent 图片上传设置、视觉模型、供应商连通性和模型能力；
+6. 契约测试通过前保持图片流量禁用。
+
+不得通过修改 WeKnora 源码规避上述失败。
+
+对钉钉 richText 中的图片，DobotAI 仅通过官方接口下载，验证来源、大小、媒体类型和文件签名后，才转换为 WeKnora 通用多模态请求。对回答中的 `resource://` 图片，仅可在鉴权获取、内容哈希转存私有 OSS 后外发；不得把任意外部 URL 当作可信图片。
+
+## 服务职责
+
+- `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：仅用于队列、重试、短期租约和临时流状态。
+
+## 升级契约
+
+每次升级官方 WeKnora 时：
+
+1. 更新固定的官方 Release/Tag；
+2. 仅对 WeKnora 执行官方数据库迁移；
+3. 执行 DobotAI Adapter 契约测试；
+4. 验证文本 Agent Chat、引用、终止错误、停止、图片、导入和 FAQ；
+5. 仅在契约测试通过后推广官方镜像。
+
+WeKnora 升级、DobotAI 迁移、钉钉单消费者切换和生产部署是独立变更边界，必须各自备份、演练和验收。

go.mod

@@ -3,6 +3,7 @@ module gitea.zheromiku.top/Weknora/dobotai-platform
 go 1.25.0
 
 require (
+	github.com/aliyun/alibabacloud-oss-go-sdk-v2 v1.5.1
 	github.com/jackc/pgx/v5 v5.9.2
 	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1
 )
@@ -15,4 +16,5 @@ require (
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	golang.org/x/sync v0.20.0 // indirect
 	golang.org/x/text v0.37.0 // indirect
+	golang.org/x/time v0.4.0 // indirect
 )

go.sum

@@ -1,3 +1,5 @@
+github.com/aliyun/alibabacloud-oss-go-sdk-v2 v1.5.1 h1:vtiFd0hhPAbyYJjztl0wYUq/PqEGkIlDmVuTIy6zw8Y=
+github.com/aliyun/alibabacloud-oss-go-sdk-v2 v1.5.1/go.mod h1:FTzydeQVmR24FI0D6XWUOMKckjXehM/jgMn1xC+DA9M=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -26,6 +28,8 @@ golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
 golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
 golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
+golang.org/x/time v0.4.0 h1:Z81tqI5ddIoXDPvVQ7/7CC9TnLM7ubaFG2qXYd5BbYY=
+golang.org/x/time v0.4.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

install-docker.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 唯一安装入口：镜像仓库名与标签策略只在本脚本维护。
+postgres_image="postgres:16-alpine"
+
+if [[ ${EUID} -ne 0 ]]; then
+  echo "请在克隆仓库根目录执行：sudo bash ./install-docker.sh" >&2
+  exit 1
+fi
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$repo_root"
+[[ -f Dockerfile && -f deploy/dobotai-dingtalk/install-docker.sh ]] || {
+  echo "安装脚本必须从完整DobotAI源码仓库根目录运行。" >&2
+  exit 1
+}
+command -v git >/dev/null || { echo "未找到 git，无法确定当前源码版本。" >&2; exit 1; }
+git -C "$repo_root" rev-parse --is-inside-work-tree >/dev/null || {
+  echo "请从 git clone 得到的仓库中执行本脚本。" >&2
+  exit 1
+}
+
+install_docker_if_missing() {
+  if command -v docker >/dev/null && docker compose version >/dev/null 2>&1; then
+    return
+  fi
+  command -v apt-get >/dev/null || {
+    echo "本脚本仅自动安装基于 apt 的 Docker；请先安装 Docker Engine 和 Docker Compose v2。" >&2
+    exit 1
+  }
+  export DEBIAN_FRONTEND=noninteractive
+  apt-get update
+  if apt-cache show docker-compose-v2 >/dev/null 2>&1; then
+    apt-get install -y docker.io docker-compose-v2
+  elif apt-cache show docker-compose-plugin >/dev/null 2>&1; then
+    apt-get install -y docker.io docker-compose-plugin
+  else
+    echo "当前APT源没有 Docker Compose v2 插件，无法安全继续。" >&2
+    exit 1
+  fi
+  systemctl enable --now docker
+  docker compose version >/dev/null
+}
+
+install_docker_if_missing
+
+commit_sha="$(git -C "$repo_root" rev-parse HEAD)"
+commit_short="$(git -C "$repo_root" rev-parse --short=12 HEAD)"
+build_time="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+image="dobotai-dingtalk:local-${commit_short}"
+
+echo "[1/3] 构建 DobotAI 镜像：$image"
+docker build \
+  --build-arg "GOPROXY=https://goproxy.cn,direct" \
+  --build-arg "VERSION=local-${commit_short}" \
+  --build-arg "COMMIT_SHA=${commit_sha}" \
+  --build-arg "BUILD_TIME=${build_time}" \
+  --label "org.opencontainers.image.revision=${commit_sha}" \
+  --tag "$image" \
+  "$repo_root"
+
+echo "[2/3] 准备独立PostgreSQL、目录、配置文件和迁移"
+export DOBOTAI_IMAGE="$image"
+export DOBOTAI_POSTGRES_IMAGE="$postgres_image"
+export DOBOTAI_SOURCE_ROOT="$repo_root"
+exec bash "$repo_root/deploy/dobotai-dingtalk/install-docker.sh"

internal/channels/dingtalk/card.go

@@ -8,6 +8,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"log"
 	"net/http"
 	"strings"
 	"sync"
@@ -206,6 +207,7 @@ func (s *CardSender) UpdateCard(ctx context.Context, outTrackID, content string,
 	if len(content) > 64*1024 {
 		return errors.New("dingtalk card: content exceeds 64 KiB")
 	}
+	log.Print(formatCardUpdateDiagnostic(content, isFinalize, isError))
 
 	token, err := s.accessToken(ctx)
 	if err != nil {
@@ -305,9 +307,25 @@ func (s *CardSender) postCard(ctx context.Context, body map[string]any, token st
 	if err != nil {
 		return err
 	}
-	// Discard successful response body
-	if len(payload) > 0 {
-		// Body is already bounded by postJSON→readBoundedAPIResponse; just discard
+	return validateDingTalkBusinessResponse(payload)
+}
+
+func validateDingTalkBusinessResponse(payload []byte) error {
+	if len(bytes.TrimSpace(payload)) == 0 {
+		return nil
+	}
+	var response struct {
+		Success *bool `json:"success"`
+		ErrCode any   `json:"errcode"`
+	}
+	if json.Unmarshal(payload, &response) != nil {
+		return nil
+	}
+	if response.Success != nil && !*response.Success {
+		return errors.New("dingtalk card: API business failure")
+	}
+	if response.ErrCode != nil && fmt.Sprint(response.ErrCode) != "0" {
+		return errors.New("dingtalk card: API business failure")
 	}
 	return nil
 }
@@ -326,8 +344,11 @@ func (s *CardSender) finalizeCard(ctx context.Context, outTrackID, content, toke
 		"isFinalize": isFinalize,
 		"isError":    isError,
 	}
-	_, err = s.doJSON(ctx, http.MethodPut, s.streamURL, body, token)
-	return err
+	payload, err := s.doJSON(ctx, http.MethodPut, s.streamURL, body, token)
+	if err != nil {
+		return err
+	}
+	return validateDingTalkBusinessResponse(payload)
 }
 
 func (s *CardSender) postJSON(ctx context.Context, endpoint string, value any, token string) ([]byte, error) {

internal/channels/dingtalk/card_diagnostics.go

@@ -0,0 +1,64 @@
+package dingtalk
+
+import (
+	"fmt"
+	"strings"
+)
+
+type cardContentShape struct {
+	bytes             int
+	lines             int
+	pipeLines         int
+	leadingPipeLines  int
+	delimiterLines    int
+	confirmedTable    bool
+	confirmedTablePos int
+}
+
+func inspectCardContent(content string) cardContentShape {
+	shape := cardContentShape{
+		bytes:             len(content),
+		confirmedTablePos: -1,
+	}
+	if content == "" {
+		return shape
+	}
+	shape.lines = strings.Count(content, "\n") + 1
+
+	lines := splitMarkdownStreamLines(content)
+	for i, line := range lines {
+		if strings.Contains(line.text, "|") {
+			shape.pipeLines++
+		}
+		if isTableHeaderCandidate(line.text) {
+			shape.leadingPipeLines++
+		}
+		if !line.inFence && isCompleteTableDelimiter(line.text) {
+			shape.delimiterLines++
+		}
+		if shape.confirmedTable || i == 0 || line.inFence || lines[i-1].inFence {
+			continue
+		}
+		if isTableHeaderCandidate(lines[i-1].text) && isCompleteTableDelimiter(line.text) {
+			shape.confirmedTable = true
+			shape.confirmedTablePos = lines[i-1].start
+		}
+	}
+	return shape
+}
+
+func formatCardUpdateDiagnostic(content string, isFinalize, isError bool) string {
+	shape := inspectCardContent(content)
+	return fmt.Sprintf(
+		"DingTalk card update shape: finalize=%t error=%t bytes=%d lines=%d pipe_lines=%d leading_pipe_lines=%d delimiter_lines=%d confirmed_table=%t table_start=%d",
+		isFinalize,
+		isError,
+		shape.bytes,
+		shape.lines,
+		shape.pipeLines,
+		shape.leadingPipeLines,
+		shape.delimiterLines,
+		shape.confirmedTable,
+		shape.confirmedTablePos,
+	)
+}

internal/channels/dingtalk/card_diagnostics_test.go

@@ -0,0 +1,93 @@
+package dingtalk
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"log"
+	"strings"
+	"testing"
+)
+
+func TestCardSenderUpdateCardLogsOnlySafeContentShape(t *testing.T) {
+	ts := newCardTestServer()
+	defer ts.Close()
+	sender, err := newCardSenderForTest("client-id", "client-secret", "template-id", ts.Client(), ts.URL()+"/token", ts.URL()+"/create")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var output bytes.Buffer
+	previousWriter := log.Writer()
+	previousFlags := log.Flags()
+	previousPrefix := log.Prefix()
+	log.SetOutput(&output)
+	log.SetFlags(0)
+	log.SetPrefix("")
+	t.Cleanup(func() {
+		log.SetOutput(previousWriter)
+		log.SetFlags(previousFlags)
+		log.SetPrefix(previousPrefix)
+	})
+
+	content := "DO_NOT_LOG_BOUNDARY_TEXT\n\n| 型号 | 负载 |\n| --- | --- |\n| CR5 | 5kg |"
+	if err := sender.UpdateCard(context.Background(), "track-diagnostic", content, false, false); err != nil {
+		t.Fatal(err)
+	}
+
+	got := output.String()
+	if !strings.Contains(got, "DingTalk card update shape:") || !strings.Contains(got, "confirmed_table=true") || !strings.Contains(got, "finalize=false") {
+		t.Fatalf("missing safe boundary diagnostic: %q", got)
+	}
+	if strings.Contains(got, "DO_NOT_LOG_BOUNDARY_TEXT") || strings.Contains(got, "CR5") || strings.Contains(got, "track-diagnostic") {
+		t.Fatalf("boundary diagnostic leaked content or card identifier: %q", got)
+	}
+}
+
+func TestFormatCardUpdateDiagnosticReportsStructureWithoutContent(t *testing.T) {
+	content := "DO_NOT_LOG_ANSWER_TEXT\n\n| 型号 | 负载 |\n| --- | --- |\n| CR5 | 5kg |"
+
+	got := formatCardUpdateDiagnostic(content, false, false)
+	wantFields := []string{
+		"DingTalk card update shape:",
+		"finalize=false",
+		"error=false",
+		fmt.Sprintf("bytes=%d", len(content)),
+		"lines=5",
+		"pipe_lines=3",
+		"leading_pipe_lines=3",
+		"delimiter_lines=1",
+		"confirmed_table=true",
+		fmt.Sprintf("table_start=%d", strings.Index(content, "| 型号")),
+	}
+	for _, field := range wantFields {
+		if !strings.Contains(got, field) {
+			t.Fatalf("diagnostic %q missing field %q", got, field)
+		}
+	}
+	if strings.Contains(got, "DO_NOT_LOG_ANSWER_TEXT") || strings.Contains(got, "CR5") {
+		t.Fatalf("diagnostic leaked answer content: %q", got)
+	}
+}
+
+func TestFormatCardUpdateDiagnosticDistinguishesFinalPlainText(t *testing.T) {
+	got := formatCardUpdateDiagnostic("普通回答", true, false)
+	wantFields := []string{
+		"finalize=true",
+		"error=false",
+		"lines=1",
+		"pipe_lines=0",
+		"leading_pipe_lines=0",
+		"delimiter_lines=0",
+		"confirmed_table=false",
+		"table_start=-1",
+	}
+	for _, field := range wantFields {
+		if !strings.Contains(got, field) {
+			t.Fatalf("diagnostic %q missing field %q", got, field)
+		}
+	}
+	if strings.Contains(got, "普通回答") {
+		t.Fatalf("diagnostic leaked answer content: %q", got)
+	}
+}

internal/channels/dingtalk/card_pump.go

@@ -39,6 +39,7 @@ func (p *cardUpdatePump) run(ctx context.Context, ticks <-chan time.Time, stopTi
 	if stopTicks != nil {
 		defer stopTicks()
 	}
+	lastSuccessful := ""
 	for {
 		select {
 		case <-ctx.Done():
@@ -52,9 +53,14 @@ func (p *cardUpdatePump) run(ctx context.Context, ticks <-chan time.Time, stopTi
 			default:
 				continue
 			}
+			if latest == lastSuccessful {
+				continue
+			}
 			if err := update(ctx, latest); err != nil {
 				log.Printf("DingTalk async card update failed, continuing")
+				continue
 			}
+			lastSuccessful = latest
 		}
 	}
 }

internal/channels/dingtalk/card_test.go

@@ -35,6 +35,7 @@ type cardTestServer struct {
 	createBodySize int64 // Content-Length for oversized response
 	streamStatus   int
 	streamBodySize int64
+	streamResponse any
 }
 
 func newCardTestServer() *cardTestServer {
@@ -42,6 +43,7 @@ func newCardTestServer() *cardTestServer {
 		tokenStatus:    http.StatusOK,
 		createStatus:   http.StatusOK,
 		streamStatus:   http.StatusOK,
+		streamResponse: map[string]any{"result": "ok"},
 		tokenResponse:  map[string]any{"accessToken": "test-access-token", "expireIn": 3600},
 		createResponse: map[string]any{"result": "ok"},
 	}
@@ -91,7 +93,7 @@ func newCardTestServer() *cardTestServer {
 				return
 			}
 			w.Header().Set("Content-Type", "application/json")
-			json.NewEncoder(w).Encode(map[string]any{"result": "ok"})
+			json.NewEncoder(w).Encode(ts.streamResponse)
 		default:
 			http.NotFound(w, r)
 		}
@@ -969,6 +971,19 @@ func TestSendFinalCardCreateStreamOnce(t *testing.T) {
 // Test: UpdateCard with non-final / error flags
 // ---------------------------------------------------------------------------
 
+func TestUpdateCardRejectsHTTP200BusinessFailure(t *testing.T) {
+	ts := newCardTestServer()
+	defer ts.Close()
+	ts.streamResponse = map[string]any{"success": false, "code": "InvalidParameter", "message": "sensitive detail"}
+	sender, err := newCardSenderForTest("client-id", "client-secret", "card-template-123", ts.Client(), ts.URL()+"/token", ts.URL()+"/create")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := sender.UpdateCard(context.Background(), "track-1", "answer", true, false); err == nil {
+		t.Fatal("HTTP 200 business failure must be rejected")
+	}
+}
+
 func TestUpdateCardNonFinalAndError(t *testing.T) {
 	ts := newCardTestServer()
 	defer ts.Close()

internal/channels/dingtalk/display_sanitizer.go

@@ -0,0 +1,31 @@
+package dingtalk
+
+import (
+	"regexp"
+	"strings"
+)
+
+const displayReferenceMarkerPattern = `\[\[ref[\t ]+id[\t ]*=[\t ]*["']c[0-9]+["'][\t ]*\]\]`
+
+var (
+	displayReferenceMarkerRE      = regexp.MustCompile(displayReferenceMarkerPattern)
+	leadingReferenceGroupColonRE  = regexp.MustCompile(`(?m)^[	 ]*(?:` + displayReferenceMarkerPattern + `[	 ]*)+[：:][	 ]*`)
+	spacedReferenceGroupRE        = regexp.MustCompile(`[	 ]+(?:` + displayReferenceMarkerPattern + `[	 ]*)+`)
+	spaceBeforeDisplayPunctuation = regexp.MustCompile(`[	 ]+([，。；：！？、,.;:!?])`)
+	spaceAfterDisplayColon        = regexp.MustCompile(`([：:])[\t ]+`)
+)
+
+func sanitizeDisplayAnswer(content string) string {
+	if index := strings.LastIndex(content, "[[ref"); index >= 0 && !strings.Contains(content[index:], "]]") {
+		content = content[:index]
+	}
+	if !displayReferenceMarkerRE.MatchString(content) {
+		return content
+	}
+	content = leadingReferenceGroupColonRE.ReplaceAllString(content, "")
+	content = spacedReferenceGroupRE.ReplaceAllString(content, " ")
+	content = displayReferenceMarkerRE.ReplaceAllString(content, "")
+	content = spaceBeforeDisplayPunctuation.ReplaceAllString(content, "$1")
+	content = spaceAfterDisplayColon.ReplaceAllString(content, "$1")
+	return content
+}

internal/channels/dingtalk/display_sanitizer_test.go

@@ -0,0 +1,66 @@
+package dingtalk
+
+import "testing"
+
+func TestSanitizeDisplayAnswerRemovesInternalReferenceMarkers(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "adjacent inline markers",
+			input: "结论支持该功能[[ref id=\"c2\"]][[ref id=\"c4\"]]。",
+			want:  "结论支持该功能。",
+		},
+		{
+			name:  "leading marker group and chinese colon",
+			input: "[[ref id=\"c2\"]][[ref id=\"c4\"]]：建议先检查配置。",
+			want:  "建议先检查配置。",
+		},
+		{
+			name:  "leading marker group and ascii colon on second line",
+			input: "第一段。\n[[ref id='c12']] : Second paragraph.",
+			want:  "第一段。\nSecond paragraph.",
+		},
+		{
+			name:  "normal punctuation remains natural",
+			input: "标题：[[ref id=\"c1\"]] 详细说明",
+			want:  "标题：详细说明",
+		},
+		{
+			name:  "spaces around marker collapse to one",
+			input: "Feature A [[ref id=\"c3\"]] remains supported.",
+			want:  "Feature A remains supported.",
+		},
+		{
+			name:  "unrelated double bracket syntax is preserved",
+			input: "请保留 [[wiki|页面名称]] 和 [普通链接](https://example.com)。",
+			want:  "请保留 [[wiki|页面名称]] 和 [普通链接](https://example.com)。",
+		},
+		{
+			name:  "content without references remains byte for byte unchanged",
+			input: "Protocol: value ; keep  spacing\n  indented",
+			want:  "Protocol: value ; keep  spacing\n  indented",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := sanitizeDisplayAnswer(tt.input); got != tt.want {
+				t.Fatalf("sanitizeDisplayAnswer()=%q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestSanitizeDisplayAnswerHoldsBackDanglingStreamingReference(t *testing.T) {
+	for _, input := range []string{
+		"答案正文[[ref",
+		"答案正文[[ref id=\"c",
+		"答案正文[[ref id=\"c2\"",
+	} {
+		if got := sanitizeDisplayAnswer(input); got != "答案正文" {
+			t.Fatalf("sanitizeDisplayAnswer(%q)=%q", input, got)
+		}
+	}
+}

internal/channels/dingtalk/download_codes_test.go

@@ -0,0 +1,33 @@
+package dingtalk
+
+import (
+	"testing"
+)
+
+func TestEffectiveDownloadCodesDeduplicatesAndPreservesOrder(t *testing.T) {
+	cb := BotCallback{
+		DownloadCode:  "code-first",
+		DownloadCodes: []string{"code-first", "code-second", "  code-third  "},
+	}
+	codes := effectiveDownloadCodes(cb)
+	if len(codes) != 3 {
+		t.Fatalf("codes=%v, want 3", codes)
+	}
+	if codes[0] != "code-first" || codes[1] != "code-second" || codes[2] != "code-third" {
+		t.Fatalf("codes=%v, want ordered de-dup", codes)
+	}
+}
+
+func TestEffectiveDownloadCodesSingleOnly(t *testing.T) {
+	cb := BotCallback{DownloadCode: "  solo  "}
+	codes := effectiveDownloadCodes(cb)
+	if len(codes) != 1 || codes[0] != "solo" {
+		t.Fatalf("codes=%v, want [solo]", codes)
+	}
+}
+
+func TestEffectiveDownloadCodesEmpty(t *testing.T) {
+	if codes := effectiveDownloadCodes(BotCallback{}); len(codes) != 0 {
+		t.Fatalf("codes=%v, want empty", codes)
+	}
+}

internal/channels/dingtalk/feedback.go

@@ -79,10 +79,6 @@ func (h *CardFeedbackHandler) HandleSDK(ctx context.Context, request *sdkcard.Ca
 	if value == feedbackdomain.ValueUp {
 		message = "感谢反馈"
 	}
-	if value == feedbackdomain.ValueDown && reason == feedbackdomain.ReasonEmpty {
-		showReasons = "true"
-		message = "请选择未解决原因"
-	}
 	return &sdkcard.CardResponse{
 		CardUpdateOptions: &sdkcard.CardUpdateOptions{UpdatePrivateDataByKey: true},
 		UserPrivateData: &sdkcard.CardDataDto{CardParamMap: map[string]string{

internal/channels/dingtalk/feedback_test.go

@@ -84,7 +84,9 @@ func TestCardFeedbackMapsNativeDislike(t *testing.T) {
 	if service.calls != 1 || service.command.Value != feedbackdomain.ValueDown || service.command.ReasonCode != feedbackdomain.ReasonEmpty {
 		t.Fatalf("calls=%d command=%+v", service.calls, service.command)
 	}
-	if response == nil || response.UserPrivateData == nil || response.UserPrivateData.CardParamMap["showFeedbackReasons"] != "true" {
+	if response == nil || response.UserPrivateData == nil ||
+		response.UserPrivateData.CardParamMap["showFeedbackReasons"] != "false" ||
+		response.UserPrivateData.CardParamMap["feedbackMessage"] != "感谢反馈，我们会继续改进" {
 		t.Fatalf("response=%+v", response)
 	}
 }
@@ -201,7 +203,7 @@ func TestCardFeedbackMapsWhitelistedActions(t *testing.T) {
 		message     string
 	}{
 		{ActionFeedbackUp, feedbackdomain.ValueUp, "", "false", "感谢反馈"},
-		{ActionFeedbackDown, feedbackdomain.ValueDown, "", "true", "请选择未解决原因"},
+		{ActionFeedbackDown, feedbackdomain.ValueDown, "", "false", "感谢反馈，我们会继续改进"},
 		{ActionReasonIncorrect, feedbackdomain.ValueDown, feedbackdomain.ReasonIncorrect, "false", "感谢反馈，我们会继续改进"},
 		{ActionReasonNotResolved, feedbackdomain.ValueDown, feedbackdomain.ReasonNotResolved, "false", "感谢反馈，我们会继续改进"},
 		{ActionReasonIrrelevant, feedbackdomain.ValueDown, feedbackdomain.ReasonIrrelevant, "false", "感谢反馈，我们会继续改进"},

internal/channels/dingtalk/group_sender.go

@@ -0,0 +1,364 @@
+package dingtalk
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/coverage"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/faqtable"
+)
+
+const (
+	groupSendURL = "https://api.dingtalk.com/v1.0/robot/groupMessages/send"
+	// maxGroupPayloadBytes caps the serialized JSON body sent to the group
+	// message endpoint.
+	maxGroupPayloadBytes = 64 << 10 // 64 KiB
+	// questionRuneLimit caps the displayed current question.
+	questionRuneLimit = 500
+	// previousQuestionRuneLimit caps each displayed historical question.
+	previousQuestionRuneLimit = 300
+)
+
+// SupportGroupSender sends DingTalk group Markdown notifications via the
+// official groupMessages/send OpenAPI. It is safe by construction: all
+// config fields are trimmed, nil client installs hardened defaults, and
+// all error paths are sanitised.
+type SupportGroupSender struct {
+	clientID         string
+	clientSecret     string
+	openConversation string
+	recordLinks      *faqtable.RecordLinkBuilder
+	tokenURL         string
+	groupURL         string
+	apiClient        *http.Client
+
+	mu        sync.Mutex
+	token     string
+	tokenTill time.Time
+}
+
+type SupportGroupSenderOption func(*SupportGroupSender)
+
+func WithFAQRecordLinkBuilder(builder *faqtable.RecordLinkBuilder) SupportGroupSenderOption {
+	return func(sender *SupportGroupSender) { sender.recordLinks = builder }
+}
+
+var _ coverage.Notifier = (*SupportGroupSender)(nil)
+
+// NewSupportGroupSender creates a SupportGroupSender. All three config values
+// are required after trimming. A nil http.Client installs a hardened default
+// (no redirects, Proxy=nil, 15s timeout).
+func NewSupportGroupSender(clientID, clientSecret, openConversationID string, client *http.Client, opts ...SupportGroupSenderOption) (*SupportGroupSender, error) {
+	return newSupportGroupSender(clientID, clientSecret, openConversationID, client, oauthTokenURL, groupSendURL, false, opts...)
+}
+
+// newSupportGroupSenderForTest is used by tests to inject httptest URLs.
+func newSupportGroupSenderForTest(clientID, clientSecret, openConversationID string, client *http.Client, tokenURL, groupURL string, opts ...SupportGroupSenderOption) (*SupportGroupSender, error) {
+	return newSupportGroupSender(clientID, clientSecret, openConversationID, client, tokenURL, groupURL, true, opts...)
+}
+
+func newSupportGroupSender(clientID, clientSecret, openConversationID string, client *http.Client, tokenURL, groupURL string, allowTest bool, opts ...SupportGroupSenderOption) (*SupportGroupSender, error) {
+	clientID = strings.TrimSpace(clientID)
+	clientSecret = strings.TrimSpace(clientSecret)
+	openConversationID = strings.TrimSpace(openConversationID)
+	if clientID == "" {
+		return nil, errors.New("dingtalk group sender: clientID is required")
+	}
+	if clientSecret == "" {
+		return nil, errors.New("dingtalk group sender: clientSecret is required")
+	}
+	if openConversationID == "" {
+		return nil, errors.New("dingtalk group sender: openConversationId is required")
+	}
+
+	base := &http.Client{Timeout: 15 * time.Second}
+	if client != nil {
+		copyClient := *client
+		base = &copyClient
+		if base.Timeout <= 0 {
+			base.Timeout = 15 * time.Second
+		}
+	}
+
+	apiClient := *base
+	apiClient.CheckRedirect = func(*http.Request, []*http.Request) error {
+		return errors.New("dingtalk API redirect refused")
+	}
+	if !allowTest {
+		transport := http.DefaultTransport.(*http.Transport).Clone()
+		transport.Proxy = nil
+		apiClient.Transport = transport
+	}
+
+	sender := &SupportGroupSender{
+		clientID:         clientID,
+		clientSecret:     clientSecret,
+		openConversation: openConversationID,
+		tokenURL:         tokenURL,
+		groupURL:         groupURL,
+		apiClient:        &apiClient,
+	}
+	for _, opt := range opts {
+		if opt != nil {
+			opt(sender)
+		}
+	}
+	if allowTest && sender.recordLinks == nil {
+		sender.recordLinks, _ = faqtable.NewRecordLinkBuilder("test-base", "test-sheet", "test-view")
+	}
+	return sender, nil
+}
+
+// Send sends a support-case notification to the DingTalk group.
+func (s *SupportGroupSender) Send(ctx context.Context, notif coverage.SupportNotification) error {
+	if notif.CaseID == "" {
+		return errors.New("dingtalk group sender: CaseID is required")
+	}
+	if s.recordLinks == nil {
+		return errors.New("dingtalk group sender: FAQ record links are required")
+	}
+	recordURL, err := s.recordLinks.Build(notif.FAQRecordID)
+	if err != nil {
+		return errors.New("dingtalk group sender: FAQ record link failed")
+	}
+
+	title, text := s.renderMarkdown(notif)
+	msgParam := map[string]string{
+		"title":       title,
+		"text":        text,
+		"singleTitle": "去回答",
+		"singleURL":   recordURL,
+	}
+	msgParamJSON, err := json.Marshal(msgParam)
+	if err != nil {
+		return errors.New("dingtalk group sender: encode msgParam failed")
+	}
+
+	body := map[string]any{
+		"msgKey":             "sampleActionCard",
+		"msgParam":           string(msgParamJSON),
+		"openConversationId": s.openConversation,
+		"robotCode":          s.clientID,
+	}
+
+	bodyJSON, err := json.Marshal(body)
+	if err != nil {
+		return errors.New("dingtalk group sender: encode request body failed")
+	}
+	if len(bodyJSON) > maxGroupPayloadBytes {
+		return fmt.Errorf("dingtalk group sender: payload exceeds %d bytes", maxGroupPayloadBytes)
+	}
+
+	// Get access token
+	token, err := s.accessToken(ctx)
+	if err != nil {
+		return err
+	}
+
+	// POST to groupMessages/send
+	respPayload, err := s.doJSON(ctx, http.MethodPost, s.groupURL, body, token)
+	if err != nil {
+		return err
+	}
+
+	// Check business response
+	var bizResp struct {
+		ProcessQueryKey string `json:"processQueryKey"`
+		ErrCode         int    `json:"errcode"`
+	}
+	if err := json.Unmarshal(respPayload, &bizResp); err != nil {
+		return errors.New("dingtalk group sender: invalid API response")
+	}
+	if bizResp.ErrCode != 0 {
+		return errors.New("dingtalk group sender: API returned business error")
+	}
+	if strings.TrimSpace(bizResp.ProcessQueryKey) == "" {
+		return errors.New("dingtalk group sender: incomplete API response")
+	}
+
+	return nil
+}
+
+// SendTest sends a fixed, non-sensitive message used to verify that the
+// configured robot can reach the candidate support group. It deliberately
+// does not require an FAQ-table binding.
+func (s *SupportGroupSender) SendTest(ctx context.Context) error {
+	msgParam, err := json.Marshal(map[string]string{
+		"title": "DobotAI 技术支持群绑定测试",
+		"text":  "DobotAI 技术支持群绑定测试成功。",
+	})
+	if err != nil {
+		return errors.New("dingtalk group sender: encode test message failed")
+	}
+	body := map[string]any{
+		"msgKey":             "sampleMarkdown",
+		"msgParam":           string(msgParam),
+		"openConversationId": s.openConversation,
+		"robotCode":          s.clientID,
+	}
+	bodyJSON, err := json.Marshal(body)
+	if err != nil {
+		return errors.New("dingtalk group sender: encode test request failed")
+	}
+	if len(bodyJSON) > maxGroupPayloadBytes {
+		return fmt.Errorf("dingtalk group sender: payload exceeds %d bytes", maxGroupPayloadBytes)
+	}
+	token, err := s.accessToken(ctx)
+	if err != nil {
+		return err
+	}
+	respPayload, err := s.doJSON(ctx, http.MethodPost, s.groupURL, body, token)
+	if err != nil {
+		return err
+	}
+	var response struct {
+		ProcessQueryKey string `json:"processQueryKey"`
+		ErrCode         int    `json:"errcode"`
+	}
+	if json.Unmarshal(respPayload, &response) != nil {
+		return errors.New("dingtalk group sender: invalid API response")
+	}
+	if response.ErrCode != 0 {
+		return errors.New("dingtalk group sender: API returned business error")
+	}
+	if strings.TrimSpace(response.ProcessQueryKey) == "" {
+		return errors.New("dingtalk group sender: incomplete API response")
+	}
+	return nil
+}
+
+// renderMarkdown produces the compact customer-question context shown in the action card.
+func (s *SupportGroupSender) renderMarkdown(notif coverage.SupportNotification) (title, text string) {
+	label := "知识库未覆盖提醒"
+	if notif.TriggerType == coverage.SupportTriggerFeedbackDown {
+		label = "回答被点踩提醒"
+	}
+	title = label
+	question := escapeMarkdown(truncateRunes(notif.Question, questionRuneLimit))
+	sender := escapeMarkdown(notif.SenderName)
+	askedAt := "未知"
+	if !notif.AskedAt.IsZero() {
+		askedAt = notif.AskedAt.In(time.FixedZone("CST", 8*60*60)).Format("2006-01-02 15:04:05")
+	}
+
+	var b strings.Builder
+	b.WriteString("## 【" + label + "】\n\n")
+	b.WriteString(fmt.Sprintf("**提问人：** %s\n\n", sender))
+	b.WriteString(fmt.Sprintf("**时间：** %s\n\n", askedAt))
+	b.WriteString(fmt.Sprintf("**当前问题：**\n> %s\n\n", question))
+	b.WriteString(fmt.Sprintf("**语言：** %s\n\n", faqtable.DetectLanguage(notif.Question)))
+	b.WriteString("**最近5次历史问题：**\n")
+	if len(notif.PreviousQuestions) == 0 {
+		b.WriteString("暂无历史问题\n")
+	} else {
+		for i, previous := range notif.PreviousQuestions {
+			if i >= 5 {
+				break
+			}
+			b.WriteString(fmt.Sprintf("%d. %s\n", i+1, escapeMarkdown(truncateRunes(previous, previousQuestionRuneLimit))))
+		}
+	}
+	return title, b.String()
+}
+
+func escapeMarkdown(value string) string {
+	value = strings.Join(strings.Fields(value), " ")
+	replacer := strings.NewReplacer(
+		"\\", "\\\\", "`", "\\`", "*", "\\*", "_", "\\_",
+		"[", "\\[", "]", "\\]", "(", "\\(", ")", "\\)",
+		"#", "\\#", ">", "\\>",
+	)
+	return replacer.Replace(value)
+}
+
+func truncateRunes(s string, limit int) string {
+	if limit <= 0 {
+		return s
+	}
+	runes := []rune(s)
+	if len(runes) <= limit {
+		return s
+	}
+	return string(runes[:limit]) + "..."
+}
+
+func (s *SupportGroupSender) accessToken(ctx context.Context) (string, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.token != "" && time.Now().Before(s.tokenTill) {
+		return s.token, nil
+	}
+
+	payload, err := s.doJSON(ctx, http.MethodPost, s.tokenURL, map[string]string{
+		"appKey":    s.clientID,
+		"appSecret": s.clientSecret,
+	}, "")
+	if err != nil {
+		return "", err
+	}
+
+	var response struct {
+		AccessToken string `json:"accessToken"`
+		ExpireIn    int64  `json:"expireIn"`
+	}
+	if json.Unmarshal(payload, &response) != nil || strings.TrimSpace(response.AccessToken) == "" {
+		return "", errors.New("dingtalk group sender: invalid OAuth response")
+	}
+
+	ttl := time.Duration(response.ExpireIn) * time.Second
+	refreshAfter := ttl - 5*time.Minute
+	if refreshAfter <= 0 {
+		refreshAfter = ttl / 2
+	}
+	if refreshAfter <= 0 {
+		refreshAfter = time.Minute
+	}
+	s.token = response.AccessToken
+	s.tokenTill = time.Now().Add(refreshAfter)
+	return s.token, nil
+}
+
+func (s *SupportGroupSender) doJSON(ctx context.Context, method, endpoint string, value any, token string) ([]byte, error) {
+	body, err := json.Marshal(value)
+	if err != nil {
+		return nil, errors.New("dingtalk group sender: encode API request failed")
+	}
+
+	req, err := http.NewRequestWithContext(ctx, method, endpoint, bytes.NewReader(body))
+	if err != nil {
+		return nil, errors.New("dingtalk group sender: create API request failed")
+	}
+	req.Header.Set("Content-Type", "application/json")
+	if token != "" {
+		req.Header.Set("x-acs-dingtalk-access-token", token)
+	}
+
+	resp, err := s.apiClient.Do(req)
+	if err != nil {
+		if ctx.Err() != nil {
+			return nil, ctx.Err()
+		}
+		// Propagate redirect errors so callers can detect them.
+		if strings.Contains(err.Error(), "redirect") {
+			return nil, err
+		}
+		return nil, errors.New("dingtalk group sender: API request failed")
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		// Discard body without reading it — sanitised error
+		_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, maxAPIResponseBytes))
+		return nil, fmt.Errorf("dingtalk group sender: API HTTP %d", resp.StatusCode)
+	}
+
+	return readBoundedAPIResponse(resp)
+}

internal/channels/dingtalk/group_sender_actioncard_test.go

@@ -0,0 +1,60 @@
+package dingtalk
+
+import (
+	"context"
+	"encoding/json"
+	"net/url"
+	"strings"
+	"testing"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/faqtable"
+)
+
+func TestSupportGroupSenderSendsActionCardWithExactFAQRecordLink(t *testing.T) {
+	gs := newGroupTestServer()
+	defer gs.Close()
+	builder, err := faqtable.NewRecordLinkBuilder("jb9-base", "hERWDMS", "qvGDAH2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	s, err := newSupportGroupSenderForTest(
+		"appKey", "appSecret", "cid-abc", gs.server.Client(),
+		gs.URL()+"/token", gs.URL()+"/groupMessages/send",
+		WithFAQRecordLinkBuilder(builder),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := s.Send(context.Background(), newTestNotification()); err != nil {
+		t.Fatal(err)
+	}
+	if gs.lastSendBody["msgKey"] != "sampleActionCard" {
+		t.Fatalf("msgKey=%v", gs.lastSendBody["msgKey"])
+	}
+	var params map[string]string
+	if err := json.Unmarshal([]byte(gs.lastSendBody["msgParam"].(string)), &params); err != nil {
+		t.Fatal(err)
+	}
+	if params["singleTitle"] != "去回答" {
+		t.Fatalf("singleTitle=%q", params["singleTitle"])
+	}
+	parsed, err := url.Parse(params["singleURL"])
+	if err != nil {
+		t.Fatal(err)
+	}
+	q := parsed.Query()
+	if parsed.Host != "docs.dingtalk.com" || q.Get("rowId") != "record-001" || q.Get("dentryUuid") != "jb9-base" {
+		t.Fatalf("singleURL=%s", params["singleURL"])
+	}
+	text := params["text"]
+	for _, required := range []string{"张三", "2026-07-24 10:16:35", "怎么配置钉钉机器人", "之前的问题一", "之前的问题二", "Chinese"} {
+		if !strings.Contains(text, required) {
+			t.Errorf("text missing %q: %s", required, text)
+		}
+	}
+	for _, forbidden := range []string{"回答摘要", "相关结果", "Score", "置信度", "case-001"} {
+		if strings.Contains(text, forbidden) {
+			t.Errorf("text contains forbidden %q: %s", forbidden, text)
+		}
+	}
+}

internal/channels/dingtalk/group_sender_test.go

@@ -0,0 +1,599 @@
+package dingtalk
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/core"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/coverage"
+)
+
+// groupTestServer provides a configurable httptest server for group message
+// tests, with token and groupMessages/send endpoints.
+type groupTestServer struct {
+	server     *httptest.Server
+	tokenCalls int
+	sendCalls  int
+
+	lastTokenBody  map[string]string
+	lastSendBody   map[string]any
+	lastSendHeader string
+
+	tokenStatus   int
+	tokenResponse any
+
+	sendStatus   int
+	sendResponse any
+}
+
+func newGroupTestServer() *groupTestServer {
+	gs := &groupTestServer{
+		tokenStatus:   http.StatusOK,
+		tokenResponse: map[string]any{"accessToken": "test-token", "expireIn": 3600},
+		sendStatus:    http.StatusOK,
+		sendResponse:  map[string]any{"processQueryKey": "pqk-123"},
+	}
+	gs.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/token":
+			gs.tokenCalls++
+			gs.lastTokenBody = make(map[string]string)
+			json.NewDecoder(r.Body).Decode(&gs.lastTokenBody)
+			w.Header().Set("Content-Type", "application/json")
+			if gs.tokenStatus != http.StatusOK {
+				w.WriteHeader(gs.tokenStatus)
+				return
+			}
+			json.NewEncoder(w).Encode(gs.tokenResponse)
+		case "/groupMessages/send":
+			gs.sendCalls++
+			gs.lastSendHeader = r.Header.Get("x-acs-dingtalk-access-token")
+			gs.lastSendBody = make(map[string]any)
+			json.NewDecoder(r.Body).Decode(&gs.lastSendBody)
+			w.Header().Set("Content-Type", "application/json")
+			if gs.sendStatus != http.StatusOK {
+				w.WriteHeader(gs.sendStatus)
+				return
+			}
+			json.NewEncoder(w).Encode(gs.sendResponse)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	return gs
+}
+
+func (gs *groupTestServer) Close()      { gs.server.Close() }
+func (gs *groupTestServer) URL() string { return gs.server.URL }
+
+func newTestNotification() coverage.SupportNotification {
+	return coverage.SupportNotification{
+		CaseID:            "case-001",
+		Question:          "怎么配置钉钉机器人？",
+		SenderName:        "张三",
+		Channel:           "dingtalk",
+		ConversationType:  core.ConversationGroup,
+		AskedAt:           time.Date(2026, 7, 24, 10, 16, 35, 0, time.FixedZone("CST", 8*60*60)),
+		PreviousQuestions: []string{"之前的问题一", "之前的问题二"},
+		FAQRecordID:       "record-001",
+	}
+}
+
+// helper to create a sender with test URLs.
+func newTestGroupSender(t *testing.T, clientID, clientSecret, openConvID string, client *http.Client, tokenURL, groupURL string) *SupportGroupSender {
+	t.Helper()
+	s, err := newSupportGroupSenderForTest(clientID, clientSecret, openConvID, client, tokenURL, groupURL)
+	if err != nil {
+		t.Fatalf("newSupportGroupSenderForTest: %v", err)
+	}
+	return s
+}
+
+// -------- 1. fail closed on missing config --------
+
+func TestSupportGroupSenderMissingConfigFailsClosed(t *testing.T) {
+	tests := []struct {
+		name, clientID, clientSecret, openConvID string
+		wantErr                                  string
+	}{
+		{name: "empty clientID", clientSecret: "s", openConvID: "c", wantErr: "clientID"},
+		{name: "empty clientSecret", clientID: "a", openConvID: "c", wantErr: "clientSecret"},
+		{name: "empty openConversationId", clientID: "a", clientSecret: "s", wantErr: "openConversationId"},
+		{name: "all empty", wantErr: "clientID"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := NewSupportGroupSender(tt.clientID, tt.clientSecret, tt.openConvID, nil)
+			if err == nil {
+				t.Fatal("expected error, got nil")
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("error = %v, want containing %q", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+// -------- 2. exact endpoint, body, header --------
+
+func TestSupportGroupSenderExactEndpointBodyHeader(t *testing.T) {
+	gs := newGroupTestServer()
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+	notif := newTestNotification()
+	ctx := context.Background()
+
+	if err := s.Send(ctx, notif); err != nil {
+		t.Fatalf("Send: %v", err)
+	}
+
+	// Verify token endpoint was called
+	if gs.tokenCalls != 1 {
+		t.Fatalf("tokenCalls = %d, want 1", gs.tokenCalls)
+	}
+	if gs.lastTokenBody["appKey"] != "appKey" || gs.lastTokenBody["appSecret"] != "appSecret" {
+		t.Fatalf("token body = %+v", gs.lastTokenBody)
+	}
+
+	// Verify send endpoint
+	if gs.sendCalls != 1 {
+		t.Fatalf("sendCalls = %d, want 1", gs.sendCalls)
+	}
+	if gs.lastSendHeader != "test-token" {
+		t.Fatalf("send header = %q, want test-token", gs.lastSendHeader)
+	}
+
+	body := gs.lastSendBody
+	if body["msgKey"] != "sampleActionCard" {
+		t.Fatalf("msgKey = %v, want sampleActionCard", body["msgKey"])
+	}
+	if body["openConversationId"] != "cid-abc" {
+		t.Fatalf("openConversationId = %v, want cid-abc", body["openConversationId"])
+	}
+	if body["robotCode"] != "appKey" {
+		t.Fatalf("robotCode = %v, want appKey", body["robotCode"])
+	}
+
+	// msgParam must be a JSON string
+	msgParamRaw, ok := body["msgParam"].(string)
+	if !ok {
+		t.Fatalf("msgParam is not a string, got %T", body["msgParam"])
+	}
+
+	// Parse msgParam as JSON
+	var msgParam map[string]string
+	if err := json.Unmarshal([]byte(msgParamRaw), &msgParam); err != nil {
+		t.Fatalf("msgParam is not valid JSON: %v (raw=%s)", err, msgParamRaw)
+	}
+	if msgParam["title"] == "" {
+		t.Fatal("msgParam.title is empty")
+	}
+	if msgParam["text"] == "" {
+		t.Fatal("msgParam.text is empty")
+	}
+}
+
+// -------- 3. msgParam is valid JSON string --------
+
+func TestSupportGroupSenderMsgParamIsValidJSON(t *testing.T) {
+	gs := newGroupTestServer()
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+
+	if err := s.Send(context.Background(), newTestNotification()); err != nil {
+		t.Fatalf("Send: %v", err)
+	}
+
+	raw := gs.lastSendBody["msgParam"].(string)
+	var mp map[string]any
+	if err := json.Unmarshal([]byte(raw), &mp); err != nil {
+		t.Fatalf("msgParam not valid JSON: %v", err)
+	}
+
+	// Verify required keys exist
+	if _, ok := mp["title"]; !ok {
+		t.Fatal("msgParam missing title")
+	}
+	if _, ok := mp["text"]; !ok {
+		t.Fatal("msgParam missing text")
+	}
+}
+
+// -------- 4. OAuth token reuse --------
+
+func TestSupportGroupSenderTokenReuse(t *testing.T) {
+	gs := newGroupTestServer()
+	gs.tokenResponse = map[string]any{"accessToken": "reused-token", "expireIn": 7200}
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+
+	// Send twice
+	if err := s.Send(context.Background(), newTestNotification()); err != nil {
+		t.Fatalf("first Send: %v", err)
+	}
+	if err := s.Send(context.Background(), newTestNotification()); err != nil {
+		t.Fatalf("second Send: %v", err)
+	}
+
+	// Token should only be fetched once
+	if gs.tokenCalls != 1 {
+		t.Fatalf("tokenCalls = %d, want 1 (token should be reused)", gs.tokenCalls)
+	}
+	if gs.sendCalls != 2 {
+		t.Fatalf("sendCalls = %d, want 2", gs.sendCalls)
+	}
+}
+
+// -------- 5. no redirects --------
+
+func TestSupportGroupSenderRejectsRedirect(t *testing.T) {
+	// Create a target server
+	target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer target.Close()
+
+	// Create a redirector
+	redirector := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, target.URL+"/groupMessages/send", http.StatusFound)
+	}))
+	defer redirector.Close()
+
+	_, err := newSupportGroupSenderForTest("appKey", "appSecret", "cid-abc", redirector.Client(),
+		redirector.URL+"/token", redirector.URL+"/groupMessages/send")
+	if err != nil {
+		t.Fatalf("newSupportGroupSenderForTest: %v", err)
+	}
+
+	// token endpoint also redirects
+	redirector2 := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Redirect(w, r, target.URL+"/token", http.StatusFound)
+	}))
+	defer redirector2.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", redirector2.Client(),
+		redirector2.URL+"/token", redirector2.URL+"/groupMessages/send")
+
+	err = s.Send(context.Background(), newTestNotification())
+	if err == nil {
+		t.Fatal("expected redirect error, got nil")
+	}
+	if !strings.Contains(err.Error(), "redirect") {
+		t.Fatalf("error = %v, want containing 'redirect'", err)
+	}
+}
+
+// -------- 6. non-2xx sanitized error --------
+
+func TestSupportGroupSenderNon2xxSanitized(t *testing.T) {
+	gs := newGroupTestServer()
+	gs.sendStatus = http.StatusInternalServerError
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+
+	err := s.Send(context.Background(), newTestNotification())
+	if err == nil {
+		t.Fatal("expected error for 500, got nil")
+	}
+
+	errStr := err.Error()
+	// Error must NOT contain clientSecret
+	if strings.Contains(errStr, "appSecret") {
+		t.Fatalf("error leaks clientSecret: %s", errStr)
+	}
+	// Error must NOT contain access token
+	if strings.Contains(errStr, "test-token") {
+		t.Fatalf("error leaks access token: %s", errStr)
+	}
+	// Error must NOT contain conversation ID
+	if strings.Contains(errStr, "cid-abc") {
+		t.Fatalf("error leaks openConversationId: %s", errStr)
+	}
+	// Error must NOT contain question
+	if strings.Contains(errStr, "怎么配置") {
+		t.Fatalf("error leaks question: %s", errStr)
+	}
+	// Error must NOT contain answer
+	if strings.Contains(errStr, "钉钉开放平台") {
+		t.Fatalf("error leaks answer: %s", errStr)
+	}
+}
+
+// -------- 7. business failure (non-success response) sanitized --------
+
+func TestSupportGroupSenderBusinessFailureSanitized(t *testing.T) {
+	gs := newGroupTestServer()
+	gs.sendStatus = http.StatusOK
+	// Simulate a business error: DingTalk returns 200 but with error code
+	gs.sendResponse = map[string]any{
+		"errcode": 40035,
+		"errmsg":  "不合法的参数",
+	}
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+
+	err := s.Send(context.Background(), newTestNotification())
+	if err == nil {
+		t.Fatal("expected business error, got nil")
+	}
+
+	errStr := err.Error()
+	if strings.Contains(errStr, "appSecret") {
+		t.Fatalf("error leaks clientSecret: %s", errStr)
+	}
+	if strings.Contains(errStr, "test-token") {
+		t.Fatalf("error leaks access token: %s", errStr)
+	}
+	if strings.Contains(errStr, "cid-abc") {
+		t.Fatalf("error leaks openConversationId: %s", errStr)
+	}
+	if strings.Contains(errStr, "怎么配置") {
+		t.Fatalf("error leaks question: %s", errStr)
+	}
+}
+
+// -------- 8. long Unicode truncation / 64KiB limit --------
+
+func TestSupportGroupSenderLongUnicodeTruncation(t *testing.T) {
+	gs := newGroupTestServer()
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+
+	// Create a notification with a very long current and historical question.
+	longQ := strings.Repeat("你好", 300)
+	longPrevious := strings.Repeat("世界", 600)
+
+	notif := newTestNotification()
+	notif.Question = longQ
+	notif.PreviousQuestions = []string{longPrevious}
+
+	if err := s.Send(context.Background(), notif); err != nil {
+		t.Fatalf("Send with long content: %v", err)
+	}
+
+	// The msgParam text should contain truncated versions
+	raw := gs.lastSendBody["msgParam"].(string)
+	var mp map[string]string
+	if err := json.Unmarshal([]byte(raw), &mp); err != nil {
+		t.Fatalf("msgParam not valid JSON: %v", err)
+	}
+
+	text := mp["text"]
+	// Both current and historical questions are present and rune-truncated.
+	if !strings.Contains(text, "你好") {
+		t.Fatal("text missing current question content")
+	}
+	if !strings.Contains(text, "世界") {
+		t.Fatal("text missing historical question content")
+	}
+
+	// The full body size must be <= 64KiB
+	bodyBytes, _ := json.Marshal(gs.lastSendBody)
+	if len(bodyBytes) > 64*1024 {
+		t.Fatalf("body size = %d, exceeds 64KiB", len(bodyBytes))
+	}
+}
+
+func TestSupportGroupSenderPayloadExceeds64KiB(t *testing.T) {
+	gs := newGroupTestServer()
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+
+	notif := newTestNotification()
+	// Use a very long SenderName to push the rendered markdown + JSON
+	// serialization beyond 64 KiB. Question/Answer are truncated to 500/1000
+	// runes, so they won't contribute much. The SenderName is not truncated.
+	notif.SenderName = strings.Repeat("张", 70*1024) // ~70KB of UTF-8
+
+	err := s.Send(context.Background(), notif)
+	if err == nil {
+		t.Fatal("expected error for oversized payload, got nil")
+	}
+	if !strings.Contains(err.Error(), "exceeds") && !strings.Contains(err.Error(), "64") && !strings.Contains(err.Error(), "KiB") {
+		t.Fatalf("error = %v, want size-limit error", err)
+	}
+}
+
+// -------- 9. error JSON response does not leak --------
+
+func TestSupportGroupSenderErrorJSONNotLeaked(t *testing.T) {
+	gs := newGroupTestServer()
+	gs.sendStatus = http.StatusBadRequest
+	// Return a large error body
+	gs.sendResponse = nil
+	// Override handler to return raw error JSON
+	gs.server.Config.Handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/token" {
+			gs.tokenCalls++
+			w.Header().Set("Content-Type", "application/json")
+			json.NewEncoder(w).Encode(gs.tokenResponse)
+			return
+		}
+		gs.sendCalls++
+		w.WriteHeader(http.StatusBadRequest)
+		// Write raw error JSON with sensitive-looking content
+		io.WriteString(w, `{"errcode":40035,"errmsg":"invalid parameter cid-abc","raw":"user appSecret leaked"}`)
+	})
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+
+	err := s.Send(context.Background(), newTestNotification())
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+
+	errStr := err.Error()
+	// Error must not contain the raw response body
+	if strings.Contains(errStr, "40035") || strings.Contains(errStr, "invalid parameter") {
+		t.Fatalf("error leaks raw API response: %s", errStr)
+	}
+	if strings.Contains(errStr, "appSecret") {
+		t.Fatalf("error leaks clientSecret: %s", errStr)
+	}
+	if strings.Contains(errStr, "cid-abc") {
+		t.Fatalf("error leaks conversation ID: %s", errStr)
+	}
+}
+
+// -------- 10. validation: empty CaseID --------
+
+func TestSupportGroupSenderRejectsEmptyCaseID(t *testing.T) {
+	gs := newGroupTestServer()
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+
+	notif := newTestNotification()
+	notif.CaseID = ""
+	err := s.Send(context.Background(), notif)
+	if err == nil {
+		t.Fatal("expected error for empty CaseID, got nil")
+	}
+	if !strings.Contains(err.Error(), "CaseID") {
+		t.Fatalf("error = %v, want containing 'CaseID'", err)
+	}
+}
+
+// -------- 11. nil client installs hardened defaults --------
+
+func TestSupportGroupSenderNilClientDefaults(t *testing.T) {
+	gs := newGroupTestServer()
+	defer gs.Close()
+
+	// Use nil client and verify it still works with httptest URLs
+	s, err := newSupportGroupSenderForTest("appKey", "appSecret", "cid-abc", nil, gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+	if err != nil {
+		t.Fatalf("newSupportGroupSenderForTest with nil client: %v", err)
+	}
+	if err := s.Send(context.Background(), newTestNotification()); err != nil {
+		t.Fatalf("Send with nil client: %v", err)
+	}
+}
+
+// -------- 12. Markdown content verification --------
+
+func TestSupportGroupSenderMarkdownContent(t *testing.T) {
+	gs := newGroupTestServer()
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+
+	notif := newTestNotification()
+	if err := s.Send(context.Background(), notif); err != nil {
+		t.Fatalf("Send: %v", err)
+	}
+
+	raw := gs.lastSendBody["msgParam"].(string)
+	var mp map[string]string
+	if err := json.Unmarshal([]byte(raw), &mp); err != nil {
+		t.Fatalf("msgParam not valid JSON: %v", err)
+	}
+
+	text := mp["text"]
+	title := mp["title"]
+
+	if title != "知识库未覆盖提醒" {
+		t.Fatalf("title = %q", title)
+	}
+	for _, want := range []string{"张三", "2026-07-24 10:16:35", "怎么配置", "之前的问题一", "之前的问题二", "Chinese"} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("action-card text missing %q: %s", want, text)
+		}
+	}
+	for _, forbidden := range []string{"case-001", "回答摘要", "相关结果", "Score", "置信度"} {
+		if strings.Contains(text, forbidden) {
+			t.Fatalf("action-card text contains forbidden %q: %s", forbidden, text)
+		}
+	}
+	if mp["singleTitle"] != "去回答" || mp["singleURL"] == "" {
+		t.Fatalf("missing FAQ action: %#v", mp)
+	}
+}
+
+func TestSupportGroupSenderNoPreviousQuestions(t *testing.T) {
+	gs := newGroupTestServer()
+	defer gs.Close()
+
+	s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+	notif := newTestNotification()
+	notif.PreviousQuestions = nil
+	if err := s.Send(context.Background(), notif); err != nil {
+		t.Fatalf("Send: %v", err)
+	}
+	if raw := gs.lastSendBody["msgParam"].(string); !strings.Contains(raw, "暂无历史问题") {
+		t.Fatalf("missing empty-history copy: %s", raw)
+	}
+}
+
+func TestSupportGroupSenderSendTestDoesNotRequireFAQBinding(t *testing.T) {
+	gs := newGroupTestServer()
+	defer gs.Close()
+
+	sender, err := newSupportGroupSenderForTest(
+		"appKey", "appSecret", "cid-abc",
+		gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send",
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err = sender.SendTest(context.Background()); err != nil {
+		t.Fatalf("SendTest: %v", err)
+	}
+	if gs.sendCalls != 1 {
+		t.Fatalf("sendCalls=%d want=1", gs.sendCalls)
+	}
+	if gs.lastSendBody["openConversationId"] != "cid-abc" || gs.lastSendBody["robotCode"] != "appKey" {
+		t.Fatalf("body=%v", gs.lastSendBody)
+	}
+	if gs.lastSendBody["msgKey"] != "sampleMarkdown" {
+		t.Fatalf("msgKey=%v want=sampleMarkdown", gs.lastSendBody["msgKey"])
+	}
+	var params map[string]string
+	if err = json.Unmarshal([]byte(gs.lastSendBody["msgParam"].(string)), &params); err != nil {
+		t.Fatal(err)
+	}
+	if params["title"] != "DobotAI 技术支持群绑定测试" || !strings.Contains(params["text"], "测试成功") {
+		t.Fatalf("params=%v", params)
+	}
+}
+
+func TestSupportGroupSenderRejectsMalformedOrIncompleteSuccessResponse(t *testing.T) {
+	tests := []struct {
+		name     string
+		response any
+	}{
+		{name: "malformed JSON", response: json.RawMessage(`{`)},
+		{name: "missing processQueryKey", response: map[string]any{}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gs := newGroupTestServer()
+			gs.sendResponse = tt.response
+			defer gs.Close()
+
+			s := newTestGroupSender(t, "appKey", "appSecret", "cid-abc", gs.server.Client(), gs.URL()+"/token", gs.URL()+"/groupMessages/send")
+			err := s.Send(context.Background(), newTestNotification())
+			if err == nil {
+				t.Fatal("expected fail-closed error, got nil")
+			}
+			if strings.Contains(err.Error(), "cid-abc") || strings.Contains(err.Error(), "怎么配置") {
+				t.Fatalf("error leaks notification data: %v", err)
+			}
+		})
+	}
+}

internal/channels/dingtalk/group_sender_trigger_test.go

@@ -0,0 +1,24 @@
+package dingtalk
+
+import (
+	"strings"
+	"testing"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/coverage"
+)
+
+func TestSupportGroupSenderRendersFeedbackDownTrigger(t *testing.T) {
+	notification := newTestNotification()
+	notification.TriggerType = coverage.SupportTriggerFeedbackDown
+	title, text := (&SupportGroupSender{}).renderMarkdown(notification)
+	if title != "回答被点踩提醒" || !strings.Contains(text, "【回答被点踩提醒】") {
+		t.Fatalf("title=%q text=%q", title, text)
+	}
+}
+
+func TestSupportGroupSenderDefaultsHistoricalTriggerToCoverage(t *testing.T) {
+	title, text := (&SupportGroupSender{}).renderMarkdown(newTestNotification())
+	if title != "知识库未覆盖提醒" || !strings.Contains(text, "【知识库未覆盖提醒】") {
+		t.Fatalf("title=%q text=%q", title, text)
+	}
+}

internal/channels/dingtalk/handler.go

@@ -2,6 +2,7 @@ package dingtalk
 
 import (
 	"context"
+	"encoding/base64"
 	"errors"
 	"fmt"
 	"log"
@@ -9,6 +10,8 @@ import (
 	"time"
 
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/core"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/directory"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/reasoningmode"
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/weknora"
 )
 
@@ -32,17 +35,19 @@ type TenantConfig struct {
 }
 
 type BotCallback struct {
-	ConversationType string
-	ConversationID   string
-	Msgtype          string
-	MsgID            string
-	SenderNick       string
-	SenderStaffID    string
-	SenderID         string
-	IsInAtList       bool
-	SessionWebhook   string
-	Text             string
-	DownloadCode     string
+	ConversationType  string
+	ConversationID    string
+	ConversationTitle string
+	Msgtype           string
+	MsgID             string
+	SenderNick        string
+	SenderStaffID     string
+	SenderID          string
+	IsInAtList        bool
+	SessionWebhook    string
+	Text              string
+	DownloadCode      string
+	DownloadCodes     []string
 }
 
 type QAAsker interface {
@@ -73,6 +78,66 @@ type ImageDownloader interface {
 	Download(ctx context.Context, downloadCode string) (core.ImageInput, error)
 }
 
+// ImagePublisher publishes a downloaded image to object storage and returns a
+// stable HTTPS URL. Implementation satisfies outboundimage.Publisher.
+type ImagePublisher interface {
+	Publish(ctx context.Context, data []byte, contentType string) (string, error)
+}
+
+type UserDirectory interface {
+	ResolveUser(ctx context.Context, tenantKey, staffID, fallbackName string) (directory.Profile, error)
+}
+
+type OutboundContentRewriter interface {
+	Rewrite(ctx context.Context, content string) string
+}
+
+type OutboundPartialSanitizer interface {
+	SanitizePartial(content string) string
+}
+
+type SettingsMessage struct {
+	TenantKey         string
+	Channel           string
+	StaffID           string
+	UnionID           string
+	DisplayName       string
+	Department        string
+	Text              string
+	ConversationType  string
+	ConversationID    string
+	ConversationTitle string
+}
+
+type SettingsRouter interface {
+	Handle(context.Context, SettingsMessage) (handled bool, reply string, err error)
+}
+
+type ReasoningMessage struct {
+	TenantKey      string
+	Channel        string
+	StaffID        string
+	Text           string
+	ConversationID string
+}
+
+type ReasoningDecision struct {
+	Handled   bool
+	Reply     string
+	Query     string
+	AgentID   string
+	Execution reasoningmode.ExecutionMode
+	Expired   bool
+}
+
+type ReasoningRouter interface {
+	Prepare(context.Context, ReasoningMessage) (ReasoningDecision, error)
+}
+
+type LanguagePreferenceResolver interface {
+	GetPreference(context.Context, string, string, string) (string, error)
+}
+
 // FinalCardSender sends an AI card as the final reply. Implementations must
 // not log err, outTrackID, or content at any level.
 type FinalCardSender interface {
@@ -87,8 +152,14 @@ type StreamingCardSender interface {
 }
 
 type HandlerOptions struct {
-	ImageDownloader ImageDownloader
-	CardSender      FinalCardSender
+	ImageDownloader  ImageDownloader
+	ImagePublisher   ImagePublisher
+	CardSender       FinalCardSender
+	Directory        UserDirectory
+	OutboundRewriter OutboundContentRewriter
+	SettingsRouter   SettingsRouter
+	ReasoningRouter  ReasoningRouter
+	LanguageResolver LanguagePreferenceResolver
 }
 
 type Handler struct {
@@ -96,7 +167,13 @@ type Handler struct {
 	qa                   QAAsker
 	reply                MarkdownSender
 	downloader           ImageDownloader
+	imagePublisher       ImagePublisher
 	card                 FinalCardSender
+	directory            UserDirectory
+	outboundRewriter     OutboundContentRewriter
+	settingsRouter       SettingsRouter
+	reasoningRouter      ReasoningRouter
+	languageResolver     LanguagePreferenceResolver
 	now                  func() time.Time
 	cardUpdateInterval   time.Duration
 	finalDeliveryTimeout time.Duration
@@ -136,7 +213,13 @@ func NewHandlerWithOptions(cfg TenantConfig, qa QAAsker, reply MarkdownSender, o
 		qa:                   qa,
 		reply:                reply,
 		downloader:           opts.ImageDownloader,
+		imagePublisher:       opts.ImagePublisher,
 		card:                 opts.CardSender,
+		directory:            opts.Directory,
+		outboundRewriter:     opts.OutboundRewriter,
+		settingsRouter:       opts.SettingsRouter,
+		reasoningRouter:      opts.ReasoningRouter,
+		languageResolver:     opts.LanguageResolver,
 		now:                  time.Now,
 		cardUpdateInterval:   500 * time.Millisecond,
 		finalDeliveryTimeout: defaultHTTPTimeout,
@@ -170,13 +253,60 @@ func (h *Handler) Handle(ctx context.Context, cb BotCallback) error {
 		return errors.New("dingtalk handler: sender staffId/senderId is required")
 	}
 
+	triggerPerson := strings.TrimSpace(cb.SenderNick)
+	senderName := triggerPerson
+	department := ""
+	region := ""
+	actorUnionID := ""
+	if h.directory != nil {
+		profile, _ := h.directory.ResolveUser(ctx, h.cfg.TenantKey, externalUserID, senderName)
+		if name := strings.TrimSpace(profile.Name); name != "" {
+			senderName = name
+			department = strings.TrimSpace(profile.DepartmentName)
+			region = strings.TrimSpace(profile.Region)
+		}
+		actorUnionID = strings.TrimSpace(profile.UnionID)
+	}
+	// Trigger person snapshot falls back to official name when callback nick is blank.
+	if triggerPerson == "" {
+		triggerPerson = senderName
+	}
+
+	if h.settingsRouter != nil && strings.EqualFold(strings.TrimSpace(cb.Msgtype), msgTypeText) {
+		handled, settingsReply, err := h.settingsRouter.Handle(ctx, SettingsMessage{
+			TenantKey: h.cfg.TenantKey, Channel: h.cfg.Channel, StaffID: externalUserID,
+			UnionID: actorUnionID, DisplayName: senderName, Department: department, Text: strings.TrimSpace(cb.Text),
+			ConversationType: mapDingTalkConversationType(cb.ConversationType),
+			ConversationID:   strings.TrimSpace(cb.ConversationID), ConversationTitle: strings.TrimSpace(cb.ConversationTitle),
+		})
+		if err != nil {
+			return fmt.Errorf("dingtalk settings: %w", err)
+		}
+		if handled {
+			if strings.TrimSpace(settingsReply) == "" {
+				return nil
+			}
+			return h.sendReply(ctx, webhookURL, settingsReply)
+		}
+	}
+
 	req := core.QARequest{
-		TenantKey:         h.cfg.TenantKey,
-		Channel:           h.cfg.Channel,
-		ExternalUserID:    externalUserID,
-		ExternalMessageID: strings.TrimSpace(cb.MsgID),
-		SenderName:        cb.SenderNick,
-		MessageType:       strings.ToLower(strings.TrimSpace(cb.Msgtype)),
+		TenantKey:             h.cfg.TenantKey,
+		Channel:               h.cfg.Channel,
+		ExternalUserID:        externalUserID,
+		ExternalMessageID:     strings.TrimSpace(cb.MsgID),
+		SenderName:            senderName,
+		TriggerPersonSnapshot: triggerPerson,
+		ActorUnionIDSnapshot:  actorUnionID,
+		Department:            department,
+		Region:                region,
+		MessageType:           strings.ToLower(strings.TrimSpace(cb.Msgtype)),
+		ConversationTitle:     strings.TrimSpace(cb.ConversationTitle),
+	}
+	if h.languageResolver != nil {
+		if locale, err := h.languageResolver.GetPreference(ctx, h.cfg.TenantKey, h.cfg.Channel, externalUserID); err == nil {
+			req.ResponseLocale = strings.TrimSpace(locale)
+		}
 	}
 	switch cb.ConversationType {
 	case conversationTypeGroup:
@@ -187,6 +317,7 @@ func (h *Handler) Handle(ctx context.Context, cb BotCallback) error {
 		req.ExternalChatID = strings.TrimSpace(cb.ConversationID)
 	default:
 		req.ConversationType = core.ConversationDirect
+		req.ConversationTitle = ""
 	}
 
 	switch strings.ToLower(strings.TrimSpace(cb.Msgtype)) {
@@ -196,7 +327,8 @@ func (h *Handler) Handle(ctx context.Context, cb BotCallback) error {
 			return errors.New("dingtalk handler: text message content is empty")
 		}
 	case msgTypePicture:
-		if strings.TrimSpace(cb.DownloadCode) == "" {
+		codes := effectiveDownloadCodes(cb)
+		if len(codes) == 0 {
 			log.Printf("DingTalk image preparation failed: stage=missing_download_code")
 			return h.sendReply(ctx, webhookURL, imageErrorReply)
 		}
@@ -204,20 +336,49 @@ func (h *Handler) Handle(ctx context.Context, cb BotCallback) error {
 			log.Printf("DingTalk image preparation failed: stage=downloader_unavailable")
 			return h.sendReply(ctx, webhookURL, imageErrorReply)
 		}
-		image, err := h.downloader.Download(ctx, strings.TrimSpace(cb.DownloadCode))
-		if err != nil {
-			log.Printf("DingTalk image preparation failed: stage=%s", imageFailureStage(err))
-			return h.sendReply(ctx, webhookURL, imageErrorReply)
+		images := make([]core.ImageInput, 0, len(codes))
+		for _, code := range codes {
+			image, err := h.downloader.Download(ctx, code)
+			if err != nil {
+				log.Printf("DingTalk image preparation failed: stage=%s", imageFailureStage(err))
+				return h.sendReply(ctx, webhookURL, imageErrorReply)
+			}
+			if h.imagePublisher != nil {
+				if url := h.publishQuestionImage(ctx, image); url != "" {
+					image.PublishedURL = url
+				}
+			}
+			images = append(images, image)
 		}
 		req.Query = strings.TrimSpace(cb.Text)
 		if req.Query == "" {
 			req.Query = imageQuery
 		}
-		req.Images = []core.ImageInput{image}
+		req.Images = images
 	default:
 		return h.sendReply(ctx, webhookURL, unsupportedMessageReply)
 	}
 
+	if h.reasoningRouter != nil {
+		decision, err := h.reasoningRouter.Prepare(ctx, ReasoningMessage{
+			TenantKey: h.cfg.TenantKey, Channel: h.cfg.Channel, StaffID: externalUserID,
+			Text: req.Query, ConversationID: req.ExternalChatID,
+		})
+		if err != nil {
+			return fmt.Errorf("dingtalk reasoning mode: %w", err)
+		}
+		if decision.Handled {
+			if strings.TrimSpace(decision.Reply) == "" {
+				return nil
+			}
+			return h.sendReply(ctx, webhookURL, decision.Reply)
+		}
+		req.Query = strings.TrimSpace(decision.Query)
+		req.AgentIDOverride = strings.TrimSpace(decision.AgentID)
+		req.ReasoningExecution = string(decision.Execution)
+		req.ReasoningExpired = decision.Expired
+	}
+
 	if eventCard, eventQA := h.eventStreamingCapable(); eventCard != nil && eventQA != nil {
 		return h.handleEventStreaming(ctx, webhookURL, req, eventCard, eventQA)
 	}
@@ -229,6 +390,13 @@ func (h *Handler) Handle(ctx context.Context, cb BotCallback) error {
 	return h.handleNonStreaming(ctx, webhookURL, req)
 }
 
+func mapDingTalkConversationType(value string) string {
+	if value == conversationTypeGroup {
+		return "group"
+	}
+	return "direct"
+}
+
 func (h *Handler) eventStreamingCapable() (StreamingCardSender, EventQAAsker) {
 	sc, ok := h.card.(StreamingCardSender)
 	if !ok {
@@ -256,6 +424,7 @@ func (h *Handler) streamingCapable() (StreamingCardSender, StreamingQAAsker) {
 func (h *Handler) handleNonStreaming(ctx context.Context, webhookURL string, req core.QARequest) error {
 	result, err := h.qa.Ask(ctx, req)
 	if err != nil {
+		logQAFailure("non_streaming", err)
 		if replyErr := h.sendReply(ctx, webhookURL, qaErrorReply); replyErr != nil {
 			return replyErr
 		}
@@ -264,13 +433,14 @@ func (h *Handler) handleNonStreaming(ctx context.Context, webhookURL string, req
 	if result.Replayed && result.DeliveryStatus == core.DeliverySent {
 		return nil
 	}
+	content := h.rewriteOutboundContent(ctx, result.Answer)
 
 	if h.card != nil {
 		cardReq := CardRequest{
 			ConversationType: req.ConversationType,
 			ExternalUserID:   req.ExternalUserID,
 			ExternalChatID:   req.ExternalChatID,
-			Content:          result.Answer,
+			Content:          content,
 		}
 		if outTrackID, cardErr := h.card.SendFinalCard(ctx, cardReq); cardErr == nil {
 			h.recordDelivery(ctx, result, core.DeliverySent, core.DeliveryMethodCard, outTrackID, "")
@@ -278,7 +448,7 @@ func (h *Handler) handleNonStreaming(ctx context.Context, webhookURL string, req
 		}
 		log.Printf("DingTalk card delivery failed, falling back to markdown")
 	}
-	if err := h.sendReply(ctx, webhookURL, result.Answer); err != nil {
+	if err := h.sendReply(ctx, webhookURL, content); err != nil {
 		h.recordDelivery(ctx, result, core.DeliveryFailed, "", "", core.DeliveryFailureChannelDelivery)
 		return err
 	}
@@ -299,6 +469,7 @@ func (h *Handler) handleStreaming(ctx context.Context, webhookURL string, req co
 		// Fallback: Ask → Markdown only (no SendFinalCard, no AskStream)
 		result, askErr := h.qa.Ask(ctx, req)
 		if askErr != nil {
+			logQAFailure("streaming_fallback", askErr)
 			if replyErr := h.sendReply(ctx, webhookURL, qaErrorReply); replyErr != nil {
 				return replyErr
 			}
@@ -307,7 +478,8 @@ func (h *Handler) handleStreaming(ctx context.Context, webhookURL string, req co
 		if result.Replayed && result.DeliveryStatus == core.DeliverySent {
 			return nil
 		}
-		if replyErr := h.sendReply(ctx, webhookURL, result.Answer); replyErr != nil {
+		content := h.rewriteOutboundContent(ctx, result.Answer)
+		if replyErr := h.sendReply(ctx, webhookURL, content); replyErr != nil {
 			h.recordDelivery(ctx, result, core.DeliveryFailed, "", "", core.DeliveryFailureChannelDelivery)
 			return replyErr
 		}
@@ -317,24 +489,33 @@ func (h *Handler) handleStreaming(ctx context.Context, webhookURL string, req co
 
 	// Streaming observer with the configured update throttle (500ms by default).
 	var lastUpdate time.Time
+	var lastPartialContent string
 	observer := func(fullContent string) {
 		if strings.TrimSpace(fullContent) == "" {
 			return
 		}
+		fullContent = decorateReasoningPartial(fullContent, req.ReasoningExecution)
 		now := h.now()
 		if lastUpdate.IsZero() || now.Sub(lastUpdate) >= h.cardUpdateInterval {
+			partialContent := h.sanitizeOutboundPartial(fullContent)
+			if strings.TrimSpace(partialContent) == "" || partialContent == lastPartialContent {
+				return
+			}
 			// Advance the throttle window before I/O so a failing DingTalk API
 			// cannot be hammered once per model chunk. The final update below is
 			// always attempted regardless of this timestamp.
 			lastUpdate = now
-			if updateErr := streamingCard.UpdateCard(ctx, outTrackID, fullContent, false, false); updateErr != nil {
+			if updateErr := streamingCard.UpdateCard(ctx, outTrackID, partialContent, false, false); updateErr != nil {
 				log.Printf("DingTalk streaming card update failed, continuing")
+				return
 			}
+			lastPartialContent = partialContent
 		}
 	}
 
 	result, err := streamingQA.AskStream(ctx, req, observer)
 	if err != nil || strings.TrimSpace(result.Answer) == "" {
+		logQAFailure("streaming", errOrEmptyAnswer(err, result.Answer))
 		return h.finalizeCardOrMarkdown(ctx, webhookURL, streamingCard, outTrackID, core.QAResult{}, qaErrorReply, true)
 	}
 	return h.finalizeCardOrMarkdown(ctx, webhookURL, streamingCard, outTrackID, result, result.Answer, false)
@@ -352,12 +533,14 @@ func (h *Handler) handleEventStreaming(ctx context.Context, webhookURL string, r
 		log.Printf("DingTalk event card start failed, falling back to markdown")
 		result, askErr := h.qa.Ask(ctx, req)
 		if askErr != nil {
+			logQAFailure("event_fallback", askErr)
 			return h.sendReply(ctx, webhookURL, qaErrorReply)
 		}
 		if result.Replayed && result.DeliveryStatus == core.DeliverySent {
 			return nil
 		}
-		if replyErr := h.sendReply(ctx, webhookURL, result.Answer); replyErr != nil {
+		content := h.rewriteOutboundContent(ctx, result.Answer)
+		if replyErr := h.sendReply(ctx, webhookURL, content); replyErr != nil {
 			h.recordDelivery(ctx, result, core.DeliveryFailed, "", "", core.DeliveryFailureChannelDelivery)
 			return replyErr
 		}
@@ -372,7 +555,10 @@ func (h *Handler) handleEventStreaming(ctx context.Context, webhookURL string, r
 	result, err := eventQA.AskEvents(ctx, req, func(event weknora.StreamEvent) {
 		if event.ResponseType == "answer" && strings.TrimSpace(event.FullAnswer) != "" {
 			answerStarted = true
-			pump.Offer(event.FullAnswer)
+			visibleAnswer := decorateReasoningPartial(event.FullAnswer, req.ReasoningExecution)
+			if partialContent := h.sanitizeOutboundPartial(visibleAnswer); strings.TrimSpace(partialContent) != "" {
+				pump.Offer(partialContent)
+			}
 			return
 		}
 		if answerStarted {
@@ -387,17 +573,32 @@ func (h *Handler) handleEventStreaming(ctx context.Context, webhookURL string, r
 	pump.Stop()
 
 	if err != nil || strings.TrimSpace(result.Answer) == "" {
+		logQAFailure("event_streaming", errOrEmptyAnswer(err, result.Answer))
 		return h.finalizeCardOrMarkdown(ctx, webhookURL, streamingCard, outTrackID, core.QAResult{}, qaErrorReply, true)
 	}
 	return h.finalizeCardOrMarkdown(ctx, webhookURL, streamingCard, outTrackID, result, result.Answer, false)
 }
 
+func decorateReasoningPartial(content, execution string) string {
+	switch reasoningmode.ExecutionMode(strings.TrimSpace(execution)) {
+	case reasoningmode.ExecutionReasoning, reasoningmode.ExecutionReasoningSingle:
+		if !strings.HasPrefix(content, "【智能推理模式】") {
+			return "【智能推理模式】\n\n" + content
+		}
+	}
+	return content
+}
+
 func (h *Handler) finalizeCardOrMarkdown(ctx context.Context, webhookURL string, streamingCard StreamingCardSender, outTrackID string, result core.QAResult, content string, isError bool) error {
 	timeout := h.finalDeliveryTimeout
 	if timeout <= 0 {
 		timeout = defaultHTTPTimeout
 	}
 
+	if !isError {
+		content = h.rewriteOutboundContent(ctx, content)
+	}
+
 	// Final card convergence must still be attempted when the QA context was
 	// canceled or timed out; otherwise the card can remain "processing".
 	finalCtx, cancelFinal := context.WithTimeout(context.WithoutCancel(ctx), timeout)
@@ -426,6 +627,27 @@ func (h *Handler) finalizeCardOrMarkdown(ctx context.Context, webhookURL string,
 	return nil
 }
 
+func (h *Handler) rewriteOutboundContent(ctx context.Context, content string) string {
+	if h.outboundRewriter == nil {
+		return sanitizeDisplayAnswer(content)
+	}
+	timeout := h.finalDeliveryTimeout
+	if timeout <= 0 {
+		timeout = defaultHTTPTimeout
+	}
+	rewriteCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), timeout)
+	defer cancel()
+	return sanitizeDisplayAnswer(h.outboundRewriter.Rewrite(rewriteCtx, content))
+}
+
+func (h *Handler) sanitizeOutboundPartial(content string) string {
+	sanitizer, ok := h.outboundRewriter.(OutboundPartialSanitizer)
+	if ok {
+		content = sanitizer.SanitizePartial(content)
+	}
+	return stableMarkdownPrefix(sanitizeDisplayAnswer(content))
+}
+
 func (h *Handler) recordDelivery(ctx context.Context, result core.QAResult, status, method, providerMessageID, failureCode string) {
 	if strings.TrimSpace(result.TurnID) == "" || strings.TrimSpace(result.AnswerMessageID) == "" {
 		return
@@ -477,6 +699,50 @@ func renderProgressEvent(event weknora.StreamEvent) string {
 	return ""
 }
 
+func errOrEmptyAnswer(err error, answer string) error {
+	if err != nil {
+		return err
+	}
+	if strings.TrimSpace(answer) == "" {
+		return weknora.ErrEmptyAnswer
+	}
+	return nil
+}
+
+func logQAFailure(mode string, err error) {
+	log.Printf("DingTalk QA failed: mode=%s stage=%s", mode, qaFailureStage(err))
+}
+
+func qaFailureStage(err error) string {
+	switch {
+	case err == nil:
+		return "unknown"
+	case errors.Is(err, context.Canceled):
+		return "context_canceled"
+	case errors.Is(err, context.DeadlineExceeded):
+		return "context_deadline"
+	case errors.Is(err, core.ErrTurnInProgress):
+		return "duplicate_or_in_progress"
+	case errors.Is(err, weknora.ErrEmptyAnswer):
+		return "empty_answer"
+	}
+	message := strings.ToLower(err.Error())
+	switch {
+	case strings.Contains(message, "begin turn"):
+		return "begin_turn"
+	case strings.Contains(message, "agent") && strings.Contains(message, "binding"):
+		return "agent_binding"
+	case strings.Contains(message, "session"):
+		return "session"
+	case strings.Contains(message, "weknora agent chat"):
+		return "agent_chat"
+	case strings.Contains(message, "required") || strings.Contains(message, "unsupported"):
+		return "validation"
+	default:
+		return "unknown"
+	}
+}
+
 func imageFailureStage(err error) string {
 	message := strings.ToLower(err.Error())
 	switch {
@@ -504,3 +770,57 @@ func (h *Handler) sendReply(ctx context.Context, webhookURL, text string) error
 	}
 	return nil
 }
+
+// publishQuestionImage best-effort publishes a downloaded image's bytes to
+// object storage for traceability. It returns the stable HTTPS URL, or an
+// empty string when publishing is unavailable or fails, so that an image
+// question is never blocked by storage.
+func (h *Handler) publishQuestionImage(ctx context.Context, image core.ImageInput) string {
+	if h.imagePublisher == nil {
+		return ""
+	}
+	data, err := decodeImageDataURI(image.DataURI)
+	if err != nil || len(data) == 0 {
+		log.Printf("DingTalk question image publish failed: stage=decode")
+		return ""
+	}
+	url, err := h.imagePublisher.Publish(ctx, data, image.MIMEType)
+	if err != nil || strings.TrimSpace(url) == "" {
+		log.Printf("DingTalk question image publish failed: stage=publish")
+		return ""
+	}
+	return strings.TrimSpace(url)
+}
+
+// decodeImageDataURI strips the "data:<mime>;base64," prefix and decodes the
+// payload into raw bytes. It is used only to publish inbound images and never
+// writes the data URI to storage.
+func decodeImageDataURI(dataURI string) ([]byte, error) {
+	const prefix = "base64,"
+	index := strings.Index(dataURI, prefix)
+	if index < 0 {
+		return nil, errors.New("dingtalk image: data URI missing base64 payload")
+	}
+	return base64.StdEncoding.DecodeString(dataURI[index+len(prefix):])
+}
+
+// effectiveDownloadCodes returns the ordered, de-duplicated list of image
+// download codes for a picture callback. DownloadCode equals the first code
+// and DownloadCodes holds every code (richText with several pictures), so the
+// single value is used to canonicalize the order without duplication.
+func effectiveDownloadCodes(cb BotCallback) []string {
+	var codes []string
+	seen := make(map[string]struct{})
+	for _, code := range append([]string{cb.DownloadCode}, cb.DownloadCodes...) {
+		code = strings.TrimSpace(code)
+		if code == "" {
+			continue
+		}
+		if _, ok := seen[code]; ok {
+			continue
+		}
+		seen[code] = struct{}{}
+		codes = append(codes, code)
+	}
+	return codes
+}

internal/channels/dingtalk/handler_test.go

@@ -3,11 +3,13 @@ package dingtalk
 import (
 	"context"
 	"errors"
+	"reflect"
 	"strings"
 	"testing"
 	"time"
 
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/core"
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/directory"
 	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/weknora"
 )
 
@@ -31,6 +33,17 @@ func (f *fakeQA) RecordDelivery(_ context.Context, update core.DeliveryUpdate) e
 	return f.deliveryErr
 }
 
+type fakeDirectory struct {
+	profile directory.Profile
+	err     error
+	calls   int
+}
+
+func (f *fakeDirectory) ResolveUser(context.Context, string, string, string) (directory.Profile, error) {
+	f.calls++
+	return f.profile, f.err
+}
+
 type fakeReply struct {
 	called    bool
 	lastURL   string
@@ -192,6 +205,44 @@ func TestHandleDirectTextCallsQAAndRepliesAnswer(t *testing.T) {
 	}
 }
 
+func TestHandleDirectUsesDirectoryProfile(t *testing.T) {
+	qa := &fakeQA{result: core.QAResult{Answer: "ok"}}
+	reply := &fakeReply{}
+	profiles := &fakeDirectory{profile: directory.Profile{Name: "张三", DepartmentName: "技术支持部", Region: "APAC"}}
+	h, err := NewHandlerWithOptions(TenantConfig{TenantKey: "tenant-a", Channel: "dingtalk"}, qa, reply, HandlerOptions{Directory: profiles})
+	if err != nil {
+		t.Fatalf("NewHandlerWithOptions: %v", err)
+	}
+	data := directTextCallback()
+	data.SenderNick = "钉钉昵称"
+	if err := h.Handle(context.Background(), data); err != nil {
+		t.Fatalf("Handle: %v", err)
+	}
+	if profiles.calls != 1 || qa.lastReq.SenderName != "张三" || qa.lastReq.Department != "技术支持部" || qa.lastReq.Region != "APAC" {
+		t.Fatalf("calls=%d request=%+v", profiles.calls, qa.lastReq)
+	}
+}
+
+// TestHandleDirectoryFailureFallsBackToSenderNick validates that when directory
+// resolution fails, SenderName falls back to the callback SenderNick.
+func TestHandleDirectoryFailureFallsBackToSenderNick(t *testing.T) {
+	qa := &fakeQA{result: core.QAResult{Answer: "ok"}}
+	reply := &fakeReply{}
+	profiles := &fakeDirectory{err: errors.New("directory unavailable")}
+	h, err := NewHandlerWithOptions(TenantConfig{TenantKey: "tenant-a", Channel: "dingtalk"}, qa, reply, HandlerOptions{Directory: profiles})
+	if err != nil {
+		t.Fatalf("NewHandlerWithOptions: %v", err)
+	}
+	data := directTextCallback()
+	data.SenderNick = "  回调昵称  "
+	if err := h.Handle(context.Background(), data); err != nil {
+		t.Fatalf("Handle: %v", err)
+	}
+	if qa.lastReq.SenderName != "回调昵称" || qa.lastReq.Department != "" || qa.lastReq.Region != "" {
+		t.Fatalf("request=%+v", qa.lastReq)
+	}
+}
+
 func TestHandleDirectTextFallsBackToSenderID(t *testing.T) {
 	qa := &fakeQA{result: core.QAResult{Answer: "ok"}}
 	reply := &fakeReply{}
@@ -676,6 +727,46 @@ func TestHandleCardSuccessDirectFieldsCorrectNoMarkdown(t *testing.T) {
 	}
 }
 
+func TestHandleNonStreamingRewritesFinalCardAndMarkdownFallback(t *testing.T) {
+	resource := "resource://AbCdEfGhIjKlMnOpQrStUv"
+	signed := "https://img.example/signed.jpg"
+	answer := "说明\n![图](" + resource + ")"
+	for _, tc := range []struct {
+		name      string
+		cardErr   error
+		wantReply bool
+	}{
+		{name: "card"},
+		{name: "markdown fallback", cardErr: errors.New("card failed"), wantReply: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			qa := &fakeQA{result: core.QAResult{Answer: answer}}
+			reply := &fakeReply{}
+			card := &fakeCard{returnID: "track", err: tc.cardErr}
+			h := newTestHandlerWithCard(t, qa, reply, card)
+			rewriter := &fakeOutboundRewriter{from: resource, to: signed}
+			h.outboundRewriter = rewriter
+
+			if err := h.Handle(context.Background(), directTextCallback()); err != nil {
+				t.Fatal(err)
+			}
+			if !card.called || reply.called != tc.wantReply {
+				t.Fatalf("card=%t reply=%t", card.called, reply.called)
+			}
+			content := card.lastReq.Content
+			if tc.wantReply {
+				content = reply.lastText
+			}
+			if strings.Contains(content, resource) || !strings.Contains(content, signed) {
+				t.Fatalf("outbound content=%q", content)
+			}
+			if rewriter.calls != 1 {
+				t.Fatalf("rewrite calls=%d, want 1", rewriter.calls)
+			}
+		})
+	}
+}
+
 func TestHandleCardSuccessGroupChatIDCorrect(t *testing.T) {
 	qa := &fakeQA{result: core.QAResult{Answer: "group card answer"}}
 	reply := &fakeReply{}
@@ -890,6 +981,23 @@ type cardUpdate struct {
 	isError    bool
 }
 
+type fakeOutboundRewriter struct {
+	calls        int
+	partialCalls int
+	from         string
+	to           string
+}
+
+func (f *fakeOutboundRewriter) Rewrite(_ context.Context, content string) string {
+	f.calls++
+	return strings.ReplaceAll(content, f.from, f.to)
+}
+
+func (f *fakeOutboundRewriter) SanitizePartial(content string) string {
+	f.partialCalls++
+	return strings.ReplaceAll(content, f.from, "")
+}
+
 func (f *fakeStreamingCard) SendFinalCard(_ context.Context, req CardRequest) (string, error) {
 	f.finalCalled = true
 	f.finalReq = req
@@ -1073,11 +1181,14 @@ func TestHandleStreamingThrottleClockAdvances(t *testing.T) {
 
 func TestHandleStreamingStartFailsFallbackAskMarkdown(t *testing.T) {
 	card := &fakeStreamingCard{startErr: errors.New("card API unavailable")}
+	resource := "resource://AbCdEfGhIjKlMnOpQrStUv"
 	qa := &fakeStreamingQA{
-		result: core.QAResult{Answer: "**fallback markdown**"},
+		result: core.QAResult{Answer: "**fallback markdown**\n![图](" + resource + ")"},
 	}
 	reply := &fakeReply{}
 	h := newTestHandlerWithStreaming(t, qa, reply, card)
+	rewriter := &fakeOutboundRewriter{from: resource, to: "https://img.example/signed.jpg"}
+	h.outboundRewriter = rewriter
 
 	err := h.Handle(context.Background(), directTextCallback())
 	if err != nil {
@@ -1106,8 +1217,11 @@ func TestHandleStreamingStartFailsFallbackAskMarkdown(t *testing.T) {
 	if !reply.called {
 		t.Fatal("SendMarkdown must be called on Start failure")
 	}
-	if reply.lastText != "**fallback markdown**" {
-		t.Fatalf("markdown text = %q, want fallback markdown", reply.lastText)
+	if strings.Contains(reply.lastText, resource) || !strings.Contains(reply.lastText, "https://img.example/signed.jpg") {
+		t.Fatalf("markdown text = %q, want rewritten fallback markdown", reply.lastText)
+	}
+	if rewriter.calls != 1 {
+		t.Fatalf("rewrite calls=%d, want 1", rewriter.calls)
 	}
 
 	// No card updates
@@ -1561,15 +1675,16 @@ func TestRenderProgressEventUsesOnlySafeFixedText(t *testing.T) {
 }
 
 func TestHandleEventStreamingFinalizesLatestAnswerWithoutMarkdown(t *testing.T) {
+	rawAnswer := "完整答案[[ref id=\"c8\"]]"
 	card := &fakeStreamingCard{startID: "track-events"}
 	qa := &fakeEventQA{
-		fakeStreamingQA: fakeStreamingQA{result: core.QAResult{Answer: "完整答案"}},
+		fakeStreamingQA: fakeStreamingQA{result: core.QAResult{Answer: rawAnswer}},
 		events: []weknora.StreamEvent{
 			{ResponseType: "tool_call", ToolName: "query_understand"},
 			{ResponseType: "tool_call", ToolName: "knowledge_search"},
 			{ResponseType: "references", ReferenceCount: 3},
-			{ResponseType: "answer", FullAnswer: "部分"},
-			{ResponseType: "answer", FullAnswer: "完整答案", Done: true},
+			{ResponseType: "answer", FullAnswer: "部分[[ref"},
+			{ResponseType: "answer", FullAnswer: rawAnswer, Done: true},
 		},
 	}
 	reply := &fakeReply{}
@@ -1591,6 +1706,9 @@ func TestHandleEventStreamingFinalizesLatestAnswerWithoutMarkdown(t *testing.T)
 	if last.content != "完整答案" || !last.isFinalize || last.isError {
 		t.Fatalf("final update=%+v", last)
 	}
+	if qa.result.Answer != rawAnswer {
+		t.Fatalf("raw QA answer mutated: %q", qa.result.Answer)
+	}
 	if reply.called {
 		t.Fatal("SendMarkdown must not be called")
 	}
@@ -1796,3 +1914,313 @@ func TestDeliveryAuditEventStreamingProductionPath(t *testing.T) {
 	}
 	requireDelivery(t, qa.deliveries, core.DeliverySent, core.DeliveryMethodCard, "event-track-1", "")
 }
+
+func TestHandlePassesConversationTitleToQARequest(t *testing.T) {
+	qa := &fakeQA{result: core.QAResult{Answer: "ok"}}
+	reply := &fakeReply{}
+	h := newTestHandler(t, qa, reply)
+
+	t.Run("group conversation title propagated", func(t *testing.T) {
+		cb := groupTextCallback()
+		cb.ConversationTitle = "项目讨论群"
+		if err := h.Handle(context.Background(), cb); err != nil {
+			t.Fatalf("Handle: %v", err)
+		}
+		if qa.lastReq.ConversationTitle != "项目讨论群" {
+			t.Fatalf("ConversationTitle = %q, want 项目讨论群", qa.lastReq.ConversationTitle)
+		}
+	})
+
+	t.Run("direct conversation title is empty", func(t *testing.T) {
+		qa2 := &fakeQA{result: core.QAResult{Answer: "ok"}}
+		h2 := newTestHandler(t, qa2, &fakeReply{})
+		cb := directTextCallback()
+		cb.ConversationTitle = "should not appear"
+		if err := h2.Handle(context.Background(), cb); err != nil {
+			t.Fatalf("Handle: %v", err)
+		}
+		if qa2.lastReq.ConversationTitle != "" {
+			t.Fatalf("ConversationTitle = %q, want empty for direct", qa2.lastReq.ConversationTitle)
+		}
+	})
+}
+
+// TestActorUnionIDSnapshotPropagation verifies the actor_union_id_snapshot
+// is populated from the directory profile UnionID when available.
+func TestActorUnionIDSnapshotPropagation(t *testing.T) {
+	t.Run("resolved profile with union ID captures snapshot", func(t *testing.T) {
+		qa := &fakeQA{result: core.QAResult{Answer: "ok"}}
+		reply := &fakeReply{}
+		profiles := &fakeDirectory{profile: directory.Profile{
+			Name: "张三", UnionID: "union-abc-123", DepartmentName: "技术部", Region: "APAC",
+		}}
+		h, err := NewHandlerWithOptions(TenantConfig{TenantKey: "tenant-a", Channel: "dingtalk"}, qa, reply, HandlerOptions{Directory: profiles})
+		if err != nil {
+			t.Fatalf("NewHandlerWithOptions: %v", err)
+		}
+		data := directTextCallback()
+		data.SenderNick = "钉钉昵称"
+		if err := h.Handle(context.Background(), data); err != nil {
+			t.Fatalf("Handle: %v", err)
+		}
+		if qa.lastReq.ActorUnionIDSnapshot != "union-abc-123" {
+			t.Fatalf("ActorUnionIDSnapshot = %q, want union-abc-123", qa.lastReq.ActorUnionIDSnapshot)
+		}
+		if qa.lastReq.SenderName != "张三" {
+			t.Fatalf("SenderName = %q, want 张三", qa.lastReq.SenderName)
+		}
+		if qa.lastReq.TriggerPersonSnapshot != "钉钉昵称" {
+			t.Fatalf("TriggerPersonSnapshot = %q, want 钉钉昵称", qa.lastReq.TriggerPersonSnapshot)
+		}
+	})
+
+	t.Run("blank profile union leaves snapshot empty", func(t *testing.T) {
+		qa := &fakeQA{result: core.QAResult{Answer: "ok"}}
+		reply := &fakeReply{}
+		profiles := &fakeDirectory{profile: directory.Profile{
+			Name: "张三", UnionID: "", DepartmentName: "技术部", Region: "APAC",
+		}}
+		h, err := NewHandlerWithOptions(TenantConfig{TenantKey: "tenant-a", Channel: "dingtalk"}, qa, reply, HandlerOptions{Directory: profiles})
+		if err != nil {
+			t.Fatalf("NewHandlerWithOptions: %v", err)
+		}
+		data := directTextCallback()
+		data.SenderNick = "钉钉昵称"
+		if err := h.Handle(context.Background(), data); err != nil {
+			t.Fatalf("Handle: %v", err)
+		}
+		if qa.lastReq.ActorUnionIDSnapshot != "" {
+			t.Fatalf("ActorUnionIDSnapshot = %q, want empty", qa.lastReq.ActorUnionIDSnapshot)
+		}
+	})
+
+	t.Run("directory failure leaves union snapshot empty", func(t *testing.T) {
+		qa := &fakeQA{result: core.QAResult{Answer: "ok"}}
+		reply := &fakeReply{}
+		profiles := &fakeDirectory{err: errors.New("directory unavailable")}
+		h, err := NewHandlerWithOptions(TenantConfig{TenantKey: "tenant-a", Channel: "dingtalk"}, qa, reply, HandlerOptions{Directory: profiles})
+		if err != nil {
+			t.Fatalf("NewHandlerWithOptions: %v", err)
+		}
+		data := directTextCallback()
+		data.SenderNick = "钉钉昵称"
+		if err := h.Handle(context.Background(), data); err != nil {
+			t.Fatalf("Handle: %v", err)
+		}
+		if qa.lastReq.ActorUnionIDSnapshot != "" {
+			t.Fatalf("ActorUnionIDSnapshot = %q, want empty on directory failure", qa.lastReq.ActorUnionIDSnapshot)
+		}
+	})
+
+	t.Run("no directory leaves union snapshot empty", func(t *testing.T) {
+		qa := &fakeQA{result: core.QAResult{Answer: "ok"}}
+		reply := &fakeReply{}
+		h := newTestHandler(t, qa, reply)
+		data := directTextCallback()
+		data.SenderNick = "钉钉昵称"
+		if err := h.Handle(context.Background(), data); err != nil {
+			t.Fatalf("Handle: %v", err)
+		}
+		if qa.lastReq.ActorUnionIDSnapshot != "" {
+			t.Fatalf("ActorUnionIDSnapshot = %q, want empty without directory", qa.lastReq.ActorUnionIDSnapshot)
+		}
+	})
+}
+
+// TestTriggerPersonSnapshotRegression proves the trigger_person_snapshot
+// contract: the callback SenderNick becomes TriggerPersonSnapshot, the
+// directory official Name remains SenderName, and a blank callback nick
+// falls back to the official name.
+func TestTriggerPersonSnapshotRegression(t *testing.T) {
+	t.Run("callback nick becomes trigger person snapshot", func(t *testing.T) {
+		qa := &fakeQA{result: core.QAResult{Answer: "ok"}}
+		reply := &fakeReply{}
+		profiles := &fakeDirectory{profile: directory.Profile{Name: "张三", DepartmentName: "技术部", Region: "APAC"}}
+		h, err := NewHandlerWithOptions(TenantConfig{TenantKey: "tenant-a", Channel: "dingtalk"}, qa, reply, HandlerOptions{Directory: profiles})
+		if err != nil {
+			t.Fatalf("NewHandlerWithOptions: %v", err)
+		}
+		data := directTextCallback()
+		data.SenderNick = "钉钉昵称"
+		if err := h.Handle(context.Background(), data); err != nil {
+			t.Fatalf("Handle: %v", err)
+		}
+		if qa.lastReq.TriggerPersonSnapshot != "钉钉昵称" {
+			t.Fatalf("TriggerPersonSnapshot = %q, want 钉钉昵称", qa.lastReq.TriggerPersonSnapshot)
+		}
+		if qa.lastReq.SenderName != "张三" {
+			t.Fatalf("SenderName = %q, want 张三", qa.lastReq.SenderName)
+		}
+	})
+
+	t.Run("blank callback nick falls back to official name", func(t *testing.T) {
+		qa := &fakeQA{result: core.QAResult{Answer: "ok"}}
+		reply := &fakeReply{}
+		profiles := &fakeDirectory{profile: directory.Profile{Name: "张三", DepartmentName: "技术部", Region: "APAC"}}
+		h, err := NewHandlerWithOptions(TenantConfig{TenantKey: "tenant-a", Channel: "dingtalk"}, qa, reply, HandlerOptions{Directory: profiles})
+		if err != nil {
+			t.Fatalf("NewHandlerWithOptions: %v", err)
+		}
+		data := directTextCallback()
+		data.SenderNick = ""
+		if err := h.Handle(context.Background(), data); err != nil {
+			t.Fatalf("Handle: %v", err)
+		}
+		if qa.lastReq.TriggerPersonSnapshot != "张三" {
+			t.Fatalf("TriggerPersonSnapshot = %q, want 张三 on blank nick", qa.lastReq.TriggerPersonSnapshot)
+		}
+		if qa.lastReq.SenderName != "张三" {
+			t.Fatalf("SenderName = %q, want 张三", qa.lastReq.SenderName)
+		}
+	})
+}
+
+func TestHandleStreamingRewritesOnlyFinalOutboundImageContent(t *testing.T) {
+	card := &fakeStreamingCard{startID: "track-image-final"}
+	resource := "resource://AbCdEfGhIjKlMnOpQrStUv"
+	answer := "操作说明\n![步骤图](" + resource + ")"
+	qa := &fakeStreamingQA{chunks: []string{answer}, result: core.QAResult{Answer: answer}}
+	reply := &fakeReply{}
+	rewriter := &fakeOutboundRewriter{from: resource, to: "https://img.example/signed.jpg"}
+	h := newTestHandlerWithStreaming(t, qa, reply, card)
+	h.outboundRewriter = rewriter
+
+	if err := h.Handle(context.Background(), directTextCallback()); err != nil {
+		t.Fatal(err)
+	}
+	if len(card.updates) < 2 {
+		t.Fatalf("updates=%d", len(card.updates))
+	}
+	if strings.Contains(card.updates[0].content, resource) {
+		t.Fatalf("streaming intermediate content leaked internal resource: %q", card.updates[0].content)
+	}
+	final := card.updates[len(card.updates)-1]
+	if !final.isFinalize || strings.Contains(final.content, resource) || !strings.Contains(final.content, "https://img.example/signed.jpg") {
+		t.Fatalf("final content=%q finalize=%t", final.content, final.isFinalize)
+	}
+	if rewriter.calls != 1 {
+		t.Fatalf("rewrite calls=%d, want 1", rewriter.calls)
+	}
+	if rewriter.partialCalls == 0 {
+		t.Fatal("streaming intermediate content was not sanitized")
+	}
+}
+
+func TestHandleFiltersReferenceMarkersAtDingTalkDisplayBoundary(t *testing.T) {
+	rawAnswer := "结论[[ref id=\"c2\"]][[ref id=\"c4\"]]。"
+	wantDisplay := "结论。"
+
+	t.Run("final card", func(t *testing.T) {
+		qa := &fakeQA{result: core.QAResult{Answer: rawAnswer}}
+		reply := &fakeReply{}
+		card := &fakeCard{returnID: "track-reference-filter"}
+		h := newTestHandlerWithCard(t, qa, reply, card)
+
+		if err := h.Handle(context.Background(), directTextCallback()); err != nil {
+			t.Fatal(err)
+		}
+		if card.lastReq.Content != wantDisplay {
+			t.Fatalf("card content=%q, want %q", card.lastReq.Content, wantDisplay)
+		}
+		if qa.result.Answer != rawAnswer {
+			t.Fatalf("raw QA answer mutated: %q", qa.result.Answer)
+		}
+	})
+
+	t.Run("markdown fallback", func(t *testing.T) {
+		qa := &fakeQA{result: core.QAResult{Answer: rawAnswer}}
+		reply := &fakeReply{}
+		card := &fakeCard{err: errors.New("card unavailable")}
+		h := newTestHandlerWithCard(t, qa, reply, card)
+
+		if err := h.Handle(context.Background(), directTextCallback()); err != nil {
+			t.Fatal(err)
+		}
+		if reply.lastText != wantDisplay {
+			t.Fatalf("markdown content=%q, want %q", reply.lastText, wantDisplay)
+		}
+		if qa.result.Answer != rawAnswer {
+			t.Fatalf("raw QA answer mutated: %q", qa.result.Answer)
+		}
+	})
+}
+
+func TestHandleStreamingHoldsBackPartialReferenceMarkers(t *testing.T) {
+	rawAnswer := "答案正文[[ref id=\"c2\"]]继续。"
+	qa := &fakeStreamingQA{
+		chunks: []string{"答案正文[[ref", " id=\"c2\"]]继续。"},
+		result: core.QAResult{Answer: rawAnswer},
+	}
+	reply := &fakeReply{}
+	card := &fakeStreamingCard{startID: "track-stream-reference-filter"}
+	h := newTestHandlerWithStreaming(t, qa, reply, card)
+
+	if err := h.Handle(context.Background(), directTextCallback()); err != nil {
+		t.Fatal(err)
+	}
+	if len(card.updates) < 2 {
+		t.Fatalf("updates=%d, want at least one partial plus final", len(card.updates))
+	}
+	for i, update := range card.updates {
+		if strings.Contains(update.content, "[[ref") {
+			t.Fatalf("update[%d] leaked reference marker: %q", i, update.content)
+		}
+	}
+	if card.updates[0].content != "答案正文" {
+		t.Fatalf("first partial=%q, want dangling marker held back", card.updates[0].content)
+	}
+	final := card.updates[len(card.updates)-1]
+	if !final.isFinalize || final.content != "答案正文继续。" {
+		t.Fatalf("final content=%q finalize=%t", final.content, final.isFinalize)
+	}
+	if qa.result.Answer != rawAnswer {
+		t.Fatalf("raw QA answer mutated: %q", qa.result.Answer)
+	}
+}
+
+func TestHandleStreamingPublishesTableOnlyOnFinalUpdate(t *testing.T) {
+	answer := "说明\n\n| 检查项 | 操作要求 |\n| --- | --- |\n| 接地检查 | 上电前确认 |\n\n结论"
+	qa := &fakeStreamingQA{
+		chunks: []string{
+			"说明\n\n",
+			"| 检查项",
+			" | 操作要求 |\n",
+			"| --- | --",
+			"- |\n",
+			"| 接地检查 | 上电前确",
+			"认 |\n\n结论",
+		},
+		result: core.QAResult{Answer: answer},
+	}
+	reply := &fakeReply{}
+	card := &fakeStreamingCard{startID: "track-stream-table"}
+	h := newTestHandlerWithStreaming(t, qa, reply, card)
+	callCount := int64(0)
+	h.now = func() time.Time {
+		callCount++
+		return time.Unix(0, callCount*int64(time.Second))
+	}
+	h.cardUpdateInterval = time.Millisecond
+
+	if err := h.Handle(context.Background(), directTextCallback()); err != nil {
+		t.Fatal(err)
+	}
+
+	var partials []string
+	for _, update := range card.updates {
+		if !update.isFinalize {
+			partials = append(partials, update.content)
+		}
+	}
+	wantPartials := []string{"说明\n\n"}
+	if !reflect.DeepEqual(partials, wantPartials) {
+		t.Fatalf("partial updates=%q, want only pre-table stream %q", partials, wantPartials)
+	}
+	final := card.updates[len(card.updates)-1]
+	if !final.isFinalize || final.content != answer {
+		t.Fatalf("final=%+v, want unchanged complete answer", final)
+	}
+	if qa.result.Answer != answer {
+		t.Fatalf("raw QA answer mutated: %q", qa.result.Answer)
+	}
+}

internal/channels/dingtalk/image_publish_test.go

@@ -0,0 +1,80 @@
+package dingtalk
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"testing"
+
+	"gitea.zheromiku.top/Weknora/dobotai-platform/internal/core"
+)
+
+type fakeImagePublisher struct {
+	published []byte
+	mime      string
+	url       string
+	err       error
+	calls     int
+}
+
+func (f *fakeImagePublisher) Publish(_ context.Context, data []byte, contentType string) (string, error) {
+	f.calls++
+	f.published = data
+	f.mime = contentType
+	return f.url, f.err
+}
+
+func TestDecodeImageDataURI(t *testing.T) {
+	raw := []byte("hello-image-bytes")
+	uri := "data:image/png;base64," + base64.StdEncoding.EncodeToString(raw)
+
+	decoded, err := decodeImageDataURI(uri)
+	if err != nil {
+		t.Fatalf("decodeImageDataURI: %v", err)
+	}
+	if string(decoded) != string(raw) {
+		t.Fatalf("decoded=%q, want %q", decoded, raw)
+	}
+
+	if _, err := decodeImageDataURI("data:image/png;base64"); err == nil {
+		t.Fatal("expected error for missing base64 payload")
+	}
+	if _, err := decodeImageDataURI("no comma at all"); err == nil {
+		t.Fatal("expected error for non-data URI")
+	}
+}
+
+func TestPublishQuestionImagePublishesDecodedBytes(t *testing.T) {
+	pub := &fakeImagePublisher{url: "https://weknora-api.example/i/001"}
+	raw := []byte{0x89, 0x50, 0x4e, 0x47}
+	image := core.ImageInput{
+		DataURI:  "data:image/png;base64," + base64.StdEncoding.EncodeToString(raw),
+		MIMEType: "image/png",
+	}
+	h := &Handler{imagePublisher: pub}
+
+	got := h.publishQuestionImage(context.Background(), image)
+	if got != "https://weknora-api.example/i/001" {
+		t.Fatalf("url=%q, want published", got)
+	}
+	if pub.calls != 1 || pub.mime != "image/png" || string(pub.published) != string(raw) {
+		t.Fatalf("publisher calls=%d mime=%q bytes=%q", pub.calls, pub.mime, pub.published)
+	}
+}
+
+func TestPublishQuestionImageFailsClosedWithoutURL(t *testing.T) {
+	h := &Handler{imagePublisher: nil}
+	if got := h.publishQuestionImage(context.Background(), core.ImageInput{}); got != "" {
+		t.Fatalf("expected empty URL without publisher, got %q", got)
+	}
+
+	pub := &fakeImagePublisher{err: errors.New("oss down")}
+	h2 := &Handler{imagePublisher: pub}
+	image := core.ImageInput{
+		DataURI:  "data:image/png;base64," + base64.StdEncoding.EncodeToString([]byte("x")),
+		MIMEType: "image/png",
+	}
+	if got := h2.publishQuestionImage(context.Background(), image); got != "" {
+		t.Fatalf("expected empty URL on publish error, got %q", got)
+	}
+}

internal/channels/dingtalk/markdown_stream.go

@@ -0,0 +1,114 @@
+package dingtalk
+
+import "strings"
+
+type markdownStreamLine struct {
+	start   int
+	text    string
+	inFence bool
+}
+
+// stableMarkdownPrefix returns the cumulative content that is safe to render
+// while Markdown is still streaming. Once a table is confirmed, the table and
+// every following token stay hidden until the terminal card update.
+func stableMarkdownPrefix(content string) string {
+	lines := splitMarkdownStreamLines(content)
+	for i := 0; i < len(lines); i++ {
+		if lines[i].inFence || !isTableHeaderCandidate(lines[i].text) {
+			continue
+		}
+
+		if i == len(lines)-1 {
+			return content[:lines[i].start]
+		}
+		if lines[i+1].inFence || !isTableDelimiterCandidate(lines[i+1].text) {
+			continue
+		}
+		if !isCompleteTableDelimiter(lines[i+1].text) {
+			return content[:lines[i].start]
+		}
+		// DingTalk only lays out Markdown tables reliably on the terminal
+		// isFinalize=true update. Keep the table and every following partial
+		// token hidden; the authoritative final update bypasses this helper.
+		return content[:lines[i].start]
+	}
+	return content
+}
+
+func splitMarkdownStreamLines(content string) []markdownStreamLine {
+	lines := make([]markdownStreamLine, 0, strings.Count(content, "\n")+1)
+	fence := ""
+	for start := 0; start < len(content); {
+		end := strings.IndexByte(content[start:], '\n')
+		if end < 0 {
+			end = len(content)
+		} else {
+			end += start + 1
+		}
+		text := strings.TrimSuffix(content[start:end], "\n")
+		text = strings.TrimSuffix(text, "\r")
+		trimmed := strings.TrimSpace(text)
+		line := markdownStreamLine{start: start, text: text, inFence: fence != ""}
+
+		if marker := markdownFenceMarker(trimmed); marker != "" {
+			line.inFence = true
+			if fence == "" {
+				fence = marker
+			} else if marker == fence {
+				fence = ""
+			}
+		}
+		lines = append(lines, line)
+		start = end
+	}
+	return lines
+}
+
+func markdownFenceMarker(trimmed string) string {
+	switch {
+	case strings.HasPrefix(trimmed, "```"):
+		return "```"
+	case strings.HasPrefix(trimmed, "~~~"):
+		return "~~~"
+	default:
+		return ""
+	}
+}
+
+func isTableHeaderCandidate(line string) bool {
+	return strings.HasPrefix(strings.TrimSpace(line), "|")
+}
+
+func isTableDelimiterCandidate(line string) bool {
+	trimmed := strings.TrimSpace(line)
+	if !strings.HasPrefix(trimmed, "|") {
+		return false
+	}
+	for _, r := range trimmed {
+		switch r {
+		case '|', ':', '-', ' ', '\t':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
+func isCompleteTableDelimiter(line string) bool {
+	trimmed := strings.TrimSpace(line)
+	trimmed = strings.TrimPrefix(trimmed, "|")
+	trimmed = strings.TrimSuffix(trimmed, "|")
+	cells := strings.Split(trimmed, "|")
+	if len(cells) < 2 {
+		return false
+	}
+	for _, cell := range cells {
+		cell = strings.TrimSpace(cell)
+		cell = strings.TrimPrefix(cell, ":")
+		cell = strings.TrimSuffix(cell, ":")
+		if len(cell) < 3 || strings.Trim(cell, "-") != "" {
+			return false
+		}
+	}
+	return true
+}