新材料只通过精确交接登记,原件字节始终留在原处
现在
在用
截至 11 月 6 日 · 材料库计数和备份日志

个人材料查找 · 功能说明

让以后能够快速查找,但不把所有文件搬进新目录,也不把材料项目扩成跨领域数据库。登记错了可以只撤一份,原件和来源都不动。

当前情况:现有 171 份登记,来自 56 个来源,4 条来源原生关系,161 份有可搜文字(32 份完整、129 份部分)、10 份没有;登记原件合计约 1.2 GB(11 月 4 日计数)。这些是既有状态,不代表这次接入了新原件。已登记原件后来补上的正文(比如扫描件认出的字),也走同一个精确交接小包:包里带完整原件身份,提取前后核对是同一份,不直接写数据库。撤一份登记的入口已经做好,还在等真实使用验收。

具体测试保留各自日期,页面不实时探测运行状态。

项目源码:私有仓库,源码未公开;用法与技术说明可在下面阅读。

新材料只通过精确交接登记,原件字节始终留在原处
现在
在用
截至 11 月 6 日 · 材料库计数和备份日志

个人材料查找 · 功能说明

让以后能够快速查找,但不把所有文件搬进新目录,也不把材料项目扩成跨领域数据库。登记错了可以只撤一份,原件和来源都不动。

当前情况:现有 171 份登记,来自 56 个来源,4 条来源原生关系,161 份有可搜文字(32 份完整、129 份部分)、10 份没有;登记原件合计约 1.2 GB(11 月 4 日计数)。这些是既有状态,不代表这次接入了新原件。已登记原件后来补上的正文(比如扫描件认出的字),也走同一个精确交接小包:包里带完整原件身份,提取前后核对是同一份,不直接写数据库。撤一份登记的入口已经做好,还在等真实使用验收。

具体测试保留各自日期,页面不实时探测运行状态。

项目源码:私有仓库,源码未公开;用法与技术说明可在下面阅读。

数字截至 2026 年 11 月 6 日

这项功能怎样使用

用途与实际影响

为什么需要它

自动爬盘建立全量索引会引入大量无消费者内容、旧版本和媒体重复;仅保存路径又无法确认后来打开的仍是同一字节。精确接入要求上游先选定对象,并让元数据、版本和哈希在写入前一致。

举个实际例子

另一个业务流程已经确认某份文件值得以后查找,我说“把它加进材料索引,原件别动”。系统会现场核对来源与内容,只记录以后定位它所需的最小信息;有一项对不上就整条拒绝,原件始终留在原处。

最后我会得到什么

得到一条可回查的登记:知道原件从哪个业务来、是哪一版、如今能否打开以及以后怎样定位。真实文件始终在原处;内容或来源对不上时整批拒绝。

这项功能怎样使用

用途与实际影响

为什么需要它

自动爬盘建立全量索引会引入大量无消费者内容、旧版本和媒体重复;仅保存路径又无法确认后来打开的仍是同一字节。精确接入要求上游先选定对象,并让元数据、版本和哈希在写入前一致。

举个实际例子

另一个业务流程已经确认某份文件值得以后查找,我说“把它加进材料索引,原件别动”。系统会现场核对来源与内容,只记录以后定位它所需的最小信息;有一项对不上就整条拒绝,原件始终留在原处。

最后我会得到什么

得到一条可回查的登记:知道原件从哪个业务来、是哪一版、如今能否打开以及以后怎样定位。真实文件始终在原处;内容或来源对不上时整批拒绝。

结果怎么看
精确交接一致时

来源业务交来已确认的非媒体文件,项目现场核对内容和版本后,只保存定位与必要的文字线索。

字段、字节或关系不一致时

来源不明、文件变了、关系对不上或混入媒体时整批拒绝,不留下半条登记。

原件或最小索引不可用时

原件或最小索引无法安全访问时停下,既不建立另一份材料库,也不复制原件绕过。

结果怎么看
精确交接一致时

来源业务交来已确认的非媒体文件,项目现场核对内容和版本后,只保存定位与必要的文字线索。

字段、字节或关系不一致时

来源不明、文件变了、关系对不上或混入媒体时整批拒绝,不留下半条登记。

原件或最小索引不可用时

原件或最小索引无法安全访问时停下,既不建立另一份材料库,也不复制原件绕过。

从哪里开始

在处理这份文件的原业务对话里说:把刚确认的非媒体原件登记到材料索引,以后能按线索找回来。

需要准备什么
  • 要让以后能找回的非媒体文件与所属业务
从开始到拿到结果
1系统核对并处理
只接确有用途的小组文件,提交前后核对来源、身份和字节;新版本清除旧派生文字。
2交付与接续
成功后可按来源与版本找回;字段矛盾或文件中途变化时整体拒绝,原件仍在原处。

不想再找到某一份 说“把那份的登记撤掉”:先预演,看清撤的是哪一份、写明原因,确认后同样的参数再执行一次才真撤;只删这一条登记和它的文字、关系,原件和来源都不动。

从哪里开始

在处理这份文件的原业务对话里说:把刚确认的非媒体原件登记到材料索引,以后能按线索找回来。

需要准备什么
  • 要让以后能找回的非媒体文件与所属业务
从开始到拿到结果
1系统核对并处理
只接确有用途的小组文件,提交前后核对来源、身份和字节;新版本清除旧派生文字。
2交付与接续
成功后可按来源与版本找回;字段矛盾或文件中途变化时整体拒绝,原件仍在原处。

不想再找到某一份 说“把那份的登记撤掉”:先预演,看清撤的是哪一份、写明原因,确认后同样的参数再执行一次才真撤;只删这一条登记和它的文字、关系,原件和来源都不动。

技术实现与依据(一)
这里保留实现、关键条件、精确入口、历史记录和验证结果。
11 月 4 日计数
171 条精确登记(保存状态均为 verified)、56 个来源(35 个普通目录、5 个文件名清单目录、11 个交接目录、5 个单文件)、4 条关系、161 份有绑定文字(按不同 material_key 去重;32 份 native/complete 原件自带完整文字,129 份 partial:115 份 extracted、14 份 ocr)、10 份没有文字;文件名清单 73,041 条;登记原件大小合计 1,218,168,484 字节。按类型(10 月 22 日 06:47 数):PDF 74、网页 20、Markdown 17、Word 18、表格 11、JSON 9、其他 22。status 的 search_texts 是绑定行数,这次恰好也是 161,份数仍按不同原件计。10 月 11 日计数时是 44 份(18 native、26 extracted),那时还没有 ocr 行。这些是登记汇总,不是这次重算哈希;本页未读取交接包正文。
测试记录
handoff 结构、稳定文件句柄、身份防重绑、文字清理和数据库身份的历史证据是 2026-09-07 基线 66 项合成回归与 Ruff 通过、9 月 28 日 106 项通过;当前测试文件 74 个测试函数、123 个用例定义(静态计数,本次没有运行)。门牌和撤登记有源码和测试定义,但还没有通过记录。
补正文
已登记原件追加正文也走 personal-materials.handoff.v1 小交接包,包内带完整原件身份;提取前后在同一原件上核验,再由精确接入写入绑定文字,不直接改数据库(README,提交 48b539d,10 月 21 日)。
关键规则与设计选择
1
来源责任项目先决定哪些原件值得接入,项目不为凑全景主动扫描。
2
路径、预期大小与 SHA-256 必须现场一致,交接回执不能替代真实文件。
3
filesystem-directory 来源根必须是绝对路径;相对根在进入发现或写入索引前直接拒绝。加密文件夹里的位置保存为“门牌”入口路径。
4
来源、材料、原生关系和绑定文字通过一个事务更新,失败不会留下部分新状态。
5
material_key 不能改绑到另一 source/native,既有 source/native 也不能改绑到另一 material_key。
6
同一材料的内容哈希发生变化时,旧 material_text 先清除;随后只写本次交接显式提供的新文字。
7
可重建文字明确区分 complete 与 partial;partial 必须写缺口,complete 不能带假缺口。
8
原件字节复制量固定为 0,索引可删除重建,原件仍由来源责任项目保管。
技术实现与依据(一)
这里保留实现、关键条件、精确入口、历史记录和验证结果。
11 月 4 日计数
171 条精确登记(保存状态均为 verified)、56 个来源(35 个普通目录、5 个文件名清单目录、11 个交接目录、5 个单文件)、4 条关系、161 份有绑定文字(按不同 material_key 去重;32 份 native/complete 原件自带完整文字,129 份 partial:115 份 extracted、14 份 ocr)、10 份没有文字;文件名清单 73,041 条;登记原件大小合计 1,218,168,484 字节。按类型(10 月 22 日 06:47 数):PDF 74、网页 20、Markdown 17、Word 18、表格 11、JSON 9、其他 22。status 的 search_texts 是绑定行数,这次恰好也是 161,份数仍按不同原件计。10 月 11 日计数时是 44 份(18 native、26 extracted),那时还没有 ocr 行。这些是登记汇总,不是这次重算哈希;本页未读取交接包正文。
测试记录
handoff 结构、稳定文件句柄、身份防重绑、文字清理和数据库身份的历史证据是 2026-09-07 基线 66 项合成回归与 Ruff 通过、9 月 28 日 106 项通过;当前测试文件 74 个测试函数、123 个用例定义(静态计数,本次没有运行)。门牌和撤登记有源码和测试定义,但还没有通过记录。
补正文
已登记原件追加正文也走 personal-materials.handoff.v1 小交接包,包内带完整原件身份;提取前后在同一原件上核验,再由精确接入写入绑定文字,不直接改数据库(README,提交 48b539d,10 月 21 日)。
关键规则与设计选择
1
来源责任项目先决定哪些原件值得接入,项目不为凑全景主动扫描。
2
路径、预期大小与 SHA-256 必须现场一致,交接回执不能替代真实文件。
3
filesystem-directory 来源根必须是绝对路径;相对根在进入发现或写入索引前直接拒绝。加密文件夹里的位置保存为“门牌”入口路径。
4
来源、材料、原生关系和绑定文字通过一个事务更新,失败不会留下部分新状态。
5
material_key 不能改绑到另一 source/native,既有 source/native 也不能改绑到另一 material_key。
6
同一材料的内容哈希发生变化时,旧 material_text 先清除;随后只写本次交接显式提供的新文字。
7
可重建文字明确区分 complete 与 partial;partial 必须写缺口,complete 不能带假缺口。
8
原件字节复制量固定为 0,索引可删除重建,原件仍由来源责任项目保管。

数字截至 2026 年 11 月 6 日

技术实现与依据(二)
9
撤一份登记(unregister)和撤一个来源(retire-source)是两个不同入口:前者只撤一条材料,后者只撤一个已经没有材料、根目录确实不在了的来源。
10
init 与 status 只是索引维护入口:前者建立或确认合法空结构,后者读取最小计数,二者都不证明用户已经找到原件。
当前怎样实现
  • 只接受顶层 schema(数据结构)、sources、materials、relations 和 texts 五组字段;未知字段直接拒绝。
  • init 只在索引不存在时创建空文件并执行 schema;已有文件必须同时通过 application_id/user_version、四个核心表存在、关键列集合与 PRAGMA integrity_check,才幂等返回 ready;外来或损坏数据库拒绝覆盖,首次建库失败只清理自己新建的占位。
  • 持久层共 5 张表:四个核心表 sources、materials、material_relations、material_text 分别拥有来源范围、原件定位、来源原生关系和与原件绑定的可重建文字;第五张 filename_entries 存文件名清单:10 月 20 日起覆盖除蓝湖产品资料外的全部登记目录(含微信和下载)。数据库身份核验仍只要求四个核心表与关键列。
  • 来源要求 source_key、类型、显示名、根定位、范围、观察时间、complete/partial/unknown 覆盖与显式 gaps;目前 4 个来源声明完整、52 个部分。
  • 材料要求来源原生身份、版本、角色、标题、绝对 locator(原件定位记录)、预期大小和 SHA-256;实现以同一稳定文件句柄依次取得 stat、完整哈希和读取后身份,并把句柄保持到事务提交前。
  • locator 与来源根按门牌表最长前缀映射成门牌入口,核对门牌开着、是真目录联接、指向一致;普通路径原样保存,旧索引只在读取时映射,不批量改写;同一原件的嵌套门牌统一成一个位置。
技术实现与依据(二)
9
撤一份登记(unregister)和撤一个来源(retire-source)是两个不同入口:前者只撤一条材料,后者只撤一个已经没有材料、根目录确实不在了的来源。
10
init 与 status 只是索引维护入口:前者建立或确认合法空结构,后者读取最小计数,二者都不证明用户已经找到原件。
当前怎样实现
  • 只接受顶层 schema(数据结构)、sources、materials、relations 和 texts 五组字段;未知字段直接拒绝。
  • init 只在索引不存在时创建空文件并执行 schema;已有文件必须同时通过 application_id/user_version、四个核心表存在、关键列集合与 PRAGMA integrity_check,才幂等返回 ready;外来或损坏数据库拒绝覆盖,首次建库失败只清理自己新建的占位。
  • 持久层共 5 张表:四个核心表 sources、materials、material_relations、material_text 分别拥有来源范围、原件定位、来源原生关系和与原件绑定的可重建文字;第五张 filename_entries 存文件名清单:10 月 20 日起覆盖除蓝湖产品资料外的全部登记目录(含微信和下载)。数据库身份核验仍只要求四个核心表与关键列。
  • 来源要求 source_key、类型、显示名、根定位、范围、观察时间、complete/partial/unknown 覆盖与显式 gaps;目前 4 个来源声明完整、52 个部分。
  • 材料要求来源原生身份、版本、角色、标题、绝对 locator(原件定位记录)、预期大小和 SHA-256;实现以同一稳定文件句柄依次取得 stat、完整哈希和读取后身份,并把句柄保持到事务提交前。
  • locator 与来源根按门牌表最长前缀映射成门牌入口,核对门牌开着、是真目录联接、指向一致;普通路径原样保存,旧索引只在读取时映射,不批量改写;同一原件的嵌套门牌统一成一个位置。

数字截至 2026 年 11 月 6 日

技术实现与依据(三)
  • BEGIN IMMEDIATE 后先拒绝 material_key→source/native 和 source/native→material_key 两个方向的身份重绑;写完来源、材料、关系和文字后,再检查所有稳定句柄身份仍一致,才提交。
  • 既有 material_key 的内容 SHA-256 变化时,在更新材料前删除该材料全部旧 material_text;之后只写本次 handoff 明确带来的 native、ocr(光学字符识别)或 extracted 文字。
  • 材料种类、MIME 或扩展名属于媒体时,在读取字节和计算哈希前返回 media_owned_by_personal_media,并把照片、视频、音频和录音交给 personal-media。
  • 关系两端必须指向本次或既有非媒体材料,并携带来源原生依据;不能连接到媒体历史项。
  • 绑定文字只允许 native、ocr、extracted,并保存文字 SHA-256、complete/partial 与 gaps;ASR(自动语音识别)和 transcript 不属于本项目。
  • unregister 用 --id 或完整 64 位 SHA-256 二选一指定,哈希必须恰好命中一条,--reason 必填;默认只预演,同样参数加 --apply 才写;只删除这条材料及外键级联的关系和文字,原件已不存在也能撤。
  • retire-source --key 只在来源根本身确实缺失、最近可读的上级不是卷根、根状态明确、且该来源不再定位任何材料时执行;根还在、上级读不到或还有材料都拒绝。
  • 成功结果只返回计数和 original_bytes_copied=0,不返回材料正文。status 只读汇总四个核心表的行数,并报告 background_process=false 与 original_bytes_copied=0;它不返回文件名清单条数,也不证明覆盖完整或原件当前可打开。background_process=false 只说材料命令自己没有常驻程序,不否认下面的每日维护任务。
技术实现与依据(三)
  • BEGIN IMMEDIATE 后先拒绝 material_key→source/native 和 source/native→material_key 两个方向的身份重绑;写完来源、材料、关系和文字后,再检查所有稳定句柄身份仍一致,才提交。
  • 既有 material_key 的内容 SHA-256 变化时,在更新材料前删除该材料全部旧 material_text;之后只写本次 handoff 明确带来的 native、ocr(光学字符识别)或 extracted 文字。
  • 材料种类、MIME 或扩展名属于媒体时,在读取字节和计算哈希前返回 media_owned_by_personal_media,并把照片、视频、音频和录音交给 personal-media。
  • 关系两端必须指向本次或既有非媒体材料,并携带来源原生依据;不能连接到媒体历史项。
  • 绑定文字只允许 native、ocr、extracted,并保存文字 SHA-256、complete/partial 与 gaps;ASR(自动语音识别)和 transcript 不属于本项目。
  • unregister 用 --id 或完整 64 位 SHA-256 二选一指定,哈希必须恰好命中一条,--reason 必填;默认只预演,同样参数加 --apply 才写;只删除这条材料及外键级联的关系和文字,原件已不存在也能撤。
  • retire-source --key 只在来源根本身确实缺失、最近可读的上级不是卷根、根状态明确、且该来源不再定位任何材料时执行;根还在、上级读不到或还有材料都拒绝。
  • 成功结果只返回计数和 original_bytes_copied=0,不返回材料正文。status 只读汇总四个核心表的行数,并报告 background_process=false 与 original_bytes_copied=0;它不返回文件名清单条数,也不证明覆盖完整或原件当前可打开。background_process=false 只说材料命令自己没有常驻程序,不否认下面的每日维护任务。
技术实现与依据(四)
1
只有项目索引尚不存在时才运行 init;已有索引要通过四个核心表、关键列和 integrity_check,身份不符或损坏文件原样保留并报错。
2
来源业务先选择一小组当前确有消费价值的非媒体原件。
3
生成 personal-materials.handoff.v1,填入来源范围、覆盖、材料原生身份、版本、大小与预期 SHA-256。
4
项目拒绝额外字段、非法覆盖状态、未知来源、悬空关系和不完整的 partial 文字说明。
5
逐材料确认真实文件存在、位于绝对 locator(经门牌核对)、不是媒体;在同一打开句柄上按 stat→完整 SHA-256→读取后身份完成首次稳定核对。
6
开始写事务后检查双向身份不能重绑;内容哈希变化先清旧 material_text,再写入本次来源、材料、原生关系和新文字。
7
所有写入完成后、提交前再次核对每个仍打开句柄的文件与路径身份;任何变化整体回滚。
  • 每日维护:PCConfig 登记的任务每天北京时间 17:10 在个人资料镜像前调用 sync-current(10 月 20 日起这一步还刷新除蓝湖外全部登记目录的文件名清单)。11 月 6 日 05:10 读日志:该步骤共 69 条记录,70 条 complete(最新一条完成于 11 月 6 日 08:25)、1 条 failed(10 月 22 日 17:10,退出码 125,后面又有成功记录,不是现在还在失败;根因没查)。任务 PersonalDataReplica-Hot-Daily 就绪,上次 11 月 5 日 17:10:01 结果 1,下次 11 月 6 日 17:10(11 月 6 日 05:19 只读,触发器每天北京时间 17:10;整项任务结果 1 的原因没查)。最新回执(11 月 5 日 17:10:38 完成):这一步 complete、退出码 0,removed_material_count=0、unavailable_source_count=0、filename_index_status=refreshed、filename_index_partial_sources 为空;11 月 3 日那次还是 partial、17 个来源达到时间上限,所以 complete 本身不代表文件名清单完整,要看这个字段。这只说明这一维护步骤的日志,不等于 70 次全量重算或备份全部成功。
执行流程
技术实现与依据(四)
1
只有项目索引尚不存在时才运行 init;已有索引要通过四个核心表、关键列和 integrity_check,身份不符或损坏文件原样保留并报错。
2
来源业务先选择一小组当前确有消费价值的非媒体原件。
3
生成 personal-materials.handoff.v1,填入来源范围、覆盖、材料原生身份、版本、大小与预期 SHA-256。
4
项目拒绝额外字段、非法覆盖状态、未知来源、悬空关系和不完整的 partial 文字说明。
5
逐材料确认真实文件存在、位于绝对 locator(经门牌核对)、不是媒体;在同一打开句柄上按 stat→完整 SHA-256→读取后身份完成首次稳定核对。
6
开始写事务后检查双向身份不能重绑;内容哈希变化先清旧 material_text,再写入本次来源、材料、原生关系和新文字。
7
所有写入完成后、提交前再次核对每个仍打开句柄的文件与路径身份;任何变化整体回滚。
  • 每日维护:PCConfig 登记的任务每天北京时间 17:10 在个人资料镜像前调用 sync-current(10 月 20 日起这一步还刷新除蓝湖外全部登记目录的文件名清单)。11 月 6 日 05:10 读日志:该步骤共 69 条记录,70 条 complete(最新一条完成于 11 月 6 日 08:25)、1 条 failed(10 月 22 日 17:10,退出码 125,后面又有成功记录,不是现在还在失败;根因没查)。任务 PersonalDataReplica-Hot-Daily 就绪,上次 11 月 5 日 17:10:01 结果 1,下次 11 月 6 日 17:10(11 月 6 日 05:19 只读,触发器每天北京时间 17:10;整项任务结果 1 的原因没查)。最新回执(11 月 5 日 17:10:38 完成):这一步 complete、退出码 0,removed_material_count=0、unavailable_source_count=0、filename_index_status=refreshed、filename_index_partial_sources 为空;11 月 3 日那次还是 partial、17 个来源达到时间上限,所以 complete 本身不代表文件名清单完整,要看这个字段。这只说明这一维护步骤的日志,不等于 70 次全量重算或备份全部成功。
执行流程

数字截至 2026 年 11 月 6 日

技术实现与依据(五)
8
返回 accepted 与最小数量回执,明确 original_bytes_copied=0;后续查找从登记索引读取。
9
原件被我在文件管理器里删掉后,每天的 sync-current 在来源根可读、原件确切不存在、事务重检仍成立时,移除这条登记及其独有文字和关系,保留其他副本;普通来源也保留,只有已经没有任何材料、又不承载文件名清单的交接目录来源(consumer-handoff-directory)登记会一并移除,目录和原件都不动;查询本身从不顺手同步。
技术实现与依据(五)
8
返回 accepted 与最小数量回执,明确 original_bytes_copied=0;后续查找从登记索引读取。
9
原件被我在文件管理器里删掉后,每天的 sync-current 在来源根可读、原件确切不存在、事务重检仍成立时,移除这条登记及其独有文字和关系,保留其他副本;普通来源也保留,只有已经没有任何材料、又不承载文件名清单的交接目录来源(consumer-handoff-directory)登记会一并移除,目录和原件都不动;查询本身从不顺手同步。
名词和入口(一)
本模块用到的名词
名词意思
Handoff(精确交接包)上游业务已经选定对象后提供的小 JSON 合同;不是让材料项目扫描来源的邀请。
Strict schema(严格结构)表和交接字段都明确列出,未知字段、类型与状态不能被静默忽略。
四个核心表+文件名清单表sources、materials、material_relations、material_text 分别保存来源、定位、原生关系和绑定文字;第五张 filename_entries 存文件名清单(10 月 20 日起除蓝湖产品资料外的全部登记目录,含微信和下载)。没有人物、事件或跨领域表。
init / statusinit 建立或确认合法最小结构;status 只读计数和零复制事实。它们是维护入口,不是查找、覆盖或真实端到端结果。
Stable file handle(稳定文件句柄)从首次 stat、完整哈希到提交前身份复核始终保持同一个打开句柄;它显著缩小替换窗口,但不能让外部文件系统加入 SQLite 原子事务。
Identity rebinding(身份重绑)同一 material_key 指向新的 source/native,或同一 source/native 改由另一 material_key 占用;两种情况都拒绝而不是覆盖。
Coverage state(覆盖状态)complete 表示所声明截面完整;partial 必须列缺口;unknown(未验证)保留未知,不靠默认值升级。
Native relation(来源原生关系)签字包、交付包、回执或其他版本关系必须来自来源自带事实,而不是模型跨来源推断。
名词和入口(一)
本模块用到的名词
名词意思
Handoff(精确交接包)
意思:
上游业务已经选定对象后提供的小 JSON 合同;不是让材料项目扫描来源的邀请。
Strict schema(严格结构)
意思:
表和交接字段都明确列出,未知字段、类型与状态不能被静默忽略。
四个核心表+文件名清单表
意思:
sources、materials、material_relations、material_text 分别保存来源、定位、原生关系和绑定文字;第五张 filename_entries 存文件名清单(10 月 20 日起除蓝湖产品资料外的全部登记目录,含微信和下载)。没有人物、事件或跨领域表。
init / status
意思:
init 建立或确认合法最小结构;status 只读计数和零复制事实。它们是维护入口,不是查找、覆盖或真实端到端结果。
Stable file handle(稳定文件句柄)
意思:
从首次 stat、完整哈希到提交前身份复核始终保持同一个打开句柄;它显著缩小替换窗口,但不能让外部文件系统加入 SQLite 原子事务。
Identity rebinding(身份重绑)
意思:
同一 material_key 指向新的 source/native,或同一 source/native 改由另一 material_key 占用;两种情况都拒绝而不是覆盖。
Coverage state(覆盖状态)
意思:
complete 表示所声明截面完整;partial 必须列缺口;unknown(未验证)保留未知,不靠默认值升级。
Native relation(来源原生关系)
意思:
签字包、交付包、回执或其他版本关系必须来自来源自带事实,而不是模型跨来源推断。
名词和入口(二)
名词意思
Rebuildable text(可重建文字)绑定到精确原件的 native、OCR(光学字符识别)或 extracted 文字;删除后可从同一原件重建。
撤一份登记/撤来源unregister 只撤一条材料登记,默认预演;retire-source 只撤一个已无材料、根目录确实不在的来源。两者都不碰原件。
专业定义

上游业务只交接已明确选择的一小组非媒体原件;项目现场复算大小与 SHA-256,接受定位元数据和可重建文字,不接管原件;登记可以按单份撤回。

名词和入口(二)
名词意思
Rebuildable text(可重建文字)
意思:
绑定到精确原件的 native、OCR(光学字符识别)或 extracted 文字;删除后可从同一原件重建。
撤一份登记/撤来源
意思:
unregister 只撤一条材料登记,默认预演;retire-source 只撤一个已无材料、根目录确实不在的来源。两者都不碰原件。
专业定义

上游业务只交接已明确选择的一小组非媒体原件;项目现场复算大小与 SHA-256,接受定位元数据和可重建文字,不接管原件;登记可以按单份撤回。

出问题时(一)
解决什么
解决无边界自动索引、路径记录无法证明当前字节、交接字段悄悄漂移、关系悬空、文字覆盖冒充完整、媒体重复所有权,以及登记错了只能整体重建的问题。
边界
  • 候选接入必须小而精确,没有当前消费者就不扩大来源或材料范围。
  • filesystem-directory 的来源根与每个材料 locator(原件定位记录)都必须是绝对路径;不把相对路径解释成当前工作目录。
  • 只接入非媒体;ASR(自动语音识别)、transcript、照片、视频、音频和录音全部由媒体路线拥有。
  • 不复制、移动、改写或删除原件;SQLite(轻量数据库)只保存最小元数据与可重建文字;撤登记也不碰原件。
  • 不保存事件、人物关系、重要性、领域判断、用户画像或跨来源推断。
  • status 中的表计数不代表来源 complete,也不证明任何登记 locator 当前仍可打开。
  • 稳定句柄的提交前复核无法把外部文件系统与 SQLite 合成单一原子事务;极小的提交后窗口由以后每次 inspect/open 再哈希兜底。
  • 交接成功不证明平台接收、接收方处理、合同生效或用户已经阅读;现实状态由领域责任项目判断。
出问题时(一)
解决什么
解决无边界自动索引、路径记录无法证明当前字节、交接字段悄悄漂移、关系悬空、文字覆盖冒充完整、媒体重复所有权,以及登记错了只能整体重建的问题。
边界
  • 候选接入必须小而精确,没有当前消费者就不扩大来源或材料范围。
  • filesystem-directory 的来源根与每个材料 locator(原件定位记录)都必须是绝对路径;不把相对路径解释成当前工作目录。
  • 只接入非媒体;ASR(自动语音识别)、transcript、照片、视频、音频和录音全部由媒体路线拥有。
  • 不复制、移动、改写或删除原件;SQLite(轻量数据库)只保存最小元数据与可重建文字;撤登记也不碰原件。
  • 不保存事件、人物关系、重要性、领域判断、用户画像或跨来源推断。
  • status 中的表计数不代表来源 complete,也不证明任何登记 locator 当前仍可打开。
  • 稳定句柄的提交前复核无法把外部文件系统与 SQLite 合成单一原子事务;极小的提交后窗口由以后每次 inspect/open 再哈希兜底。
  • 交接成功不证明平台接收、接收方处理、合同生效或用户已经阅读;现实状态由领域责任项目判断。
出问题时(二)
失败与恢复
  • 交接字段或 schema(数据结构)不匹配: 返回明确验证错误,整个交接不写入;由上游按当前合同重建小包。
  • filesystem-directory 根或材料 locator 不是绝对路径: 在扫描、哈希和写事务前拒绝;不依赖当前工作目录猜出一个位置。
  • 门牌关着、错配或没登记: 返回对应门牌缺口,这是访问受阻,不是删除证明。
  • 原件大小或 SHA-256 漂移: 拒绝接入,不接受旧回执或元数据;由来源责任项目重新确认当前版本。
  • 材料在首次哈希后、提交前发生变化: 稳定句柄身份复核失败,整个 SQLite 事务回滚,不留下来源、材料、关系或文字的部分新状态。
  • material_key 或 source/native 试图重绑: 返回 material_identity_conflict,保留原身份与全部既有记录,不用覆盖写入。
  • 同一材料内容哈希改变: 先删除全部旧 material_text,再只写本次交接提供的新文字;未提供新文字时保持为空,避免旧派生内容污染新字节。
  • 关系对象不存在或属于媒体: 拒绝关系与整个事务,不制造悬空或跨责任项目连接。
出问题时(二)
失败与恢复
  • 交接字段或 schema(数据结构)不匹配: 返回明确验证错误,整个交接不写入;由上游按当前合同重建小包。
  • filesystem-directory 根或材料 locator 不是绝对路径: 在扫描、哈希和写事务前拒绝;不依赖当前工作目录猜出一个位置。
  • 门牌关着、错配或没登记: 返回对应门牌缺口,这是访问受阻,不是删除证明。
  • 原件大小或 SHA-256 漂移: 拒绝接入,不接受旧回执或元数据;由来源责任项目重新确认当前版本。
  • 材料在首次哈希后、提交前发生变化: 稳定句柄身份复核失败,整个 SQLite 事务回滚,不留下来源、材料、关系或文字的部分新状态。
  • material_key 或 source/native 试图重绑: 返回 material_identity_conflict,保留原身份与全部既有记录,不用覆盖写入。
  • 同一材料内容哈希改变: 先删除全部旧 material_text,再只写本次交接提供的新文字;未提供新文字时保持为空,避免旧派生内容污染新字节。
  • 关系对象不存在或属于媒体: 拒绝关系与整个事务,不制造悬空或跨责任项目连接。
出问题时(三)
  • partial 文字没有 gap,或 complete 文字带 gap: 拒绝覆盖语义矛盾的数据,避免把残缺文字升级为完整。
  • 撤登记的哈希命中不止一条或没写原因: 拒绝;只预演时不写库。
  • 撤来源时根还在、上级读不到或来源还有材料: 拒绝,不用撤来源代替撤一份登记。
  • 来源根不可读、其他读取错误或文件还在但内容变了: 每日维护都不当成删除,登记保留并报缺口。
  • 数据库是外部、缺表缺列或损坏文件: 应用身份、四个核心表关键列或 integrity_check 失败;不初始化覆盖现有字节,只恢复正确的项目索引。
出问题时(三)
  • partial 文字没有 gap,或 complete 文字带 gap: 拒绝覆盖语义矛盾的数据,避免把残缺文字升级为完整。
  • 撤登记的哈希命中不止一条或没写原因: 拒绝;只预演时不写库。
  • 撤来源时根还在、上级读不到或来源还有材料: 拒绝,不用撤来源代替撤一份登记。
  • 来源根不可读、其他读取错误或文件还在但内容变了: 每日维护都不当成删除,登记保留并报缺口。
  • 数据库是外部、缺表缺列或损坏文件: 应用身份、四个核心表关键列或 integrity_check 失败;不初始化覆盖现有字节,只恢复正确的项目索引。
依据与来源(一)
真实入口
  • AGENTS.md 定义最小定位元数据、原件保护、无跨域推断、媒体分离和现场大小/哈希复核。
  • README.md 说明 handoff v1、已登记原件补正文的交接与覆盖核验、允许的绑定文字、门牌、unregister、retire-source、零原件复制和最小 SQLite 边界。
  • materials.py 实现字段验证、媒体判断、路径/大小/SHA-256 现场核对、门牌、关系与文字验证、事务写入和两种撤销入口(共 4,126 行)。
  • schema.sql 定义严格来源、材料、关系、绑定文字、文件名清单、唯一约束、外键级联与数据库应用身份。
  • tests/test_materials.py 覆盖额外字段、哈希漂移、外部数据库拒绝、失败初始化清理、媒体 handoff、零复制状态、门牌和撤登记(74 个测试函数、123 个用例定义,10 月 22 日静态计数,本次没有运行)。
如何验证
  • 以虚构临时文件生成精确 handoff,证明成功回执只含来源/材料/关系/文字数量和 original_bytes_copied=0。
  • 分别修改预期大小、SHA-256、额外字段、文字覆盖和关系端点,确认事务没有部分写入。
  • 验证 filesystem-directory 相对根和材料相对 locator 都在读取或写入前拒绝。
依据与来源(一)
真实入口
  • AGENTS.md 定义最小定位元数据、原件保护、无跨域推断、媒体分离和现场大小/哈希复核。
  • README.md 说明 handoff v1、已登记原件补正文的交接与覆盖核验、允许的绑定文字、门牌、unregister、retire-source、零原件复制和最小 SQLite 边界。
  • materials.py 实现字段验证、媒体判断、路径/大小/SHA-256 现场核对、门牌、关系与文字验证、事务写入和两种撤销入口(共 4,126 行)。
  • schema.sql 定义严格来源、材料、关系、绑定文字、文件名清单、唯一约束、外键级联与数据库应用身份。
  • tests/test_materials.py 覆盖额外字段、哈希漂移、外部数据库拒绝、失败初始化清理、媒体 handoff、零复制状态、门牌和撤登记(74 个测试函数、123 个用例定义,10 月 22 日静态计数,本次没有运行)。
如何验证
  • 以虚构临时文件生成精确 handoff,证明成功回执只含来源/材料/关系/文字数量和 original_bytes_copied=0。
  • 分别修改预期大小、SHA-256、额外字段、文字覆盖和关系端点,确认事务没有部分写入。
  • 验证 filesystem-directory 相对根和材料相对 locator 都在读取或写入前拒绝。

数字截至 2026 年 11 月 6 日

依据与来源(二)
  • 用缺核心表、缺关键列、伪造 application id/version 和 integrity_check 失败的数据库验证 init 不覆盖现有字节;首次建库失败只移除自己新建的空占位。
  • 在首次 stat/hash(内容指纹)后和提交前分别改变文件,确认稳定句柄检测变化并回滚全部写入。
  • 分别尝试 material_key 与 source/native 双向重绑,确认既有记录字节不变。
  • 让同一 material_key 的内容哈希变化,确认旧 material_text 全清且只保留本次新文字。
  • 验证 unregister 默认只预演、--apply 只删一条及其级联文字和关系;retire-source 在根还在或还有材料时拒绝。
  • 验证 status 只返回核心表计数、background_process=false 与 original_bytes_copied=0,并确认它不会读取正文或声称覆盖完整。
  • 验证所有媒体类型在读取字节或计算哈希前拒绝,ASR/transcript 文字种类也不能进入材料索引。
  • 真实接入验收必须由一个现役消费者提供精确对象,并在接入后通过普通描述找到、选中、重新验真和打开原件;本次没有执行接入、撤登记或撤来源,也没有做这样的验收。
与其他模块的关系

它是登记查找的数据入口,也管登记的撤回和每日的删除跟随,但不是用户日常查找入口。精确接入提供小而可信的来源与版本事实;登记查找消费这些事实,有界发现只在尚未接入的位置补一个选中对象。

依据与来源(二)
  • 用缺核心表、缺关键列、伪造 application id/version 和 integrity_check 失败的数据库验证 init 不覆盖现有字节;首次建库失败只移除自己新建的空占位。
  • 在首次 stat/hash(内容指纹)后和提交前分别改变文件,确认稳定句柄检测变化并回滚全部写入。
  • 分别尝试 material_key 与 source/native 双向重绑,确认既有记录字节不变。
  • 让同一 material_key 的内容哈希变化,确认旧 material_text 全清且只保留本次新文字。
  • 验证 unregister 默认只预演、--apply 只删一条及其级联文字和关系;retire-source 在根还在或还有材料时拒绝。
  • 验证 status 只返回核心表计数、background_process=false 与 original_bytes_copied=0,并确认它不会读取正文或声称覆盖完整。
  • 验证所有媒体类型在读取字节或计算哈希前拒绝,ASR/transcript 文字种类也不能进入材料索引。
  • 真实接入验收必须由一个现役消费者提供精确对象,并在接入后通过普通描述找到、选中、重新验真和打开原件;本次没有执行接入、撤登记或撤来源,也没有做这样的验收。
与其他模块的关系

它是登记查找的数据入口,也管登记的撤回和每日的删除跟随,但不是用户日常查找入口。精确接入提供小而可信的来源与版本事实;登记查找消费这些事实,有界发现只在尚未接入的位置补一个选中对象。

复制 AI 续作说明

项目:新材料只通过精确交接登记,原件字节始终留在原处;仓库:页面未提供仓库地址;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。

把“目标”换成这次要做的事,整段复制给 AI。