
个人材料查找 · 功能说明
先确认选中的确实是当前这份原件,再按需要核对里面的话在哪页、哪段或哪一行;只有要求在桌面查看时才启动阅读器。准备接入一批文件时,也可先按内容哈希核对电脑是否已有可靠原件,避免重复保存;文件变化会明确停止,旧定位不会悄悄指向另一份内容。
当前情况:选中后核对原件在用;定位页段文字和按需打开的入口都在,真实用过没有还说不准(没有留下记录)。登记的 171 份原件保存状态均为“已核验”(11 月 4 日计数)。这只是保存的状态,本次没有逐件打开或重算,也没有做从一句话到打开原件的真实验收。
具体测试保留各自日期,页面不实时探测运行状态。
项目源码:私有仓库,源码未公开;用法与技术说明可在下面阅读。


个人材料查找 · 功能说明
先确认选中的确实是当前这份原件,再按需要核对里面的话在哪页、哪段或哪一行;只有要求在桌面查看时才启动阅读器。准备接入一批文件时,也可先按内容哈希核对电脑是否已有可靠原件,避免重复保存;文件变化会明确停止,旧定位不会悄悄指向另一份内容。
当前情况:选中后核对原件在用;定位页段文字和按需打开的入口都在,真实用过没有还说不准(没有留下记录)。登记的 171 份原件保存状态均为“已核验”(11 月 4 日计数)。这只是保存的状态,本次没有逐件打开或重算,也没有做从一句话到打开原件的真实验收。
具体测试保留各自日期,页面不实时探测运行状态。
项目源码:私有仓库,源码未公开;用法与技术说明可在下面阅读。

数字截至 2026 年 11 月 6 日

用途与实际影响
候选生成与用户选择之间,文件可能被移动、替换或改写;来源根也可能重新挂载到别的位置。若只在发现时记一个路径,之后直接打开,用户得到的可能已不是当时看到的那一项。
我说“在刚选的合同里找到交付期限,告诉我在哪页或哪一段”。系统只核对并读取这一份原件,给出位置和相关片段;我再说“打开给我看”时才启动默认阅读器。若期间文件换了版本,就停止旧结果并说明变化。
交回这份文件的标题、来源、版本和本次核验结果;要找某句话时给 PDF 页、Word 正文段落或表格位置、文本行及有限片段。扫描 PDF 没文字层、Word 某些区域未覆盖时会直说;桌面阅读器是否真的打开另行说明。

用途与实际影响
候选生成与用户选择之间,文件可能被移动、替换或改写;来源根也可能重新挂载到别的位置。若只在发现时记一个路径,之后直接打开,用户得到的可能已不是当时看到的那一项。
我说“在刚选的合同里找到交付期限,告诉我在哪页或哪一段”。系统只核对并读取这一份原件,给出位置和相关片段;我再说“打开给我看”时才启动默认阅读器。若期间文件换了版本,就停止旧结果并说明变化。
交回这份文件的标题、来源、版本和本次核验结果;要找某句话时给 PDF 页、Word 正文段落或表格位置、文本行及有限片段。扫描 PDF 没文字层、Word 某些区域未覆盖时会直说;桌面阅读器是否真的打开另行说明。

确认选中原件的当前内容与来源后,只读交回文件或所需内容位置;明确要求桌面显示才启动阅读器。
文件不见了、版本改变、内容无法提取或应用启动失败时说清受影响部分;没有找到一句话不等于整份文件没有它。
来源暂不可读时停止验真;桌面启动失败不会抹掉已完成的只读文件核对。

确认选中原件的当前内容与来源后,只读交回文件或所需内容位置;明确要求桌面显示才启动阅读器。
文件不见了、版本改变、内容无法提取或应用启动失败时说清受影响部分;没有找到一句话不等于整份文件没有它。
来源暂不可读时停止验真;桌面启动失败不会抹掉已完成的只读文件核对。

选中一份候选,请 AI 核对、找词句,或明确要求桌面打开。
- 选定文件
- 待定位词句或桌面打开请求


选中一份候选,请 AI 核对、找词句,或明确要求桌面打开。
- 选定文件
- 待定位词句或桌面打开请求



数字截至 2026 年 11 月 6 日


- lookup-content 接收互斥的 --hashes-json / 可重复 --sha256,规范化并去重后最多 1000 项,以最多 900 个参数分批查询现有材料索引。只对精确命中的非媒体原件重新读取大小和 SHA-256;同内容的多个已验证位置都返回。缺失、不可读和内容漂移留在 unverified;not_indexed 只表示当前登记切片没有该哈希。命令不扫描目录、登记、复制或启动阅读器。
- inspect 与 inspect-discovered 使用只读数据库连接,按选中身份验证当前 locator(原件定位记录)、门牌、来源根、大小与 SHA-256;缺失或漂移只返回 gap。open / open-discovered 才保留状态写回和登记事务。
- 旧的绝对定位在只读连接回读时映射成门牌入口,不批量改写数据库。
- locate-content 接收互斥的 --id / --token,在同一个已核验的原件上提取文字并匹配有限片段;读取结束再次验证大小、文件身份和 SHA-256,变化时拒绝旧片段。
- PDF 仅提取文字层;DOCX 遍历顶层正文段落和顶层表格单元格,明确排除嵌套表格、页眉页脚、文本框与嵌入对象;TXT/MD 返回行号和编码覆盖。整份 PDF 无可提取文字时返回单件 OCR(光学字符识别)接续,命令本身不启动 OCR。
- 发现候选使用可解码的 discovery token(发现候选令牌),它是 URL-safe Base64(网址安全编码)选择句柄,内容是 schema(数据结构)版本、来源键、相对位置、大小、修改时间和来源根承诺;它不是签名、秘密或动作授权。


- lookup-content 接收互斥的 --hashes-json / 可重复 --sha256,规范化并去重后最多 1000 项,以最多 900 个参数分批查询现有材料索引。只对精确命中的非媒体原件重新读取大小和 SHA-256;同内容的多个已验证位置都返回。缺失、不可读和内容漂移留在 unverified;not_indexed 只表示当前登记切片没有该哈希。命令不扫描目录、登记、复制或启动阅读器。
- inspect 与 inspect-discovered 使用只读数据库连接,按选中身份验证当前 locator(原件定位记录)、门牌、来源根、大小与 SHA-256;缺失或漂移只返回 gap。open / open-discovered 才保留状态写回和登记事务。
- 旧的绝对定位在只读连接回读时映射成门牌入口,不批量改写数据库。
- locate-content 接收互斥的 --id / --token,在同一个已核验的原件上提取文字并匹配有限片段;读取结束再次验证大小、文件身份和 SHA-256,变化时拒绝旧片段。
- PDF 仅提取文字层;DOCX 遍历顶层正文段落和顶层表格单元格,明确排除嵌套表格、页眉页脚、文本框与嵌入对象;TXT/MD 返回行号和编码覆盖。整份 PDF 无可提取文字时返回单件 OCR(光学字符识别)接续,命令本身不启动 OCR。
- 发现候选使用可解码的 discovery token(发现候选令牌),它是 URL-safe Base64(网址安全编码)选择句柄,内容是 schema(数据结构)版本、来源键、相对位置、大小、修改时间和来源根承诺;它不是签名、秘密或动作授权。

- 解析相对位置时拒绝绝对路径与上级跳转,并复核最终路径仍位于登记来源根内。
- 以打开的文件句柄计算 SHA-256,在读取前、读取后和提交前比较文件与路径身份,防止中途替换。
- 原子事务检查稳定 material_key 与 source/native_id 唯一性;冲突或再次变化时回滚。
- 同一 source/native_id 的发现路径若内容 SHA-256 已变化,会先删除旧 material_text,再用当前 mtime/size 更新 version_id、按来源文件名更新 version_role,并写入当前来源时间、大小和哈希。
- open 对登记项保留同一 VerifiedFile 句柄,并在 os.startfile 前重新读取完整字节、比较原摘要和文件身份;open-discovered 在 SQLite 提交后重新打开并哈希当前文件,再与刚登记摘要比较。
- 两条打开路线复验通过后才调用 Windows os.startfile(path);启动失败记录 not_openable,但与 hash_mismatch、missing 分开。


- 解析相对位置时拒绝绝对路径与上级跳转,并复核最终路径仍位于登记来源根内。
- 以打开的文件句柄计算 SHA-256,在读取前、读取后和提交前比较文件与路径身份,防止中途替换。
- 原子事务检查稳定 material_key 与 source/native_id 唯一性;冲突或再次变化时回滚。
- 同一 source/native_id 的发现路径若内容 SHA-256 已变化,会先删除旧 material_text,再用当前 mtime/size 更新 version_id、按来源文件名更新 version_role,并写入当前来源时间、大小和哈希。
- open 对登记项保留同一 VerifiedFile 句柄,并在 os.startfile 前重新读取完整字节、比较原摘要和文件身份;open-discovered 在 SQLite 提交后重新打开并哈希当前文件,再与刚登记摘要比较。
- 两条打开路线复验通过后才调用 Windows os.startfile(path);启动失败记录 not_openable,但与 hash_mismatch、missing 分开。





| 名词 | 意思 |
|---|---|
| Root commitment(来源根承诺) | 来源根当前解析结果的内部指纹;根目录换到另一位置时,旧选择必须失效。 |
| Base64 selection handle(Base64 选择句柄) | 把发现时的来源与文件元数据编码成可解码 JSON 的执行层句柄;它不签名、不保密、也不授权打开,真正完整性仍来自随后重读来源根、stat 与 SHA-256。 |
| File signature(文件身份) | 文件句柄与路径的设备、文件、大小和时间字段组合,用于检测读取前后是否换成另一项。 |
| Identity conflict(身份冲突) | 稳定材料键或 source/native_id 已指向另一身份;事务必须回滚,而不是覆盖。 |
| verified / opened | verified 只表示当前字节核验通过;opened 还表示系统已接受启动请求,两者都不等于用户已经阅读。 |
| open_state | unverified、verified、not_openable、missing 或 hash_mismatch;每种状态对应不同恢复动作。 |

登记候选与发现候选都先只读核验;选定原件可继续返回页、段落、单元格或行位置,桌面打开保留为用户明确要求的独立动作。



登记候选与发现候选都先只读核验;选定原件可继续返回页、段落、单元格或行位置,桌面打开保留为用户明确要求的独立动作。

- inspect、inspect-discovered 与 locate-content 只读取用户或上层流程已经明确选中的一项,不批量为普通候选计算哈希;locate-content 最多返回 10 个位置、每段最多 280 字符并保留截断。独立的 lookup-content 接收已选内容哈希批次,只复核现有索引精确命中。
- 路径必须留在登记来源根内,不接受绝对路径、上级跳转或链接逃逸;加密文件夹只经登记过的门牌进入。
- 发现候选在成功提交前仍不是登记材料,也不能在搜索结果中冒充已核验。
- 默认应用启动不等于用户阅读完成,更不等于提交、签署或平台收到。
- 媒体即使持有旧材料记录或构造出的选择凭据,也会在读取字节前被拒绝。
- Windows os.startfile 消费的是路径而不是已验证文件句柄;即使启动前立即重哈希,最后一次复验与系统消费路径之间仍有极小竞争窗口。
- SQLite 提交与外部文件系统变化不能组成一个原子事务;发现路线用提交前身份检查、提交后启动前重哈希和后续每次 open 复核收窄风险,但不宣称数学上的零窗口。
- 内容哈希没有已验证命中: 精确索引行缺失、不可读或字节漂移时返回 unverified 与原因;没有登记行则为 not_indexed,不能据此判断其他磁盘或未登记来源不存在。

- inspect、inspect-discovered 与 locate-content 只读取用户或上层流程已经明确选中的一项,不批量为普通候选计算哈希;locate-content 最多返回 10 个位置、每段最多 280 字符并保留截断。独立的 lookup-content 接收已选内容哈希批次,只复核现有索引精确命中。
- 路径必须留在登记来源根内,不接受绝对路径、上级跳转或链接逃逸;加密文件夹只经登记过的门牌进入。
- 发现候选在成功提交前仍不是登记材料,也不能在搜索结果中冒充已核验。
- 默认应用启动不等于用户阅读完成,更不等于提交、签署或平台收到。
- 媒体即使持有旧材料记录或构造出的选择凭据,也会在读取字节前被拒绝。
- Windows os.startfile 消费的是路径而不是已验证文件句柄;即使启动前立即重哈希,最后一次复验与系统消费路径之间仍有极小竞争窗口。
- SQLite 提交与外部文件系统变化不能组成一个原子事务;发现路线用提交前身份检查、提交后启动前重哈希和后续每次 open 复核收窄风险,但不宣称数学上的零窗口。
- 内容哈希没有已验证命中: 精确索引行缺失、不可读或字节漂移时返回 unverified 与原因;没有登记行则为 not_indexed,不能据此判断其他磁盘或未登记来源不存在。

- 门牌关着、错配或没登记: 返回 folder_door_closed_or_mismatched 或 folder_door_not_registered,不猜替代目标,也不当成原件被删。
- 登记 locator(原件定位记录)在可访问可信根中已不存在: inspect 返回 locator_missing,不改索引、不猜相邻路径、不恢复文件;清单在每天 17:10 的 sync-current 维护中跟随删除。来源根整个不可用只报不可用,不算删除。
- 大小或 SHA-256 漂移: 只读检查返回 size_match/hash_match 与精确 gap,不改索引;明确打开动作才写回 hash_mismatch。旧版本不打开,重新发现后再选定。
- 选定原件没有可提取文字或只部分覆盖: 返回格式、区域、编码和截断范围;整份 PDF 无文字层时指出单件 OCR 缺口,不把部分零命中当成整份原件不存在该内容。
- 来源根或候选 stat 改变: 返回 refresh_required、root_changed 或 candidate_changed;旧内部选择凭据失效,重新 discover。
- 读取期间文件改变: 事务回滚并返回 changed_during_hash;不留下新材料记录。
- 稳定身份冲突: 回滚并返回 identity_conflict;保留既有记录,等待检查来源与相对位置。
- 同一路径内容已更新: 保留稳定 source/native 身份,刷新 version_id/version_role、时间、大小与哈希,并删除旧 material_text;没有本次新文字时保持为空,不能沿用旧派生内容。

- 门牌关着、错配或没登记: 返回 folder_door_closed_or_mismatched 或 folder_door_not_registered,不猜替代目标,也不当成原件被删。
- 登记 locator(原件定位记录)在可访问可信根中已不存在: inspect 返回 locator_missing,不改索引、不猜相邻路径、不恢复文件;清单在每天 17:10 的 sync-current 维护中跟随删除。来源根整个不可用只报不可用,不算删除。
- 大小或 SHA-256 漂移: 只读检查返回 size_match/hash_match 与精确 gap,不改索引;明确打开动作才写回 hash_mismatch。旧版本不打开,重新发现后再选定。
- 选定原件没有可提取文字或只部分覆盖: 返回格式、区域、编码和截断范围;整份 PDF 无文字层时指出单件 OCR 缺口,不把部分零命中当成整份原件不存在该内容。
- 来源根或候选 stat 改变: 返回 refresh_required、root_changed 或 candidate_changed;旧内部选择凭据失效,重新 discover。
- 读取期间文件改变: 事务回滚并返回 changed_during_hash;不留下新材料记录。
- 稳定身份冲突: 回滚并返回 identity_conflict;保留既有记录,等待检查来源与相对位置。
- 同一路径内容已更新: 保留稳定 source/native 身份,刷新 version_id/version_role、时间、大小与哈希,并删除旧 material_text;没有本次新文字时保持为空,不能沿用旧派生内容。

- SQLite 提交后、启动前文件又变化: open-discovered 的第二次哈希或 open 的同句柄重哈希失败,写回 hash_mismatch 与 before_launch gap,不调用 os.startfile。
- 默认应用启动失败: 记录 not_openable 和 launcher_failed;不把已通过字节核验的事实改写成哈希失败。

- SQLite 提交后、启动前文件又变化: open-discovered 的第二次哈希或 open 的同句柄重哈希失败,写回 hash_mismatch 与 before_launch gap,不调用 os.startfile。
- 默认应用启动失败: 记录 not_openable 和 launcher_failed;不把已通过字节核验的事实改写成哈希失败。

- README.md 定义候选选择后才哈希、登记并打开,门牌入口,以及登记项每次打开前重新核对。
- materials.py 实现选择凭据、来源根承诺、门牌、路径约束、SHA-256、事务、状态写回和启动器调用。
- schema.sql 定义稳定材料身份、source/native_id 唯一性和五种 open_state。
- tests/test_materials.py 覆盖来源根变化、每候选独立来源根、读取中变化、身份冲突回滚、哈希漂移、门牌与媒体拒绝(74 个测试函数、123 个用例定义,10 月 22 日静态计数,本次没有运行)。
- 验证登记文件缺失、大小变化和字节变化分别形成 missing 或 hash_mismatch,且不会启动应用。
- 验证同一相对位置在不同来源中使用各自来源根,不能借另一个候选的根通过。
- 在哈希读取期间模拟文件身份变化,确认事务回滚且没有新增材料记录。
- 预置冲突稳定身份,确认既有记录和候选都不被覆盖。

- README.md 定义候选选择后才哈希、登记并打开,门牌入口,以及登记项每次打开前重新核对。
- materials.py 实现选择凭据、来源根承诺、门牌、路径约束、SHA-256、事务、状态写回和启动器调用。
- schema.sql 定义稳定材料身份、source/native_id 唯一性和五种 open_state。
- tests/test_materials.py 覆盖来源根变化、每候选独立来源根、读取中变化、身份冲突回滚、哈希漂移、门牌与媒体拒绝(74 个测试函数、123 个用例定义,10 月 22 日静态计数,本次没有运行)。
- 验证登记文件缺失、大小变化和字节变化分别形成 missing 或 hash_mismatch,且不会启动应用。
- 验证同一相对位置在不同来源中使用各自来源根,不能借另一个候选的根通过。
- 在哈希读取期间模拟文件身份变化,确认事务回滚且没有新增材料记录。
- 预置冲突稳定身份,确认既有记录和候选都不被覆盖。
数字截至 2026 年 11 月 6 日

- 让同一来源相对路径出现新内容,确认 version_id/version_role 刷新、旧 material_text 清空且稳定材料身份不重绑。
- 分别在登记项启动前重哈希和发现项提交后重哈希时制造变化,确认 os.startfile 从未被调用并写回 before_launch gap。
- 将 Windows 路径消费的最后竞争窗口和 SQLite/文件系统非原子边界保留为已知限制,不用单元测试冒充已经消除。
- 真实端到端验收必须记录自然请求、候选选择、核验耗时、打开结果与用户实际看到的原件;截至 10 月 11 日还没有这样的验收记录。
它是登记查找和有界发现的共同收口:前两者只缩小候选,这里只读证明原件身份,并按请求定位内容。只有明确登记或桌面打开路径才把发现候选加入索引。

- 让同一来源相对路径出现新内容,确认 version_id/version_role 刷新、旧 material_text 清空且稳定材料身份不重绑。
- 分别在登记项启动前重哈希和发现项提交后重哈希时制造变化,确认 os.startfile 从未被调用并写回 before_launch gap。
- 将 Windows 路径消费的最后竞争窗口和 SQLite/文件系统非原子边界保留为已知限制,不用单元测试冒充已经消除。
- 真实端到端验收必须记录自然请求、候选选择、核验耗时、打开结果与用户实际看到的原件;截至 10 月 11 日还没有这样的验收记录。
它是登记查找和有界发现的共同收口:前两者只缩小候选,这里只读证明原件身份,并按请求定位内容。只有明确登记或桌面打开路径才把发现候选加入索引。
复制 AI 续作说明
项目:先验证选定原件,再定位页、段落或行;按需要打开阅读器;仓库:页面未提供仓库地址;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。
把“目标”换成这次要做的事,整段复制给 AI。







