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

package/lib/types/host/services/ssh/tools.js

@@ -0,0 +1,270 @@
+/**
+ * ssh host 服务域 —— agent 工具层（全新实现；行为契约参考旧包）。
+ *
+ * 工具名冻结：ssh_list / ssh_exec / ssh_upload / ssh_download / ssh_tunnel /
+ * ssh_cluster。用 SDK 的 defineTool 声明；text 渲染与参数 schema 保持旧包
+ * 可感知形状（模型侧契约不变）。
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+/** 纯文本内容块（这些工具唯一渲染形状）。 */
+function text(value) {
+    return [{ type: 'text', text: value }];
+}
+/** 主机表格渲染。 */
+function renderHosts(hosts) {
+    if (hosts.length === 0)
+        return 'no hosts configured';
+    const rows = hosts.map(host => [
+        host.alias, host.host, String(host.port), host.user, host.auth,
+        host.environment ?? '-', (host.tags.length > 0 ? host.tags.join(',') : '-'), host.description ?? '',
+    ].join(' | '));
+    return ['alias | host | port | user | auth | environment | tags | description', '--- | --- | --- | --- | --- | --- | --- | ---', ...rows].join('\n');
+}
+/** exec 结果文本。 */
+function renderExec(result) {
+    if (!result.success) {
+        const reason = result.error ?? (result.timedOut
+            ? `timed out after ${result.durationMs}ms; remote command terminated (retry with a larger timeoutMs to allow more time)`
+            : `exit ${result.exitCode ?? '?'}`);
+        return `failed: ${reason}${result.stdout ? `\nstdout:\n${result.stdout.trimEnd()}` : ''}${result.stderr ? `\nstderr:\n${result.stderr.trimEnd()}` : ''}`;
+    }
+    return result.stdout.trimEnd() || '(no output)';
+}
+export function sshListTool(engine) {
+    return defineTool({
+        name: 'ssh_list',
+        description: 'List configured SSH hosts (alias, host, user, auth, environment, tags, description). Use ssh_exec etc. with the alias. Triggers: SSH, remote server, server IP/hostname, connect/login, check server/status, deploy, upload/download, jump host, tunnel, port forward.',
+        parameters: {
+            query: { type: 'string', description: 'Optional fuzzy match against alias, description, host, and tags.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    hosts: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                alias: { type: 'string', required: true },
+                                host: { type: 'string', required: true },
+                                port: { type: 'integer', required: true },
+                                user: { type: 'string', required: true },
+                                auth: { type: 'string', enum: ['key', 'password', 'agent'], required: true },
+                                keyReady: { type: 'boolean', required: true },
+                                proxyJump: { type: 'array', items: { type: 'string' }, required: true },
+                                description: { type: 'string' },
+                                environment: { type: 'string' },
+                                tags: { type: 'array', items: { type: 'string' }, required: true },
+                                location: { type: 'string' },
+                                createdAt: { type: 'integer', required: true },
+                                updatedAt: { type: 'integer', required: true },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => text(renderHosts(value.hosts ?? [])),
+        },
+        async execute(args) {
+            return { hosts: engine.list(args.query) };
+        },
+    });
+}
+export function sshExecTool(engine) {
+    return defineTool({
+        name: 'ssh_exec',
+        description: 'Execute a command on a remote host and return the result. ' +
+            'Every command has a timeout (120000 ms unless the call passes timeoutMs); on timeout the remote command is terminated instead of hanging. ' +
+            'Triggers: SSH, remote server, server IP/hostname, connect/login, run command on server, deploy, check server status, jump host.',
+        parameters: {
+            alias: { type: 'string', required: true, description: 'Configured host alias (see ssh_list).' },
+            command: { type: 'string', required: true, description: 'The shell command to run.' },
+            timeoutMs: { type: 'integer', description: 'Optional per-command timeout in milliseconds (default 120000). When it fires the channel is closed and the remote command is terminated.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    success: { type: 'boolean', required: true },
+                    exitCode: { oneOf: [{ type: 'integer' }, { type: 'null' }], required: true },
+                    timedOut: { type: 'boolean', required: true },
+                    stdout: { type: 'string', required: true },
+                    stderr: { type: 'string', required: true },
+                    durationMs: { type: 'integer', required: true },
+                    error: { type: 'string' },
+                },
+            },
+            render: (_args, value) => text(renderExec(value)),
+        },
+        async execute(args) {
+            const result = await engine.exec(args.alias, args.command, typeof args.timeoutMs === 'number' ? args.timeoutMs : undefined);
+            return result;
+        },
+    });
+}
+export function sshUploadTool(engine) {
+    return defineTool({
+        name: 'ssh_upload',
+        description: 'Upload a local file to a remote host over SFTP. ' +
+            'Triggers: upload file to server, push file to remote host, deploy artifact, scp equivalent.',
+        parameters: {
+            alias: { type: 'string', required: true, description: 'Configured host alias.' },
+            localPath: { type: 'string', required: true, description: 'Absolute path of the local file.' },
+            remotePath: { type: 'string', required: true, description: 'Absolute target path on the remote host.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    bytes: { type: 'integer', required: true },
+                    files: { type: 'integer', required: true },
+                },
+            },
+            render: (_args, value) => text(`uploaded ${value.files} file(s), ${value.bytes} bytes`),
+        },
+        async execute(args) {
+            const result = await engine.upload(args.alias, args.localPath, args.remotePath);
+            return { bytes: result.bytes, files: result.files };
+        },
+    });
+}
+export function sshDownloadTool(engine) {
+    return defineTool({
+        name: 'ssh_download',
+        description: 'Download a remote file to the local machine over SFTP. ' +
+            'Triggers: download file from server, fetch remote artifact, scp equivalent.',
+        parameters: {
+            alias: { type: 'string', required: true, description: 'Configured host alias.' },
+            remotePath: { type: 'string', required: true, description: 'Absolute source path on the remote host.' },
+            localPath: { type: 'string', required: true, description: 'Absolute destination path on this machine.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    localPath: { type: 'string', required: true },
+                    bytes: { type: 'integer', required: true },
+                },
+            },
+            render: (_args, value) => text(`downloaded to ${value.localPath} (${value.bytes} bytes)`),
+        },
+        async execute(args) {
+            const { readFileSync, writeFileSync, mkdirSync } = await import('node:fs');
+            const { dirname } = await import('node:path');
+            const client = await engine.acquire(args.alias);
+            const data = await new Promise((resolvePromise, rejectPromise) => {
+                client.sftp((error, sftp) => {
+                    if (error !== undefined) {
+                        rejectPromise(error);
+                        return;
+                    }
+                    sftp.readFile(args.remotePath, (readError, buf) => {
+                        if (readError !== undefined) {
+                            rejectPromise(readError);
+                            return;
+                        }
+                        resolvePromise(buf);
+                    });
+                });
+            });
+            mkdirSync(dirname(args.localPath), { recursive: true });
+            writeFileSync(args.localPath, data);
+            void readFileSync;
+            return { localPath: args.localPath, bytes: data.length };
+        },
+    });
+}
+export function sshTunnelTool(engine) {
+    return defineTool({
+        name: 'ssh_tunnel',
+        description: 'Create a local port-forward tunnel to a remote service. ' +
+            'Triggers: tunnel, port forward, access remote database/service, connect to internal network resource.',
+        parameters: {
+            alias: { type: 'string', required: true, description: 'Configured host alias.' },
+            remoteHost: { type: 'string', required: true, description: 'Remote host to reach (often 127.0.0.1 on the remote side).' },
+            remotePort: { type: 'integer', required: true, description: 'Remote port to forward.' },
+            localPort: { type: 'integer', description: 'Optional local listen port (0 = auto-assign).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    localPort: { type: 'integer', required: true },
+                    remoteHost: { type: 'string', required: true },
+                    remotePort: { type: 'integer', required: true },
+                },
+            },
+            render: (_args, value) => text(`tunnel listening on 127.0.0.1:${value.localPort} -> ${value.remoteHost}:${value.remotePort}`),
+        },
+        async execute(args) {
+            const result = await engine.tunnel(args.alias, typeof args.localPort === 'number' ? args.localPort : 0, args.remoteHost, args.remotePort);
+            return { localPort: result.localPort, remoteHost: args.remoteHost, remotePort: args.remotePort };
+        },
+    });
+}
+export function sshClusterTool(engine) {
+    return defineTool({
+        name: 'ssh_cluster',
+        description: 'Run the same command concurrently on multiple hosts and return per-host results. ' +
+            'Triggers: run on all servers, batch operation, production servers, cluster command.',
+        parameters: {
+            aliases: { type: 'array', items: { type: 'string' }, required: true, description: 'Configured host aliases to run on.' },
+            command: { type: 'string', required: true, description: 'The shell command to run on every host.' },
+            timeoutMs: { type: 'integer', description: 'Optional per-host timeout in milliseconds (default 120000). When it fires the channel is closed and the remote command is terminated.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    results: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                alias: { type: 'string', required: true },
+                                ok: { type: 'boolean', required: true },
+                                exitCode: { oneOf: [{ type: 'integer' }, { type: 'null' }] },
+                                timedOut: { type: 'boolean' },
+                                stdout: { type: 'string' },
+                                stderr: { type: 'string' },
+                                durationMs: { type: 'integer' },
+                                error: { type: 'string' },
+                            },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => text(value.results.map(r => `=== ${r.alias} ===\n${[r.stdout, r.stderr].filter(Boolean).join('\n') || (r.ok ? 'ok' : r.error ?? 'fail')}`).join('\n')),
+        },
+        async execute(args) {
+            const results = await engine.cluster({
+                aliases: args.aliases,
+                command: args.command,
+                timeoutMs: typeof args.timeoutMs === 'number' ? args.timeoutMs : undefined,
+            });
+            return { results };
+        },
+    });
+}
+/** 全部 ssh agent 工具。 */
+export function makeSshTools(engine, _store) {
+    return [
+        sshListTool(engine),
+        sshExecTool(engine),
+        sshUploadTool(engine),
+        sshDownloadTool(engine),
+        sshTunnelTool(engine),
+        sshClusterTool(engine),
+    ];
+}

package/lib/types/host/services/web-render/contracts.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 渲染式抓取的契约、设置 schema 与默认值 —— host 半区。
+ *
+ * 原生 `dsh-web-fetch-http` 走的是纯 HTTP GET，交给 `dsh-tool-web` 转 markdown；
+ * 对客户端渲染页面（SPA、懒加载列表、内容靠 XHR 回填）拿到的只是一个空壳。
+ * 本域向 `ctx.web` 注册第二个 fetch provider（id `browser`），用真实 Chromium
+ * 执行页面脚本后返回**渲染后的 DOM**，`body.kind` 仍是 `html`，因此
+ * HTML→markdown、GFM 表格、截断与结果包装仍由 `dsh-tool-web` 负责，
+ * 模型侧的工具名、schema 与提示词完全不变。
+ *
+ * 与 `playwright-sessions` 不共享启动器：那个域按规划会随 `@playwright/mcp`
+ * 一起退役，渲染能力不能跟着断，所以这里自包含一个共享 Chromium 实例。
+ *
+ * @module web-all/host/services/web-render
+ */
+import z from 'schemastery';
+/** 设置命名空间：`web-render`。 */
+export declare const WEB_RENDER_SETTINGS_NAMESPACE = "web-render";
+/** 注册到 `ctx.web` 的 provider id；bundle patch 用它 pin `fetchProvider`。 */
+export declare const WEB_RENDER_PROVIDER_ID = "browser";
+/** 用户可配置面（也是设置文档里该命名空间的字段）。 */
+export interface WebRenderConfig {
+    /** 关闭后本域不注册 provider，`web_fetch` 回到原生 HTTP 行为。 */
+    enabled?: boolean;
+    /** 无头运行。 */
+    headless?: boolean;
+    /** 依次尝试的 Chromium 通道（chrome / msedge / chromium）。 */
+    browserChannels?: string[];
+    /** 显式 Chromium 可执行文件路径；设置后不再按通道尝试。 */
+    executablePath?: string;
+    /** 持久化 Chrome profile 目录；留空则用 <DSH_HOME>/cache/web-render/chrome-profile。 */
+    userDataDir?: string;
+    /** 单次抓取硬上限（导航 + 等待渲染）。 */
+    timeoutMs?: number;
+    /** 导航等待条件；SPA 通常 domcontentloaded 后由 networkIdleMs 兜底。 */
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+    /** 加载后尽力等网络空闲的上限；0 表示不等。 */
+    networkIdleMs?: number;
+    /** 网络空闲后的额外稳定期，等末帧绘制/字体。 */
+    settleMs?: number;
+    /** `html` 返回渲染后的 DOM（保留表格结构）；`text` 只返回可见文本。 */
+    extract?: 'html' | 'text';
+    /** 返回字符上限，与 `dsh-tool-web` 自身的上限对齐。 */
+    maxBodyChars?: number;
+    viewportWidth?: number;
+    viewportHeight?: number;
+    /** 追加的 Chrome 启动参数，例如 ['--proxy-server=http://127.0.0.1:7890']。 */
+    args?: string[];
+}
+/** 运行时的权威 schema；导出后该命名空间才会出现在设置文档里。 */
+export declare const Config: z<WebRenderConfig>;
+/** 解析后的配置：字段全部落地，无 undefined。 */
+export type ResolvedWebRenderConfig = Required<WebRenderConfig>;
+/** 提取一份可用配置：未配置的字段取 schema 默认值。 */
+export declare function effectiveConfig(config: WebRenderConfig | undefined): ResolvedWebRenderConfig;
+/** 未显式指定 profile 时的默认目录（登录态可长期保存在这里）。 */
+export declare function defaultUserDataDir(dshHome: string): string;
+/** 一次抓取请求；seam 只传 url。 */
+export interface WebFetchRequest {
+    readonly url: string;
+}
+/** 解码后的正文；本域只产出 html 或 text。 */
+export interface WebFetchBody {
+    readonly kind: 'html' | 'text';
+    readonly content: string;
+}
+/** 一次抓取结果；非 2xx 仍是结果而非异常。 */
+export interface WebFetchResult {
+    readonly url: string;
+    readonly statusCode: number;
+    readonly body: WebFetchBody;
+    readonly truncated: boolean;
+}
+/** 一个 fetch 后端。 */
+export interface WebFetchProvider {
+    readonly id: string;
+    /** 廉价的本地可用性检查；不得发起网络请求。 */
+    available(): boolean;
+    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+}
+/** `ctx.web` 上本域用到的部分。 */
+export interface WebSeam {
+    registerFetchProvider(provider: WebFetchProvider): () => void;
+}
+/**
+ * 抓取失败。形状对齐 `WebError`（带机器可路由的 `code`），
+ * 由 `dsh-tool-web` 包装成模型可读的 `Error: <message>`。
+ */
+export declare class WebRenderError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+//# sourceMappingURL=contracts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/web-render/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,CAAC,MAAM,aAAa,CAAA;AAG3B,2BAA2B;AAC3B,eAAO,MAAM,6BAA6B,eAAe,CAAA;AAEzD,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,YAAY,CAAA;AAE/C,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,YAAY;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,qDAAqD;IACrD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,aAAa,GAAG,QAAQ,CAAA;IAClE,4BAA4B;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,wCAAwC;AACxC,eAAO,MAAM,MAAM,EAeF,CAAC,CAAC,eAAe,CAAC,CAAA;AAInC,iCAAiC;AACjC,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC,eAAe,CAAC,CAAA;AAE/D,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,GAAG,uBAAuB,CAE5F;AAED,yCAAyC;AACzC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAMD,0BAA0B;AAC1B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED,mBAAmB;AACnB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,2BAA2B;IAC3B,SAAS,IAAI,OAAO,CAAA;IACpB,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;CAC/E;AAED,0BAA0B;AAC1B,MAAM,WAAW,OAAO;IACtB,qBAAqB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAAA;CAC9D;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-render/contracts.js

@@ -0,0 +1,60 @@
+/**
+ * 渲染式抓取的契约、设置 schema 与默认值 —— host 半区。
+ *
+ * 原生 `dsh-web-fetch-http` 走的是纯 HTTP GET，交给 `dsh-tool-web` 转 markdown；
+ * 对客户端渲染页面（SPA、懒加载列表、内容靠 XHR 回填）拿到的只是一个空壳。
+ * 本域向 `ctx.web` 注册第二个 fetch provider（id `browser`），用真实 Chromium
+ * 执行页面脚本后返回**渲染后的 DOM**，`body.kind` 仍是 `html`，因此
+ * HTML→markdown、GFM 表格、截断与结果包装仍由 `dsh-tool-web` 负责，
+ * 模型侧的工具名、schema 与提示词完全不变。
+ *
+ * 与 `playwright-sessions` 不共享启动器：那个域按规划会随 `@playwright/mcp`
+ * 一起退役，渲染能力不能跟着断，所以这里自包含一个共享 Chromium 实例。
+ *
+ * @module web-all/host/services/web-render
+ */
+import { join } from 'node:path';
+import z from 'schemastery';
+import { registerFamilyNamespace } from "../family-config.js";
+/** 设置命名空间：`web-render`。 */
+export const WEB_RENDER_SETTINGS_NAMESPACE = 'web-render';
+/** 注册到 `ctx.web` 的 provider id；bundle patch 用它 pin `fetchProvider`。 */
+export const WEB_RENDER_PROVIDER_ID = 'browser';
+/** 运行时的权威 schema；导出后该命名空间才会出现在设置文档里。 */
+export const Config = z.object({
+    enabled: z.boolean().default(true),
+    headless: z.boolean().default(true),
+    browserChannels: z.array(z.string()).default(['chrome', 'msedge', 'chromium']),
+    executablePath: z.string().default(''),
+    userDataDir: z.string().default(''),
+    timeoutMs: z.number().step(1).min(1).default(20_000),
+    waitUntil: z.union(['load', 'domcontentloaded', 'networkidle', 'commit']).default('domcontentloaded'),
+    networkIdleMs: z.number().step(1).min(0).default(2_500),
+    settleMs: z.number().step(1).min(0).default(400),
+    extract: z.union(['html', 'text']).default('html'),
+    maxBodyChars: z.number().step(1).min(1).default(200_000),
+    viewportWidth: z.number().step(1).min(1).default(1_280),
+    viewportHeight: z.number().step(1).min(1).default(900),
+    args: z.array(z.string()).default([]),
+});
+registerFamilyNamespace(WEB_RENDER_SETTINGS_NAMESPACE, Config);
+/** 提取一份可用配置：未配置的字段取 schema 默认值。 */
+export function effectiveConfig(config) {
+    return Config(config ?? {});
+}
+/** 未显式指定 profile 时的默认目录（登录态可长期保存在这里）。 */
+export function defaultUserDataDir(dshHome) {
+    return join(dshHome, 'cache', 'web-render', 'chrome-profile');
+}
+/**
+ * 抓取失败。形状对齐 `WebError`（带机器可路由的 `code`），
+ * 由 `dsh-tool-web` 包装成模型可读的 `Error: <message>`。
+ */
+export class WebRenderError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'WebError';
+        this.code = code;
+    }
+}

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

@@ -0,0 +1,58 @@
+/**
+ * 渲染式抓取服务域 —— 向 `ctx.web` 注册 `browser` fetch provider。
+ *
+ * ## 为什么注册是"只要 web 在就注册"
+ *
+ * bundle patch 把 `@deepseek-ai/dsh-web` 的 `fetchProvider` pin 成 `browser`，
+ * 否则 `http` 与本 provider 同时可用会让每次抓取都以
+ * `WEB_PROVIDER_AMBIGUOUS` 失败。pin 生效后，映射关系是：
+ *
+ * | 情况 | seam 结果 |
+ * |---|---|
+ * | provider 已注册且可用 | 正常渲染抓取 |
+ * | provider 已注册但 `available()` 为假 | `WEB_PROVIDER_CONFIGURED_UNAVAILABLE` |
+ * | provider 未注册 | `WEB_PROVIDER_CONFIGURED_MISSING` |
+ *
+ * 后两者都会让 `web_fetch` **整体不可用**。因此这里选择"只要 web 服务在就注册"，
+ * 让映射始终成立：没有可用浏览器时在注册期写一条明确告警，运行期由 seam 给出
+ * 可操作的错误，而不是留下一个静默失败的 pin。
+ *
+ * 要彻底关掉本域，必须**同时**把 `fetchProvider` 改回 `http`（见 cordis.patch.yml
+ * 的注释），单独设 `enabled: false` 会复现 MISSING。
+ *
+ * ## 为什么用局部 inject
+ *
+ * 0.2 严格注入下，插件只能访问自己 inject 声明过的服务。这里用
+ * `ctx.inject(['web'], …)` 等待，而不是把 `web` 写进 web-all 的全局 inject：
+ * 那会让整个全家桶在缺少 web 服务的 profile 里直接挂掉。
+ *
+ * ## 配置读取
+ *
+ * `web-render` 是聚合 Config 里的一个 volatile 命名空间，不是装配参数，
+ * 因此按家族惯例用 `familyNamespace()` 读取；provider 拿到的是**读取函数**而非
+ * 快照，设置面板改无头/超时/视口可即时生效，无需重挂插件。
+ *
+ * @module web-all/host/services/web-render
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type WebRenderConfig } from './contracts.ts';
+export interface WebRenderRegistrationOptions {
+    /** 用户 dsh 配置根，用于推导默认的持久化 profile 目录。 */
+    dshHome?: string;
+    /** 结构化告警出口；缺省写 console。 */
+    logger?: {
+        warn: (message: string) => void;
+    };
+    /** 显式配置（测试用）。缺省时从 `web-render` 命名空间读取。 */
+    config?: WebRenderConfig;
+}
+/**
+ * 注册渲染式 fetch provider。
+ * @param ctx - host plugin context。
+ * @param options - dshHome 与告警出口。
+ * @returns 卸载回调：注销 provider 并关闭浏览器。
+ */
+export declare function register(ctx: Context, options?: WebRenderRegistrationOptions): () => void;
+export { WEB_RENDER_PROVIDER_ID, WEB_RENDER_SETTINGS_NAMESPACE, effectiveConfig, type WebRenderConfig } from './contracts.ts';
+export { RenderFetchProvider } from './provider.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/web-render/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,gBAAgB,CAAA;AAGvB,MAAM,WAAW,4BAA4B;IAC3C,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2BAA2B;IAC3B,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAA;IAC5C,0CAA0C;IAC1C,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,4BAAiC,GAAG,MAAM,IAAI,CA0C7F;AAED,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAC7H,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA"}

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

@@ -0,0 +1,90 @@
+/**
+ * 渲染式抓取服务域 —— 向 `ctx.web` 注册 `browser` fetch provider。
+ *
+ * ## 为什么注册是"只要 web 在就注册"
+ *
+ * bundle patch 把 `@deepseek-ai/dsh-web` 的 `fetchProvider` pin 成 `browser`，
+ * 否则 `http` 与本 provider 同时可用会让每次抓取都以
+ * `WEB_PROVIDER_AMBIGUOUS` 失败。pin 生效后，映射关系是：
+ *
+ * | 情况 | seam 结果 |
+ * |---|---|
+ * | provider 已注册且可用 | 正常渲染抓取 |
+ * | provider 已注册但 `available()` 为假 | `WEB_PROVIDER_CONFIGURED_UNAVAILABLE` |
+ * | provider 未注册 | `WEB_PROVIDER_CONFIGURED_MISSING` |
+ *
+ * 后两者都会让 `web_fetch` **整体不可用**。因此这里选择"只要 web 服务在就注册"，
+ * 让映射始终成立：没有可用浏览器时在注册期写一条明确告警，运行期由 seam 给出
+ * 可操作的错误，而不是留下一个静默失败的 pin。
+ *
+ * 要彻底关掉本域，必须**同时**把 `fetchProvider` 改回 `http`（见 cordis.patch.yml
+ * 的注释），单独设 `enabled: false` 会复现 MISSING。
+ *
+ * ## 为什么用局部 inject
+ *
+ * 0.2 严格注入下，插件只能访问自己 inject 声明过的服务。这里用
+ * `ctx.inject(['web'], …)` 等待，而不是把 `web` 写进 web-all 的全局 inject：
+ * 那会让整个全家桶在缺少 web 服务的 profile 里直接挂掉。
+ *
+ * ## 配置读取
+ *
+ * `web-render` 是聚合 Config 里的一个 volatile 命名空间，不是装配参数，
+ * 因此按家族惯例用 `familyNamespace()` 读取；provider 拿到的是**读取函数**而非
+ * 快照，设置面板改无头/超时/视口可即时生效，无需重挂插件。
+ *
+ * @module web-all/host/services/web-render
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { familyNamespace } from "../family-config.js";
+import { defaultUserDataDir, effectiveConfig, WEB_RENDER_SETTINGS_NAMESPACE, } from "./contracts.js";
+import { RenderFetchProvider } from "./provider.js";
+/**
+ * 注册渲染式 fetch provider。
+ * @param ctx - host plugin context。
+ * @param options - dshHome 与告警出口。
+ * @returns 卸载回调：注销 provider 并关闭浏览器。
+ */
+export function register(ctx, options = {}) {
+    const warn = options.logger?.warn ?? ((message) => console.warn(message));
+    const readConfig = () => {
+        const raw = options.config ?? familyNamespace(WEB_RENDER_SETTINGS_NAMESPACE);
+        return effectiveConfig(raw);
+    };
+    const initial = readConfig();
+    if (!initial.enabled)
+        return () => undefined;
+    const home = options.dshHome ?? process.env['DSH_HOME'] ?? join(homedir(), '.dsh');
+    // profile 目录只解析一次：改它需要换浏览器实例，属于重挂语义。
+    const userDataDir = initial.userDataDir.trim() !== '' ? initial.userDataDir.trim() : defaultUserDataDir(home);
+    const provider = new RenderFetchProvider(readConfig, userDataDir, warn);
+    if (!provider.available()) {
+        warn(`[web-all:web-render] 未找到可用浏览器（channels=${initial.browserChannels.join('/')}，executablePath=${initial.executablePath === '' ? '未设' : initial.executablePath}）：`
+            + 'web_fetch 仍被 pin 到 browser provider，调用会以 WEB_PROVIDER_UNAVAILABLE 失败；'
+            + '请安装 Google Chrome 或设置 web-render 的 executablePath，或把 web 行的 fetchProvider 改回 http');
+    }
+    let disposed = false;
+    let unregister;
+    try {
+        ctx.inject(['web'], (cctx) => {
+            if (disposed)
+                return;
+            const seam = cctx.web;
+            if (seam?.registerFetchProvider === undefined)
+                return;
+            unregister = seam.registerFetchProvider(provider);
+        });
+    }
+    catch (error) {
+        // 组合里没有 web 服务：本域静默缺席，绝不影响全家桶其余能力。
+        warn(`[web-all:web-render] 等待 web 服务失败，本域缺席：${error instanceof Error ? error.message : String(error)}`);
+        return () => undefined;
+    }
+    return () => {
+        disposed = true;
+        unregister?.();
+        void provider.dispose();
+    };
+}
+export { WEB_RENDER_PROVIDER_ID, WEB_RENDER_SETTINGS_NAMESPACE, effectiveConfig } from "./contracts.js";
+export { RenderFetchProvider } from "./provider.js";

package/lib/types/host/services/web-render/provider.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 用真实 Chromium 渲染页面的 fetch provider。
+ *
+ * 一个 Chromium 实例懒启动、跨次复用，每次抓取开新页面；插件卸载时关闭。
+ * 配置按**每次抓取**从注入的读取器取，因此 `web-render` 命名空间的 volatile
+ * 热更新（无头/超时/视口等）立即生效，无需重挂插件。
+ *
+ * `available()` 只做本地文件检查，不发网络请求（seam 的硬要求）。
+ *
+ * @module web-all/host/services/web-render
+ */
+import { type ResolvedWebRenderConfig, type WebFetchProvider, type WebFetchRequest, type WebFetchResult } from './contracts.ts';
+/** 用真实 Chromium 渲染页面的抓取后端。 */
+export declare class RenderFetchProvider implements WebFetchProvider {
+    #private;
+    readonly id = "browser";
+    /** 持久化 profile 目录；非空时用 launchPersistentContext 保住登录态。 */
+    readonly userDataDir: string;
+    /**
+     * @param readConfig - 每次取值时重新解析配置（命名空间 volatile 热更新可见）。
+     * @param userDataDir - 持久化 Chrome profile 目录；空串表示用临时上下文。
+     * @param warn - 告警出口（profile 被占用降级等）。
+     */
+    constructor(readConfig: () => ResolvedWebRenderConfig, userDataDir: string, warn?: (message: string) => void);
+    /** 廉价的本地检查：必须有一个能启动的浏览器。 */
+    available(): boolean;
+    /**
+     * 渲染并取回一个 URL。
+     * 非 2xx 作为结果返回（状态码是资源状态的一部分），不抛异常。
+     * @param request - seam 的抓取请求。
+     * @param signal - 工具调用超时策略下发的取消信号。
+     */
+    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+    /** 关闭共享浏览器并停止接受抓取。 */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/lib/types/host/services/web-render/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/web-render/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EAGL,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAA;AAqDvB,8BAA8B;AAC9B,qBAAa,mBAAoB,YAAW,gBAAgB;;IAC1D,QAAQ,CAAC,EAAE,aAAyB;IAEpC,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAY5B;;;;OAIG;gBACS,UAAU,EAAE,MAAM,uBAAuB,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;IAM5G,4BAA4B;IAC5B,SAAS,IAAI,OAAO;IAOpB;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC;IAgJpF,sBAAsB;IAChB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAkB/B"}