

个人材料查找 · 功能说明
在不知道位置时仍能扩大一次搜索范围,但扩大过程可预期、可说明、不会变成后台全盘索引。10 月 20 日起,除蓝湖产品资料那一个文件夹外,登记过的普通文件夹也和微信收到的文件、下载文件夹一样每天记一份文件名清单:先查范围内全部清单,再对配上的现场核对;只有蓝湖产品资料仍按本次预算现场找,普通目录不再挑至多 8 个去现场搜。
当前情况:两条路都在用。文件名清单覆盖除蓝湖产品资料外的全部登记文件夹:35 个普通文件夹来源(蓝湖那一个除外),加上 5 个微信和下载来源(下载文件夹,以及微信新版、旧版客户端的主号和副号收件目录),共 73,041 条(11 月 06 日 14:26 计数);某个来源没刷完时会先用旧清单并明确报缺口:11 月 3 日 17:12 那次每日维护有 17 个来源到时间上限没刷完;最近一次 11 月 5 日 17:10 全部刷完,0 个来源没刷完。这只说明清单这次都更新了,不代表所有原件都重新核对过,也不等于下面的盘点变成了精确总数。11 月 4 日 09:08 的一次有界盘点在 20 秒时间上限处停下,已看到至少 87,272 个非媒体路径,其中至少 85,685 个尚未精确登记;这只是看到的下限,不是总数,和旧盘点数字的差也不能当成删了多少。
具体测试保留各自日期,页面不实时探测运行状态。
项目源码:私有仓库,源码未公开;用法与技术说明可在下面阅读。

个人材料查找 · 功能说明
在不知道位置时仍能扩大一次搜索范围,但扩大过程可预期、可说明、不会变成后台全盘索引。10 月 20 日起,除蓝湖产品资料那一个文件夹外,登记过的普通文件夹也和微信收到的文件、下载文件夹一样每天记一份文件名清单:先查范围内全部清单,再对配上的现场核对;只有蓝湖产品资料仍按本次预算现场找,普通目录不再挑至多 8 个去现场搜。
当前情况:两条路都在用。文件名清单覆盖除蓝湖产品资料外的全部登记文件夹:35 个普通文件夹来源(蓝湖那一个除外),加上 5 个微信和下载来源(下载文件夹,以及微信新版、旧版客户端的主号和副号收件目录),共 73,041 条(11 月 06 日 14:26 计数);某个来源没刷完时会先用旧清单并明确报缺口:11 月 3 日 17:12 那次每日维护有 17 个来源到时间上限没刷完;最近一次 11 月 5 日 17:10 全部刷完,0 个来源没刷完。这只说明清单这次都更新了,不代表所有原件都重新核对过,也不等于下面的盘点变成了精确总数。11 月 4 日 09:08 的一次有界盘点在 20 秒时间上限处停下,已看到至少 87,272 个非媒体路径,其中至少 85,685 个尚未精确登记;这只是看到的下限,不是总数,和旧盘点数字的差也不能当成删了多少。
具体测试保留各自日期,页面不实时探测运行状态。
项目源码:私有仓库,源码未公开;用法与技术说明可在下面阅读。

数字截至 2026 年 11 月 6 日

用途与实际影响
登记索引有意保持小而精确,必然不能覆盖每一份尚未接入的文件。直接递归所有登记目录会耗时、读取过量并把“查一次”变成持续维护。每次现找又太慢,所以除蓝湖产品资料外,全部登记目录都每天记一份不含内容的文件名清单;只有蓝湖产品资料那一个文件夹,仍在真正需要时有上限地现找一次。
我看完候选说“都不是,好像是别人微信发我的,再找一次”。系统在除蓝湖产品资料外的全部文件名清单里配对(说了“微信”就只查微信收到的文件),再对配上的文件现场确认它还在、还是普通文件;要查蓝湖产品资料,才现场看文件名和基本信息,到 2,500 个文件、12 层或 8 秒就停。最后告诉我哪些查过、哪些没查。
得到少量尚未登记的候选及其来源、原生容器、时间、大小和类型;候选仍不含真实路径,内容是否和以前一样、有没有重复,明确标为“选择后才计算”。

用途与实际影响
登记索引有意保持小而精确,必然不能覆盖每一份尚未接入的文件。直接递归所有登记目录会耗时、读取过量并把“查一次”变成持续维护。每次现找又太慢,所以除蓝湖产品资料外,全部登记目录都每天记一份不含内容的文件名清单;只有蓝湖产品资料那一个文件夹,仍在真正需要时有上限地现找一次。
我看完候选说“都不是,好像是别人微信发我的,再找一次”。系统在除蓝湖产品资料外的全部文件名清单里配对(说了“微信”就只查微信收到的文件),再对配上的文件现场确认它还在、还是普通文件;要查蓝湖产品资料,才现场看文件名和基本信息,到 2,500 个文件、12 层或 8 秒就停。最后告诉我哪些查过、哪些没查。
得到少量尚未登记的候选及其来源、原生容器、时间、大小和类型;候选仍不含真实路径,内容是否和以前一样、有没有重复,明确标为“选择后才计算”。

在文件名清单或蓝湖产品资料的现场查找中找到少量尚未登记的非媒体候选;选中后还需核对原件。
零命中、目录打不开或达到范围/时间上限时,给出实际看过和未看过的地方;清单还没刷新到的部分也会说明。
来源离线或本次预算未轮到它时标明未搜索,不改用猜出的路径;清单所在目录读不到时保留旧清单,但不把旧条目当成文件现在还在。

在文件名清单或蓝湖产品资料的现场查找中找到少量尚未登记的非媒体候选;选中后还需核对原件。
零命中、目录打不开或达到范围/时间上限时,给出实际看过和未看过的地方;清单还没刷新到的部分也会说明。
来源离线或本次预算未轮到它时标明未搜索,不改用猜出的路径;清单所在目录读不到时保留旧清单,但不把旧条目当成文件现在还在。

登记候选都不对时,要求再找一次;可以说明大概是微信收到的、下载的,还是在别的获准目录里。登记没有严格对上时,查文件名清单这一步会自动做,不用另说;只有蓝湖产品资料要明确再找一次才现场查。
- 原请求的名称或用途
- 希望限定的已获准来源(如有)


登记候选都不对时,要求再找一次;可以说明大概是微信收到的、下载的,还是在别的获准目录里。登记没有严格对上时,查文件名清单这一步会自动做,不用另说;只有蓝湖产品资料要明确再找一次才现场查。
- 原请求的名称或用途
- 希望限定的已获准来源(如有)



- 登记为 filesystem-directory 的非媒体来源(排除已经退役的媒体来源身份)现在有 35 个;10 月 20 日(提交 9b8e35c)起,其中只有蓝湖产品资料那一个文件夹保留现场扫描,其余都走文件名清单。
- 文件名清单支线覆盖登记为 filename-index-directory 的 5 个来源(微信收到的文件和下载文件夹)和上面除蓝湖外的 filesystem-directory 来源,清单存在第五张表 filename_entries;每天的维护(sync-current / refresh-filenames)刷新它,每个来源最多 10 万文件、整步最多 60 秒,这是维护额度,不是查找额度。
- 查找时先在选定范围的清单里按来源显示名和相对路径配对,单来源最多返回 40 个已现场复核的匹配;复核读取当前文件信息,跳过已不存在、读不到或不是普通文件的条目,用当前大小和时间生成候选。这一步没有拿当前大小、时间和清单旧值逐条比较,所以不能说明文件内容没变,内容一致性留到选中后的 SHA-256 核验。


- 登记为 filesystem-directory 的非媒体来源(排除已经退役的媒体来源身份)现在有 35 个;10 月 20 日(提交 9b8e35c)起,其中只有蓝湖产品资料那一个文件夹保留现场扫描,其余都走文件名清单。
- 文件名清单支线覆盖登记为 filename-index-directory 的 5 个来源(微信收到的文件和下载文件夹)和上面除蓝湖外的 filesystem-directory 来源,清单存在第五张表 filename_entries;每天的维护(sync-current / refresh-filenames)刷新它,每个来源最多 10 万文件、整步最多 60 秒,这是维护额度,不是查找额度。
- 查找时先在选定范围的清单里按来源显示名和相对路径配对,单来源最多返回 40 个已现场复核的匹配;复核读取当前文件信息,跳过已不存在、读不到或不是普通文件的条目,用当前大小和时间生成候选。这一步没有拿当前大小、时间和清单旧值逐条比较,所以不能说明文件内容没变,内容一致性留到选中后的 SHA-256 核验。
数字截至 2026 年 11 月 6 日

- 10 月 20 日(提交 9b8e35c)起,discover 不再给普通目录做相关性排序、挑子集或探测各根第一层(旧做法:每根最多看第一层 400 条名称,至多选 8 个来源平分额度)。除 ON_DEMAND_DIRECTORY_SOURCE_KEYS 里登记的那一个产品资料文件夹外,filesystem-directory 与 filename-index-directory 来源一律查 filename_entries 清单;显式来源提示只缩小范围。文件匹配只比对来源名称和相对路径,scope_description 里的举例词不当作整目录命中。
- find 在已登记元数据没有严格匹配时(即使已有模糊候选)也自动只读查询范围内全部清单,不现场扫目录;这时蓝湖来源以 live_scan_requires_discover 列入未搜索,要现场查须明确走 discover。
- 现场扫描只剩蓝湖这一个来源:最多 2500 个文件(MAX_DISCOVERY_FILES)、8 秒(MAX_DISCOVERY_SECONDS)、递归 12 层(MAX_DISCOVERY_DEPTH)。这些额度不包括清单查询,也不保证整个命令一定 8 秒内返回;清单查询每个来源最多返回 40 个现场复核过的匹配。
- 使用 os.scandir 的增量迭代器,在取得每一个下一目录项前检查文件与时间预算;不会先把整个目录读入内存或排序后才截断。
- 遍历不跟随符号链接;只读取目录项、文件名、相对目录和 stat,媒体扩展名或 MIME 类型直接跳过。
- 目录无法打开或某个目录项无法读取时,累计 directory_gap_count,并返回有限的相对目录、gap、错误类型样本与额外数量。
- 来源根经“门牌”解析:按最长目标前缀映射,门牌开着、是真目录联接、指向一致才读;同一原件的嵌套门牌统一成一个持久位置,避免重复发现;未登记的私密目标拒绝。
- 候选只保存内部选择凭据、标题、来源、原生容器、版本元数据和选择前状态;路径、哈希和重复信息不在此时计算。


- 10 月 20 日(提交 9b8e35c)起,discover 不再给普通目录做相关性排序、挑子集或探测各根第一层(旧做法:每根最多看第一层 400 条名称,至多选 8 个来源平分额度)。除 ON_DEMAND_DIRECTORY_SOURCE_KEYS 里登记的那一个产品资料文件夹外,filesystem-directory 与 filename-index-directory 来源一律查 filename_entries 清单;显式来源提示只缩小范围。文件匹配只比对来源名称和相对路径,scope_description 里的举例词不当作整目录命中。
- find 在已登记元数据没有严格匹配时(即使已有模糊候选)也自动只读查询范围内全部清单,不现场扫目录;这时蓝湖来源以 live_scan_requires_discover 列入未搜索,要现场查须明确走 discover。
- 现场扫描只剩蓝湖这一个来源:最多 2500 个文件(MAX_DISCOVERY_FILES)、8 秒(MAX_DISCOVERY_SECONDS)、递归 12 层(MAX_DISCOVERY_DEPTH)。这些额度不包括清单查询,也不保证整个命令一定 8 秒内返回;清单查询每个来源最多返回 40 个现场复核过的匹配。
- 使用 os.scandir 的增量迭代器,在取得每一个下一目录项前检查文件与时间预算;不会先把整个目录读入内存或排序后才截断。
- 遍历不跟随符号链接;只读取目录项、文件名、相对目录和 stat,媒体扩展名或 MIME 类型直接跳过。
- 目录无法打开或某个目录项无法读取时,累计 directory_gap_count,并返回有限的相对目录、gap、错误类型样本与额外数量。
- 来源根经“门牌”解析:按最长目标前缀映射,门牌开着、是真目录联接、指向一致才读;同一原件的嵌套门牌统一成一个持久位置,避免重复发现;未登记的私密目标拒绝。
- 候选只保存内部选择凭据、标题、来源、原生容器、版本元数据和选择前状态;路径、哈希和重复信息不在此时计算。





| 名词 | 意思 |
|---|---|
| Source routing(来源路由) | 有显式来源提示时只保留匹配来源;没有提示时查范围内全部清单。10 月 20 日前按相关性挑少数目录现场扫的做法已取消。 |
| Global budget(共同预算) | 现在只用于蓝湖产品资料的现场扫描:文件数、深度与总时间共同封顶;清单查询不占这份额度。 |
| 文件名清单 | 除蓝湖产品资料外,全部登记目录(含微信和下载)每天记的相对路径、大小和修改时间;不含内容,不是全文索引,查到后还要现场核对。 |
| stat(文件元数据) | 文件大小、修改时间和身份字段;发现阶段用它描述候选,但不读完整内容。 |
| Cutoff(截止) | 达到文件数、时间或进入来源前预算已耗尽;必须写明原因,不能冒充完整搜索。 |
| Unsearched source(未搜索来源) | 因显式来源提示、清单缺口,或蓝湖需单独 discover 而没有查到的登记来源;零命中时必须保留。 |

按同一句自然描述查范围内全部登记目录的每日文件名清单,配上的少量候选现场核对;只有蓝湖产品资料在机械上限内现场查看文件名、原生目录名和 stat;不读正文、不建全盘或全文索引。



按同一句自然描述查范围内全部登记目录的每日文件名清单,配上的少量候选现场核对;只有蓝湖产品资料在机械上限内现场查看文件名、原生目录名和 stat;不读正文、不建全盘或全文索引。

- 只在已登记且获准的来源内工作,不接受临时猜出的新根目录。
- 不跟随链接,不读取文件正文,不计算候选哈希;文件名清单只覆盖已登记目录(蓝湖产品资料除外),不扩出登记范围。
- 照片、视频、音频、录音和退役媒体来源全部跳过并转 personal-media。
- 候选阶段不输出真实路径;内部选择凭据只用于下一步验真。
- 零命中只覆盖本次实际查到的来源、清单已刷新的范围和蓝湖现场扫描的上限,不外推其他账号、设备或离线介质。
- 蓝湖现场扫描和盘点的枚举为了按预算立即停止,不先对全目录排序;一旦截止,本次看到的具体子集可能受 Windows 文件系统枚举顺序影响,不能称稳定完整列表。盘点数字同理,只是当次下限。
- 来源根不可访问: 该来源标为 searched=false 和 root_not_openable;继续与否只取决于剩余已获准来源,不猜替代路径。清单来源读不到时保留旧清单,但旧条目不当成现在还在。
- 门牌关着、错配或未登记: 返回对应门牌缺口,不当成文件没了。

- 只在已登记且获准的来源内工作,不接受临时猜出的新根目录。
- 不跟随链接,不读取文件正文,不计算候选哈希;文件名清单只覆盖已登记目录(蓝湖产品资料除外),不扩出登记范围。
- 照片、视频、音频、录音和退役媒体来源全部跳过并转 personal-media。
- 候选阶段不输出真实路径;内部选择凭据只用于下一步验真。
- 零命中只覆盖本次实际查到的来源、清单已刷新的范围和蓝湖现场扫描的上限,不外推其他账号、设备或离线介质。
- 蓝湖现场扫描和盘点的枚举为了按预算立即停止,不先对全目录排序;一旦截止,本次看到的具体子集可能受 Windows 文件系统枚举顺序影响,不能称稳定完整列表。盘点数字同理,只是当次下限。
- 来源根不可访问: 该来源标为 searched=false 和 root_not_openable;继续与否只取决于剩余已获准来源,不猜替代路径。清单来源读不到时保留旧清单,但旧条目不当成现在还在。
- 门牌关着、错配或未登记: 返回对应门牌缺口,不当成文件没了。

- 目录或目录项无法读取: 继续处理其余可读部分,并返回 directory_gap_count、有限 gap 样本、错误类型和额外 gap 数;零命中不能越过这些缺口。
- 蓝湖现场扫描达到文件或时间上限: 立即停止,记录 cutoff_reason、已检查文件/目录数和剩余未搜索来源;结果仍可返回,但不能称完整。
- 清单还没刷新到或只部分覆盖: 明确报缺口,可手动运行 refresh-filenames 接续;查询本身不刷新清单,不假装清单是最新的。每日维护到上限时 refresh-filenames 返回 partial、退出码仍是 0,维护子步骤记 complete,已完成的定位维护不回滚,也不阻断后面的云端媒体维护,原因写进回执 summary。2026-11-03 17:12 那次 filename_index_status=partial,17 个来源达到时间上限;2026-11-05 17:10:38 那次 refreshed、未完成来源 0。所以 complete 不代表清单完整,要看这个字段。
- 发现的都是媒体: 统计跳过数量,不返回媒体候选;需要媒体原件时转 personal-media。
- 没有任何候选: 返回 not_found、所有逐来源报告与未搜索摘要;建议补一个能改变来源路由或文件名匹配的线索。

- 目录或目录项无法读取: 继续处理其余可读部分,并返回 directory_gap_count、有限 gap 样本、错误类型和额外 gap 数;零命中不能越过这些缺口。
- 蓝湖现场扫描达到文件或时间上限: 立即停止,记录 cutoff_reason、已检查文件/目录数和剩余未搜索来源;结果仍可返回,但不能称完整。
- 清单还没刷新到或只部分覆盖: 明确报缺口,可手动运行 refresh-filenames 接续;查询本身不刷新清单,不假装清单是最新的。每日维护到上限时 refresh-filenames 返回 partial、退出码仍是 0,维护子步骤记 complete,已完成的定位维护不回滚,也不阻断后面的云端媒体维护,原因写进回执 summary。2026-11-03 17:12 那次 filename_index_status=partial,17 个来源达到时间上限;2026-11-05 17:10:38 那次 refreshed、未完成来源 0。所以 complete 不代表清单完整,要看这个字段。
- 发现的都是媒体: 统计跳过数量,不返回媒体候选;需要媒体原件时转 personal-media。
- 没有任何候选: 返回 not_found、所有逐来源报告与未搜索摘要;建议补一个能改变来源路由或文件名匹配的线索。

- AGENTS.md 限定未知位置、获准范围、媒体所有权、无全盘扫描和零命中语义。
- README.md 解释 discover 查范围内全部文件名清单、只有蓝湖来源保留有界现找、find 未严格命中时自动查清单、选择前不读正文/哈希和未搜索来源摘要。当前 README 写的是“已不存在的条目直接跳过,候选使用现场大小和修改时间”,与代码一致。
- materials.py 实现文件名清单查询与刷新、蓝湖来源的有界文件名遍历与共同预算、媒体跳过、门牌和发现结果。
- tests/test_materials.py 覆盖未知位置发现、零命中、文件名清单查询、来源根绑定、门牌和媒体跳过(具体测试名本次未逐条核对)。
- 构造多个虚构普通目录来源,证明 discover 查全部清单、不再挑至多 8 个来源,蓝湖以外不做现场扫描;旧的“超过 8 个来源时挑相关来源”验证已随 10 月 20 日改动过时。
- 验证蓝湖现场扫描在 2500 个文件、12 层或 8 秒处截止,并报告截止原因。
- 验证候选没有真实路径或 native_id,且 hash_state 与 duplicate_state 明确为选择后才计算。
- 验证不跟随链接、跳过媒体、不可访问来源和达到截止均形成可解释报告。

- AGENTS.md 限定未知位置、获准范围、媒体所有权、无全盘扫描和零命中语义。
- README.md 解释 discover 查范围内全部文件名清单、只有蓝湖来源保留有界现找、find 未严格命中时自动查清单、选择前不读正文/哈希和未搜索来源摘要。当前 README 写的是“已不存在的条目直接跳过,候选使用现场大小和修改时间”,与代码一致。
- materials.py 实现文件名清单查询与刷新、蓝湖来源的有界文件名遍历与共同预算、媒体跳过、门牌和发现结果。
- tests/test_materials.py 覆盖未知位置发现、零命中、文件名清单查询、来源根绑定、门牌和媒体跳过(具体测试名本次未逐条核对)。
- 构造多个虚构普通目录来源,证明 discover 查全部清单、不再挑至多 8 个来源,蓝湖以外不做现场扫描;旧的“超过 8 个来源时挑相关来源”验证已随 10 月 20 日改动过时。
- 验证蓝湖现场扫描在 2500 个文件、12 层或 8 秒处截止,并报告截止原因。
- 验证候选没有真实路径或 native_id,且 hash_state 与 duplicate_state 明确为选择后才计算。
- 验证不跟随链接、跳过媒体、不可访问来源和达到截止均形成可解释报告。

- 注入目录与目录项读取错误,确认 gap 以相对目录和错误类型显式返回,而不是静默跳过。
- 用超过文件预算的增量枚举器确认达到上限后不再请求下一个目录项,并把截止子集标为本次枚举结果而非稳定全量排序。
- 真实验收必须在一个用户明确获准的来源范围内运行,并检查实际耗时、候选质量与零命中说明。10 月 11 日只跑了一次有界盘点,没有从一句自然请求一路找到、选中并打开一份真实原件,盘点不等于找到材料。
它是登记查找的按需后备,不是默认入口。找到候选后必须进入“验真与内容定位”;候选在此之前不进入“精确接入”索引。

- 注入目录与目录项读取错误,确认 gap 以相对目录和错误类型显式返回,而不是静默跳过。
- 用超过文件预算的增量枚举器确认达到上限后不再请求下一个目录项,并把截止子集标为本次枚举结果而非稳定全量排序。
- 真实验收必须在一个用户明确获准的来源范围内运行,并检查实际耗时、候选质量与零命中说明。10 月 11 日只跑了一次有界盘点,没有从一句自然请求一路找到、选中并打开一份真实原件,盘点不等于找到材料。
它是登记查找的按需后备,不是默认入口。找到候选后必须进入“验真与内容定位”;候选在此之前不进入“精确接入”索引。
复制 AI 续作说明
项目:没有合适候选时,先查文件名清单;只有蓝湖产品资料还现场找;仓库:页面未提供仓库地址;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。
把“目标”换成这次要做的事,整段复制给 AI。







