docs: design avatar chat knowledge flow

docs/superpowers/specs/2026-07-23-avatar-chat-knowledge-design.md

@@ -0,0 +1,72 @@
+# 数字分身聊天与知识库增强设计
+
+## 目标
+
+让用户可以在数字分身管理页进入聊天窗口，并让每次回复严格遵循“标准问答对 > 文件知识库 > 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_*` 环境变量。