@mokuyoaxis/dsh-iris 0.2.0 → 0.2.1

package/lib/adapters.js

@@ -3,6 +3,8 @@
  * Iris 媒体生成后端 —— 多协议适配器。
  * - dashscope：阿里云百炼（图像/视频异步任务 + qwen-tts 同步）
  * - openai-images：OpenAI Images 兼容协议（generations）
+ * - openai-chat-images：网关 Chat Completions 生图扩展（非流式）
+ * - openai-responses-images：Responses image_generation 工具及网关图片消息（同步）
  * 所有函数只收显式 key；错误统一 throw Error(人话)。
  */
 import fs from 'node:fs';
@@ -11,6 +13,8 @@ import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { dashscopeApiBase, isDashScopeBaseUrl } from './provider-protocol.js';
 import { chmodPrivateFile, ensurePrivateDir, privateSibling } from './private-storage.js';
+import { isFreeQuotaExhausted, retryAfterDelay } from './provider-health.js';
+import { ProviderContractError } from './provider-contract.js';
 
 /**
  * 网络调用超时档位（2026-09-03 健康检查）：挂死的连接绝不能冻住盯守 tick——
@@ -53,26 +57,31 @@ async function readJson(res) {
  * message 保持人话（向后兼容 String(err.message)）。
  */
 export class ProviderError extends Error {
-  constructor({ category, status, message, rootCause }) {
+  constructor({ category, status, message, rootCause, providerCode, retryAfterMs }) {
     super(message);
     this.name = 'ProviderError';
     this.category = category;
     this.status = status;
     this.rootCause = rootCause;
+    this.providerCode = providerCode;
+    this.retryAfterMs = retryAfterMs;
   }
 }
 
-function classifyHttpError(status, body, fallback) {
-  const msg = (body && (body.message || (body.output && body.output.message))) || (body && body.code) || `HTTP ${status}`;
-  const code = String((body && body.code) || '');
+function classifyHttpError(status, body, fallback, headers) {
+  const msg = body?.message || body?.output?.message || body?.error?.message || body?.code || `HTTP ${status}`;
+  const code = String(body?.code || body?.error?.code || '');
   let category = 'unknown';
   let text;
-  if (status === 401 || status === 403) {
+  if (isFreeQuotaExhausted({ status, code, message: msg })) {
+    category = 'quota';
+    text = `免费额度耗尽：${msg}`;
+  } else if (status === 401 || status === 403) {
     category = 'auth';
     text = `鉴权失败：${msg}`;
   } else if (status === 429) {
-    category = /quota|insufficient|balance|limit|额度/i.test(msg + ' ' + code) ? 'quota' : 'rate_limit';
-    text = `限流或额度不足：${msg}`;
+    category = code === 'BudgetLimitExceeded' ? 'quota' : 'rate_limit';
+    text = `${category === 'quota' ? '预算额度耗尽' : '请求限流'}：${msg}`;
   } else if (/InvalidParameter|NotFound\.Model|unsupported/i.test(code)) {
     category = 'invalid_parameter';
     text = `模型或参数不受支持：${msg}`;
@@ -82,7 +91,8 @@ function classifyHttpError(status, body, fallback) {
   } else {
     text = `${fallback}：${msg}`;
   }
-  return new ProviderError({ category, status, message: text, rootCause: msg });
+  return new ProviderError({ category, status, message: text, rootCause: msg, providerCode: code,
+    ...(status === 429 ? { retryAfterMs: retryAfterDelay(headers?.get('retry-after')) } : {}) });
 }
 
 /** 包装 fetch 层的网络异常（无 HTTP 状态） */
@@ -96,8 +106,8 @@ export function networkError(err) {
   return e;
 }
 
-function providerError(status, body, fallback) {
-  return classifyHttpError(status, body, fallback);
+function providerError(status, body, fallback, headers) {
+  return classifyHttpError(status, body, fallback, headers);
 }
 
 /* ---------------- DashScope：图像（旧异步 / 新版多模态） ---------------- */
@@ -129,7 +139,7 @@ export async function generateImageMultimodal({ key, baseUrl, model, prompt, siz
     })
   });
   const body = await readJson(res);
-  if (!res.ok) throw providerError(res.status, body, '生成失败');
+  if (!res.ok) throw providerError(res.status, body, '生成失败', res.headers);
   const urls = [];
   for (const choice of (body && body.output && body.output.choices) || []) {
     for (const item of (choice && choice.message && choice.message.content) || []) {
@@ -157,7 +167,7 @@ export async function submitImage({ key, baseUrl, model, prompt, size, n = 1, ti
     body: JSON.stringify({ model, input: { prompt }, parameters: { ...(size ? { size } : {}), n: Number(n) || 1 } })
   });
   const body = await readJson(res);
-  if (!res.ok) throw providerError(res.status, body, '提交失败');
+  if (!res.ok) throw providerError(res.status, body, '提交失败', res.headers);
   const taskId = body && body.output && body.output.task_id;
   if (!taskId) throw new Error('提交成功但未返回 task_id');
   return taskId;
@@ -199,7 +209,7 @@ export async function submitVideo({ key, baseUrl, model, prompt, imgDataUrl, siz
     body: JSON.stringify({ model, input, parameters })
   });
   const body = await readJson(res);
-  if (!res.ok) throw providerError(res.status, body, '提交失败');
+  if (!res.ok) throw providerError(res.status, body, '提交失败', res.headers);
   const taskId = body && body.output && body.output.task_id;
   if (!taskId) throw new Error('提交成功但未返回 task_id');
   return taskId;
@@ -218,7 +228,7 @@ export async function uploadTempFile({ key, baseUrl, model, filePath, timeoutMs
   u.searchParams.set('model', model);
   const pres = await fetch(u, { headers: authHeaders(key), signal: timeoutSignal(timeoutMs, signal) });
   const pbody = await readJson(pres);
-  if (!pres.ok || !pbody || !pbody.data) throw providerError(pres.status, pbody, '获取上传凭证失败');
+  if (!pres.ok || !pbody || !pbody.data) throw providerError(pres.status, pbody, '获取上传凭证失败', pres.headers);
   const pol = pbody.data;
   const name = path.basename(filePath);
   const keyPath = `${pol.upload_dir}/${Date.now()}-${name}`;
@@ -246,7 +256,7 @@ export async function pollTask({ key, baseUrl, remoteTaskId, timeoutMs = T_POLL,
     signal: timeoutSignal(timeoutMs, signal)
   });
   const body = await readJson(res);
-  if (!res.ok) throw providerError(res.status, body, '查询任务失败');
+  if (!res.ok) throw providerError(res.status, body, '查询任务失败', res.headers);
   const out = (body && body.output) || {};
   const status = out.task_status || 'UNKNOWN';
   const urls = [];
@@ -291,7 +301,7 @@ export async function synthesizeTts({ key, baseUrl, model = 'qwen-tts-latest', t
     body: JSON.stringify({ model, input: { text, voice } })
   });
   const body = await readJson(res);
-  if (!res.ok) throw providerError(res.status, body, '合成失败');
+  if (!res.ok) throw providerError(res.status, body, '合成失败', res.headers);
   const audio = body && body.output && body.output.audio;
   const url = audio && (audio.url || audio.audio_url);
   const b64 = audio && typeof audio.data === 'string' ? audio.data : null;
@@ -309,17 +319,118 @@ export async function openAiGenerateImage({ key, baseUrl, model, prompt, size =
     body: JSON.stringify({ model, prompt, size, n: Number(n) || 1 })
   });
   const body = await readJson(res);
-  if (!res.ok) throw providerError(res.status, body, '生成失败');
+  if (!res.ok) throw providerError(res.status, body, '生成失败', res.headers);
   const items = (body && Array.isArray(body.data) && body.data) || [];
   const out = [];
   for (const it of items) {
     if (it && typeof it.b64_json === 'string') out.push({ b64: it.b64_json });
     else if (it && typeof it.url === 'string') out.push({ url: it.url });
   }
-  if (!out.length) throw new Error('生成完成但未返回图片数据');
+  if (!out.length) throw imageResponseError('生成响应未返回图片数据');
   return out;
 }
 
+function imageResponseError(message) {
+  return new ProviderContractError(message, {
+    stage: 'response', category: 'protocol', acceptance: 'unknown'
+  });
+}
+
+function imageBase64Item(value, mediaType, label) {
+  const b64 = typeof value === 'string' ? value.replace(/\s/g, '') : '';
+  const bytes = Buffer.from(b64, 'base64');
+  if (!bytes.length || bytes.toString('base64').replace(/=+$/, '') !== b64.replace(/=+$/, '')) {
+    throw imageResponseError(label + '响应包含无效的图片 base64');
+  }
+  return { b64: bytes.toString('base64'), ...(mediaType ? { mediaType } : {}) };
+}
+
+/** 网关扩展：图片 Markdown/data URL、image_url 内容块或 message.images。 */
+function chatImageItems(body, label = '聊天生图') {
+  const items = [], seen = new Set();
+  function add(source) {
+    if (typeof source !== 'string') return;
+    const value = source.trim();
+    if (seen.has(value)) return;
+    const data = /^data:(image\/[a-z0-9.+-]+);base64,([\s\S]+)$/i.exec(value);
+    if (data) {
+      items.push(imageBase64Item(data[2], data[1].toLowerCase(), label));
+    } else if (/^https?:\/\//i.test(value)) {
+      items.push({ url: value });
+    } else return;
+    seen.add(value);
+  }
+  function text(content) {
+    for (const match of content.matchAll(/!\[[^\]]*\]\(([^)]+)\)/g)) add(match[1]);
+    for (const match of content.matchAll(/data:image\/[a-z0-9.+-]+;base64,[^\s)"<>]+/gi)) add(match[0]);
+  }
+  function part(item) {
+    if (item?.type === 'text' && typeof item.text === 'string') text(item.text);
+    else if (item?.image_url) add(typeof item.image_url === 'string' ? item.image_url : item.image_url.url);
+  }
+  for (const choice of Array.isArray(body?.choices) ? body.choices : []) {
+    const message = choice?.message;
+    if (typeof message?.content === 'string') text(message.content);
+    else if (Array.isArray(message?.content)) message.content.forEach(part);
+    if (Array.isArray(message?.images)) message.images.forEach(part);
+  }
+  if (!items.length) throw imageResponseError(label + '响应未返回图片；受理结果未知，禁止自动重提');
+  return items;
+}
+
+export async function openAiChatGenerateImage({ key, baseUrl, model, prompt, image, size, n = 1, timeoutMs = T_SYNC_GEN, signal }) {
+  if (typeof size === 'string' && size.trim()) {
+    throw new ProviderContractError('聊天生图协议不支持 size 参数；请在提示词中描述所需尺寸', {
+      stage: 'validate', category: 'invalid_request', acceptance: 'not_accepted'
+    });
+  }
+  const base = String(baseUrl || '').replace(/\/+$/, '');
+  const content = image ? [
+    { type: 'text', text: prompt },
+    { type: 'image_url', image_url: { url: 'data:' + image.mediaType + ';base64,' + Buffer.from(image.bytes).toString('base64') } }
+  ] : prompt;
+  const res = await fetch(`${base}/chat/completions`, {
+    method: 'POST', headers: authHeaders(key), signal: timeoutSignal(timeoutMs, signal),
+    body: JSON.stringify({ model, stream: false, messages: [{ role: 'user', content }],
+      ...(Number(n) > 1 ? { n: Number(n) } : {}) })
+  });
+  const body = await readJson(res);
+  if (!res.ok) throw providerError(res.status, body, '聊天生图失败', res.headers);
+  return chatImageItems(body);
+}
+
+/** 同步 Responses 生图：主模型由 model 指定，图片工具模型沿用服务端默认。 */
+export async function openAiResponsesGenerateImage({ key, baseUrl, model, prompt, size, n = 1, timeoutMs = T_SYNC_GEN, signal }) {
+  if (Number(n) !== 1) {
+    throw new ProviderContractError('Responses 生图当前只支持 n=1', {
+      stage: 'validate', category: 'invalid_request', acceptance: 'not_accepted'
+    });
+  }
+  const base = String(baseUrl || '').replace(/\/+$/, '');
+  const res = await fetch(`${base}/responses`, {
+    method: 'POST', headers: authHeaders(key), signal: timeoutSignal(timeoutMs, signal),
+    body: JSON.stringify({ model, input: prompt, stream: false, store: false, background: false,
+      tools: [{ type: 'image_generation', action: 'generate', ...(size ? { size: size.replace('*', 'x') } : {}) }],
+      tool_choice: { type: 'image_generation' } })
+  });
+  const body = await readJson(res);
+  if (!res.ok) throw providerError(res.status, body, 'Responses 生图失败', res.headers);
+  if (body?.status !== 'completed') throw imageResponseError('Responses 生图未返回同步完成结果；禁止自动重提');
+  const output = Array.isArray(body.output) ? body.output : [];
+  const images = output.filter(item => item?.type === 'image_generation_call');
+  if (images.length) return images.map(item => {
+    if (item.status !== 'completed') throw imageResponseError('Responses 图片工具未完成；禁止自动重提');
+    return imageBase64Item(item.result, undefined, 'Responses 生图');
+  });
+  // 实测网关将图片作为 output_text 返回；这不证明执行了官方图片工具。
+  const messages = output.filter(item => item?.type === 'message');
+  if (messages.some(item => item.status !== 'completed')) throw imageResponseError('Responses 图片消息未完成；禁止自动重提');
+  return chatImageItems({ choices: messages.map(item => ({ message: {
+    content: (Array.isArray(item.content) ? item.content : []).map(part => part?.type === 'output_text'
+      ? { type: 'text', text: part.text } : part)
+  } })) }, 'Responses 生图');
+}
+
 /* ---------------- 模型发现（OpenAI GET /models + DashScope GET /api/v1/models） ---------------- */
 /**
  * 拉取供应商模型目录。DashScope 官方端点分页读取并保留 capabilities；
@@ -342,7 +453,7 @@ export async function listModels({ key, baseUrl, timeoutMs = T_SUBMIT, signal })
     }
     const res = await fetch(url, { headers: authHeaders(key), signal: timeoutSignal(timeoutMs, signal) });
     const body = await readJson(res);
-    if (!res.ok) throw providerError(res.status, body, '模型发现失败');
+    if (!res.ok) throw providerError(res.status, body, '模型发现失败', res.headers);
     const output = body && body.output;
     const items = (output && Array.isArray(output.models) && output.models)
       || (body && Array.isArray(body.data) && body.data)
@@ -411,7 +522,7 @@ export async function visionStream({ key, baseUrl, model = 'qwen-vl-plus', promp
     const text = await res.text().catch(() => '');
     let body = null;
     try { body = JSON.parse(text); } catch (_) { /* keep null */ }
-    throw providerError(res.status, body, '视觉理解失败');
+    throw providerError(res.status, body, '视觉理解失败', res.headers);
   }
   let full = '';
   const decoder = new TextDecoder();
@@ -488,7 +599,7 @@ export async function submitTranscription({ key, baseUrl, model = 'qwen-audio-3.
     body: JSON.stringify({ model, input })
   });
   const body = await readJson(res);
-  if (!res.ok) throw providerError(res.status, body, '提交转写失败');
+  if (!res.ok) throw providerError(res.status, body, '提交转写失败', res.headers);
   const taskId = body && body.output && body.output.task_id;
   if (!taskId) throw new Error('提交成功但未返回 task_id');
   return taskId;
@@ -520,7 +631,7 @@ export async function pollTranscriptionTask({ key, baseUrl, remoteTaskId, timeou
     signal: timeoutSignal(timeoutMs, signal)
   });
   const body = await readJson(res);
-  if (!res.ok) throw providerError(res.status, body, '查询转写任务失败');
+  if (!res.ok) throw providerError(res.status, body, '查询转写任务失败', res.headers);
   const out = (body && body.output) || {};
   const status = out.task_status || 'UNKNOWN';
   let text = '';

package/lib/api.js

@@ -17,6 +17,9 @@ import { irisHome, capabilitiesOf, onChange as onConfigChange, providerHealthSna
 import { mimeOf, mediaUrl } from './media.js';
 import * as tasks from './tasks.js';
 import * as artifacts from './artifacts.js';
+import { workbenchArtifacts } from './workbench-artifacts.js';
+import { workbenchDetail, downloadWorkbenchSelection, deleteWorkbenchArtifacts, workbenchTransactions,
+  restoreWorkbenchTransaction, workbenchError } from './workbench-management.js';
 import { runAction } from './actions.js';
 import { chmodPrivateFile, ensurePrivateDir } from './private-storage.js';
 import { selectMediaProtocol } from './provider-protocol.js';
@@ -25,6 +28,7 @@ import { hostDoctor } from './doctor.js';
 import { hostRuntimeEvidence, recordHostClient } from './host-runtime.js';
 import { cancelProviderTaskForDsh, coreSnapshotForDsh, disposeCoreTaskAttention, readCoreArtifactMediaForDsh, redeliverProviderTaskForDsh, reobserveProviderTaskForDsh, retryProviderTaskForDsh } from './dsh-core-adapter.js';
 import { optimizePrompt } from './prompt-optimizer.js';
+import { PROMPT_OPTIMIZER_CAPABILITIES } from './prompt-optimizer-core.js';
 import {
   importPromptOptimizerConfig,
   loadPromptOptimizerConfig,
@@ -331,6 +335,9 @@ export function serveApi(req, res, host) {
 
     // POST /iris/api/actions/:name —— GUI 直连触发工具执行
     if (method === 'POST') {
+      if (urlPath === '/iris/api/works/download') return handleWorkbenchPost(req, res, downloadWorkbenchSelection, true);
+      if (urlPath === '/iris/api/works/delete') return handleWorkbenchPost(req, res, deleteWorkbenchArtifacts);
+      if (urlPath === '/iris/api/works/restore') return handleWorkbenchPost(req, res, restoreWorkbenchTransaction);
       if (urlPath === '/iris/api/host-client') {
         if (!host || typeof host !== 'object') return sendJson(res, 503, { error: 'host unavailable' });
         return handleJsonPost(req, res, (body) => recordHostClient(body));
@@ -362,7 +369,7 @@ export function serveApi(req, res, host) {
       return serveSse(res);
     }
     if (urlPath === '/iris/api/prompt-optimizer/config') {
-      return sendJson(res, 200, method === 'HEAD' ? {} : loadPromptOptimizerConfig());
+      return sendJson(res, 200, method === 'HEAD' ? {} : { ...loadPromptOptimizerConfig(), capabilities: PROMPT_OPTIMIZER_CAPABILITIES });
     }
     if (urlPath === '/iris/api/doctor') {
       if (!host || typeof host !== 'object') return sendJson(res, 503, { error: 'host unavailable' });
@@ -373,6 +380,12 @@ export function serveApi(req, res, host) {
       const query = new URL(req.url || '', 'http://iris.local').searchParams;
       return serveCoreSnapshot(res, { limit: Number(query.get('limit') || 12) });
     }
+    if (urlPath === '/iris/api/works') {
+      return serveWorkbenchArtifacts(req, method, res);
+    }
+    if (urlPath === '/iris/api/works/transactions') return serveWorkbenchRead(res, method, () => workbenchTransactions());
+    const workDetailMatch = urlPath.match(/^\/iris\/api\/works\/(core|legacy)\/([^/]+)$/);
+    if (workDetailMatch) return serveWorkbenchRead(res, method, () => workbenchDetail(workDetailMatch[1], workDetailMatch[2]));
     const coreMediaMatch = urlPath.match(/^\/iris\/api\/core\/artifact\/(artifact_[a-f0-9]{24})\/media$/);
     if (coreMediaMatch) return serveCoreArtifactMedia(coreMediaMatch[1], method, res);
     if (urlPath === '/iris/api/artifacts') {
@@ -400,6 +413,32 @@ export function serveApi(req, res, host) {
   }
 }
 
+async function serveWorkbenchArtifacts(req, method, res) {
+  const params = new URL(req.url || '', 'http://iris.local').searchParams;
+  const input = Object.fromEntries(params);
+  for (const key of ['offset', 'limit']) if (input[key] !== undefined) input[key] = Number(input[key]);
+  try { return sendJson(res, 200, method === 'HEAD' ? {} : await workbenchArtifacts(input)); }
+  catch (error) { return sendJson(res, error.statusCode || 500, { error: '作品读取失败', code: error.code || 'IRIS_GALLERY_FAILED' }); }
+}
+
+async function serveWorkbenchRead(res, method, execute) {
+  try { return sendJson(res, 200, method === 'HEAD' ? {} : await execute()); }
+  catch (error) { const safe = workbenchError(error); return sendJson(res, safe.statusCode || 400, { error: safe.message, code: safe.code }); }
+}
+
+function handleWorkbenchPost(req, res, execute, download = false) {
+  return handleJsonPost(req, res, async (body, signal) => {
+    try { return await execute(body, { signal }); }
+    catch (error) { throw workbenchError(error); }
+  }, download ? (response, _status, bytes) => {
+    if (response.writableEnded || response.destroyed) return;
+    response.writeHead(200, { 'Content-Type': 'application/zip', 'Content-Length': bytes.length,
+      'Content-Disposition': 'attachment; filename="iris-works.zip"', 'Cache-Control': 'no-store',
+      'X-Content-Type-Options': 'nosniff', 'Cross-Origin-Resource-Policy': 'same-origin' });
+    response.end(bytes);
+  } : sendJson);
+}
+
 async function serveCoreArtifactMedia(artifactId, method, res) {
   try {
     const result = await readCoreArtifactMediaForDsh(artifactId);
@@ -439,7 +478,7 @@ function sendJson(res, status, obj) {
 
 /** POST /iris/api/actions/:name：读取 JSON body 调 runAction 返回结果 */
 const MAX_BODY_BYTES = 1e6; // 1MB 上限（防滥用）
-function handleJsonPost(req, res, execute) {
+function handleJsonPost(req, res, execute, respond = sendJson) {
   const chunks = [];
   const controller = new AbortController();
   let completed = false;
@@ -448,7 +487,7 @@ function handleJsonPost(req, res, execute) {
   const finish = (status, body) => {
     if (completed) return;
     completed = true;
-    sendJson(res, status, body);
+    (status === 200 ? respond : sendJson)(res, status, body);
   };
   const disconnect = () => { if (!completed) controller.abort(); };
   if (typeof req.on === 'function') req.on('aborted', disconnect);
@@ -469,11 +508,13 @@ function handleJsonPost(req, res, execute) {
       const raw = Buffer.concat(chunks).toString('utf8');
       const body = raw ? JSON.parse(raw) : {};
       const result = await execute(body, controller.signal);
+      if (controller.signal.aborted) return finish(499, { error: 'request canceled' });
       finish(200, result);
     } catch (err) {
       finish(controller.signal.aborted ? 499 : (Number(err && err.statusCode) || 400), {
         error: controller.signal.aborted ? 'request canceled' : String((err && err.message) || err),
-        ...(err && err.code ? { code: String(err.code) } : {})
+        ...(err && err.code ? { code: String(err.code) } : {}),
+        ...(err && /^delete_[a-f0-9]{24}$/.test(err.transactionId) ? { transactionId: err.transactionId } : {})
       });
     }
   });
@@ -524,6 +565,7 @@ function handleCoreTaskRetry(taskId, req, res) {
       const result = await retryProviderTaskForDsh({
         taskId,
         prompt,
+        ...(body.source_artifact_id !== undefined ? { sourceArtifactId: body.source_artifact_id } : {}),
         ...(body.text !== undefined ? { text: String(body.text) } : {}),
         ...(body.voice !== undefined ? { voice: String(body.voice) } : {}),
         ...(body.audio_url !== undefined ? { audio_url: String(body.audio_url) } : {}),
@@ -588,10 +630,10 @@ function handlePromptOptimizer(host, operation, req, res) {
     if (operation === 'optimize') return optimizePrompt(host, body, { signal });
     if (operation === 'import') {
       const imported = body && body.config !== undefined ? body.config : body;
-      return { ok: true, ...importPromptOptimizerConfig(imported) };
+      return { ok: true, ...importPromptOptimizerConfig(imported), capabilities: PROMPT_OPTIMIZER_CAPABILITIES };
     }
-    if (operation === 'reset') return { ok: true, ...resetPromptOptimizerConfig() };
-    if (operation === 'enabled') return { ok: true, ...setPromptOptimizerEnabled(body && body.enabled) };
+    if (operation === 'reset') return { ok: true, ...resetPromptOptimizerConfig(), capabilities: PROMPT_OPTIMIZER_CAPABILITIES };
+    if (operation === 'enabled') return { ok: true, ...setPromptOptimizerEnabled(body && body.enabled), capabilities: PROMPT_OPTIMIZER_CAPABILITIES };
     throw new Error('unknown prompt optimizer operation');
   });
 }

package/lib/chromium-browser.js

@@ -0,0 +1,117 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+
+// 与 DSH render 的页面权限一致：只渲染内联样式和内嵌图片，不执行脚本或加载网络资源。
+const CSP = "sandbox; default-src 'none'; img-src data: blob:; style-src 'unsafe-inline'; font-src data:; connect-src 'none'; form-action 'none'; base-uri 'none'; frame-src 'none'";
+const failure = (code, message) => Object.assign(new Error(message), { code });
+
+export function createChromiumBrowser({ executable, noSandbox = false, timeoutMs = 30000 } = {}) {
+  if (!executable || !path.isAbsolute(executable)) {
+    throw failure('IRIS_BROWSER_REQUIRED', '请通过 --browser-executable 或 IRIS_BROWSER_EXECUTABLE 提供 Chromium 的绝对路径');
+  }
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120000) {
+    throw failure('IRIS_BROWSER_INPUT_INVALID', '浏览器超时必须是 1–120000 毫秒');
+  }
+  return Object.freeze({ async renderHtml({ html, width, height, fullPage, signal }) {
+    const operation = AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(timeoutMs)]);
+    operation.throwIfAborted();
+    const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'iris-browser-'));
+    const route = '/' + crypto.randomBytes(16).toString('hex');
+    const server = http.createServer((req, res) => {
+      if (req.url !== route || !['GET', 'HEAD'].includes(req.method)) { res.writeHead(404); res.end(); return; }
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Content-Security-Policy': CSP,
+        'Referrer-Policy': 'no-referrer', 'X-Content-Type-Options': 'nosniff', 'Cache-Control': 'no-store' });
+      res.end(req.method === 'HEAD' ? '' : html);
+    });
+    let child;
+    let closed;
+    let nextId = 0;
+    let incoming = Buffer.alloc(0);
+    const pending = new Map();
+    const events = new Map();
+    const rejectPending = error => {
+      for (const request of pending.values()) request.reject(error);
+      pending.clear();
+      for (const event of events.values()) event.reject(error);
+      events.clear();
+    };
+    const kill = () => {
+      if (!child?.pid) return;
+      try { process.kill(-child.pid, 'SIGKILL'); } catch (_) { /* 已结束 */ }
+    };
+    const onAbort = () => { rejectPending(operation.reason); kill(); };
+    operation.addEventListener('abort', onAbort, { once: true });
+    const send = (method, params = {}, sessionId) => {
+      operation.throwIfAborted();
+      return new Promise((resolve, reject) => {
+        const id = ++nextId;
+        pending.set(id, { resolve, reject });
+        child.stdio[3].write(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }) + '\0', error => {
+          if (error) { pending.delete(id); reject(failure('IRIS_BROWSER_FAILED', '浏览器通信失败')); }
+        });
+      });
+    };
+    try {
+      await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+      operation.throwIfAborted();
+      const args = ['--headless=new', '--hide-scrollbars', '--remote-debugging-pipe', '--disable-gpu', '--disable-dev-shm-usage', '--disable-background-networking',
+        '--no-first-run', '--no-default-browser-check', '--disable-extensions', '--disable-sync',
+        '--user-data-dir=' + profile, ...(noSandbox ? ['--no-sandbox'] : [])];
+      child = spawn(executable, args, { detached: true, stdio: ['ignore', 'ignore', 'ignore', 'pipe', 'pipe'] });
+      closed = new Promise(resolve => {
+        child.once('error', () => { rejectPending(failure('IRIS_BROWSER_FAILED', '无法启动 Chromium')); resolve(); });
+        child.once('close', () => { rejectPending(failure('IRIS_BROWSER_FAILED', 'Chromium 提前退出；请检查可执行文件及运行环境')); resolve(); });
+      });
+      child.stdio[3].on('error', () => rejectPending(failure('IRIS_BROWSER_FAILED', '浏览器通信失败')));
+      child.stdio[4].on('data', chunk => {
+        incoming = Buffer.concat([incoming, chunk]);
+        let separator;
+        while ((separator = incoming.indexOf(0)) >= 0) {
+          const packet = incoming.subarray(0, separator); incoming = incoming.subarray(separator + 1);
+          let message;
+          try { message = JSON.parse(packet.toString()); } catch (_) { continue; }
+          if (message.id) {
+            const request = pending.get(message.id);
+            pending.delete(message.id);
+            if (request) message.error ? request.reject(failure('IRIS_BROWSER_FAILED', 'Chromium 无法完成截图操作')) : request.resolve(message.result);
+          } else {
+            const key = message.sessionId + ':' + message.method;
+            const event = events.get(key);
+            if (event) { events.delete(key); event.resolve(message.params); }
+          }
+        }
+      });
+      const { targetId } = await send('Target.createTarget', { url: 'about:blank' });
+      const { sessionId } = await send('Target.attachToTarget', { targetId, flatten: true });
+      await send('Page.enable', {}, sessionId);
+      await send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }, sessionId);
+      const loaded = new Promise((resolve, reject) => events.set(sessionId + ':Page.loadEventFired', { resolve, reject }));
+      // 导航失败时也必须消费事件 Promise 的拒绝。
+      loaded.catch(() => {});
+      const navigation = await send('Page.navigate', { url: 'http://127.0.0.1:' + server.address().port + route }, sessionId);
+      if (navigation.errorText) throw failure('IRIS_BROWSER_FAILED', 'HTML 页面无法加载');
+      await loaded;
+      const layout = await send('Page.getLayoutMetrics', {}, sessionId);
+      const size = fullPage ? layout.cssContentSize : { width, height };
+      const captureWidth = Math.max(width, Math.ceil(size.width)), captureHeight = Math.ceil(size.height);
+      if (captureWidth > 16384 || captureHeight > 16384 || captureWidth * captureHeight > 40000000) {
+        throw failure('IRIS_BROWSER_INPUT_INVALID', '截图尺寸超过限制（边长 16384，4000 万像素）');
+      }
+      const screenshot = await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: fullPage,
+        clip: { x: 0, y: 0, width: captureWidth, height: captureHeight, scale: 1 } }, sessionId);
+      operation.throwIfAborted();
+      return { bytes: Buffer.from(screenshot.data, 'base64'), mediaType: 'image/png' };
+    } finally {
+      operation.removeEventListener('abort', onAbort);
+      kill();
+      if (closed) await closed;
+      server.closeAllConnections();
+      await new Promise(resolve => server.close(resolve));
+      fs.rmSync(profile, { recursive: true, force: true });
+    }
+  } });
+}