feat(ai): 精修片内流式——NDJSON 逐节 SSE + Delta 帧打字机（REQ-290①）

Author: Aparencia

app/src-tauri/src/ai_chat_stream.rs

@@ -143,6 +143,54 @@ pub fn extract_usage(line: &str) -> Option<String> {
     }
 }
 
+/// 精修流式传输（REQ-290①）：对给定 payload 置 stream:true 发 SSE，逐 delta
+/// 回调 emit（无取消语义——精修片幂等由重试兜底，与 chat stream_chat 区分：
+/// 不自动重试/不落库/无 usage 消费）。返回全部累积文本供整包回退解析。
+pub fn stream_sse_content(
+    client: &AiClient,
+    mut payload: serde_json::Value,
+    mut emit: impl FnMut(&str),
+) -> Result<StreamOutcome, AiClientError> {
+    if !client.config.is_local && client.config.api_key.trim().is_empty() {
+        return Err(AiClientError::Auth(
+            "未配置 API 密钥（设置页保存或配置环境变量）".to_string(),
+        ));
+    }
+    payload["stream"] = serde_json::json!(true);
+    let url = chat_completions_url(&client.config.base_url);
+    let agent = ureq::AgentBuilder::new()
+        .timeout(std::time::Duration::from_secs(client.config.timeout_secs.max(5)))
+        .build();
+    let resp = agent
+        .post(&url)
+        .set("Content-Type", "application/json")
+        .set("Authorization", &format!("Bearer {}", client.config.api_key.trim()))
+        .send_string(&payload.to_string())
+        .map_err(map_status)?;
+    let reader = BufReader::new(resp.into_reader());
+    let mut content = String::new();
+    let mut usage_json: Option<String> = None;
+    for line in reader.lines() {
+        let line = match line {
+            Ok(l) => l,
+            Err(_) => break, // 传输中途断流：以已累积内容为准
+        };
+        match parse_sse_line(&line) {
+            SseEvent::Delta(d) => {
+                content.push_str(&d);
+                emit(&d);
+            }
+            SseEvent::Done => break,
+            SseEvent::Ignore => {
+                if let Some(usage) = extract_usage(&line) {
+                    usage_json = Some(usage);
+                }
+            }
+        }
+    }
+    Ok(StreamOutcome { content, usage_json, cancelled: false })
+}
+
 /// HTTP 状态 → AiClientError（与 post_completions 同归一口径——四下一致）。
 fn map_status(e: ureq::Error) -> AiClientError {
     match e {

app/src-tauri/src/ai_note_refine.rs

@@ -199,6 +199,76 @@ impl AiNoteRefineAdapter {
         }
         Ok(resp)
     }
+
+    /// REQ-290① 流式精修（NDJSON 逐节，默认路径）：SSE 增量累积 → 行级解析
+    /// （每行=与整包数组元素同构的节对象）；每解析一节即回调 on_section
+    /// （调用方渲染推 Delta 帧——打字机正文）。返回整包 Response（schema v2，
+    /// 与终稿同构；下游 diff/落库语义零变化）。
+    ///
+    /// @ai-context: 模型不遵守逐节约定（整包 JSON 输出）→ sections 空 → Err
+    ///              Parse，调用方同 attempt 回退非流式 refine()（行为与旧版
+    ///              逐字节一致——流式只是呈现增强，诚实降级）。
+    #[allow(clippy::type_complexity)]
+    pub fn refine_stream_ndjson(
+        &self,
+        request: &AiRefineRequest,
+        images: &[String],
+        dims: Option<&ResolvedDims>,
+        mut on_section: impl FnMut(crate::ai_refine_protocol::AiRefineSection),
+    ) -> Result<AiRefineResponse, AiClientError> {
+        use crate::ai_refine_protocol::parse_section_ndjson_line;
+
+        let mut system = self.prompt.build_system(&request.profile, dims);
+        system.push_str("\n\n");
+        system.push_str(crate::ai_refine_protocol::NDJSON_SYSTEM_SUFFIX);
+        // REQ-290② 预算（与 refine_vision 同口径——流式不豁免上限）
+        let budget = crate::refine_budget::output_budget(
+            dims.map(|d| d.preset_id.as_str()).unwrap_or("standard"),
+            request.content.chars().count(),
+        );
+        let user = serde_json::to_string(request)
+            .map_err(|e| AiClientError::Parse(format!("精修请求序列化失败: {}", e)))?;
+        let payload = if images.is_empty() {
+            crate::ai_client::build_chat_payload(
+                &self.client.config.model, &system, &user, budget.max_tokens,
+            )
+        } else {
+            crate::ai_client::build_vision_payload(
+                &self.client.config.model, &system, &user, images, budget.max_tokens,
+            )
+        };
+        let mut sections: Vec<crate::ai_refine_protocol::AiRefineSection> = Vec::new();
+        let mut pending = String::new();
+        let outcome = crate::ai_chat_stream::stream_sse_content(
+            &self.client,
+            payload,
+            |delta| {
+                pending.push_str(delta);
+                while let Some(pos) = pending.find('\n') {
+                    let line: String = pending.drain(..=pos).collect();
+                    if let Some(sec) = parse_section_ndjson_line(&line) {
+                        sections.push(sec.clone());
+                        on_section(sec);
+                    }
+                }
+            },
+        )?;
+        // 末行无换行（SSE 结束前 flush）
+        if let Some(sec) = parse_section_ndjson_line(&pending) {
+            sections.push(sec.clone());
+            on_section(sec);
+        }
+        let _ = outcome.content;
+        if sections.is_empty() {
+            return Err(AiClientError::Parse(
+                "流式响应未解析出章节（模型未按逐节输出——回退非流式）".to_string(),
+            ));
+        }
+        Ok(crate::ai_refine_protocol::AiRefineResponse {
+            schema_version: crate::ai_refine_protocol::SCHEMA_VERSION_V2,
+            sections,
+        })
+    }
 }
 
 /// 单测独立文件（保持本文件 ≤300 行，AGENTS.md §3）。

app/src-tauri/src/ai_refine_protocol.rs

@@ -193,45 +193,70 @@ impl AiRefineResponse {
     ///              image=原样配图行 `- ![画面](path)`（F3 v2——与规则版
     ///              画面要点行同形态，前端渲染器统一处理）。
     pub fn to_markdown(&self) -> String {
-        let mut out = String::new();
-        for sec in &self.sections {
-            out.push_str(&format!("## {}\n\n", sec.heading.trim()));
-            for b in &sec.blocks {
-                match b.block_type {
-                    AiRefineBlockType::Paragraph => {
-                        out.push_str(b.content.trim());
-                        out.push_str("\n\n");
-                    }
-                    AiRefineBlockType::List => {
-                        for line in b.content.lines().map(|l| l.trim()).filter(|l| !l.is_empty()) {
-                            out.push_str(&format!("- {}\n", line));
-                        }
-                        out.push('\n');
-                    }
-                    AiRefineBlockType::Term => {
-                        out.push_str(&format!("- **{}**\n", b.content.trim()));
-                    }
-                    AiRefineBlockType::Highlight => {
-                        out.push_str(&format!("**{}**\n\n", b.content.trim()));
-                    }
-                    AiRefineBlockType::Quote => {
-                        for line in b.content.lines().map(|l| l.trim()).filter(|l| !l.is_empty()) {
-                            out.push_str(&format!("> {}\n", line));
-                        }
-                        out.push('\n');
+        render_sections(&self.sections).trim().to_string()
+    }
+}
+
+/// 章节序列 → Markdown（纯函数；to_markdown 与流式 Delta 渲染共用同一出口——
+/// REQ-290① 增量帧按前缀渲染，文本与终稿逐字节一致）。
+pub fn render_sections(sections: &[AiRefineSection]) -> String {
+    let mut out = String::new();
+    for sec in sections {
+        out.push_str(&format!("## {}\n\n", sec.heading.trim()));
+        for b in &sec.blocks {
+            match b.block_type {
+                AiRefineBlockType::Paragraph => {
+                    out.push_str(b.content.trim());
+                    out.push_str("\n\n");
+                }
+                AiRefineBlockType::List => {
+                    for line in b.content.lines().map(|l| l.trim()).filter(|l| !l.is_empty()) {
+                        out.push_str(&format!("- {}\n", line));
                     }
-                    AiRefineBlockType::Image => {
-                        // F3 v2：配图行（content=session-images/{sid}/{rel}——
-                        // 原样输出；与规则版画面要点行同形态供前端渲染）
-                        out.push_str(&format!("- ![画面]({})\n", b.content.trim()));
+                    out.push('\n');
+                }
+                AiRefineBlockType::Term => {
+                    out.push_str(&format!("- **{}**\n", b.content.trim()));
+                }
+                AiRefineBlockType::Highlight => {
+                    out.push_str(&format!("**{}**\n\n", b.content.trim()));
+                }
+                AiRefineBlockType::Quote => {
+                    for line in b.content.lines().map(|l| l.trim()).filter(|l| !l.is_empty()) {
+                        out.push_str(&format!("> {}\n", line));
                     }
+                    out.push('\n');
+                }
+                AiRefineBlockType::Image => {
+                    // F3 v2：配图行（content=session-images/{sid}/{rel}——
+                    // 原样输出；与规则版画面要点行同形态供前端渲染）
+                    out.push_str(&format!("- ![画面]({})\n", b.content.trim()));
                 }
             }
         }
-        out.trim().to_string()
     }
+    out
 }
 
+/// 单行 NDJSON 节解析（REQ-290① 流式）：每节=与终稿数组元素同构的 JSON 对象
+/// （heading + blocks）；非对象行/解析失败 → None（由上层按整包回退解析）。
+pub fn parse_section_ndjson_line(line: &str) -> Option<AiRefineSection> {
+    let t = line.trim();
+    if t.is_empty() || t.starts_with('[') || t.starts_with(']') || t.starts_with(',') {
+        return None;
+    }
+    let v: serde_json::Value = serde_json::from_str(t).ok()?;
+    let obj = v.as_object()?;
+    if !obj.contains_key("heading") || !obj.contains_key("blocks") {
+        return None;
+    }
+    serde_json::from_value::<AiRefineSection>(v).ok()
+}
+
+/// 流式模式输出要求（附加在 system 尾部——逐节 JSONL；无法遵守时整体 JSON
+/// 数组亦可——解析端自动兼容回退，见 adapter）。
+pub const NDJSON_SYSTEM_SUFFIX: &str = "【流式输出要求】请逐节输出整理结果：每一节单独输出一行 JSON（对象含 heading 与 blocks 字段，字段格式与前述格式要求完全一致），节与节之间只换行、不写数组括号/逗号/多余说明；若必须一次性输出，则输出完整 JSON 数组（系统可自动兼容解析）。";
+
 /// 单测独立文件（保持本文件 ≤300 行，AGENTS.md §3）。
 #[cfg(test)]
 #[path = "ai_refine_protocol_tests.rs"]
@@ -241,3 +266,30 @@ mod tests;
 #[cfg(test)]
 #[path = "refine_golden_tests.rs"]
 mod golden_tests;
+
+#[cfg(test)]
+mod ndjson_parse_tests {
+    use super::parse_section_ndjson_line;
+
+    #[test]
+    fn parses_single_section_object_line() {
+        let line = r#"{"heading":"第一节","blocks":[]}"#;
+        let sec = parse_section_ndjson_line(line).expect("应解析出节");
+        assert_eq!(sec.heading, "第一节");
+        assert!(sec.blocks.is_empty());
+    }
+
+    #[test]
+    fn ignores_array_wrappers_and_empty_lines() {
+        assert!(parse_section_ndjson_line("[").is_none());
+        assert!(parse_section_ndjson_line("]").is_none());
+        assert!(parse_section_ndjson_line(",").is_none());
+        assert!(parse_section_ndjson_line("  ").is_none());
+    }
+
+    #[test]
+    fn ignores_non_section_objects_and_garbage() {
+        assert!(parse_section_ndjson_line(r#"{"a":1}"#).is_none());
+        assert!(parse_section_ndjson_line("not json {").is_none());
+    }
+}

app/src-tauri/src/ai_refine_task.rs

@@ -45,6 +45,9 @@ pub enum RefineStreamFrame {
     Progress { slice_index: usize, slice_total: usize },
     /// 该片精修结果（validate 通过后的渲染 markdown——逐章正文流出）
     BlockDone { slice_index: usize, markdown: String },
+    /// REQ-290①：片内流式增量（NDJSON 逐节解析即推——打字机正文；text=节渲染
+    /// 的 markdown 片段，同片内按到达序拼接；终稿以 BlockDone 为准）
+    Delta { slice_index: usize, text: String },
     /// 该片失败（回退纯规则语义——诚实降级提示）
     SliceFailed { slice_index: usize, reason: String },
     /// 任务终态（全部片合并完成）
@@ -510,6 +513,7 @@ pub(crate) fn refine_slices_concurrent(ctx: RefineCtx<'_>) -> (Vec<String>, usiz
             let mock_adapter = ctx.mock_adapter;
             let mock = ctx.mock;
             let task_id = ctx.task_id;
+            let st = ctx.st; // REQ-290①：流式 Delta 帧推送（worker 线程内 emit）
             let profile = ctx.profile; // 轨迹 system 提示词构建用（模板分组同请求）
             let vision_images = ctx.vision_images;
             let dims = ctx.dims; // 策略解析结果（worker 只读共享）
@@ -524,11 +528,55 @@ pub(crate) fn refine_slices_concurrent(ctx: RefineCtx<'_>) -> (Vec<String>, usiz
                 let mut outcome: Option<String> = None;
                 for attempt in 0..=SLICE_RETRY {
                     // REQ-290（v0.19.6）埋点先行：单片耗时归因——任务级 elapsed_ms
-                    // 已有（db_ai_tasks），此处补片级时间（非流式阶段只有总耗时；
-                    // 流式上线后同点补首 delta 时刻，见批次设计 §2.8 ③）。
+                    // 已有（db_ai_tasks），此处补片级时间（含流式整包耗时口径）。
                     let started = std::time::Instant::now();
+                    // REQ-290①（v0.19.7）：首拍（attempt 0）优先流式（NDJSON 逐节，
+                    // 解析一节推一节 Delta——打字机正文）；流式不可用/模型未遵守
+                    // 逐节约定 → 同拍回退非流式（与旧版逐字节一致）；重试拍走非
+                    // 流式（幂等语义下不重复推流）。
+                    let stream_enabled = !mock
+                        && attempt == 0
+                        && std::env::var("REFINE_STREAM_NDJSON")
+                            .map(|v| v != "0")
+                            .unwrap_or(true);
                     let resp = if mock {
                         Ok(mock_adapter.refine(req))
+                    } else if stream_enabled {
+                        match adapter
+                            .refine_stream_ndjson(
+                                req,
+                                ctx.vision_images,
+                                Some(dims),
+                                |sec| {
+                                    emit_refine_stream(
+                                        st,
+                                        task_id,
+                                        RefineStreamFrame::Delta {
+                                            slice_index: idx + 1,
+                                            text: crate::ai_refine_protocol::render_sections(
+                                                std::slice::from_ref(&sec),
+                                            ),
+                                        },
+                                    );
+                                },
+                            )
+                            .map_err(AiTaskFailure::from)
+                        {
+                            Ok(r) => Ok(r),
+                            Err(e) => {
+                                eprintln!(
+                                    "[refine-task] task={} 片 {} 流式不可用，同拍回退非流式: {}",
+                                    task_id, idx + 1, e.message()
+                                );
+                                if ctx.vision_images.is_empty() {
+                                    adapter.refine(req, Some(dims)).map_err(AiTaskFailure::from)
+                                } else {
+                                    adapter
+                                        .refine_vision(req, ctx.vision_images, Some(dims))
+                                        .map_err(AiTaskFailure::from)
+                                }
+                            }
+                        }
                     } else if ctx.vision_images.is_empty() {
                         adapter.refine(req, Some(dims)).map_err(AiTaskFailure::from)
                     } else {

app/src/components/TaskThreadCard.test.tsx

@@ -14,7 +14,7 @@ import type { AiTaskRecord } from "../types";
 // v0.17.0：流式 hook 依赖 tauri event listen——测试环境 mock 为空流（不报错）
 vi.mock("../hooks/useRefineStream", () => ({
   useRefineStream: () => [],
-  orderedBlockFrames: () => [],
+  sliceStreamContent: () => [],
 }));
 
 function task(partial: Partial<AiTaskRecord> & { taskId: number }): AiTaskRecord {

app/src/components/TaskThreadCard.tsx

@@ -10,7 +10,8 @@
  *              [回到会话] [查看笔记]（用户裁决：完成后快速闭环）。
  */
 import type { AiTaskRecord } from "../types";
-import { orderedBlockFrames, useRefineStream } from "../hooks/useRefineStream";
+// REQ-290①（v0.19.7）：delta 逐节增量并入片正文（打字机）；blockDone 收尾
+import { sliceStreamContent, useRefineStream } from "../hooks/useRefineStream";
 
 interface Props {
   tasks: AiTaskRecord[];
@@ -51,26 +52,29 @@ function recentDone(tasks: AiTaskRecord[]): AiTaskRecord | null {
 /** 精修流式正文（进行中任务卡内——逐章流出；无帧则仅进度行） */
 function RefineStreamBody({ taskId, total }: { taskId: number; total: number | null }) {
   const frames = useRefineStream(taskId);
-  const blocks = orderedBlockFrames(frames);
+  const slices = sliceStreamContent(frames);
   const doneFrames = frames.filter((f) => f.kind === "done").length;
   const failedCount = frames.filter((f) => f.kind === "sliceFailed").length;
-  if (blocks.length === 0 && frames.length === 0) return null;
+  const streamingLive = slices.some((s) => !s.complete && s.text.length > 0);
+  if (slices.length === 0 && frames.length === 0) return null;
   return (
     <div style={{ width: "100%", marginTop: 4, borderTop: "1px dashed #e5e7eb", paddingTop: 4 }}>
       <div style={{ fontSize: 10.5, color: "#9ca3af", marginBottom: 2 }}>
-        已整理 {blocks.length}/{total ?? "?"} 片{failedCount > 0 && ` · 失败 ${failedCount} 片（保留规则版）`}
+        已整理 {slices.filter((s) => s.complete).length}/{total ?? "?"} 片{failedCount > 0 && ` · 失败 ${failedCount} 片（保留规则版）`}
+        {streamingLive && " · 逐节流出中"}
         {doneFrames > 0 && " · 完成"}
       </div>
-      {blocks.map((b) => (
+      {slices.map((s) => (
         <pre
-          key={b.sliceIndex}
+          key={s.sliceIndex}
           style={{
             whiteSpace: "pre-wrap", wordBreak: "break-word", fontFamily: "inherit",
             fontSize: 11.5, color: "#374151", margin: 0, padding: "2px 0",
-            borderTop: b.sliceIndex > 1 ? "1px solid #f3f4f6" : "none",
+            borderTop: s.sliceIndex > 1 ? "1px solid #f3f4f6" : "none",
           }}
         >
-          {b.markdown}
+          {s.text}
+          {!s.complete && s.text.length > 0 ? " ▍" : ""}
         </pre>
       ))}
     </div>