用途与实际影响
这项功能怎样使用
为什么需要它
登记索引有意保持小而精确，必然不能覆盖每一份尚未接入的文件。直接递归所有登记目录会耗时、读取过量并把“查一次”变成持续维护。发现因此只在真正需要时运行一次，并让所有来源共享硬上限。
举个实际例子
我看完候选说“都不是，再去我允许的几个目录里找一次”。系统只挑最相关的地方查看文件名、目录名和基本信息；到达本次上限就停，并告诉我哪些目录查过、哪些还没查，不把一次查找扩成全盘扫描。
最后我会得到什么
得到少量尚未登记的候选及其来源、原生容器、时间、大小和类型；候选仍不含真实路径，哈希与重复状态明确标为“选择后才计算”。
有发现候选时
只在本次相关的获准目录中找到少量尚未登记的非媒体候选；选中后还需核对原件。
零命中或达到上限时
零命中、目录打不开或达到范围/时间上限时，给出实际看过和未看过的地方。
来源根不可用时
来源离线或本次预算未轮到它时标明未搜索，不改用猜出的路径。
从哪里开始
登记候选都不对时，要求在获准的几个目录再找一次。
需要准备什么
- 原请求的名称或用途
- 希望限定的已获准来源（如有）
从开始到拿到结果
- 1
系统核对并处理
只选相关目录，有上限地看文件名和基本信息，跳过媒体及已登记文件，记录不可读和截断处。
- 2
交付与接续
交回待验证候选与已查、未查范围；没有找到不等于其他目录不存在。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
本轮已见至少 194,540 个尚未精确登记的非媒体路径条目；3 个来源根不可达，未截止也不代表完整总数。来源路由、共同预算、媒体跳过、链接拒绝、未搜索来源摘要和根绑定由 2026-09-07 基线 66 项合成回归与 Ruff 通过；不覆盖后来新增的 lookup-content，本轮未重跑 支持。关键规则与设计选择
只有登记查找没有合适结果时才付出文件系统遍历成本。
来源数量、文件数、深度和总时间共同封顶，多个来源不会各自得到一份无限预算。
选择前不读取正文和完整字节，不把一次搜索变成批量内容摄取。
未搜索来源与截止原因显式返回，用户知道零命中到底能说明什么。
本模块用到的名词
- Source routing（来源路由）
- 根据当前请求选择最相关的已获准来源，而不是每次扫遍所有来源。
- Global budget（共同预算）
- 多个来源共享文件数与总时间限制，不能每个来源重新获得完整额度。
- stat（文件元数据）
- 文件大小、修改时间和身份字段；发现阶段用它描述候选，但不读完整内容。
- Cutoff（截止）
- 达到文件数、时间或进入来源前预算已耗尽；必须写明原因，不能冒充完整搜索。
- Unsearched source（未搜索来源）
- 因请求路由、显式来源提示或全局预算没有进入的登记来源；零命中时必须保留。
专业定义
按同一句自然描述选择最相关的少量来源，在全局机械上限内只查看文件名、原生目录名和 stat；不预扫描、不持续索引。
解决什么
解决未知位置下需要扩大查找、但不能全盘扫描、持续索引、跟随链接或无边界读取文件的问题。
当前怎样实现
- 只选择登记为 filesystem-directory 的非媒体来源，并排除已经退役的媒体来源身份。
- 先用请求与来源显示名、范围说明、来源键和根定位做机械相关性排序；有强来源词时只选同强度候选。
- 最多选择 8 个来源；所有来源共享 2500 个文件和 8 秒，单来源递归深度最多 12。
- 使用 os.scandir 的增量迭代器，在取得每一个下一目录项前检查文件与时间预算；不会先把整个目录读入内存或排序后才截断。
- 遍历不跟随符号链接；只读取目录项、文件名、相对目录和 stat，媒体扩展名或 MIME 类型直接跳过。
- 目录无法打开或某个目录项无法读取时，累计 directory_gap_count，并返回有限的相对目录、gap、错误类型样本与额外数量。
- 候选只保存内部选择凭据、标题、来源、原生容器、版本元数据和选择前状态；路径、哈希和重复信息不在此时计算。
执行流程
- 1
确认 find 没有合适候选，并且用户确实不知道位置。
- 2
取获准文件目录来源；显式来源提示存在时只保留匹配来源。
- 3
按请求线索给来源排序，选择最相关的有界子集，并记录未选原因。
- 4
公平分配剩余文件预算，逐项枚举文件名与目录名；在请求下一个目录项前达到任一全局上限就立即停止。
- 5
去掉已经登记的定位和全部媒体，只保留少量最高分候选。
- 6
返回候选、逐来源扫描报告、未搜索来源摘要和共同限制；不写入索引。
边界
- 只在已登记且获准的文件目录来源内工作，不接受临时猜出的新根目录。
- 不跟随链接，不读取文件正文，不计算候选哈希，不建立持续索引。
- 照片、视频、音频、录音和退役媒体来源全部跳过并转 personal-media。
- 候选阶段不输出真实路径；内部选择凭据只用于下一步验真。
- 零命中只覆盖本次实际选中来源和共同上限，不外推其他账号、设备或离线介质。
- 枚举为了按预算立即停止，不先对全目录排序；一旦截止，本次看到的具体子集可能受 Windows 文件系统枚举顺序影响，不能称稳定完整列表。
失败与恢复
- 来源根不可访问
- 该来源标为 searched=false 和 root_not_openable；继续与否只取决于剩余已获准来源，不猜替代路径。
- 目录或目录项无法读取
- 继续处理其余可读部分，并返回 directory_gap_count、有限 gap 样本、错误类型和额外 gap 数；零命中不能越过这些缺口。
- 达到共同文件或时间上限
- 立即停止，记录 cutoff_reason、已检查文件/目录数和剩余未搜索来源；结果仍可返回，但不能称完整。
- 发现的都是媒体
- 统计跳过数量，不返回媒体候选；需要媒体原件时转 personal-media。
- 没有任何候选
- 返回 not_found、所有逐来源报告与未搜索摘要；建议补一个能改变来源路由或文件名匹配的线索。
真实入口
AGENTS.md限定未知位置、获准范围、媒体所有权、无全盘扫描和零命中语义。
README.md解释 discover 的选择条件、共同上限、选择前不读正文/哈希和未搜索来源摘要。
materials.py实现来源优先级、文件名遍历、共同预算、媒体跳过和发现结果。
tests/test_materials.py覆盖未知位置发现、零命中、八来源路由、来源根绑定和媒体跳过。
如何验证
- 构造超过 8 个虚构来源，证明请求线索会选择相关来源并报告其余未搜索数量。
- 验证所有选中来源共享 2500 个文件和 8 秒，而不是各自获得完整预算。
- 验证候选没有真实路径或 native_id，且 hash_state 与 duplicate_state 明确为选择后才计算。
- 验证不跟随链接、跳过媒体、不可访问来源和达到截止均形成可解释报告。
- 注入目录与目录项读取错误，确认 gap 以相对目录和错误类型显式返回，而不是静默跳过。
- 用超过文件预算的增量枚举器确认达到上限后不再请求下一个目录项，并把截止子集标为本次枚举结果而非稳定全量排序。
- 真实验收必须在一个用户明确获准的来源范围内运行，并检查实际耗时、候选质量与零命中说明。
与其他模块的关系
它是登记查找的按需后备，不是默认入口。找到候选后必须进入“验真再打开”；候选在此之前不进入“精确接入”索引。