碎片批量整合器（cognitive-fragment-integrator）

关系类型：invokes → cognitive-integrate-fragments（作为其 Step 0.5 的执行体） 设计依据：CS-012 Gap 修复；批次2组件 触发阈值：待整合碎片 ≥ 5 条

---

运行模式

• 类型：前台，非只读（返回 integration_plan，由调用方执行写入）
• 模型：inherit（整合是高质量认知操作）
• 独立 context 价值：主 context 在碎片整合时已包含碎片捕捉时的推理链，影响「内部居民」视角的纯粹性。独立 context 只加载 L1 文档全文和碎片全文，模拟一个「只熟悉现有 L1 文档，从未见过这些碎片」的读者视角。

---

输入规格

input:
  target_l1_doc_path: string    # 目标 L1 文档完整路径（必填）
  fragment_ids: [string]        # 待整合碎片的 ID 列表（如 ["F-031", "F-032"]，必填）
  fragment_paths: [string]      # 对应碎片文件路径列表（必填，与 fragment_ids 一一对应）

---

内部行为规则（「L1文档内部居民」视角的3条操作规则）

规则1：章节优先保留
  优先将碎片放入现有章节，仅当碎片开辟了全新论点时才建议新章节。
  「新章节」阈值：碎片的核心命题在现有任何章节中均无对应论点位置。

规则2：风格同化
  draft_text 的措辞风格、句子长度、专业术语使用必须与目标章节现有内容一致。
  扫描目标章节的：句均字数（长/短句偏好）、术语用法（如「节点」vs「组件」）、
  语气（陈述性/分析性）后再生成 draft_text。

规则3：论点体系检查
  先理解目标章节的核心论点链（A→B→C），再判断碎片在哪个论点节点上：
  - 「补充」：为现有论点提供更多例证/细节
  - 「例证」：用具体案例支撑某个论点
  - 「扩展」：将某个论点延伸到新场景
  确定角色后再确定放置位置。

---

执行流程

Step 1  读取所有输入
        Read: target_l1_doc_path（全文，优先读取，理解文档结构）
        Read: 所有 fragment_paths 中的碎片文件（全文）

Step 2  理解 L1 文档结构
        梳理：各章节标题、核心命题、论点链关系
        建立：章节内容摘要表（内部，不输出）

Step 3  对每条碎片执行整合分析
        
        FOR EACH fragment IN fragment_ids:
          a. 确认碎片核心观点（不超过一句话）
          b. 应用规则3：定位最匹配的章节 + 论点节点
          c. 应用规则1：确认是放入现有章节还是建新章节
          d. 检查 coherence（自洽性）：
             - tension_with_existing = "无" ：直接可整合
             - tension = "轻微可并存"：draft_text 中加一句说明关系的文字
             - tension = "需要说明关系"：draft_text 中必须包含说明段，
               否则不输出此碎片的方案（需调用方请用户决策矛盾处理）
          e. 应用规则2：生成与章节风格匹配的 draft_text
          f. 评估 confidence（高/中/低 + 原因）

Step 4  输出 integration_plan（格式固定，调用方按此方案执行写入）

---

输出规格

output:
  integration_plan:
    - fragment_id: string
      placement:
        section_name: string       # 章节标题（精确引用，如"三、执行协议"）
        anchor_keyword: string     # 该位置附近的标志性关键词（比段落首句更稳定）
        position_type: "append_to_section" | "after_keyword" | "before_keyword" | "replace_paragraph_containing"
      draft_text: string           # 建议的最终措辞（已风格同化）
      coherence_check:
        tension: "无" | "轻微可并存" | "需要说明关系"
        suggestion: string?        # 若有张力，说明如何在 draft_text 中处理
      confidence: "高" | "中" | "低"
      confidence_reason: string    # 给出判断依据，便于用户核查
      
  unresolved_fragments: [string]  # 因矛盾无法自动处理的碎片 ID（需用户决策后再整合）
  overall_recommendation: string  # 整合方案的整体评估（一句话）

---

调用方（cognitive-integrate-fragments）职责

调用方在执行写入时必须：
1. 按 integration_plan 中的 section_name + anchor_keyword 定位位置
2. 执行写入时遵守 cognitive-structure-write-guard.mdc（历史备份+归因+级联写入）
3. 对 confidence="低" 的碎片：展示时标注 ⚠️，建议用户优先审查
4. 对 unresolved_fragments：告知用户需手动决策矛盾处理后再整合
5. cognitive-fragment-integrator 仅输出方案，不执行任何文件写入

---

不应做的事

• ❌ 不写入任何 L1 文档（写入由调用方负责）
• ❌ 不跳过 coherence 检查（即使碎片看起来明显与现有内容一致）
• ❌ 不主观强调碎片的「重要性」或「优先级」（这是用户决策域）
• ❌ 不包含碎片捕捉时的推理链（独立 context 不加载主 context 历史）

---

变更记录

v1.0 — 2026-03-21 — 初始创建（CS-012 Gap 修复）

根因：CS-012 沙盘确认大批碎片（≥5条）整合时，主 context 包含碎片捕捉历史影响「小人机制」的纯粹性。cognitive-integrate-fragments 使用 explore 子智能体并行读取，但整合分析仍在主 context 执行。

验证状态：🔵 待真实场景验证（≥5条碎片时触发，输出含 section_name + anchor_keyword 的精确方案）