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

package/src/host/services/ssh/tools.ts

@@ -0,0 +1,279 @@
+/**
+ * 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'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { SshEngine } from './engine.ts'
+import type { HostStore } from './store.ts'
+import type { ExecResult, SshHostSummary } from '../../../core/ssh/protocol.ts'
+
+/** 纯文本内容块（这些工具唯一渲染形状）。 */
+function text(value: string): ContentBlock[] {
+  return [{ type: 'text', text: value }]
+}
+
+/** 主机表格渲染。 */
+function renderHosts(hosts: SshHostSummary[]): string {
+  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: ExecResult): string {
+  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: SshEngine) {
+  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: { hosts?: SshHostSummary[] }) => text(renderHosts(value.hosts ?? [])),
+    },
+    async execute(args) {
+      return { hosts: engine.list(args.query) }
+    },
+  })
+}
+
+export function sshExecTool(engine: SshEngine) {
+  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: ExecResult) => 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: SshEngine) {
+  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: { bytes: number; files: number }) => 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: SshEngine) {
+  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: { localPath: string; bytes: number }) => 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<Buffer>((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: SshEngine) {
+  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: { localPort: number; remoteHost: string; remotePort: number }) =>
+        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: SshEngine) {
+  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: { results: Array<{ alias: string; ok: boolean; stdout?: string; stderr?: string; error?: string }> }) =>
+        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: SshEngine, _store: HostStore): Array<ReturnType<typeof sshListTool>> {
+  return [
+    sshListTool(engine),
+    sshExecTool(engine),
+    sshUploadTool(engine),
+    sshDownloadTool(engine),
+    sshTunnelTool(engine),
+    sshClusterTool(engine),
+  ]
+}

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

@@ -0,0 +1,138 @@
+/**
+ * 渲染式抓取的契约、设置 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.ts'
+
+/** 设置命名空间：`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'
+
+/** 用户可配置面（也是设置文档里该命名空间的字段）。 */
+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 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'] as const).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'] as const).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([]),
+}) as unknown as z<WebRenderConfig>
+
+registerFamilyNamespace(WEB_RENDER_SETTINGS_NAMESPACE, Config)
+
+/** 解析后的配置：字段全部落地，无 undefined。 */
+export type ResolvedWebRenderConfig = Required<WebRenderConfig>
+
+/** 提取一份可用配置：未配置的字段取 schema 默认值。 */
+export function effectiveConfig(config: WebRenderConfig | undefined): ResolvedWebRenderConfig {
+  return Config(config ?? {}) as ResolvedWebRenderConfig
+}
+
+/** 未显式指定 profile 时的默认目录（登录态可长期保存在这里）。 */
+export function defaultUserDataDir(dshHome: string): string {
+  return join(dshHome, 'cache', 'web-render', 'chrome-profile')
+}
+
+// ——— `ctx.web` 的结构面 ———
+// 家族惯例是不 import 原生包类型（版本各自漂移），只按行为断言所需的缝面。
+// 与 `@deepseek-ai/dsh-web` 的 `WebFetchRequest/Result/Provider` 形状一致。
+
+/** 一次抓取请求；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 class WebRenderError extends Error {
+  readonly code: string
+
+  constructor(message: string, code: string) {
+    super(message)
+    this.name = 'WebError'
+    this.code = code
+  }
+}

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

@@ -0,0 +1,112 @@
+/**
+ * 渲染式抓取服务域 —— 向 `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 type { Context } from '@deepseek-ai/cordis'
+import { familyNamespace } from '../family-config.ts'
+import {
+  defaultUserDataDir,
+  effectiveConfig,
+  WEB_RENDER_SETTINGS_NAMESPACE,
+  type ResolvedWebRenderConfig,
+  type WebRenderConfig,
+  type WebSeam,
+} from './contracts.ts'
+import { RenderFetchProvider } from './provider.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 function register(ctx: Context, options: WebRenderRegistrationOptions = {}): () => void {
+  const warn = options.logger?.warn ?? ((message: string): void => console.warn(message))
+  const readConfig = (): ResolvedWebRenderConfig => {
+    const raw = options.config ?? familyNamespace<WebRenderConfig>(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: (() => void) | undefined
+
+  try {
+    ctx.inject(['web'], (cctx) => {
+      if (disposed) return
+      const seam = (cctx as Context & { web?: WebSeam }).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, type WebRenderConfig } from './contracts.ts'
+export { RenderFetchProvider } from './provider.ts'