把分散文档转成结构化、可追溯的本地知识资产。
CASE STUDY 03本地知识治理与检索 MVP
TRACEABLE KNOWLEDGE GOVERNANCE & RETRIEVAL
Support Knowledge Engine
可追溯技术支持知识引擎
将分散的厂商技术文档转化为可治理、可检索、可追溯到原始文档和页码，并可持续评测的知识资产。
演示数据 / Mock Data
页面只展示抽象机制与虚构数据；不包含真实资料、查询、路径、数据库或内部运行结果。
02
PROJECT POSITIONING / 项目定位
先把技术资料变成可信知识资产，再讨论自动化使用。
不是自动回答问题，而是先把来源、版本、产品、页码与可信状态治理清楚。
不是上传即生效；受控获取、资料导入、人工修订与生命周期是分开的责任节点。
不是向量知识库；当前检索依赖 SQLite FTS5 trigram 与显式规则。
03
BUSINESS CONTEXT / 业务背景
检索的业务价值，来自来源、版本和页码都能被复核。
技术支持资料的难点不只是找到关键词，而是确认这份资料来自哪里、适用于哪个产品、是否已过期，以及结论能否回到原始页。
让人工修订不覆盖原始提取值，并保留完整变更证据。
让失败查询、版本冲突和过期资料成为可复盘的质量信号。
04
BEFORE / 原始知识问题
文件可以被找到，不代表知识已经被治理。
来源散落
公开目录、本地文件与临时下载缺少统一授权和获取边界。
重复不可见
同一内容可能以不同文件名出现，重复索引会放大噪声。
元数据漂移
标题、产品、版本和日期依赖文件名或人工记忆，难以复核。
新旧混用
替代关系和生命周期不清，旧文档可能被当成当前依据。
答案无证据
搜索结果不能回到具体文档和页码，人工无法快速核实。
质量不可评
失败查询、串库和无答案误返没有稳定指标或日志。
05
CONSTRAINTS / 设计约束
本地、受控、人工生效和保守失败，是系统可以被信任的前提。
本地优先
数据库与文件留在本机，不依赖云端知识服务。
来源受控
只处理清单或已下载目录中的明确资料，不抓取整站。
人工生效
授权、元数据和生命周期由人工确认，获取不等于导入。
失败保守
歧义或证据不足时返回空结果，不填充低相关内容。
证据可回溯
每个结果保留文档、页码、状态与原文片段。
公开脱敏
作品集不承载真实资料、查询、路径与运行数字。
06
TWO SOURCE PATHS / 两条资料入口
入口保持独立，底层去重、解析和治理能力复用。
厂商公开资料目录
- 1已下载公开资料
- 2权威 manifest
- 3产品 / slug 别名
- 4PDF 导入与索引
只读目录适配，不负责网站抓取。
受控 JSON 来源清单
- 1显式 URL / 本地文件
- 2dry-run 与校验
- 3独立获取区
- 4人工确认后导入
不发现链接，不处理登录或验证码。
共享底层：SHA-256 → PDF 页级解析 → 元数据治理 → 产品与生命周期 → FTS5 → 日志与评测
07
PDF & PAGE MAPPING / PDF 导入与页码映射
索引单位是页，结果必须能回到原始文档页码。
01PDF 签名与读取→
02PyMuPDF 文本提取→
03按页保存正文→
04页码写入 FTS→
05返回片段与原页
当前不做 OCR；纯扫描件或无法提取文本的文档进入失败记录。
08
CONTENT IDENTITY / SHA-256 去重
文件名可以变化，内容身份由哈希判断。
01读取文件流→
02计算 SHA-256→
03比对 documents 唯一哈希→
04新增索引或记录重复→
05跨入口补齐权威元数据
09
THREE-VALUE GOVERNANCE / 元数据三值治理
修订不是覆盖原值，而是增加一层有责任人的治理证据。
原始值
解析或清单提供的值，作为不可丢失的来源证据。
人工值
维护者给出的修订值，要求原因与操作者。
生效值
人工值存在时优先，否则回退原始值。
- 标题
- 产品
- 文档类型
- 语言
- 版本
- 发布日期
- 来源
- 权威等级
- 生命周期
10
PRODUCT & ALIAS / 产品和别名
用显式别名统一产品表达，遇到冲突时停止猜测。
规范产品维护标准名称与系列。
中英文名、缩写和常见写法作为显式别名。
英文别名大小写无关；未配置的模糊猜测不自动发生。
同一别名属于多个产品时暂停自动关联并标记歧义。
11
DOCUMENT LIFECYCLE / 文档生命周期
新版本生效不删除历史，替代链与审计共同保留上下文。
待复核
缺失或冲突字段需要人工处理。
生效
当前可优先检索的有效资料。
已替代
保留历史并指向替代文档。
草稿
尚未成为正式检索依据。
归档
默认不优先，但可按状态追溯。
替代关系禁止指向自身或形成循环；人工变更写入 append-only 审计。
12
PAGE-LEVEL RETRIEVAL / 页级检索
SQLite FTS5 trigram 负责找页，生命周期和产品规则负责控制结果。
01用户查询→
02规范化→
03产品识别→
04页级 FTS5→
05生命周期排序→
06可信状态→
07文档与页码
当前没有向量数据库、embedding、RAG 或 LLM 自动问答。
13
QUERY NORMALIZATION / 查询规范化
只应用可解释的显式规则，不把字符串处理包装成语义理解。
01Unicode NFKC
02英文大小写
03显式错拼纠正
04显式故障同义词
05标点与空格
06产品别名
14
TRUST STATES / 检索可信状态
可信度是规则标签，不是模型概率。
高可信匹配
唯一产品 + 生效文档页命中。
可能匹配
有页级原文，但缺少更明确约束。
产品歧义
别名属于多个产品，返回空结果。
版本冲突
同类新旧状态同时命中，要求核对。
仅过期文档
保留历史证据并突出风险。
证据不足
不填充低相关结果。
15
SEARCH LOGS & AUDIT / 搜索日志与审计
记录查询如何被处理，才能把失败变成下一轮治理输入。
- 原始查询
- 规范化查询
- 应用规则
- 识别产品
- 可信状态
- 结果数量
- 检索耗时
公开页面不展示真实查询、操作者、路径、哈希或审计原文。
16
BACKUP & RECOVERY / 备份与恢复
恢复不是简单覆盖：先验证，再保留当前库的安全退路。
01SQLite 在线备份→
02完整性检查→
03schema 版本检查→
04SHA-256 校验→
05恢复前安全备份→
06原子替换
17
EVALUATION / 检索评测
用可重复用例检查召回、串库、过期误命中与无答案误返。
以下为虚构语料自动化评测，不代表真实生产业务效果。
v0.3.1 发布验证
v0.3.1 发布验证
覆盖类型
- 中英文
- 型号与缩写
- 别名
- 错拼
- 相似产品
- 配件
- 否定式
- 无答案
- 仅过期文档
输出指标
- Recall@1
- Recall@3
- MRR
- 产品串库率
- 过期误命中率
- 无答案错误返回率
- 别名识别率
- 平均耗时
18
SYSTEM ARCHITECTURE / 系统架构
从受控来源到证据与评测，每一层都保留失败和人工复核边界。
来源层
- 公开目录适配
- 受控 JSON 清单
校验与解析
- 类型 / 签名 / 大小
- SHA-256
- PyMuPDF 按页解析
治理层
- 三值元数据
- 产品 / 别名
- 生命周期 / 审计
检索层
- FTS5 trigram
- 查询规范化
- 六类可信状态
证据与运营
- 文档 / 页码
- 搜索日志
- 评测 / 备份恢复
本地单用户边界
没有 OCR、向量数据库、RAG、LLM 自动问答、登录、多租户或云同步。
19
INTERACTIVE MOCK DEMO / 交互式检索模拟
选择入口、治理元数据，再观察查询如何得到可信状态和页级证据。
Demo 只使用前端内存状态，不读文件、不连 SQLite、不调用 OCR 或 AI、不发送网络请求。
演示数据 / Mock Data
TRACEABLE RETRIEVAL LAB
从受控资料入口走到页级证据与评测记录
此交互用于展示资料治理、检索、证据追溯和评测逻辑，不连接真实文档或知识库。
- 1资料入口
- 2来源校验
- 3导入结果
- 4元数据治理
- 5查询
- 6可信状态
- 7页级证据
- 8日志与评测
- 9完成
选择一条虚构入口
20
MATURITY / 项目成熟度
本地知识治理与检索 MVP
核心治理、两入口、页级检索、可信状态、日志、备份和虚构评测已进入稳定主线；仍没有真实试点、正式盲测或生产部署证据。
01Prototype
02MVP当前
03Pre-release
04Internal pilot
05Production
21
VERIFIED / 已验证能力
只展示当前稳定提交、代码、测试或版本化报告能够证明的能力。
稳定主线为 main@010e5cb，并建立 v0.3.1-corpus-pilot 标签；v0.3.0 保留为功能整合基线。
代码最高 schema migration 3；未读取真实数据库。
稳定版本包含 39 项 unittest，v0.3.1 发布记录为 39/39 通过。
基础虚构评测 13/13、corpus pilot 虚构评测 84/84 已进入 v0.3.1 发布记录；不代表真实生产效果。
README 候选分支矛盾和 favicon 404 已修复；/favicon.ico 发布回归为 HTTP 200、image/svg+xml。
两条资料入口、跨入口去重、可信状态、日志和备份恢复均有当前代码与测试覆盖。
页级 FTS5 检索可以回到文档、页码与原文片段。
22
OPEN ITEMS / 尚未完成与未验证
把实验、真实效果和生产状态留在证据边界之外。
真实资料目录和受控来源的正式授权、全量导入与人工验收。
后续代码变化后的 39 项 unittest 与两套虚构评测持续复验。
真实数据库当前 migration 版本与备份恢复演练。
正式人工盲测、真实用户试点、生产运维和业务收益。
OCR、向量检索、RAG 与 LLM 问答均未实现。
Phase 4.0 / 4.1、A/B/C、3,567 片段和 45 项测试未被当前 Git 证明。
23
MY ROLE / 我的职责
独立完成本地知识治理与可追溯检索 MVP 的设计、开发和验证。
01独立识别知识治理问题
02独立设计来源治理与授权边界
03独立设计元数据三值和生命周期
04独立实现检索可信状态与保守失败规则
05独立建立测试、评测与迭代机制
06独立控制脱敏与公开边界
24
PRIVACY & PUBLIC BOUNDARY / 隐私与公开边界
展示治理方法，不展示真实资料、查询或内部运行环境。
- 不展示真实 PDF、manifest、原文片段或下载清单。
- 不展示真实路径、数据库、备份、哈希、查询或审计日志。
- 不展示内部域名、凭据、Cookie、登录状态或公司服务配置。
- 所有产品、文档、页码、日志和指标均为演示数据。
- 品牌、职责归因和真实运行成果在公开前单独确认。
- 版本化虚构评测不被包装为生产准确率或业务收益。
25
NEXT / 下一步计划