fix(ai): 精修丢图修复——配图行缺括号 bug + 本地合并降级回填 (F1-A2)

Author: Aparencia

app/src-tauri/src/commands_ai_refine.rs

@@ -388,6 +388,10 @@ fn run_refine_task_inner(
         );
     }
     // ④ 合并 + 与规则版 diff（基线=本地版，AI 变化点高亮）
+    // 丢图修复（2026-08-21 F1）：协议 v2 前，模型可能丢弃规则版画面配图行
+    // （`- ![画面 N](session-images/..)`）——本地合并降级：AI 未保留配图时
+    // 把规则版配图行按章节合并回精修版（不丢不假，零模型成本）
+    let refined = crate::note_image_merge::merge_rule_images(&draft.markdown, &refined);
     let diff = diff_markdown(&draft.markdown, &refined);
     let (added, removed, _) = diff_stats(&diff);
     Ok(AiRefineResult {

app/src-tauri/src/lib.rs

@@ -164,6 +164,8 @@ mod model_registry;
 mod note_filter;
 mod note_filter_ai;
 mod note_filter_discourse;
+// v0.8.0 F1（REQ-141 丢图修复）：精修版配图本地合并降级（协议 v2 image 块兜底）
+mod note_image_merge;
 mod novelty;
 mod ocr;
 mod ocr_correction;

app/src-tauri/src/note_filter.rs

@@ -445,7 +445,10 @@ pub fn render_screen_points(screens: &[SessionScreen]) -> Vec<String> {
             lines.push(format!("  - 标签：{}", s.labels.join(" · ")));
         }
         if let Some(rel) = &s.image_ref {
-            lines.push(format!("  - ![画面 {}](session-images/{}/{}", i + 1, s.session_id, rel));
+            // 修复（2026-08-21 审查）：缺闭合 `)`——前端渲染正则
+            // `^\s*-\s*!\[([^\]]*)\]\(([^)]*)\)$` 要求 `)$` 结尾，缺括号时
+            // 配图行永远匹配不上 → 渲染为纯文本而非图片（丢图真因之一）
+            lines.push(format!("  - ![画面 {}](session-images/{}/{})", i + 1, s.session_id, rel));
         }
     }
     lines

app/src-tauri/src/note_image_merge.rs

@@ -0,0 +1,79 @@
+//! 精修版配图本地合并降级（REQ-141 丢图修复，2026-08-21 F1）。
+//!
+//! @ai-context: 规则版 markdown 含画面要点配图行（`- ![画面 N](session-images/..)`，
+//!              由 note_filter::render_screen_points 生成）；AI 精修协议
+//!              v1 无 image 块类型，模型可能丢弃配图行 → 精修版丢图。
+//!              本模块为降级路径：AI 未保留配图时，把规则版配图行按章节
+//!              合并回精修版（零模型成本，不丢不假）。协议 v2（F3）AI
+//!              返回 image 块后，本路径仅在 AI 未返回时兜底。
+//! @ai-context: 纯函数可单测；配图行识别用宽松模式（行含 session-images/ 且
+//!              匹配 `- ![` 前缀——与前端渲染正则同口径，兼容缩进变体）。
+
+/// 配图行前缀（规则版生成格式；前端渲染正则 `^\s*-\s*!\[` 同口径）。
+const IMG_MARK: &str = "session-images/";
+
+/// 从 markdown 提取配图行（保留原行文本；空输入 → 空向量）。
+///
+/// @ai-context: 只认列表项形态的配图行（`- ![` 前缀 + session-images/ 引用）；
+///              其他形态（正文内嵌图等）不在规则版生成范围内，不处理。
+pub fn extract_image_lines(markdown: &str) -> Vec<String> {
+    markdown
+        .lines()
+        .filter(|l| {
+            let t = l.trim_start();
+            t.starts_with("- ![") && l.contains(IMG_MARK)
+        })
+        .map(|l| l.to_string())
+        .collect()
+}
+
+/// 精修版是否已含配图行（AI 已保留/生成 → 本地合并跳过，不干预 AI 输出）。
+pub fn has_image_lines(markdown: &str) -> bool {
+    markdown.lines().any(|l| l.contains(IMG_MARK))
+}
+
+/// 把规则版配图行合并回精修版（降级路径总入口）。
+///
+/// @ai-context: 规则：① 规则版无配图 → 原样返回精修版；② 精修版已有配图
+///              （AI 保留或 image 块渲染）→ 原样返回（AI 处理优先）；
+///              ③ 否则把规则版配图行作为「画面要点」章节追加——
+///              精修版已有 `## 画面要点` 章节则插入其标题之后，
+///              无则文末追加新章节（配图是课程内容，精修=整理不创作
+///              语义下必须保留）。
+pub fn merge_rule_images(base_markdown: &str, refined_markdown: &str) -> String {
+    let imgs = extract_image_lines(base_markdown);
+    if imgs.is_empty() || has_image_lines(refined_markdown) {
+        return refined_markdown.to_string();
+    }
+    let section = format!("## 画面要点\n\n{}\n", imgs.join("\n"));
+    // 精修版已有画面要点章节 → 插入标题行后（保持章节内聚）
+    let heading_pos = refined_markdown
+        .lines()
+        .position(|l| {
+            let t = l.trim_end();
+            t == "## 画面要点" || t == "## 画面要点 "
+        });
+    match heading_pos {
+        Some(idx) => {
+            let mut out = String::new();
+            for (i, line) in refined_markdown.lines().enumerate() {
+                out.push_str(line);
+                out.push('\n');
+                if i == idx {
+                    out.push('\n');
+                    out.push_str(&section);
+                }
+            }
+            out
+        }
+        None => {
+            let trimmed = refined_markdown.trim_end();
+            format!("{}\n\n{}\n", trimmed, section)
+        }
+    }
+}
+
+/// 单测独立文件（保持本文件 ≤300 行，AGENTS.md §3）。
+#[cfg(test)]
+#[path = "note_image_merge_tests.rs"]
+mod tests;

app/src-tauri/src/note_image_merge_tests.rs

@@ -0,0 +1,97 @@
+//! note_image_merge.rs 单测（AAA 模式）。
+//!
+//! @ai-context: 覆盖：提取（宽松匹配/空输入/非配图行排除）、精修版已含图
+//!              跳过、已有画面要点章节插入、无章节文末追加、降级不动输入。
+
+use crate::note_image_merge::{extract_image_lines, has_image_lines, merge_rule_images};
+
+const RULE_MD: &str = "# 课程标题\n\n正文内容\n\n## 画面要点\n\n- **画面 1**\n  - ![画面 1](session-images/5/full/30000.webp)\n";
+
+#[test]
+fn extract_picks_list_item_image_lines() {
+    // Act
+    let imgs = extract_image_lines(RULE_MD);
+    // Assert：只提取配图行（画面要点标题/正文行不含 session-images/ 不提取）
+    assert_eq!(imgs.len(), 1);
+    assert!(imgs[0].contains("session-images/5/full/30000.webp"));
+}
+
+#[test]
+fn extract_empty_input_returns_empty() {
+    assert!(extract_image_lines("").is_empty());
+    assert!(extract_image_lines("   \n  ").is_empty());
+}
+
+#[test]
+fn extract_excludes_non_list_image_forms() {
+    // 正文内嵌 markdown 图（非列表项）不在规则版生成范围——不提取
+    let md = "正文 ![内嵌](session-images/5/full/a.webp) 继续\n- ![画面 1](session-images/5/full/b.webp)";
+    let imgs = extract_image_lines(md);
+    assert_eq!(imgs.len(), 1);
+    assert!(imgs[0].contains("b.webp"));
+}
+
+#[test]
+fn merge_skips_when_rule_has_no_images() {
+    // Arrange：规则版无配图
+    let base = "# 标题\n\n正文";
+    let refined = "## 精修\n\n内容";
+    // Act
+    let out = merge_rule_images(base, refined);
+    // Assert：原样返回精修版
+    assert_eq!(out, refined);
+}
+
+#[test]
+fn merge_skips_when_refined_already_has_images() {
+    // Arrange：精修版已有配图（AI 保留/image 块渲染）→ 不干预
+    let base = "# 标题\n\n## 画面要点\n\n- ![画面 1](session-images/5/full/30000.webp)";
+    let refined = "## 精修\n\n内容\n\n- ![画面 1](session-images/5/full/30000.webp)";
+    // Act
+    let out = merge_rule_images(base, refined);
+    // Assert：原样（不重复追加）
+    assert_eq!(out, refined);
+}
+
+#[test]
+fn merge_appends_new_section_when_refined_has_no_heading() {
+    // Arrange：精修版无画面要点章节
+    let refined = "## 精修\n\n正文内容";
+    // Act
+    let out = merge_rule_images(RULE_MD, refined);
+    // Assert：文末追加画面要点章节 + 配图行
+    assert!(out.contains("## 画面要点"));
+    assert!(out.contains("session-images/5/full/30000.webp"));
+    // 配图行在文末（追加语义——不破坏精修结构）
+    assert!(out.trim_end().ends_with("30000.webp)"));
+}
+
+#[test]
+fn merge_inserts_after_existing_heading() {
+    // Arrange：精修版已有画面要点章节（空——AI 没保留配图）
+    let refined = "## 精修\n\n正文\n\n## 画面要点\n";
+    // Act
+    let out = merge_rule_images(RULE_MD, refined);
+    // Assert：配图行插入画面要点标题之后
+    let pos_title = out.find("## 画面要点").unwrap();
+    let pos_img = out.find("session-images/5/full/30000.webp").unwrap();
+    assert!(pos_img > pos_title, "配图行应在画面要点标题之后");
+}
+
+#[test]
+fn merge_does_not_mutate_inputs() {
+    // Arrange
+    let base = RULE_MD.to_string();
+    let refined = "## 精修\n\n正文".to_string();
+    // Act
+    let _ = merge_rule_images(&base, &refined);
+    // Assert：输入不变（纯函数）
+    assert!(base.contains("session-images/5/full/30000.webp"));
+    assert_eq!(refined, "## 精修\n\n正文");
+}
+
+#[test]
+fn has_images_detects_any_session_images_ref() {
+    assert!(has_image_lines("- ![画面 1](session-images/5/full/a.webp)"));
+    assert!(!has_image_lines("纯文本无图"));
+}