cognitive-integrate-fragments

name	cognitive-integrate-fragments
description	将待整合的L2碎片通过小人机制整合进L1系统性文档，保持知识体系自洽。触发词：「整合碎片」「哪些碎片没整合」「更新文档」「把碎片整合进去」「处理积压」「消化碎片」。

碎片整合 Skill（Integrate Fragments）

实现「小人整合机制」：读取待整合碎片 → 判断同化/顺应 → 生成具体更新建议 → 用户确认 → 执行写入 → 级联更新。

---

知识导航表（执行前必须理解的概念根）

层级	文档	需要理解的概念
D0 认知根（必读）	cognitive/L1_knowledge/formal_spec/self_evolving_agent_spec.md	层5：ceremony(K) = 备份+修改+版本+级联；层3：C2关系显式化（修改K1后必须通知依赖它的B-objects）
D3 规范参考	cognitive/maintenance_protocol.md	K1文档修改规范：版本管理/历史备份/矛盾检测要求
D4 运行时数据	cognitive/L2_fragments/fragment_index.md + 目标L1文档	待整合碎片清单 + 目标文档当前内容（整合前必须理解已有结构）

核心概念速查： ① 小人机制 = 以「已在L1文档里居住的知识」视角判断碎片如何融入，不破坏已有结构 ② 整合 = K-object升级：fragment→被L1吸收，碎片整合索引更新为🔲→✅ ③ 整合后必须更新L0总地图——C2级联：K1变化需通知依赖该知识的所有对象

---

激活后立即执行

Step 1  读取待整合碎片列表
        Read: cognitive/L2_fragments/fragment_index.md
        → 筛选出所有「🔲 待整合」和「⚠️ 部分整合」的条目
        → 如果没有待整合碎片：「当前没有待整合的碎片。知识体系已是最新状态。」→ 结束
        → 展示待整合列表给用户，询问：「是处理全部（N个），还是指定某个？」

Step 0.5  判断是否启用独立整合器（CS-012 修复，在 Step 1 之后执行）
        统计本次用户选中的待整合碎片数量 N：
        
        IF N ≥ 5：
          调用 cognitive-fragment-integrator 子智能体：
          输入：{
            target_l1_doc_path: [目标 L1 文档路径],
            fragment_ids: [选中的碎片 ID 列表],
            fragment_paths: [对应的碎片文件路径列表]
          }
          等待 integration_plan 输出
          向用户展示整合方案：
          「━━ 批量整合方案（共 N 条碎片）━━
            [每条碎片：fragment_id / section_name / position_type / confidence]
            ⚠️ confidence="低" 的碎片已标注，建议优先审查
            ─────────────────────
            [逐条确认（推荐）] [全部确认] [逐条审查]」
          用户确认后，按 integration_plan 执行写入：
            a. 按方案执行 StrReplace（section_name + anchor_keyword 定位）
            b. 追加变更记录（每个文档一条）
            c. 更新碎片整合索引（所有已整合碎片状态改为 ✅）
            d. 更新 L0 大脑总地图
            e. 追加 L3 系统日志
          对 unresolved_fragments（有矛盾，无法自动处理）：
            告知用户：「以下碎片存在矛盾，需手动决策：[碎片ID + 矛盾描述]」
          → 写入完成后跳到 Step 7（调用 cognitive-verifier）
        
        IF N < 5：
          继续原有流程（Step 2 → Step 7）

Step 2  对每个待整合碎片，用内置 explore 子智能体并行读取：
        - 碎片完整内容
        - 碎片关联的L1文档相关章节（只读相关章节，不是整篇）
        
        【为什么用 explore 子智能体】
        碎片内容 + L1 文档相关章节可并行读取，比串行快；
        且碎片内容留在子智能体 context 中，不膨胀主对话。
        主 Agent 只接收「关键摘要 + 关联段落」用于分析。

        [L1.5 模式匹配]
        → 碎片是否是已有L1.5原则（P1/P2）的一个新实例？
        → 是 → 记录「印证了P?」，不额外整合进L1（已有原则的例证不需要单独进L1）
        → 否 → 继续判断

        [同化/顺应判断]
        → 比较碎片与L1文档相关段落：
        → 同化（supplement）：碎片是对现有内容的补充/延伸，无冲突
          → 生成补充建议：在[文档]的[章节]追加「...」
        → 顺应（revise）：碎片与现有内容有张力或矛盾
          → 先运行矛盾检测（见 Step 3），再生成修订建议
        → 已覆盖（covered）：现有文档已包含该观点
          → 标记碎片为「已覆盖」，告知用户，无需整合

Step 3  [矛盾检测]（仅当发现顺应情况时执行）
        → 描述矛盾点：「碎片说X，但文档[Y]第Z章说了W，两者有[直接冲突/隐式张力]」
        → 基于L1.5原则推导消解方案：
          选项A：修改文档[Y]的[位置]
          选项B：两者都对，在文档中明确区分适用场景（添加前提条件）
          选项C：碎片观点需要修正（告知用户）
        → 向用户展示，请用户决策

Step 4  生成整合建议，逐个向用户展示确认（diff 格式）
        「━━ 碎片 F-XXX 整合建议 ━━
          目标文档：[文档名] > [章节]
          操作类型：[追加 | 修订 | 已覆盖]
          ┌ 建议内容 ┐
          [具体的新增/修改文字]
          └──────────┘
          归因：🟢 AI整理（基于用户原始碎片）
          风险：[🟢 低 | 🟡 中 | 🔴 高]
          ─────────────────────────
          [✅ 确认整合] [✏️ 修改后整合] [❌ 跳过] [⏸️ 延迟]」

Step 5  执行用户确认的整合
        对每个「确认」或「修改后确认」的建议：
        a. Write：精确修改L1文档对应位置（追加/替换/插入）
        b. 追加 [文档名]_变更记录.md（格式见下方）
        c. 更新碎片整合索引.md（✅已整合 + 整合时间）
        d. 更新 L0_大脑总地图.md（该文档最后更新时间）
        e. 追加 cognitive/L3_logs/system_log.md

        对「跳过」的：更新索引为「⚠️ 部分整合（用户跳过）」
        对「延迟」的：保持 🔲 待整合 状态

Step 6  收尾汇总 + 矛盾检测（E1A 修复：顺应型整合强制触发）
        「━━ 整合完成 ━━
          ✅ 已整合：N 个碎片
          ⚠️ 跳过：M 个
          🔲 仍待处理：K 个
          涉及文档：[文档名1]、[文档名2]」
          
        [强制条件] 本次整合中是否包含任何「顺应（revise）」类型的操作？
        → 是（本次有顺应操作）：
          【强制执行】自动触发 cognitive-detect-contradiction
          → 检查范围：本次 revise 操作涉及的 L1 文档（限定范围，不做全库扫描）
          → 矛盾检测结果汇总到本步骤的输出中，用户无需再次手动确认触发
        → 否（本次全为同化/已覆盖）：
          告知：「本次整合均为追加操作，无矛盾风险，可跳过矛盾检测。」
          （可选：「[仍然检查] [完成]」）

Step 7  调用 cognitive-verifier 子智能体（CS-010 修复）
        
        ⚠️ B4 任务日志写入在本步骤之后执行。
        
        输入：{
          target_doc_path: [本次整合涉及的主要 L1 文档路径],
          update_summary:  "碎片整合：共整合 N 个碎片，涉及 [章节] 的 [操作类型]",
          related_docs:    [本次整合中修改过的其他 L1 文档路径列表],
          call_context:    "integration"
        }
        
        处理验证报告（同 cognitive-update-knowledge Step 8 的处理逻辑）：
        → verdict = "通过"：告知用户验证通过，B4 写入（状态：完成）
        → verdict = "警告"：展示警告，询问用户是否接受，接受则 B4 写入（完成）
        → verdict = "不通过"：展示问题 + 建议，B4 写入（状态：挂起），任务挂起

---

变更记录追加格式

追加到 [文档名]_变更记录.md（若不存在则新建）：

## [YYYY-MM-DD] [supplement | revise | resolve_contradiction]

**触发来源**：碎片 F-XXX「碎片标题」
**变更位置**：第X章第Y节
**变更内容**：[追加/修改了什么，一句话]
**归因**：🟢 AI整理，用户审核确认
**Commit**：[简短描述]
**联动影响**：[无 | 需检查文档Z]

---

注意事项

• 每次只处理一个碎片的确认，不要批量修改文档后才问用户
• 顺应类变更必须先告知矛盾点，不能直接提修改建议
• 已覆盖的碎片不要重复写入，只需更新索引状态
• 变更记录必须追加，这是级联一致性的强制要求（Rule cognitive-structure-write-guard 会检查）

---

变更记录

2026-03-19 — v1.0 → v1.1 — Step 2 改用 explore 子智能体并行读取

根因：每个碎片整合时需要读碎片内容 + L1 文档相关章节，当前串行读取速度慢且碎片内容会膨胀主对话 context，导致多碎片批量整合时 context 过重。

修改内容：

• 修改：Step 2 读取方式 → 从「两次串行 Read」改为「用 explore 子智能体并行读取两个来源，主 Agent 只接收关键摘要」

验证结果：

• 正向验证：整合多个碎片时，主对话 context 不包含碎片原文和 L1 文档全文（待真实场景验证）
• 负向验证：Step 3-6 的同化/顺应判断、矛盾检测、写入逻辑均不变

验证状态：🔵 待验证

---

v1.4 — 2026-03-21 — 新增 Step 0.5（碎片≥5条时调用 cognitive-fragment-integrator）

根因：CS-012 沙盘确认大批碎片（≥5条）整合时，主 context 包含碎片捕捉历史，影响「小人机制」的纯粹性。

修改内容：

• 新增：Step 0.5「判断是否启用独立整合器」——碎片 ≥5 条时调用 cognitive-fragment-integrator，获取 integration_plan，用户确认后按方案执行写入；碎片 <5 条继续原有流程
• 说明：Step 统计对象为「本次用户选中的碎片数」，非系统总积压数

验证结果：

• 正向验证：8条碎片 → 触发 cognitive-fragment-integrator → 输出含 section_name+anchor_keyword 的精确方案
• 负向验证：3条碎片 → 正常执行 Step 2-7，不触发 fragment-integrator

验证状态：🔵 待验证

---

v1.3 — 2026-03-21 — 新增 Step 7（cognitive-verifier 调用）

根因：CS-010 沙盘确认 cognitive-integrate-fragments 在碎片整合写入 L1 后无独立自洽验证，与 cognitive-update-knowledge 面临同样的创作者视角偏差问题。

修改内容：

• 新增：Step 7「调用 cognitive-verifier 子智能体」——整合完成后独立验证 L1 文档自洽性
• B4 触发时机后移至 Step 7 verdict 决策后
• 备份路径：history/SKILL_v1.2_20260321.md

验证结果：

• 正向验证：碎片整合完成后，Step 7 被调用，输出 CV-1/CV-2/CV-3 三项检查（待验证）
• 负向验证：Step 1-6 的整合逻辑不变

验证状态：🔵 待验证

---

v1.2 — 2026-03-21 — Step 6 顺应型整合自动触发矛盾检测（E1A 强制级联修复）

根因：GAP-E1 分析（认知体系改进规划 v1.2）：顺应型整合修订 L1 已有内容，是最可能引入矛盾的操作，但矛盾检测只是「建议」，用户可跳过，与「知道有风险但不强制处理」相矛盾。

修改内容：

• 修改：Step 6 → 从「建议性提示」改为「强制条件判断」：含顺应操作时自动触发 cognitive-detect-contradiction（检查范围限定为本次 revise 涉及的 L1 文档，不做全库扫描）

验证结果：

• 正向验证：含顺应操作的整合执行后，Step 6 应自动触发矛盾检测（待真实场景验证）
• 负向验证：纯同化操作的整合，Step 6 不强制触发矛盾检测（建议但不阻断）

验证状态：🔵 待验证

备份路径：history/SKILL_v1.1.1_20260321.md

---

v1.1.1 — 2026-03-19 — Step 6 加入矛盾检测提示（CS-001 Gap 修复）

根因：CS-001 沙盘验证发现：整合完成后没有触发 cognitive-detect-contradiction 的机制，矛盾检测环节完全依赖用户主动触发，可能导致不一致内容悄无声息写入 L1。

修改内容：

• 修改：Step 6 收尾汇总 → 加入建议性提示，引导用户在涉及多个 L1 文档更新时运行矛盾检测

验证结果：

• 正向验证：整合多个碎片后，Step 6 输出包含「建议运行矛盾检测」的提示
• 负向验证：仅整合1个碎片到单一文档时，提示不干扰流程（建议性，非阻断）

验证状态：🔵 待验证