@mokuyoaxis/dsh-iris 0.2.5 → 0.2.6

package/lib/headless-vision.js

@@ -70,9 +70,9 @@ function completionResult(completion, routes) {
   return { ...result, ...selectedModel(completion, routes) };
 }
 
-async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit }) {
+async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit, onModelAvailability }) {
   const routes = transcribeCandidatesFromCatalog(catalog, input.transcribe_model_ref);
-  const candidates = routes.map(route => ({ adapter: createConfiguredProviderAdapter(route.provider, { onRateLimit }),
+  const candidates = routes.map(route => ({ adapter: createConfiguredProviderAdapter(route.provider, { onRateLimit, onModelAvailability }),
     model: route.modelRef, selectionReason: route.selectionReason, providerBinding: providerTaskBinding(route.provider) }));
   const audio = await waitForModelWork(() => extractAudioTrack({ inputPath: input.video_path, signal: operation.signal }), operation.signal);
   const abortRuntime = () => { void runtime.dispose().catch(() => {}); };
@@ -111,7 +111,7 @@ async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit
   }
 }
 
-export async function executeVisionCommand({ command, input, catalog, modelRef = '', runtime, signal, timeoutMs = VISION_BUDGET.timeoutMs, onRateLimit }) {
+export async function executeVisionCommand({ command, input, catalog, modelRef = '', runtime, signal, timeoutMs = VISION_BUDGET.timeoutMs, onRateLimit, onModelAvailability }) {
   normalizeVisionInput(command, input);
   if (modelRef && !/^[^:]+::.+$/.test(modelRef)) invalid('--model-ref 必须是 providerId::modelId');
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > VISION_BUDGET.timeoutMs) invalid('--timeout-ms 必须是 1–120000 的整数');
@@ -121,7 +121,7 @@ export async function executeVisionCommand({ command, input, catalog, modelRef =
   const inputs = new Map();
   const prepareImageRequest = command === 'locate' ? createLocateImageRequest(input.target, inputs)
     : command === 'ocr' ? createVisionInputObserver(inputs) : undefined;
-  const ports = routes.map(route => createConfiguredVisionModelPort(route.provider, route.model, { onRateLimit,
+  const ports = routes.map(route => createConfiguredVisionModelPort(route.provider, route.model, { onRateLimit, onModelAvailability,
     prepareImages: ['look', 'ocr', 'locate'].includes(command), orientImages: command === 'locate', prepareImageRequest }));
   const budget = { ...VISION_BUDGET, timeoutMs };
   const operation = createModelOperation({ signal, budget: { timeoutMs, maxInvocations: command === 'ocr' ? input.max_invocations ?? 64 : ports.length } });
@@ -140,7 +140,7 @@ export async function executeVisionCommand({ command, input, catalog, modelRef =
       }
       let transcript = input.transcribe_text || '', transcription = { status: transcript.trim() ? 'provided' : 'disabled' };
       if (input.transcribe) {
-        const asr = meta.hasAudio ? await transcribeVideo({ catalog, input, runtime, operation, onRateLimit }) : { report: { status: 'no_audio' }, text: '' };
+        const asr = meta.hasAudio ? await transcribeVideo({ catalog, input, runtime, operation, onRateLimit, onModelAvailability }) : { report: { status: 'no_audio' }, text: '' };
         transcript = asr.text; transcription = asr.report;
       }
       const completion = await summarizeMedia({ ports, frames, question: input.question, transcript, operation, budget });

package/lib/host-contract.js

@@ -13,6 +13,7 @@ export const HOST_PORTS = Object.freeze([
   'attachments',
   'browser',
   'clientSlots',
+  'providerConnections',
   'routes',
   'sessions',
   'skills',

package/lib/http-vision-model-adapter.js

@@ -5,6 +5,7 @@ import { ModelPortError, normalizeModelDescriptor, normalizeModelCall, normalize
 import { modelCallScope, modelAbortError, waitForModelWork } from './model-call-runtime.js';
 import { createHash } from 'node:crypto';
 import { isFreeQuotaExhausted, retryAfterDelay } from './provider-health.js';
+import { isModelNotFound } from './model-directory.js';
 import { prepareVisionImage } from './vision-image-input.js';
 
 const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -103,7 +104,7 @@ export function createHttpVisionModelPort({ providerId, modelId, baseUrl, apiKey
           });
         }, signal, 'invoke', 'unknown');
         if (!response.ok) {
-          const body = [400, 403, 413, 429].includes(response.status) ? await waitForModelWork(() => response.json().catch(() => null), signal, 'read', 'rejected') : null;
+          const body = [400, 403, 404, 413, 429].includes(response.status) ? await waitForModelWork(() => response.json().catch(() => null), signal, 'read', 'rejected') : null;
           // 只提取可验证的数值事实，不把供应商原文或凭据带到 UI/CLI。
           const limit = [400, 413].includes(response.status)
             ? /\b(\d+) bytes exceeds the (\d+)-byte limit\b/i.exec(String(body?.error?.message || body?.message || '')) : null;
@@ -114,10 +115,12 @@ export function createHttpVisionModelPort({ providerId, modelId, baseUrl, apiKey
               imageBytes: image.bytes.byteLength, ...(maxBytes ? { imageMaxBytes: maxBytes } : {}) });
           }
           const quota = isFreeQuotaExhausted({ status: response.status, ...(body?.error || body) });
-          const code = quota ? 'IRIS_MODEL_RATE_LIMITED' : [401, 403].includes(response.status) ? 'IRIS_MODEL_AUTH_FAILED'
+          const missing = isModelNotFound({ status: response.status, ...(body?.error || body) });
+          const code = missing ? 'IRIS_MODEL_UNAVAILABLE' : quota ? 'IRIS_MODEL_RATE_LIMITED' : [401, 403].includes(response.status) ? 'IRIS_MODEL_AUTH_FAILED'
             : response.status === 429 ? 'IRIS_MODEL_RATE_LIMITED' : response.status === 400 ? 'IRIS_MODEL_INPUT_INVALID' : 'IRIS_MODEL_REQUEST_FAILED';
           const error = new ModelPortError(code, { stage: 'invoke', invocation: code === 'IRIS_MODEL_REQUEST_FAILED' ? 'unknown' : 'rejected', status: response.status });
           error.providerCode = (body?.error || body)?.code;
+          if (missing) error.providerCode = 'model_not_found';
           if (response.status === 429) error.retryAfterMs = retryAfterDelay(response.headers.get('retry-after'));
           if (quota) error.quotaExhausted = true;
           throw error;

package/lib/index.js

@@ -18,6 +18,8 @@ import { runVisionRequest, readVisionImageFile } from './vision-model-routing.js
 import { waitForModelWork } from './model-call-runtime.js';
 import { hasHostPort, requireHostPort } from './host-contract.js';
 import { createDshHostAdapter } from './dsh-host-adapter.js';
+import { withDshProviderConfig } from './dsh-provider-config.js';
+import { configureProviderHostForDsh } from './dsh-core-adapter.js';
 import { cropForDsh, diffForDsh, framesForDsh, summaryFramesForDsh, visionImageForDsh, htmlForDsh, inspectProviderTaskForDsh, projectCoreTaskForDsh, readCoreArtifactMediaForDsh, resumeProviderTaskWatchesForDsh, stopProviderTaskWatchesForDsh } from './dsh-core-adapter.js';
 import { imageDimensions } from './pixels.js';
 import { runLocateRequest, runSummaryRequest, describeGeneratedImage } from './composite-vision-routing.js';
@@ -219,6 +221,7 @@ function safeRegister(host, definition) {
 
 export async function apply(ctx) {
   beginHostRuntime({ pluginId: IRIS_PLUGIN_ID, version: PACKAGE_VERSION });
+  const releaseProviderHost = configureProviderHostForDsh(() => dshHost(ctx));
   guard('Iris 私有存储权限收紧', () => hardenPrivateTree(store.irisHome()));
 
   guard('上传临时文件清理', () => purgeStaleUploads());
@@ -254,6 +257,7 @@ export async function apply(ctx) {
     ctx.effect(() => () => {
       tasks.stopWatchAll();
       stopProviderTaskWatchesForDsh();
+      releaseProviderHost();
     });
   });
 
@@ -274,6 +278,20 @@ export async function apply(ctx) {
   });
 
   const host = dshHost(ctx);
+  const providerTools = new Set(['iris_draw_image', 'iris_edit_image', 'iris_generate_video', 'iris_generate_music',
+    'iris_speak_text', 'iris_transcribe_audio', 'iris_look_at_image', 'iris_relook_attachment',
+    'iris_media_summarize', 'iris_locate', 'iris_long_ocr']);
+  const visionTools = new Set(['iris_look_at_image', 'iris_relook_attachment', 'iris_media_summarize', 'iris_locate', 'iris_long_ocr']);
+  function registerIrisTool(definition) {
+    safeRegister(host, { ...definition, execute(args, exec) {
+      const execute = async () => {
+        if (visionTools.has(definition.name) && !args?.model) await store.refreshAutomaticDirectories({ capability: 'vision', signal: exec.signal });
+        return definition.execute(args, exec);
+      };
+      return providerTools.has(definition.name)
+        ? withDshProviderConfig(dshHost(ctx), execute, { signal: exec.signal }) : execute();
+    } });
+  }
   if (!hasHostPort(host, 'tools')) {
     console.error('[iris] tools 服务不可用，跳过全部工具注册（宿主不受影响）');
     return;
@@ -291,7 +309,7 @@ export async function apply(ctx) {
     let note = '';
     try {
       const described = await describeGeneratedImage(dshHost(ctx), {
-        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, originalPrompt: prompt, signal,
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability, originalPrompt: prompt, signal,
         async prepareImage(inputSignal) {
           const first = await readCoreArtifactMediaForDsh(projected.artifacts[0].artifact.id, { signal: inputSignal });
           return { bytes: new Uint8Array(first.bytes), mediaType: first.artifact.mediaType };
@@ -309,7 +327,7 @@ export async function apply(ctx) {
     return { blocks };
   }
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_import_image',
     description: 'Save a local image or a current-session image attachment as a persistent Iris image Artifact for later viewing, editing and export. Provide exactly one of image_path or attachment_id. Supports static PNG/JPEG/WebP up to 20 MiB, preserves the source, and never calls a model.',
     parameters: {
@@ -334,7 +352,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🖼️ 画图 ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_draw_image',
     description:
       'Generate an image from a detailed prompt using the user-configured image model and its configured image protocol. ' +
@@ -345,7 +363,7 @@ export async function apply(ctx) {
         prompt: { type: 'string', description: 'Detailed visual description of the image to create' },
         size: { type: 'string', description: "Output size; DashScope uses 'W*H' (e.g. '1024*1024'), OpenAI uses 'WxH'. Default provider default." },
         n: { type: 'string', description: "Number of images, default '1'" },
-        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id also accepted)' }
+        model: { type: 'string', description: 'Optional providerId::modelId in the enabled function pool; selects only this item (legacy bare model id also accepted)' }
       },
       required: ['prompt']
     },
@@ -390,7 +408,7 @@ export async function apply(ctx) {
       let note = '';
       try {
         const described = await describeGeneratedImage(dshHost(ctx), {
-          providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, originalPrompt: prompt, signal: exec.signal,
+          providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability, originalPrompt: prompt, signal: exec.signal,
           prepareImage: signal => readVisionImageFile(files[0], MEDIA_TYPES[path.extname(files[0]).toLowerCase()] || 'image/png', signal)
         });
         if (described) note = `画面内容：${described}`;
@@ -405,14 +423,14 @@ export async function apply(ctx) {
     }
   });
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_edit_image',
-    description: 'Edit an existing Core image by Artifact ID and an instruction using an assigned chat-image model or native DashScope Qwen edit model. Returns new Core Artifacts and DSH image attachments; preserves the source image and records its provenance.',
+    description: 'Edit an existing Core image by Artifact ID and an instruction using an allowed chat-image model or native DashScope Qwen edit model. Returns new Core Artifacts and DSH image attachments; preserves the source image and records its provenance.',
     parameters: {
       type: 'object', properties: {
         source_artifact_id: { type: 'string', description: 'Core Artifact ID of the source PNG, JPEG or WebP image (up to 20 MiB)' },
         prompt: { type: 'string', description: 'Describe the changes and what should be preserved in the source image' },
-        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item; supports openai-chat-images or DashScope Qwen edit/max/plus and 2.0/pro models' },
+        model: { type: 'string', description: 'Optional providerId::modelId in the enabled image pool; selects only this item; supports openai-chat-images or DashScope Qwen edit/max/plus and 2.0/pro models' },
         n: { type: 'string', description: "Number of images, default '1'" }
       }, required: ['source_artifact_id', 'prompt']
     },
@@ -425,7 +443,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🎬 视频生成 ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_generate_video',
     description:
       'Generate a video with the configured DashScope video model. Three modes: ' +
@@ -443,7 +461,7 @@ export async function apply(ctx) {
         resolution: { type: 'string', description: "s2v only: output tier '480P' (default) or '720P'" },
         size: { type: 'string', description: "t2v/i2v only: output size 'W*H', e.g. '1280*720' (default)" },
         duration: { type: 'number', description: 't2v/i2v only: duration in seconds, if the model supports it' },
-        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional providerId::modelId in the enabled function pool; selects only this item (legacy bare model id accepted)' }
       },
       required: []
     },
@@ -487,12 +505,12 @@ export async function apply(ctx) {
     }
   });
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_generate_music',
-    description: 'Generate music using a model explicitly assigned to Music. Returns audio artifact IDs and playback links. Lyrics, vocals and duration are prompt intentions. Configured 502 retries may generate again.',
+    description: 'Generate music using a model in the enabled Music pool. Returns audio artifact IDs and playback links. Lyrics, vocals and duration are prompt intentions. Configured 502 retries may generate again.',
     parameters: { type: 'object', properties: {
       prompt: { type: 'string', description: 'Describe the music, including any lyrics, vocals, mood or intended duration' },
-      model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item' },
+      model: { type: 'string', description: 'Optional providerId::modelId in the enabled Music pool; selects only this item' },
       timeout_ms: { type: 'integer', description: 'Per-attempt timeout; default 300000 ms' },
       retry_502: { type: 'integer', description: '502 regeneration retries, 0–5; default 2; each retry consumes another request' },
       retry_delay_ms: { type: 'integer', description: 'Delay between 502 retries; default 5000 ms' }
@@ -507,7 +525,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🔊 语音合成 ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_speak_text',
     description: 'Synthesize spoken audio from text using the configured TTS model. Returns Core audio Artifact IDs and playback links; export an Artifact to a host file before passing it as audio_path to another tool. Use iris_generate_music for songs or background music.',
     parameters: {
@@ -515,7 +533,7 @@ export async function apply(ctx) {
       properties: {
         text: { type: 'string', description: 'Text to speak' },
         voice: { type: 'string', description: "Voice name, e.g. 'Cherry' (DashScope qwen-tts voices)" },
-        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional providerId::modelId in the enabled function pool; selects only this item (legacy bare model id accepted)' }
       },
       required: ['text']
     },
@@ -545,14 +563,14 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🎙️ 音频转写（阶段 7.2） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_transcribe_audio',
     description: 'Transcribe an audio file (wav/mp3) to text using the configured DashScope provider (qwen-audio-3.0-asr-flash-filetrans). The audio is uploaded to Bailian temp storage, then an async task is submitted. Returns the full recognized text.',
     parameters: {
       type: 'object',
       properties: {
         audio_path: { type: 'string', description: 'Absolute path to the audio file (wav/mp3)' },
-        model: { type: 'string', description: 'Optional assigned transcription providerId::modelId; selects only this item (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional providerId::modelId in the enabled transcription pool; selects only this item (legacy bare model id accepted)' }
       },
       required: ['audio_path']
     },
@@ -588,7 +606,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🎞️ 视频抽帧（阶段 7.1，ffmpeg 可选） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_video_frames',
     description:
       'Extract N frames (uniformly sampled across the video) from a local video file using the system ffmpeg. ' +
@@ -646,7 +664,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📝 多模态视频摘要（阶段 7.3，ffmpeg 可选） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_media_summarize',
     description:
       'Summarize a local video or existing Core video-frame Artifacts as one contact sheet (with timestamps) plus an optional ' +
@@ -664,7 +682,7 @@ export async function apply(ctx) {
         target_width: { type: 'integer', description: 'Frame width for sampling (default 640)' },
         transcribe: { type: 'boolean', description: 'Auto-transcribe the audio track for video_path (default true unless transcribe_text is provided). Existing frames only consume explicit text.' },
         transcribe_text: { type: 'string', description: 'Optional existing transcript text; does not create a transcription task' },
-        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
+        model: { type: 'string', description: 'Optional item from the enabled vision pool (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: []
     },
@@ -679,7 +697,7 @@ export async function apply(ctx) {
         if (!ffmpegAvailable()) throw new Error('iris: ffmpeg 不可用，无法分析视频（可选安装 ffmpeg/ffprobe 后启用）');
       }
       const { answer, via, model, sheet, meta, frames, transcriptNote } = await runSummaryRequest(dshHost(ctx), {
-        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, model: args.model, question: args.question, signal: exec.signal,
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability, model: args.model, question: args.question, signal: exec.signal,
         async prepareMedia(signal) {
           if (source === 'core-artifacts') {
             return { ...await summaryFramesForDsh({ frameArtifactIds: args.frame_artifact_ids, signal }), transcript: args.transcribe_text };
@@ -745,7 +763,7 @@ export async function apply(ctx) {
 
   /* ---------- 👁 视觉路由（M3）：显式工具，自持栈为主 ---------- */
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_look_at_image',
     description:
       'Look at a local image file or an existing Core image Artifact and answer one question with the configured vision model (self-hosted provider stack, then DSH default vision). Provide exactly one of image_path or artifact_id. Local files are saved as durable DSH attachments; Core images are read directly without export or Core writes.',
@@ -755,7 +773,7 @@ export async function apply(ctx) {
         image_path: { type: 'string', description: 'Absolute path to the image file (png/jpg/jpeg/webp)' },
         artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path)' },
         question: { type: 'string', description: 'Question or extraction request about the image; defaults to a detailed description' },
-        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
+        model: { type: 'string', description: 'Optional item from the enabled vision pool (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: []
     },
@@ -784,7 +802,7 @@ export async function apply(ctx) {
     }
   });
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_relook_attachment',
     description:
       'Ask a NEW question about an image that was already seen in this session: pass its attachment_id (from user uploads, tool results, or any iris-generated image). Pixels are re-read via the vision model.',
@@ -793,7 +811,7 @@ export async function apply(ctx) {
       properties: {
         attachment_id: { type: 'string', description: 'The attachment_id of an image that appeared in this session or was generated by iris' },
         question: { type: 'string', description: 'New question about the image pixels' },
-        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
+        model: { type: 'string', description: 'Optional item from the enabled vision pool (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: ['attachment_id', 'question']
     },
@@ -820,7 +838,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📋 任务查询 ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_task_status',
     description:
       'Query Iris tasks (image/video/tts/music/transcription). Pass a task_id for one task, or omit it to list recent tasks. Core results provide Artifact IDs and playback links; legacy tasks may provide file paths. Querying does not re-observe or redeliver a task.',
@@ -840,7 +858,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- ✂️ 确定性像素工具（阶段 2） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_crop',
     description:
       'Crop a rectangular region from an image (absolute local path or a session attachment_id) and save the result as a durable DSH attachment. ' +
@@ -890,7 +908,7 @@ export async function apply(ctx) {
     }
   });
 
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_pixel_diff',
     description:
       'Compute a pixel-level difference between two images (absolute local paths or session attachment_ids). ' +
@@ -945,7 +963,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📍 模型驱动定位（阶段 3A） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_locate',
     description:
       'Locate an object/region described by `target` in an image (exactly one of absolute image_path, Core artifact_id, or session attachment_id), ' +
@@ -958,7 +976,7 @@ export async function apply(ctx) {
         artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path or attachment_id)' },
         attachment_id: { type: 'string', description: 'Session attachment id of an image (alternative to image_path)' },
         target: { type: 'string', description: 'The object or UI element to locate, e.g. "send button"' },
-        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
+        model: { type: 'string', description: 'Optional item from the enabled vision pool (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: ['target']
     },
@@ -966,7 +984,7 @@ export async function apply(ctx) {
     isConcurrencySafe: () => true,
     async execute(args, exec) {
       const r = await runLocateRequest(dshHost(ctx), {
-        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, model: args.model, target: args.target,
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability, model: args.model, target: args.target,
         prepareImage: signal => resolveVisionImageInput(dshHost(ctx), exec, args, signal), signal: exec.signal
       });
       const { width, height } = r;
@@ -980,7 +998,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 🖼️ HTML 截图（阶段 3C，基于 dsh-builtin-browser） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_html_screenshot',
     description:
       'Render an HTML string to a page screenshot using the shared browser. ' +
@@ -1033,7 +1051,7 @@ export async function apply(ctx) {
   });
 
   /* ---------- 📄 长截图 OCR（阶段 3B，视觉模型分块） ---------- */
-  safeRegister(host, {
+  registerIrisTool({
     name: 'iris_long_ocr',
     description:
       'OCR a (possibly long) image from exactly one of image_path, Core artifact_id, or session attachment_id: slice it into chunks (1200px tall with 120px overlap by default) ' +
@@ -1055,7 +1073,7 @@ export async function apply(ctx) {
     async execute(args, exec) {
       const host = dshHost(ctx);
       const result = await runOcrRequest(host, {
-        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit,
+        providers: store.pickAllFor(cap.CAPABILITIES.VISION), onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability,
         prepareImage: operationSignal => resolveVisionImageInput(host, exec, args, operationSignal),
         chunkHeight: args.chunk_height,
         overlap: args.overlap,
@@ -1180,7 +1198,8 @@ export async function sessionAttachmentRef(host, exec, attachmentId) {
  */
 export async function askVision(host, { question, dataUrl, image, prepareImage, signal, model, budget }) {
   const visionProviders = store.pickAllFor(cap.CAPABILITIES.VISION);
-  return runVisionRequest(host, { providers: visionProviders, model, question, dataUrl, image, prepareImage, signal, budget, onRateLimit: store.recordRateLimit });
+  return runVisionRequest(host, { providers: visionProviders, model, question, dataUrl, image, prepareImage, signal, budget,
+    onRateLimit: store.recordRateLimit, onModelAvailability: store.recordAvailability });
 }
 
 /**

package/lib/model-directory-service.js

@@ -0,0 +1,53 @@
+import { listModels } from './adapters.js';
+import { capabilitiesOfDiscoveredModel } from './models.js';
+import { providerApiKey, providerMediaBaseUrl, selectMediaProtocol } from './provider-protocol.js';
+import { redactProviderMessage } from './provider-contract.js';
+import { MODEL_DIRECTORY_TTL_MS, MODEL_DIRECTORY_RETRY_MS, currentModelDirectory, modelDirectoryBinding } from './model-directory.js';
+
+const pending = new Map();
+
+/** 只有完整发现成功才替换快照；相同连接合并网络读取，各调用方保存自己的配置。 */
+export async function refreshModelDirectory(provider, { force = false, signal, save, discover = listModels, now = Date.now() } = {}) {
+  if (!['dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images', 'gemini-web-music'].includes(selectMediaProtocol(provider).mediaProtocol)) {
+    return { refreshed: false, error: '当前协议未提供模型目录发现' };
+  }
+  const previous = currentModelDirectory(provider);
+  if (!force && previous) {
+    const stale = Boolean(previous.lastError) || !previous.checkedAt || now - Date.parse(previous.checkedAt) >= MODEL_DIRECTORY_TTL_MS
+      || Date.parse(previous.invalidatedAt || '') >= Date.parse(previous.checkedAt);
+    if (!stale || (previous.failedAt && now - Date.parse(previous.failedAt) < MODEL_DIRECTORY_RETRY_MS)) {
+      return { refreshed: false, directory: previous, ...(previous.lastError ? { error: previous.lastError } : {}) };
+    }
+  }
+  signal?.throwIfAborted();
+  const binding = modelDirectoryBinding(provider);
+  let job = pending.get(binding);
+  if (!job) {
+    const budget = AbortSignal.timeout(15000);
+    job = discover({ key: providerApiKey(provider), baseUrl: providerMediaBaseUrl(provider),
+      signal: signal ? AbortSignal.any([signal, budget]) : budget, timeoutMs: 15000 });
+    pending.set(binding, job);
+    job.finally(() => { if (pending.get(binding) === job) pending.delete(binding); }).catch(() => {});
+  }
+  let discovered;
+  try {
+    discovered = await job;
+  } catch (error) {
+    signal?.throwIfAborted();
+    const key = providerApiKey(provider);
+    const message = String(error?.message || error);
+    const directory = { version: 1, binding, ...(previous || {}), failedAt: new Date(now).toISOString(),
+      lastError: redactProviderMessage(key ? message.split(key).join('[REDACTED]') : message) };
+    if (await save(directory) === false) return { refreshed: false, error: '连接在目录同步期间发生变化，请重新同步' };
+    return { refreshed: false, directory, error: directory.lastError };
+  }
+  signal?.throwIfAborted();
+  const models = discovered.map(model => ({ id: typeof model === 'string' ? model : model.id,
+    capabilities: capabilitiesOfDiscoveredModel(model) }));
+  const known = new Set(previous?.models?.map(model => model.id)
+    || provider.models?.map(model => typeof model === 'string' ? model : model.id) || []);
+  const directory = { version: 1, binding, checkedAt: new Date(now).toISOString(), models,
+    added: models.filter(model => !known.has(model.id)).map(model => model.id) };
+  if (await save(directory) === false) return { refreshed: false, error: '连接在目录同步期间发生变化，请重新同步' };
+  return { refreshed: true, directory };
+}

package/lib/model-directory.js

@@ -0,0 +1,103 @@
+import crypto from 'node:crypto';
+import { isKnownCapability } from './capability.js';
+import { providerApiKey, providerMediaBaseUrl, selectMediaProtocol, providerForImageModel, providerForMusicModel } from './provider-protocol.js';
+
+export const MODEL_DIRECTORY_TTL_MS = 10 * 60 * 1000;
+export const MODEL_DIRECTORY_RETRY_MS = 30 * 1000;
+
+/** 配置是外部输入，目录只接受不含连接凭据的固定数据形状。 */
+export function validateModelDirectory(value) {
+  if (value === undefined) return;
+  if (!value || value.version !== 1 || !/^[a-f0-9]{64}$/.test(value.binding)
+      || (value.checkedAt !== undefined && !Number.isFinite(Date.parse(value.checkedAt)))
+      || (value.checkedAt && !Array.isArray(value.models))
+      || (value.models !== undefined && (!Array.isArray(value.models) || value.models.some(model =>
+        !model || typeof model.id !== 'string' || !model.id.trim() || !Array.isArray(model.capabilities)
+        || !model.capabilities.every(isKnownCapability))))
+      || (value.added !== undefined && (!Array.isArray(value.added) || !value.added.every(id => typeof id === 'string')))) {
+    throw new TypeError('模型目录快照结构无效');
+  }
+}
+
+/** 摘要绑定实际连接，不保存或回传密钥。 */
+export function modelDirectoryBinding(provider) {
+  return crypto.createHash('sha256').update(JSON.stringify([
+    provider.id, provider.type || '', provider.baseUrl || '', providerMediaBaseUrl(provider), selectMediaProtocol(provider).mediaProtocol,
+    provider.auth || 'bearer', providerApiKey(provider)
+  ])).digest('hex');
+}
+
+export function currentModelDirectory(provider, { allowUnresolvedConnections = false } = {}) {
+  const directory = provider?.modelDirectory;
+  if (!directory || directory.version !== 1) return null;
+  if (directory.binding === modelDirectoryBinding(provider)) return directory;
+  return allowUnresolvedConnections && provider.dshProvider && !provider.baseUrl ? directory : null;
+}
+
+export function modelAvailabilityBinding(provider, modelId, capability) {
+  if (capability === 'image-gen') return modelDirectoryBinding(providerForImageModel(provider, modelId));
+  if (capability === 'music-gen' && provider.models?.some(model => model?.id === modelId && model.musicProtocol)) {
+    return modelDirectoryBinding(providerForMusicModel(provider, modelId));
+  }
+  return modelDirectoryBinding(provider);
+}
+
+export function modelDirectoryEntry(provider, modelId, options) {
+  return currentModelDirectory(provider, options)?.models?.find(model => model.id === modelId) || null;
+}
+
+export function modelDirectoryStatus(provider, modelId) {
+  const directory = currentModelDirectory(provider, { allowUnresolvedConnections: true });
+  if (!directory?.checkedAt) return 'unknown';
+  return directory.models.some(model => model.id === modelId) ? 'listed' : 'unlisted';
+}
+
+/** 普通请求路径404或参数400不代表模型不存在。兼容已有精确404记录。 */
+export function isModelNotFound(result) {
+  if (result?.stage === 'poll') return false;
+  const status = Number(result?.httpStatus ?? result?.status);
+  if (status !== 404) return false;
+  const code = String(result?.providerCode || result?.code || '');
+  const message = String(result?.note || result?.safeMessage || result?.message || '');
+  return /^(?:NotFound\.Model|model_not_found|ModelNotFound)$/i.test(code)
+    || /\bModel not exist\./i.test(message);
+}
+
+/** 当前可选性与历史成功分开；旧Task成功不能解除新提交已确认的阻断。 */
+export function modelUnavailable(provider, modelId, capability, { allowUnresolvedConnections = false } = {}) {
+  const observation = provider?.health?.observations?.find(item => item.modelId === modelId && item.capability === capability);
+  const availability = observation?.availability;
+  if (availability) {
+    if (availability.binding !== modelAvailabilityBinding(provider, modelId, capability)
+        && !(allowUnresolvedConnections && provider.dshProvider && !provider.baseUrl)) return null;
+    return availability.state === 'blocked' ? availability : null;
+  }
+  const failure = [observation?.lastTransient, observation?.lastFailure].filter(isModelNotFound)
+    .sort((a, b) => String(b.at).localeCompare(String(a.at)))[0];
+  if (!failure) return null;
+  if (observation.lastSuccess?.source === 'probe' && observation.lastSuccess.at >= failure.at) return null;
+  return { ...failure, state: 'blocked' };
+}
+
+export function modelUnavailableReason() {
+  return '当前连接已返回模型不存在，已暂停自动选用；请核对目录后单独实测恢复';
+}
+
+export function modelDirectorySummary(provider) {
+  const directory = currentModelDirectory(provider, { allowUnresolvedConnections: true });
+  if (!directory) return { status: 'unknown', note: '尚未同步当前连接的模型目录' };
+  const models = directory.models || [];
+  const configuredIds = Array.isArray(provider.models)
+    ? provider.models.map(model => typeof model === 'string' ? model : model.id)
+    : [...new Set(['imageModel', 'videoModel', 'ttsModel', 'musicModel', 'transcribeModel', 'visionModel']
+      .map(field => provider[field]).filter(id => typeof id === 'string' && id.trim()).map(id => id.trim()))];
+  const missing = directory.checkedAt ? configuredIds.filter(id => !models.some(model => model.id === id)) : [];
+  const stale = Boolean(directory.lastError) || Date.now() - Date.parse(directory.checkedAt || '') >= MODEL_DIRECTORY_TTL_MS
+    || Date.parse(directory.invalidatedAt || '') >= Date.parse(directory.checkedAt || '');
+  return {
+    status: directory.checkedAt ? stale ? 'stale' : 'current' : 'unknown',
+    checkedAt: directory.checkedAt || null, modelCount: models.length,
+    added: directory.added || [], missing,
+    ...(directory.lastError ? { error: directory.lastError, failedAt: directory.failedAt } : {})
+  };
+}