feat(ai): 精修画面理解——vision-exp 图片随精修上云（v0.12.0 M5·精修侧）

M5 质量债·AI 精修图片理解（可选增强，默认关）：
- ai_settings 加 vision_refine_enabled（默认关——图片上传最敏感独立闸门）+ 持久化/测试
- ai_client 加 chat_vision + build_vision_payload（content 数组 text+image_url data URI）；
  chat_text 重试/错误归一提取 post_completions 复用——9 处既有调用零改动
- ai_note_refine 加 refine_vision（多模态分支，images 空回落 chat_json，现有行为零变化）
- ai_refine_task 装载会话屏卡图（≤1280px 控 token → PNG base64），开启时切片请求
  附屏卡图送 vision-exp；仅精修触发，不新增独立命令
- commands_ai_settings 加 ai_set_vision_refine 命令 + AiSettingsView 透出字段
- 前端 AiServicePanel 加「精修时启用画面理解」复选框（默认关）
- 隐私红线（ADR-010 扩展）：图片仅随精修切片请求上云，关闭走纯文本零变化

注：M5 剩余「视频会话全帧 OCR 下线 + 关键帧存图触发解耦」（live_keyframes/
live_frame_process）涉及实时采集管线，需真机验证，留待后续提交。

Author: Aparencia

app/src-tauri/src/ai_client.rs

@@ -169,10 +169,35 @@ impl AiClient {
     ///              parse_response 做 TextFilterResponse 反序列化）；
     ///              chat_json = chat_text + parse_json_object 的组合。
     pub fn chat_text(&self, system: &str, user: &str) -> Result<String, AiClientError> {
+        let payload = build_chat_payload(&self.config.model, system, user, self.config.max_tokens);
+        let body = self.post_completions(payload)?;
+        extract_content(&body)
+    }
+
+    /// chat/completions 多模态请求（v0.12.0 M5：vision-exp 视觉提取）→ 原始文本。
+    ///
+    /// @ai-context: content 数组（text + image_url data URI，OpenAI 兼容）。
+    ///              images 为 base64 data URI 列表（"data:image/png;base64,.."），
+    ///              调用方负责缩放 ≤1280px 控 token；空 images 回落纯文本
+    ///              content（与 chat_text 行为一致）。与 chat_text/chat_json
+    ///              共用 post_completions 的降级链/重试/错误归一——9 处既有调用零改动。
+    pub fn chat_vision(
+        &self,
+        system: &str,
+        user: &str,
+        images: &[String],
+    ) -> Result<String, AiClientError> {
+        let payload = build_vision_payload(&self.config.model, system, user, images, self.config.max_tokens);
+        let body = self.post_completions(payload)?;
+        extract_content(&body)
+    }
+
+    /// 发送 chat/completions payload（HTTP + 指数退避重试 + 错误归一；纯网络
+    /// 路径不单测）。chat_text/chat_vision 共用——降级链/重试单一实现。
+    fn post_completions(&self, payload: serde_json::Value) -> Result<String, AiClientError> {
         if !self.config.is_local && self.config.api_key.trim().is_empty() {
             return Err(AiClientError::Auth("未配置 API 密钥（设置页保存或配置环境变量）".to_string()));
         }
-        let payload = build_chat_payload(&self.config.model, system, user, self.config.max_tokens);
         let url = chat_completions_url(&self.config.base_url);
         let agent = ureq::AgentBuilder::new()
             .timeout(std::time::Duration::from_secs(self.config.timeout_secs.max(5)))
@@ -190,17 +215,16 @@ impl AiClient {
                 .send_json(payload.clone());
             match resp {
                 Ok(resp) => {
-                    let body = resp
+                    return resp
                         .into_string()
-                        .map_err(|e| AiClientError::Network(format!("读取响应失败: {}", e)))?;
-                    return extract_content(&body);
+                        .map_err(|e| AiClientError::Network(format!("读取响应失败: {}", e)));
                 }
                 // 401/403 拆分（2026-08-21 真机 unauthorized 排查）：401=密钥
                 // 无效（换密钥），403=账号无权限/模型未开通（换模型或开权限）——
                 // 合并时用户无法区分该修密钥还是该换模型
                 Err(ureq::Error::Status(401, _)) => {
                     return Err(AiClientError::Auth(
-                        "API 密钥无效（HTTP 401）——请检查设置页密钥或环境变量 SILICONFLOW_API_KEY".to_string(),
+                        "API 密钥无效（HTTP 401）——请检查设置页密钥或环境变量 DEEPSEEK_API_KEY".to_string(),
                     ));
                 }
                 Err(ureq::Error::Status(403, _)) => {
@@ -287,6 +311,41 @@ pub fn build_chat_payload(model: &str, system: &str, user: &str, max_tokens: u32
     body
 }
 
+/// 构建多模态 chat/completions payload（v0.12.0 M5：vision-exp 视觉提取。
+/// 纯函数可单测；content 为数组——text + image_url data URI，OpenAI 兼容）。
+///
+/// @ai-context: images 为空 → content 回归纯文本（与 build_chat_payload 一致，
+///              但多加 json_object 约束——视觉精修输出结构同 note_refine v2）。
+/// @ai-context: image_url 走 data URI（base64 内联，无本地上传路径——隐私红线：
+///              图片仅随精修切片请求上云，不作独立提取命令）。
+pub fn build_vision_payload(
+    model: &str,
+    system: &str,
+    user: &str,
+    images: &[String],
+    max_tokens: u32,
+) -> serde_json::Value {
+    let mut content: Vec<serde_json::Value> = Vec::new();
+    content.push(serde_json::json!({"type": "text", "text": user}));
+    for img in images {
+        content.push(serde_json::json!({"type": "image_url", "image_url": {"url": img}}));
+    }
+    let mut body = serde_json::json!({
+        "model": model,
+        "messages": [
+            {"role": "system", "content": system},
+            {"role": "user", "content": content}
+        ],
+        "temperature": 0,
+        "max_tokens": max_tokens,
+        "response_format": {"type": "json_object"}
+    });
+    if model.to_lowercase().contains("r1") {
+        body["no_think"] = serde_json::json!(true);
+    }
+    body
+}
+
 /// 从 chat/completions 响应体提取 assistant 文本（纯函数）。
 pub fn extract_content(body: &str) -> Result<String, AiClientError> {
     let v: serde_json::Value = serde_json::from_str(body)

app/src-tauri/src/ai_note_refine.rs

@@ -11,7 +11,7 @@
 
 use serde::{Deserialize, Serialize};
 
-use crate::ai_client::{AiClient, AiClientError};
+use crate::ai_client::{AiClient, AiClientError, parse_json_object};
 use crate::ai_refine_protocol::{AiRefineRequest, AiRefineResponse};
 
 /// 提示词模板（prompts/note_refine.json 结构）。
@@ -127,10 +127,30 @@ impl AiNoteRefineAdapter {
     ///              summary）——提示词据此约束"只整理本片、沿用全局章节"；
     ///              响应 schema_version=2（向后兼容：旧响应缺省 1 仍可解析）。
     pub fn refine(&self, request: &AiRefineRequest) -> Result<AiRefineResponse, AiClientError> {
+        // v0.12.0 M5：单一实现——refine = refine_vision(request, &[])（纯文本，
+        // 与既有行为逐字节一致；画面理解是可选增强，不改变默认链）
+        self.refine_vision(request, &[])
+    }
+
+    /// 单次精修（多模态分支，v0.12.0 M5：vision-exp 视觉提取）。
+    ///
+    /// @ai-context: images 非空 → 屏卡图随切片请求送 vision-exp（content 数组
+    ///              多模态，chat_vision）；空 → 纯文本（chat_json，零变化）。
+    ///              精修输出直接含画面要点；校验/回退逻辑与 refine 共用。
+    pub fn refine_vision(
+        &self,
+        request: &AiRefineRequest,
+        images: &[String],
+    ) -> Result<AiRefineResponse, AiClientError> {
         let system = self.prompt.build_system(&request.profile);
         let user = serde_json::to_string(request)
             .map_err(|e| AiClientError::Parse(format!("精修请求序列化失败: {}", e)))?;
-        let v = self.client.chat_json(&system, &user)?;
+        let v = if images.is_empty() {
+            self.client.chat_json(&system, &user)?
+        } else {
+            let raw = self.client.chat_vision(&system, &user, images)?;
+            parse_json_object(&raw)?
+        };
         let mut resp: AiRefineResponse = serde_json::from_value(v)
             .map_err(|e| AiClientError::Parse(format!("精修响应结构非法: {}", e)))?;
         resp.validate()

app/src-tauri/src/ai_refine_task.rs

@@ -13,6 +13,8 @@ use std::collections::VecDeque;
 use std::sync::mpsc;
 use std::sync::{Arc, Mutex};
 
+use base64::Engine;
+
 use crate::ai_client::AiClient;
 use crate::ai_mock::AiMockAdapter;
 use crate::ai_note_refine::AiNoteRefineAdapter;
@@ -211,6 +213,13 @@ fn run_refine_task_inner(
     let client = AiClient::from_settings_with_store(&settings, stored_key, &store);
     let adapter = AiNoteRefineAdapter::new(client.clone());
     let mock_adapter = AiMockAdapter;
+    // v0.12.0 M5：画面理解——仅精修设置开启时装载会话屏卡图（≤1280px 控 token；
+    // 空 → 精修纯文本，现有行为零变化；图文会话不触发——调用方只对视频会话接线）
+    let vision_images = if settings.vision_refine_enabled {
+        load_session_vision_images(&st.data_dir, session_id)
+    } else {
+        Vec::new()
+    };
     // F2-B4：并发精修（worker 池消费切片队列；按片上报进度；失败片重试后
     // 仍失败 → 记 failed 下标，不中断其他片——部分成功语义）
     let (markdowns, failed) = refine_slices_concurrent(RefineCtx {
@@ -224,6 +233,7 @@ fn run_refine_task_inner(
         workers: total.min(CONCURRENCY),
         st,
         task_id,
+        vision_images: &vision_images,
     });
     // ④ 合并（协议层 merge_refine_slices：各片 join + 章节锚点回挂——7️⃣
     // 剥离的章节锚点按标题精确匹配还原，未匹配不挂）
@@ -260,6 +270,9 @@ struct RefineCtx<'a> {
     workers: usize,
     st: &'a AppState,
     task_id: u64,
+    /// v0.12.0 M5：屏卡图 base64 data URI 列表（vision_refine_enabled 开启且
+    /// 会话有归档图时非空；空 → 精修纯文本，现有行为零变化）
+    vision_images: &'a [String],
 }
 
 /// 片间摘要（F3 v2：前/后片首尾 N 字——提示词衔接上下文，防片间断裂）。
@@ -282,6 +295,52 @@ fn slice_summary(text: &str, head: bool) -> Option<String> {
     }
 }
 
+/// v0.12.0 M5：装载会话屏卡图（≤1280px 控 token → PNG base64 data URI）。
+///
+/// @ai-context: 仅 vision_refine_enabled 开启时调用；目录缺失/解码失败 → 跳过
+///              （空列表 → 精修纯文本，现有行为零变化——画面理解是可选增强，
+///              不是硬依赖，绝不阻塞精修主链路）。图片库为
+///              data_dir/session-images/<id> 下平铺 PNG/JPEG 屏卡。
+/// @ai-context: 隐私红线（ADR-010 扩展）：图片仅随精修切片请求上云，不作独立
+///              提取命令；缩放控 token（长图缩放不裁剪，保画面完整）。
+fn load_session_vision_images(data_dir: &std::path::Path, session_id: i64) -> Vec<String> {
+    const MAX_EDGE: u32 = 1280;
+    let dir = data_dir.join("session-images").join(session_id.to_string());
+    let Ok(entries) = std::fs::read_dir(&dir) else { return Vec::new() };
+    let mut out = Vec::new();
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if !path.is_file() {
+            continue;
+        }
+        let ext = path.extension().and_then(|e| e.to_str()).unwrap_or("").to_lowercase();
+        if ext != "png" && ext != "jpg" && ext != "jpeg" {
+            continue;
+        }
+        let Ok(frame) = image::open(&path) else { continue };
+        // 长边 >1280 按比例缩放（保比例；小图原样——控 token 同时不糊画面）。
+        // resize 返回 RgbaImage，与 to_rgba8() 同型。
+        let (w, h) = (frame.width(), frame.height());
+        let max_edge = w.max(h);
+        let rgb = if max_edge > MAX_EDGE {
+            let scale = MAX_EDGE as f32 / max_edge as f32;
+            let nw = (w as f32 * scale).round().max(1.0) as u32;
+            let nh = (h as f32 * scale).round().max(1.0) as u32;
+            image::imageops::resize(&frame, nw, nh, image::imageops::FilterType::Triangle)
+        } else {
+            frame.to_rgba8()
+        };
+        let mut buf = std::io::Cursor::new(Vec::new());
+        let encoder = image::codecs::png::PngEncoder::new(&mut buf);
+        if rgb.write_with_encoder(encoder).is_err() {
+            continue;
+        }
+        let b64 = base64::engine::general_purpose::STANDARD.encode(buf.into_inner());
+        out.push(format!("data:image/png;base64,{}", b64));
+    }
+    out
+}
+
 /// 并发切片精修（纯编排）：worker 池从共享队列取片 → 单片重试 → 收集。
 ///
 /// @ai-context: 返回 (各片 markdown（保序，失败片跳过）, 失败片数)。
@@ -338,8 +397,13 @@ fn refine_slices_concurrent(ctx: RefineCtx<'_>) -> (Vec<String>, usize) {
                 for attempt in 0..=SLICE_RETRY {
                     let resp = if mock {
                         Ok(mock_adapter.refine(req))
-                    } else {
+                    } else if ctx.vision_images.is_empty() {
                         adapter.refine(req).map_err(AiTaskFailure::from)
+                    } else {
+                        // v0.12.0 M5：开启画面理解 → 屏卡图随切片请求送 vision-exp
+                        adapter
+                            .refine_vision(req, ctx.vision_images)
+                            .map_err(AiTaskFailure::from)
                     };
                     match resp {
                         Ok(r) => {

app/src-tauri/src/ai_settings.rs

@@ -34,6 +34,11 @@ pub struct AiSettings {
     pub low_balance_threshold: f64,
     /// 成本确认"记住此选择"偏好（REQ-143 基础版；M2 精修消费）
     pub remember_cost_choice: bool,
+    /// 精修时启用画面理解（v0.12.0 M5）：开启后 AI 精修请求附带屏卡图
+    /// （content 数组多模态，deepseek-v4-flash-vision-exp 视觉提取画面要点）。
+    /// 图片上传最敏感——独立闸门；默认关（关闭则精修纯文本，现有行为零变化）。
+    /// 仅视频会话生效；图文会话 OCR 已足够，不触发 vision。
+    pub vision_refine_enabled: bool,
 }
 
 impl Default for AiSettings {
@@ -45,6 +50,7 @@ impl Default for AiSettings {
             model: DEFAULT_AI_MODEL.to_string(),
             low_balance_threshold: DEFAULT_LOW_BALANCE_THRESHOLD,
             remember_cost_choice: false,
+            vision_refine_enabled: false,
         }
     }
 }

app/src-tauri/src/ai_settings_tests.rs

@@ -20,6 +20,8 @@ fn default_is_disabled_and_unauthorized() {
     let s = AiSettings::default();
     assert!(!s.enabled, "全局开关默认必须关闭");
     assert!(!s.authorized, "授权默认必须未同意");
+    // v0.12.0 M5：图片上传最敏感——vision 画面理解默认关（隐私红线）
+    assert!(!s.vision_refine_enabled, "图片理解默认必须关闭");
 }
 
 #[test]
@@ -51,6 +53,8 @@ fn save_load_roundtrip() {
     s.model = "acme/model-1".to_string();
     s.low_balance_threshold = 5.0;
     s.remember_cost_choice = true;
+    // v0.12.0 M5：vision 画面理解默认关——持久化 roundtrip 保真
+    s.vision_refine_enabled = true;
     s.save(&path).expect("保存成功");
     let loaded = AiSettings::load(&path);
     assert_eq!(loaded, s);

app/src-tauri/src/commands_ai_settings.rs

@@ -29,6 +29,8 @@ pub struct AiSettingsView {
     pub model: String,
     pub low_balance_threshold: f64,
     pub remember_cost_choice: bool,
+    /// 精修时启用画面理解（v0.12.0 M5——默认关，图片上传最敏感独立闸门）
+    pub vision_refine_enabled: bool,
     /// 是否已配置密钥（env 或凭据库）
     pub has_key: bool,
     /// 密钥来源：credential | env | none
@@ -64,6 +66,7 @@ pub fn ai_get_settings(state: State<'_, AppState>) -> Result<AiSettingsView, Str
         model: s.model,
         low_balance_threshold: s.low_balance_threshold,
         remember_cost_choice: s.remember_cost_choice,
+        vision_refine_enabled: s.vision_refine_enabled,
         has_key,
         key_source,
     })
@@ -138,6 +141,20 @@ pub fn ai_set_enabled(state: State<'_, AppState>, enabled: bool) -> Result<(), S
     lock.save(&state.ai_settings_path)
 }
 
+/// 开启/关闭"精修时画面理解"（v0.12.0 M5——图片上传最敏感，独立闸门默认关）。
+///
+/// @ai-context: 仅影响 AI 音视频会话精修是否随请求上传屏卡图；开启不等于自动
+///              上传——仍需全局 enabled + authorized（content_gate 门控）。
+#[tauri::command]
+pub fn ai_set_vision_refine(state: State<'_, AppState>, refine_enabled: bool) -> Result<(), String> {
+    let mut lock = state
+        .ai_settings
+        .lock()
+        .map_err(|e| format!("AI 设置锁中毒: {}", e))?;
+    lock.vision_refine_enabled = refine_enabled;
+    lock.save(&state.ai_settings_path)
+}
+
 /// 一键测试连接（REQ-138：调余额接口验证密钥有效性——错误密钥明确报错）。
 ///
 /// @ai-context: 配置验证类读操作，不 gate 授权；401/403 → 明确"密钥无效"

app/src-tauri/src/lib.rs

@@ -552,6 +552,7 @@ pub fn run() {
             commands_ai_settings::ai_update_settings,
             commands_ai_settings::ai_set_authorized,
             commands_ai_settings::ai_set_enabled,
+            commands_ai_settings::ai_set_vision_refine,
             commands_ai_settings::ai_test_connection,
             commands_ai_settings::ai_get_balance,
             commands_ai_settings::ai_audit_list,

app/src/components/AiServicePanel.tsx

@@ -106,6 +106,20 @@ export default function AiServicePanel() {
     }
   };
 
+  /** v0.12.0 M5：精修画面理解开关（图片上传最敏感——独立闸门默认关） */
+  const toggleVisionRefine = async (on: boolean) => {
+    setBusy(true);
+    try {
+      await invoke("ai_set_vision_refine", { refineEnabled: on });
+      setMsg({ kind: "ok", text: on ? "已开启画面理解（仅视频会话精修生效）" : "已关闭画面理解" });
+      await load();
+    } catch (e) {
+      setMsg({ kind: "err", text: `操作失败：${e}` });
+    } finally {
+      setBusy(false);
+    }
+  };
+
   return (
     <div style={{ fontSize: 12, color: "#1f2937" }}>
       <div style={{ display: "flex", alignItems: "center", gap: 8, marginBottom: 10 }}>
@@ -131,6 +145,20 @@ export default function AiServicePanel() {
         <span style={{ color: "#6b7280" }}>（默认关——AI 调用须显式开启）</span>
       </div>
 
+      {/* v0.12.0 M5：精修画面理解（图片上传最敏感——独立闸门默认关） */}
+      <div style={{ display: "flex", alignItems: "center", gap: 8, marginBottom: 10 }}>
+        <label style={{ display: "flex", alignItems: "center", gap: 6, cursor: "pointer" }}>
+          <input
+            type="checkbox"
+            checked={!!view?.visionRefineEnabled}
+            disabled={busy}
+            onChange={(e) => void toggleVisionRefine(e.target.checked)}
+          />
+          精修时启用画面理解
+        </label>
+        <span style={{ color: "#6b7280" }}>（默认关——图片随精修上传，仅视频会话生效）</span>
+      </div>
+
       {/* 授权确认卡（开启且未授权时出现） */}
       {consentVisible && (
         <div

app/src/types/ai.ts

@@ -16,6 +16,8 @@ export interface AiSettingsView {
   model: string;
   lowBalanceThreshold: number;
   rememberCostChoice: boolean;
+  /** v0.12.0 M5：精修时启用画面理解（默认关——图片随精修上传，仅视频会话生效） */
+  visionRefineEnabled: boolean;
   hasKey: boolean;
   /** credential（凭据库）| env（环境变量）| none */
   keySource: string;