# 数字分身聊天与知识库增强设计

## 目标

让用户可以在数字分身管理页进入聊天窗口，并让每次回复严格遵循“标准问答对 > 文件知识库 > OpenAI 兼容 Qwen 模型”的业务优先级；同时补齐分身人格配置、Markdown/TXT 文档支持和知识库管理页面的可用性。

## 已确认范围

- 文档格式：在现有 PDF、DOC、DOCX、XLSX 基础上增加 MD、TXT。
- 回复顺序：启用的标准问答对优先；未命中后检索文件知识库；最终由 OpenAI 兼容接口的 Qwen 模型生成。
- 模型配置：后端环境变量 `CHAT_API_URL`、`CHAT_API_KEY`、`CHAT_MODEL`，密钥不进入前端。
- 分身配置：回复风格、创造力、严谨度、幽默感、回复长度、系统提示词保存到 `Avatar.config`。
- 知识库 UI：文档知识库和标准问答对使用两个可切换的 table 面板；表体独立滚动，页面在移动端仍可上下滚动。

## 后端设计

### 文档解析

扩展 `backend/embeddings.py` 的文本抽取能力：`.md` 和 `.txt` 使用 UTF-8 优先、带替换错误的纯文本读取；分块、向量化和现有文档保持一致。`knowledge.py` 的允许扩展名、错误提示和文件类型注释同步更新。

### 聊天编排

新增 `POST /api/avatar/{avatar_id}/chat`，请求体包含 `message` 和可选的最近历史消息；响应包含 `answer`、`source`、可选 `references`。入口先校验 Bearer app token 对应用户拥有该分身，拒绝未登录或越权访问。

编排步骤：

1. 清理问题空白并限制长度；查询该分身启用的问答对。
2. 对问答对问题做空白、大小写和标点归一化；先精确匹配，再使用确定性的轻量相似度匹配，达到阈值直接返回标准答案，`source=qa`，不调用模型。
3. 未命中时复用现有向量检索，获取高相关文档片段；片段存在时加入模型上下文，`source=knowledge`。
4. 调用 OpenAI 兼容 `/chat/completions`，使用 Qwen 配置和分身 `Avatar.config` 生成回答；没有文档片段时 `source=qwen`。
5. Qwen 未配置、调用失败或返回空内容时返回明确的可展示错误，不返回伪造答案。

人格配置映射到系统提示词和模型参数：回复风格、严谨度、幽默感、回复长度进入系统提示词；创造力映射到受限的 temperature 范围。历史消息只传递最近有限条，避免请求无限增长。

## 前端设计

### 聊天窗口

新增 `AvatarChat.vue` 和 `/avatar/chat/:id` 路由。管理页的分身卡片点击进入该路由。聊天页提供消息气泡、来源标记、引用文件名、发送中状态、失败重试提示和移动端固定输入区；发送按钮在空消息或请求中禁用。

### 分身编辑

在 `AvatarEdit.vue` 增加与 `AvatarCreate.vue` 对齐的六项配置控件，并通过现有 `updateAvatar` 写入 `config`。详情初始化时兼容缺失配置，使用创建页默认值；保存后重新加载分身并回到管理页。

### 知识库管理

`KnowledgeManage.vue` 顶部保留上传区和分身上下文，下面改为两个 tab：

- 文档知识库：上传、向量化状态、文件大小/类型、删除和检索测试。
- 标准问答对：问题、答案摘要、启用状态、编辑、删除和添加。

文档和问答 table 使用固定的最大内容高度与 `overflow-y: auto`，根页面使用 `min-height: 100dvh` 和正常页面滚动；不使用会锁死移动端滚动的全局 `overflow: hidden`。

## 错误与安全

- 聊天接口必须验证用户和分身归属；知识库和问答现有接口也同步使用当前用户校验，避免通过 avatar ID 读取或修改他人数据。
- 上传限制文件扩展名和单文件大小，文件名仅用于展示，落盘名继续使用随机 ID。
- 模型密钥只读取后端环境变量；日志不得输出完整请求、密钥或用户 token。
- 模型服务超时返回可理解的错误，并保留标准问答命中不依赖模型的能力。

## 测试策略

- 后端单元测试：MD/TXT 抽取、问答精确/相似命中、问答优先级、知识片段上下文、无知识时 Qwen 调用、配置映射、未登录/越权拒绝。
- 前端测试：编辑配置 payload、聊天请求/响应映射、知识库 tab 切换和列表解包。
- 构建验证：`vite build`、Python 编译检查、已有 smoke tests。
- 测试环境验收：上传 MD/TXT、添加并启用问答对、验证同一问题优先返回标准答案，再验证未命中问题进入知识库/Qwen；最后确认移动端长列表可滚动。

## 不在本次范围

- 不新增独立聊天数据库或聊天历史持久化表；本期历史仅由前端会话维护。
- 不改会会登录接口和会会用户体系。
- 不把根目录已有管理后台的 AI 模型配置直接耦合进数字分身测试服务；数字分身服务使用明确的 `CHAT_*` 环境变量。