# V2 一期范围清单

日期：2026-07-06

## 目的

这份文档用于锁定 AI 知识库系统 V2 的一期开发边界。后续开发、测试、验收和排期都以这里的范围为准；如果范围变化，需要新增决策记录，不直接悄悄改代码。

## 一期产品目标

一期要交付的是一个“企业飞书知识库 AI 问答系统”的可用版本，核心价值是：

1. 用户可以登录并向系统提问。
2. 系统只基于当前已开放的飞书知识库回答，已开放知识库默认对所有用户可见。
3. 管理员可以维护用户、知识库、Prompt、模型、系统配置和聊天记录。
4. 每次 AI 调用都有日志可追溯，方便排查回答、知识库范围和成本问题。

## 一期必须包含

### 用户端

| 功能 | 一期要求 | 说明 |
| --- | --- | --- |
| 手机号验证码登录 | 必须 | 先接 mock 短信，后续替换真实短信供应商；手机号必须已存在于学员名单。 |
| 学员名单准入 | 必须 | 不再自动注册，只有管理员手动添加或批量导入的学员可以登录。 |
| Token 登录态 | 必须 | 支持登录有效期、退出后 Token 失效。 |
| AI 聊天 | 必须 | 文本输入、发送、接收 AI 回复。 |
| 多会话 | 必须 | 支持新建会话、切换会话、历史会话列表。 |
| 历史聊天 | 必须 | 用户可以查看自己的历史聊天。 |
| 会话标题 | 必须 | 支持自动生成和手动修改标题。 |
| 流式回答 | 必须 | 使用 SSE 流式返回。 |
| 停止生成 | 必须 | 停止当前模型请求，保留已生成内容。 |
| Markdown 渲染 | 必须 | 支持标题、列表、代码块、表格等基础 Markdown。 |
| 每日聊天次数限制 | 必须 | 默认次数来自系统配置，也支持用户维度覆盖。 |
| 知识库开放控制 | 必须 | 只能检索已开放、未禁用的知识库；已开放知识库默认所有用户可见。 |

### 管理后台

| 功能 | 一期要求 | 说明 |
| --- | --- | --- |
| 管理员登录 | 必须 | 用户名 + 密码。 |
| Dashboard | 必须 | 展示用户、聊天、Token 等核心统计；AI 成功率/失败率一期不展示。 |
| 用户管理 | 必须 | 查询、详情、手动添加学员、Excel 模板批量导入学员、启用/禁用、删除、设置额度和有效期。 |
| 管理员管理 | 必须 | 仅超级管理员可维护管理员账号。 |
| 知识库管理 | 必须 | 新增、编辑、删除、启用/禁用飞书知识库。 |
| Prompt / Agent 管理 | 必须 | 查看、编辑、保存、恢复默认；选择模型和知识库；在聊天式预览窗口中调试 Agent。 |
| AI 模型管理 | 必须 | 新增、编辑、启用、删除模型；同一时间仅一个模型启用。 |
| 聊天记录 | 必须 | 查询、详情、导出。 |
| 系统配置 | 必须 | 以中文分组表单维护全部允许后台配置的项目；不提供高级配置或自由 Key/Value 入口。 |
| 操作日志 | 必须 | 关键后台操作必须写日志；日志不允许删除。 |

### AI/RAG 能力

| 能力 | 一期要求 | 说明 |
| --- | --- | --- |
| 飞书知识库实时检索 | 必须 | 优先调用搜索接口；未配置或异常时回退飞书直读；一期不做本地同步和向量库同步。 |
| 多知识库开放过滤 | 必须 | 检索前先过滤出全部已开放、未禁用知识库；调用搜索接口时必须把这些知识库的 `spaceId/nodeId` 作为检索范围传入，禁止全局搜索。 |
| Prompt 组装 | 必须 | 系统 Prompt + 检索片段 + 历史上下文 + 当前问题。 |
| 大模型调用 | 必须 | 从启用模型配置读取 API URL、Key、模型名和参数。 |
| SSE 输出 | 必须 | 支持流式输出和结束标记。 |
| 引用来源 | 必须 | 用户端是否展示由后台配置控制；后台始终记录完整引用。 |
| 无命中兜底 | 必须 | 固定返回“当前知识库中未检索到相关内容，请联系管理员补充相关知识。” |
| 知识冲突处理 | 必须 | 展示不同知识库观点，不由 AI 自行裁决。 |
| AI 请求日志 | 必须 | 记录用户、会话、模型、Prompt、知识库、Token、耗时、状态和错误。 |

## 一期明确不做

| 功能 | 不做原因 |
| --- | --- |
| 文件上传 | 文档明确一期不做，避免知识来源变复杂。 |
| 图片理解 | 不属于当前文本知识问答主链路。 |
| OCR | 不属于一期能力。 |
| 联网搜索 | 一期固定关闭，避免模型越过企业知识库回答。 |
| 向量数据库同步 | 一期要求实时访问飞书，不做本地同步。 |
| 支付系统 | 与当前企业内部知识问答无关。 |
| 课程系统 | 与当前一期主链路无关。 |
| 自动授权 | 知识库不再按用户授权，已开放知识库默认全员可见。 |
| 多租户 | 一期按单企业内部系统处理。 |
| 多 Prompt | 一期只维护一个当前生效 Prompt。 |
| 重新生成回答 | 文档明确不做。 |
| 编辑历史消息 | 文档明确不做。 |

## 后续扩展预留

以下能力不进入一期开发，但架构上要避免封死：

- 多模型切换策略
- 向量数据库
- 更多知识源
- 文件上传
- 多租户
- 联网搜索
- 更复杂的 Prompt 版本管理
- 知识库同步/缓存
- 企业微信、微信小程序或其他端

## 一期验收重点

1. 已在学员名单中的用户可以完成登录、提问、流式回答、停止生成、查看历史。
2. AI 只使用已开放的知识库，知识库禁用或未开放时不能参与检索；搜索接口也必须限制在已开放知识库节点内。
3. 无知识命中时不编造答案。
4. 飞书异常、模型异常、AI 超时都有明确提示和日志。
5. 后台可以维护用户、知识库、Prompt、模型、系统配置和聊天记录。
6. 未在学员名单中的手机号不能发送验证码，也不能登录使用系统。
7. 管理后台权限隔离生效：普通管理员不能维护管理员账号。
8. 所有关键操作和 AI 请求都可追溯。
