@mokuyoaxis/dsh-iris 0.1.4 → 0.2.1

package/lib/provider-config-service.js

@@ -0,0 +1,236 @@
+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, capabilitiesOfModel, capabilitiesOfDiscoveredModel, 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) {
+        if (!model.capabilities.length) continue;
+        const old = entries.find(value => value.id === model.id);
+        if (!old) entries.push(model);
+        else if (old.source !== 'manual') Object.assign(old, model);
+      }
+    } else if (command === 'models.add') {
+      text(modelId);
+      const capabilities = input.capabilities === undefined ? capabilitiesOfModel(modelId) : 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

@@ -42,10 +42,32 @@ export const PROVIDER_ERROR_CATEGORIES = Object.freeze([
 ]);
 
 const ACCEPTANCE = new Set(['not_accepted', 'accepted', 'unknown']);
-const SECRET_QUERY = /([?&](?:access[_-]?key|api[_-]?key|authorization|credential|signature|token)=)[^&#\s]+/gi;
+// 凭据查询参数：允许厂商前缀（x-amz- / x-oss- / OSSAccessKeyId 这类驼峰），但**限制尾部后缀**
+// （审计 C-9 要求覆盖带前缀参数名）。
+//
+// 正则分两级，是为了同时满足两个方向：
+//   ① 强凭据词（key/credential/signature/secret）：允许任意字母前缀 + 有限后缀（id|secret|ids），
+//      保证 OSSAccessKeyId / X-Amz-Credential / gemini-signature 一律脱敏；
+//   ② 弱凭据词（token/auth/authorization）：只允许【白名单厂商前缀】，且后缀限 id|secret|ids。
+//      这是 C-9 首版修复的更正——首版给两级都开了无限 `[a-z0-9_-]*` 后缀，导致
+//      page_token / tokenizer / signature_mode 这类非凭据参数被误脱敏，诊断信息丢失。
+const SECRET_STRONG = '(?:access[_-]?key|api[_-]?key|apikey|credential|signature|secret)';
+const SECRET_WEAK = '(?:token|auth|authorization)';
+const SECRET_SUFFIX = '(?:id|secret|ids)?';
+const SECRET_VENDOR = '(?:(?:x|amz|oss|aliyun|aws|s3|gcp|azure|sts|sec|security|sig|sign|auth|oauth|bearer|jwt|session|csrf|access|api|private|secret|refresh|id|tmp|temp)[-_]?)*';
+const SECRET_NAME = '(?:' + '(?:[a-z0-9]+[-_])*[a-z0-9]*' + SECRET_STRONG + SECRET_SUFFIX
+  + '|' + SECRET_VENDOR + SECRET_WEAK + SECRET_SUFFIX + ')';
+const SECRET_QUERY = new RegExp('([?&]' + SECRET_NAME + '=)[^&#\\s]+', 'gi');
 const BEARER = /\bBearer\s+[^\s,;]+/gi;
 const API_KEY = /\bsk-[A-Za-z0-9_-]{8,}\b/g;
-const JSON_SECRET = /(["']?(?:api[_-]?key|authorization|access[_-]?token|secret)["']?\s*[:=]\s*["']?)[^"',\s}]+/gi;
+// 结构化凭据字段：与 SECRET_QUERY 同构，同样限制弱凭据词的后缀。
+// 左边界 `NAME_START` 不可省：否则 `page_token=x` 里的子串 `token=x` 也会被匹配，
+// 非凭据参数将被误脱敏（本次收紧时发现，旧实现同样存在该缺陷）。
+const NAME_START = '(?<![A-Za-z0-9_-])';
+const JSON_SECRET = new RegExp('(\"?\'?' + NAME_START
+  + '(?:' + '(?:[A-Za-z0-9]+[-_])*' + SECRET_STRONG + SECRET_SUFFIX
+  + '|' + SECRET_VENDOR.replace(/\[-_\]\?/g, '[-_]?') + SECRET_WEAK + SECRET_SUFFIX + ')'
+  + '[\"\']?\\s*[:=]\\s*[\"\']?)[^\"\',\\s}]+', 'gi');
 const POSIX_PATH = /(^|[\s("'=])\/(?:[^/\s"'`,;)}\]]+\/)*[^/\s"'`,;)}\]]+/gm;
 const WINDOWS_PATH = /\b[A-Za-z]:\\(?:[^\\\s"'`,;)}\]]+\\)*[^\\\s"'`,;)}\]]+/g;
 
@@ -103,6 +125,44 @@ export class ProviderContractError extends Error {
   }
 }
 
+/**
+ * Provider 交付描述只允许远端 URL 或短生命周期的内联 base64。内联正文故意设为
+ * non-enumerable：Runner 可以物化它，但日志、JSON 和 Task 持久化不会顺手复制图片。
+ */
+export function normalizeProviderArtifacts(value) {
+  if (value === undefined) return Object.freeze([]);
+  if (!Array.isArray(value)) throw new TypeError('Provider artifacts 必须是数组');
+  return Object.freeze(value.map((item) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      throw new TypeError('Provider artifact 必须是对象');
+    }
+    const mediaType = typeof item.mediaType === 'string' && item.mediaType.trim()
+      ? item.mediaType.trim()
+      : undefined;
+    if (item.kind === 'remote-url') {
+      const url = String(item.url || '').trim();
+      if (!url) throw new TypeError('Provider remote-url artifact 缺少 url');
+      return Object.freeze({ kind: 'remote-url', url, ...(mediaType ? { mediaType } : {}) });
+    }
+    if (item.kind === 'inline-base64') {
+      const data = String(item.data || '').trim();
+      // 避免按四字符重复分组：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);
+      const artifact = {
+        kind: 'inline-base64',
+        byteLength: (data.length / 4) * 3 - padding,
+        ...(mediaType ? { mediaType } : {})
+      };
+      Object.defineProperty(artifact, 'data', { value: data, enumerable: false });
+      return Object.freeze(artifact);
+    }
+    throw new TypeError('Provider artifact kind 仅支持 remote-url/inline-base64');
+  }));
+}
+
 export function normalizeSubmissionResult(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new TypeError('Provider submit 必须返回结构化结果');
@@ -111,7 +171,17 @@ export function normalizeSubmissionResult(value) {
     throw new TypeError('未知 Provider submit kind: ' + String(value.kind));
   }
   if (value.kind === 'completed') {
-    return { kind: 'completed', acceptance: 'accepted', value: value.value };
+    const result = {
+      kind: 'completed', acceptance: 'accepted',
+      ...(value.artifacts !== undefined ? { artifacts: normalizeProviderArtifacts(value.artifacts) } : {})
+    };
+    if (value.value !== undefined) {
+      Object.defineProperty(result, 'value', {
+        value: value.value,
+        enumerable: value.artifacts === undefined
+      });
+    }
+    return result;
   }
   if (value.kind === 'accepted') {
     const remoteTaskId = String(value.remoteTaskId || '').trim();
@@ -218,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, {

package/lib/provider-protocol.js

@@ -2,18 +2,77 @@
 /** 供应商媒体协议判断与 DashScope 凭据边界。 */
 
 const DASH_SCOPE_HOST = /^dashscope(?:-[a-z0-9-]+)?\.aliyuncs\.com$/i;
+const REGIONAL_HOST = /^cn-hongkong\.dashscope\.aliyuncs\.com$/i;
+const WORKSPACE_HOST = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.(?:cn-beijing|ap-southeast-1|eu-central-1|ap-northeast-1|us-east-1)\.maas\.aliyuncs\.com$/i;
+
+/** 可选媒体端点；空值沿用普通/视觉端点。 */
+export function providerMediaBaseUrl(provider) {
+  return String(provider?.mediaBaseUrl || '').trim() || String(provider?.baseUrl || '').trim();
+}
 
 export function isDashScopeBaseUrl(value) {
   try {
     const url = new URL(String(value || '').trim());
-    return url.protocol === 'https:' && !url.username && !url.password && DASH_SCOPE_HOST.test(url.hostname);
+    return url.protocol === 'https:' && !url.username && !url.password
+      && (DASH_SCOPE_HOST.test(url.hostname) || REGIONAL_HOST.test(url.hostname) || WORKSPACE_HOST.test(url.hostname));
   } catch (_) {
     return false;
   }
 }
 
 export function inferMediaProtocol(baseUrl) {
-  return isDashScopeBaseUrl(baseUrl) ? 'dashscope' : 'openai-images';
+  return detectMediaProtocol(baseUrl) || 'openai-images';
+}
+
+/** 未识别的端点不等于已验证的兼容协议。 */
+export function detectMediaProtocol(baseUrl) {
+  if (isDashScopeBaseUrl(baseUrl)) return 'dashscope';
+  try {
+    const url = new URL(String(baseUrl || '').trim());
+    if (url.protocol === 'https:' && !url.username && !url.password
+        && url.hostname === 'api.openai.com') return 'openai-images';
+  } catch (_) { /* 未知端点保留兼容回退，由调用方展示推断状态 */ }
+  return null;
+}
+
+export function selectMediaProtocol(provider) {
+  const explicit = typeof provider?.mediaProtocol === 'string' ? provider.mediaProtocol.trim() : '';
+  if (explicit && explicit !== 'auto'
+      && (provider?.protocolInferred !== true || explicit !== 'openai-images')) {
+    return { mediaProtocol: explicit, protocolInferred: false };
+  }
+  const detected = detectMediaProtocol(providerMediaBaseUrl(provider));
+  return { mediaProtocol: detected || 'openai-images', protocolInferred: !detected };
+}
+
+/** 模型图片协议只覆盖生图；auto 沿用账号级默认，不另外猜测端点。 */
+export function normalizeImageProtocol(value) {
+  const protocol = typeof value === 'string' ? value.trim() : '';
+  if (!['auto', 'dashscope', 'openai-images', 'openai-chat-images', 'openai-responses-images'].includes(protocol)) {
+    throw Object.assign(new TypeError('imageProtocol 必须是 auto、dashscope、openai-images、openai-chat-images 或 openai-responses-images'), {
+      code: 'IRIS_PROVIDER_IMAGE_PROTOCOL_INVALID'
+    });
+  }
+  return protocol;
+}
+
+export function selectImageProtocol(provider, modelId) {
+  const entry = Array.isArray(provider?.models) ? provider.models.find(model => model?.id?.trim() === modelId) : null;
+  if (entry?.imageProtocol === undefined) return selectMediaProtocol(provider);
+  const protocol = normalizeImageProtocol(entry.imageProtocol);
+  return protocol === 'auto' ? selectMediaProtocol(provider) : { mediaProtocol: protocol, protocolInferred: false };
+}
+
+/** 给已绑定图片模型的 Adapter/binding 投影协议，不改写账号默认值。 */
+export function providerForImageModel(provider, modelId) {
+  return { ...provider, ...selectImageProtocol(provider, modelId) };
+}
+
+export function unsupportedProtocolError(protocol, kind = 'media') {
+  const safeName = /^[a-z][a-z0-9-]{0,63}$/.test(String(protocol)) ? protocol : '(invalid)';
+  const error = new TypeError('iris: 不支持的 ' + (kind === 'vision' ? 'Vision' : 'Provider') + ' 协议：' + safeName);
+  error.code = kind === 'vision' ? 'IRIS_VISION_PROTOCOL_UNSUPPORTED' : 'IRIS_PROVIDER_PROTOCOL_UNSUPPORTED';
+  return error;
 }
 
 /** 返回官方 DashScope API 根；不满足边界时在 fetch 前拒绝。 */
@@ -23,3 +82,16 @@ export function dashscopeApiBase(baseUrl) {
   }
   return new URL('/api/v1', String(baseUrl).trim()).toString().replace(/\/$/, '');
 }
+
+/** 无认证模式不发送保留的旧凭据；未声明模式保持 bearer 兼容。 */
+export function providerApiKey(provider) {
+  return provider?.auth === 'none' ? '' : String(provider?.apiKey || '');
+}
+
+/** 配置管理与 headless 候选链共用可用性门，未声明 enabled 时默认启用。 */
+export function isConfiguredProvider(provider) {
+  return Boolean(provider && provider.enabled !== false
+    && typeof provider.id === 'string' && provider.id.trim()
+    && providerMediaBaseUrl(provider)
+    && (provider.auth === 'none' || (typeof provider.apiKey === 'string' && provider.apiKey.trim())));
+}