intelligent-import

name	intelligent-import
description	对已入库文档的节点树做目录层级重整——叠章节虚拟容器、调父子边、调兄弟顺序、给虚拟容器补章节名。导入对话框"智能导入"在入库后自动触发，或用户在 LLM 协作模式发起"重整目录"时使用。只动结构不动任何节点正文，产物写入 owner=llm 影子分支待审。

智能导入 / 重整目录 skill

用途

专职整理文档的目录层级结构。在简单导入或完整导入入库后，对已有节点树做结构调整——新建虚拟容器节点叠章节层、调父子边、调兄弟顺序、给虚拟容器补章节名。

本 skill 不重做简单导入已识别的结构——能用正则/AST/格式规范做的事不调用 LLM API（成本约束）。

触发

• 导入流程入口：用户在导入对话框选"智能导入"，简单导入入库后自动触发本 skill；导入流程结束时弹强制审批对话框（接受全部/拒绝全部）。
• 重整目录入口：已导入文档上，用户在 LLM 协作模式对话区发起"用 LLM 重整目录"指令；产物按 15-7 路径进 LLM 对话区待审卡片，按 15-8/15-9 逐条或整批审。

输入

调用方上下文提供：

• 当前文档 docId 和 treeIndex（每个节点的地址、深度、子节点数、字数）
• 当前权限模式（必须为 agent.mode.edit 协作模式或更高）
• 触发场景（import-flow 或 restructure），用于决定审批 UI 走哪条路

输入产物来自完整导入（4-2）——智能导入入库阶段复用完整导入解析，不走简单导入失败拒绝。所以 treeIndex 反映的形态有三种：

1. 结构识别成功：节点 1 下有章节层、章节下有段落容器（虚拟节点）、段落下有句子节点
2. 结构识别失败：节点 1 下平铺段落容器（虚拟节点）、段落下有句子节点；无章节层
3. 极端兜底：节点 1 单节点（全文塞节点 1 正文），无子节点

skill 按需通过 db read <docId> <地址> 拉取节点正文；不拿原始源文件，因为节点已经反映了规则解析的产物。

输出

调用 database_mutation 产生 entry kinds 序列，写入 owner=llm 影子分支。允许的 entry kinds：

kind	用途
node.insert	新建虚拟容器节点
node.update	给虚拟容器节点写 node_title 字段
node.reparent	调节点父子边
node.moveBefore / node.moveAfter	调兄弟顺序
node.delete	删除已没有子节点的空虚拟容器

其余 entry kinds（node.split、node.mergeInto、axiom.*、ref.* 等）本 skill 不调用。

虚拟容器节点形态（强约束）

新建节点必须严格按 9-1-1 虚拟节点形态：

• text 为空
• node_type 用 TEXT，role 标记为容器类型（如 paragraph）
• source_position 取该容器所有子节点最早 source_position 减 0.5（半步偏移避免位置冲突）
• skipVector 为 true
• node_title 可写（章节名）；node_note 留空

未按此形态创建的节点会破坏 9-1 渲染规则，被判定为违规。

职责范围（"该/不该"，非系统级"能/不能"）

skill 做

• 新建虚拟容器节点做分组归类
• 给虚拟容器节点的 node_title 写章节名
• 调父子边把散落的同类节点归到一起
• 调兄弟顺序把章节按合理顺序排
• 删除已空的虚拟容器（其子节点全部被移走后）

skill 不涉及

• 正文编辑：text 字段修改归 LLM 系统级编辑能力（别的 skill 或人类编辑模式负责）。本 skill 不动任何节点正文。
• 节点摘要：给真实内容节点（有正文的）写 node_title 当摘要属于节点摘要 skill 范围。本 skill 只给虚拟容器写章节名。
• 段落切分/合并：段落容器和句子节点的粒度由 4-2 完整导入锁定（智能导入入库走完整导入解析）。本 skill 不动段落正文边界。
• 删带正文的真实内容节点：本 skill 只删自己创建的空虚拟容器。
• 事实前提：axiom.* 全部归 9-8 单独编辑路径。

工作流

1. 读 treeIndex 看当前结构，按上面三种输入产物形态分类。
2. 判断是否需要调整——保守原则，不为了"做点什么"而强行调整：
   • 结构识别成功 + 章节顺序合理 + 层级合理 → 返回空 entries
   • 结构识别成功 + 章节顺序乱（按 source_position 序号看不连续）或层级误划 → 重排或调层
   • 结构识别失败（节点 1 下平铺段落容器）→ 按段落正文聚类，新建章节虚拟容器作为段落容器的父节点
   • 极端兜底（节点 1 单节点）→ 返回空 entries 并在对话区说明"短文档/单句备忘无需结构化"
3. 必要时按 db read 拉节点正文 判断聚类——不要一次性拉所有正文，按 treeIndex 字数评估，只读相关节点。
4. 决定调整方案，生成 entry 序列。每个 entry 必须可在影子分支投影中合法应用（参考 edit-branch-projection.mjs）。
5. 保持节点集合恒等——真实内容节点不增不减，只调关系；只增删虚拟容器。

边界

• 段落级粒度恒等：完整导入产出多少真实内容节点（段落容器 + 句子节点），本 skill 跑完还是多少。
• 节点正文不变：跑完后所有真实内容节点和虚拟段落容器的 text 字段不变。
• 入库阶段不归本 skill：本 skill 跑在已入库的文档树上，不接触源文件、不接触 4-1 / 4-2 的格式解析器。skill 只新增章节级虚拟容器、不动段落容器本身。

失败 / 空动作

以下情形 skill 返回空 entries 序列：

• 文档已经结构良好，无需调整
• 文档只有节点 1（直接导入兜底产物）且全文 ≤ 1000 字，可能本就无结构需要叠
• 节点正文之间无可识别的聚类信号

返回空 entries 时，导入流程入口的"接受全部 / 拒绝全部"按钮仍然弹出，但都是 no-op；重整目录入口下不产生待审卡片。

例 A：结构识别成功 + 部分平铺（增量补）

某 md 文档完整导入识别出 20 个 heading + 80 段段落，但 heading 都集中在文档前半部分（深度 1-2），后半部分是 50 段挂在节点 1 直下的平铺段落容器。

LLM 读 treeIndex 看到节点 1 下有 20 个章节节点 + 50 个平铺段落容器；按 db read 抽取若干平铺段落正文判断主题，发现这 50 段实际属于 5 个聚类。

LLM 生成 entries：

• 5 个 node.insert：新建章节虚拟容器 1-21 / 1-22 / 1-23 / 1-24 / 1-25
• 5 个 node.update：给每个章节虚拟容器的 node_title 写聚类主题名
• 50 个 node.reparent：把 50 段平铺段落容器按聚类分别 reparent 到对应章节虚拟容器下

入库流程入口下：用户看 diff 视图（8-3-2-3）确认聚类合理 → 点"接受全部"（按 15-8-1 提示进入编辑模式后合入）。

例 B：结构识别失败 + 平铺段落（叠章节层）

某 md 文档完全没有 # heading（用户用纯文本段落写作）。完整导入退化为节点 1 下平铺 N 个段落容器（虚拟节点）、每段下挂句子节点；无章节层。

LLM 读 treeIndex 看到节点 1 直接子全是段落容器；按 db read 抽样段落正文判断主题聚类，把 N 段聚成 K 个章节。

LLM 生成 entries：

• K 个 node.insert：新建章节虚拟容器，按 9-1-1 形态（text 空、role 容器、source_position 取该章节所有段落容器最早位置减 0.5、node_title 写章节名）
• N 个 node.reparent：把 N 个段落容器按聚类 reparent 到对应章节虚拟容器下

这是 LLM 的核心价值场景——规则识别不到结构，LLM 在段落上叠章节层。用户审 diff 看左侧"节点 1 + N 段平铺"、右侧"节点 1 + K 章 + 每章下若干段"。

例 C：结构识别成功且良好 / 极端兜底（空 entries）

文档结构识别成功且章节/段落分布合理 → LLM 返回空 entries（不为做事而做事）。 文档极小到完整导入退化为节点 1 单节点（如单句备忘）→ LLM 返回空 entries 并在对话区说明"短文档/单句备忘无需结构化"。

导入流程入口下：审批对话框仍然弹出但显示"无变更"，用户接受/拒绝都不影响主文档。