fix(ai): 补充校验改逐块审查——坏块隔离好块照落

Author: Aparencia

app/src-tauri/prompts/note_enrich.json

@@ -1,5 +1,5 @@
 {
-  "version": 1,
+  "version": 2,
   "system": "你是课堂笔记的知识补充助手。用户会给出课程笔记正文与勾选的补充子项。请为每个勾选子项生成一条补充块：深度类（d1 概念展开/d2 步骤补全/d3 例子补全）必须引用笔记中的真实章节标题作为 anchor_ref，内容与课程知识直接相关；广度类（b1~b6）是模型外部知识的延伸，不携带锚点。严格约束：资源推荐（b6）只给标题/书名/作者，绝不输出任何链接（禁止出现 http、https、www 字样）；所有补充内容必须是可核实的事实知识，不确定时宁缺毋滥；不得改写、删除或重复课程原文。",
   "kinds": {
     "d1": "概念展开：对课程中提到的概念做更深入的展开解释",
@@ -12,5 +12,5 @@
     "b5": "实践建议：动手实践的建议",
     "b6": "资源推荐：推荐书目/资源（仅标题，禁止链接）"
   },
-  "output_format": "只输出 JSON，不要任何其他文字、解释或代码块标记。格式：{\"blocks\":[{\"kind\":\"d1|d2|d3|b1|b2|b3|b4|b5|b6\",\"anchor_ref\":\"<深度类必填：笔记中的章节标题；广度类必须为 null>\",\"heading\":\"<块标题，简短>\",\"content\":\"<内容，非空且不超过 3000 字>\",\"confidence\":<0到1之间的小数>}]}。要求：只输出用户勾选的子项，每项至多一条；总块数不超过 50。"
+  "output_format": "只输出 JSON，不要任何其他文字、解释或代码块标记。格式：{\"blocks\":[{\"kind\":\"d1|d2|d3|b1|b2|b3|b4|b5|b6\",\"anchor_ref\":\"<深度类必填：必须逐字等于用户消息中『笔记章节目录』的某一项；若用户消息声明笔记无章节（目录为空），深度类必须填 null；广度类必须为 null>\",\"heading\":\"<块标题，简短>\",\"content\":\"<内容，非空且不超过 3000 字>\",\"confidence\":<0到1之间的小数>}]}。要求：只输出用户勾选的子项，每项至多一条；总块数不超过 50。anchor_ref 字段任何情况下都不得省略。"
 }

app/src-tauri/src/ai_enrich_protocol.rs

@@ -76,6 +76,10 @@ pub struct AiEnrichRequest {
     pub note_content: String,
     pub selected_kinds: Vec<AiEnrichKind>,
     pub profile: String,
+    /// 全篇章节标题目录（2026-09 修复：跨片全局目录注入——长笔记切片后
+    /// 中间片常不含章节标题，模型无从引用；目录给模型"可引用锚点白名单"，
+    /// 空=笔记无章节，深度块 anchor_ref 允许 null 落尾部）
+    pub chapter_directory: Vec<String>,
 }
 
 /// 补充块（kind/锚点/标题/内容/置信度）。
@@ -91,20 +95,24 @@ pub struct AiEnrichBlock {
     pub confidence: f32,
 }
 
+/// 单块内容上限（防单块刷屏；协议与逐块审查共用——2026-09 提为模块常量）。
+pub const BLOCK_MAX_CHARS: usize = 3000;
+/// 响应总块数上限（九子项 + 防刷屏；协议与逐块审查共用）。
+pub const BLOCKS_MAX: usize = 50;
+
 /// 补充响应（块数组；一次批量返回）。
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AiEnrichResponse {
     pub blocks: Vec<AiEnrichBlock>,
 }
 
+/// 全量强校验契约快照（2026-09 起仅测试使用——运行时已改用
+/// enrich_salvage::salvage_blocks 逐块审查：坏块隔离好块照落；本函数保留
+/// 全部规则的"任一违规即整批拒绝"语义作为协议契约的测试基准）。
+#[cfg(test)]
 impl AiEnrichResponse {
-    /// 单块内容上限（防单块刷屏）。
-    const BLOCK_MAX_CHARS: usize = 3000;
-    /// 响应总块数上限（九子项 + 防刷屏）。
-    const BLOCKS_MAX: usize = 50;
-
-    /// schema 强校验（纯函数；失败 → 丢弃 AI 结果回退——防御性编程铁律）。
+    /// schema 强校验（纯函数；失败 → 整批拒绝——契约快照语义）。
     ///
     /// @ai-context: 规则：kind ∈ 选定子项；深度块 anchor_ref 必填（锚点溯源）、
     ///              广度块 anchor_ref 应空（聚合扩展区）；heading/content 非空
@@ -114,12 +122,8 @@ impl AiEnrichResponse {
         if self.blocks.is_empty() {
             return Err("补充响应缺少内容块".to_string());
         }
-        if self.blocks.len() > Self::BLOCKS_MAX {
-            return Err(format!(
-                "补充块数超上限（{} > {}）",
-                self.blocks.len(),
-                Self::BLOCKS_MAX
-            ));
+        if self.blocks.len() > BLOCKS_MAX {
+            return Err(format!("补充块数超上限（{} > {}）", self.blocks.len(), BLOCKS_MAX));
         }
         for b in &self.blocks {
             if !selected.contains(&b.kind) {
@@ -133,7 +137,7 @@ impl AiEnrichResponse {
             if heading.is_empty() || heading.chars().count() > 200 {
                 return Err("块标题为空或超长".to_string());
             }
-            if content.is_empty() || content.chars().count() > Self::BLOCK_MAX_CHARS {
+            if content.is_empty() || content.chars().count() > BLOCK_MAX_CHARS {
                 return Err("块内容为空或超长".to_string());
             }
             if b.kind.is_depth()
@@ -155,7 +159,9 @@ impl AiEnrichResponse {
     }
 }
 
-/// 是否含 URL 模式（B6 防幻觉：http(s)/www 前缀）。
+/// 是否含 URL 模式（B6 防幻觉：http(s)/www 前缀；validate 契约快照专用——
+/// 运行时逐块审查的 URL 规则见 enrich_salvage::salvage_blocks）。
+#[cfg(test)]
 fn contains_url(s: &str) -> bool {
     let lower = s.to_lowercase();
     lower.contains("http://") || lower.contains("https://") || lower.contains("www.")

app/src-tauri/src/ai_mock.rs

@@ -195,15 +195,15 @@ impl AiMockAdapter {
     }
 
     /// 知识补充 mock（REQ-142）：按勾选子项规则化产出合法块数组；
-    /// 响应通过 AiEnrichResponse::validate（深度块带锚点/广度块无锚点/
-    /// B6 无链接——持续验证补充协议校验链）。
-    pub fn enrich(&self, _request: &AiEnrichRequest, selected: &[AiEnrichKind]) -> AiEnrichResponse {
+    /// 深度块锚点取章节目录首项（2026-09 修复：与真实路径同口径——目录空时
+    /// 深度块 anchor_ref=null，走无章节放行语义），广度块无锚点/B6 无链接。
+    pub fn enrich(&self, request: &AiEnrichRequest, selected: &[AiEnrichKind]) -> AiEnrichResponse {
         let blocks: Vec<AiEnrichBlock> = selected
             .iter()
             .map(|kind| AiEnrichBlock {
                 kind: *kind,
                 anchor_ref: if kind.is_depth() {
-                    Some("笔记".to_string())
+                    request.chapter_directory.first().cloned()
                 } else {
                     None
                 },

app/src-tauri/src/ai_note_enrich.rs

@@ -1,17 +1,27 @@
 //! AI 知识补充适配器（REQ-142，v0.8.0 M3）。
 //!
-//! @ai-context: 输入=笔记正文+勾选子项+档案 → 云端一次批量返回块数组 →
-//!              强校验（kind ∈ 勾选/B6 无链接/深度锚点必填——协议层
-//!              AiEnrichResponse::validate）→ 失败回退不落任何补充内容
-//!              （补充是增量能力，失败不破坏原笔记——与精修"降级纯规则"
-//!              语义不同，补充无本地兜底内容，失败即不补充）。
+//! @ai-context: 输入=笔记正文（切片）+章节目录+勾选子项+档案 → 云端一次批量
+//!              返回块数组 → 逐块审查（2026-09 修复：enrich_salvage 取代协议层
+//!              全有或全无的 validate——坏块隔离、好块照落，丢弃原因随回执返回
+//!              供 UI 明示；全批无一可落才失败（原语义"失败不落任何补充内容"
+//!              保留——补充是增量能力，失败不破坏原笔记）。
 //! @ai-context: 提示词模板 prompts/note_enrich.json 编译期捆绑（include_str），
-//!              勾选子项说明动态注入 system；网络/解析走共享 AiClient。
+//!              勾选子项说明动态注入 system；章节目录/无章节说明注入 user
+//!              （anchor_ref 白名单——模型不得自造或省略锚点）；网络/解析走
+//!              共享 AiClient。
 
 use serde::{Deserialize, Serialize};
 
 use crate::ai_client::{AiClient, AiClientError};
 use crate::ai_enrich_protocol::{AiEnrichKind, AiEnrichRequest, AiEnrichResponse};
+use crate::enrich_salvage::salvage_blocks;
+
+/// 单次补充结果：可落响应（已剔除违规块）+ 丢弃原因（UI 明示"哪些块为何未落"）。
+#[derive(Debug, Clone)]
+pub struct EnrichOutcome {
+    pub response: AiEnrichResponse,
+    pub dropped_reasons: Vec<String>,
+}
 
 /// 提示词模板（prompts/note_enrich.json 结构）。
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
@@ -41,7 +51,7 @@ impl NoteEnrichPrompt {
         }
         Self {
             version: 1,
-            system: "你是课堂笔记的知识补充助手：只补充勾选子项，深度类带章节锚点，B6 不输出链接。"
+            system: "你是课堂笔记的知识补充助手：只补充勾选子项，深度类带章节锚点（无章节时 anchor_ref=null），B6 不输出链接。"
                 .to_string(),
             kinds,
             output_format: "只输出 JSON：{\"blocks\":[{\"kind\":\"d1|..|b6\",\"anchor_ref\":\"..|null\",\"heading\":\"..\",\"content\":\"..\",\"confidence\":0.9}]}"
@@ -99,22 +109,42 @@ impl AiNoteEnrichAdapter {
 
     /// 单次批量补充（一请求=全部勾选子项；长笔记切片由 command 层任务编排）。
     ///
-    /// @ai-context: 强校验在此层做（validate 失败 → Parse 错误 → 调用方
-    ///              不落任何补充内容——非法响应不得进入笔记管线）。
+    /// @ai-context: 2026-09 修复：逐块审查在此层做（salvage_blocks）——单块违规
+    ///              只丢该块（原因随 EnrichOutcome 返回），全批无一可落才 Err
+    ///              （调用方不落任何补充内容——非法响应不得进入笔记管线）。
     pub fn enrich(
         &self,
         request: &AiEnrichRequest,
         selected: &[AiEnrichKind],
-    ) -> Result<AiEnrichResponse, AiClientError> {
+    ) -> Result<EnrichOutcome, AiClientError> {
         let system = self.prompt.build_system(selected);
-        let user = serde_json::to_string(request)
+        // 章节目录注入 user 消息（2026-09 修复）：目录=anchor_ref 白名单——
+        // 切片正文可能不含任何章节标题（长笔记跨片），不给目录模型只能省略
+        // 锚点或自造标题；无章节时显式要求 null（防模型省略字段导致整批失败）
+        let mut user_text = String::new();
+        if request.chapter_directory.is_empty() {
+            user_text.push_str(
+                "说明：本笔记没有章节标题（章节目录为空）。深度类块（d1~d3）的 anchor_ref 必须为 null——系统会把这类块安放在笔记尾部。\n\n",
+            );
+        } else {
+            user_text.push_str("笔记章节目录（深度类块 anchor_ref 必须逐字取自以下某一项，不得自造、不得省略；广度类仍为 null）：\n");
+            for c in &request.chapter_directory {
+                user_text.push_str(&format!("- {}\n", c));
+            }
+            user_text.push('\n');
+        }
+        let user_json = serde_json::to_string(request)
             .map_err(|e| AiClientError::Parse(format!("补充请求序列化失败: {}", e)))?;
-        let v = self.client.chat_json(&system, &user)?;
+        user_text.push_str(&user_json);
+        let v = self.client.chat_json(&system, &user_text)?;
         let resp: AiEnrichResponse = serde_json::from_value(v)
             .map_err(|e| AiClientError::Parse(format!("补充响应结构非法: {}", e)))?;
-        resp.validate(selected)
+        let out = salvage_blocks(resp, selected, &request.chapter_directory)
             .map_err(|e| AiClientError::Parse(format!("补充响应校验失败（已丢弃）: {}", e)))?;
-        Ok(resp)
+        Ok(EnrichOutcome {
+            response: AiEnrichResponse { blocks: out.kept },
+            dropped_reasons: out.dropped_reasons,
+        })
     }
 }
 

app/src-tauri/src/commands_ai_enrich.rs

@@ -19,13 +19,14 @@ use crate::ai_client::AiClient;
 use crate::ai_cost::estimate_for_content_model;
 use crate::ai_enrich_protocol::{AiEnrichBlock, AiEnrichKind, AiEnrichRequest, AiEnrichResponse};
 use crate::ai_mock::AiMockAdapter;
-use crate::ai_note_enrich::AiNoteEnrichAdapter;
+use crate::ai_note_enrich::{AiNoteEnrichAdapter, EnrichOutcome};
 use crate::ai_task::{slice_note, AiTaskFailure, AiTaskState, SLICE_MAX_CHARS};
 use crate::commands::AppState;
 use crate::commands_ai_refine::{
     set_task, trim_tasks, AiTaskEntry, AiTaskHandle, RefineEstimateView,
 };
 use crate::enrich_placement::render_enriched_note;
+use crate::enrich_salvage::{chapter_titles_of, salvage_blocks};
 use crate::types::Note;
 
 /// mock 模式 env 键（本地规则补充，不联网——测试/离线开发）。
@@ -47,6 +48,12 @@ pub struct AiEnrichResult {
     pub slices: usize,
     /// 实际返回的子项（kebab-case）
     pub kinds: Vec<String>,
+    /// 丢弃块数（2026-09 修复：逐块审查回执——被隔离的违规块数与原因可见）
+    #[serde(default)]
+    pub dropped_blocks: usize,
+    /// 丢弃原因（逐条人类可读；为空=无丢弃——UI 明示"哪些块为何未落"）
+    #[serde(default)]
+    pub dropped_reasons: Vec<String>,
     pub model: String,
 }
 
@@ -285,24 +292,33 @@ fn run_enrich_task(st: AppState, task_id: u64, note_id: i64, selected: Vec<AiEnr
         );
         let adapter = AiNoteEnrichAdapter::new(client.clone());
         let mock_adapter = AiMockAdapter;
+        // 全篇章节目录（2026-09 修复：跨片全局注入——切片正文常不含章节标题，
+        // 目录=anchor_ref 白名单；空=笔记无章节，深度块允许 null 锚点落尾部）
+        let chapter_dir = chapter_titles_of(&note.content);
         // 切片（长笔记按章节切——REQ-145 基建复用；锚点跨片=全局章节标题）
         let slices = slice_note(&note.content, SLICE_MAX_CHARS);
         let total = slices.len();
         set_task(&st, task_id, AiTaskState::Running { finished_slices: 0, total_slices: total });
         let mut all_blocks: Vec<AiEnrichBlock> = Vec::new();
+        // 2026-09 修复：逐块审查丢弃回执（坏块隔离，原因跨片聚合随结果返回）
+        let mut dropped_reasons_all: Vec<String> = Vec::new();
         let mut turns: Vec<crate::ai_chat::AiTurn> = Vec::with_capacity(total);
         for (i, slice) in slices.iter().enumerate() {
             let req = AiEnrichRequest {
                 note_content: slice.clone(),
                 selected_kinds: selected.clone(),
                 profile: profile.clone(),
+                chapter_directory: chapter_dir.clone(),
             };
             // 单片重试 1 次（审查修复 2026-08-21：与精修 SLICE_RETRY 对齐——
             // 网络抖动瞬态失败直接重试，避免整任务失败浪费已成功的片）
-            let mut resp: Option<AiEnrichResponse> = None;
+            let mut outcome: Option<EnrichOutcome> = None;
             for attempt in 0..=1 {
                 let r = if mock {
-                    Ok(mock_adapter.enrich(&req, &selected))
+                    Ok(EnrichOutcome {
+                        response: mock_adapter.enrich(&req, &selected),
+                        dropped_reasons: Vec::new(),
+                    })
                 } else {
                     adapter.enrich(&req, &selected).map_err(AiTaskFailure::from)
                 };
@@ -313,9 +329,9 @@ fn run_enrich_task(st: AppState, task_id: u64, note_id: i64, selected: Vec<AiEnr
                             turn: i + 1,
                             system: adapter.prompt.build_system(&selected),
                             user: serde_json::to_string(&req).unwrap_or_default(),
-                            response: serde_json::to_string(&v).unwrap_or_default(),
+                            response: serde_json::to_string(&v.response).unwrap_or_default(),
                         });
-                        resp = Some(v);
+                        outcome = Some(v);
                         break;
                     }
                     Err(e) if attempt < 1 => {
@@ -324,17 +340,25 @@ fn run_enrich_task(st: AppState, task_id: u64, note_id: i64, selected: Vec<AiEnr
                     Err(e) => return Err(e),
                 }
             }
-            let resp = resp.expect("重试循环必然产出结果或返回");
-            all_blocks.extend(resp.blocks);
+            let outcome = outcome.expect("重试循环必然产出结果或返回");
+            dropped_reasons_all.extend(outcome.dropped_reasons);
+            all_blocks.extend(outcome.response.blocks);
             set_task(
                 &st,
                 task_id,
                 AiTaskState::Running { finished_slices: i + 1, total_slices: total },
             );
         }
-        // 合并后整体强校验（非法 → 不落任何补充内容）
-        let resp = AiEnrichResponse { blocks: all_blocks };
-        resp.validate(&selected).map_err(AiTaskFailure::InvalidResponse)?;
+        // 合并后整体复审（2026-09 修复：逐块审查替代全有或全无 validate——
+        // 单片已隔离违规块；此处兜底跨片总量上限，全部不合规 → 不落任何内容）
+        let final_out = salvage_blocks(
+            AiEnrichResponse { blocks: all_blocks },
+            &selected,
+            &chapter_dir,
+        )
+        .map_err(AiTaskFailure::InvalidResponse)?;
+        dropped_reasons_all.extend(final_out.dropped_reasons);
+        let resp = AiEnrichResponse { blocks: final_out.kept };
         let enriched = render_enriched_note(&note.content, &resp);
         let depth = resp.blocks.iter().filter(|b| b.kind.is_depth()).count();
         let breadth = resp.blocks.len() - depth;
@@ -349,6 +373,8 @@ fn run_enrich_task(st: AppState, task_id: u64, note_id: i64, selected: Vec<AiEnr
                 breadth_blocks: breadth,
                 slices: total,
                 kinds,
+                dropped_blocks: dropped_reasons_all.len(),
+                dropped_reasons: dropped_reasons_all,
                 model: client.config.model,
             },
             turns,