@mokuyoaxis/dsh-iris 0.1.2 → 0.1.4

package/lib/provider-adapters.js

@@ -0,0 +1,279 @@
+'use strict';
+
+/**
+ * 已支持协议到 Provider Adapter v0 的映射。
+ *
+ * 凭据和 baseUrl 只被操作闭包捕获，不进入 Adapter 描述或能力快照。
+ * transport 默认为现有低层 HTTP 实现；测试可注入零网络 fixture。
+ */
+import * as defaultTransport from './adapters.js';
+import { ProviderContractError, providerErrorRecord } from './provider-contract.js';
+import { defineProviderAdapter } from './provider-adapter.js';
+import { inferMediaProtocol } from './provider-protocol.js';
+
+const AMBIGUOUS_4XX = new Set([408, 409, 425, 499]);
+
+function providerIdentity(provider) {
+  const id = String(provider?.id || '').trim();
+  const key = String(provider?.apiKey || '');
+  const baseUrl = String(provider?.baseUrl || '').trim();
+  if (!id) throw new TypeError('Provider 配置缺少 id');
+  if (!baseUrl) throw new TypeError('Provider 配置缺少 baseUrl');
+  return { id, key, baseUrl };
+}
+
+function mappedCategory(error, status) {
+  const raw = String(error?.category || '').toLowerCase();
+  if (error?.name === 'AbortError' || error?.code === 'ABORT_ERR') return 'aborted';
+  if (error?.name === 'TimeoutError' || /timeout|timed out|超时/i.test(String(error?.message || ''))) return 'timeout';
+  if (status === 401 || status === 403 || raw === 'auth') return 'authentication';
+  if (status === 429 && raw === 'quota') return 'quota';
+  if (status === 429 || raw === 'rate_limit') return 'rate_limit';
+  if (raw === 'invalid_parameter') return 'invalid_request';
+  if (raw === 'network' || error instanceof TypeError) return 'network';
+  if (raw === 'server' || status >= 500) return 'provider';
+  if (!status && /未返回|响应|协议|结构|json/i.test(String(error?.message || ''))) return 'protocol';
+  return 'provider';
+}
+
+/** 当前两个协议共享的错误映射；不保留 cause、rootCause、正文、URL 或凭据。 */
+export function mapProviderAdapterError(error, context = {}) {
+  const statusValue = Number(error?.httpStatus ?? error?.status);
+  const httpStatus = Number.isInteger(statusValue) && statusValue >= 100 && statusValue <= 599
+    ? statusValue
+    : undefined;
+  const stage = String(context.stage || error?.stage || 'submit');
+  const category = mappedCategory(error, httpStatus);
+  let acceptance = context.acceptance || error?.acceptance;
+  if (stage === 'validate' || stage === 'prepare' || stage === 'upload') {
+    acceptance = 'not_accepted';
+  } else if (stage === 'submit') {
+    acceptance = httpStatus && httpStatus >= 400 && httpStatus < 500 && !AMBIGUOUS_4XX.has(httpStatus)
+      ? 'not_accepted'
+      : (error?.acceptance === 'not_accepted' ? 'not_accepted' : 'unknown');
+  } else if (!acceptance) {
+    acceptance = 'accepted';
+  }
+  const retryable = Boolean(
+    context.retryable ?? error?.retryable
+    ?? (httpStatus === 429 || (httpStatus && httpStatus >= 500)
+      || category === 'network' || category === 'timeout')
+  );
+  return providerErrorRecord(error, {
+    stage,
+    category,
+    acceptance,
+    retryable,
+    ...(httpStatus ? { httpStatus } : {})
+  });
+}
+
+function unsupportedCapability(capability, protocol) {
+  return new ProviderContractError(
+    '协议 ' + protocol + ' 不支持任务能力 ' + String(capability || ''),
+    { stage: 'validate', category: 'invalid_request', acceptance: 'not_accepted' }
+  );
+}
+
+function pollFailureKind(status) {
+  const value = String(status || '').toUpperCase();
+  if (value === 'CANCELED' || value === 'CANCELLED') return 'canceled';
+  if (value === 'UNKNOWN') return 'unknown';
+  return 'failed';
+}
+
+function operationsForDashScope(provider, transport) {
+  const { key, baseUrl } = providerIdentity(provider);
+  return {
+    async discover({ signal, timeoutMs } = {}) {
+      return { models: await transport.listModels({ key, baseUrl, signal, timeoutMs }) };
+    },
+
+    async submit(request = {}) {
+      const input = request.input || {};
+      const common = {
+        key, baseUrl, model: request.model, signal: request.signal,
+        ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
+      };
+      if (request.capability === 'image') {
+        if (transport.dashscopeImageMode(request.model) === 'legacy-async') {
+          const remoteTaskId = await transport.submitImage({
+            ...common, prompt: input.prompt, size: input.size, n: input.n
+          });
+          return { kind: 'accepted', remoteTaskId };
+        }
+        const urls = await transport.generateImageMultimodal({
+          ...common, prompt: input.prompt, size: input.size, n: input.n
+        });
+        return { kind: 'completed', value: { kind: 'urls', items: urls } };
+      }
+      if (request.capability === 'video') {
+        const remoteTaskId = await transport.submitVideo({
+          ...common,
+          prompt: input.prompt,
+          imgDataUrl: input.imgDataUrl,
+          size: input.size,
+          duration: input.duration,
+          audioUrl: input.audioUrl,
+          resolution: input.resolution
+        });
+        return { kind: 'accepted', remoteTaskId };
+      }
+      if (request.capability === 'transcribe') {
+        const remoteTaskId = await transport.submitTranscription({
+          ...common, audioUrl: input.audioUrl
+        });
+        return { kind: 'accepted', remoteTaskId };
+      }
+      if (request.capability === 'tts') {
+        const value = await transport.synthesizeTts({
+          ...common, text: input.text, voice: input.voice
+        });
+        return { kind: 'completed', value };
+      }
+      throw unsupportedCapability(request.capability, 'dashscope');
+    },
+
+    async poll(request = {}) {
+      const common = {
+        key, baseUrl, remoteTaskId: request.remoteTaskId, signal: request.signal,
+        ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
+      };
+      if (request.capability === 'transcribe') {
+        const result = await transport.pollTranscriptionTask(common);
+        if (!result.done) return { kind: 'pending', progress: result.status || 'running' };
+        if (!result.ok) {
+          return {
+            kind: pollFailureKind(result.status),
+            error: mapProviderAdapterError(result.message || '转写任务失败', {
+              stage: 'poll', acceptance: 'accepted'
+            })
+          };
+        }
+        return { kind: 'succeeded', value: { kind: 'text', text: String(result.text || '') } };
+      }
+      if (request.capability === 'image' || request.capability === 'video') {
+        const result = await transport.pollTask(common);
+        if (!result.done) return { kind: 'pending', progress: result.status || 'running' };
+        if (!result.ok) {
+          return {
+            kind: pollFailureKind(result.status),
+            error: mapProviderAdapterError(result.message || '生成任务失败', {
+              stage: 'poll', acceptance: 'accepted'
+            })
+          };
+        }
+        return {
+          kind: 'succeeded',
+          artifacts: (result.urls || []).map((url) => ({ kind: 'remote-url', url }))
+        };
+      }
+      throw unsupportedCapability(request.capability, 'dashscope');
+    },
+
+    async download(request = {}) {
+      const artifact = request.artifact || {};
+      if (artifact.kind !== 'remote-url' || !artifact.url) {
+        throw new ProviderContractError('download 需要 remote-url artifact', {
+          stage: 'download', category: 'protocol', acceptance: 'accepted'
+        });
+      }
+      const targetPath = String(request.targetPath || '').trim();
+      if (!targetPath) {
+        throw new ProviderContractError('download 需要 targetPath', {
+          stage: 'download', category: 'local_io', acceptance: 'accepted'
+        });
+      }
+      return {
+        bytes: await transport.downloadTo(artifact.url, targetPath, {
+          signal: request.signal,
+          ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
+        })
+      };
+    },
+
+    mapError: mapProviderAdapterError
+  };
+}
+
+export function createDashScopeProviderAdapter(provider, { transport = defaultTransport } = {}) {
+  return defineProviderAdapter({
+    id: providerIdentity(provider).id,
+    protocol: 'dashscope',
+    capabilities: ['image', 'video', 'tts', 'transcribe'],
+    operations: operationsForDashScope(provider, transport),
+    unsupported: {
+      cancel: '当前 DashScope 媒体协议未提供经过验证的远端取消实现'
+    }
+  });
+}
+
+function operationsForOpenAiImages(provider, transport) {
+  const { key, baseUrl } = providerIdentity(provider);
+  return {
+    async discover({ signal, timeoutMs } = {}) {
+      return { models: await transport.listModels({ key, baseUrl, signal, timeoutMs }) };
+    },
+
+    async submit(request = {}) {
+      if (request.capability !== 'image') {
+        throw unsupportedCapability(request.capability, 'openai-images');
+      }
+      const input = request.input || {};
+      const items = await transport.openAiGenerateImage({
+        key,
+        baseUrl,
+        model: request.model,
+        prompt: input.prompt,
+        size: input.size,
+        n: input.n,
+        signal: request.signal,
+        ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
+      });
+      return { kind: 'completed', value: { kind: 'openai', items } };
+    },
+
+    async download(request = {}) {
+      const artifact = request.artifact || {};
+      if (artifact.kind !== 'remote-url' || !artifact.url) {
+        throw new ProviderContractError('download 需要 remote-url artifact', {
+          stage: 'download', category: 'protocol', acceptance: 'accepted'
+        });
+      }
+      const targetPath = String(request.targetPath || '').trim();
+      if (!targetPath) {
+        throw new ProviderContractError('download 需要 targetPath', {
+          stage: 'download', category: 'local_io', acceptance: 'accepted'
+        });
+      }
+      return {
+        bytes: await transport.downloadTo(artifact.url, targetPath, {
+          signal: request.signal,
+          ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
+        })
+      };
+    },
+
+    mapError: mapProviderAdapterError
+  };
+}
+
+export function createOpenAiImagesProviderAdapter(provider, { transport = defaultTransport } = {}) {
+  return defineProviderAdapter({
+    id: providerIdentity(provider).id,
+    protocol: 'openai-images',
+    capabilities: ['image'],
+    operations: operationsForOpenAiImages(provider, transport),
+    unsupported: {
+      poll: 'OpenAI Images 兼容路径在当前实现中同步返回结果',
+      cancel: '同步图片响应没有可验证的远端取消任务'
+    }
+  });
+}
+
+export function createConfiguredProviderAdapter(provider, options = {}) {
+  const protocol = options.protocol || provider?.mediaProtocol || inferMediaProtocol(provider?.baseUrl);
+  if (protocol === 'dashscope') return createDashScopeProviderAdapter(provider, options);
+  if (protocol === 'openai-images') return createOpenAiImagesProviderAdapter(provider, options);
+  throw new TypeError('iris: 不支持的 Provider 协议：' + String(protocol));
+}

package/lib/provider-contract.js

@@ -0,0 +1,234 @@
+'use strict';
+/**
+ * v0.1.3 最小 Provider 提交契约。
+ *
+ * 这里只定义提交结果、脱敏错误和候选调度边界，不依赖 DSH、配置存储或具体供应商。
+ */
+import { allowsAutomaticFailover } from './task-semantics.js';
+import { parseModelRef } from './models.js';
+
+export const SUBMISSION_KINDS = Object.freeze([
+  'completed',
+  'accepted',
+  'not_accepted',
+  'acceptance_unknown'
+]);
+
+export const PROVIDER_STAGES = Object.freeze([
+  'validate',
+  'prepare',
+  'upload',
+  'submit',
+  'response',
+  'poll',
+  'cancel',
+  'download',
+  'persist',
+  'emit'
+]);
+
+export const PROVIDER_ERROR_CATEGORIES = Object.freeze([
+  'invalid_request',
+  'authentication',
+  'quota',
+  'rate_limit',
+  'network',
+  'timeout',
+  'aborted',
+  'provider',
+  'protocol',
+  'local_io',
+  'unknown'
+]);
+
+const ACCEPTANCE = new Set(['not_accepted', 'accepted', 'unknown']);
+const SECRET_QUERY = /([?&](?:access[_-]?key|api[_-]?key|authorization|credential|signature|token)=)[^&#\s]+/gi;
+const BEARER = /\bBearer\s+[^\s,;]+/gi;
+const API_KEY = /\bsk-[A-Za-z0-9_-]{8,}\b/g;
+const JSON_SECRET = /(["']?(?:api[_-]?key|authorization|access[_-]?token|secret)["']?\s*[:=]\s*["']?)[^"',\s}]+/gi;
+const POSIX_PATH = /(^|[\s("'=])\/(?:[^/\s"'`,;)}\]]+\/)*[^/\s"'`,;)}\]]+/gm;
+const WINDOWS_PATH = /\b[A-Za-z]:\\(?:[^\\\s"'`,;)}\]]+\\)*[^\\\s"'`,;)}\]]+/g;
+
+export function redactProviderMessage(value, maxLength = 1000) {
+  return String(value || '供应商操作失败')
+    .replace(SECRET_QUERY, '$1[REDACTED]')
+    .replace(BEARER, 'Bearer [REDACTED]')
+    .replace(API_KEY, '[REDACTED]')
+    .replace(JSON_SECRET, '$1[REDACTED]')
+    .replace(WINDOWS_PATH, '[PATH]')
+    .replace(POSIX_PATH, '$1[PATH]')
+    .slice(0, maxLength);
+}
+
+function enumValue(values, value, fallback) {
+  return values.includes(value) ? value : fallback;
+}
+
+function integerOrUndefined(value) {
+  const number = Number(value);
+  return Number.isInteger(number) && number >= 100 && number <= 599 ? number : undefined;
+}
+
+/** 只返回允许持久化的结构化字段，不包含 cause、stack、请求体或响应正文。 */
+export function providerErrorRecord(error, overrides = {}) {
+  const source = error && typeof error === 'object' ? error : {};
+  const acceptance = ACCEPTANCE.has(overrides.acceptance)
+    ? overrides.acceptance
+    : (ACCEPTANCE.has(source.acceptance) ? source.acceptance : 'unknown');
+  const out = {
+    stage: enumValue(PROVIDER_STAGES, overrides.stage || source.stage, 'submit'),
+    category: enumValue(PROVIDER_ERROR_CATEGORIES, overrides.category || source.category, 'unknown'),
+    acceptance,
+    retryable: Boolean(overrides.retryable ?? source.retryable),
+    safeMessage: redactProviderMessage(overrides.safeMessage || source.safeMessage || source.message || error)
+  };
+  const httpStatus = integerOrUndefined(overrides.httpStatus ?? source.httpStatus ?? source.status);
+  if (httpStatus !== undefined) out.httpStatus = httpStatus;
+  const providerCode = overrides.providerCode ?? source.providerCode ?? source.code;
+  if (typeof providerCode === 'string' && providerCode.trim()) {
+    out.providerCode = redactProviderMessage(providerCode.trim(), 128);
+  }
+  return out;
+}
+
+export class ProviderContractError extends Error {
+  constructor(message, details = {}) {
+    super(redactProviderMessage(message));
+    this.name = 'ProviderContractError';
+    Object.assign(this, providerErrorRecord({ ...details, message }, details));
+  }
+
+  toJSON() {
+    return providerErrorRecord(this);
+  }
+}
+
+export function normalizeSubmissionResult(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('Provider submit 必须返回结构化结果');
+  }
+  if (!SUBMISSION_KINDS.includes(value.kind)) {
+    throw new TypeError('未知 Provider submit kind: ' + String(value.kind));
+  }
+  if (value.kind === 'completed') {
+    return { kind: 'completed', acceptance: 'accepted', value: value.value };
+  }
+  if (value.kind === 'accepted') {
+    const remoteTaskId = String(value.remoteTaskId || '').trim();
+    if (!remoteTaskId) throw new TypeError('accepted 结果必须包含 remoteTaskId');
+    return { kind: 'accepted', acceptance: 'accepted', remoteTaskId };
+  }
+  const acceptance = value.kind === 'not_accepted' ? 'not_accepted' : 'unknown';
+  return {
+    kind: value.kind,
+    acceptance,
+    error: providerErrorRecord(value.error, { acceptance })
+  };
+}
+
+export function resultFromThrown(error) {
+  const safe = providerErrorRecord(error);
+  if (safe.acceptance === 'not_accepted') {
+    return normalizeSubmissionResult({ kind: 'not_accepted', error: safe });
+  }
+  return normalizeSubmissionResult({ kind: 'acceptance_unknown', error: safe });
+}
+
+function safeAttemptSnapshot(attempt, result) {
+  const out = {
+    id: attempt.id,
+    ordinal: attempt.ordinal,
+    providerId: attempt.providerId,
+    model: attempt.model,
+    acceptance: result.acceptance,
+    resultKind: result.kind
+  };
+  if (result.remoteTaskId) out.remoteTaskId = result.remoteTaskId;
+  if (result.error) out.error = result.error;
+  return out;
+}
+
+/**
+ * 串行尝试 Provider 候选，并强制执行写前记录与受理边界。
+ *
+ * beforeAttempt 必须把 Attempt 写入持久化存储后再返回。afterResult 的落盘失败
+ * 会作为 localError 返回并立即停止；即使结果明确未受理，也不在证据未落盘时继续。
+ */
+export async function submitWithAcceptanceBoundary(candidates, input, hooks = {}) {
+  if (!Array.isArray(candidates) || candidates.length === 0) {
+    throw new TypeError('至少需要一个 Provider 候选');
+  }
+  if (typeof hooks.beforeAttempt !== 'function') {
+    throw new TypeError('beforeAttempt 写前持久化 Hook 必填');
+  }
+
+  const attempts = [];
+  for (let index = 0; index < candidates.length; index++) {
+    const candidate = candidates[index];
+    if (!candidate || typeof candidate.submit !== 'function') {
+      throw new TypeError(`Provider 候选 ${index + 1} 缺少 submit()`);
+    }
+    const initial = {
+      ordinal: index + 1,
+      providerId: String(candidate.id || '').trim(),
+      model: String(candidate.model || '').trim(),
+      acceptance: 'none',
+      stage: 'submitting'
+    };
+    const parsedModel = parseModelRef(initial.model);
+    if (!initial.providerId || !parsedModel || parsedModel.providerId !== initial.providerId) {
+      throw new TypeError(`Provider 候选 ${index + 1} 缺少 id、复合 model，或两者身份不一致`);
+    }
+
+    // 写前 Hook 失败时尚未调用供应商；错误原样抛出，由本地持久化层处理。
+    const persisted = await hooks.beforeAttempt({ ...initial });
+    const attemptId = persisted && typeof persisted.id === 'string' ? persisted.id.trim() : '';
+    if (!attemptId) throw new TypeError('beforeAttempt 必须返回已持久化的稳定 Attempt ID');
+    // Hook 只能补充持久化身份和可选元数据，不能改写候选 Provider、模型或 ordinal。
+    const attempt = {
+      ...initial,
+      id: attemptId,
+      ...(typeof persisted.startedAt === 'string' ? { startedAt: persisted.startedAt } : {}),
+      ...(typeof persisted.idempotencyKey === 'string' ? { idempotencyKey: persisted.idempotencyKey } : {})
+    };
+
+    let result;
+    try {
+      result = normalizeSubmissionResult(await candidate.submit(input, { attempt: { ...attempt } }));
+    } catch (error) {
+      result = resultFromThrown(error);
+    }
+
+    const snapshot = safeAttemptSnapshot(attempt, result);
+    attempts.push(snapshot);
+    if (typeof hooks.afterResult === 'function') {
+      try {
+        await hooks.afterResult({ ...snapshot });
+      } catch (error) {
+        return {
+          candidate,
+          result,
+          attempts,
+          localError: providerErrorRecord(error, {
+            stage: 'persist',
+            category: 'local_io',
+            acceptance: result.acceptance
+          })
+        };
+      }
+    }
+
+    if (!allowsAutomaticFailover(result)) {
+      return { candidate, result, attempts, localError: null };
+    }
+  }
+
+  return {
+    candidate: null,
+    result: attempts.length
+      ? { kind: 'not_accepted', acceptance: 'not_accepted', error: attempts.at(-1).error }
+      : null,
+    attempts,
+    localError: null
+  };
+}

package/lib/provider-health.js

@@ -0,0 +1,59 @@
+'use strict';
+
+export const PROVIDER_HEALTH_SCHEMA_VERSION = 1;
+export const PROVIDER_HEALTH_FRESH_MS = 7 * 24 * 60 * 60 * 1000;
+export const PROVIDER_HEALTH_STATES = Object.freeze([
+  'unconfigured',
+  'configured',
+  'verified',
+  'failed'
+]);
+
+const DEFINITIVE_FAILURES = new Set(['authentication', 'auth', 'permission']);
+
+function validTime(value) {
+  const ms = Date.parse(String(value || ''));
+  return Number.isFinite(ms) ? ms : 0;
+}
+
+export function isDefinitiveHealthFailure(value) {
+  const status = Number(value && (value.httpStatus ?? value.status));
+  const category = String(value && value.category || '').toLowerCase();
+  return status === 401 || status === 403 || DEFINITIVE_FAILURES.has(category);
+}
+
+export function healthObservationState(observation, {
+  now = Date.now(),
+  freshMs = PROVIDER_HEALTH_FRESH_MS
+} = {}) {
+  if (!observation || typeof observation !== 'object') return 'configured';
+  const successAt = validTime(observation.lastSuccess && observation.lastSuccess.at);
+  const failureAt = validTime(observation.lastFailure && observation.lastFailure.at);
+  const cutoff = Number(now) - Number(freshMs);
+
+  if (failureAt >= cutoff && failureAt >= successAt
+      && isDefinitiveHealthFailure(observation.lastFailure)) {
+    return 'failed';
+  }
+  if (successAt >= cutoff && successAt > failureAt) return 'verified';
+  return 'configured';
+}
+
+export function aggregateHealthStates(states) {
+  const list = (Array.isArray(states) ? states : []).filter((state) =>
+    PROVIDER_HEALTH_STATES.includes(state) && state !== 'unconfigured');
+  if (!list.length) return 'unconfigured';
+  if (list.includes('verified')) return 'verified';
+  if (list.includes('configured')) return 'configured';
+  return 'failed';
+}
+
+export function newestHealthEvidence(observation) {
+  const entries = [
+    observation && observation.lastSuccess,
+    observation && observation.lastFailure,
+    observation && observation.lastTransient
+  ].filter((item) => item && validTime(item.at));
+  entries.sort((a, b) => validTime(b.at) - validTime(a.at));
+  return entries[0] || null;
+}

package/lib/render.js

@@ -6,8 +6,8 @@
  *   Promise<{ png: Buffer }>
  *
  * BrowserHtmlRenderer：基于宿主 webServer 的 /iris/render/ 静态路由 +
- * dsh-builtin-browser 的 ctx.browser 服务（可选访问，软耦合）。
- * - 不 import dsh-builtin-browser 包，只在运行时探测 ctx.get('browser')
+ * DSH Host Adapter 注入的 browser 端口底层服务（可选访问，软耦合）。
+ * - 不 import dsh-builtin-browser 包，不在通用渲染层探测 DSH ctx
  * - HTML 通过宿主路由以同源 HTTP 打开（避免 file:// 的 CORS 限制）
  * - 每次调用独立临时渲染目录，用后即删
  */
@@ -25,14 +25,42 @@ export class RenderError extends Error {
   }
 }
 
+function throwIfAborted(signal) {
+  if (!signal?.aborted) return;
+  const error = new RenderError('iris_html_screenshot: 已取消');
+  error.name = 'AbortError';
+  throw error;
+}
+
+function waitForRender(ms, signal) {
+  if (!(ms > 0)) return Promise.resolve();
+  throwIfAborted(signal);
+  return new Promise((resolve, reject) => {
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', canceled);
+      resolve();
+    };
+    const canceled = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', canceled);
+      const error = new RenderError('iris_html_screenshot: 已取消');
+      error.name = 'AbortError';
+      reject(error);
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener?.('abort', canceled, { once: true });
+  });
+}
+
 /** 渲染临时目录根：$DSH_HOME/iris/v1/render/ */
 export function renderRoot() {
   return path.join(irisHome(), 'render');
 }
 
 /**
- * 基于 ctx.browser（dsh-builtin-browser）的 HTML → PNG 渲染器。
- * @param {{browser?: object, waitMs?: number}} opts browser 为 ctx.get('browser') 服务
+ * 基于 DSH Adapter 持有的原生 browser 服务完成 HTML → PNG。
+ * @param {{browser?: object, waitMs?: number}} opts browser 只在 DSH Adapter 内构造
  */
 export class BrowserHtmlRenderer {
   constructor({ browser, waitMs = 1200 }) {
@@ -40,13 +68,14 @@ export class BrowserHtmlRenderer {
     this.waitMs = waitMs;
   }
 
-  async render({ html, width, height, fullPage }) {
+  async render({ html, width, height, fullPage, signal }) {
     const b = this.browser;
     if (!b || typeof b.open !== 'function' || typeof b.openUrl !== 'function' || typeof b.screenshot !== 'function') {
-      throw new RenderError('iris: 浏览器服务不可用（ctx.get("browser") 为空）——需要启用 dsh-builtin-browser 插件');
+      throw new RenderError('iris: 浏览器服务不可用——需要启用兼容的 dsh-builtin-browser 插件');
     }
     const text = String(html || '').trim();
     if (!text) throw new RenderError('iris_html_screenshot: html 不能为空');
+    throwIfAborted(signal);
 
     // 每次调用独立子目录（随机名），写 index.html
     const dir = path.join(renderRoot(), crypto.randomBytes(6).toString('hex'));
@@ -63,13 +92,15 @@ export class BrowserHtmlRenderer {
     const pngPath = path.join(dir, 'render.png');
 
     try {
-      const session = await b.open();
+      const session = await b.open({ signal });
+      throwIfAborted(signal);
       try {
-        await b.openUrl(session, { url, newTab: true });
-        if (this.waitMs > 0) {
-          await new Promise((r) => setTimeout(r, this.waitMs)); // 等页面加载（无加载完成事件可用的折中）
-        }
-        await b.screenshot(session, { fullPage: fullPage !== false, savePath: pngPath });
+        await b.openUrl(session, { url, newTab: true, signal });
+        throwIfAborted(signal);
+        await waitForRender(this.waitMs, signal); // 等页面加载（无加载完成事件可用的折中）
+        throwIfAborted(signal);
+        await b.screenshot(session, { fullPage: fullPage !== false, savePath: pngPath, signal });
+        throwIfAborted(signal);
       } finally {
         try { await b.close(session); } catch (_) { /* 幂等 */ }
       }