@thincoder/core 0.10.7 → 0.10.9

package/tools/web-deepseek.mjs

@@ -0,0 +1,172 @@
+/**
+ * web-deepseek.mjs — DeepSeek Search / Fetch backend for the `websearch` & `fetch` tools
+ * (design = `docs/core/design/TOOLS.md` §6.23 · ledger #1605).
+ *
+ * Key source = the first `providers[]` entry whose baseURL host is the official
+ * `api.deepseek.com` and whose apiKey resolves non-empty (`${env:VAR}` resolved at use
+ * time — an unresolved reference makes that entry ineligible, never throws). Zero new
+ * config: a configured DeepSeek provider is enough.
+ *
+ * The tools never fail because of this backend: every export returns a pure value
+ * (`{ status: "ok" | "empty" | "failed" | "unavailable" }`) and never throws.
+ * 401/402/403/404 trip a per-agent breaker (WeakSet); 408/429/5xx retry once (500 ms);
+ * everything else falls back to the caller's existing chain.
+ */
+import { URL } from "node:url"
+import { truncate, isPrivateHost } from "./shared.mjs"
+import { resolveProviderSecrets } from "../env-ref.mjs"
+import { proxyFetch } from "../proxy.mjs"
+import { logEvent } from "../log.mjs"
+
+// D-WB2: endpoints are fixed constants — `baseURL` only decides eligibility (a user's
+// `/v1` suffix or prefix must not build a doubled path, and the key only goes to the
+// official host).
+const SEARCH_URL = "https://api.deepseek.com/v1/tools/search"
+const FETCH_URL = "https://api.deepseek.com/v1/tools/fetch"
+const DEEPSEEK_HOST = "api.deepseek.com"
+const TIMEOUT_MS = 15_000
+const RETRY_DELAY_MS = 500 // D-WB5: fixed single backoff (no Retry-After parsing)
+const COST_PER_CALL = 0.00075 // $0.75 / 1000 successful requests — `count` does not change the price
+const TRIP_STATUS = new Set([401, 402, 403, 404])
+const RETRY_STATUS = (() => {
+  const codes = new Set([408, 429])
+  for (let code = 500; code <= 599; code++) codes.add(code)
+  return codes
+})()
+
+let _transport = proxyFetch
+let _breaker = new WeakSet()
+
+/** Test seam (CONFIG.md §6.2 ③ — paired): swap the transport; reset also clears the breaker. */
+export function _setDeepseekTransportForTest(fn) { _transport = typeof fn === "function" ? fn : proxyFetch }
+export function _resetDeepseekTransportForTest() { _transport = proxyFetch; _breaker = new WeakSet() }
+
+/** `local` skips the DeepSeek backend; anything else (missing ∥ misspelled ∥ non-string) = `auto` (fail-open). */
+export function backendMode(cfg, key) {
+  return cfg?.[key]?.backend === "local" ? "local" : "auto"
+}
+
+/** First qualifying channel in stored order → `{ apiKey }` | null. Never throws. */
+function deepseekChannel(cfg) {
+  const list = Array.isArray(cfg?.providersList) ? cfg.providersList
+    : Array.isArray(cfg?.providers) ? cfg.providers : []
+  for (const entry of list) {
+    if (entry === null || typeof entry !== "object") continue
+    let url
+    try { url = new URL(String(entry.baseURL ?? "")) } catch { continue }
+    if (url.protocol !== "https:") continue
+    const host = url.hostname.toLowerCase().replace(/\.$/, "") // trailing-dot host still official
+    if (host !== DEEPSEEK_HOST) continue // subdomains never qualify (x.api.deepseek.com)
+    if (url.port !== "" && url.port !== "443") continue // non-standard port could impersonate
+    let apiKey
+    try { apiKey = resolveProviderSecrets(entry).apiKey } catch { continue } // unset env ref ⇒ ineligible
+    if (typeof apiKey !== "string" || apiKey.trim() === "") continue
+    return { apiKey: apiKey.trim() }
+  }
+  return null
+}
+
+const tripped = (agent) => agent !== null && typeof agent === "object" && _breaker.has(agent)
+
+/** Break the backend for this agent identity (single domain — search ∥ fetch share it, D-WB3). */
+function trip(agent) {
+  if (agent !== null && typeof agent === "object") _breaker.add(agent)
+}
+
+/** One POST. Returns `{ kind: "ok", data }` | `{ kind: "http", status }` | `{ kind: "net", timeout }` | `{ kind: "json" }`. */
+async function postOnce(url, body, apiKey, proxyUri) {
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS)
+  try {
+    const res = await _transport(url, {
+      method: "POST",
+      // Same header shape as the Tavily leg (`web.mjs` bearer precedent).
+      headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    }, proxyUri)
+    if (!res || res.ok !== true) {
+      try { await res?.body?.cancel?.() } catch { /* body already closed */ }
+      return { kind: "http", status: Number(res?.status ?? 0) }
+    }
+    try { return { kind: "ok", data: await res.json() } } catch { return { kind: "json" } }
+  } catch (e) {
+    return { kind: "net", timeout: e?.name === "AbortError" }
+  } finally { clearTimeout(timer) }
+}
+
+/** One logical call: retry once (408/429/5xx), trip on 401/402/403/404, otherwise fall back. */
+async function request(url, body, apiKey, proxyUri, tool, agent) {
+  const started = Date.now()
+  let r = await postOnce(url, body, apiKey, proxyUri)
+  if (r.kind === "http" && RETRY_STATUS.has(r.status)) {
+    await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS))
+    r = await postOnce(url, body, apiKey, proxyUri)
+  }
+  if (r.kind === "ok") return { ok: true, data: r.data }
+  if (r.kind === "http" && TRIP_STATUS.has(r.status) && agent !== null && typeof agent === "object") {
+    trip(agent)
+    // Tripping line only (transient fallbacks stay quiet — ⑤).
+    logEvent("web:deepseek", { tool, status: r.status, tripped: true, ms: Date.now() - started })
+  }
+  const reason = r.kind === "http" ? `http ${r.status}`
+    : r.kind === "net" ? (r.timeout ? "timeout" : "network")
+      : "malformed json"
+  return { ok: false, reason }
+}
+
+/** Response → tool text: `[deepseek]` block per result, same numbered shape as the Tavily ∥ Bing legs. */
+function renderSearch(data, limit) {
+  const list = Array.isArray(data?.results) ? data.results : []
+  const results = list.slice(0, limit)
+  if (results.length === 0) return { n: 0, text: "" }
+  const blocks = results.map((r, i) => {
+    const meta = []
+    if (typeof r?.date === "string" && r.date.trim() !== "") meta.push(r.date)
+    if (Number.isFinite(r?.authority) && r.authority >= 0) meta.push(`authority ${r.authority}`) // -1 = unknown ⇒ omitted
+    if (Number.isFinite(r?.rerank_score)) meta.push(`rerank ${r.rerank_score}`)
+    const summary = typeof r?.summary === "string" && r.summary.trim() !== ""
+      ? r.summary
+      : (typeof r?.snippet === "string" ? r.snippet : "")
+    const lines = [`${i + 1}. [deepseek] ${r?.title ?? ""}`, `   ${r?.url ?? ""}`]
+    if (meta.length > 0) lines.push(`   ${meta.join(" · ")}`)
+    if (summary !== "") lines.push(`   ${summary}`)
+    return lines.join("\n")
+  })
+  return { n: results.length, text: truncate(blocks.join("\n\n")) }
+}
+
+/** search — `count` = the tool-face limit (`web.mjs` already clamps it to 20); `< 1` ⇒ 1. Never throws. */
+export async function deepseekSearch({ cfg, query, limit = 8, proxy = null, agent = null } = {}) {
+  const channel = deepseekChannel(cfg)
+  if (channel === null) return { status: "unavailable" }
+  if (tripped(agent)) return { status: "failed", reason: "breaker open" }
+  const count = Math.min(50, Math.max(1, Number.isFinite(limit) ? Math.floor(limit) : 8))
+  const started = Date.now()
+  const r = await request(SEARCH_URL, { query, count, need_content: false }, channel.apiKey, proxy, "search", agent)
+  if (!r.ok) return { status: "failed", reason: r.reason }
+  const { n, text } = renderSearch(r.data, count)
+  logEvent("web:deepseek", { tool: "search", n, ms: Date.now() - started, cost: n > 0 ? COST_PER_CALL : 0 })
+  return n > 0 ? { status: "ok", text, n } : { status: "empty" }
+}
+
+/** fetch — title + Markdown; empty `content` ⇒ `empty` (caller falls back to the local fetch). Never throws. */
+export async function deepseekFetch({ cfg, url, proxy = null, agent = null } = {}) {
+  const channel = deepseekChannel(cfg)
+  if (channel === null) return { status: "unavailable" }
+  if (tripped(agent)) return { status: "failed", reason: "breaker open" }
+  // `web.mjs` runs the SSRF gate before calling; keep a second one here so a direct
+  // caller can never send a private/metadata URL to a third party either.
+  let target
+  try { target = new URL(url) } catch { return { status: "failed", reason: "invalid url" } }
+  if (isPrivateHost(target.hostname)) return { status: "failed", reason: "private url" }
+  const started = Date.now()
+  const r = await request(FETCH_URL, { url }, channel.apiKey, proxy, "fetch", agent)
+  if (!r.ok) return { status: "failed", reason: r.reason }
+  const title = typeof r.data?.title === "string" ? r.data.title : ""
+  const content = typeof r.data?.content === "string" ? r.data.content : ""
+  const n = content.trim() === "" ? 0 : content.length
+  logEvent("web:deepseek", { tool: "fetch", n, ms: Date.now() - started, cost: n > 0 ? COST_PER_CALL : 0 })
+  if (n === 0) return { status: "empty" }
+  return { status: "ok", text: truncate(`[deepseek] ${title}\n\n${content}`), n }
+}

package/tools/web.mjs

@@ -2,11 +2,17 @@ import { DESC, truncate, stripTags, htmlToText, isPrivateHost } from "./shared.m
 import { URL } from "node:url";
 import { proxyFetch } from "../proxy.mjs";
 import { resolveEnvRefs } from "../env-ref.mjs";
+import { backendMode, deepseekSearch, deepseekFetch } from "./web-deepseek.mjs";
 
 export const UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
 const FETCH_TIMEOUT = 15_000
 // D-TF3：网络失败错误文本追加 proxy 提示——纯文本提示，不自动路由（2026-08-31 裁定：proxy 显式传不自动应用）
 const PROXY_HINT = "network failure — retry with proxy: 'http://host:port' if the target is blocked"
+// WEB-BACKEND-DEEPSEEK（TOOLS.md §6.23 ④）：DeepSeek 未出结果 ⇒ 回落腿承接后结果末尾恰一行（按返回态分叉）。
+// fetch 腿两态零提示（D-WB6）；`unavailable` ∥ `local` 零提示（零回归）。
+const deepseekNote = (status, leg) => status === "empty"
+  ? `(deepseek returned no results — results from ${leg})`
+  : `(deepseek backend unavailable — results from ${leg})`
 
 // ── Web search (Bing; direct by default, through proxy when configured and web toggle on) ──
 
@@ -107,18 +113,29 @@ export const websearchTool = {
     // 2026-08-31 ruling: proxy is a PER-CALL decision (args.proxy), never the config.json
     // fixed configuration. Model picks by target: github/foreign → pass proxy; gitee/domestic → omit.
     const proxyUri = args.proxy ?? null
+    // DeepSeek first when a qualifying provider is configured (TOOLS.md §6.23 ②) — `local`,
+    // no channel, or a query over 128 chars ⇒ zero calls, and the chain below runs verbatim.
+    let dsNote = null
+    if (backendMode(ctx?.agent?.config, "websearch") !== "local"
+      && typeof args.query === "string" && args.query.length <= 128) {
+      const ds = await deepseekSearch({ cfg: ctx?.agent?.config, query: args.query, limit, proxy: proxyUri, agent: ctx?.agent })
+      if (ds.status === "ok") return ds.text
+      if (ds.status === "empty" || ds.status === "failed") dsNote = ds.status
+    }
+    // A DeepSeek outcome only adds a line once a fallback leg actually carries results.
+    const withNote = (text, leg) => (dsNote ? `${text}\n\n${deepseekNote(dsNote, leg)}` : text)
     // Structured search first when a Tavily key is configured — stable, dated,
     // no HTML scraping. Falls back to Bing silently.
     const tavily = await fetchTavily(args.query, limit, ctx, proxyUri)
     if (tavily && tavily.results.length > 0) {
-      return truncate(tavily.results.slice(0, limit).map((r, i) => `${i + 1}. [tavily] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n"))
+      return withNote(truncate(tavily.results.slice(0, limit).map((r, i) => `${i + 1}. [tavily] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n")), "tavily")
     }
     if (args.engine) {
       const engine = ENGINES.find(e => e.name === args.engine)
       if (!engine) return `Unknown engine '${args.engine}'. Available: ${ENGINE_NAMES.join(", ")}`
       const fetched = await fetchEngine(engine, args.query, page, proxyUri)
       if (!fetched || fetched.results.length === 0) return "(no results)"
-      return truncate(fetched.results.slice(0, limit).map((r, i) => `${i + 1}. [${engine.label}] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n"))
+      return withNote(truncate(fetched.results.slice(0, limit).map((r, i) => `${i + 1}. [${engine.label}] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n")), engine.name)
     }
     const promises = ENGINES.map(e => fetchEngine(e, args.query, 1, proxyUri))
     const fetched = (await Promise.all(promises)).filter(Boolean)
@@ -135,7 +152,9 @@ export const websearchTool = {
         }
       }
     }
-    return truncate(merged.slice(0, limit).map((r, i) => `${i + 1}. [${r._engine}] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n"))
+    // Note only when a leg actually carried results — an empty merge keeps today's output.
+    const mergedText = truncate(merged.slice(0, limit).map((r, i) => `${i + 1}. [${r._engine}] ${r.title}\n   ${r.href}\n   ${r.snippet}`).join("\n\n"))
+    return merged.length > 0 ? withNote(mergedText, fetched[0].engine) : mergedText
   },
 }
 
@@ -193,9 +212,15 @@ export const fetchTool = {
     required: ["url"],
   },
   readonly: true,
-  async execute(args, _ctx) {
+  async execute(args, ctx) {
     if (!/^https?:\/\//.test(args.url)) throw new Error("url must start with http:// or https://")
     if (isPrivateUrl(args.url)) throw new Error("fetch blocked: internal/private/metadata addresses are not allowed")
+    // DeepSeek returns Markdown (W3); `empty` ∥ `failed` fall through to the local fetch,
+    // both without a result note (D-WB6 — the content face stays verbatim).
+    if (backendMode(ctx?.agent?.config, "fetch") !== "local") {
+      const ds = await deepseekFetch({ cfg: ctx?.agent?.config, url: args.url, proxy: args.proxy ?? null, agent: ctx?.agent })
+      if (ds.status === "ok") return ds.text
+    }
     try {
       // 2026-08-31 ruling: per-call decision — args.proxy when passed, direct otherwise.
       const proxyUri = args.proxy ?? null

package/vision-reader.mjs

@@ -1,8 +1,8 @@
 /**
  * vision-reader.mjs — 非多模态降级读图跑者（上提核件 —— parity-b4 W0 · 2026-09-29）。
  *
- * 上提源 = VSC `thincoder-vscode/src/extension/vision-channel.mjs:14`（`findVisionChannel` 逐字）
- * + `image-handler.mjs:70-95`（`runVisionReader` 逐字）；VSC 自持跑者 ∕ 渠道副本已随迁移轮（parity-b4）删。
+ * 上提源 = VSC `thincoder-vscode/src/extension/vision-channel.mjs`（#1127 已删档；`findVisionChannel` 逐字）
+ * + `image-handler.mjs`（`runVisionReader` 逐字）；VSC 自持跑者 ∕ 渠道副本已随迁移轮（parity-b4）删。
  * 消费面 = VSC `image-handler.mjs`（已改指本档）· 桌面 `src/main/attachments.mjs`
  * （降级适配器缺省 = 本档 —— `visionReader` 缝的核默认实现）。
  *
@@ -19,13 +19,13 @@
  *
  *  W8 契约②（2026-09-29 断链）：`agent.mjs` ∕ `agent-tools/subagent-async.mjs` 静态链达 `node:sqlite`
  *  （`agent.mjs` → `agent/setup.mjs` → `memory.mjs` → `memory/schema.mjs`）⇒ 两端一律**函数体内动态 import**
- *  （约定源 = `ledger.mjs:16`；实例 = `tools/index.mjs:63`）；本档静态边只留闭包净件（`config-io.mjs` ∕
+ *  （约定源 = `ledger.mjs`；实例 = `tools/index.mjs` 的 `assembleBuiltinTools`）；本档静态边只留闭包净件（`config-io.mjs` ∕
  *  `tools/index.mjs`）。
  */
 import { resolveProviders } from "./config-io.mjs"
 import { assembleBuiltinTools } from "./tools/index.mjs"
 
-/** 读图墙钟上限（VSC `image-handler.mjs:70` 同值——一次性子代理的成功径上限）。 */
+/** 读图墙钟上限（VSC `image-handler.mjs` 的 `runVisionReader` 同值——一次性子代理的成功径上限）。 */
 export const VISION_READ_TIMEOUT_MS = 60_000
 
 /** 找可跑视觉读图的渠道：`{ provider, model }` ∥ `null`。