01是什么WHAT IT IS
KB-Prototype · 知识库原型 关注如何把业务知识整理成可查询、可维护、可观测的后端结构。
02为什么重要WHY IT MATTERS
很多知识库项目失败，不是因为没有 RAG，而是因为资料没有分层、来源不清、更新和反馈没有记录。
03架构方向ARCHITECTURE
整体拆成五层，每一层只解决一个问题，层与层之间靠明确的数据契约衔接。以下是可售卖方法论的抽象版；私有原型已围绕这些边界实现了部分 schema、检索和隔离测试。
图 P-005 · 知识库原型的核心不是向量检索，而是来源必填、结构化查询、引用留痕和观测反馈。
- 资料实体层——每条知识是一个实体：正文、摘要、时效标注，加一条必填的来源记录（出自哪个项目、哪份文件、哪次对话）。没有来源的内容不允许入库，这是整个系统的第一条硬约束。
- 组织层——标签体系加别名表。同一个概念在业务里往往有多种叫法（客户口径、内部口径、行业口径），别名表把它们收敛到同一个实体，检索时才不会漏掉一半资料。
- 查询接口层——结构化查询先行（按标签、来源、时间过滤），全文检索后置。返回结果必须携带来源引用，使用方能追问「这条结论从哪来」。
- 引用与日志层——每次查询和引用留记录：谁查的、查了什么、结果用在了哪。这层是反馈回路的地基——没有使用记录，就无法判断哪些资料真的有价值。
- 观测层——三个最小指标：覆盖率（多少资料已结构化）、新鲜度（多久没更新）、命中率（查询是否得到可用答案）。指标不为好看，为暴露该淘汰和该补的资料。
后续若进入 RAG 或向量检索，前提仍是上述数据边界先立住：私有原文永远不进入公开层，检索质量未经验证前不作为事实引用。
04数据模型与接口DATA MODEL & API
核心对象（对应五层）：
entity——id · body · summary · valid_from · valid_until · status；每条知识一行，时效用起止时间标注。source_record——entity_id · origin_type(project/file/conversation) · origin_ref · ingested_at；与 entity 一对多且必填，缺来源不允许入库，是第一条硬约束落到 schema 上的样子。tag/alias——tag(id·name)；alias(alias_text → canonical_tag_id)，把同概念的多种叫法收敛到一个标签。query_log——query_id · actor · query_expr · result_refs[] · used_in · ts；每次查询与引用留痕，喂给观测层。- 观测不建表，是建立在上述表上的派生视图：覆盖率、新鲜度、命中率。
目标接口（示例）：
POST /entities——入库；请求体缺source_ref返422（硬约束在接口层的兑现，不是靠约定）。GET /query?tag=&source=&since=——结构化查询先行；返回每条结果都带source_ref，使用方能追问出处。GET /metrics——返回覆盖率/新鲜度/命中率三项，供判断该补该淘汰哪些资料。
全文与向量检索是这套接口之上的后置增强，不改变"结构化先行、来源必带、私有原文不出库"的契约。
05证据状态EVIDENCE STATUS
Implemented：私有原型已覆盖结构化资料登记、默认可见范围、别名扩展、结构化查询、本地搜索和人工复核队列等核心骨架。方向与叙事属于定位描述，不计入已实现。
Mac 复验：2026-07-06，python3 -m pytest 跑过 test_kb_database_builder.py、test_kb_database_search.py、test_kb_local_search.py，结果为 15 passed。这组测试覆盖建库、默认排除私有范围、公开产品知识可查、别名扩展、私有范围需要权限等关键边界。
已有私有报告：覆盖率面板、BM25/混合检索和候选误判审计已有历史报告可参考；公开页只保留能力结论：默认检索排除私有范围、检索结果需要来源回传、未验证质量前暂不进入 RAG。
未复验项：本机尚缺一份输入快照，覆盖率面板测试在 Mac 上未通过复验；因此本页只把它列为既有私有报告，不写成当前已复验通过。
Planned：补一个完全脱敏的小样本：3 条资料、2 条别名、2 次查询、1 张指标截图。它会作为对外售卖演示，不带任何真实业务原文。
06边界BOUNDARY
不公开真实业务数据，不把未验证的检索质量写成事实，不进入私有资料原文展示。
07下一步NEXT
当前最大缺口不是有没有原型，而是缺一个能公开给客户看的脱敏样本。下一步只做最小演示包：用虚构资料重建一份小型知识库，展示建库、别名查询、权限隔离和指标面板；完整私有资料继续留在内部，不进入公开页。