常见问题与排错
用起来最常撞的问题。按「它会不会动我的文件」→「为什么这样判」→「跑不起来怎么办」的顺序排。
01它会不会改我的文件
默认不会。 安装完什么都不改，它只读。要它动文件，必须显式敲 kbfold apply；要它移动文件，必须再加 --move 并二次确认。
它会删我的文件吗？ 不会。代码里没有 unlink 调用（可以 grep -r unlink 自查）。trash/ 里放的是副本，清理副本也不影响源文件。
我误操作了怎么退？ kbfold undo <batch>。批次号在 apply 结束时会打出来，也在 .kb/undo/ 和 journal.jsonl 里。
02为什么这样判
为什么 0.95？这个分数是概率吗？ 不是。它是「这一级判据的可信程度」，从 L0 的 0.95 逐级下降到 L5 的 0.40。残差（0.95 − 实际）才是你该看的数。
为什么明明很像两个库，它一个都不选？ 因为具体程度打平了。平手时选任意一个都等于抛硬币，而抛错的代价是你在几千个文件里找那一份。所以两个候选都列进 _inbox/。
_inbox/ 会自己清空吗？ 不会。它是一个待办队列，你处理掉一部分（改规则或手动安置）再跑 plan，它才会变短。它不自动清空，因为「自动清空」等于「自动猜」。
我把文件拖到另一个目录，它会重新判定吗？ 不会。它认 hash：同 hash 新路径 ⇒ 只改链接，不重解析。这正是省掉 90% 工作的那一态。
删掉一个文件会怎么样？ 索引里打 tombstone，不删记录。所以你可以撤回，也不会因为误删源文件就丢了「曾经有过这份」的事实。
03规则写得不对
规则写了没生效？ 三个常见原因，按顺序查：① match 的基准目录是 root，不是规则文件所在目录；② 黑名单里的通用目录名（data、config、docs …）在启动时就被拒了，看 stderr；③ 多条命中时被更具体的规则覆盖了，跑 kbfold explain <文件> 看它到底命中哪条。
为什么我不能把目标设成 data/？ 因为通用目录名不携带任何场景信息，把判定权交给它等于没判定。启动时直接报错，比事后发现问题好。
能不能一个 kbfold.yml 管多个盘？ 可以，root 写多个或用多次 --rules 都可以，但跨卷批次会退化为 copy + 删源，比较慢，且必须整批成功或整批停。
04跑不起来
| 现象 | 原因 | 怎么办 |
|---|---|---|
node: command not found | 没装 Node，或版本太低 | 装 Node 20+，推荐 22（22 才自带 node:sqlite） |
| 全文检索一直没结果 | node:sqlite 不可用，索引降级 | 升到 Node 22；或接受只走关键词那一路 |
✗ 规则错误：目标目录 "xxx" 属于通用名黑名单 | to: 写了通用目录名 | 换成场景名，如 01-原始资料/data |
| 语义检索没生效，但没报错 | Ollama 没起，这是设计好的静默降级 | ollama serve 后重跑；或不管它，关键词那路照常 |
apply 报「磁盘不足，拒绝执行」 | trash/ 放不下原件快照 | 清旧批次 trash/，或换到空间更大的卷 |
undo 报「hash 不符」 | 该文件在 apply 之后被别的程序改过 | 停下来人工比对，不要强撤 |
| 中文路径报错 | 老版本在 Windows 上的编码问题 | 升到 v0.1.0 以上 |
| DSH 里没有那五个工具 | 插件没 enable，或注册失败（只写 stderr） | dsh plugin list 看状态；看 DSH stderr 日志 |
05关于开源本身
为什么许可证是 Apache-2.0？ 因为它有显式专利授权、允许商用、企业法务不用开会讨论。我们不想让「能不能用」变成一道审批题。
为什么行业模板不开源？ 代码全开，通用模板（L0 基线 + 文件类型 12 类）全开；六个行业的目录体系是我们自己项目里长出来的东西，属于场景积累而不是通用能力。格式完全一样，你照着自己的行业写一份就行。
能商用吗？ 能，Apache-2.0 允许。唯一的要求是保留版权声明与许可文本。
我的资料会被上传吗？ 不会。除本地 Ollama 端口外零外连。kbfold audit 会列出本次运行碰到的所有外部端点，正常情况下列表是空的或只有 127.0.0.1:11434。这一条是可自证的，不需要你信文档。匿名改进反馈默认关闭（L0 零网络调用）；即使你手动打开，也只上行本机脱敏后的统计与结构信息，永不上行文件名、目录原名与文件内容——三档口径逐条见仓库 docs/FEEDBACK.md。