@mokuyoaxis/dsh-iris 0.2.0 → 0.2.2

package/lib/provider-adapters.js

@@ -11,6 +11,8 @@ import { ProviderContractError, providerErrorRecord } from './provider-contract.
 import { writePrivateFile } from './private-storage.js';
 import { defineProviderAdapter } from './provider-adapter.js';
 import { selectMediaProtocol, providerApiKey, providerMediaBaseUrl, unsupportedProtocolError } from './provider-protocol.js';
+import { modelRateLimit, reportModelRateLimit, isFreeQuotaExhausted } from './provider-health.js';
+import { prepareVisionImage, visionInputLimits } from './vision-image-input.js';
 
 const AMBIGUOUS_4XX = new Set([408, 409, 425, 499]);
 
@@ -26,18 +28,21 @@ function providerIdentity(provider) {
 function mappedCategory(error, status) {
   const raw = String(error?.category || '').toLowerCase();
   if (error?.name === 'AbortError' || error?.code === 'ABORT_ERR') return 'aborted';
-  if (error?.name === 'TimeoutError' || /timeout|timed out|超时/i.test(String(error?.message || ''))) return 'timeout';
+  if (error?.name === 'TimeoutError' || raw === 'timeout'
+      || ((!raw || raw === 'unknown') && /timeout|timed out|超时/i.test(String(error?.message || '')))) return 'timeout';
+  if (isFreeQuotaExhausted(error)) return 'quota';
   if (status === 401 || status === 403 || raw === 'auth') return 'authentication';
   if (status === 429 && raw === 'quota') return 'quota';
   if (status === 429 || raw === 'rate_limit') return 'rate_limit';
-  if (raw === 'invalid_parameter') return 'invalid_request';
+  if (raw === 'invalid_parameter' || raw === 'invalid_request') return 'invalid_request';
+  if (raw === 'protocol') return 'protocol';
   if (raw === 'network' || error instanceof TypeError) return 'network';
   if (raw === 'server' || status >= 500) return 'provider';
   if (!status && /未返回|响应|协议|结构|json/i.test(String(error?.message || ''))) return 'protocol';
   return 'provider';
 }
 
-/** 当前两个协议共享的错误映射；不保留 cause、rootCause、正文、URL 或凭据。 */
+/** 已支持协议共享的错误映射；不保留 cause、rootCause、正文、URL 或凭据。 */
 export function mapProviderAdapterError(error, context = {}) {
   const statusValue = Number(error?.httpStatus ?? error?.status);
   const httpStatus = Number.isInteger(statusValue) && statusValue >= 100 && statusValue <= 599
@@ -90,10 +95,10 @@ function remoteImageArtifacts(urls) {
 function openAiImageArtifacts(items) {
   return (items || []).map((item) => {
     if (item && item.b64) {
-      return { kind: 'inline-base64', data: item.b64, mediaType: 'image/png' };
+      return { kind: 'inline-base64', data: item.b64, mediaType: item.mediaType || 'image/png' };
     }
     if (item && item.url) {
-      return { kind: 'remote-url', url: item.url, mediaType: 'image/png' };
+      return { kind: 'remote-url', url: item.url, mediaType: item.mediaType || 'image/png' };
     }
     throw new ProviderContractError('同步图片结果缺少 b64 或 URL', {
       stage: 'response', category: 'protocol', acceptance: 'accepted'
@@ -259,7 +264,7 @@ export function createDashScopeProviderAdapter(provider, { transport = defaultTr
   });
 }
 
-function operationsForOpenAiImages(provider, transport) {
+function operationsForOpenAiImages(provider, transport, protocol = 'openai-images') {
   const { key, baseUrl } = providerIdentity(provider);
   return {
     async discover({ signal, timeoutMs } = {}) {
@@ -268,14 +273,27 @@ function operationsForOpenAiImages(provider, transport) {
 
     async submit(request = {}) {
       if (request.capability !== 'image') {
-        throw unsupportedCapability(request.capability, 'openai-images');
+        throw unsupportedCapability(request.capability, protocol);
       }
       const input = request.input || {};
-      const items = await transport.openAiGenerateImage({
+      let image;
+      if (input.image) {
+        if (protocol !== 'openai-chat-images') throw new ProviderContractError('该图片协议不支持聊天改图', {
+          stage: 'validate', category: 'invalid_request', acceptance: 'not_accepted'
+        });
+        image = await prepareVisionImage(input.image, visionInputLimits(provider, request.model), { signal: request.signal, orient: true });
+      }
+      const method = {
+        'openai-images': 'openAiGenerateImage',
+        'openai-chat-images': 'openAiChatGenerateImage',
+        'openai-responses-images': 'openAiResponsesGenerateImage'
+      }[protocol];
+      const items = await transport[method]({
         key,
         baseUrl,
         model: request.model,
         prompt: input.prompt,
+        ...(image ? { image } : {}),
         size: input.size,
         n: input.n,
         signal: request.signal,
@@ -327,9 +345,39 @@ export function createOpenAiImagesProviderAdapter(provider, { transport = defaul
   });
 }
 
+export function createOpenAiChatImagesProviderAdapter(provider, { transport = defaultTransport } = {}) {
+  return defineProviderAdapter({
+    id: providerIdentity(provider).id,
+    protocol: 'openai-chat-images',
+    capabilities: ['image'],
+    operations: operationsForOpenAiImages(provider, transport, 'openai-chat-images'),
+    unsupported: {
+      poll: 'Chat Completions 生图为同步协议，不提供远端任务轮询',
+      cancel: 'Chat Completions 生图不提供远端取消'
+    },
+    unsupportedPreparation: 'Chat Completions 生图未实现临时输入上传'
+  });
+}
+
+export function createOpenAiResponsesImagesProviderAdapter(provider, { transport = defaultTransport } = {}) {
+  return defineProviderAdapter({
+    id: providerIdentity(provider).id,
+    protocol: 'openai-responses-images',
+    capabilities: ['image'],
+    operations: operationsForOpenAiImages(provider, transport, 'openai-responses-images'),
+    unsupported: {
+      poll: 'Responses 生图当前只接同步结果，不提供后台任务轮询',
+      cancel: '同步 Responses 生图不提供远端取消'
+    },
+    unsupportedPreparation: 'Responses 生图未实现临时输入上传'
+  });
+}
+
 const PROTOCOL_FACTORIES = new Map([
   ['dashscope', createDashScopeProviderAdapter],
-  ['openai-images', createOpenAiImagesProviderAdapter]
+  ['openai-images', createOpenAiImagesProviderAdapter],
+  ['openai-chat-images', createOpenAiChatImagesProviderAdapter],
+  ['openai-responses-images', createOpenAiResponsesImagesProviderAdapter]
 ]);
 
 export function createConfiguredProviderAdapter(provider, options = {}) {
@@ -338,5 +386,34 @@ export function createConfiguredProviderAdapter(provider, options = {}) {
     : selectMediaProtocol(provider);
   const factory = PROTOCOL_FACTORIES.get(selection.mediaProtocol);
   if (!factory) throw unsupportedProtocolError(selection.mediaProtocol);
-  return factory(provider, options);
+  const adapter = factory(provider, options);
+  const operations = { ...adapter.operations };
+  for (const name of ['submit', 'poll']) {
+    if (!operations[name]) continue;
+    const run = operations[name];
+    operations[name] = async request => {
+      const modelId = request.model || options.modelId;
+      const report = error => reportModelRateLimit(provider, modelId, {
+        httpStatus: error.httpStatus ?? error.status, category: error.category,
+        code: error.code, providerCode: error.providerCode, message: error.safeMessage || error.message,
+        retryAfterMs: error.retryAfterMs,
+        source: options.allowRateLimited ? 'probe' : 'task'
+      }, options.onRateLimit, request.capability);
+      if (name === 'submit' && !options.allowRateLimited && modelRateLimit(provider, modelId)) {
+        const blocked = modelRateLimit(provider, modelId);
+        throw new ProviderContractError(blocked.until ? '该模型正在限流冷却，请稍后使用' : '该模型额度或预算耗尽，请手动实测成功后再使用', {
+          stage: 'validate', category: 'rate_limit', acceptance: 'not_accepted'
+        });
+      }
+      try {
+        const result = await run(request);
+        if (result.error) report(result.error);
+        return result;
+      } catch (error) {
+        report(error);
+        throw error;
+      }
+    };
+  }
+  return Object.freeze({ ...adapter, operations: Object.freeze(operations) });
 }

package/lib/provider-catalog.js

@@ -5,8 +5,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { CAPABILITIES } from './capability.js';
 import { modelPool, orderedModels, providerModels, parseModelRef, resolveModelRef, resolvePoolModel, selectionReasonForModel } from './models.js';
-import { dashscopeApiBase, selectMediaProtocol, providerMediaBaseUrl, isConfiguredProvider } from './provider-protocol.js';
+import { dashscopeApiBase, selectMediaProtocol, providerForImageModel, providerMediaBaseUrl, isConfiguredProvider } from './provider-protocol.js';
 import { redactProviderMessage } from './provider-contract.js';
+import { modelRateLimit } from './provider-health.js';
+import { normalizeVisionInputLimits } from './vision-image-input.js';
 
 export class ProviderCatalogError extends Error {
   constructor(code, message) {
@@ -52,10 +54,10 @@ export function loadProviderCatalog(configPath) {
 
 const CANDIDATE_CAP_LABEL = Object.freeze({
   [CAPABILITIES.IMAGE]: '图片', [CAPABILITIES.VIDEO]: '视频',
-  [CAPABILITIES.TTS]: '语音', [CAPABILITIES.TRANSCRIBE]: '转写'
+  [CAPABILITIES.TTS]: '语音', [CAPABILITIES.TRANSCRIBE]: '转写', [CAPABILITIES.VISION]: '视觉'
 });
 
-/** 与稳定配置层相同的“手工顺序优先、池序补齐”候选规则（image/video/tts/transcribe 同构）。 */
+/** 与稳定配置层相同的“手工顺序优先、池序补齐”候选规则。 */
 function candidatesFromCatalog(catalog, requestedModelRef, capability) {
   const label = CANDIDATE_CAP_LABEL[capability];
   if (!label) fail('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', '当前 Headless 候选链只开放图片、视频、语音与转写能力');
@@ -68,6 +70,9 @@ function candidatesFromCatalog(catalog, requestedModelRef, capability) {
     const exact = resolvePoolModel(pool, requested, capability);
     if (!exact) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `指定模型不存在、未启用或没有${label}能力`);
     const provider = providers.find((item) => item.id === exact.providerId);
+    if (exact.rateLimited) fail('IRIS_PROVIDER_MODEL_RATE_LIMITED', modelRateLimit(provider, exact.id)?.until
+      ? '指定模型正在限流冷却，请稍后使用或手动实测'
+      : '指定模型额度或预算耗尽，请手动实测成功后再使用');
     return Object.freeze([Object.freeze({
       provider, model: exact.id, modelRef: resolveModelRef(provider, capability, requested),
       selectionReason: 'explicit'
@@ -85,7 +90,8 @@ function candidatesFromCatalog(catalog, requestedModelRef, capability) {
 }
 
 export function imageCandidatesFromCatalog(catalog, requestedModelRef = '') {
-  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.IMAGE);
+  return Object.freeze(candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.IMAGE).map(route =>
+    Object.freeze({ ...route, provider: providerForImageModel(route.provider, route.model) })));
 }
 
 export function videoCandidatesFromCatalog(catalog, requestedModelRef = '') {
@@ -100,6 +106,10 @@ export function transcribeCandidatesFromCatalog(catalog, requestedModelRef = '')
   return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.TRANSCRIBE);
 }
 
+export function visionCandidatesFromCatalog(catalog, requestedModelRef = '') {
+  return candidatesFromCatalog(catalog, requestedModelRef, CAPABILITIES.VISION);
+}
+
 /** 只读配置投影；不构造 Adapter、不发现模型、不暴露端点或凭据。 */
 export function providerCatalogSnapshot(catalog) {
   const safeLabel = (value) => value
@@ -114,6 +124,7 @@ export function providerCatalogSnapshot(catalog) {
         enabled: provider.enabled !== false, configured: isConfiguredProvider(provider),
         auth: provider.auth === 'none' ? 'none' : 'bearer',
         mediaProtocol: safeLabel(selection.mediaProtocol), protocolInferred: selection.protocolInferred,
+        ...(provider.visionInput ? { visionInput: normalizeVisionInputLimits(provider.visionInput) } : {}),
         capabilities: Object.values(CAPABILITIES).filter((capability) => models.some((model) => model.capabilities.includes(capability))),
         modelCount: models.length
       };
@@ -141,7 +152,7 @@ export function providerTaskBinding(provider) {
   try {
     const url = new URL(baseUrl);
     if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('unsafe endpoint');
-    if (!['dashscope', 'openai-images'].includes(protocol)) throw new Error('unknown protocol');
+    if (!['dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images'].includes(protocol)) throw new Error('unknown protocol');
     endpoint = protocol === 'dashscope' ? dashscopeApiBase(baseUrl) : url.href.replace(/\/+$/, '');
   } catch (_) { fail('IRIS_PROVIDER_CONFIG_INVALID', 'Provider 媒体端点或协议无效'); }
   return 'sha256:' + crypto.createHash('sha256').update(JSON.stringify([1, protocol, endpoint])).digest('hex');
@@ -161,8 +172,9 @@ export function providerForTaskFromCatalog(catalog, task) {
   if (!parsed || parsed.providerId !== task.providerId) fail('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Task 的 Provider 与模型身份不一致');
   const matches = catalog.providers.filter((item) => item && item.id === task.providerId);
   if (matches.length > 1) fail('IRIS_PROVIDER_CONFIG_AMBIGUOUS', 'provider-config 存在重复 Provider ID');
-  const provider = matches[0];
-  if (!provider || provider.enabled === false || (provider.auth !== 'none' && (typeof provider.apiKey !== 'string' || !provider.apiKey.trim()))) fail('IRIS_PROVIDER_TASK_PROVIDER_UNAVAILABLE', 'Task 原 Provider 已移除、停用或缺少凭据');
+  const configured = matches[0];
+  if (!configured || configured.enabled === false || (configured.auth !== 'none' && (typeof configured.apiKey !== 'string' || !configured.apiKey.trim()))) fail('IRIS_PROVIDER_TASK_PROVIDER_UNAVAILABLE', 'Task 原 Provider 已移除、停用或缺少凭据');
+  const provider = task.capability === 'image' ? providerForImageModel(configured, parsed.modelId) : configured;
   if (!task.providerBinding) fail('IRIS_PROVIDER_TASK_BINDING_MISSING', '旧 Task 缺少提交端点绑定；仅支持只读查看，不猜测恢复配置');
   if (providerTaskBinding(provider) !== task.providerBinding) fail('IRIS_PROVIDER_TASK_BINDING_MISMATCH', 'Task 提交端点或协议已改变；拒绝向新端点观察原任务');
   const model = modelPool([provider]).find((item) => item.providerId === parsed.providerId && item.id === parsed.modelId && item.capabilities.includes(capability));

package/lib/provider-config-service.js

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+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, capabilitiesOfDiscoveredModel, hasConfiguredModelCapabilities, resolvePoolModel } from './models.js';
+import { atomicWritePrivate, privateSibling, ensurePrivateDir } from './private-storage.js';
+import { createConfiguredProviderAdapter } from './provider-adapters.js';
+import { selectImageProtocol, normalizeImageProtocol } 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 { normalizeVisionInputLimits, visionInputLimits } from './vision-image-input.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');
+const safe = value => redactProviderMessage(String(value || '').replace(/https?:\/\/[^\s<>"']+/gi, '[URL]'));
+const text = value => { if (typeof value !== 'string' || !value.trim()) fail('ID 必须是非空字符串'); return value.trim(); };
+const caps = value => {
+  if (!Array.isArray(value) || !value.every(isKnownCapability) || new Set(value).size !== value.length) fail('capabilities 必须是不重复的已知能力数组');
+  return value;
+};
+
+function assignmentSnapshot(catalog) {
+  const pool = modelPool(catalog.providers);
+  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 }];
+  }));
+}
+
+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.imageProtocol !== undefined ? { imageProtocol: model.imageProtocol } : {}),
+    ...(model.visionInput !== undefined ? { visionInput: model.visionInput } : {}),
+    ...(model.capabilities.includes('vision') ? { visionInputEffective: visionInputLimits(provider, model.id) } : {}),
+    ...(model.capabilities.includes('image-gen') ? { imageRouting: selectImageProtocol(provider, model.id) } : {}),
+    verified: Object.fromEntries(Object.entries(model.verified || {}).map(([capability, value]) => [capability, { ok: value.ok === true, at: safe(value.at), category: safe(value.category) }])),
+    ...(model.rateLimited ? { rateLimited: true, rateLimitedAt: modelRateLimit(provider, model.id).at,
+      ...(modelRateLimit(provider, model.id).until ? { retryAt: modelRateLimit(provider, model.id).until }
+        : { reason: modelRateLimit(provider, model.id).reason }) } : {})
+  }))), assignments: assignmentSnapshot(catalog), routing: catalogCapabilitySnapshot(catalog) };
+}
+
+export async function executeConfigCommand(configPath, command, input = {}, { signal, probe } = {}) {
+  if (command === 'init') {
+    if (!path.isAbsolute(configPath)) fail('provider-config 必须是绝对路径');
+    ensurePrivateDir(path.dirname(configPath));
+    fs.writeFileSync(configPath, JSON.stringify({ providers: [], assignments: {} }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    return { command, created: true };
+  }
+  const catalog = loadProviderCatalog(configPath);
+  const before = fs.readFileSync(configPath);
+  if (JSON.stringify(JSON.parse(before)) !== JSON.stringify(catalog)) throw Object.assign(new Error('配置在读取期间发生变化，请重试'), { code: 'IRIS_CONFIG_CHANGED' });
+  if (command === 'show') return configSnapshot(catalog);
+  if (command === 'check') {
+    const issues = [];
+    const ids = catalog.providers.map(provider => provider.id);
+    if (new Set(ids).size !== ids.length) issues.push('duplicate_provider_id');
+    const pool = modelPool(catalog.providers);
+    for (const provider of catalog.providers) {
+      try { normalizeVisionInputLimits(provider.visionInput); } catch (_) { issues.push('invalid_vision_input'); }
+      for (const model of provider.models || []) {
+        try { normalizeVisionInputLimits(model?.visionInput); } catch (_) { issues.push('invalid_model_vision_input'); }
+        if (model?.imageProtocol === undefined) continue;
+        try { normalizeImageProtocol(model.imageProtocol); } catch (_) { issues.push('invalid_model_image_protocol'); }
+      }
+    }
+    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');
+    }
+    return { valid: issues.length === 0, issues: [...new Set(issues)] };
+  }
+  if (command === 'models.list') return { models: configSnapshot(catalog).models };
+  if (command === 'assignments.list') return { ...catalogCapabilitySnapshot(catalog), assignments: assignmentSnapshot(catalog) };
+  let result = { command, changed: true };
+  const initialPool = modelPool(catalog.providers);
+  let provider;
+  const providerId = input.provider_id || parseModelRef(input.model_ref)?.providerId || input.provider?.id;
+  if (providerId) {
+    const matches = catalog.providers.filter(value => value.id === providerId);
+    if (matches.length > 1) fail('Provider ID 不唯一');
+    provider = matches[0];
+  }
+  if (command === 'providers.add' || command === 'providers.set') {
+    const value = input.provider;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) fail('需要 provider 对象');
+    const id = text(value.id);
+    if (command === 'providers.add' ? Boolean(provider) : !provider) fail(command === 'providers.add' ? 'Provider 已存在' : 'Provider 不存在');
+    const updated = { ...(provider || {}), ...value, id };
+    if (updated.visionInput !== undefined) updated.visionInput = normalizeVisionInputLimits(updated.visionInput) || null;
+    let url;
+    try { url = new URL(updated.baseUrl); } catch (_) { fail('baseUrl 必须是 HTTP(S) 地址'); }
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) fail('baseUrl 含不支持的协议或凭据参数');
+    if (updated.enabled !== undefined && typeof updated.enabled !== 'boolean') fail('enabled 必须是布尔值');
+    if (updated.models !== undefined) {
+      if (!Array.isArray(updated.models)) fail('models 必须是数组');
+      for (const model of updated.models) {
+        text(typeof model === 'string' ? model : model?.id);
+        if (model?.capabilities !== undefined) caps(model.capabilities);
+      }
+      updated.models = updated.models.map(model => typeof model === 'string' ? model : ({ ...model,
+        ...(model?.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(model.imageProtocol) } : {}),
+        ...(model?.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(model.visionInput) || null } : {}) }));
+    }
+    if (provider) {
+      for (const model of providerModels(provider)) {
+        if (selectImageProtocol(provider, model.id).mediaProtocol !== selectImageProtocol(updated, model.id).mediaProtocol) {
+          clearModelCapabilityHealth(updated, model.id, 'image-gen');
+        }
+      }
+    }
+    if (provider) catalog.providers[catalog.providers.indexOf(provider)] = updated;
+    else catalog.providers.push(updated);
+  } else if (command === 'providers.remove') {
+    if (!provider) fail('Provider 不存在');
+    catalog.providers.splice(catalog.providers.indexOf(provider), 1);
+  } else if (command.startsWith('models.')) {
+    if (!provider) fail('Provider 不存在');
+    const parsed = parseModelRef(input.model_ref);
+    const modelId = parsed?.modelId || input.model_id;
+    let entries = Array.isArray(provider.models) ? provider.models.map(model => typeof model === 'string' ? { id: model } : { ...model })
+      : providerModels(provider).map(({ id, capabilities }) => ({ id, capabilities }));
+    let entry = entries.find(model => model.id === modelId);
+    if (command === 'models.discover') {
+      const discovered = await invokeProviderOperation(createConfiguredProviderAdapter(provider), 'discover', { signal, timeoutMs: 15000 });
+      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;
+      for (const model of models) {
+        const old = entries.find(value => value.id === model.id);
+        if (!old) entries.push(model);
+        else if (!hasConfiguredModelCapabilities(provider, model.id)) Object.assign(old, model);
+      }
+    } else if (command === 'models.add') {
+      text(modelId);
+      const capabilities = input.capabilities === undefined ? undefined : caps(input.capabilities);
+      if (entry) fail('模型已存在；请用 models caps 修改能力');
+      entries.push({ id: modelId, capabilities, source: 'manual',
+        ...(input.imageProtocol !== undefined ? { imageProtocol: normalizeImageProtocol(input.imageProtocol) } : {}),
+        ...(input.visionInput !== undefined ? { visionInput: normalizeVisionInputLimits(input.visionInput) || null } : {}) });
+    } else if (command === 'models.remove') {
+      if (!entry) fail('模型不存在');
+      entries = entries.filter(model => model.id !== modelId);
+    } else if (command === 'models.caps') {
+      if (!entry) fail('模型不存在');
+      entry.capabilities = caps(input.capabilities); entry.source = 'manual';
+    } else if (command === 'models.protocol') {
+      if (!entry) fail('模型不存在');
+      const protocol = normalizeImageProtocol(input.imageProtocol);
+      const previous = selectImageProtocol(provider, modelId).mediaProtocol;
+      if (protocol === 'auto') delete entry.imageProtocol;
+      else entry.imageProtocol = protocol;
+      provider.models = entries;
+      if (previous !== selectImageProtocol(provider, modelId).mediaProtocol) clearModelCapabilityHealth(provider, modelId, 'image-gen');
+      result = { ...result, model_ref: safe(input.model_ref), imageRouting: selectImageProtocol(provider, modelId) };
+    } else if (command === 'models.vision-input') {
+      if (!entry || !Object.hasOwn(input, 'visionInput')) fail('需要已存在的模型和 visionInput 对象或 null');
+      const limits = normalizeVisionInputLimits(input.visionInput);
+      if (limits) entry.visionInput = limits;
+      else delete entry.visionInput;
+      provider.models = entries;
+      result = { ...result, model_ref: safe(input.model_ref), visionInputEffective: visionInputLimits(provider, modelId) };
+    } else if (command === 'models.test') {
+      if (!entry || !isKnownCapability(input.capability) || !providerModels(provider).find(model => model.id === modelId)?.capabilities.includes(input.capability)) fail('模型不存在或没有指定能力');
+      if (typeof probe !== 'function') fail('模型实测缺少 Probe Port');
+      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.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); }
+      if (tested.ok === true) { observation.lastSuccess = evidence; clearModelRateLimit(provider, modelId); }
+      else {
+        observation[isDefinitiveHealthFailure(evidence) ? 'lastFailure' : 'lastTransient'] = evidence;
+        recordModelRateLimit(provider, modelId, evidence);
+      }
+      result = { command, changed: true, passed: tested.ok === true, ...(tested.taskId ? { taskId: tested.taskId } : {}), ...(tested.code ? { code: tested.code } : {}) };
+    } else fail('未知模型命令');
+    provider.models = entries;
+  } 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 {
+      if (!Array.isArray(input.model_refs) || new Set(input.model_refs).size !== input.model_refs.length) fail('model_refs 必须是不重复的复合引用数组');
+      const pool = modelPool(catalog.providers);
+      for (const ref of input.model_refs) if (!parseModelRef(ref) || !resolvePoolModel(pool, ref, input.capability)) fail('分配模型不存在或没有该能力');
+      catalog.assignments[input.capability] = input.model_refs;
+    }
+  } else fail('未知配置命令');
+
+  // 移除/降级条目时剪去明确指向该条目的分配，保留其他账号和旧裸引用格式。
+  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];
+      else catalog.assignments[capability] = Array.isArray(assignment) ? values : values[0];
+    }
+  }
+  signal?.throwIfAborted();
+  return writeConfigChange(configPath, catalog, before, result);
+}
+
+/** 请求边界持久化冷却或明确耗尽；沿用配置锁、备份与原子写入。 */
+export function recordCatalogRateLimit(configPath, event) {
+  const { providerId, modelId } = event;
+  const catalog = loadProviderCatalog(configPath);
+  const before = fs.readFileSync(configPath);
+  const provider = catalog.providers.find(value => value.id === providerId);
+  if (!provider || !recordModelRateLimit(provider, modelId, { ...event, source: 'task' })) return;
+  return writeConfigChange(configPath, catalog, before, { changed: true });
+}
+
+function writeConfigChange(configPath, catalog, before, result) {
+  const lock = configPath + '.lock';
+  let fd;
+  try { fd = fs.openSync(lock, 'wx', 0o600); }
+  catch (_) { throw Object.assign(new Error('配置正在被另一进程修改'), { code: 'IRIS_CONFIG_BUSY' }); }
+  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 });
+    atomicWritePrivate(configPath, JSON.stringify(catalog, null, 2) + '\n');
+    result.backupPath = backupPath;
+    return result;
+  } finally { fs.closeSync(fd); fs.unlinkSync(lock); }
+}

package/lib/provider-contract.js

@@ -146,7 +146,8 @@ export function normalizeProviderArtifacts(value) {
     }
     if (item.kind === 'inline-base64') {
       const data = String(item.data || '').trim();
-      if (!data || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data)) {
+      // 避免按四字符重复分组：4K 图片的大 base64 正文会耗尽正则回溯栈。
+      if (!data || data.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(data)) {
         throw new TypeError('Provider inline-base64 artifact 数据无效');
       }
       const padding = data.endsWith('==') ? 2 : (data.endsWith('=') ? 1 : 0);
@@ -287,7 +288,7 @@ export async function submitWithAcceptanceBoundary(candidates, input, hooks = {}
       }
     }
 
-    if (!allowsAutomaticFailover(result)) {
+    if (hooks.signal?.aborted || !allowsAutomaticFailover(result)) {
       return { candidate, result, attempts, localError: null };
     }
   }

package/lib/provider-health.js

@@ -10,6 +10,85 @@ export const PROVIDER_HEALTH_STATES = Object.freeze([
 ]);
 
 const DEFINITIVE_FAILURES = new Set(['authentication', 'auth', 'permission']);
+export const MODEL_RATE_LIMIT_COOLDOWN_MS = 60000;
+
+export function retryAfterDelay(value, now = Date.now()) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return MODEL_RATE_LIMIT_COOLDOWN_MS;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.max(1000, seconds * 1000);
+  const at = Date.parse(raw);
+  return Number.isFinite(at) && at > now ? at - now : MODEL_RATE_LIMIT_COOLDOWN_MS;
+}
+
+/** 百炼“免费额度用完即停”返回 403，不应误归类为 Key 无效。 */
+export function isFreeQuotaExhausted(value) {
+  const status = Number(value?.httpStatus ?? value?.status);
+  if (![403, 429].includes(status)) return false;
+  return status === 403 && (value.category === 'quota' || value.code === 'IRIS_MODEL_RATE_LIMITED')
+    || (value.providerCode || value.code) === 'AllocationQuota.FreeTierOnly'
+    || /\bfree (?:allocated quota|quota|tier)\b[^\n]{0,120}\b(?:exhausted|expired|exceeded)\b/i.test(String(value.message || value.safeMessage || value.note || ''));
+}
+
+export function quotaExhaustionReason(value) {
+  if (isFreeQuotaExhausted(value) || value?.reason === 'free_quota') return 'free_quota';
+  const status = Number(value?.httpStatus ?? value?.status);
+  if (status !== 429) return null;
+  if ((value.providerCode || value.code) === 'BudgetLimitExceeded' || value.reason === 'budget') return 'budget';
+  return null;
+}
+
+/** 短时限流到期即可参与候选；额度/预算耗尽只有成功实测才解除。 */
+export function modelRateLimit(provider, modelId, { now = Date.now() } = {}) {
+  const blocked = provider?.health?.rateLimits?.find(item => item.modelId === modelId);
+  return blocked && (!blocked.until || Date.parse(blocked.until) > now) ? blocked : null;
+}
+
+export function recordModelRateLimit(provider, modelId, result) {
+  const status = Number(result?.httpStatus ?? result?.status);
+  const reason = quotaExhaustionReason(result);
+  const category = reason ? 'quota' : status === 429 ? 'rate_limit' : null;
+  const existing = modelRateLimit(provider, modelId);
+  if (!category || !modelId || existing && (!reason || existing.reason)) return false;
+  provider.health ||= { version: 1, revision: 0, observations: [] };
+  provider.health.rateLimits ||= [];
+  const at = Date.parse(result.at || '');
+  const timestamp = Number.isFinite(at) ? at : Date.now();
+  const delay = Number.isFinite(result.retryAfterMs) ? result.retryAfterMs : MODEL_RATE_LIMIT_COOLDOWN_MS;
+  provider.health.rateLimits = provider.health.rateLimits.filter(item => item.modelId !== modelId);
+  provider.health.rateLimits.push({ modelId,
+    at: new Date(timestamp).toISOString(),
+    source: result.source === 'probe' ? 'probe' : 'task', category, httpStatus: status,
+    ...(reason ? { reason } : { until: result.until || new Date(timestamp + Math.max(1000, delay)).toISOString() }) });
+  return true;
+}
+
+/** 只有显式模型实测通过才调用；普通任务成功不能解除停用。 */
+export function clearModelRateLimit(provider, modelId) {
+  if (!provider?.health?.rateLimits) return;
+  provider.health.rateLimits = provider.health.rateLimits.filter(item => item.modelId !== modelId);
+  if (!provider.health.rateLimits.length) delete provider.health.rateLimits;
+}
+
+/** 配置改变时使一项能力验证失效；保留同模型的限流/耗尽资格和其他能力。 */
+export function clearModelCapabilityHealth(provider, modelId, capability) {
+  if (provider.health?.observations) {
+    provider.health = { ...provider.health, revision: (provider.health.revision || 0) + 1,
+      observations: provider.health.observations.filter(item => item.modelId !== modelId || item.capability !== capability) };
+  }
+  const entry = provider.models?.find(model => model?.id?.trim() === modelId);
+  if (entry?.verified) {
+    entry.verified = { ...entry.verified };
+    delete entry.verified[capability];
+  }
+}
+
+export function reportModelRateLimit(provider, modelId, result, onRateLimit, capability) {
+  if (!recordModelRateLimit(provider, modelId, result)) return;
+  const blocked = modelRateLimit(provider, modelId);
+  try { onRateLimit?.({ providerId: provider.id, capability, ...blocked }); }
+  catch (_) { console.warn('[iris] 模型停用状态未能持久化，请检查配置写入权限'); }
+}
 
 function validTime(value) {
   const ms = Date.parse(String(value || ''));
@@ -19,7 +98,7 @@ function validTime(value) {
 export function isDefinitiveHealthFailure(value) {
   const status = Number(value && (value.httpStatus ?? value.status));
   const category = String(value && value.category || '').toLowerCase();
-  return status === 401 || status === 403 || DEFINITIVE_FAILURES.has(category);
+  return !isFreeQuotaExhausted(value) && (status === 401 || status === 403 || DEFINITIVE_FAILURES.has(category));
 }
 
 export function healthObservationState(observation, {