smart-import

name	smart-import
description	把任意源文件整理成条件树文档并入库。适用于内置 agent、外部 LLM 或任何能跑脚本的工具执行导入任务：观察源文样本、写一次性切割脚本产出与 db push 同契约的 JSON，经 db import-json 校验入库。正文必须是源文的逐字节切片——LLM 只贡献结构，不贡献正文。

智能导入 skill（projectneed 4-3）

把任意源文件整理成条件树文档并入库。本文写给执行导入的 LLM——内置 agent、外部模型、 或任何能跑脚本的工具都行：产物是与流式写入（db push）同一契约的 JSON， 经 db import-json 校验入库，不挑框架（4-3-4 去中心化）。

原则

1. LLM 只贡献结构，不贡献正文。 正文 text 必须是导入源的逐字节切片， 由你写的脚本机械切割产生——你不得复述、改写、润色、纠错任何正文字符。 校验器会逐字节比对，改一个字就过不了。
2. 观察样本、写脚本，不要逐段标注。 读源文的开头/中间/结尾各一段， 识别这个文件特有的结构模式（标题行特征、编号体系、段落分隔）， 然后写一个一次性脚本扫全文产出 JSON。规则零成本，token 按量计费。
3. 你造的文字走专用字段。 原文没有标题而你需要分组时，建虚拟容器： text 留空，章节名写进 nodeTitle，绝不把自己写的字混进 text。
4. 切到段落级，句子交给系统。 你只切到「章节 → 段落」两层：章节标题作 text 节点、 其下每个自然段作一个子 text 节点。不要自己切句子——产物 JSON 顶层加 "splitSentences": true， 入库后系统会用句末标点正则把每个段落自动细切成句子子节点（能用规则做的不劳你）。 也不要只切到章节那么粗：段落归属是规则识别不到、需要你判断的语义结构。

JSON 契约（与 db push 完全一致）

{
  "title": "文档标题",
  "splitSentences": true,
  "nodes": [
    {
      "text": "第一章 总则",
      "trustLevel": "不受控",
      "children": [
        { "text": "本章第一段的正文……。", "trustLevel": "不受控" },
        { "text": "本章第二段的正文……。", "trustLevel": "不受控" }
      ]
    },
    {
      "text": "第二章 罚则",
      "trustLevel": "不受控",
      "children": [
        { "text": "本章正文……。", "trustLevel": "不受控" }
      ]
    }
  ]
}

字段规则：

• address：可选，不用写——系统按 children 嵌套前序自动生成（顶层 1-1、1-2…， 子节点为父地址 + 序号）。层级只用 children 嵌套表达即可，连续地址这种机械的事不用你算。
• text：源文的逐字节连续切片。切片允许去掉首尾空白，不得改动内部任何字符 （包括空格、标点、换行——跨行句子保留原换行符）。
• trustLevel：智能导入产物一律 "不受控"（4-3-2-1）。
• nodeTitle：你构造的标题（虚拟容器的章节名）。真实标题行不用它—— 原文里存在的标题行本身就是一个 text 节点。
• 虚拟容器（text 为空的节点）：必须给数值 sourcePosition， 取它后面第一个带正文的节点的句位序号减 0.5（句位序号 = 该节点在全部 text 非空节点的前序遍历中的序号，从 1 起）。相邻多个虚拟容器依次再减 （3.5、3.25 不必——用 3.5、3.4 等不冲突的小数即可，只为排序不碰撞）。
• 带正文节点的 sourcePosition 可以省略：校验器锚定后自动回填句位。
• nodeType 缺省 TEXT，导入阶段不做条件类型标注。

顺序铁律：树的前序遍历顺序必须与正文在源文中的出现顺序一致。 校验器按前序逐个在源文中向后匹配——你想重排章节顺序，那不是导入，别在这里做。

工作流

1. 观察：读源文样本片段，写下这个文件的结构模式 （例：标题是独立行的「数字+顿号」；段落以空行分隔；含页眉「第 N 页」）。
2. 写脚本：在 LLM 工作区（.iftree-llm-workspace）写一个一次性 node 脚本， 读源文 → 按你识别的模式切割 → 输出 tree.json。脚本要点： 按行/按模式定位结构边界，切到段落即可（句子层入库后由系统补）；正文一律 slice 原文，不要重新拼写。
3. 校验：

   db import-json <工作区>/tree.json <源文件路径> --dry-run
   

   读返回的 JSON 报告，按 missing / out_of_order / uncovered 三类错误修脚本重跑，直到 ok: true：
   • missing——正文在源文中不存在：九成是脚本改动了内部空白/换行， 或源文有不可见字符；对照 textPreview 定位。
   • out_of_order——正文存在但位置在已消费区间之前：JSON 顺序与源文不一致， 检查脚本的遍历顺序。
   • uncovered——源文有带字的区间没被任何节点覆盖：脚本漏切了这段，对照 textPreview 把它切进对应节点（系统不替你补、也不放行）。 地址、句子层由系统处理、你不用管：地址按 children 前序自动生成；段落正文由系统按句末标点切成 句子（段落本身变成空容器、句子作它的子）。但覆盖是你的事：纯空白（段落间空行、分页符）不用管、 靠段落空容器的位置表达边界；任何带字的区间（含装饰线 ⸻、漏掉的正文段）都得切进某个节点，否则报 uncovered。
4. 导入：去掉 --dry-run 正式入库（需要向量时加 --embed）。 命令自动完成：建文档（增量编辑模式）→ 批量建树 → 绑定源文档层与句位对照 （导入后的文档支持选区高亮与句位回溯）。
5. 留档：脚本与 tree.json 留在工作区，默认保留 30 天—— 它们是这次导入的证据链，可追溯、可重跑、可修正后重导。

源文不可直接切割时：修整副本

源文有乱序文本层、OCR 噪声、XML 残渣，或只差几个语法标记就能用—— 先在工作区生成修整副本（如 cleaned.md）：修复的是载体（顺序、编码、噪声行）， 正文内容仍不改写。之后整个流程对修整副本做：

db import-json <工作区>/tree.json <工作区>/cleaned.md

修整副本就是这个文档的导入源（源文档层存它，原始文件路径自行记入备注或会话说明）。 CHM 这类多文件源也走这条路：先把反编译出的页面按目录顺序拼成单一文本文件再切。

自检清单（产 JSON 前过一遍）

• 每个 text 都是源文 slice 出来的，没有任何手打正文
• 前序顺序 = 源文顺序
• 不用写 address（系统按 children 前序生成）；层级用 children 嵌套表达
• 虚拟容器：text 空、nodeTitle 有名、sourcePosition 半步
• 所有节点 trustLevel: "不受控"
• 粒度到段落级（句子层由系统的 splitSentences 开关补）
• --dry-run 报告 ok: true（含覆盖：带字的区间都已切进节点，无 uncovered）