用途与实际影响
这项功能怎样使用
为什么需要它
同一材料可能有草稿、签字版、交付版、回执或完全相同的副本。只按文件名排序会把版本混在一起；直接公开路径又会在尚未选择时暴露不必要的私人位置。登记查找先把候选缩小，并保留来源原生差异。
举个实际例子
我说“找一下那份延保合同”，页面只给出几份能看出来源、日期和“草稿、签字版、回执”等角色的候选。两份内容完全相同可以标成重复，但桌面上有签字包，绝不等于平台已经收到。
最后我会得到什么
得到少量可比较候选和明确的登记搜索范围。候选还不是最终原件证明；选中后继续进入重新验真，零命中则说明哪些来源和材料记录确实被查询。
有清晰登记候选时
从已登记材料交回少量能分清来源、日期和版本的候选；这一步还不是最终原件证明。
零命中或版本仍歧义时
只有旧文字或来源记录能提示候选时，明确证据较弱；本人已删除的文件不会作为可用候选。
登记索引不可读取时
索引不能安全读取时停止查找，不从陌生数据库猜答案。
从哪里开始
用自然话描述那份非媒体材料，先查已登记来源。
需要准备什么
- 标题、用途、日期或来源线索
- 可选的明确来源限定
从开始到拿到结果
- 1
系统核对并处理
从登记记录和绑定文字里挑少量能区分版本、来源与状态的候选；候选不等于当前原件已验真。
- 2
交付与接续
交回候选和实际搜索范围；零命中说明登记范围，选中后再进入验真。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
status 当前有 154 条精确定位记录，stored open_state（保存的打开状态）均为 verified；这不是本次154份原件已逐项核验。44份材料有来源自带绑定文字，其余110份没有。登记查找把 verified_locator、unverified_source_evidence 与 known_locator_gap 三阶段分开；版本区分、路径隐藏、零命中范围、媒体过滤与可信文件管理器退役保留 2026-09-07 基线 66 项合成回归与 Ruff 通过；不覆盖后来新增的 lookup-content，本轮未重跑 的历史证据。关键规则与设计选择
用户不用先回忆绝对路径或内部材料 ID，只需描述目标。
登记候选与发现候选分开：已有定位优先，不为每次查询遍历文件系统。
查找阶段本身表达证据强度：verified、未验证来源证据（来源/材料元数据、search_text 或绑定文字）和已知定位缺口不会混在同一个“已找到”标签里。
完全相同字节、逻辑版本和来源原生关系分别表达，不把“相似”写成“同一份”。
零命中自动携带已搜索与未搜索范围，不能被解释成其他设备或位置不存在。
来源根可访问而已登记原件不存在时，查询只读跳过该 occurrence（出现记录），不把它作为 known_locator_gap 恢复候选；现有日常维护调用 sync-current，在事务重检后才退出该记录及级联文字/关系。
本模块用到的名词
- Registered index（登记索引）
- 只包含明确接入的来源和非媒体原件定位，不是整盘文件清单。
- Logical family（逻辑版本族）
- 同一现实材料的多个来源原生版本；它与相同字节副本不是同一概念。
- Exact duplicate（精确重复）
- 只有完整 SHA-256 相同才成立；标题相同或迁移回执不能证明。
- Hash-bound text（哈希绑定文字）
- OCR（光学字符识别）、提取或原生文字与一份精确原件身份绑定；只帮助召回，引用仍回到原件。
- Search scope（搜索范围）
- 本次实际查询的登记材料与来源，以及未查询部分；零命中必须与它一起解释。
- Lookup stage（查找阶段）
- verified_locator 只含 verified；unverified_source_evidence 只含 unverified 的来源元数据或绑定文字证据；known_locator_gap 只保留 hash_mismatch、not_openable 等仍可复核问题，本人已删的 missing occurrence 已先退出。
专业定义
用一句普通描述匹配已登记来源、标题、原生标识、版本角色和绑定文字，优先返回已有可靠定位的少量候选。
解决什么
解决路径遗忘、同名文件、版本混淆、旧定位优先级和候选阶段不必要暴露真实位置。
当前怎样实现
- 从 sources、materials、material_relations 和 material_text 读取登记事实；媒体历史行在查询前过滤。
- 先按 verified_locator 查找，确切缺失候选不占 limit；该阶段没有有效结果才回退 unverified_source_evidence，再回退已记录问题。不能因为一个已删文件挡住后面的真实原件。
- 没有 verified 匹配时才查 open_state=unverified 的来源名、标题、原生 ID、版本字段、材料 search_text 与 material_text，并标为 unverified_source_evidence；即使没有 material_text，来源原生元数据仍可形成未验证候选。
- material_text 只接收 native、ocr（光学字符识别） 或 extracted 三类可重建文字；它们可以帮助召回，但不能替代当前原件验真。
- 查询文本去除常见请求词，并结合完整短语、拉丁词和中文二元片段计算有界匹配分。
- find 命令默认返回 5 个、允许 1–10 个；个人 Skill 为减少选择成本固定请求最多 4 个。
- 候选卡提供来源、标题、容器、逻辑与版本身份、时间、指纹、大小、状态、精确重复次数和原生关系，但不包含 locator（原件定位记录）。
- 搜索范围记录已查非媒体材料数、来源样本、未搜索来源数和实际命中来源。
执行流程
- 1
确认请求属于非媒体原件且没有可靠 locator（原件定位记录）；否则直接分流或绕过。
- 2
把用户原话规范为搜索签名，不要求用户翻译成内部字段。
- 3
查询按 verified_locator → unverified_source_evidence → known_locator_gap 逐阶段返回仍可核对的候选，不写数据库或触发同步；候选数量上限只计算有效项。
- 4
按分数、来源时间和稳定材料身份排序，只保留最多 4 个候选。
- 5
返回候选、查找阶段、搜索范围与零命中说明；不在这一步打开原件。
边界
- 已有可靠路径直接打开，不先经过登记查找。
- 只查询非媒体原件；照片、视频、音频和录音始终由 personal-media 处理。
- 候选不向用户暴露真实路径、内部 ID 或内部选择凭据。
- 绑定文字不拥有高于原件的证据地位，也不进入人物、事件或领域判断。
- 来源覆盖是 complete、partial 或 unknown（未验证） 的登记声明，不等于整台电脑。
失败与恢复
- 零命中
- 返回 not_found、登记搜索阶段、实际材料数量、来源样本、未搜索来源与缺口；只说明本轮登记索引没有合适候选。
- 指定来源没有可用登记项
- 不静默扩大到其他来源；显示空范围并等待更正来源或明确进入发现。
- 只有旧的未验证文字命中
- 明确标为派生文字召回，不能跳过原件验真，也不能把文字内容直接当当前原件。
- 本人已从可信文件管理器删除登记原件
- 查询跳过缺失项并继续找有效候选，不删除索引或原件；现有计划维护调用 sync-current 后再移除该 occurrence 与级联文字/关系，保留来源及其他副本。
- 只有仍可核对的定位缺口命中
- hash_mismatch、not_openable 等返回 known_locator_gap 和原 open_state，不能称 verified_locator。
- 数据库身份不符
- 拒绝连接，不初始化或覆盖外部字节；由项目入口恢复正确的最小 SQLite。
真实入口
README.md定义普通请求、候选路径隐藏、find 优先和零命中范围。
materials.py实现 query signature、匹配评分、候选卡、来源范围和 find 命令。
schema.sql定义来源、材料、原生关系、绑定文字和可打开状态。
tests/test_materials.py覆盖自然查询、版本区分、路径隐藏、零命中与媒体历史行过滤。
如何验证
- 用虚构临时材料验证普通长描述能命中正确版本，并确认候选 JSON 不含 locator（原件定位记录）。
- 验证完全相同 SHA-256 与同逻辑版本族分别统计，不互相冒充。
- 分别构造 verified、unverified、missing、hash_mismatch、not_openable，确认三个 lookup_stage 严格分层且缺口从不标成 verified_locator。
- 验证零命中返回来源范围、未搜索数量与缺口，而不是空对象或绝对不存在。
- 验证媒体历史行既不能成为来源，也不能通过 find 返回或打开。
- 隔离回归覆盖查询/状态/检查不改库，缺失项不占 limit，verified 全失效后正确回退，单文件来源删除可同步，以及维护仅级联移除失效项的独有关系/文字。
- 真实产品验收必须从自然请求开始，并最终选中、重新验真、打开一份真实原件；单元测试不能替代。
与其他模块的关系
这是主入口。候选清楚时进入“验真再打开”；没有合适登记候选且位置真正未知时才进入“有界发现”。“精确接入”持续为本模块提供小而可信的来源与版本事实。