新增: obscura 安装引导(prompt AI 看 hint 帮装 + 前端工具卡片 AI 帮装按钮)

2026-08-01 18:07:56 +08:00
parent d664bdc309
commit 3afaff9efe
11 changed files with 332 additions and 4 deletions
@@ -126,6 +126,10 @@ fn system_prompt_parts(lang: &str) -> (&'static str, &'static str, &'static str)
 /// - fetch_url = 读文档(URL→markdown,去 HTML 噪声);http_request = 调 API(POST/鉴权/原始响应)
 /// - 不瞎试 URL:先读文档提取端点,再验证;杜绝未读文档即对原始 URL 盲发请求
 ///
+/// 末尾追加 obscura 安装引导子段:fetch_url render=true 未装 obscura 时,结果含
+/// `render_mode=static_fallback` + `hint` 字段(引导链接 github.com/h4ckf0r0day/obscura)。
+/// AI 看到 hint 即自主提示用户「装了能 JS 渲染 SPA/反爬」,征得同意后用 run_command 帮装。
+///
 /// 仅段加在 prefix 末尾(聚焦段后),不破坏现有结构。
 fn doc_exploration_strategy_section(lang: &str) -> &'static str {
    match lang {
@@ -137,7 +141,18 @@ fn doc_exploration_strategy_section(lang: &str) -> &'static str {
                 3. **Extract keys**: pull out base_url, provider_type, auth scheme, model list, endpoint paths — write them down explicitly before calling anything.\n\
                 4. **Verify**: only now use `http_request` against the correct endpoint you extracted (e.g. `GET {base_url}/v1/models` with the auth header) to confirm it works.\n\
                 5. **Apply**: configure the Provider / write code / transcribe into a file via `write_file`.\n\
-                 Rule: `fetch_url` is for *reading* a URL (docs/web/API description, markdown output); `http_request` is for *calling* an API (POST/auth/raw response). Never guess an endpoint — read the doc first, extract, then verify.\n",
+                 Rule: `fetch_url` is for *reading* a URL (docs/web/API description, markdown output); `http_request` is for *calling* an API (POST/auth/raw response). Never guess an endpoint — read the doc first, extract, then verify.\n\
+                 \n\
+                 ### JS-rendered docs & the obscura install hint\n\
+                 `fetch_url` defaults to a static fetch (no JS). For SPA / anti-scrape / JS-rendered docs, the user (or you) can pass `render=true`. When obscura (the JS-rendering backend, github.com/h4ckf0r0day/obscura) is **not installed**, the result silently falls back to static and the returned JSON carries `render_mode: \"static_fallback\"` plus a `hint` field pointing to the install page. Watch the **`hint` field** specifically (not just `render_mode`) — it is the install signal:\n\
+                 1. **Notice**: if the `fetch_url` result has `hint` set (or `render_mode` is `static_fallback`), obscura is missing and the page may be under-rendered.\n\
+                 2. **Offer**: proactively tell the user — \"obscura is not installed; installing it lets fetch_url render JS-heavy SPA / anti-scrape docs. Want me to install it for you?\" Don't silently continue with the static fallback when the user clearly needs JS rendering.\n\
+                 3. **Install on consent**: once the user agrees, run the install yourself via `run_command` and stream the output so the user sees progress — pick whichever path fits the user's environment:\n\
+                    - Rust toolchain present: `cargo install obscura`\n\
+                    - otherwise: download the matching prebuilt binary from github.com/h4ckf0r0day/obscura releases and place it on PATH\n\
+                    (`run_command` is high-risk and requires user approval — the user's \"yes\" above is that approval; still announce the exact command before running.)\n\
+                 4. **Re-fetch**: after install succeeds, tell the user \"obscura is ready\" and retry `fetch_url` with `render=true` to get the properly rendered markdown.\n\
+                 This is a pure conversational guide — there is no UI button for it; you detect the hint and drive the install through dialogue.\n",
        _ => "\n\
              ## 文档探索策略\n\
              收到用户给的 URL(产品页/API 文档/SDK 说明)时,按以下流程走,不要盲目对原始 URL 发 http_request 瞎试:\n\
@@ -146,7 +161,18 @@ fn doc_exploration_strategy_section(lang: &str) -> &'static str {
              3. **提取关键**:把 base_url、provider_type、鉴权方式、模型清单、端点路径显式列出来,再决定调什么。\n\
              4. **验证**:此时才用 `http_request` 打你提取出的正确端点(如带鉴权头 `GET {base_url}/v1/models`)确认可用。\n\
              5. **应用**:配置 Provider / 编码 / 转写到文件(write_file)。\n\
-              铁律:`fetch_url` 用于**读** URL(文档/网页/API 说明,输出 markdown);`http_request` 用于**调** API(POST/鉴权/原始响应)。严禁猜端点——先读文档提取,再验证。\n",
+              铁律:`fetch_url` 用于**读** URL(文档/网页/API 说明,输出 markdown);`http_request` 用于**调** API(POST/鉴权/原始响应)。严禁猜端点——先读文档提取,再验证。\n\
+              \n\
+              ### JS 渲染文档与 obscura 安装引导\n\
+              `fetch_url` 默认走静态抓取(不跑 JS)。遇到 SPA / 反爬 / JS 渲染的文档,用户(或你)可传 `render=true`。当 obscura(JS 渲染后端,github.com/h4ckf0r0day/obscura)**未安装**时,结果会静默回退静态,返回的 JSON 带 `render_mode: \"static_fallback\"` 和一个指向安装页的 `hint` 字段。请**重点看 `hint` 字段**(而非只看 `render_mode`)——它就是安装信号:\n\
+              1. **察觉**:若 `fetch_url` 结果带 `hint`(或 `render_mode` 为 `static_fallback`),说明 obscura 缺失,页面可能没渲染完整。\n\
+              2. **提议**:主动告诉用户——「obscura 未安装,装了之后 fetch_url 就能渲染 JS 重的 SPA / 反爬文档。要我帮你装吗?」当用户明显需要 JS 渲染时,不要默默用静态回退糊弄过去。\n\
+              3. **同意即装**:用户同意后,你自己用 `run_command` 执行安装并流式输出(让用户看到进度),按用户环境选合适路径:\n\
+                 - 有 Rust 工具链:`cargo install obscura`\n\
+                 - 否则:从 github.com/h4ckf0r0day/obscura releases 下载对应平台的预编译二进制,放到 PATH 上\n\
+                 (`run_command` 是高风险、需用户批准的工具——上面用户的「同意」即是批准;执行前仍要把确切命令告知用户。)\n\
+              4. **重试**:装成功后告诉用户「obscura 就绪」,并用 `render=true` 重试 `fetch_url` 拿到渲染完整的 markdown。\n\
+              这是纯对话式引导——没有专门的 UI 按钮,靠你识别 hint 字段、在对话中驱动安装。\n",
    }
 }

@@ -399,6 +425,26 @@ mod tests {
        assert!(en.contains("Extract keys"));
        assert!(en.contains("Verify"));
        assert!(en.contains("Apply"));
+
+        // obscura 安装引导子段(中/英)——看 hint 字段自主提示 + 帮装 + 重试
+        // 核心:hint 字段是安装信号(非只看 render_mode),同意即用 run_command 装,装完重试 render=true。
+        assert!(zh.contains("obscura"));
+        assert!(zh.contains("hint"));
+        assert!(zh.contains("static_fallback"));
+        assert!(zh.contains("render_mode"));
+        assert!(zh.contains("run_command"));
+        assert!(zh.contains("cargo install obscura"));
+        assert!(zh.contains("github.com/h4ckf0r0day/obscura"));
+        assert!(zh.contains("render=true"));
+
+        assert!(en.contains("obscura"));
+        assert!(en.contains("hint"));
+        assert!(en.contains("static_fallback"));
+        assert!(en.contains("render_mode"));
+        assert!(en.contains("run_command"));
+        assert!(en.contains("cargo install obscura"));
+        assert!(en.contains("github.com/h4ckf0r0day/obscura"));
+        assert!(en.contains("render=true"));
    }

    #[test]