判定流水线

01五步流水线

②③④ 之间零 IO。这是刻意的：内核对同一份输入必须给出同一个答案，所以它不能读时钟、不能读网络、不能读环境变量。

02判分的四类信号

权重不是概率，是「谁更该被信」的顺序。四类信号不会相加，而是按下面的梯子逐级下降。

03L0–L6 七级判定梯

从最高开始逐级下降，命中即停，不再往下看：

残差 ＝ 0.95 − 实际置信，会写进报告。残差大的文件就是「最该人工看一眼」的那批，比按置信排序更有用。

04三态分流

第三条是这套工具的性格：宁可空着，不替你猜。

05增量：第二次跑只碰动过的文件

六步：扫描 → 指纹 → 比对 manifest → 只对变化集判定 → 只动差异的投影与索引 → 原子提交 manifest。

指纹先比 size + mtime，只有这俩变了才去算 SHA-256——这是为了在十万文件的目录上把 IO 压下来。

变化被分成四态：

「移动」是这里最值钱的一态。用户拖一次目录，普通工具会当成「删了 200 个文件又新增 200 个文件」，KBFold 只更新 200 条链接。

另有两个防抖机制：

• settled 终态集：已经人工定案的文件记 settled: true，后续批次不再重复判定。
• 组合键幂等：batch = hash(规则版本 + 变化集)，同一规则、同一批变化重跑，不会产生第二批动作。

06manifest.json 长什么样

{
  "version": 1,
  "rules_locked": "sha256:8f3c…",
  "files": {
    "星海项目/合同/2024-采购合同-v2.pdf": {
      "size": 412903,
      "mtime": 1730188800,
      "hash": "sha256:1a2b…",
      "kb": "XH-2024",
      "target": "02-合同",
      "confidence": 0.95,
      "reason": "L0:显式标记 .xhproject",
      "settled": false
    }
  }
}

大目录上这个文件会很大，所以是分片存储的（按顶层目录切片），十万文件也不至于每次整读。

reason 字段是人话，直接显示在报告与 kbfold explain 里。这个格式是完全公开的：第三方工具可以读写 .kb/，我们不会加私有字段。一个能被别人接管的台账，才可能变成事实标准。

07apply 的六步链路

④ 是整个设计的枢纽：先记账再动手，账写不下去就不动手。 所以不存在「改了但没记」的状态。

journal.jsonl 一行一条，追加不改写：

{"batch":"20261030-1412-a3f9","op":"rename","from":"合同/a.pdf","to":"02-合同/2024-星海-采购合同-v2.pdf","hash_before":"sha256:1a2b…","hash_after":"sha256:1a2b…","ts":1730189520}
{"batch":"20261030-1412-a3f9","op":"undo","from":"02-合同/2024-星海-采购合同-v2.pdf","to":"合同/a.pdf","hash_before":"sha256:1a2b…","hash_after":"sha256:1a2b…","ts":1730191200}

注意第二行：undo 本身也是一条 append 记录，不是把第一行删掉。所以任何时刻把 journal 从头读一遍，都能重放到「现在到底是什么状态」。

08原子性

• 同卷（同一个盘）：改名与移动走 MoveFileEx，本身是原子操作。
• 跨卷（C: → D:）：系统只提供 copy，所以只能 copy → 校验 hash → 删源，三步不可能原子。

因此跨卷批次一律按「整批成功或整批停」执行，绝不逐个文件试运气。

09归档：三档，全都不动

第三档最容易做错：很多整理工具会自动把老文件搬到「归档区」，然后你再也找不到它。KBFold 永远不自动搬，方向必须由人给。

10检索：三路融合

kbfold search 同时走三条路，只读名次不读分数，用 RRF（k=60）融合：

命中子块会回灌父块（子块 512 字符，父块上下文 1600 字符、上限 4000），这样返回的是能读的整段，而不是断句。

四条容量闸：单库 10 万块 / 单库矩阵 512MB / 全进程 1GB / 单查询 500ms，都在 80% 处预警。超闸不是崩溃，是把对应的那一路降级并在结果里注明。

所有结果都带 [n]，可回溯到文件与行号——这一点写进了 AI 工具的调用说明里，见「架构与设计」中的引用纪律五条。