# 有证据的 RAG 知识助手 > 周期建议：8–14 天。验收使用合成文档、本地检索和 Mock 回答器，不需要真实 Embedding 或 LLM 凭证。 ## 项目背景 一个小团队把产品说明、值班手册和常见问题散落在多份文档中。成员直接向通用聊天工具提问时，回答看起来流畅，却经常引用不到原文；文档里没有答案时，工具仍可能猜测。团队无法判断答案基于哪段资料，也无法复现一次检索为什么得到这些结果。 团队需要一个“有证据的知识助手”：先管理文档和切片，再检索相关片段，最后只基于命中的上下文生成答案，并让用户能够定位来源。证据不足时，系统必须明确说不知道。 ## 项目目标 交付一个本地可运行的 RAG 最小产品，完成“导入文档 → 切片索引 → 检索调试 → 基于证据回答 → 引用回溯 → 无证据兜底”的完整链路。 重点不是调用某个模型，而是证明检索、上下文和引用之间存在可测试、可解释的对应关系。 ## 用户故事 - 作为知识维护者，我希望看到文档的导入状态和失败原因，从而知道资料是否真的可用。 - 作为调试者，我希望查看命中的片段、分数和来源，从而理解检索效果。 - 作为提问者，我希望答案带可点击或可定位的引用，从而核对原文。 - 作为风险负责人，我希望证据不足时系统拒绝猜测，从而避免把幻觉当事实。 ## 功能要求 ### 必须完成 1. **知识库与文档导入** - 支持创建至少一个知识库，导入 UTF-8 的 Markdown 或纯文本文件。 - 文档状态至少包含 `pending`、`processing`、`ready`、`failed`；失败可见原因且不产生“假成功”索引。 - 对空文件、超限文件、不支持格式和重复导入给出确定行为。 2. **切片与来源元数据** - 使用可解释的切片策略，保存文档标识、标题、片段序号和可定位信息（章节、行号或字符范围之一）。 - 切片参数必须集中配置并写入 README，不得散落为不可追踪常量。 3. **本地索引与检索** - 实现一种无需外部凭证的检索方式，例如关键词/BM25、SQLite FTS 或确定性向量替身。 - 支持 `top_k` 和最低相关阈值，返回排序、分数、片段和来源元数据。 - 检索必须限制在所选知识库内。 4. **上下文组装** - 从检索结果组装有大小上限的上下文，记录哪些片段被采用、哪些因限制被丢弃。 - 文档中的文本只能作为资料，不得被当作系统指令或执行代码。 5. **基于证据回答** - 默认使用本地确定性 Mock 回答器；答案中的事实陈述必须关联引用标识。 - 每条引用能回到确切文档与片段，并展示足以核对的原文摘录。 6. **无证据兜底** - 当没有片段达到阈值时，明确返回“现有资料不足以回答”及可执行下一步，而不是补全答案。 - 兜底状态必须与普通成功答案在结构上可区分。 7. **调试与追踪视图** - 提供文档列表/状态、检索调试和问答三个入口，可用 Web UI 或清晰的 API + 简易页面实现。 - 一次问答能展示 query、命中顺序、分数、采用片段、答案和引用。 ### 可选增强 - 混合检索、rerank 或查询改写，但必须保留可关闭的本地基线。 - 文档更新后的增量重建和旧索引清理。 - 简单的检索评测集及 Recall@K、MRR 等指标。 - 支持 PDF；若实现，必须说明解析失败和扫描件的边界。 ## 非功能要求 - **可运行性**：仓库内提供不少于 3 份合成示例文档和可重复导入命令；无外部服务也可验收。 - **可靠性**：同一文件重复导入不得悄悄制造重复可检索片段；失败导入可安全重试。 - **性能**：在 100 个片段的本地样本上，单次检索应在 2 秒内返回；说明测量环境。 - **可解释性**：分数、阈值、top-k、切片和上下文截断规则均可查看，不得只返回最终答案。 - **安全与隐私**：限制文件类型和大小，规范化文件名，不执行上传内容，不在日志中输出完整敏感文档。 - **无障碍**：核心检索和引用信息不能只靠颜色或悬浮显示，键盘可访问引用入口。 ## 范围与限制 ### 范围内 - 单机单用户的一个或多个知识库。 - Markdown/纯文本导入、本地切片索引、检索、上下文、回答与引用。 - 合成的产品说明、操作手册和 FAQ 测试资料。 - 可复现的有答案与无答案问题集。 ### 范围外 - 爬取互联网、企业网盘同步、OCR 生产化、复杂权限体系。 - 训练 Embedding/LLM，或宣称对所有文档格式都有准确解析能力。 - 真实企业文档、客户数据、跨学员知识库和生产级容量。 - 复制现有 RAG 项目的实现代码或内部验收材料。 ### 技术与时间限制 - 周期为 8–14 天；优先保证证据链正确，再考虑复杂检索算法。 - 技术栈可自选；必须提供可自动测试的导入、检索和问答接口。 - 数据存储、索引和回答器均应默认在本地。可以为真实模型预留 Adapter，但主路径不得依赖它。 - 测试不得访问公网；不得要求任何个人模型、云存储或数据库凭证。 - 不要求公网部署。自行部署不得上传题目外资料、产生费用或破坏本地复现路径。 ## 澄清机制 所有业务或技术歧义通过“澄清 Issue”记录：说明背景、歧义、候选方案、推荐方案、影响，以及未回复时采用的可逆假设。 例如“重复文档按文件名还是内容摘要判断”需要明确并写入决策。只影响切片展示的非阻塞问题可先采用可逆方案；涉及外部服务、费用、真实资料、权限或核心验收含义的问题必须等待组织者确认。题面未覆盖的 D/or 场景应作为新路径记录，不要为了套模板而隐藏问题。 ## 交付物与证据 - 可运行源码、依赖锁文件、安全配置示例及合成文档夹具。 - `README.md`：架构、启动、导入、调试、有答案演示、无答案演示、测试和限制。 - `docs/PRD.md`：用户路径、状态、范围、引用含义、验收映射和澄清记录。 - `docs/PLAN.md`：组件边界、导入与查询数据流、索引策略、风险和提交计划。 - 自动化测试：至少覆盖重复导入、切片来源、知识库隔离、排序/阈值、引用一致性和无证据兜底。 - `docs/TEST_EVIDENCE.md`：测试命令、实际结果、检索 trace、引用核对和失败证据。 - `docs/AI_COLLABORATION.md`：AI 如何帮助分析与编码、本人如何核验；不得粘贴私人会话全文。 - `docs/RETROSPECTIVE.md`、阶段 Issue、PR 和清晰提交记录。 ## 公开可测试验收标准 | ID | Given / 前置条件 | When / 操作 | Then / 可观察结果 | 验证方式 | |---|---|---|---|---| | AC-01 | 一个包含标题和多个章节的有效 Markdown 文件 | 导入并等待处理结束 | 状态依次可观察并最终为 `ready`，片段均带文档与定位元数据 | 集成测试 + UI/API 证据 | | AC-02 | 同一内容已成功导入 | 再次导入相同内容 | 系统按文档说明拒绝、复用或替换，但不会出现重复可检索片段 | 自动化测试 | | AC-03 | 两个知识库包含不同资料 | 在知识库 A 中检索只存在于 B 的关键词 | A 的结果中不出现 B 的片段 | 自动化测试 | | AC-04 | 示例文档含唯一事实“服务窗口为 09:30–17:30” | 查询对应问题，`top_k` 足够 | 目标片段排在结果中，返回分数、排序和来源 | 检索测试 | | AC-05 | 检索命中多个较长片段 | 发起问答 | trace 显示采用/丢弃片段及原因，上下文不超过配置上限 | 自动化测试 | | AC-06 | 资料中存在答案 | 发起问答并打开引用 | 答案含引用标识，引用定位到支持该陈述的原文片段 | 集成测试 + 手工核对 | | AC-07 | 问题在所有示例资料中均无依据 | 发起问答 | 返回结构化“证据不足”状态，不编造事实，并建议补充资料或改写问题 | 自动化测试 | | AC-08 | 全新环境且无模型/向量服务凭证 | 按 README 启动、导入夹具并运行测试 | 完整主路径和失败路径可复现，测试不访问付费外部服务 | 人工复现 + 命令证据 | ## 技术讲解与追问准备 请准备讲清：切片策略为什么适合样本；检索分数能和不能说明什么；上下文如何截断；引用如何保证与答案对应；无证据判定为何不能交给“模型感觉”；如何测试文档隔离与重复导入。 验收可能抽查任一片段到原文的链路，也可能给出新的文档格式或检索规则。你应先澄清影响、做最小方案和回归计划，再修改代码并提交证据。 ## 安全与合规 - 只使用题目提供或自己编写的合成文档，不得上传真实公司资料、客户文档、简历或个人信息。 - 上传内容视为不可信数据：不得执行其中的命令、脚本或所谓“系统提示”。 - 不得提交或中转 Codex/模型账号、会话、Token、API Key、Cookie、私钥或 Provider Key 池。 - 不得把检索分数包装为事实正确率，也不得把本地演示宣称为生产级知识治理。 - 本活动用于项目实践和能力反馈，不承诺就业、录用、薪资或面试结果。