@mokuyoaxis/dsh-iris 0.2.4 → 0.2.6

package/lib/dsh-provider-source.js

@@ -0,0 +1,102 @@
+/** Read only public DSH services; never open profile or credential files. */
+export class DshProviderSourceError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DshProviderSourceError';
+    this.code = 'IRIS_DSH_PROVIDER_UNAVAILABLE';
+  }
+}
+
+const unavailable = message => { throw new DshProviderSourceError(message); };
+const refName = value => typeof value === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+const recordId = value => typeof value === 'string' && /^[a-z][a-z0-9-]*$/.test(value);
+
+async function credentialRead(read) {
+  try { return await read(); }
+  catch (_) { unavailable('DSH 凭据服务读取失败，请在宿主检查该连接'); }
+}
+
+function endpoint(value) {
+  let url;
+  try { url = new URL(value); } catch (_) { unavailable('DSH 连接没有可复用的 HTTP(S) 地址'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    unavailable('DSH 连接地址包含不支持的协议或凭据参数');
+  }
+  return url.href.replace(/\/+$/, '');
+}
+
+export function createDshProviderSource(services) {
+  function entries() {
+    const { llm, settings, credentials } = services();
+    if (typeof llm?.listProviders !== 'function' || typeof llm?.listConfigurableProviders !== 'function'
+        || typeof settings?.describe !== 'function') {
+      unavailable('当前 DSH 未提供连接目录与设置接口，请手动添加 Iris 供应商');
+    }
+    const active = new Set(llm.listProviders().map(provider => provider.id));
+    const forms = settings.describe({ redactSecrets: true });
+    return llm.listConfigurableProviders().filter(entry => active.has(entry.provider)).map(entry => {
+      let profile = forms.find(form => form.ns === entry.settingsNs)?.value;
+      for (const key of entry.settingsPath) profile = profile && Object.hasOwn(profile, key) ? profile[key] : undefined;
+      return { entry, profile, credentials };
+    });
+  }
+
+  async function facts({ entry, profile, credentials }) {
+    if (!profile || typeof profile !== 'object' || Array.isArray(profile)) unavailable('DSH 连接设置不可读取');
+    if (profile.headers && Object.keys(profile.headers).length) unavailable('该 DSH 连接含自定义请求头，当前请手动配置 Iris 供应商');
+    const baseUrl = endpoint(profile.baseURL || entry.defaultBaseURL);
+    if (!credentials) unavailable('当前 DSH 没有凭据解析服务，请手动配置 Iris 供应商');
+    if (profile.apiKeyEnv !== undefined) {
+      if (!refName(profile.apiKeyEnv) || typeof credentials.describe !== 'function'
+          || typeof credentials.resolve !== 'function') unavailable('DSH 凭据引用不可用');
+      if (!(await credentialRead(() => credentials.describe(profile.apiKeyEnv))).configured) unavailable('DSH 连接尚未配置可用密钥');
+      return { baseUrl, ref: profile.apiKeyEnv };
+    }
+    // This is the documented api-key record space owned by llm-pi-ai.
+    if (entry.settingsNs === 'llm-pi-ai' && recordId(entry.provider)
+        && typeof credentials.describeRecord === 'function' && typeof credentials.readRecord === 'function') {
+      const key = 'llm-pi-ai/' + entry.provider;
+      const info = await credentialRead(() => credentials.describeRecord(key));
+      if (info.configured) {
+        if (info.kind !== 'api-key') unavailable('该 DSH 连接使用登录授权，当前不支持将其用于媒体请求');
+        return { baseUrl, recordKey: key };
+      }
+    }
+    for (const ref of entry.nativeAuth?.env || []) {
+      if (refName(ref) && typeof credentials.describe === 'function' && typeof credentials.resolve === 'function'
+          && (await credentialRead(() => credentials.describe(ref))).configured) return { baseUrl, ref };
+    }
+    unavailable('该 DSH 连接没有可复用的 API Key；登录授权和专有认证需单独适配');
+  }
+
+  async function list() {
+    return Promise.all(entries().map(async source => {
+      const { entry } = source;
+      const common = { provider: entry.provider, settingsNs: entry.settingsNs, name: entry.displayName || entry.provider };
+      try { return { ...common, baseUrl: (await facts(source)).baseUrl, available: true }; }
+      catch (error) {
+        if (!(error instanceof DshProviderSourceError)) throw error;
+        return { ...common, available: false, reason: error.message };
+      }
+    }));
+  }
+
+  async function resolve(reference, { signal } = {}) {
+    signal?.throwIfAborted();
+    const source = entries().find(({ entry }) => entry.provider === reference.provider && entry.settingsNs === reference.settingsNs);
+    if (!source) unavailable('DSH 原连接已停用、移除或改变来源，请检查宿主供应商设置');
+    const plan = await facts(source);
+    let key;
+    if (plan.ref) key = (await credentialRead(() => source.credentials.resolve(plan.ref)))?.value;
+    else {
+      const record = await credentialRead(() => source.credentials.readRecord(plan.recordKey));
+      if (record?.kind === 'api-key') key = record.key;
+    }
+    signal?.throwIfAborted();
+    if (typeof key !== 'string' || !key.trim() || /[\r\n]/.test(key)) unavailable('DSH 原连接没有可用于媒体请求的 API Key');
+    // Even accidental JSON serialization of this Host-only result excludes the key.
+    return Object.freeze(Object.defineProperty({ baseUrl: plan.baseUrl }, 'apiKey', { value: key }));
+  }
+
+  return Object.freeze({ list, resolve });
+}

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 };
+}