@mokuyoaxis/dsh-iris 0.2.4 → 0.2.6

package/lib/provider-config-service.js

@@ -3,14 +3,16 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { loadProviderCatalog, providerCatalogSnapshot, catalogCapabilitySnapshot } from './provider-catalog.js';
 import { isKnownCapability } from './capability.js';
-import { providerModels, modelPool, parseModelRef, HOST_VISION_REF, capabilitiesOfDiscoveredModel, hasConfiguredModelCapabilities, resolvePoolModel } from './models.js';
+import { providerModels, modelPool, functionPolicy, savedAssignmentRefs, parseModelRef, HOST_VISION_REF, capabilitiesOfDiscoveredModel, hasConfiguredModelCapabilities, resolvePoolModel } from './models.js';
 import { atomicWritePrivate, privateSibling, ensurePrivateDir } from './private-storage.js';
 import { createConfiguredProviderAdapter } from './provider-adapters.js';
-import { selectImageProtocol, normalizeImageProtocol, normalizeMusicProtocol } from './provider-protocol.js';
+import { selectImageProtocol, normalizeImageProtocol, normalizeMusicProtocol, isConfiguredProvider } from './provider-protocol.js';
 import { invokeProviderOperation } from './provider-adapter.js';
 import { redactProviderMessage } from './provider-contract.js';
-import { modelRateLimit, recordModelRateLimit, clearModelRateLimit, clearModelCapabilityHealth, isDefinitiveHealthFailure } from './provider-health.js';
+import { modelRateLimit, recordModelRateLimit, clearModelRateLimit, clearModelCapabilityHealth, isDefinitiveHealthFailure, recordModelAvailability, resetHealthOnCriticalChange } from './provider-health.js';
 import { normalizeVisionInputLimits, visionInputLimits } from './vision-image-input.js';
+import { currentModelDirectory, modelDirectoryBinding, modelAvailabilityBinding } from './model-directory.js';
+import { refreshModelDirectory } from './model-directory-service.js';
 
 const fail = message => { throw Object.assign(new Error(message), { code: 'IRIS_CONFIG_INPUT_INVALID' }); };
 const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
@@ -24,14 +26,18 @@ const caps = value => {
 function assignmentSnapshot(catalog) {
   const pool = modelPool(catalog.providers, { includeHostVision: true });
   return Object.fromEntries(Object.entries(catalog.assignments || {}).map(([capability, value]) => {
-    const refs = (Array.isArray(value) ? value : [value]).map(ref => resolvePoolModel(pool, ref, capability));
-    return [safe(capability), { model_refs: refs.filter(Boolean).map(model => safe(model.ref)), invalidRefs: refs.filter(ref => !ref).length }];
+    const policy = functionPolicy(value, capability);
+    const refs = policy.models.map(ref => resolvePoolModel(pool, ref, capability));
+    return [safe(capability), { mode: policy.mode, hostVision: policy.hostVision,
+      model_refs: refs.filter(Boolean).map(model => safe(model.ref)), invalidRefs: refs.filter(ref => !ref).length }];
   }));
 }
 
 export function configSnapshot(catalog) {
   return { ...providerCatalogSnapshot(catalog), models: catalog.providers.flatMap(provider => providerModels(provider).map(model => ({
     ref: safe(model.ref), providerId: safe(provider.id), id: safe(model.id), capabilities: model.capabilities,
+    ...(model.catalogStatus ? { catalogStatus: model.catalogStatus } : {}),
+    ...(model.unavailableCapabilities ? { unavailableCapabilities: model.unavailableCapabilities } : {}),
     ...(model.imageProtocol !== undefined ? { imageProtocol: model.imageProtocol } : {}),
     ...(model.musicProtocol !== undefined ? { musicProtocol: model.musicProtocol } : {}),
     ...(model.visionInput !== undefined ? { visionInput: model.visionInput } : {}),
@@ -73,7 +79,8 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     }
     for (const [capability, assignment] of Object.entries(catalog.assignments || {})) {
       if (!isKnownCapability(capability)) issues.push('unknown_assignment_capability');
-      for (const ref of (Array.isArray(assignment) ? assignment : [assignment])) if (!resolvePoolModel(pool, ref, capability)) issues.push('unavailable_assignment_model');
+      const policy = functionPolicy(assignment, capability);
+      if (policy.mode === 'manual') for (const ref of policy.models) if (!resolvePoolModel(pool, ref, capability)) issues.push('unavailable_assignment_model');
     }
     return { valid: issues.length === 0, issues: [...new Set(issues)] };
   }
@@ -116,6 +123,7 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
           clearModelCapabilityHealth(updated, model.id, 'image-gen');
         }
       }
+      resetHealthOnCriticalChange(provider, updated, value);
     }
     if (provider) catalog.providers[catalog.providers.indexOf(provider)] = updated;
     else catalog.providers.push(updated);
@@ -134,6 +142,9 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
       const models = discovered.models.map(model => ({ id: text(typeof model === 'string' ? model : model.id), capabilities: capabilitiesOfDiscoveredModel(model), source: 'discovered' }));
       result = { command, changed: input.apply === true, total: models.length, mediaCount: models.filter(model => model.capabilities.length).length, models: models.map(model => ({ ...model, id: safe(model.id) })) };
       if (input.apply !== true) return result;
+      provider.modelDirectory = { version: 1, binding: modelDirectoryBinding(provider), checkedAt: new Date().toISOString(),
+        models: models.map(({ id, capabilities }) => ({ id, capabilities })),
+        added: models.filter(model => !entries.some(entry => entry.id === model.id)).map(model => model.id) };
       for (const model of models) {
         const old = entries.find(value => value.id === model.id);
         if (!old) entries.push(model);
@@ -181,12 +192,14 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
       const tested = await probe({ provider, modelId, capability: input.capability, signal });
       if (tested.skipped) return { command, changed: false, ...tested };
       const evidence = { at: new Date().toISOString(), source: 'probe', category: tested.category || (tested.ok ? 'success' : 'unknown'),
+        ...(tested.providerCode ? { providerCode: safe(tested.providerCode) } : {}),
         ...(tested.httpStatus || tested.status ? { httpStatus: tested.httpStatus || tested.status } : {}) };
       entry.verified = { ...(entry.verified || {}), [input.capability]: { ok: tested.ok === true, ...evidence } };
       provider.health ||= { version: 1, revision: 0, observations: [] };
       const observations = provider.health.observations;
       let observation = observations.find(value => value.modelId === modelId && value.capability === input.capability);
       if (!observation) { observation = { modelId, capability: input.capability }; observations.push(observation); }
+      recordModelAvailability(provider, modelId, input.capability, { ...tested, ...evidence });
       if (tested.ok === true) { observation.lastSuccess = evidence; clearModelRateLimit(provider, modelId); }
       else {
         observation[isDefinitiveHealthFailure(evidence) ? 'lastFailure' : 'lastTransient'] = evidence;
@@ -195,11 +208,34 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
       result = { command, changed: true, passed: tested.ok === true, ...(tested.taskId ? { taskId: tested.taskId } : {}), ...(tested.code ? { code: tested.code } : {}) };
     } else fail('未知模型命令');
     provider.models = entries;
+    if (['models.add', 'models.caps'].includes(command) && input.enableAutomatic !== undefined) {
+      if (typeof input.enableAutomatic !== 'boolean') fail('enableAutomatic 必须是布尔值');
+      if (input.enableAutomatic) for (const capability of caps(input.capabilities)) {
+        catalog.assignments ||= {};
+        const previous = functionPolicy(catalog.assignments[capability], capability);
+        catalog.assignments[capability] = { mode: 'auto', models: savedAssignmentRefs(modelPool(catalog.providers, { includeHostVision: true }), capability, previous.models),
+          ...(capability === 'vision' ? { hostVision: previous.hostVision } : {}) };
+      }
+    }
   } else if (command === 'assignments.set' || command === 'assignments.clear') {
     if (!isKnownCapability(input.capability)) fail('未知能力');
     catalog.assignments ||= {};
     if (command === 'assignments.clear') delete catalog.assignments[input.capability];
-    else {
+    else if (input.mode !== undefined) {
+      const previous = functionPolicy(catalog.assignments[input.capability], input.capability);
+      const next = { mode: input.mode, models: savedAssignmentRefs(modelPool(catalog.providers, { includeHostVision: true }), input.capability, previous.models),
+        ...(input.capability === 'vision' ? { hostVision: input.hostVision ?? previous.hostVision } : {}) };
+      functionPolicy(next, input.capability);
+      if (input.hostVision && input.capability !== 'vision') fail('hostVision 仅用于视觉');
+      if (input.model_refs !== undefined) {
+        if (!Array.isArray(input.model_refs) || new Set(input.model_refs).size !== input.model_refs.length) fail('model_refs 必须是不重复的引用数组');
+        const pool = modelPool(catalog.providers, { includeHostVision: true });
+        for (const ref of input.model_refs) if ((typeof ref !== 'string' || (!parseModelRef(ref) && ref !== HOST_VISION_REF))
+            || !resolvePoolModel(pool, ref, input.capability)) fail('分配模型不存在或没有该能力');
+        next.models = input.model_refs;
+      }
+      catalog.assignments[input.capability] = next;
+    } else {
       if (!Array.isArray(input.model_refs) || new Set(input.model_refs).size !== input.model_refs.length) fail('model_refs 必须是不重复的复合引用数组');
       const pool = modelPool(catalog.providers, { includeHostVision: true });
       for (const ref of input.model_refs) if ((!parseModelRef(ref) && ref !== HOST_VISION_REF) || !resolvePoolModel(pool, ref, input.capability)) fail('分配模型不存在或没有该能力');
@@ -211,8 +247,9 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
   if (command === 'providers.remove' || command === 'models.remove' || command === 'models.caps') {
     const pool = modelPool(catalog.providers);
     for (const [capability, assignment] of Object.entries(catalog.assignments || {})) {
-      const values = (Array.isArray(assignment) ? assignment : [assignment]).filter(ref => resolvePoolModel(pool, ref, capability) || !resolvePoolModel(initialPool, ref, capability));
-      if (!values.length) delete catalog.assignments[capability];
+      const values = functionPolicy(assignment, capability).models.filter(ref => resolvePoolModel(pool, ref, capability) || !resolvePoolModel(initialPool, ref, capability));
+      if (assignment && typeof assignment === 'object' && !Array.isArray(assignment) && Object.hasOwn(assignment, 'mode')) catalog.assignments[capability] = { ...assignment, models: values };
+      else if (!values.length) delete catalog.assignments[capability];
       else catalog.assignments[capability] = Array.isArray(assignment) ? values : values[0];
     }
   }
@@ -230,7 +267,37 @@ export function recordCatalogRateLimit(configPath, event) {
   return writeConfigChange(configPath, catalog, before, { changed: true });
 }
 
-function writeConfigChange(configPath, catalog, before, result) {
+/** CLI真实提交的可用性证据，复用同一配置锁；不为可重建元数据新增备份。 */
+export function recordCatalogAvailability(configPath, { providerId, modelId, capability, ...event }) {
+  const catalog = loadProviderCatalog(configPath);
+  const before = fs.readFileSync(configPath);
+  const provider = catalog.providers.find(item => item.id === providerId);
+  const cap = { image: 'image-gen', video: 'video-gen', music: 'music-gen' }[capability] || capability;
+  if (!provider || (event.binding && modelAvailabilityBinding(provider, modelId, cap) !== event.binding)
+      || !recordModelAvailability(provider, modelId, capability, event)) return;
+  const directory = currentModelDirectory(provider);
+  if (directory && event.ok !== true) directory.invalidatedAt = event.at || new Date().toISOString();
+  return writeConfigChange(configPath, catalog, before, { changed: true }, { backup: false });
+}
+
+/** 新的自动请求按需读取目录；只读CLI命令与手选/停用不走这里。 */
+export async function refreshCatalogDirectories(configPath, catalog, capability, { signal } = {}) {
+  if (functionPolicy(catalog.assignments?.[capability], capability).mode !== 'auto') return [];
+  return Promise.all(catalog.providers.filter(provider => isConfiguredProvider(provider)
+    && providerModels(provider).some(model => model.capabilities.includes(capability))).map(provider =>
+    refreshModelDirectory(provider, { signal, save: directory => {
+      const fresh = loadProviderCatalog(configPath);
+      const before = fs.readFileSync(configPath);
+      const current = fresh.providers.find(item => item.id === provider.id);
+      if (!current || modelDirectoryBinding(current) !== directory.binding) return false;
+      current.modelDirectory = directory;
+      writeConfigChange(configPath, fresh, before, { changed: true }, { backup: false });
+      provider.modelDirectory = directory;
+      return true;
+    } })));
+}
+
+function writeConfigChange(configPath, catalog, before, result, { backup = true } = {}) {
   const lock = configPath + '.lock';
   let fd;
   try { fd = fs.openSync(lock, 'wx', 0o600); }
@@ -238,10 +305,12 @@ function writeConfigChange(configPath, catalog, before, result) {
   try {
     loadProviderCatalog(configPath);
     if (hash(fs.readFileSync(configPath)) !== hash(before)) throw Object.assign(new Error('配置在操作期间发生变化，请重新读取后重试'), { code: 'IRIS_CONFIG_CHANGED' });
-    const backupPath = privateSibling(configPath, 'backup');
-    fs.writeFileSync(backupPath, before, { flag: 'wx', mode: 0o600 });
+    if (backup) {
+      const backupPath = privateSibling(configPath, 'backup');
+      fs.writeFileSync(backupPath, before, { flag: 'wx', mode: 0o600 });
+      result.backupPath = backupPath;
+    }
     atomicWritePrivate(configPath, JSON.stringify(catalog, null, 2) + '\n');
-    result.backupPath = backupPath;
     return result;
   } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
 }

package/lib/provider-health.js

@@ -1,4 +1,37 @@
 'use strict';
+import { isKnownCapability } from './capability.js';
+import { isModelNotFound, modelAvailabilityBinding, modelUnavailable } from './model-directory.js';
+
+const HEALTH_SENSITIVE_FIELDS = new Set([
+  'auth', 'type', 'baseUrl', 'mediaBaseUrl', 'apiKey', 'mediaProtocol',
+  'imageModel', 'videoModel', 'ttsModel', 'transcribeModel', 'visionModel'
+]);
+
+/** 明确修改连接后旧健康证据失效；额度停用仍需显式实测解除。 */
+export function resetHealthOnCriticalChange(previous, next, patch) {
+  if (![...HEALTH_SENSITIVE_FIELDS].some(key => Object.hasOwn(patch, key) && previous[key] !== next[key])) return;
+  const current = previous.health;
+  next.health = { version: 1, revision: (Number.isSafeInteger(current?.revision) ? current.revision : 0) + 1,
+    observations: [], ...(current?.rateLimits?.length ? { rateLimits: current.rateLimits } : {}) };
+}
+
+/** 仅提交或显式实测更新模型可选性，远端旧任务的观察不解除阻断。 */
+export function recordModelAvailability(provider, modelId, capability, result) {
+  const cap = { image: 'image-gen', video: 'video-gen', music: 'music-gen' }[capability] || capability;
+  if (!modelId || !isKnownCapability(cap)) return false;
+  let observation = provider.health?.observations?.find(item => item.modelId === modelId && item.capability === cap);
+  const blocked = isModelNotFound(result);
+  if (!blocked && !(result.ok === true && (result.source === 'probe' || result.stage === 'submit')
+      && (observation?.availability?.state === 'blocked' || modelUnavailable(provider, modelId, cap)))) return false;
+  provider.health ||= { version: 1, revision: 0, observations: [] };
+  provider.health.observations ||= [];
+  observation ||= provider.health.observations.find(item => item.modelId === modelId && item.capability === cap);
+  if (!observation) { observation = { modelId, capability: cap }; provider.health.observations.push(observation); }
+  observation.availability = { state: blocked ? 'blocked' : 'available', at: result.at || new Date().toISOString(),
+    binding: result.binding || modelAvailabilityBinding(provider, modelId, cap), source: result.source === 'probe' ? 'probe' : 'task',
+    ...(blocked ? { httpStatus: 404, reason: 'model_not_found' } : {}) };
+  return true;
+}
 
 export const PROVIDER_HEALTH_SCHEMA_VERSION = 1;
 export const PROVIDER_HEALTH_FRESH_MS = 7 * 24 * 60 * 60 * 1000;

package/lib/provider-protocol.js

@@ -114,6 +114,36 @@ export function isConfiguredProvider(provider) {
     && (provider.auth === 'none' || (typeof provider.apiKey === 'string' && provider.apiKey.trim())));
 }
 
+/** 已知需要其他接口的语音系列；自定义模型仍以明确配置和实测为准。 */
+export function dashscopeTtsProtocolIssue(modelId) {
+  const model = String(modelId || '');
+  if (/^qwen(?:\d+(?:\.\d+)?)?-(?:tts|omni|audio)-.*realtime(?:-|$)/i.test(model)) {
+    return '该实时语音模型需要 WebSocket，Iris 尚未接入该调用方式';
+  }
+  if (/^(?:qwen-audio-|cosyvoice(?:-|$)|sambert-|MiniMax\/speech-)/i.test(model)) {
+    return 'Iris 尚未接入该语音系列的合成接口；当前使用 Qwen-TTS 普通 HTTP 接口';
+  }
+  return '';
+}
+
+/** 复刻/设计模型不能沿用普通模型的默认音色。 */
+export function dashscopeTtsInputIssue(modelId, voice) {
+  return dashscopeTtsProtocolIssue(modelId)
+    || (/^qwen(?:\d+)?-tts-(?:vc|vd)(?:-|$)/i.test(String(modelId || '')) && !String(voice || '').trim()
+      ? '该模型需要先创建复刻或设计音色；请在语音功能填写与该模型匹配的音色 ID 后验证'
+      : '');
+}
+
+/** Protocol support is independent from model capability declarations and health. */
+export function supportsModelCapability(provider, modelId, capability, { checkEndpoint = true } = {}) {
+  if (capability === 'vision') return true;
+  if (capability === 'music-gen') return provider?.models?.some(model => model?.id === modelId && model.musicProtocol === 'gemini-web-music') === true;
+  const protocol = capability === 'image-gen' ? selectImageProtocol(provider, modelId).mediaProtocol : selectMediaProtocol(provider).mediaProtocol;
+  if (protocol === 'dashscope') return (capability !== 'tts' || !dashscopeTtsProtocolIssue(modelId))
+    && (!checkEndpoint || isDashScopeBaseUrl(providerMediaBaseUrl(provider)));
+  return capability === 'image-gen' && ['openai-images', 'openai-chat-images', 'openai-responses-images'].includes(protocol);
+}
+
 /**
  * 生图尺寸的协议差异集中在这里，调用点不再自带厂商假设。
  *

package/lib/vision-model-routing.js

@@ -7,7 +7,8 @@ import { prepareDshVisionModelPort } from './dsh-vision-model-adapter.js';
 import { createModelOperation } from './model-invoker.js';
 import { ModelPortError, normalizeModelDescriptor, normalizeModelCall, modelErrorRecord } from './model-port-contract.js';
 import { waitForModelWork } from './model-call-runtime.js';
-import { modelRateLimit, reportModelRateLimit } from './provider-health.js';
+import { modelRateLimit, reportModelRateLimit, recordModelAvailability } from './provider-health.js';
+import { modelAvailabilityBinding, modelUnavailable } from './model-directory.js';
 import { completeVision, VISION_BUDGET } from './vision-core.js';
 import { open } from 'node:fs/promises';
 import { DEFAULT_VISION_INPUT, visionInputLimits } from './vision-image-input.js';
@@ -47,7 +48,7 @@ function deferredDshPort(host, { prepareImages, orientImages, prepareImageReques
 }
 
 /** 配置只绑定一个自持模型；CLI 不附加宿主候选。 */
-export function createConfiguredVisionModelPort(provider, model, { allowRateLimited = false, onRateLimit, prepareImages = false,
+export function createConfiguredVisionModelPort(provider, model, { allowRateLimited = false, onRateLimit, onModelAvailability, prepareImages = false,
   orientImages = false, prepareImageRequest } = {}) {
   const parsed = parseModelRef(resolveModelRef(provider, 'vision', model));
   const id = 'iris-provider:' + encodeURIComponent(provider.id);
@@ -59,13 +60,25 @@ export function createConfiguredVisionModelPort(provider, model, { allowRateLimi
     baseUrl: provider.baseUrl, apiKey: providerApiKey(provider),
     orientImages, prepareImageRequest,
     ...(prepareImages ? { imageInput: visionInputLimits(provider, parsed.modelId) } : {}) });
+  const availability = result => {
+    const event = { ...result, stage: 'submit', source: allowRateLimited ? 'probe' : 'task',
+      binding: modelAvailabilityBinding(provider, parsed.modelId, 'vision') };
+    if (!recordModelAvailability(provider, parsed.modelId, 'vision', event)) return;
+    try { onModelAvailability?.({ providerId: provider.id, modelId: parsed.modelId, capability: 'vision', ...event }); }
+    catch (_) { console.warn('[iris] 模型可用性未能持久化，请检查配置写入权限'); }
+  };
   return Object.freeze({ describe: port.describe,
     async complete(request, options) {
-      if (!allowRateLimited && modelRateLimit(provider, parsed.modelId)) {
+      if (!allowRateLimited && (modelRateLimit(provider, parsed.modelId) || modelUnavailable(provider, parsed.modelId, 'vision'))) {
         throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare', invocation: 'not_invoked' });
       }
-      try { return await port.complete(request, options); }
+      try {
+        const result = await port.complete(request, options);
+        availability({ ok: true });
+        return result;
+      }
       catch (error) {
+        availability({ ok: false, httpStatus: error.status, providerCode: error.providerCode });
         reportModelRateLimit(provider, parsed.modelId, { status: error.status, code: error.code,
           providerCode: error.providerCode, retryAfterMs: error.retryAfterMs,
           ...(error.quotaExhausted ? { reason: 'free_quota' } : {}),
@@ -76,7 +89,7 @@ export function createConfiguredVisionModelPort(provider, model, { allowRateLimi
   });
 }
 
-export function buildVisionModelCandidates(host, { providers = [], model, allowRateLimited = false, onRateLimit, prepareImages = false,
+export function buildVisionModelCandidates(host, { providers = [], model, allowRateLimited = false, onRateLimit, onModelAvailability, prepareImages = false,
   orientImages = false, prepareImageRequest } = {}) {
   const candidates = [], seen = new Set();
   let selected = providers.filter(Boolean);
@@ -100,7 +113,7 @@ export function buildVisionModelCandidates(host, { providers = [], model, allowR
     // 显式模型会把同账号的多份池记录解析为同一复合引用，只保留首次候选。
     if (parsed && seen.has(ref)) continue;
     if (parsed) seen.add(ref);
-    const port = createConfiguredVisionModelPort(provider, provider.visionModel, { allowRateLimited, onRateLimit, prepareImages, orientImages, prepareImageRequest });
+    const port = createConfiguredVisionModelPort(provider, provider.visionModel, { allowRateLimited, onRateLimit, onModelAvailability, prepareImages, orientImages, prepareImageRequest });
     const id = port.describe().identity.backendId;
     candidates.push({ port, id, via: 'selfstack', backendId: provider.id, model: parsed?.modelId || '' });
   }
@@ -148,10 +161,10 @@ function projectError(record, candidates) {
 }
 
 /** prepareImage 的信号覆盖文件/会话读取；函数开始时即建立整体预算。 */
-export async function runVisionOperation(host, { providers, model, signal, budget = VISION_BUDGET, onRateLimit, prepareImages = false,
+export async function runVisionOperation(host, { providers, model, signal, budget = VISION_BUDGET, onRateLimit, onModelAvailability, prepareImages = false,
   orientImages = false, prepareImageRequest }, consume) {
   if (signal?.aborted) throw new ModelPortError('IRIS_MODEL_ABORTED');
-  const candidates = buildVisionModelCandidates(host, { providers, model, onRateLimit, prepareImages, orientImages, prepareImageRequest });
+  const candidates = buildVisionModelCandidates(host, { providers, model, onRateLimit, onModelAvailability, prepareImages, orientImages, prepareImageRequest });
   const operation = createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: candidates.length } });
   try {
     const { completion: result, ...details } = await consume(candidates.map(candidate => candidate.port), operation);
@@ -168,8 +181,8 @@ export async function runVisionOperation(host, { providers, model, signal, budge
 }
 
 /** 单图与复合业务共用同一候选、整体预算和结果投影。 */
-export async function runVisionRequest(host, { providers, model, question, image, dataUrl, prepareImage, signal, budget = VISION_BUDGET, onRateLimit }) {
-  return runVisionOperation(host, { providers, model, signal, budget, onRateLimit, prepareImages: true }, async (ports, operation) => {
+export async function runVisionRequest(host, { providers, model, question, image, dataUrl, prepareImage, signal, budget = VISION_BUDGET, onRateLimit, onModelAvailability }) {
+  return runVisionOperation(host, { providers, model, signal, budget, onRateLimit, onModelAvailability, prepareImages: true }, async (ports, operation) => {
     normalizeModelCall(ports[0].describe(), { prompt: question,
       image: { bytes: new Uint8Array([0]), mediaType: 'image/png' } }, { budget });
     const resolved = await waitForModelWork(() => prepareImage ? prepareImage(operation.signal)
@@ -179,9 +192,9 @@ export async function runVisionRequest(host, { providers, model, question, image
 }
 
 /** 付费确认在动作入口；红图实测只有一个供应商，不退到 Host 冒充其能力。 */
-export async function probeVisionModel(provider, model, image, { signal, timeoutMs = 15000 } = {}) {
+export async function probeVisionModel(provider, model, image, { signal, timeoutMs = 15000, onModelAvailability } = {}) {
   try {
-    const port = createConfiguredVisionModelPort(provider, model, { allowRateLimited: true });
+    const port = createConfiguredVisionModelPort(provider, model, { allowRateLimited: true, onModelAvailability });
     const result = await completeVision([port], { prompt: '这张图片是什么颜色？请只回答颜色名称（中文）。', image },
       { signal, budget: { ...VISION_BUDGET, timeoutMs } });
     return { ok: /红|red/i.test(result.text), answer: result.text };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mokuyoaxis/dsh-iris",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Multi-provider image, video, music, and speech generation, transcription, visual understanding, and prompt optimization with an integrated Iris workbench for DeepSeek Harness.",
   "type": "module",
   "main": "lib/index.js",
@@ -34,7 +34,7 @@
   ],
   "dsh": {
     "engines": {
-      "dsh": "0.2.0-rc.2 || 0.2.1-alpha.4"
+      "dsh": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4"
     },
     "bundle": {
       "patch": "./cordis.patch.yml"
@@ -66,7 +66,7 @@
   "license": "MIT",
   "engines": {
     "node": ">=22.0.0",
-    "dsh": "0.2.0-rc.2 || 0.2.1-alpha.4"
+    "dsh": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4"
   },
   "scripts": {
     "test": "node scripts/test.mjs",
@@ -74,11 +74,11 @@
     "prepublishOnly": "npm test"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.2 || 0.2.1-alpha.4",
-    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.2 || 0.2.1-alpha.4",
-    "@deepseek-ai/dsh-client-ui-renderer": "0.2.0-rc.2 || 0.2.1-alpha.4",
-    "@deepseek-ai/dsh-client-ui-session": "0.2.0-rc.2 || 0.2.1-alpha.4",
-    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.2 || 0.2.1-alpha.4"
+    "@deepseek-ai/dsh-client-locale": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4",
+    "@deepseek-ai/dsh-client-ui-renderer": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4",
+    "@deepseek-ai/dsh-client-ui-session": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.2-rc.1 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.5-rc.3 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-client-locale": {
@@ -98,7 +98,7 @@
     }
   },
   "dependencies": {
-    "sharp": "^0.35.4"
+    "sharp": "^0.35.5"
   },
   "publishConfig": {
     "access": "public"

package/user_guide.md

@@ -1,40 +1,37 @@
 # dsh-iris 用户指南
 
-本指南对应Iris 0.2.4。发布状态见 [README](README.md)，升级范围见 [CHANGELOG](CHANGELOG.md) 和 [发布说明](docs/releases/0.2.4.md)。
+本指南对应 Iris 0.2.6。安装要求见 [README](README.md)，升级范围见 [CHANGELOG](CHANGELOG.md) 和 [发布说明](docs/releases/0.2.6.md)。
 
-功能来自明确标签、旧能力字段绑定或供应商能力元数据，账号和名称不会自动赋能。0.2.4还要求把模型明确加入对应功能名单；空名单停止新调用。已有配置保留，详见 [升级说明](docs/FUNCTION_MODEL_ASSIGNMENTS.md)。
+功能来自明确标签、旧能力字段绑定或供应商能力元数据，账号和名称不会自动赋能。0.2.4/0.2.5 要求明确功能名单；0.2.6 保留旧名单和空配置行为，也可主动启用自动池。详见 [升级说明](docs/FUNCTION_MODEL_ASSIGNMENTS.md)。
+
+可 [引用 DSH 连接](docs/DSH_PROVIDER_CONNECTIONS.md)，并在确认模型用途时启用 [功能自动池](docs/FUNCTION_MODEL_POOLS.md)，无需二次分配；已有名单与空配置不会自动改变。
+
+供应商详情提供默认折叠的“模型目录”，可同步目录并查看新增、未列出及失败保留状态；自动请求按需刷新并缓存 10 分钟。当前连接明确返回模型不存在的条目会被隔离，新发现项仍须确认用途。目录同步不发起模型实测或生成。
 
 ## 安装
 
-先运行 `dsh --version`。Iris 0.2.4支持DSH `0.2.0-rc.2` 或 `0.2.1-alpha.4`；Iris0.2.0–0.2.3仅支持rc.2。旧DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 固定使用Iris0.1.4，见 [兼容矩阵](docs/DSH_COMPATIBILITY.md)。还需要PATH中的pnpm及至少一个所需功能的供应商。Iris最低Node.js为22.0.0，宿主要求更高时以宿主为准；旧npm0.1.4的历史要求为20.10.0。
+先运行`dsh --version`。Iris 0.2.6 沿用 0.2.5 的 12 个准确 DSH 版本，详见 [兼容矩阵](docs/DSH_COMPATIBILITY.md)。还需要 PATH 中的 pnpm 及至少一个所需功能的供应商。当前 Iris 最低 Node.js 为 22.0.0，即使保留旧 DSH 也需满足；宿主要求更高时以宿主为准。
 
-在上述旧 DSH 范围内，从 npm 安装固定稳定版到 Web profile：
+在矩阵所列宿主中，将固定版本加入Web profile：
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.6
 dsh web
 ```
 
 npm 上无 scope 的 `dsh-iris` 是另一款插件；安装或更新 Iris Media 时必须使用完整 scoped 包名。
 
-只下载旧稳定包可运行 `npm pack @mokuyoaxis/dsh-iris@0.1.4`，安装为普通npm依赖可运行 `npm install @mokuyoaxis/dsh-iris@0.1.4`；后者不会自动加入DSH profile。0.1.4不包含新的Core媒体CLI。
-
-在DSH rc.2或alpha.4上，固定安装0.2.4：
-
-```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.4
-dsh web
-```
+只下载包可运行`npm pack @mokuyoaxis/dsh-iris@0.2.6`；普通`npm install`不会自动加入DSH profile。仍需保留历史Iris0.1.4时可以固定其版本，历史DSH/Node要求见兼容矩阵；0.1.4不包含当前Core媒体CLI与后续新功能。
 
 浏览器默认打开 `http://127.0.0.1:3080`。插件安装后只会在下一次 DSH 启动时装载；如果 DSH 已经运行，请先停止再启动。启动输出包含一次性认证参数时，必须完整打开该 URL，不能只输入裸地址。
 
 ### 独立 CLI
 
-无需DSH，在自己的项目安装 `npm install @mokuyoaxis/dsh-iris@0.2.4`，通过 `npx dsh-iris --help` 查看入口。发布状态见README，完整说明见 [Headless CLI](docs/HEADLESS_CLI.md) 和 [视觉CLI](docs/VISION_CLI.md)。
+无需DSH，在自己的项目安装 `npm install @mokuyoaxis/dsh-iris@0.2.6`，通过 `npx dsh-iris --help` 查看入口。发布状态见README，完整说明见 [Headless CLI](docs/HEADLESS_CLI.md) 和 [视觉CLI](docs/VISION_CLI.md)。
 
-其他 DSH 版本，包括 `0.2.0` 正式版与其他 rc，须另行验收。让 Agent 协助安装时，可使用[简要 Prompt](docs/AGENT_QUICKSTART.md)。
+未列入对应Iris版本兼容矩阵的DSH版本须另行验收。让Agent协助安装时，可使用 [简要Prompt](docs/AGENT_QUICKSTART.md)。
 
-通过 dsh-market 安装时也要核对显示的 Iris 版本、完整 scoped 包名和 DSH 支持范围。市场可能缓存 npm 信息；旧宿主仍按固定 `@0.1.4` 命令安装，不直接跟随 latest。
+通过dsh-market安装时也要核对显示的Iris版本、完整scoped包名和对应发行版的DSH支持范围。市场可能缓存npm信息；0.2.4及更早发行版仍按各自历史范围安装。
 
 可以在启动前检查组合配置：
 
@@ -58,10 +55,12 @@ dsh --profile web --dump-config
 2. 名称可填“阿里云百炼”。
 3. Base URL 填 `https://dashscope.aliyuncs.com/compatible-mode/v1`；如果账号使用百炼业务空间专属域名，再把“媒体 Base URL”填为同地域的 `https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1`（地域按账号实际情况替换）。
 4. 填入与模型、Endpoint 同地域的 DashScope API Key，点击“保存”。
-5. 展开刚添加的供应商，点击“发现模型”。
-6. 若模型显示“未标注功能”，点击其“设置功能”，勾选已确认支持的功能并保存。
+5. 展开供应商的“模型目录”，点击“同步目录”；也可手动填写已核对的模型 ID。
+6. 点击“设置功能”，勾选已确认支持的用途。首次配置可同时勾选“同时启用所选功能的自动池”，点击“保存模型用途”。
+
+DSH 已配好同一媒体服务时，可在第 1 步选择连接来源，明确协议后直接复用地址与密钥，无需重复填写。连接支持范围见 [连接复用](docs/DSH_PROVIDER_CONNECTIONS.md)。
 
-0.2.4中，单个供应商也需要在“功能分配（调用顺序）”为所需功能选择模型；未分配时不调用模型池。0.2.3仅Music采用严格名单，升级影响见 [功能模型分配](docs/FUNCTION_MODEL_ASSIGNMENTS.md)。
+选择自动池后，确认过用途的合格模型按登记顺序参与调用；保留“仅用所选模型”时，还需在“功能池与调用方式”选择模型。旧空名单不会自动变成自动池，升级差异见 [功能模型池](docs/FUNCTION_MODEL_POOLS.md)。
 
 保存供应商和修改能力分配都会立即生效，不需要重启 DSH。
 
@@ -103,7 +102,7 @@ Iris 当前支持两类调用路径：
 
 未提供标签的模型仍可在后续发现中接收供应商能力元数据；显式保存空标签表示当前不加入任何功能池，发现不会覆盖该选择。
 
-Iris 先按画图、视频、语音、转写和视觉功能组织候选池，再按该功能的能力分配顺序选模型；每次从首项开始，生成只有明确未受理才切换。标注功能不会发起实测、生成或改变分配顺序。
+Iris 按六类功能的当前策略组织候选池：自动模式使用已确认用途的合格模型，手选模式按所选顺序，停用模式不发起新调用。每次从首项开始，媒体生成只有明确未受理才安全切换。确认用途不发起实测或生成；勾选同时启用自动池会明确改变所选功能策略。
 
 点击模型旁单项能力标记会进行验证。视觉、图片和 TTS 会先显示确认框，再发起真实供应商请求，不是本地校验：
 
@@ -135,16 +134,16 @@ Iris 先按画图、视频、语音、转写和视觉功能组织候选池，再
 
 每项能力都可以设置一个有序的“供应商 + 模型”列表。界面显示的是模型名和供应商，配置中保存为 `providerId::modelId` 复合引用，因此不同供应商的同名模型不会冲突。
 
-- 六类功能仅使用各自分配名单，每次按名单顺序选择，不补入其他模型。
-- 临时指定模型须已分配，本次只调用该项。
+- 六类功能可选自动池、仅用所选模型或停用；手选不补池，自动池只纳入已确认用途的合格模型，每个请求从首项开始。
+- 临时指定模型须在当前功能允许范围内，本次只调用该项；功能停用时不能绕过。
 - “清空分配”停止新调用，模型、任务与作品保留；已有任务按原绑定观察和补交付。
-- 视觉可明确加入“DSH 当前默认模型”并排序；未加入时不使用宿主视觉。
+- 视觉可将“DSH 当前默认模型”加入手选名单，或在自动池中明确启用宿主视觉；默认不加入。
 
 生成类故障转移只覆盖上传、提交和同步生成阶段。远端一旦受理异步任务，Iris 就会继续跟踪这个任务，不会因轮询或下载失败自动重提，以免重复生成和计费。
 
 ## 音乐生成
 
-为音乐服务添加实际模型，设置“音乐”标签，选择 **Chat Completions（内嵌音频）** 协议，再将模型加入音乐能力分配名单。音乐必须明确分配，不从其他模型池自动补齐；这个接口要求服务在聊天响应正文中返回MP3/WAV音频data URL。
+为音乐服务添加实际模型，确认“音乐”用途，选择 **Chat Completions（内嵌音频）** 协议，再启用音乐自动池或加入手选名单。这个接口要求服务在聊天响应正文中返回 MP3/WAV 音频 data URL；音乐与 TTS 的用途及协议分别确认。
 
 配置后可在DSH中说“用Iris生成一首复古摇滚配乐”，或使用工作台音乐卡片。生成结果可试听、下载与导出；音乐和TTS分别配置，配乐按需加入多步骤流程。
 
@@ -178,7 +177,7 @@ Core 图片卡可直接点击“看图”或“OCR”；结果可以复制、下
 
 ### 按 Artifact ID 改图
 
-Core 静态 PNG/JPEG/WebP 图片卡可点击“改图”，填写修改指令，再选择已分配的带图编辑模型。点击“生成修改版”才调用模型，修改版保存为关联原图的新作品，原图保留；可继续看图、OCR、下载或编辑。
+Core 静态 PNG/JPEG/WebP 图片卡可点击“改图”，填写修改指令，再选择当前图片池允许的带图编辑模型。点击“生成修改版”才调用模型，修改版保存为关联原图的新作品，原图保留；可继续看图、OCR、下载或编辑。
 
 Agent可调用 `iris_edit_image`，提供 `source_artifact_id`、`prompt` 与可选 `model`；CLI使用 `run image`，模型字段为 `model_ref`，见 [Artifact改图](docs/CLI_MANAGEMENT.md#artifact-聊天改图)。支持openai-chat-images带图生成，0.2.4另支持DashScope原生Qwen edit/max/plus、2.0/pro及日期快照。不提供mask、多参考图或连续编辑历史。
 
@@ -219,7 +218,7 @@ $DSH_HOME/iris/v1/providers.json
 }
 ```
 
-`mediaBaseUrl` 可以省略或留空，此时媒体调用沿用 `baseUrl`。`assignments` 可以省略；省略后使用模型池顺序。包含特殊字符的 provider 或模型引用会经过 URL 编码，复杂引用建议在工作台中生成，不要手写。
+`mediaBaseUrl` 可以省略或留空，此时媒体调用沿用 `baseUrl`。`assignments` 可以省略，但从 0.2.4 起缺失分配不发起对应功能的新调用；0.2.6 也不会将其静默改为自动池。包含特殊字符的 provider 或模型引用会经过 URL 编码，复杂引用建议在工作台中生成，不要手写。
 
 可为明确不需要认证的本地端点设置 `"auth": "none"` 并省略 `apiKey`；缺省或 `"auth": "bearer"` 仍要求 Key，保持旧配置行为。无认证模式不会发送 Authorization 头，已有的旧 Key 也不会被带入该模式的媒体请求。工作台尚无专门的无认证开关，需要按上述停机原则编辑私有配置；不要对需要认证的公网端点使用 `auth:none`。
 
@@ -387,11 +386,11 @@ npx @mokuyoaxis/dsh-iris doctor --json
 
 已安装包也可以直接运行 `dsh-iris doctor`。退出码为 `0`（正常）、`1`（警告）和 `2`（硬错误）。Doctor 会执行一个随后立即删除的本地写入探针，并检查配置、任务、能力分配、临时文件和产物引用；输出不含完整 API Key。离线模式无法检查 DSH 工具/客户端是否已经装载，也不会用付费请求验证 Provider。
 
-**0.2.0** 另提供 `doctor --data-root <绝对路径> --json`：只读盘点指定 Core 数据根的 Task、Artifact、Index 和租约，不执行上述写入探针，也不自动修复。`providers list` 与 `capabilities list` 可用 `--provider-config <私有配置绝对路径>` 只读查看脱敏供应商摘要和按配置排序的候选链；它们不代表远端能力已实测。异常退出留下租约时，先用显式 Doctor 查看 owner，再按 [Headless CLI 的恢复步骤](docs/HEADLESS_CLI.md#异常退出后的写者租约)人工确认并运行 `runtime recover`，不要手动删除租约。安装 Iris 后使用 `dsh-iris` 命令；临时运行可用 `npx --package @mokuyoaxis/dsh-iris@0.2.4 dsh-iris ...`。旧版 0.1.4 不包含这些 Core 命令。
+**0.2.0** 另提供 `doctor --data-root <绝对路径> --json`：只读盘点指定 Core 数据根的 Task、Artifact、Index 和租约，不执行上述写入探针，也不自动修复。`providers list` 与 `capabilities list` 可用 `--provider-config <私有配置绝对路径>` 只读查看脱敏供应商摘要和按配置排序的候选链；它们不代表远端能力已实测。异常退出留下租约时，先用显式 Doctor 查看 owner，再按 [Headless CLI 的恢复步骤](docs/HEADLESS_CLI.md#异常退出后的写者租约)人工确认并运行 `runtime recover`，不要手动删除租约。安装 Iris 后使用 `dsh-iris` 命令；临时运行可用 `npx --package @mokuyoaxis/dsh-iris@0.2.6 dsh-iris ...`。旧版 0.1.4 不包含这些 Core 命令。
 
 ## Host Doctor
 
-DSH运行后打开“设置 → Iris工作台 → 宿主诊断”。卡片检查宿主/服务端/客户端版本、当前工具和随包Skill、四组路由与四个UI Slot。0.2.4包含17个工具和三项Skill；升级后检查服务端实际装载、刷新页面，并为所需功能分配模型。点击“刷新”查看结果，原始JSON可在已认证的同一浏览器访问 `/iris/api/doctor`。
+DSH 运行后打开“设置 → Iris 工作台 → 宿主诊断”。卡片检查宿主/服务端/客户端版本、当前工具和随包 Skill、四组路由与四个 UI Slot。0.2.6 保留 17 个工具和三项 Skill；升级后检查服务端实际装载、刷新页面，并确认功能策略。点击“刷新”查看结果，原始 JSON 可在同一浏览器访问 `/iris/api/doctor`；该路由使用 Iris 的 Host/来源守卫，不提供独立身份认证。
 
 0.2.4新增图片导入后检查17个工具，三项Skill保持；0.2.3为16个工具。
 
@@ -433,7 +432,7 @@ dsh plugin --profile web remove @mokuyoaxis/dsh-iris
 - **没有可用模型**：先确认供应商已启用且 Key 有效，再运行“发现模型”；未标注模型需通过“设置功能”选择用途，不支持 `/models` 时手动添加并标注。
 - **OpenAI 兼容图片请求走错协议**：核对模型的有效图片协议；`/images/generations` 使用 `openai-images`，网关聊天图片扩展使用 `openai-chat-images`，同步 `/responses` 生图使用 `openai-responses-images`。可在生图模型行或 CLI `models protocol` 设置模型级覆盖，不需要改变同账号其他模型的接口。
 - **反向代理访问返回 `untrusted host`**：把浏览器实际使用的域名或 `host:port` 加入 `IRIS_TRUSTED_HOSTS`，保留 Host，并确认代理层已经启用认证。
-- **模型池为空时使用宿主看图**：0.2.4需在视觉分配中明确加入“DSH 当前默认模型”；宿主默认模型须声明图片输入。也可配置并分配自持 `vision` 模型。
+- **模型池为空时使用宿主看图**：在视觉手选名单中加入“DSH 当前默认模型”，或在自动池中明确启用宿主视觉；宿主模型须声明图片输入。也可确认自持 `vision` 模型用途，再启用自动池或加入手选名单。
 - **视频摘要提示 ffmpeg 不可用**：安装系统级 `ffmpeg` 和 `ffprobe`，并确保 DSH 进程的 PATH 能找到它们。
 - **本地文件不存在**：这里的“本地”指 DSH 宿主，不一定是浏览器所在设备；优先用“上传文件”。
 - **视频任务长时间运行**：不要重复提交。用 `iris_task_status` 或工作台任务详情查询原任务。