修复: read_file 可靠性 + obscura 渲染(压缩豁免 + UTF-16 闭环 + stdout 救回)

read_file 压缩豁免(AI 定向读代码不折叠)+ UTF-16 BOM 闭环(read_file/read_symbol/patch_file);
obscura 非零退出码救回 stdout + fetch markdown 空壳 fallback scrape --eval + 探测日志。

src-tauri/src/commands/ai/fetch_url.rs

@@ -59,6 +59,11 @@ const OBSCURA_TIMEOUT_SECS: u64 = 45;
 /// obscura 未安装时的引导提示。回退静态管线后通过返回 JSON 的 `hint` 字段透传给 LLM/用户。
 const OBSCURA_HINT: &str = "obscura 未安装,已用静态模式。装 obscura(Rust 无头浏览器,自带 V8)可增强 JS 渲染文档(SPA/反爬):见 github.com/h4ckf0r0day/obscura";
 
+/// 二进制响应(含 \0)拒绝错误消息。引导式:明示改用 download_file 工具下载文件,
+/// 让 AI 看到错误即知换工具(治会话 01f05167:fetch_url 拒二进制 + run_command curl 失败 → 卡死)。
+const BINARY_REJECT_MSG: &str = "该 URL 返回二进制内容(图片/压缩包/文件等),fetch_url 只读 HTML 文档;\
+     如需下载文件请改用 download_file 工具(支持任意文件类型,含图片/二进制/文档)";
+
 /// fetch_url 工具 handler 入口(供 tools/fetch_url.rs register 调用)。
 ///
 /// 参数:
@@ -192,9 +197,12 @@ async fn fetch_static(
             total_bytes, MAX_HTML_BYTES
         );
     }
-    // 含 \0 → 二进制(非 HTML),直接拒(PDF/图片等走专用工具,fetch_url 只处理文本网页)
+    // 含 \0 → 二进制(非 HTML),直接拒(PDF/图片等走专用工具,fetch_url 只处理文本网页)。
+    // 错误文案引导式:明示改用 download_file(支持任意文件类型,图片/压缩包/二进制均可下载),
+    // 让 AI 看到错误即知换工具,避免卡死在 fetch_url / run_command curl 死循环(实测会话 01f05167)。
+    // 错误消息抽为 const 便于单元测试断言(无需真实网络/含 \0 响应即可验证引导文案)。
     if bytes.contains(&0u8) {
-        anyhow::bail!("响应为二进制(非 HTML 文本),fetch_url 仅处理网页文档");
+        anyhow::bail!("{}", BINARY_REJECT_MSG);
     }
     let html = String::from_utf8_lossy(&bytes).into_owned();
 
@@ -236,7 +244,16 @@ async fn fetch_static(
 /// 流程:检测 obscura 在 PATH/已知路径 → spawn `obscura fetch --dump markdown <URL>`(带超时)
 /// → 取 stdout → 截断 → 返回与静态管线同构的 JSON(render_mode=obscura)。
 ///
-/// 任何环节失败(未装 / spawn 失败 / 非零退出 / 超时)都不向上抛,而是回退静态管线:
+/// ## 两次尝试的鲁棒性(缺陷 3+4)
+///
+/// - **缺陷 3**:obscura 非零退出码时不直接回退——先看 stdout 是否仍有实质内容(V8 watchdog
+///   kill 时 exit≠0 但 stdout 可能已加载大部分内容),有则用 partial 标记,无才回退。
+/// - **缺陷 4**:`fetch --dump markdown` 对 JS 重的 SPA(如 Next.js hydration)可能输出空壳
+///   (watchdog kill 在 dump 前)。此时自动 fallback 再试 `scrape --eval "document.body.innerText"`
+///   ——后者走不同管线(innerText 纯文本,不等 JS 全执行完),对 SPA 更鲁棒。
+///   两次都空壳/无实质内容才回退静态管线。
+///
+/// 任何环节最终失败(未装 / spawn 失败 / 两次都超时 / 都空壳)都不向上抛,而是回退静态管线:
 /// 内部调 fetch_static 拿结果,塞 hint 字段提示装 obscura。这样 render=true 在任何环境
 /// 都不会因 obscura 缺失/故障而让工具整体失败(引导式安装的核心保证)。
 async fn fetch_with_obscura(url_raw: &str, max_length: usize) -> anyhow::Result<Value> {
@@ -255,26 +272,25 @@ async fn fetch_with_obscura(url_raw: &str, max_length: usize) -> anyhow::Result<
         }
     };
 
-    // ── spawn obscura(带进程级超时) ──
-    // obscura fetch --dump markdown <URL>:obscura 内部管 page load timeout(默认 30s),
-    // 我们外加 tokio timeout 兜底 V8 启动/JIT 卡死等 obscura 自身超时管不到的场景。
-    let mut cmd = tokio::process::Command::new(&obscura_path);
-    cmd.args(["fetch", "--dump", "markdown", url_raw])
-        .stdout(std::process::Stdio::piped())
-        .stderr(std::process::Stdio::piped());
-    // CREATE_NO_WINDOW:防 obscura spawn 弹控制台窗口闪烁(对齐 shell.rs build_command)。
-    #[cfg(windows)]
-    {
-        use std::os::windows::process::CommandExt;
-        cmd.creation_flags(0x0800_0000);
-    }
-
-    let output = match tokio::time::timeout(
-        Duration::from_secs(OBSCURA_TIMEOUT_SECS),
-        cmd.output(),
-    ).await {
-        Ok(Ok(o)) => o,
-        Ok(Err(e)) => {
+    // ── 第 1 次尝试:fetch --dump markdown(输出结构 markdown,优先) ──
+    // obscura 内部管 page load timeout(默认 30s),我们外加 tokio timeout 兜底 V8 启动/JIT
+    // 卡死等 obscura 自身超时管不到的场景。
+    match run_obscura(&obscura_path, &["fetch", "--dump", "markdown", url_raw]).await {
+        ObscuraRunResult::Markdown(md) => {
+            return Ok(build_obscura_json(url_raw, &md, max_length, started, "obscura", None));
+        }
+        ObscuraRunResult::Partial(md) => {
+            // 缺陷 3:非零退出码但 stdout 有实质内容(watchdog 截断)→ 用 partial 结果,不回退。
+            return Ok(build_obscura_json(
+                url_raw,
+                &md,
+                max_length,
+                started,
+                "obscura_partial",
+                Some("obscura 非零退出(可能 watchdog 截断),已用部分渲染结果"),
+            ));
+        }
+        ObscuraRunResult::SpawnFailed(e) => {
             tracing::warn!("obscura spawn 失败({}),回退静态", e);
             let mut fallback = fetch_static(url_raw, max_length, DEFAULT_TIMEOUT_SECS, &Value::Null).await?;
             fallback["render_mode"] = json!("obscura_failed");
@@ -282,44 +298,198 @@ async fn fetch_with_obscura(url_raw: &str, max_length: usize) -> anyhow::Result<
             fallback["elapsed_ms"] = json!(started.elapsed().as_millis() as u64);
             return Ok(fallback);
         }
-        Err(_) => {
-            tracing::warn!("obscura 超时({}s),回退静态", OBSCURA_TIMEOUT_SECS);
+        ObscuraRunResult::Timeout => {
+            tracing::warn!("obscura fetch 超时({}s),改试 scrape --eval", OBSCURA_TIMEOUT_SECS);
+            // 超时也走 scrape --eval 兜底(scraper 管线不同,可能更快返回)。
+        }
+        ObscuraRunResult::EmptyShell => {
+            // 缺陷 4:fetch markdown 空壳 → fallback scrape --eval。
+            tracing::info!("obscura fetch --dump markdown 空壳/无实质内容,改用 scrape --eval(innerText)");
+        }
+    }
+
+    // ── 第 2 次尝试:scrape --eval(输出 innerText 纯文本,对 SPA 鲁棒,缺陷 4) ──
+    match run_obscura(
+        &obscura_path,
+        &["scrape", "--eval", "document.body.innerText", url_raw],
+    )
+    .await
+    {
+        ObscuraRunResult::Markdown(md) | ObscuraRunResult::Partial(md) => {
+            // scrape --eval 拿到内容:innerText 纯文本无 markdown 结构,但能拿到正文。
+            return Ok(build_obscura_json(
+                url_raw,
+                &md,
+                max_length,
+                started,
+                "obscura_scrape_eval",
+                Some("obscura fetch markdown 空壳,改用 innerText 纯文本"),
+            ));
+        }
+        ObscuraRunResult::SpawnFailed(e) => {
+            tracing::warn!("obscura scrape spawn 失败({}),回退静态", e);
             let mut fallback = fetch_static(url_raw, max_length, DEFAULT_TIMEOUT_SECS, &Value::Null).await?;
             fallback["render_mode"] = json!("obscura_failed");
-            fallback["hint"] = json!(format!("obscura 渲染超时({}s),已用静态模式。{}", OBSCURA_TIMEOUT_SECS, OBSCURA_HINT));
+            fallback["hint"] = json!(format!("obscura 启动失败({}),已用静态模式。{}", e, OBSCURA_HINT));
             fallback["elapsed_ms"] = json!(started.elapsed().as_millis() as u64);
             return Ok(fallback);
         }
-    };
-
-    if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        tracing::warn!("obscura 非零退出({}),stderr: {}", output.status, stderr.trim());
-        let mut fallback = fetch_static(url_raw, max_length, DEFAULT_TIMEOUT_SECS, &Value::Null).await?;
-        fallback["render_mode"] = json!("static_fallback");
-        fallback["hint"] = json!(format!("obscura 渲染失败(exit {}),已用静态模式。{}", output.status, OBSCURA_HINT));
-        fallback["elapsed_ms"] = json!(started.elapsed().as_millis() as u64);
-        return Ok(fallback);
+        ObscuraRunResult::Timeout => {
+            tracing::warn!("obscura scrape --eval 也超时({}s),回退静态", OBSCURA_TIMEOUT_SECS);
+        }
+        ObscuraRunResult::EmptyShell => {
+            tracing::warn!("obscura scrape --eval 也无实质内容,回退静态");
+        }
     }
 
-    // ── 取 stdout(已是 markdown) ──
-    let mut markdown = String::from_utf8_lossy(&output.stdout).into_owned();
-    // obscura 偶发在 markdown 前后带空白/日志行,trim 首尾;内部仍走 cleanup 折叠空行。
-    markdown = cleanup_markdown(markdown.trim());
-    let html_bytes_est = markdown.len(); // obscura 不给原始 HTML 字节数,用 markdown 长度近似(仅信息字段)
+    // ── 两次都失败/空壳:回退静态管线 ──
+    let mut fallback = fetch_static(url_raw, max_length, DEFAULT_TIMEOUT_SECS, &Value::Null).await?;
+    fallback["render_mode"] = json!("static_fallback");
+    fallback["hint"] = json!(format!(
+        "obscura 渲染失败(fetch markdown 与 scrape --eval 均无实质内容),已用静态模式。{}",
+        OBSCURA_HINT
+    ));
+    fallback["elapsed_ms"] = json!(started.elapsed().as_millis() as u64);
+    Ok(fallback)
+}
 
+/// obscura 单次执行结果(供 fetch_with_obscura 判定 partial/空壳/失败)。
+///
+/// - `Markdown`:退出码 0 且 stdout 有实质内容(正常成功)。
+/// - `Partial`:非零退出码但 stdout 仍有实质内容(缺陷 3:watchdog kill 截断,内容已部分加载)。
+/// - `EmptyShell`:stdout 无实质内容(空 / 纯框架标签 / 极短)。caller 应尝试别的管线或回退。
+/// - `Timeout`:超过 OBSCURA_TIMEOUT_SECS 被杀。
+/// - `SpawnFailed`:spawn 本身失败(obscura 二进制损坏等)。
+enum ObscuraRunResult {
+    Markdown(String),
+    Partial(String),
+    EmptyShell,
+    Timeout,
+    SpawnFailed(String),
+}
+
+/// spawn obscura 带指定子命令参数,带进程级超时,返回 stdout 内容分类。
+///
+/// fetch --dump markdown 与 scrape --eval 共用此 helper(同样的 spawn 装配 + 超时 + 实质内容判定),
+/// 保证两条管线鲁棒性一致、且都带 CREATE_NO_WINDOW(防弹窗)。
+async fn run_obscura(obscura_path: &str, args: &[&str]) -> ObscuraRunResult {
+    let mut cmd = tokio::process::Command::new(obscura_path);
+    cmd.args(args)
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped());
+    // CREATE_NO_WINDOW:防 obscura spawn 弹控制台窗口闪烁(对齐 shell.rs build_command)。
+    #[cfg(windows)]
+    {
+        cmd.creation_flags(0x0800_0000);
+    }
+
+    let output = match tokio::time::timeout(
+        Duration::from_secs(OBSCURA_TIMEOUT_SECS),
+        cmd.output(),
+    )
+    .await
+    {
+        Ok(Ok(o)) => o,
+        Ok(Err(e)) => return ObscuraRunResult::SpawnFailed(format!("{}", e)),
+        Err(_) => return ObscuraRunResult::Timeout,
+    };
+
+    let success = output.status.success();
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    if !success {
+        // 保留原 :297 的 stderr warn 日志(诊断 obscura 非零退出原因)。
+        tracing::warn!("obscura 非零退出({}),stderr: {}", output.status, stderr.trim());
+    }
+
+    // obscura 偶发在 stdout 前后带空白/日志行,trim 首尾;内部仍走 cleanup 折叠空行。
+    let markdown = cleanup_markdown(String::from_utf8_lossy(&output.stdout).trim());
+
+    if has_substantial_content(&markdown) {
+        if success {
+            ObscuraRunResult::Markdown(markdown)
+        } else {
+            // 缺陷 3:非零退出码但有实质内容(watchdog 截断)。
+            ObscuraRunResult::Partial(markdown)
+        }
+    } else {
+        ObscuraRunResult::EmptyShell
+    }
+}
+
+/// 判定 obscura stdout 是否有实质内容(缺陷 3+4 共用)。
+///
+/// 用于区分:watchdog kill 时 stdout 已加载大部分内容(可用 partial)vs SPA 空壳(无可读正文)。
+/// 判定规则(层层剔除空壳形态):
+/// 1. trim 后 <500 chars → 无实质内容(空/极短)。
+/// 2. 从原文移除常见空壳骨架(`<div id=root></div>` 等 hydration 占位标签)。
+/// 3. 从剩余文本移除占位词(loading / please enable javascript / 404 / not found 等)。
+/// 4. 剔除后剩余「非空白字符」<200 → 判空壳(原文虽长但全是占位骨架/占位词)。
+/// 真实正文即使在 watchdog 截断后,也会保留大量非占位正文 char → 通过。
+fn has_substantial_content(md: &str) -> bool {
+    let trimmed = md.trim();
+    if trimmed.chars().count() < 500 {
+        return false;
+    }
+    let lower = trimmed.to_lowercase();
+    // 第 2 步:移除空壳骨架标签(hydration 占位)。
+    let shell_markers = [
+        "<div id=\"root\"></div>",
+        "<div id=root></div>",
+        "<div id=\"app\"></div>",
+        "<div id=app></div>",
+        "<noscript>",
+        "</noscript>",
+    ];
+    let mut stripped: String = lower.clone();
+    for marker in shell_markers {
+        stripped = stripped.replace(marker, "");
+    }
+    // 第 3 步:移除占位词(空壳站点常常只有这类文案)。
+    for placeholder in [
+        "loading",
+        "please wait",
+        "please enable javascript",
+        "enable javascript",
+        "enable js",
+        "javascript is required",
+        "404",
+        "not found",
+        "page not found",
+    ] {
+        stripped = stripped.replace(placeholder, "");
+    }
+    // 第 4 步:剩余「有效字符」(非空白且非纯标点 .,!?:; 等)<200 → 判空壳。
+    // 标点不计入有效内容:Loading... 去掉 loading 后剩 ... 是空壳残留标点,非正文。
+    let non_ws_chars: usize = stripped
+        .chars()
+        .filter(|c| !c.is_whitespace() && !matches!(c, '.' | ',' | '!' | '?' | ':' | ';' | '-' | '_' | '|' | '*' | '#' | '<' | '>' | '/' | '=' | '"' | '\''))
+        .count();
+    non_ws_chars >= 200
+}
+
+/// 组装 obscura 成功路径 JSON(三种 render_mode:obscura / obscura_partial / obscura_scrape_eval)。
+///
+/// 抽出共用:三种成功路径(正常/partial/scrape_eval)的 JSON 结构除 render_mode 与 hint
+/// 外完全一致(同样从 markdown 启发式取 title、截断、算 length/html_bytes_est)。
+fn build_obscura_json(
+    url_raw: &str,
+    markdown_raw: &str,
+    max_length: usize,
+    started: Instant,
+    render_mode: &str,
+    hint: Option<&str>,
+) -> Value {
+    let html_bytes_est = markdown_raw.len(); // obscura 不给原始 HTML 字节数,用 markdown 长度近似(仅信息字段)
     // 截断(按 char 边界,与静态一致)
-    let (markdown, truncated) = truncate_chars(&markdown, max_length);
+    let (markdown, truncated) = truncate_chars(markdown_raw, max_length);
     let elapsed_ms = started.elapsed().as_millis() as u64;
-
-    // title:obscura --dump markdown 不单独给 title,从 markdown 首个 H1/首行启发式取;取不到则 null。
     let title = extract_title_from_markdown(&markdown);
     // scheme:obscura 路径下重新 validate_url 拿 scheme(已在入口校验过,这里仅取字段值,失败兜底 https)。
     let scheme = crate::commands::ai::http::validate_url(url_raw)
         .map(|(s, _, _)| s)
         .unwrap_or_else(|_| "https".to_string());
 
-    Ok(json!({
+    let mut v = json!({
         "url": url_raw,
         "scheme": scheme,
         "status": 200u16, // obscura 成功路径不暴露 HTTP status(已渲染),用 200 占位
@@ -329,14 +499,20 @@ async fn fetch_with_obscura(url_raw: &str, max_length: usize) -> anyhow::Result<
         "html_bytes": html_bytes_est,
         "truncated": truncated,
         "elapsed_ms": elapsed_ms,
-        "render_mode": "obscura",
-    }))
+        "render_mode": render_mode,
+    });
+    if let Some(h) = hint {
+        v["hint"] = json!(h);
+    }
+    v
 }
 
 /// 检测 obscura 是否已安装且可执行。优先级:PATH > 已知 npm-global 路径。
 ///
 /// 用 `obscura --version` 探活(比 `which` 跨平台:Windows 无 which,且 --version 能确认
-/// 二进制可跑而非仅存在)。同步探活带 5s 超时防卡(对齐 module.rs::run_command 的 thread+channel 风格)。
+/// 二进制可跑而非仅存在)。同步探活带 15s 超时防卡(对齐 module.rs::run_command 的 thread+channel 风格)。
+/// 探活结果全程 tracing 日志(debug:每个 candidate 尝试/exit/超时;warn:全部失败列出试过的路径),
+/// 让 Tauri 进程 PATH 与 PowerShell 不同导致的间歇性失败可诊断。
 fn find_obscura() -> Option<String> {
     let candidates: &[&str] = &[
         "obscura", // PATH 优先(用户 npm i -g 后即在 PATH)
@@ -345,7 +521,9 @@ fn find_obscura() -> Option<String> {
         "D:\\NodeJS\\npm-global\\obscura.exe", // Windows 原生路径(tauri 在 Windows 跑)
     ];
 
+    let mut tried: Vec<&str> = Vec::with_capacity(candidates.len());
     for cand in candidates {
+        tracing::debug!("obscura 探测尝试 candidate: {}", cand);
         let (tx, rx) = std::sync::mpsc::channel();
         let cand_owned = cand.to_string();
         std::thread::spawn(move || {
@@ -363,10 +541,25 @@ fn find_obscura() -> Option<String> {
             let _ = tx.send(out);
         });
         match rx.recv_timeout(Duration::from_secs(15)) {
-            Ok(Ok(o)) if o.status.success() => return Some(cand.to_string()),
-            _ => continue,
+            Ok(Ok(o)) if o.status.success() => {
+                tracing::debug!("obscura 探测命中 candidate: {}", cand);
+                return Some(cand.to_string());
+            }
+            Ok(Ok(o)) => {
+                tracing::debug!("obscura 探测失败 candidate={}, exit={}", cand, o.status);
+                tried.push(cand);
+            }
+            Ok(Err(e)) => {
+                tracing::debug!("obscura 探测 spawn 失败 candidate={}, err={}", cand, e);
+                tried.push(cand);
+            }
+            Err(_) => {
+                tracing::debug!("obscura 探测超时(15s) candidate={}", cand);
+                tried.push(cand);
+            }
         }
     }
+    tracing::warn!("obscura 所有 candidate 探测失败,试过: {:?}", tried);
     None
 }
 
@@ -480,6 +673,21 @@ fn truncate_chars(md: &str, max: usize) -> (String, bool) {
 mod tests {
     use super::*;
 
+    // ── 二进制拒绝错误文案(引导式:含 download_file 提示) ──
+    // 治会话 01f05167:fetch_url 拒二进制后 AI 不知换工具,卡死在 run_command curl。
+    // 错误消息必须明示 download_file,让 AI 看到错误即换工具。纯 const 断言零网络零依赖。
+
+    #[test]
+    fn test_binary_reject_msg_guides_to_download_file() {
+        // 错误消息必须含 download_file 工具名(引导换工具的核心)
+        assert!(BINARY_REJECT_MSG.contains("download_file"));
+        // 必须明示 fetch_url 只读 HTML(让 AI 理解为何被拒)
+        assert!(BINARY_REJECT_MSG.contains("HTML"));
+        // 必须提及图片/二进制等关键词(匹配 AI 触发场景:用户给 .png URL)
+        assert!(BINARY_REJECT_MSG.contains("二进制"));
+        assert!(BINARY_REJECT_MSG.contains("图片"));
+    }
+
     // ── extract_title ──
 
     #[test]
@@ -603,6 +811,150 @@ mod tests {
         assert!(!out.contains('\u{FFFD}'));
     }
 
+    // ── has_substantial_content(缺陷 3+4 共用判定) ──
+
+    #[test]
+    fn test_substantial_content_real_markdown_passes() {
+        // 真实正文:600 chars,无空壳标记,应判有实质内容
+        let md = "# 异步编程指南\n\n这是一篇关于 Rust 异步编程的详细指南。\n".repeat(15);
+        assert!(has_substantial_content(&md));
+    }
+
+    #[test]
+    fn test_substantial_content_short_returns_false() {
+        // <500 chars → 无实质内容
+        assert!(!has_substantial_content("short content only"));
+        assert!(!has_substantial_content(""));
+        assert!(!has_substantial_content("   \n\n  "));
+    }
+
+    #[test]
+    fn test_substantial_content_empty_shell_root_div_rejected() {
+        // SPA hydration 空壳典型:仅 <div id="root"></div> + 大量空白填充到 >500 chars
+        let padding = " ".repeat(600);
+        let shell = format!("<div id=\"root\"></div>\n{}", padding);
+        assert!(!has_substantial_content(&shell));
+    }
+
+    #[test]
+    fn test_substantial_content_empty_shell_app_div_rejected() {
+        // 仅 <div id="app"></div> 空壳
+        let padding = "\n".repeat(600);
+        let shell = format!("<div id=\"app\"></div>{}", padding);
+        assert!(!has_substantial_content(&shell));
+    }
+
+    #[test]
+    fn test_substantial_content_loading_placeholder_rejected() {
+        // 纯 "Loading..." 占位符重复(去掉 "loading" 后仅剩标点/空白)→ 空壳
+        let placeholder = "Loading...\n".repeat(120);
+        assert!(!has_substantial_content(&placeholder));
+    }
+
+    #[test]
+    fn test_substantial_content_enable_js_rejected() {
+        // 纯 "Please enable JavaScript" 占位(去掉占位词后仅剩空白)→ 空壳
+        let placeholder = "Please enable JavaScript\n".repeat(40);
+        assert!(!has_substantial_content(&placeholder));
+    }
+
+    #[test]
+    fn test_substantial_content_mixed_real_content_passes() {
+        // 含真实正文(loading 标题但有正文)→ 应判有实质内容
+        let md = "# Loading data\n\n".to_string()
+            + &"这是真实的正文内容,描述了一篇技术文章的核心要点。".repeat(20);
+        assert!(has_substantial_content(&md));
+    }
+
+    // ── ObscuraRunResult 分类逻辑(缺陷 3:partial 分支) ──
+    //
+    // 注:run_obscura 依赖真实 obscura 二进制 + 网络,此处不直接测 spawn,而是间接验证
+    // has_substantial_content 的判定正确性(它是 run_obscura 内 partial vs emptyshell 的核心)。
+    // 上面 has_substantial_content 测试已覆盖:有实质内容 → Markdown/Partial 分支可命中;
+    // 空壳 → EmptyShell 分支可命中。
+
+    #[test]
+    fn test_obscura_partial_classification_via_substantial_check() {
+        // 模拟 watchdog 截断:obscura 非零退出但 stdout 已加载部分真实内容(>500 chars 正文)。
+        // run_obscura 会判 success=false + has_substantial_content=true → ObscuraRunResult::Partial。
+        let partial_stdout = "# 文章标题\n\n".to_string()
+            + &"这是 watchdog 截断前已加载的部分正文内容,包含真实信息。".repeat(20);
+        // has_substantial_content 是 Partial 分支的唯一判据
+        assert!(has_substantial_content(&partial_stdout));
+    }
+
+    #[test]
+    fn test_obscura_emptyshell_classification_via_substantial_check() {
+        // 模拟 SPA 空壳:obscura 输出仅 hydration 占位 → EmptyShell → 触发 scrape --eval fallback
+        let empty_stdout = format!("<div id=\"root\"></div>\n{}", " ".repeat(600));
+        assert!(!has_substantial_content(&empty_stdout));
+    }
+
+    // ── build_obscura_json(render_mode 三态 + hint) ──
+
+    #[test]
+    fn test_build_obscura_json_normal_mode_no_hint() {
+        let md = "# 标题\n\n正文内容".to_string();
+        let started = Instant::now();
+        let v = build_obscura_json("https://example.com/", &md, 1000, started, "obscura", None);
+        assert_eq!(v["render_mode"].as_str().unwrap(), "obscura");
+        assert_eq!(v["status"].as_u64().unwrap(), 200);
+        assert_eq!(v["url"].as_str().unwrap(), "https://example.com/");
+        assert_eq!(v["title"].as_str().unwrap(), "标题");
+        assert_eq!(v["scheme"].as_str().unwrap(), "https");
+        // hint 字段不存在
+        assert!(v.get("hint").is_none());
+    }
+
+    #[test]
+    fn test_build_obscura_json_partial_mode_with_hint() {
+        // 缺陷 3:obscura_partial render_mode + hint 说明 watchdog 截断
+        let md = "# 截断的标题\n\n".to_string() + &"部分正文。".repeat(50);
+        let started = Instant::now();
+        let v = build_obscura_json(
+            "https://example.com/",
+            &md,
+            10000,
+            started,
+            "obscura_partial",
+            Some("obscura 非零退出(可能 watchdog 截断),已用部分渲染结果"),
+        );
+        assert_eq!(v["render_mode"].as_str().unwrap(), "obscura_partial");
+        let hint = v["hint"].as_str().unwrap();
+        assert!(hint.contains("watchdog"));
+        assert!(hint.contains("部分渲染"));
+    }
+
+    #[test]
+    fn test_build_obscura_json_scrape_eval_mode() {
+        // 缺陷 4:obscura_scrape_eval render_mode + hint 说明改用 innerText
+        let md = "这是 innerText 纯文本正文,无 markdown 结构。".repeat(20);
+        let started = Instant::now();
+        let v = build_obscura_json(
+            "https://example.com/",
+            &md,
+            10000,
+            started,
+            "obscura_scrape_eval",
+            Some("obscura fetch markdown 空壳,改用 innerText 纯文本"),
+        );
+        assert_eq!(v["render_mode"].as_str().unwrap(), "obscura_scrape_eval");
+        let hint = v["hint"].as_str().unwrap();
+        assert!(hint.contains("innerText"));
+        // innerText 无 markdown 结构 → extract_title_from_markdown 走首行 fallback
+        assert!(v["title"].as_str().is_some());
+    }
+
+    #[test]
+    fn test_build_obscura_json_truncation_applies() {
+        // build_obscura_json 内部应走 truncate_chars:超长 markdown 截断标记
+        let md: String = "abcdefghij".repeat(2000); // 20000 chars
+        let started = Instant::now();
+        let v = build_obscura_json("https://example.com/", &md, 1000, started, "obscura", None);
+        assert_eq!(v["truncated"], true);
+        assert!(v["markdown"].as_str().unwrap().contains("[markdown 已截断"));
+    }
+
     // ── handler 参数边界 ──
 
     #[tokio::test]