Problem
需要从技术文档中检索可追溯答案的售后支持与知识维护场景。- 原始流程
- 资料从不同目录或人工导入后，使用者依赖文件名、记忆或全文搜索定位答案，再手工确认来源与版本。
- 核心痛点
- 文档重复、产品归属与版本不清，检索结果缺少页码和可信状态。
- 业务影响
- 错误或过期资料可能进入回答，搜索质量难以回归测试，也无法稳定解释答案来源。
- 原方案不足
- 直接做聊天问答或向量检索会跳过资料准入、版本、激活和证据不足等基础治理问题。
LAB / PROTOTYPE 01
TRACEABLE KNOWLEDGE GOVERNANCE & RETRIEVAL
Support Knowledge Engine
可追溯技术支持知识引擎
将分散的厂商技术文档转化为可治理、可检索、可追溯到原始文档和页码，并可持续评测的知识资产。
演示数据 / Mock Data
当前公开范围：资料治理、页级检索与评测机制；页面数据为虚构或抽象内容。
CONTEXT / 业务背景
Constraints / 真实约束 4
- 本地单用户运行，只允许两条受控资料入口。
- 资料必须人工激活，默认保守失败并保留来源、页码和内容哈希。
- 当前使用页级 SQLite FTS5，不宣称已实现 OCR、向量数据库、RAG 或 LLM 问答。
- 公开评测仅使用虚构语料，不代表生产效果。
Ownership / AI-assisted boundary
项目所有者负责
- 定义资料准入、元数据、去重、版本和六种可信状态。
- 设计页级检索、证据追溯、回归评测与失败边界。
- 负责测试口径、成熟度声明与最终验收。
Codex / AI 辅助
- 辅助工具代码、迁移、测试、文档和作品集 Demo 实现。
- 不替代资料授权、人工激活、检索质量判断或业务验收。
SYSTEM / 系统逻辑
Implementation / 已完成的实施工作
- 受控文档导入与来源管理：校验 PDF 签名、大小和 SHA-256；获取与人工导入分开。
- 内容去重与元数据治理：保留原始值、人工值和生效值，管理产品别名、版本与生命周期。
- 页级检索基线：SQLite FTS5 trigram 索引配合显式查询规范化，返回文档、原文片段和页码。
- 质量反馈：搜索日志保留规范化规则、识别产品、可信状态、结果数和耗时；版本化报告支持 Recall@1、Recall@3 与 MRR。
Architecture / Evidence / Demo
查看系统架构、设计依据与交互演示。
DECISIONS & EVIDENCE / 决策与证据
Evaluation / 基线、测试与失败复盘
- 先固定页级 FTS5 基线，再用虚构问题集检查预期行为，把失败类型纳入回归测试。
- 版本化记录：基础虚构评测 13/13、corpus pilot 虚构评测 84/84；稳定版本含 39 项 unittest，发布记录为 39/39。
查看评测范围与 Failure Cases / Lessons
- 检查点包括重复导入、产品歧义、过期版本、证据不足与无答案误返；这些是规则与测试覆盖，不是实际客户效果。
- 当前证据未证明 A/B/C 检索方案对照或候选默认方案；本轮未重跑源项目，沿用 v0.3.1 版本化记录。
- 元数据和版本漂移
- 文件名不能作为产品与版本的唯一依据；人工修订保留原值，并通过生命周期控制生效范围。
- 产品歧义与串库风险
- 显式别名发生冲突时保守停止自动关联；证据不足返回空结果，不补低相关答案。
- 扫描件或文本无法提取
- 进入导入失败记录；当前没有 OCR，不把无法读取的 PDF 描述为已索引。
- 检索噪声与语义局限
- 记录查询规则和可信状态，使用回归集检查无答案误返；显式规范化不等于语义理解。
证据来源：v0.3.1-corpus-pilot / main@010e5cb；PROJECT_FACTS、EVIDENCE_INDEX、CONTENT_GAPS 与版本化虚构评测记录。
查看设计决策与取舍
先治理资料，再扩展 AI 问答
- 为什么
- 来源、版本和激活状态不可信时，生成式回答只会放大错误。
- 取舍
- 短期体验不如聊天式入口，但证据边界可验证。
页级 FTS5 与证据不足状态
- 为什么
- 当前规模需要低成本、本地、可追溯的基线。
- 取舍
- 语义召回能力有限，但不引入未验证的向量 / RAG 复杂度。
两条受控入口与人工激活
- 为什么
- 避免任意目录内容未经确认直接成为可用知识。
- 取舍
- 导入效率更保守，换取来源和权限可控。
Evidence Ledger 4
证据来源按项目所有者确认、源码、测试、仓库资产或 Demo 行为分别标注；外部验证单独说明。
- Evidence Type
- Engineering evidence
- Evidence status
- Source-code verified
- Claim
- 本地资料治理、页级 FTS5、来源追溯与六种可信状态链路可运行。
- Scope
- v0.3.1-corpus-pilot 单用户 MVP。
- Source
- PROJECT_FACTS 源码审计
- Date
- 2026-07-27
- Public-safe
- Public content
- Notes
- v0.3.1 为发布卫生修复，不改变核心业务能力；尚未投入真实业务，未实现 OCR、向量检索、RAG 或 LLM 问答。
- Evidence Type
- Automated test
- Evidence status
- Test-backed
- Claim
- 仓库记录 39 项 unittest，以及虚构评测 13 / 13 和 84 / 84。
- Scope
- 版本化自动化基线与虚构语料。
- Source
- PROJECT_FACTS 测试记录
- Date
- 2026-07-27
- Public-safe
- Public content
- Notes
- 不代表真实资料准确率、用户验证或生产效果。
- Evidence Type
- Demo / Mock
- Evidence status
- Demo-verified behavior
- Claim
- 公开 Demo 可演示资料准入、激活、检索与证据不足。
- Scope
- 虚构资料和页面演示。
- Source
- Portfolio 公开 Mock
- Date
- 2026-08-09
- Public-safe
- Public content
- Notes
- 不连接真实文档或知识库。
- Evidence Type
- Potential value
- Evidence status
- External validation: none
- Claim
- 可信资料治理可作为可复核知识检索的低成本底座。
- Scope
- 潜在价值假设。
- Source
- 系统设计推论
- Date
- 2026-08-09
- Public-safe
- Public content
- Notes
- 真实命中率、维护成本和用户价值待授权语料与人工盲测。
OUTCOME & NEXT / 结果与下一步
Next Step / 当前是传统检索基线。下一阶段若接入 embedding / reranker / LLM，应先使用当前评测集做对照验证，记录质量变化、失败模式与性能代价；这些能力尚未实现。
Deliverable
- 本地资料治理、页级检索、来源追溯和可信状态链路可运行。Evidence: SKE-E01
Observable Outcome
- 无真实用户或业务观察结果。Evidence: SKE-E01
LAB DEEP DIVE展开治理、检索、评测与 Mock Demo
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 / 交互式检索模拟
选择入口、治理元数据，再观察查询如何得到可信状态和页级证据。
当前验证范围：前端内存中的虚构来源、元数据治理、查询、页级证据与评测记录。
TRACEABLE RETRIEVAL LAB
从受控资料入口走到页级证据与评测记录
- 1资料入口
- 2来源校验
- 3导入结果
- 4元数据治理
- 5查询
- 6可信状态
- 7页级证据
- 8日志与评测
- 9完成
选择一条虚构入口
21
REPOSITORY EVIDENCE / 仓库证据
稳定提交、源码、测试与版本化报告支持以下能力。
稳定主线为 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 VERIFICATION / 开放验证事项
尚待验证：真实语料效果、用户试用、多用户治理与生产环境。
真实资料目录和受控来源的正式授权、全量导入与人工验收。
后续代码变化后的 39 项 unittest 与两套虚构评测持续复验。
真实数据库当前 migration 版本与备份恢复演练。
正式人工盲测、真实用户试点、生产运维和业务收益。
OCR、向量检索、RAG 与 LLM 问答均未实现。
Phase 4.0 / 4.1、A/B/C、3,567 片段和 45 项测试未被当前 Git 证明。
CAREER CONVERSATION / 求职与合作
把业务现场、流程、数据与 AI 应用落到可交付的系统里。
我目前关注企业 AI 应用实施、企业解决方案、业务需求分析与数字化实施方向。如果你的团队正在寻找能够连接业务现场、流程、数据与 AI 应用落地的人，欢迎继续查看我的求职信息或直接联系我。