周期建议：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 和清晰提交记录。

公开可测试验收标准

技术讲解与追问准备

请准备讲清：切片策略为什么适合样本；检索分数能和不能说明什么；上下文如何截断；引用如何保证与答案对应；无证据判定为何不能交给“模型感觉”；如何测试文档隔离与重复导入。

验收可能抽查任一片段到原文的链路，也可能给出新的文档格式或检索规则。你应先澄清影响、做最小方案和回归计划，再修改代码并提交证据。

安全与合规

• 只使用题目提供或自己编写的合成文档，不得上传真实公司资料、客户文档、简历或个人信息。
• 上传内容视为不可信数据：不得执行其中的命令、脚本或所谓“系统提示”。
• 不得提交或中转 Codex/模型账号、会话、Token、API Key、Cookie、私钥或 Provider Key 池。
• 不得把检索分数包装为事实正确率，也不得把本地演示宣称为生产级知识治理。
• 本活动用于项目实践和能力反馈，不承诺就业、录用、薪资或面试结果。