@mokuyoaxis/dsh-iris 0.1.3 → 0.1.4

package/lib/actions.js

@@ -6,7 +6,7 @@
  * ① `POST /iris/api/actions/:name` 路由（GUI 直连，submit-only 不等待）
  * ② 工具 execute 体（Agent 调用，可等待）
  *
- * 每个 action 是纯函数 `(ctx, args, { signal }) => result`，
+ * 每个 action 是纯函数 `(host, args, { signal }) => result`，
  * 结果只有可序列化 JSON（无 live 对象）。
  */
 import fs from 'node:fs';
@@ -16,17 +16,20 @@ import * as store from './config.js';
 import * as cap from './capability.js';
 import * as models from './models.js';
 import * as tasks from './tasks.js';
+import * as artifacts from './artifacts.js';
 import { registerMedia, mediaLinksOf, webBase } from './media.js';
-import { buildVisionBackends, askWithBackends, testVisionCapability, RED_TEST_IMAGE } from './vision.js';
+import { buildVisionBackendsFromHost, askWithBackends, testVisionCapability, RED_TEST_IMAGE } from './vision.js';
+import { HOST_CONTRACT_VERSION, HOST_PORTS, defineHostAdapter, hasHostPort, requireHostPort } from './host-contract.js';
 import { cropImage, pixelDiff, imageDimensions } from './pixels.js';
 import { locateObject } from './locate.js';
-import { BrowserHtmlRenderer } from './render.js';
 import { longOcr } from './ocr.js';
 import { ffmpegAvailable, extractFrames, probeVideo } from './media-probe.js';
 import { buildContactSheet, summarizeMedia } from './summarize.js';
 import { ensurePrivateDir, writePrivateFile } from './private-storage.js';
 import { inferMediaProtocol } from './provider-protocol.js';
 import { ProviderContractError, submitWithAcceptanceBoundary } from './provider-contract.js';
+import { invokeProviderOperation, providerPollTaskView } from './provider-adapter.js';
+import { createConfiguredProviderAdapter } from './provider-adapters.js';
 import { deriveUserState } from './task-semantics.js';
 
 const MEDIA_TYPES = {
@@ -34,14 +37,30 @@ const MEDIA_TYPES = {
   '.webp': 'image/webp', '.gif': 'image/gif'
 };
 
+const EMPTY_ACTION_HOST = defineHostAdapter({
+  id: 'iris-hostless',
+  ports: {},
+  unavailable: Object.fromEntries(HOST_PORTS.map((name) => [name, {
+    kind: 'unavailable', reason: '当前动作没有宿主能力'
+  }]))
+});
+
+function actionHost(value) {
+  if (!value || (typeof value === 'object' && Object.keys(value).length === 0)) return EMPTY_ACTION_HOST;
+  if (value.contractVersion === HOST_CONTRACT_VERSION && value.ports && value.unavailable) {
+    try { return defineHostAdapter(value); } catch (_) { /* 统一为 Command 边界错误 */ }
+  }
+  throw new TypeError('Iris Action 只接受有效的 Host Adapter，不接受原始 ctx');
+}
+
 /* ---------------- 视觉效果自述（辅助 iris_draw_image） ---------------- */
-async function describeFirstImage(ctx, ref, absPath, originalPrompt) {
+async function describeFirstImage(host, ref, absPath, originalPrompt) {
   try {
     const mt = MEDIA_TYPES[path.extname(absPath).toLowerCase()] || 'image/png';
     const buf = fs.readFileSync(absPath);
     const dataUrl = `data:${mt};base64,${buf.toString('base64')}`;
-    const backends = buildVisionBackends(ctx, { providers: store.pickAllFor(cap.CAPABILITIES.VISION) });
-    const { answer } = await askWithBackends(backends, {
+    const backends = buildVisionBackendsFromHost(host, { providers: store.pickAllFor(cap.CAPABILITIES.VISION) });
+    const { answer } = await askWithHealth(backends, {
       question: `用不超过两句话描述这张图片的主题与构图。生成该图的提示词是：「${String(originalPrompt).slice(0, 200)}」`,
       imageDataUrl: dataUrl,
       signal: undefined
@@ -86,28 +105,10 @@ function imageRoute(provider, args) {
   const model = args.model
     ? (parsed?.modelId || String(args.model))
     : (provider.imageModel || (protocol === 'openai-images' ? 'gpt-image-1' : 'wan2.2-t2i-flash'));
-  return { provider, protocol, model, modelRef: models.modelRef(provider.id, model) };
-}
-
-function imageSubmissionError(error) {
-  const status = Number(error && error.status) || undefined;
-  // 408/409/425/499 可能来自中间层或冲突恢复，不能证明请求未被受理。
-  const explicitRejection = Boolean(status && status >= 400 && status < 500 && ![408, 409, 425, 499].includes(status));
-  let category = 'provider';
-  if (error && (error.name === 'AbortError' || error.code === 'ABORT_ERR')) category = 'aborted';
-  else if (error && (error.category === 'network' || error instanceof TypeError)) category = 'network';
-  else if (status === 401 || status === 403) category = 'authentication';
-  else if (status === 429 && error && error.category === 'quota') category = 'quota';
-  else if (status === 429) category = 'rate_limit';
-  else if (status && status >= 400 && status < 500) category = 'invalid_request';
-  else if (!status) category = 'protocol';
-  return new ProviderContractError(String((error && error.message) || error || '提交失败'), {
-    stage: 'submit',
-    category,
-    acceptance: explicitRejection ? 'not_accepted' : 'unknown',
-    retryable: status === 429 || Boolean(status && status >= 500) || category === 'network',
-    ...(status ? { httpStatus: status } : {})
-  });
+  return {
+    provider, protocol, model, modelRef: models.modelRef(provider.id, model),
+    adapter: createConfiguredProviderAdapter(provider, { protocol })
+  };
 }
 
 function taskActionError(taskId, message, details) {
@@ -117,14 +118,82 @@ function taskActionError(taskId, message, details) {
   return error;
 }
 
-async function deliverCompletedImage(taskId, value, signal) {
+function recordProviderHealthSafe(providerId, modelId, capability, result) {
+  try {
+    store.recordProviderHealth(providerId, modelId, capability, { source: 'task', ...result });
+  } catch (error) {
+    console.warn('[iris] Provider 健康事实记录失败：', String(error && error.message || error));
+  }
+}
+
+async function observeProviderCapability(route, capability, operation, { recordSuccess = true } = {}) {
+  try {
+    const result = await operation();
+    if (recordSuccess && result && ['accepted', 'completed', 'pending', 'succeeded'].includes(result.kind)) {
+      recordProviderHealthSafe(route.provider.id, route.model, capability, {
+        ok: true,
+        category: 'success',
+        note: result.kind === 'accepted' ? '任务已受理' : '供应商请求成功'
+      });
+    } else if (result && result.error) {
+      recordProviderHealthSafe(route.provider.id, route.model, capability, {
+        ok: false,
+        category: result.error.category,
+        httpStatus: result.error.httpStatus,
+        note: result.error.safeMessage
+      });
+    }
+    return result;
+  } catch (error) {
+    recordProviderHealthSafe(route.provider.id, route.model, capability, {
+      ok: false,
+      category: error && error.category,
+      httpStatus: error && (error.httpStatus ?? error.status),
+      note: String(error && (error.safeMessage || error.message) || error)
+    });
+    throw error;
+  }
+}
+
+function recordVisionHealth(errors) {
+  for (const error of errors || []) {
+    if (error && error.kind === 'selfstack') {
+      recordProviderHealthSafe(error.backendId, error.model, cap.CAPABILITIES.VISION, {
+        ok: false,
+        category: error.category,
+        httpStatus: error.status,
+        note: error.message
+      });
+    }
+  }
+}
+
+async function askWithHealth(backends, request) {
+  try {
+    const result = await askWithBackends(backends, request);
+    recordVisionHealth(result.errors);
+    if (result.via === 'selfstack') {
+      recordProviderHealthSafe(result.backendId, result.model, cap.CAPABILITIES.VISION, {
+        ok: true, category: 'success', note: '视觉请求成功'
+      });
+    }
+    return result;
+  } catch (error) {
+    recordVisionHealth(error && error.errors);
+    throw error;
+  }
+}
+
+async function deliverCompletedImage(taskId, value, signal, providerAdapter) {
   const names = [];
   try {
     tasks.beginDelivery(taskId);
     if (value && value.kind === 'urls') {
       for (const url of value.items || []) {
         const name = taskId + '-' + names.length + '.' + adapters.extFromUrl(url, 'png');
-        await adapters.downloadTo(url, path.join(outputDir(), name), { signal });
+        await invokeProviderOperation(providerAdapter, 'download', {
+          artifact: { kind: 'remote-url', url }, targetPath: path.join(outputDir(), name), signal
+        });
         names.push(name);
       }
     } else if (value && value.kind === 'openai') {
@@ -132,7 +201,9 @@ async function deliverCompletedImage(taskId, value, signal) {
         const name = taskId + '-' + names.length + '.png';
         const target = path.join(outputDir(), name);
         if (item && item.b64) writePrivateFile(target, Buffer.from(item.b64, 'base64'));
-        else if (item && item.url) await adapters.downloadTo(item.url, target, { signal });
+        else if (item && item.url) await invokeProviderOperation(providerAdapter, 'download', {
+          artifact: { kind: 'remote-url', url: item.url }, targetPath: target, signal
+        });
         else throw new Error('同步图片结果缺少 b64 或 URL');
         names.push(name);
       }
@@ -176,29 +247,13 @@ async function submitImageV2(routes, prompt, args, signal) {
           stage: 'submit', category: 'aborted', acceptance: 'unknown'
         });
       }
-      try {
-        if (route.protocol === 'dashscope') {
-          if (adapters.dashscopeImageMode(route.model) === 'legacy-async') {
-            const remoteTaskId = await adapters.submitImage({
-              key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
-              model: route.model, prompt, size: args.size, n: args.n, signal
-            });
-            return { kind: 'accepted', remoteTaskId };
-          }
-          const urls = await adapters.generateImageMultimodal({
-            key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
-            model: route.model, prompt, size: args.size, n: args.n, signal
-          });
-          return { kind: 'completed', value: { kind: 'urls', items: urls } };
-        }
-        const items = await adapters.openAiGenerateImage({
-          key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
-          model: route.model, prompt, size: args.size, n: args.n, signal
-        });
-        return { kind: 'completed', value: { kind: 'openai', items } };
-      } catch (error) {
-        throw imageSubmissionError(error);
-      }
+      return observeProviderCapability(route, cap.CAPABILITIES.IMAGE, () =>
+        invokeProviderOperation(route.adapter, 'submit', {
+          capability: 'image',
+          model: route.model,
+          input: { prompt, size: args.size, n: args.n },
+          signal
+        }));
     }
   }));
 
@@ -231,7 +286,7 @@ async function submitImageV2(routes, prompt, args, signal) {
 
   const route = submitted.candidate.route;
   if (submitted.result.kind === 'completed') {
-    const delivered = await deliverCompletedImage(task.id, submitted.result.value, signal);
+    const delivered = await deliverCompletedImage(task.id, submitted.result.value, signal, route.adapter);
     return { task: delivered, provider: route.provider, model: route.model, remoteTaskId: null };
   }
   if (submitted.result.kind !== 'accepted') {
@@ -244,14 +299,21 @@ async function submitImageV2(routes, prompt, args, signal) {
     throw taskActionError(task.id, '远端已受理，但本地盯守状态落盘失败；禁止自动重提', { message: String(error.message || error) });
   }
   tasks.watch(tasks.get(task.id), {
-    key: () => route.provider.apiKey,
-    poll: ({ key, remoteTaskId }) => adapters.pollTask({ key, baseUrl: route.provider.baseUrl, remoteTaskId }),
+    poll: ({ remoteTaskId, signal: pollSignal }) => observeProviderCapability(
+      route, cap.CAPABILITIES.IMAGE,
+      () => invokeProviderOperation(route.adapter, 'poll', {
+        capability: 'image', remoteTaskId, signal: pollSignal
+      }),
+      { recordSuccess: false }
+    ),
     intervalMs: 2500,
     onSuccess: async (record, result) => {
       const names = [];
       for (const url of result.urls || []) {
         const name = record.id + '-' + names.length + '.' + adapters.extFromUrl(url, 'png');
-        await adapters.downloadTo(url, path.join(outputDir(), name));
+        await invokeProviderOperation(route.adapter, 'download', {
+          artifact: { kind: 'remote-url', url }, targetPath: path.join(outputDir(), name)
+        });
         names.push(name);
       }
       for (const name of names) registerMedia(record.id, path.join(outputDir(), name));
@@ -304,7 +366,10 @@ function videoRoute(provider, args, frame) {
   const model = args.model ? (parsed?.modelId || String(args.model)) : (provider.videoModel || 'wan2.2-t2v-flash');
   const isS2V = /s2v/i.test(model);
   const mode = isS2V ? 's2v' : (frame ? 'i2v' : 't2v');
-  return { provider, model, modelRef: models.modelRef(provider.id, model), isS2V, mode, protocol: 'dashscope' };
+  return {
+    provider, model, modelRef: models.modelRef(provider.id, model), isS2V, mode, protocol: 'dashscope',
+    adapter: createConfiguredProviderAdapter(provider, { protocol: 'dashscope' })
+  };
 }
 
 function beforeGenerationError(error, stage) {
@@ -368,15 +433,10 @@ async function submitVideoV2(routes, frame, prompt, args, signal) {
         }
       }
       tasks.markAttemptStage(task.id, attemptId, 'submit');
-      try {
-        const remoteTaskId = await adapters.submitVideo({
-          key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
-          model: route.model, ...submitArgs, signal
-        });
-        return { kind: 'accepted', remoteTaskId };
-      } catch (error) {
-        throw imageSubmissionError(error);
-      }
+      return observeProviderCapability(route, cap.CAPABILITIES.VIDEO, () =>
+        invokeProviderOperation(route.adapter, 'submit', {
+          capability: 'video', model: route.model, input: submitArgs, signal
+        }));
     }
   }));
 
@@ -414,14 +474,21 @@ async function submitVideoV2(routes, frame, prompt, args, signal) {
   const route = submitted.candidate.route;
   tasks.activateWatch(task.id);
   tasks.watch(tasks.get(task.id), {
-    key: () => route.provider.apiKey,
-    poll: ({ key, remoteTaskId: id }) => adapters.pollTask({ key, baseUrl: route.provider.baseUrl, remoteTaskId: id }),
+    poll: ({ remoteTaskId: id, signal: pollSignal }) => observeProviderCapability(
+      route, cap.CAPABILITIES.VIDEO,
+      () => invokeProviderOperation(route.adapter, 'poll', {
+        capability: 'video', remoteTaskId: id, signal: pollSignal
+      }),
+      { recordSuccess: false }
+    ),
     intervalMs: 6000,
     onSuccess: async (record, result) => {
       const names = [];
       for (const url of result.urls || []) {
         const name = record.id + '-' + names.length + '.' + adapters.extFromUrl(url, 'mp4');
-        await adapters.downloadTo(url, path.join(outputDir(), name));
+        await invokeProviderOperation(route.adapter, 'download', {
+          artifact: { kind: 'remote-url', url }, targetPath: path.join(outputDir(), name)
+        });
         names.push(name);
       }
       for (const name of names) registerMedia(record.id, path.join(outputDir(), name));
@@ -434,7 +501,10 @@ async function submitVideoV2(routes, frame, prompt, args, signal) {
 function simpleModelRoute(provider, args, field, fallback, protocol = 'dashscope') {
   const parsed = models.parseModelRef(String(args.model || ''));
   const model = args.model ? (parsed?.modelId || String(args.model)) : (provider[field] || fallback);
-  return { provider, model, modelRef: models.modelRef(provider.id, model), protocol };
+  return {
+    provider, model, modelRef: models.modelRef(provider.id, model), protocol,
+    adapter: createConfiguredProviderAdapter(provider, { protocol })
+  };
 }
 
 async function submitTranscriptionV2(routes, audioPath, args, signal) {
@@ -458,15 +528,10 @@ async function submitTranscriptionV2(routes, audioPath, args, signal) {
         throw beforeGenerationError(error, 'upload');
       }
       tasks.markAttemptStage(task.id, context.attempt.id, 'submit');
-      try {
-        const remoteTaskId = await adapters.submitTranscription({
-          key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
-          model: route.model, audioUrl, signal
-        });
-        return { kind: 'accepted', remoteTaskId };
-      } catch (error) {
-        throw imageSubmissionError(error);
-      }
+      return observeProviderCapability(route, cap.CAPABILITIES.TRANSCRIBE, () =>
+        invokeProviderOperation(route.adapter, 'submit', {
+          capability: 'transcribe', model: route.model, input: { audioUrl }, signal
+        }));
     }
   }));
   const submitted = await submitWithAcceptanceBoundary(candidates, { capability: 'transcribe' }, {
@@ -491,11 +556,13 @@ async function submitTranscriptionV2(routes, audioPath, args, signal) {
   const route = submitted.candidate.route;
   tasks.activateWatch(task.id);
   tasks.watch(tasks.get(task.id), {
-    key: () => route.provider.apiKey,
-    poll: async ({ key, remoteTaskId: id }) => {
-      const result = await adapters.pollTranscriptionTask({ key, baseUrl: route.provider.baseUrl, remoteTaskId: id });
-      return { done: result.done, ok: result.ok, urls: result.text ? [result.text] : [], message: result.message };
-    },
+    poll: ({ remoteTaskId: id, signal: pollSignal }) => observeProviderCapability(
+      route, cap.CAPABILITIES.TRANSCRIBE,
+      () => invokeProviderOperation(route.adapter, 'poll', {
+        capability: 'transcribe', remoteTaskId: id, signal: pollSignal
+      }),
+      { recordSuccess: false }
+    ),
     intervalMs: 2500,
     allowEmptyResult: true,
     onSuccess: async (record, result) => {
@@ -517,15 +584,10 @@ async function submitTtsV2(routes, text, args, signal) {
     route,
     submit: async (_input, context) => {
       tasks.markAttemptStage(task.id, context.attempt.id, 'submit');
-      try {
-        const audio = await adapters.synthesizeTts({
-          key: route.provider.apiKey, baseUrl: route.provider.baseUrl,
-          model: route.model, text, voice: route.voice, signal
-        });
-        return { kind: 'completed', value: audio };
-      } catch (error) {
-        throw imageSubmissionError(error);
-      }
+      return observeProviderCapability(route, cap.CAPABILITIES.TTS, () =>
+        invokeProviderOperation(route.adapter, 'submit', {
+          capability: 'tts', model: route.model, input: { text, voice: route.voice }, signal
+        }));
     }
   }));
   const submitted = await submitWithAcceptanceBoundary(candidates, { capability: 'tts' }, {
@@ -556,7 +618,9 @@ async function submitTtsV2(routes, text, args, signal) {
     tasks.beginDelivery(task.id);
     const name = task.id + '.' + (audio.audioUrl ? adapters.extFromUrl(audio.audioUrl, 'wav') : 'wav');
     const target = path.join(outputDir(), name);
-    if (audio.audioUrl) await adapters.downloadTo(audio.audioUrl, target, { signal });
+    if (audio.audioUrl) await invokeProviderOperation(route.adapter, 'download', {
+      artifact: { kind: 'remote-url', url: audio.audioUrl }, targetPath: target, signal
+    });
     else if (audio.audioB64) writePrivateFile(target, Buffer.from(audio.audioB64, 'base64'));
     else throw new Error('语音合成成功响应缺少音频数据');
     names.push(name);
@@ -572,13 +636,33 @@ async function submitTtsV2(routes, text, args, signal) {
 /** 重新观察/交付与启动恢复共享的远端查询和本地落盘依赖。 */
 export function taskPollDeps(provider, task) {
   if (!provider || !task) return null;
+  if (!['image', 'video', 'transcribe'].includes(task.cap)) return null;
+  const protocol = task.protocol || (task.cap === 'image'
+    ? (provider.mediaProtocol || inferMediaProtocol(provider.baseUrl))
+    : 'dashscope');
+  let providerAdapter;
+  try {
+    providerAdapter = createConfiguredProviderAdapter(provider, { protocol });
+  } catch (_) {
+    return null;
+  }
+  const healthCapability = task.cap === 'image'
+    ? cap.CAPABILITIES.IMAGE
+    : (task.cap === 'video' ? cap.CAPABILITIES.VIDEO : cap.CAPABILITIES.TRANSCRIBE);
+  const parsedTaskModel = models.parseModelRef(String(task.model || ''));
+  const healthRoute = {
+    provider,
+    model: parsedTaskModel?.modelId || String(task.model || provider[models.CAP_FIELD[healthCapability]] || '')
+  };
   if (task.cap === 'transcribe') {
     return {
-      key: () => provider.apiKey,
-      poll: async ({ key, remoteTaskId }) => {
-        const r = await adapters.pollTranscriptionTask({ key, baseUrl: provider.baseUrl, remoteTaskId });
-        return { done: r.done, ok: r.ok, urls: r.text ? [r.text] : [], message: r.message };
-      },
+      poll: ({ remoteTaskId, signal }) => observeProviderCapability(
+        healthRoute, healthCapability,
+        () => invokeProviderOperation(providerAdapter, 'poll', {
+          capability: 'transcribe', remoteTaskId, signal
+        }),
+        { recordSuccess: false }
+      ),
       intervalMs: 2500,
       allowEmptyResult: true,
       onSuccess: async (record, result) => {
@@ -587,17 +671,23 @@ export function taskPollDeps(provider, task) {
       }
     };
   }
-  if (task.cap !== 'image' && task.cap !== 'video') return null;
   return {
-    key: () => provider.apiKey,
-    poll: ({ key, remoteTaskId }) => adapters.pollTask({ key, baseUrl: provider.baseUrl, remoteTaskId }),
+    poll: ({ remoteTaskId, signal }) => observeProviderCapability(
+      healthRoute, healthCapability,
+      () => invokeProviderOperation(providerAdapter, 'poll', {
+        capability: task.cap, remoteTaskId, signal
+      }),
+      { recordSuccess: false }
+    ),
     intervalMs: task.cap === 'video' ? 6000 : 2500,
     onSuccess: async (record, result) => {
       const names = [];
       for (const url of result.urls || []) {
         const fallback = task.cap === 'video' ? 'mp4' : 'png';
         const name = record.id + '-' + names.length + '.' + adapters.extFromUrl(url, fallback);
-        await adapters.downloadTo(url, path.join(outputDir(), name));
+        await invokeProviderOperation(providerAdapter, 'download', {
+          artifact: { kind: 'remote-url', url }, targetPath: path.join(outputDir(), name)
+        });
         names.push(name);
       }
       for (const name of names) registerMedia(record.id, path.join(outputDir(), name));
@@ -613,7 +703,7 @@ const actions = {};
 /**
  * 注册一个 action。
  * @param {string} name 动作名（用于路由）
- * @param {Function} fn (ctx, args, { signal }) => { ok, text?, imageDataUrl?, taskId?, blocks? }
+ * @param {Function} fn (host, args, { signal }) => { ok, text?, imageDataUrl?, taskId?, blocks? }
  */
 function register(name, fn) {
   actions[name] = fn;
@@ -625,16 +715,16 @@ export function listActions() {
 }
 
 /** 执行一个动作 */
-export async function runAction(ctx, name, args, { signal } = {}) {
+export async function runAction(host, name, args, { signal } = {}) {
   const fn = actions[name];
   if (!fn) throw new Error(`iris: 未知动作 "${name}"`);
-  return fn(ctx, args, { signal });
+  return fn(actionHost(host), args || {}, { signal });
 }
 
 /* ============ 动作实现 ============ */
 
 /* ---------- 🖼️ 画图 ---------- */
-register('image', async (ctx, args, { signal }) => {
+register('image', async (host, args, { signal }) => {
   const prompt = String(args.prompt || '').trim();
   if (!prompt) throw new Error('iris: prompt 不能为空');
 
@@ -651,7 +741,7 @@ register('image', async (ctx, args, { signal }) => {
 });
 
 /* ---------- 🎬 视频生成 ---------- */
-register('video', async (ctx, args, { signal }) => {
+register('video', async (host, args, { signal }) => {
   const prompt = String(args.prompt || '').trim();
   if (!prompt && !args.audio_path) throw new Error('iris: prompt 不能为空');
   const frame = resolveFirstFrameFile(args);
@@ -666,7 +756,7 @@ register('video', async (ctx, args, { signal }) => {
 });
 
 /* ---------- 🔊 语音合成 ---------- */
-register('tts', async (ctx, args, { signal }) => {
+register('tts', async (host, args, { signal }) => {
   const text = String(args.text || '').trim();
   if (!text) throw new Error('iris: text 不能为空');
   const providers = selectProviders(cap.CAPABILITIES.TTS, '语音', args.model);
@@ -682,21 +772,21 @@ register('tts', async (ctx, args, { signal }) => {
 });
 
 /* ---------- 👁 看图 ---------- */
-register('look', async (ctx, args, { signal }) => {
+register('look', async (host, args, { signal }) => {
   const p = String(args.image_path || '').trim();
   if (!p || !path.isAbsolute(p)) throw new Error('iris: image_path 必须是绝对路径');
   const mt = MEDIA_TYPES[path.extname(p).toLowerCase()];
   if (!mt || mt === 'image/gif') throw new Error('iris: 不支持的图片格式');
   if (!fs.existsSync(p)) throw new Error('iris: 图片不存在');
   const dataUrl = `data:${mt};base64,${fs.readFileSync(p).toString('base64')}`;
-  const backends = buildVisionBackends(ctx, { providers: store.pickAllFor(cap.CAPABILITIES.VISION), model: args.model });
-  const { answer, via, model } = await askWithBackends(backends, { question: (args.question || '详细描述这张图片。'), imageDataUrl: dataUrl, signal });
+  const backends = buildVisionBackendsFromHost(host, { providers: store.pickAllFor(cap.CAPABILITIES.VISION), model: args.model });
+  const { answer, via, model } = await askWithHealth(backends, { question: (args.question || '详细描述这张图片。'), imageDataUrl: dataUrl, signal });
   const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 全局视觉模型';
   return { ok: true, text: `[iris] 看图回答（${model} · ${viaLabel}）：\n${answer}` };
 });
 
 /* ---------- ✂️ 裁剪 ---------- */
-register('crop', async (ctx, args, { signal }) => {
+register('crop', async (host, args, { signal }) => {
   const p = String(args.image_path || '').trim();
   if (!p || !path.isAbsolute(p)) throw new Error('iris: image_path 必须是绝对路径');
   if (!fs.existsSync(p)) throw new Error('iris: 图片不存在');
@@ -706,7 +796,7 @@ register('crop', async (ctx, args, { signal }) => {
 });
 
 /* ---------- 📷 像素 diff ---------- */
-register('diff', async (ctx, args, { signal }) => {
+register('diff', async (host, args, { signal }) => {
   if (!args.image_a_path || !args.image_b_path) throw new Error('iris: 需要 image_a_path 和 image_b_path');
   const { ratio, diffPixels, totalPixels, width, height, worstRegions, heatmap, mime } = await pixelDiff({
     inputA: args.image_a_path, inputB: args.image_b_path, grid: args.grid || 8, topRegions: args.top_regions || 3
@@ -721,7 +811,7 @@ register('diff', async (ctx, args, { signal }) => {
 });
 
 /* ---------- 📍 定位 ---------- */
-register('locate', async (ctx, args, { signal }) => {
+register('locate', async (host, args, { signal }) => {
   const p = String(args.image_path || '').trim();
   if (!p || !path.isAbsolute(p)) throw new Error('iris: image_path 必须是绝对路径');
   if (!fs.existsSync(p)) throw new Error('iris: 图片不存在');
@@ -729,28 +819,28 @@ register('locate', async (ctx, args, { signal }) => {
   const mt = MEDIA_TYPES[path.extname(p).toLowerCase()] || 'image/png';
   const dataUrl = `data:${mt};base64,${buf.toString('base64')}`;
   const { width, height } = await imageDimensions(buf);
-  const backends = buildVisionBackends(ctx, { providers: store.pickAllFor(cap.CAPABILITIES.VISION), model: args.model });
+  const backends = buildVisionBackendsFromHost(host, { providers: store.pickAllFor(cap.CAPABILITIES.VISION), model: args.model });
   const r = await locateObject(backends, { target: args.target, imageDataUrl: dataUrl, width, height, signal });
   if (!r.found) return { ok: true, text: `[iris] 在图片中未找到「${args.target}」` };
   return { ok: true, text: `[iris] 定位「${args.target}」：bbox (${r.x1},${r.y1},${r.x2},${r.y2}) / ${width}x${height}（${r.via} · ${r.model}）` };
 });
 /* ---------- 🖼️ HTML 截图 ---------- */
-register('html', async (ctx, args, { signal }) => {
+register('html', async (host, args, { signal }) => {
   const html = String(args.html || '').trim();
   if (!html) throw new Error('iris: html 不能为空');
-  const browser = ctx.get('browser');
-  if (!browser) throw new Error('iris: 浏览器服务不可用——需要启用 dsh-builtin-browser 插件');
-  const renderer = new BrowserHtmlRenderer({ browser });
-  const { png } = await renderer.render({ html, width: args.width, height: args.height, fullPage: args.fullPage !== false });
-  return { ok: true, text: `[iris] HTML 截图完成（fullPage: ${args.fullPage !== false}）`, imageDataUrl: `data:image/png;base64,${png.toString('base64')}` };
+  const browser = requireHostPort(host, 'browser', 'HTML 截图');
+  const rendered = await browser.renderHtml({ html, width: args.width, height: args.height,
+    fullPage: args.fullPage !== false, signal });
+  const png = Buffer.from(rendered.bytes);
+  return { ok: true, text: `[iris] HTML 截图完成（fullPage: ${args.fullPage !== false}）`, imageDataUrl: `data:${rendered.mediaType || 'image/png'};base64,${png.toString('base64')}` };
 });
 
 /* ---------- 📄 长截图 OCR ---------- */
-register('ocr', async (ctx, args, { signal }) => {
+register('ocr', async (host, args, { signal }) => {
   const p = String(args.image_path || '').trim();
   if (!p || !path.isAbsolute(p)) throw new Error('iris: image_path 必须是绝对路径');
   if (!fs.existsSync(p)) throw new Error('iris: 图片不存在');
-  const backends = buildVisionBackends(ctx, { providers: store.pickAllFor(cap.CAPABILITIES.VISION) });
+  const backends = buildVisionBackendsFromHost(host, { providers: store.pickAllFor(cap.CAPABILITIES.VISION) });
   const result = await longOcr({ input: p, backends, chunkHeight: args.chunk_height || 1200, overlap: args.overlap || 120, signal });
   const errCount = result.chunks.filter((c) => c.error).length;
   const head = `[iris] 长截图 OCR 完成：${result.width}x${result.height}px，${result.totalChunks} 块${errCount ? '（' + errCount + ' 块失败）' : ''}\n`;
@@ -758,7 +848,7 @@ register('ocr', async (ctx, args, { signal }) => {
 });
 
 /* ---------- 📋 任务查询 ---------- */
-register('status', async (ctx, args, { signal }) => {
+register('status', async (host, args, { signal }) => {
   if (args.task_id) {
     const t = tasks.get(String(args.task_id).trim());
     if (!t) throw new Error('iris: 没有这个任务：' + args.task_id);
@@ -776,7 +866,7 @@ register('status', async (ctx, args, { signal }) => {
 });
 
 /* ---------- Task v2 人工接管 ---------- */
-register('task_reobserve', async (ctx, args) => {
+register('task_reobserve', async (host, args) => {
   const id = String(args.task_id || '').trim();
   const task = tasks.get(id);
   if (!task || !tasks.isV2Task(task)) throw new Error('iris: 找不到可接管的 Task v2');
@@ -790,7 +880,7 @@ register('task_reobserve', async (ctx, args) => {
   return { ok: true, taskId: id, text: '[iris] 已重新观察远端任务；不会重新提交生成请求。' };
 });
 
-register('task_redeliver', async (ctx, args, { signal }) => {
+register('task_redeliver', async (host, args, { signal }) => {
   const id = String(args.task_id || '').trim();
   const task = tasks.get(id);
   if (!task || !tasks.isV2Task(task)) throw new Error('iris: 找不到可重新交付的 Task v2');
@@ -802,7 +892,7 @@ register('task_redeliver', async (ctx, args, { signal }) => {
   tasks.prepareRedelivery(id);
   try {
     tasks.beginDelivery(id);
-    const result = await deps.poll({ key: deps.key(), remoteTaskId: task.remoteTaskId, signal });
+    const result = providerPollTaskView(await deps.poll({ remoteTaskId: task.remoteTaskId, signal }));
     if (!result.done) throw new Error('远端结果暂未就绪，请先重新观察');
     if (!result.ok) throw new Error(result.message || '供应商当前无法返回成功产物');
     if (!(result.urls || []).length) throw new Error('供应商未返回可交付的结果 URL');
@@ -816,7 +906,7 @@ register('task_redeliver', async (ctx, args, { signal }) => {
   }
 });
 
-register('task_ack_attention', async (_ctx, args) => {
+register('task_ack_attention', async (_host, args) => {
   const id = String(args.task_id || '').trim();
   const task = tasks.get(id);
   if (!task || !tasks.isV2Task(task)) throw new Error('iris: 找不到可标为已读的 Task v2');
@@ -824,7 +914,7 @@ register('task_ack_attention', async (_ctx, args) => {
   return { ok: true, taskId: id, text: '[iris] 提醒已标为已读；任务事实未改变，可在历史详情中恢复提醒。' };
 });
 
-register('task_restore_attention', async (_ctx, args) => {
+register('task_restore_attention', async (_host, args) => {
   const id = String(args.task_id || '').trim();
   const task = tasks.get(id);
   if (!task || !tasks.isV2Task(task)) throw new Error('iris: 找不到可恢复提醒的 Task v2');
@@ -832,7 +922,7 @@ register('task_restore_attention', async (_ctx, args) => {
   return { ok: true, taskId: id, text: '[iris] 已恢复任务提醒。' };
 });
 
-register('task_manual_retry', async (ctx, args, { signal }) => {
+register('task_manual_retry', async (host, args, { signal }) => {
   const id = String(args.task_id || '').trim();
   if (args.confirm_duplicate_charge !== true) throw new Error('iris: 必须明确确认本次操作可能产生重复任务或重复费用');
   const task = tasks.get(id);
@@ -856,7 +946,7 @@ register('task_manual_retry', async (ctx, args, { signal }) => {
   if (task.modelRef) retryArgs.model = task.modelRef;
   retryArgs._retryOf = id;
   try {
-    const result = await runAction(ctx, action, retryArgs, { signal });
+    const result = await runAction(host, action, retryArgs, { signal });
     if (result.taskId) tasks.linkManualRetry(id, result.taskId);
     return { ...result, retryOf: id, text: (result.text || '[iris] 已创建新任务')
       + '\n[iris] 原任务提醒已归档，并保留新旧任务关联；本次新任务可能与远端未知任务重复。' };
@@ -880,6 +970,7 @@ function scanOrphanArtifacts() {
     for (const m of t.media || []) referenced.add(path.basename(m.file));
     for (const a of t.attachments || []) if (a.file) referenced.add(path.basename(a.file));
   }
+  for (const item of artifacts.all()) referenced.add(path.basename(item.file));
   const files = [];
   let bytes = 0;
   for (const name of fs.readdirSync(dir)) {
@@ -895,7 +986,7 @@ function scanOrphanArtifacts() {
 }
 
 /** 删除单条任务记录（仅终态；运行中须先取消）。只删元数据，产物文件保留。 */
-register('tasks_delete', async (ctx, args) => {
+register('tasks_delete', async (host, args) => {
   const id = String(args.task_id || '').trim();
   if (!id) throw new Error('iris: task_id 不能为空');
   const r = tasks.remove(id);
@@ -907,7 +998,7 @@ register('tasks_delete', async (ctx, args) => {
  * 批量清理任务记录：scope = completed（所有终态）| older_than（早于 days 天）| all（等同 completed，运行中受保护）。
  * 只删元数据，绝不动运行中任务，产物文件默认保留。
  */
-register('tasks_clear', async (ctx, args) => {
+register('tasks_clear', async (host, args) => {
   const scope = String(args.scope || 'completed').trim();
   if (!['completed', 'older_than', 'all'].includes(scope)) throw new Error('iris: scope 需为 completed/older_than/all');
   let removed;
@@ -920,7 +1011,28 @@ register('tasks_clear', async (ctx, args) => {
     // completed / all：删除全部终态记录（运行中永不被 prune 命中）
     removed = tasks.prune(() => true);
   }
-  return { ok: true, removed: removed.length, text: `[iris] 已清理 ${removed.length} 条任务记录（产物文件保留）` };
+  return { ok: true, removed: removed.length, text: `[iris] 已清理 ${removed.length} 条任务记录（作品仍可在作品库查看）` };
+});
+
+/** 重新扫描 outputs/，补录旧作品并移除已经不存在的索引。 */
+register('artifacts_reindex', async () => {
+  const result = artifacts.reindex();
+  return { ok: true, ...result, text: `[iris] 作品库已刷新：找回 ${result.added} 个，移除 ${result.missing} 个失效索引，共 ${result.total} 个作品` };
+});
+
+/** 删除一件作品及其文件；任务历史不会随之删除。 */
+register('artifacts_delete', async (_host, args) => {
+  const id = String(args.artifact_id || '').trim();
+  if (!id) throw new Error('iris: artifact_id 不能为空');
+  const result = artifacts.remove(id);
+  if (!result.ok) throw new Error('iris: ' + result.reason);
+  return { ok: true, removed: 1, text: `[iris] 已删除作品 ${result.file}；任务历史保留` };
+});
+
+/** 清空作品库及其文件；客户端必须单独二次确认。 */
+register('artifacts_clear', async () => {
+  const result = artifacts.clear();
+  return { ok: result.failed === 0, ...result, text: `[iris] 已删除 ${result.deleted} 个作品，释放 ${(result.bytes / 1048576).toFixed(1)}MB${result.failed ? `；${result.failed} 个删除失败并保留索引` : ''}` };
 });
 
 /** 孤儿产物报告：outputs/ 里无任务引用的文件 + 总占用（只读，不删） */
@@ -947,7 +1059,7 @@ register('tasks_purge_orphans', async () => {
 });
 
 /* ---------- 👁 重看（GUI：只查 iris 自己的任务产物，无会话上下文） ---------- */
-register('relook', async (ctx, args, { signal }) => {
+register('relook', async (host, args, { signal }) => {
   const id = String(args.attachment_id || '').trim();
   if (!id) throw new Error('iris: attachment_id 不能为空');
   const question = String(args.question || '').trim();
@@ -966,8 +1078,8 @@ register('relook', async (ctx, args, { signal }) => {
   if (!hit) throw new Error('iris: 该 attachment 不在 iris 生成的任务产物中（GUI 重看仅支持 iris 画图产物）');
   const mt = hit.mediaType || MEDIA_TYPES[path.extname(hit.absPath).toLowerCase()] || 'image/png';
   const dataUrl = `data:${mt};base64,${fs.readFileSync(hit.absPath).toString('base64')}`;
-  const backends = buildVisionBackends(ctx, { providers: store.pickAllFor(cap.CAPABILITIES.VISION), model: args.model });
-  const { answer, via, model } = await askWithBackends(backends, { question, imageDataUrl: dataUrl, signal });
+  const backends = buildVisionBackendsFromHost(host, { providers: store.pickAllFor(cap.CAPABILITIES.VISION), model: args.model });
+  const { answer, via, model } = await askWithHealth(backends, { question, imageDataUrl: dataUrl, signal });
   const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 全局视觉模型';
   return { ok: true, text: `[iris] 重看回答（${model} · ${viaLabel}）：\n${answer}` };
 });
@@ -975,7 +1087,7 @@ register('relook', async (ctx, args, { signal }) => {
 /* ============ 供应商管理动作（阶段 6 条目 3-5） ============ */
 
 /** 列出全部供应商及其模型池（管理 GUI 用；apiKey 只给 hint） */
-register('providers_list', async (ctx, args) => {
+register('providers_list', async (host, args) => {
   const list = store.allProviders();
   return {
     ok: true,
@@ -987,14 +1099,22 @@ register('providers_list', async (ctx, args) => {
       enabled: p.enabled !== false,
       mediaProtocol: p.mediaProtocol || inferMediaProtocol(p.baseUrl),
       apiKeyHint: String(p.apiKey || '').length <= 8 ? '****' : String(p.apiKey).slice(0, 3) + '****' + String(p.apiKey).slice(-4),
-      models: models.providerModels(p).map((m) => ({ id: m.id, capabilities: m.capabilities, verified: m.verified || null, source: m.source || 'auto' })),
+      models: models.providerModels(p).map((m) => ({
+        id: m.id,
+        capabilities: m.capabilities,
+        verified: m.verified || null,
+        health: Object.fromEntries(m.capabilities.map((capability) => [
+          capability, store.modelHealth(p.id, m.id, capability)
+        ])),
+        source: m.source || 'auto'
+      })),
       capabilities: store.capabilitiesOf(p)
     }))
   };
 });
 
 /** 新增/更新供应商 */
-register('providers_upsert', async (ctx, args) => {
+register('providers_upsert', async (host, args) => {
   const id = args.id || undefined;
   const patch = { id };
   const allowed = ['name', 'type', 'baseUrl', 'apiKey', 'enabled', 'mediaProtocol',
@@ -1008,13 +1128,13 @@ register('providers_upsert', async (ctx, args) => {
 });
 
 /** 删除供应商 */
-register('providers_remove', async (ctx, args) => {
+register('providers_remove', async (host, args) => {
   const ok = store.removeProvider(String(args.id || ''));
   return { ok, removed: ok };
 });
 
 /** 设置某供应商的模型池（覆盖显式 models） */
-register('providers_set_models', async (ctx, args) => {
+register('providers_set_models', async (host, args) => {
   const p = store.setProviderModels(String(args.id || ''), Array.isArray(args.models) ? args.models : []);
   if (!p) throw new Error('iris: 供应商不存在');
   return { ok: true };
@@ -1024,12 +1144,14 @@ register('providers_set_models', async (ctx, args) => {
  * 模型发现（P2）：GET /models 拉全量 → 按规则过滤出媒体能力模型 → 写入显式池。
  * 免费只读；拉不到/不支持则原样保留现有池（优雅降级），报人话错误。
  */
-register('providers_discover', async (ctx, args) => {
+register('providers_discover', async (host, args, { signal }) => {
   const p = store.providerById(String(args.id || ''));
   if (!p) throw new Error('iris: 供应商不存在或未启用');
   let ids;
   try {
-    ids = await adapters.listModels({ key: p.apiKey, baseUrl: p.baseUrl });
+    const providerAdapter = createConfiguredProviderAdapter(p);
+    const discovered = await invokeProviderOperation(providerAdapter, 'discover', { signal });
+    ids = discovered.models.map((model) => model.id);
   } catch (err) {
     throw new Error('iris: 模型发现失败（保留现有池）：' + String(err.message || err));
   }
@@ -1046,16 +1168,22 @@ register('providers_discover', async (ctx, args) => {
 });
 
 /** 能力实测（红色测试图）：对某供应商的 vision 模型跑 testVisionCapability */
-register('providers_test_vision', async (ctx, args) => {
+register('providers_test_vision', async (host, args, { signal }) => {
   const p = store.providerById(String(args.id || ''));
   if (!p) throw new Error('iris: 供应商不存在');
   const visionProviders = store.pickAllFor(cap.CAPABILITIES.VISION).filter((x) => x.id === p.id);
   if (!visionProviders.length) return { ok: true, tested: false, text: '该供应商未配置 vision 模型，跳过' };
-  const backends = buildVisionBackends(ctx, { providers: visionProviders });
+  const backends = buildVisionBackendsFromHost(host, { providers: visionProviders });
   const backend = backends[0];
   if (!backend) return { ok: true, tested: false, text: '该供应商的 vision 配置不可用（类型非 openai）' };
   if (args.confirm_paid !== true) throw new Error('iris: 视觉实测会发起真实供应商请求，请先明确确认');
-  const r = await testVisionCapability(backend, { timeoutMs: 15000, signal: args._signal });
+  const r = await testVisionCapability(backend, { timeoutMs: 15000, signal });
+  store.setModelVerified(p.id, backend.model, cap.CAPABILITIES.VISION, {
+    ok: r.ok,
+    note: r.ok ? '认出红色测试图' : (r.error || '未识别出红色'),
+    category: r.category,
+    status: r.status
+  });
   return {
     ok: true,
     tested: true,
@@ -1069,35 +1197,69 @@ register('providers_test_vision', async (ctx, args) => {
 /* ============ 模型池逐模型管理（阶段 9 P3：手动增删改 + 逐能力实测） ============ */
 
 /** 按能力实测单个模型；返回 {ok, note}。真实调用仅在 UI 明确确认后执行。 */
-async function probeModel(ctx, p, modelId, capability) {
+async function probeModel(host, p, modelId, capability, signal) {
   if (capability === cap.CAPABILITIES.VISION) {
-    const backend = buildVisionBackends(ctx, { providers: [p], model: modelId })[0];
+    const backend = buildVisionBackendsFromHost(host, { providers: [p], model: modelId })[0];
     if (!backend) return { ok: false, note: '非 openai 类型，无法直测' };
-    const r = await testVisionCapability(backend, { timeoutMs: 15000, signal: null });
-    return { ok: r.ok, note: r.ok ? '认出红色测试图' : (r.error || '未识别出红色') };
+    const r = await testVisionCapability(backend, { timeoutMs: 15000, signal });
+    return {
+      ok: r.ok,
+      note: r.ok ? '认出红色测试图' : (r.error || '未识别出红色'),
+      category: r.category,
+      status: r.status
+    };
   }
   if (capability === cap.CAPABILITIES.TRANSCRIBE) {
     return { skipped: true, ok: false, note: '需真实音频，请通过“音频转写”动作验证' };
   }
   if (capability === cap.CAPABILITIES.TTS) {
-    const r = await adapters.synthesizeTts({ key: p.apiKey, baseUrl: p.baseUrl, model: modelId, text: '你好', voice: 'Cherry' });
-    const ok = !!(r.audioUrl || r.audioB64);
-    return { ok, note: ok ? '合成返回音频' : '无音频返回' };
+    const providerAdapter = createConfiguredProviderAdapter(p, { protocol: 'dashscope' });
+    const submitted = await invokeProviderOperation(providerAdapter, 'submit', {
+      capability: 'tts', model: modelId, input: { text: '你好', voice: 'Cherry' }, signal
+    });
+    const value = submitted.kind === 'completed' ? submitted.value : null;
+    const ok = Boolean(value && (value.audioUrl || value.audioB64));
+    return { ok, note: ok ? '合成返回音频' : (submitted.error?.safeMessage || '无音频返回') };
   }
   if (capability === cap.CAPABILITIES.IMAGE) {
-    if ((p.mediaProtocol || inferMediaProtocol(p.baseUrl)) === 'openai-images') {
-      const outs = await adapters.openAiGenerateImage({ key: p.apiKey, baseUrl: p.baseUrl, model: modelId, prompt: 'red circle', size: '256x256', n: 1 });
-      return { ok: outs.length > 0, note: outs.length ? '生成返回图片' : '无图片返回' };
+    const providerAdapter = createConfiguredProviderAdapter(p);
+    const submitted = await invokeProviderOperation(providerAdapter, 'submit', {
+      capability: 'image', model: modelId,
+      input: {
+        prompt: providerAdapter.protocol === 'openai-images' ? 'red circle' : '红色圆形',
+        size: providerAdapter.protocol === 'openai-images' ? '256x256' : '512*512',
+        n: 1
+      },
+      signal
+    });
+    if (submitted.kind === 'completed') {
+      const items = Array.isArray(submitted.value?.items) ? submitted.value.items : [];
+      return { ok: items.length > 0, note: items.length ? '生成返回图片' : '无图片返回' };
     }
-    const started = await adapters.startImageGeneration({ key: p.apiKey, baseUrl: p.baseUrl, model: modelId, prompt: '红色圆形', size: '512*512', n: 1 });
-    if (!started.remoteTaskId) {
-      return { ok: (started.urls || []).length > 0, note: (started.urls || []).length ? '生成成功' : '无图片返回' };
+    if (submitted.kind !== 'accepted') {
+      return {
+        ok: false,
+        note: submitted.error?.safeMessage || '提交未被确认受理',
+        category: submitted.error?.category,
+        httpStatus: submitted.error?.httpStatus
+      };
     }
-    // 有界轮询到终态（图像通常 5–15s）
     for (let i = 0; i < 20; i++) {
-      await new Promise((r) => setTimeout(r, 3000));
-      const st = await adapters.pollTask({ key: p.apiKey, baseUrl: p.baseUrl, remoteTaskId: started.remoteTaskId });
-      if (st.done) return { ok: st.ok && (st.urls || []).length > 0, note: st.ok ? '生成成功' : (st.message || '生成失败') };
+      throwIfAborted(signal);
+      await new Promise((resolve) => setTimeout(resolve, 3000));
+      const polled = await invokeProviderOperation(providerAdapter, 'poll', {
+        capability: 'image', remoteTaskId: submitted.remoteTaskId, signal
+      });
+      if (polled.kind === 'pending') continue;
+      if (polled.kind === 'succeeded') {
+        return { ok: polled.artifacts.length > 0, note: polled.artifacts.length ? '生成成功' : '无图片返回' };
+      }
+      return {
+        ok: false,
+        note: polled.error?.safeMessage || ('生成终态：' + polled.kind),
+        category: polled.error?.category,
+        httpStatus: polled.error?.httpStatus
+      };
     }
     return { ok: false, note: '生成超时（>60s）' };
   }
@@ -1108,7 +1270,7 @@ async function probeModel(ctx, p, modelId, capability) {
 }
 
 /** 手动添加模型到池（能力可选，缺省按规则推断） */
-register('providers_add_model', async (ctx, args) => {
+register('providers_add_model', async (host, args) => {
   const id = String(args.id || '');
   const modelId = String(args.model_id || '').trim();
   if (!modelId) throw new Error('iris: model_id 不能为空');
@@ -1121,14 +1283,14 @@ register('providers_add_model', async (ctx, args) => {
 });
 
 /** 从池移除模型 */
-register('providers_remove_model', async (ctx, args) => {
+register('providers_remove_model', async (host, args) => {
   const ok = store.removeProviderModel(String(args.id || ''), String(args.model_id || ''));
   if (!ok) throw new Error('iris: 模型不在池中');
   return { ok: true, text: `[iris] 已移除模型 ${args.model_id}` };
 });
 
 /** 纠正某模型的能力标签 */
-register('providers_set_model_caps', async (ctx, args) => {
+register('providers_set_model_caps', async (host, args) => {
   const caps = (Array.isArray(args.capabilities) ? args.capabilities : []).filter((c) => cap.isKnownCapability(c));
   const ok = store.setModelCapabilities(String(args.id || ''), String(args.model_id || ''), caps);
   if (!ok) throw new Error('iris: 模型不在池中');
@@ -1136,7 +1298,7 @@ register('providers_set_model_caps', async (ctx, args) => {
 });
 
 /** 逐模型实测某能力 → 存 verified（"test it, don't guess it"；用户手动触发，发现不自动跑） */
-register('providers_test_model', async (ctx, args) => {
+register('providers_test_model', async (host, args, { signal }) => {
   const p = store.providerById(String(args.id || ''));
   if (!p) throw new Error('iris: 供应商不存在或未启用');
   const modelId = String(args.model_id || '').trim();
@@ -1147,9 +1309,14 @@ register('providers_test_model', async (ctx, args) => {
   }
   let result;
   try {
-    result = await probeModel(ctx, p, modelId, capability);
+    result = await probeModel(host, p, modelId, capability, signal);
   } catch (err) {
-    result = { ok: false, note: String(err.message || err) };
+    result = {
+      ok: false,
+      note: String(err && (err.safeMessage || err.message) || err),
+      category: err && err.category,
+      httpStatus: err && (err.httpStatus ?? err.status)
+    };
   }
   if (result.skipped) {
     return { ok: true, skipped: true, passed: false, text: `[iris] ${modelId} · ${capability} 已跳过：${result.note}` };
@@ -1165,7 +1332,7 @@ register('providers_test_model', async (ctx, args) => {
 /* ============ 能力分配动作（阶段 6 条目 4） ============ */
 
 /** 查询：全部分配 + 每个能力可用的模型池（client 渲染下拉/排序） */
-register('assignments_get', async (ctx, args) => {
+register('assignments_get', async (host, args) => {
   const pool = models.modelPool(store.allProviders());
   const byCap = {};
   for (const m of pool) {
@@ -1185,7 +1352,7 @@ register('assignments_get', async (ctx, args) => {
  *   model_refs 数组 = Provider+模型复合引用的有序 failover 列表；
  *   model_ids/model_id 保留为旧客户端兼容入口。
  */
-register('assignments_set', async (ctx, args) => {
+register('assignments_set', async (host, args) => {
   const capability = String(args.capability || '').trim();
   if (!capability) throw new Error('iris: capability 不能为空');
   const listArg = Array.isArray(args.model_refs) ? args.model_refs : args.model_ids;
@@ -1204,45 +1371,19 @@ register('assignments_set', async (ctx, args) => {
 
 /* ============ 文件选择器 L1：会话附件枚举（阶段 10） ============ */
 
-/** 深度遍历会话事件，收集所有 image 附件引用（去重 by attachmentId） */
-function collectImageAttachments(nodes) {
-  const out = [];
-  const seen = new Set();
-  const visited = new Set();
-  const stack = Array.isArray(nodes) ? [...nodes] : [nodes];
-  let scanned = 0;
-  while (stack.length && scanned < 8000) {
-    const node = stack.pop();
-    scanned++;
-    if (!node || typeof node !== 'object' || visited.has(node)) continue;
-    visited.add(node);
-    const ref = node.attachment && typeof node.attachment === 'object' ? node.attachment
-      : (node.attachmentId && node.mediaType ? node : null);
-    if (ref && typeof ref.attachmentId === 'string' && typeof ref.mediaType === 'string' && ref.mediaType.startsWith('image/')) {
-      if (!seen.has(ref.attachmentId)) {
-        seen.add(ref.attachmentId);
-        out.push({ attachmentId: ref.attachmentId, mediaType: ref.mediaType, name: ref.name || '', source: 'session' });
-      }
-    }
-    for (const v of Object.values(node)) if (v && typeof v === 'object') stack.push(v);
-  }
-  return out;
-}
-
 /**
  * 枚举可选附件：当前会话的 image 附件（readSession）+ iris 自有产物（全局，兜底）。
  * 客户端传当前会话 id；读不到会话也不报错，退化为只列 iris 产物。
  */
-register('attachments_list', async (ctx, args) => {
+register('attachments_list', async (host, args) => {
   const items = [];
   const seen = new Set();
   const sessionId = String(args.session_id || '').trim();
-  const sq = ctx && typeof ctx.get === 'function' ? ctx.get('sessionQuery') : undefined;
-  if (sessionId && sq && typeof sq.readSession === 'function') {
+  const sessions = hasHostPort(host, 'sessions') ? host.ports.sessions : undefined;
+  if (sessionId && sessions) {
     try {
-      const events = (await sq.readSession(sessionId)).events;
-      for (const a of collectImageAttachments(events)) {
-        if (!seen.has(a.attachmentId)) { seen.add(a.attachmentId); items.push(a); }
+      for (const a of await sessions.listImageAttachments(sessionId)) {
+        if (!seen.has(a.attachmentId)) { seen.add(a.attachmentId); items.push({ ...a, source: 'session' }); }
       }
     } catch (_) {
       /* 读不到会话 → 只列 iris 产物 */
@@ -1263,7 +1404,7 @@ register('attachments_list', async (ctx, args) => {
  * 把一个附件（会话 image 或 iris 产物）导出为宿主可读的文件路径，供工具消费。
  * iris 产物直接返回其 outputs 路径；会话附件读字节存 uploads/（按 attachmentId 哈希缓存，不重复落盘）。
  */
-register('attachment_export', async (ctx, args) => {
+register('attachment_export', async (host, args, { signal }) => {
   const id = String(args.attachment_id || '').trim();
   if (!id) throw new Error('iris: attachment_id 不能为空');
   // 1) iris 自有产物：文件已在 outputs/
@@ -1280,18 +1421,13 @@ register('attachment_export', async (ctx, args) => {
   const cached = path.join(uploads, 'att-' + id.replace(/[^a-z0-9]/gi, '').slice(-40));
   if (fs.existsSync(cached)) return { ok: true, path: cached, name: path.basename(cached) };
   const sessionId = String(args.session_id || '').trim();
-  const sq = ctx && typeof ctx.get === 'function' ? ctx.get('sessionQuery') : undefined;
-  const att = ctx && typeof ctx.get === 'function' ? ctx.get('attachments') : undefined;
-  if (!sessionId || !sq || !att || typeof att.readImage !== 'function') {
-    throw new Error('iris: 该附件不可导出（非 iris 产物，且缺会话/附件服务上下文）');
-  }
+  if (!sessionId) throw new Error('iris: 非 Iris 产物必须提供 session_id');
+  const sessions = requireHostPort(host, 'sessions', '导出会话附件');
+  const attachments = requireHostPort(host, 'attachments', '导出会话附件');
   let ref = null;
-  try {
-    const events = (await sq.readSession(sessionId)).events;
-    for (const a of collectImageAttachments(events)) if (a.attachmentId === id) { ref = a; break; }
-  } catch (_) { /* ignore */ }
+  try { ref = await sessions.findImageAttachment(sessionId, id); } catch (_) { /* 统一为未找到 */ }
   if (!ref) throw new Error('iris: 该 attachment 不在本会话中、也不是 iris 产物：' + id);
-  const stored = await att.readImage({ attachmentId: ref.attachmentId, mediaType: ref.mediaType }, null);
+  const stored = await attachments.readImage(ref, signal);
   ensurePrivateDir(uploads);
   writePrivateFile(cached, Buffer.from(stored.data));
   return { ok: true, path: cached, name: ref.name || path.basename(cached) };
@@ -1299,7 +1435,7 @@ register('attachment_export', async (ctx, args) => {
 
 /* ============ 音频转写（阶段 7.2） ============ */
 
-register('transcribe', async (ctx, args, { signal }) => {
+register('transcribe', async (host, args, { signal }) => {
   const audioPath = String(args.audio_path || '').trim();
   if (!audioPath || !path.isAbsolute(audioPath)) throw new Error('iris: audio_path 必须是绝对路径');
   if (!fs.existsSync(audioPath)) throw new Error('iris: 音频文件不存在');
@@ -1317,7 +1453,7 @@ register('transcribe', async (ctx, args, { signal }) => {
 
 /* ============ 视频抽帧（阶段 7.1） ============ */
 
-register('video_frames', async (ctx, args, { signal }) => {
+register('video_frames', async (host, args, { signal }) => {
   const p = String(args.video_path || '').trim();
   if (!p || !path.isAbsolute(p)) throw new Error('iris: video_path 必须是绝对路径');
   if (!fs.existsSync(p)) throw new Error('iris: 视频文件不存在');
@@ -1342,7 +1478,7 @@ register('video_frames', async (ctx, args, { signal }) => {
 
 /* ============ 多模态视频摘要（阶段 7.3，GUI 同步快速版） ============ */
 
-register('media_summarize', async (ctx, args, { signal }) => {
+register('media_summarize', async (host, args, { signal }) => {
   const p = String(args.video_path || '').trim();
   if (!p || !path.isAbsolute(p)) throw new Error('iris: video_path 必须是绝对路径');
   if (!fs.existsSync(p)) throw new Error('iris: 视频文件不存在');
@@ -1353,7 +1489,7 @@ register('media_summarize', async (ctx, args, { signal }) => {
     format: 'jpeg', quality: 70, signal
   });
   const sheet = await buildContactSheet({ frames, cols: 3 });
-  const backends = buildVisionBackends(ctx, { providers: store.pickAllFor(cap.CAPABILITIES.VISION), model: args.model });
+  const backends = buildVisionBackendsFromHost(host, { providers: store.pickAllFor(cap.CAPABILITIES.VISION), model: args.model });
   const { answer, via, model } = await summarizeMedia({
     backends, question: args.question,
     transcript: args.transcribe_text, // GUI 同步版：不自动转写，可粘贴已有转写文本