@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.4

package/src/host/services/web-render/provider.ts

@@ -0,0 +1,282 @@
+/**
+ * 用真实 Chromium 渲染页面的 fetch provider。
+ *
+ * 一个 Chromium 实例懒启动、跨次复用，每次抓取开新页面；插件卸载时关闭。
+ * 配置按**每次抓取**从注入的读取器取，因此 `web-render` 命名空间的 volatile
+ * 热更新（无头/超时/视口等）立即生效，无需重挂插件。
+ *
+ * `available()` 只做本地文件检查，不发网络请求（seam 的硬要求）。
+ *
+ * @module web-all/host/services/web-render
+ */
+
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { homedir, platform, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { chromium, type Browser, type BrowserContext } from 'playwright-core'
+import {
+  WebRenderError,
+  WEB_RENDER_PROVIDER_ID,
+  type ResolvedWebRenderConfig,
+  type WebFetchProvider,
+  type WebFetchRequest,
+  type WebFetchResult,
+} from './contracts.ts'
+
+/** 各平台已知的浏览器安装路径，仅用于廉价的可用性判断。 */
+const CHANNEL_PATHS: Record<string, Record<string, string[]>> = {
+  darwin: {
+    chrome: ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'],
+    msedge: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+    chromium: ['/Applications/Chromium.app/Contents/MacOS/Chromium'],
+  },
+  linux: {
+    chrome: ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/opt/google/chrome/chrome'],
+    msedge: ['/usr/bin/microsoft-edge', '/usr/bin/microsoft-edge-stable'],
+    chromium: ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'],
+  },
+  win32: {
+    chrome: [
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    ],
+    msedge: [
+      'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+      'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+    ],
+    chromium: [],
+  },
+}
+
+/** 该通道是否像样地可启动：只查已知路径与 playwright 自带的下载缓存。 */
+function channelLaunchable(channel: string): boolean {
+  const known = CHANNEL_PATHS[platform()]?.[channel] ?? []
+  if (known.some(candidate => existsSync(candidate))) return true
+  if (channel !== 'chromium') return false
+  const caches = [
+    join(homedir(), 'Library/Caches/ms-playwright'),
+    join(homedir(), '.cache/ms-playwright'),
+    join(process.env['LOCALAPPDATA'] ?? '', 'ms-playwright'),
+  ]
+  if (caches.some(dir => dir !== '' && existsSync(dir))) return true
+  try { return existsSync(chromium.executablePath()) } catch { return false }
+}
+
+/**
+ * Chrome 的 profile 单例锁冲突。同一个 userDataDir 同时只能有一个浏览器实例
+ * （ProcessSingleton），因此同机并发运行第二个使用本 profile 的 dsh 进程会撞上它。
+ */
+function isProfileInUse(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  return /ProcessSingleton|already in use|is already running/i.test(message)
+}
+
+/** launchPersistentContext 的选项面。 */
+type PersistentLaunchOptions = Parameters<typeof chromium.launchPersistentContext>[1]
+
+/** 用真实 Chromium 渲染页面的抓取后端。 */
+export class RenderFetchProvider implements WebFetchProvider {
+  readonly id = WEB_RENDER_PROVIDER_ID
+
+  /** 持久化 profile 目录；非空时用 launchPersistentContext 保住登录态。 */
+  readonly userDataDir: string
+
+  #readConfig: () => ResolvedWebRenderConfig
+  #browser: Browser | undefined
+  #context: BrowserContext | undefined
+  #launching: Promise<BrowserContext> | undefined
+  #disposed = false
+  #warn: (message: string) => void
+  /** profile 被占用时降级用的临时目录；dispose 时删除。 */
+  #ephemeralDir: string | undefined
+  #warnedProfileInUse = false
+
+  /**
+   * @param readConfig - 每次取值时重新解析配置（命名空间 volatile 热更新可见）。
+   * @param userDataDir - 持久化 Chrome profile 目录；空串表示用临时上下文。
+   * @param warn - 告警出口（profile 被占用降级等）。
+   */
+  constructor(readConfig: () => ResolvedWebRenderConfig, userDataDir: string, warn?: (message: string) => void) {
+    this.#readConfig = readConfig
+    this.userDataDir = userDataDir
+    this.#warn = warn ?? ((message: string): void => console.warn(message))
+  }
+
+  /** 廉价的本地检查：必须有一个能启动的浏览器。 */
+  available(): boolean {
+    if (this.#disposed) return false
+    const config = this.#readConfig()
+    if (config.executablePath !== '') return existsSync(config.executablePath)
+    return config.browserChannels.some(channelLaunchable)
+  }
+
+  /**
+   * 渲染并取回一个 URL。
+   * 非 2xx 作为结果返回（状态码是资源状态的一部分），不抛异常。
+   * @param request - seam 的抓取请求。
+   * @param signal - 工具调用超时策略下发的取消信号。
+   */
+  async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult> {
+    const { url } = request
+    let parsed: URL
+    try {
+      parsed = new URL(url)
+    } catch {
+      throw new WebRenderError(`invalid URL: ${url}`, 'WEB_INVALID_URL')
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new WebRenderError(`unsupported URL scheme "${parsed.protocol}" (only http and https are fetched)`, 'WEB_INVALID_URL')
+    }
+    // 用函数重读状态：写成内联比较会让 TS 把 signal.aborted 收窄成 false，
+    // catch 分支里的同款判断就变成"无重叠类型"。
+    const isAborted = (): boolean => signal?.aborted === true
+    if (isAborted()) throw new WebRenderError('web fetch aborted', 'WEB_ABORTED')
+
+    const config = this.#readConfig()
+    const context = await this.#ensureContext()
+    const page = await context.newPage()
+    let timedOut = false
+    const abort = (): void => { void page.close().catch(() => undefined) }
+    const timer = setTimeout(() => { timedOut = true; abort() }, config.timeoutMs)
+    signal?.addEventListener('abort', abort, { once: true })
+
+    try {
+      await page.setViewportSize({ width: config.viewportWidth, height: config.viewportHeight })
+      const response = await page.goto(url, { waitUntil: config.waitUntil, timeout: config.timeoutMs })
+
+      // 给客户端渲染留出完成时间。两次等待都是尽力而为：带轮询或 websocket 的
+      // 页面永远不会进入网络空闲，这不能算抓取失败。
+      if (config.networkIdleMs > 0) {
+        await page.waitForLoadState('networkidle', { timeout: config.networkIdleMs }).catch(() => undefined)
+      }
+      if (config.settleMs > 0) await page.waitForTimeout(config.settleMs)
+
+      // `page.innerText` 而不是 page.evaluate 里的 document：host 侧 tsconfig 的
+      // lib 只有 ES2024（无 DOM），在 evaluate 回调里引用 DOM 全局无法通过类型检查。
+      const raw = config.extract === 'text'
+        ? await page.innerText('body').catch(() => '')
+        : await page.content()
+
+      let content = raw
+      let truncated = false
+      if (content.length > config.maxBodyChars) {
+        content = content.slice(0, config.maxBodyChars)
+        truncated = true
+      }
+
+      return {
+        url: page.url(),
+        statusCode: response?.status() ?? 0,
+        body: { kind: config.extract, content },
+        truncated,
+      }
+    } catch (error) {
+      if (isAborted()) throw new WebRenderError('web fetch aborted', 'WEB_ABORTED')
+      if (timedOut) throw new WebRenderError(`web render timed out after ${config.timeoutMs}ms: ${url}`, 'WEB_FETCH_TIMEOUT')
+      const detail = error instanceof Error ? error.message.split('\n')[0] : String(error)
+      throw new WebRenderError(`browser fetch failed for ${url}: ${detail}`, 'WEB_PROVIDER_ERROR')
+    } finally {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', abort)
+      await page.close().catch(() => undefined)
+    }
+  }
+
+  /** 懒启动共享浏览器；启动失败不入缓存，下次调用重试。 */
+  #ensureContext(): Promise<BrowserContext> {
+    this.#launching ??= this.#launch().catch((error: unknown) => {
+      this.#launching = undefined
+      throw error
+    })
+    return this.#launching
+  }
+
+  /** 按配置的通道逐个尝试启动。 */
+  async #launch(): Promise<BrowserContext> {
+    const config = this.#readConfig()
+    const attempts = config.executablePath !== '' ? [''] : config.browserChannels
+    const failures: string[] = []
+
+    for (const channel of attempts) {
+      // playwright 的 `chromium` 通道表示自带下载，传 channel 反而会失败。
+      const channelOption = channel !== '' && channel !== 'chromium' ? { channel } : {}
+      const launchOptions = {
+        headless: config.headless,
+        args: config.args,
+        viewport: { width: config.viewportWidth, height: config.viewportHeight },
+        ...(config.executablePath !== '' ? { executablePath: config.executablePath } : {}),
+        ...channelOption,
+      }
+      try {
+        if (this.userDataDir !== '') {
+          const context = await this.#launchPersistent(launchOptions)
+          if (this.#disposed) {
+            await context.close().catch(() => undefined)
+            throw new Error('web-render disposed during launch')
+          }
+          this.#context = context
+          return context
+        }
+        const browser = await chromium.launch(launchOptions)
+        if (this.#disposed) {
+          await browser.close().catch(() => undefined)
+          throw new Error('web-render disposed during launch')
+        }
+        this.#browser = browser
+        const context = await browser.newContext({ viewport: launchOptions.viewport })
+        this.#context = context
+        return context
+      } catch (error) {
+        if (this.#disposed) throw error
+        const detail = error instanceof Error ? error.message.split('\n')[0] : String(error)
+        failures.push(`${channel === '' ? 'executablePath' : channel}: ${detail}`)
+      }
+    }
+    throw new WebRenderError(
+      `no launchable browser found (tried ${failures.join('; ')}). Install Google Chrome, or set the web-render executablePath setting.`,
+      'WEB_PROVIDER_UNAVAILABLE',
+    )
+  }
+
+  /**
+   * 启动持久化上下文；profile 被同机另一实例占用时降级到临时 profile。
+   *
+   * 降级是刻意的：一个 profile 锁不该让整个 `web_fetch` 变成不可用。代价只是
+   * 这一次实例没有登录态，并在日志里留一条明确告警。
+   */
+  async #launchPersistent(launchOptions: PersistentLaunchOptions): Promise<BrowserContext> {
+    try {
+      return await chromium.launchPersistentContext(this.userDataDir, launchOptions)
+    } catch (error) {
+      if (!isProfileInUse(error)) throw error
+      this.#ephemeralDir ??= mkdtempSync(join(tmpdir(), 'web-render-profile-'))
+      if (!this.#warnedProfileInUse) {
+        this.#warnedProfileInUse = true
+        this.#warn(`[web-all:web-render] Chrome profile "${this.userDataDir}" 已被另一个实例占用：`
+          + `本次降级到临时 profile（${this.#ephemeralDir}），抓取可用但没有登录态。`
+          + '要保住登录态，请避免同机并发运行第二个使用该 profile 的进程。')
+      }
+      return await chromium.launchPersistentContext(this.#ephemeralDir, launchOptions)
+    }
+  }
+
+  /** 关闭共享浏览器并停止接受抓取。 */
+  async dispose(): Promise<void> {
+    this.#disposed = true
+    const pending = this.#launching
+    this.#launching = undefined
+    if (pending !== undefined) await pending.catch(() => undefined)
+    const context = this.#context
+    this.#context = undefined
+    const browser = this.#browser
+    this.#browser = undefined
+    if (context !== undefined && (this.userDataDir !== '' || this.#ephemeralDir !== undefined)) {
+      await context.close().catch(() => undefined)
+    }
+    if (browser !== undefined) await browser.close().catch(() => undefined)
+    if (this.#ephemeralDir !== undefined) {
+      try { rmSync(this.#ephemeralDir, { recursive: true, force: true }) } catch { /* 临时目录清理失败不影响卸载 */ }
+      this.#ephemeralDir = undefined
+    }
+  }
+}

package/src/host/services/web-search-anthropic/contracts.ts

@@ -0,0 +1,163 @@
+/**
+ * Anthropic 兼容 Messages 检索：`ctx.web` 的结构面与错误形状 —— host 半区。
+ *
+ * ## 为什么存在（唯一原因）
+ *
+ * 官方 `@deepseek-ai/dsh-web-search-deepseek` 的请求侧是通用的（Anthropic 兼容
+ * Messages + 原生 `web_search_20250305`），端点/模型/凭据引用本来都可配置；
+ * 但它的**响应侧写死了一个前提**：
+ *
+ *   const resultBlocks = blocks.filter((b) => b.type === "web_search_tool_result")
+ *   if (resultBlocks.length === 0) throw new WebError("...no web_search_tool_result blocks...")
+ *
+ * 所以只要上游不返回结果块，无论怎么改配置都必然失败。Bedrock 系路由正是这种
+ * 形状：只有 `server_tool_use` 与带 `citations[]` 的 `text` 块，命中的 URL /
+ * 标题 / 摘录全在 citation 里。本域补的就是这一层解析：两种形状都归一化成 seam
+ * 的 `sources[]`。
+ *
+ * ## 为什么没有自己的配置面（重要）
+ *
+ * 本域**不注册** settings 命名空间、不定义 schema、不设默认值，只读官方
+ * `web-search-deepseek` 条目当前的活值（就是官方「Web search」页那几项：
+ * Messages API 地址、模型、凭据引用、`anthropic-version`、生成上限、搜索次数上限）。
+ * 于是：
+ *
+ *   - 用户要换任何 Anthropic 兼容搜索 API，改的还是**原来那个配置面**，无需学习新名字；
+ *   - 插件源码里不出现任何厂商端点、模型名或密钥引用（默认值由 DSH 自己的 schema 提供）；
+ *   - 把 pin 从本 provider 改回 `deepseek-official` 时，配置完全不用动。
+ *
+ * @module web-all/host/services/web-search-anthropic
+ */
+
+/** 注册到 `ctx.web` 的 search provider id；profile 用它 pin `searchProvider`。 */
+export const WEB_SEARCH_ANTHROPIC_PROVIDER_ID = 'anthropic-messages'
+
+/**
+ * 本域镜像的官方设置条目 id（`dsh-base` 的 `web-search-deepseek` 行）。
+ * 配置只从这里读，本域不新增任何命名空间。
+ */
+export const SEARCH_SETTINGS_ENTRY_ID = 'web-search-deepseek'
+
+// ——— `ctx.web` 的结构面 ———
+// 家族惯例是不 import 原生包类型（版本各自漂移），只按行为断言所需的缝面。
+// 与 `@deepseek-ai/dsh-web` 的 `WebSearchRequest/Result/Provider` 形状一致。
+
+/** 一次搜索请求；seam 传 query 与可选上限。 */
+export interface WebSearchRequest {
+  readonly query: string
+  readonly maxResults?: number
+}
+
+/** 一条可引用来源。 */
+export interface WebSearchSource {
+  readonly url: string
+  readonly title?: string
+  readonly snippet?: string
+  readonly publishedAt?: string
+}
+
+/** 归一化后的搜索产出。 */
+export interface WebSearchResult {
+  readonly sources: readonly WebSearchSource[]
+  readonly truncated: boolean
+}
+
+/** 一个搜索后端。 */
+export interface WebSearchProvider {
+  readonly id: string
+  /** 廉价的本地可用性检查；不得发起网络请求。 */
+  available(): boolean
+  search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
+}
+
+/** `ctx.web` 上本域用到的部分。 */
+export interface WebSeam {
+  registerSearchProvider(provider: WebSearchProvider): () => void
+}
+
+/** `ctx.settings.describe()` 返回的一条条目（只取本域需要的两个字段）。 */
+export interface SettingsEntry {
+  readonly ns?: string
+  readonly value?: unknown
+}
+
+/** `ctx.settings` 上本域用到的部分（只读，绝不写入别人的配置）。 */
+export interface SettingsSeam {
+  describe(options?: { redactSecrets?: boolean }): readonly SettingsEntry[]
+}
+
+/** `ctx.credentials` 上本域用到的部分（可选服务）。 */
+export interface CredentialSeam {
+  resolve(ref: string): Promise<{ value: string } | undefined>
+}
+
+/** 一次搜索的运行期配置快照；每个字段都来自官方设置条目，本域不给默认值。 */
+export interface SearchConfig {
+  /** Messages API 基址，不含 `/messages`。 */
+  baseURL: string
+  /** Anthropic 格式模型名。 */
+  model: string
+  /** 凭据引用名（凭据服务 / 启动环境），仅用于解析 key 与报错。 */
+  apiKeyEnv: string
+  /** `anthropic-version` 头。 */
+  apiVersion: string
+  /** 生成上限。 */
+  maxTokens: number
+  /** 服务端搜索次数上限。 */
+  maxUses: number
+}
+
+/** 非空字符串。 */
+function text(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+}
+
+/** 正整数。 */
+function positiveInteger(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined
+}
+
+/**
+ * 从官方设置条目里读出一次搜索的配置。
+ *
+ * 读不到条目、或基址/模型为空时返回 `undefined` —— 本域不会替用户猜端点或模型
+ * （插件里不该出现任何厂商默认值），而是让 `available()` 为假，由 seam 给出
+ * 「去 Web search 设置里配」的明确失败。
+ *
+ * @param entries - `ctx.settings.describe()` 的结果。
+ * @returns 配置快照；缺关键项时为 undefined。
+ */
+export function searchConfigFrom(entries: readonly SettingsEntry[] | undefined): SearchConfig | undefined {
+  const entry = entries?.find(candidate => candidate.ns === SEARCH_SETTINGS_ENTRY_ID)
+  const value = entry?.value
+  if (value === null || typeof value !== 'object') return undefined
+  const raw = value as Record<string, unknown>
+  const baseURL = text(raw['baseURL'])
+  const model = text(raw['model'])
+  if (baseURL === undefined || model === undefined) return undefined
+  const maxTokens = positiveInteger(raw['maxTokens'])
+  const maxUses = positiveInteger(raw['maxUses'])
+  if (maxTokens === undefined || maxUses === undefined) return undefined
+  return {
+    baseURL,
+    model,
+    apiKeyEnv: text(raw['apiKeyEnv']) ?? '',
+    apiVersion: text(raw['apiVersion']) ?? '2023-06-01',
+    maxTokens,
+    maxUses,
+  }
+}
+
+/**
+ * 检索失败。形状对齐 `WebError`（带机器可路由的 `code`），
+ * 由 `dsh-tool-web` 包装成模型可读的 `Error: <message>`。
+ */
+export class WebSearchError extends Error {
+  readonly code: string
+
+  constructor(message: string, code: string) {
+    super(message)
+    this.name = 'WebError'
+    this.code = code
+  }
+}

package/src/host/services/web-search-anthropic/index.ts

@@ -0,0 +1,152 @@
+/**
+ * Anthropic 兼容检索服务域 —— 向 `ctx.web` 注册 `anthropic-messages` search provider。
+ *
+ * ## 它只补什么
+ *
+ * 官方 `web-search-deepseek` provider 的请求侧通用、配置侧齐全，唯独解析侧写死
+ * 「响应必须含 `web_search_tool_result` 块」，否则抛错。本域用同一份配置发出同样的
+ * 请求，只把「只有 citation 的响应」也解析成来源（Bedrock 系路由的表现）。
+ * 因此本域**不新增配置面**：每次搜索从官方 `web-search-deepseek` 条目现读活值。
+ *
+ * ## 为什么注册是「只要 web 在就注册」
+ *
+ * profile patch 把 `@deepseek-ai/dsh-web` 的 `searchProvider` pin 成 `anthropic-messages`。
+ * seam 在指定了 id 时只用该 id：provider 缺席报 `WEB_PROVIDER_CONFIGURED_MISSING`，
+ * 注册了但 `available()` 为假报 `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`——两者都会让
+ * `web_search` 整体不可用。所以这里「只要 web 服务在就注册」，没配端点/模型时在注册期
+ * 写一条明确告警，运行期由 seam 给出可操作的错误，而不是留下一个静默失败的 pin。
+ *
+ * 要彻底关掉本域，必须**同时**把 profile 里的 `searchProvider` 改回
+ * `deepseek-official`，只删这一段会留下一个指向不存在 provider 的 pin。
+ *
+ * ## 为什么用局部 inject
+ *
+ * 0.2 严格注入下，插件只能访问自己 inject 声明过的服务。这里用
+ * `ctx.inject([...])` 分别等待 `web` / `settings` / `credentials`，而不是把它们写进
+ * web-all 的全局 inject：那会让整个全家桶在缺少这些服务的 profile 里挂掉。
+ *
+ * @module web-all/host/services/web-search-anthropic
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import {
+  searchConfigFrom,
+  SEARCH_SETTINGS_ENTRY_ID,
+  WEB_SEARCH_ANTHROPIC_PROVIDER_ID,
+  type CredentialSeam,
+  type SettingsSeam,
+  type WebSeam,
+} from './contracts.ts'
+import { AnthropicMessagesSearchProvider } from './provider.ts'
+
+export interface WebSearchAnthropicRegistrationOptions {
+  /** 结构化告警出口；缺省写 console。 */
+  logger?: { warn: (message: string) => void }
+  /** 显式的 settings 缝面（测试用）。缺省时从 `ctx.settings` 拿。 */
+  settings?: SettingsSeam
+  /** 环境变量读取面（测试用）。缺省读 `process.env`。 */
+  env?: (name: string) => string | undefined
+  /** 注入的 fetch，测试用。 */
+  fetchImpl?: typeof fetch
+}
+
+/** 可选读取一个服务缝隙：0.2 严格注入下访问未声明的服务会直接抛错。 */
+function optionalService<T>(ctx: Context, name: string): T | undefined {
+  try {
+    return (ctx as Context & Record<string, unknown>)[name] as T | undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * 注册 Anthropic 兼容检索 provider。
+ * @param ctx - host plugin context。
+ * @param options - 告警出口与测试注入面。
+ * @returns 卸载回调：注销 provider。
+ */
+export function register(ctx: Context, options: WebSearchAnthropicRegistrationOptions = {}): () => void {
+  const warn = options.logger?.warn ?? ((message: string): void => console.warn(message))
+  const env = options.env ?? ((name: string): string | undefined => process.env[name])
+  let settings = options.settings
+  let credentials: CredentialSeam | undefined
+
+  // settings 是可选依赖：没有它就读不到配置，provider 仍注册（注册期告警）。
+  try {
+    ctx.inject(['settings'], (cctx) => {
+      settings = settings ?? optionalService<SettingsSeam>(cctx as Context, 'settings')
+      if (searchConfigFrom(readEntries()) === undefined) {
+        warn(`[web-all:web-search-anthropic] ${SEARCH_SETTINGS_ENTRY_ID} 条目里还没有可用的 Messages API 基址与模型：`
+          + `web_search 仍被 pin 到 ${WEB_SEARCH_ANTHROPIC_PROVIDER_ID}，调用会以 WEB_PROVIDER_CREDENTIAL_MISSING 失败；`
+          + '请在 Web search 设置（Plugins > Built-in plugin settings > Web search）里填写 Messages API 地址、模型与凭据引用')
+      }
+    })
+  } catch {
+    // 组合里没有 settings 服务：本域无法读配置，注册期告警后继续。
+    warn('[web-all:web-search-anthropic] 没有 settings 服务，读不到 Web search 配置；本域注册但不可用')
+  }
+
+  // credentials 也是可选依赖：没有它时 key 回落到启动环境变量。
+  try {
+    ctx.inject(['credentials'], (cctx) => { credentials = optionalService<CredentialSeam>(cctx as Context, 'credentials') })
+  } catch {
+    // 该 profile 没有 credentials 服务：静默缺席，key 交由环境变量。
+  }
+
+  /** 当前设置条目的活值（`describe` 失败时视为无配置，不抛给 seam）。 */
+  function readEntries(): ReturnType<SettingsSeam['describe']> | undefined {
+    try {
+      return settings?.describe()
+    } catch {
+      return undefined
+    }
+  }
+
+  /** 每次搜索解析一次 key：凭据服务 → 启动环境变量。 */
+  async function resolveKey(): Promise<string | undefined> {
+    const ref = searchConfigFrom(readEntries())?.apiKeyEnv ?? ''
+    if (ref === '') return undefined
+    try {
+      const stored = await credentials?.resolve(ref)
+      if (stored !== undefined && stored.value.length > 0) return stored.value
+    } catch {
+      // 凭据服务拒绝解析（引用不存在/语法非法）时退回环境变量。
+    }
+    const ambient = env(ref)
+    return ambient !== undefined && ambient.length > 0 ? ambient : undefined
+  }
+
+  const provider = new AnthropicMessagesSearchProvider(
+    () => searchConfigFrom(readEntries()),
+    resolveKey,
+    options.fetchImpl,
+  )
+
+  let disposed = false
+  let unregister: (() => void) | undefined
+
+  try {
+    ctx.inject(['web'], (cctx) => {
+      if (disposed) return
+      const seam = optionalService<WebSeam>(cctx as Context, 'web')
+      if (seam?.registerSearchProvider === undefined) return
+      unregister = seam.registerSearchProvider(provider)
+    })
+  } catch (error) {
+    // 组合里没有 web 服务：本域静默缺席，绝不影响全家桶其余能力。
+    warn(`[web-all:web-search-anthropic] 等待 web 服务失败，本域缺席：${error instanceof Error ? error.message : String(error)}`)
+    return () => undefined
+  }
+
+  return () => {
+    disposed = true
+    unregister?.()
+  }
+}
+
+export {
+  searchConfigFrom,
+  SEARCH_SETTINGS_ENTRY_ID,
+  WEB_SEARCH_ANTHROPIC_PROVIDER_ID,
+} from './contracts.ts'
+export { AnthropicMessagesSearchProvider, citationSnippets, mapSearchResponse } from './provider.ts'