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

package/lib/types/host/services/web-render/provider.js

@@ -0,0 +1,274 @@
+/**
+ * 用真实 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 } from 'playwright-core';
+import { WebRenderError, WEB_RENDER_PROVIDER_ID, } from "./contracts.js";
+/** 各平台已知的浏览器安装路径，仅用于廉价的可用性判断。 */
+const CHANNEL_PATHS = {
+    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) {
+    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) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /ProcessSingleton|already in use|is already running/i.test(message);
+}
+/** 用真实 Chromium 渲染页面的抓取后端。 */
+export class RenderFetchProvider {
+    id = WEB_RENDER_PROVIDER_ID;
+    /** 持久化 profile 目录；非空时用 launchPersistentContext 保住登录态。 */
+    userDataDir;
+    #readConfig;
+    #browser;
+    #context;
+    #launching;
+    #disposed = false;
+    #warn;
+    /** profile 被占用时降级用的临时目录；dispose 时删除。 */
+    #ephemeralDir;
+    #warnedProfileInUse = false;
+    /**
+     * @param readConfig - 每次取值时重新解析配置（命名空间 volatile 热更新可见）。
+     * @param userDataDir - 持久化 Chrome profile 目录；空串表示用临时上下文。
+     * @param warn - 告警出口（profile 被占用降级等）。
+     */
+    constructor(readConfig, userDataDir, warn) {
+        this.#readConfig = readConfig;
+        this.userDataDir = userDataDir;
+        this.#warn = warn ?? ((message) => console.warn(message));
+    }
+    /** 廉价的本地检查：必须有一个能启动的浏览器。 */
+    available() {
+        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, signal) {
+        const { url } = request;
+        let parsed;
+        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 = () => 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 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() {
+        this.#launching ??= this.#launch().catch((error) => {
+            this.#launching = undefined;
+            throw error;
+        });
+        return this.#launching;
+    }
+    /** 按配置的通道逐个尝试启动。 */
+    async #launch() {
+        const config = this.#readConfig();
+        const attempts = config.executablePath !== '' ? [''] : config.browserChannels;
+        const failures = [];
+        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) {
+        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() {
+        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/lib/types/host/services/web-search-anthropic/contracts.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 declare const WEB_SEARCH_ANTHROPIC_PROVIDER_ID = "anthropic-messages";
+/**
+ * 本域镜像的官方设置条目 id（`dsh-base` 的 `web-search-deepseek` 行）。
+ * 配置只从这里读，本域不新增任何命名空间。
+ */
+export declare const SEARCH_SETTINGS_ENTRY_ID = "web-search-deepseek";
+/** 一次搜索请求；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;
+}
+/**
+ * 从官方设置条目里读出一次搜索的配置。
+ *
+ * 读不到条目、或基址/模型为空时返回 `undefined` —— 本域不会替用户猜端点或模型
+ * （插件里不该出现任何厂商默认值），而是让 `available()` 为假，由 seam 给出
+ * 「去 Web search 设置里配」的明确失败。
+ *
+ * @param entries - `ctx.settings.describe()` 的结果。
+ * @returns 配置快照；缺关键项时为 undefined。
+ */
+export declare function searchConfigFrom(entries: readonly SettingsEntry[] | undefined): SearchConfig | undefined;
+/**
+ * 检索失败。形状对齐 `WebError`（带机器可路由的 `code`），
+ * 由 `dsh-tool-web` 包装成模型可读的 `Error: <message>`。
+ */
+export declare class WebSearchError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+//# sourceMappingURL=contracts.d.ts.map

package/lib/types/host/services/web-search-anthropic/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/web-search-anthropic/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,uBAAuB,CAAA;AAEpE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,wBAAwB,CAAA;AAM7D,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,eAAe;AACf,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,iBAAiB;AACjB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;IAC5C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED,cAAc;AACd,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,2BAA2B;IAC3B,SAAS,IAAI,OAAO,CAAA;IACpB,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAClF;AAED,0BAA0B;AAC1B,MAAM,WAAW,OAAO;IACtB,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAAA;CAChE;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,aAAa,EAAE,CAAA;CAC1E;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAA;CAC7D;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAA;IACf,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAA;IACjB,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAA;CAChB;AAYD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAmBxG;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAK1C"}

package/lib/types/host/services/web-search-anthropic/contracts.js

@@ -0,0 +1,90 @@
+/**
+ * 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';
+/** 非空字符串。 */
+function text(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+/** 正整数。 */
+function positiveInteger(value) {
+    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) {
+    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;
+    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 {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'WebError';
+        this.code = code;
+    }
+}

package/lib/types/host/services/web-search-anthropic/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 { type SettingsSeam } from './contracts.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;
+}
+/**
+ * 注册 Anthropic 兼容检索 provider。
+ * @param ctx - host plugin context。
+ * @param options - 告警出口与测试注入面。
+ * @returns 卸载回调：注销 provider。
+ */
+export declare function register(ctx: Context, options?: WebSearchAnthropicRegistrationOptions): () => void;
+export { searchConfigFrom, SEARCH_SETTINGS_ENTRY_ID, WEB_SEARCH_ANTHROPIC_PROVIDER_ID, } from './contracts.ts';
+export { AnthropicMessagesSearchProvider, citationSnippets, mapSearchResponse } from './provider.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/host/services/web-search-anthropic/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/web-search-anthropic/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAKL,KAAK,YAAY,EAElB,MAAM,gBAAgB,CAAA;AAGvB,MAAM,WAAW,qCAAqC;IACpD,2BAA2B;IAC3B,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAA;IAC5C,kDAAkD;IAClD,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,sCAAsC;IACtC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IAC1C,qBAAqB;IACrB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB;AAWD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,qCAA0C,GAAG,MAAM,IAAI,CA6EtG;AAED,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,gCAAgC,GACjC,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,+BAA+B,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA"}

package/lib/types/host/services/web-search-anthropic/index.js

@@ -0,0 +1,123 @@
+/**
+ * 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 { searchConfigFrom, SEARCH_SETTINGS_ENTRY_ID, WEB_SEARCH_ANTHROPIC_PROVIDER_ID, } from "./contracts.js";
+import { AnthropicMessagesSearchProvider } from "./provider.js";
+/** 可选读取一个服务缝隙：0.2 严格注入下访问未声明的服务会直接抛错。 */
+function optionalService(ctx, name) {
+    try {
+        return ctx[name];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 注册 Anthropic 兼容检索 provider。
+ * @param ctx - host plugin context。
+ * @param options - 告警出口与测试注入面。
+ * @returns 卸载回调：注销 provider。
+ */
+export function register(ctx, options = {}) {
+    const warn = options.logger?.warn ?? ((message) => console.warn(message));
+    const env = options.env ?? ((name) => process.env[name]);
+    let settings = options.settings;
+    let credentials;
+    // settings 是可选依赖：没有它就读不到配置，provider 仍注册（注册期告警）。
+    try {
+        ctx.inject(['settings'], (cctx) => {
+            settings = settings ?? optionalService(cctx, '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(cctx, 'credentials'); });
+    }
+    catch {
+        // 该 profile 没有 credentials 服务：静默缺席，key 交由环境变量。
+    }
+    /** 当前设置条目的活值（`describe` 失败时视为无配置，不抛给 seam）。 */
+    function readEntries() {
+        try {
+            return settings?.describe();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** 每次搜索解析一次 key：凭据服务 → 启动环境变量。 */
+    async function resolveKey() {
+        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;
+    try {
+        ctx.inject(['web'], (cctx) => {
+            if (disposed)
+                return;
+            const seam = optionalService(cctx, '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.js";
+export { AnthropicMessagesSearchProvider, citationSnippets, mapSearchResponse } from "./provider.js";