@mokuyoaxis/dsh-iris 0.1.4 → 0.2.0

package/lib/command-service.js

@@ -0,0 +1,420 @@
+'use strict';
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  createCoreArtifact,
+  exportCoreArtifact,
+  inspectCoreArtifact,
+  listCoreArtifacts,
+  readCoreArtifactBytes,
+  rebuildCoreArtifactIndex
+} from './core-artifacts.js';
+import { inspectCoreTask, listCoreTasks } from './core-tasks.js';
+import { cropImage, pixelDiff, PixelError } from './pixels.js';
+import { extractFrames, normalizeFramesOptions, probeVideo } from './media-probe.js';
+import { hasProviderOperation } from './provider-adapter.js';
+import { createProviderTaskRunner } from './provider-task-runner.js';
+import { GenerationInputError, normalizeGenerationInput } from './generation-input.js';
+
+export const COMMAND_CONTRACT_VERSION = 0;
+export const CORE_COMMANDS = Object.freeze([
+  'crop', 'media.diff', 'media.frames', 'task.inspect', 'task.list', 'task.observe', 'task.reobserve', 'task.redeliver', 'task.cancel', 'task.retry',
+  'artifact.inspect', 'artifact.list', 'artifact.export', 'artifact.rebuild'
+]);
+
+export class CommandError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'CommandError';
+    this.code = code;
+  }
+}
+
+function commandError(code, message) {
+  return new CommandError(code, message);
+}
+
+function plain(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function exactInput(input, allowed) {
+  if (!plain(input)) throw commandError('IRIS_COMMAND_INPUT_INVALID', 'Command 输入必须是 JSON 对象');
+  for (const key of Object.keys(input)) {
+    if (!allowed.includes(key)) throw commandError('IRIS_COMMAND_INPUT_INVALID', `Command 不支持输入字段：${key}`);
+  }
+}
+
+function localFile(value, field, label) {
+  const supplied = String(value || '').trim();
+  if (!supplied || !path.isAbsolute(supplied)) {
+    throw commandError('IRIS_COMMAND_INPUT_INVALID', field + ' 必须是宿主可读的绝对路径');
+  }
+  try {
+    const resolved = fs.realpathSync.native(supplied);
+    if (!fs.statSync(resolved).isFile()) throw new Error('not file');
+    return resolved;
+  } catch (_) {
+    throw commandError('IRIS_COMMAND_INPUT_INVALID', label + '不存在或不是普通文件');
+  }
+}
+
+function localImage(input) {
+  return localFile(input.image_path, 'image_path', '图片');
+}
+
+function coordinates(input) {
+  const values = {};
+  for (const name of ['left', 'top', 'width', 'height']) {
+    if (typeof input[name] !== 'number' || !Number.isFinite(input[name])) {
+      throw commandError('IRIS_COMMAND_INPUT_INVALID', `${name} 必须是有限数字`);
+    }
+    values[name] = input[name];
+  }
+  return values;
+}
+
+function abortError() {
+  const error = new Error('Core Command 已取消');
+  error.name = 'AbortError';
+  return error;
+}
+
+export function createCommandService(runtime, ports = {}) {
+  if (!runtime || typeof runtime.run !== 'function') throw new TypeError('Command Service 需要 Core Runtime');
+
+  async function execute(name, input) {
+    if (!CORE_COMMANDS.includes(name)) throw commandError('IRIS_COMMAND_UNKNOWN', `未知 Command：${String(name)}`);
+    if (name === 'crop') {
+      exactInput(input, ['image_path', 'artifact_id', 'left', 'top', 'width', 'height']);
+      const hasPath = Boolean(String(input.image_path || '').trim());
+      const hasArtifact = Boolean(String(input.artifact_id || '').trim());
+      if (hasPath === hasArtifact) {
+        throw commandError('IRIS_COMMAND_INPUT_INVALID', 'crop 必须且只能提供 image_path 或 artifact_id 之一');
+      }
+      const localPath = hasPath ? localImage(input) : null;
+      const region = coordinates(input);
+      return runtime.run('execute', async ({ dataRoot, signal }) => {
+        if (signal.aborted) throw abortError();
+        const source = hasArtifact ? readCoreArtifactBytes(dataRoot, input.artifact_id) : null;
+        const image = source ? source.bytes : localPath;
+        let cropped;
+        try { cropped = await cropImage({ input: image, ...region }); }
+        catch (error) {
+          if (error instanceof PixelError) throw commandError('IRIS_COMMAND_INPUT_INVALID', error.message);
+          throw commandError('IRIS_COMMAND_PROCESSING_FAILED', '图片无法裁剪；请确认格式受支持且文件可读取');
+        }
+        if (signal.aborted) throw abortError();
+        const artifact = createCoreArtifact(dataRoot, {
+          bytes: cropped.buffer,
+          mediaType: cropped.mime,
+          kind: 'crop',
+          metadata: { width: cropped.width, height: cropped.height },
+          relations: source ? [{ type: 'derived-from', artifactId: source.artifact.id }] : []
+        });
+        return Object.freeze({
+          contractVersion: COMMAND_CONTRACT_VERSION,
+          command: 'crop',
+          artifact
+        });
+      });
+    }
+    if (name === 'media.diff') {
+      exactInput(input, [
+        'image_a_path', 'image_a_artifact_id', 'image_b_path', 'image_b_artifact_id',
+        'grid', 'top_regions'
+      ]);
+      const aPathSupplied = Boolean(String(input.image_a_path || '').trim());
+      const aArtifactSupplied = Boolean(String(input.image_a_artifact_id || '').trim());
+      const bPathSupplied = Boolean(String(input.image_b_path || '').trim());
+      const bArtifactSupplied = Boolean(String(input.image_b_artifact_id || '').trim());
+      if (aPathSupplied === aArtifactSupplied || bPathSupplied === bArtifactSupplied) {
+        throw commandError('IRIS_COMMAND_INPUT_INVALID',
+          'media.diff 的 A/B 两侧都必须且只能提供本地路径或 Artifact ID 之一');
+      }
+      const imageAPath = aPathSupplied
+        ? localFile(input.image_a_path, 'image_a_path', '图片 A') : null;
+      const imageBPath = bPathSupplied
+        ? localFile(input.image_b_path, 'image_b_path', '图片 B') : null;
+      const grid = input.grid === undefined ? 8 : Number(input.grid);
+      const topRegions = input.top_regions === undefined ? 3 : Number(input.top_regions);
+      if (!Number.isSafeInteger(grid) || grid < 1 || grid > 64
+          || !Number.isSafeInteger(topRegions) || topRegions < 1 || topRegions > 100) {
+        throw commandError('IRIS_COMMAND_INPUT_INVALID',
+          'grid 必须是 1–64 的整数，top_regions 必须是 1–100 的整数');
+      }
+      return runtime.run('execute', async ({ dataRoot, signal }) => {
+        if (signal.aborted) throw abortError();
+        const sourceA = aArtifactSupplied
+          ? readCoreArtifactBytes(dataRoot, input.image_a_artifact_id) : null;
+        const sourceB = bArtifactSupplied
+          ? readCoreArtifactBytes(dataRoot, input.image_b_artifact_id) : null;
+        for (const source of [sourceA, sourceB]) {
+          if (source && !source.artifact.mediaType.startsWith('image/')) {
+            throw commandError('IRIS_COMMAND_INPUT_INVALID', 'media.diff 的 Artifact 输入必须是图片');
+          }
+        }
+        let diff;
+        try {
+          diff = await pixelDiff({
+            inputA: sourceA ? sourceA.bytes : imageAPath,
+            inputB: sourceB ? sourceB.bytes : imageBPath,
+            grid,
+            topRegions
+          });
+        } catch (error) {
+          if (signal.aborted) throw abortError();
+          if (error instanceof PixelError) {
+            throw commandError('IRIS_COMMAND_INPUT_INVALID', error.message);
+          }
+          throw commandError('IRIS_COMMAND_PROCESSING_FAILED',
+            '图片差异分析失败；请确认格式受支持且文件可读取');
+        }
+        if (signal.aborted) throw abortError();
+        const sourceIds = [...new Set([sourceA?.artifact.id, sourceB?.artifact.id].filter(Boolean))];
+        const metrics = Object.freeze({
+          ratio: diff.ratio,
+          diffPixels: diff.diffPixels,
+          totalPixels: diff.totalPixels,
+          width: diff.width,
+          height: diff.height,
+          worstRegions: Object.freeze(diff.worstRegions.map((region) => Object.freeze({ ...region })))
+        });
+        const artifact = createCoreArtifact(dataRoot, {
+          bytes: diff.heatmap,
+          mediaType: diff.mime,
+          kind: 'pixel-diff',
+          metadata: { ...metrics, worstRegions: diff.worstRegions },
+          relations: sourceIds.map((artifactId) => ({ type: 'derived-from', artifactId }))
+        });
+        return Object.freeze({
+          contractVersion: COMMAND_CONTRACT_VERSION,
+          command: name,
+          metrics,
+          artifact
+        });
+      });
+    }
+    if (name === 'media.frames') {
+      exactInput(input, ['video_path', 'artifact_id', 'max_frames', 'target_width', 'quality', 'format']);
+      const hasPath = Boolean(String(input.video_path || '').trim());
+      const hasArtifact = Boolean(String(input.artifact_id || '').trim());
+      if (hasPath === hasArtifact) {
+        throw commandError('IRIS_COMMAND_INPUT_INVALID',
+          'media.frames 必须且只能提供 video_path 或 artifact_id 之一');
+      }
+      const videoPath = hasPath ? localFile(input.video_path, 'video_path', '视频') : null;
+      let frameOptions;
+      try {
+        frameOptions = normalizeFramesOptions({
+          ...(input.max_frames !== undefined ? { maxFrames: input.max_frames } : {}),
+          ...(input.target_width !== undefined ? { targetWidth: input.target_width } : {}),
+          ...(input.quality !== undefined ? { quality: input.quality } : {}),
+          ...(input.format !== undefined ? { format: input.format } : {})
+        });
+      } catch (error) {
+        throw commandError('IRIS_COMMAND_INPUT_INVALID', error.message);
+      }
+      return runtime.run('execute', async ({ dataRoot, signal }) => {
+        if (signal.aborted) throw abortError();
+        const source = hasArtifact ? readCoreArtifactBytes(dataRoot, input.artifact_id) : null;
+        if (source && !source.artifact.mediaType.startsWith('video/')) {
+          throw commandError('IRIS_COMMAND_INPUT_INVALID', 'media.frames 的 Artifact 输入必须是视频');
+        }
+        let temporaryDirectory;
+        let readablePath = videoPath;
+        if (source) {
+          try {
+            temporaryDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'iris-command-frames-'));
+            readablePath = path.join(temporaryDirectory, 'source.mp4');
+            fs.writeFileSync(readablePath, source.bytes, { mode: 0o600 });
+          } catch (_) {
+            if (temporaryDirectory) {
+              try { fs.rmSync(temporaryDirectory, { recursive: true, force: true }); } catch (_) { /* 临时副本 */ }
+            }
+            throw commandError('IRIS_COMMAND_PROCESSING_FAILED', '视频临时副本无法安全写入');
+          }
+        }
+        let media;
+        let frames;
+        try {
+          media = probeVideo(readablePath);
+          frames = await extractFrames({ inputPath: readablePath, ...frameOptions, signal });
+        } catch (error) {
+          if (signal.aborted) throw abortError();
+          throw commandError('IRIS_COMMAND_PROCESSING_FAILED',
+            '视频抽帧失败；请确认 ffmpeg 可用且文件格式受支持');
+        } finally {
+          if (temporaryDirectory) {
+            try { fs.rmSync(temporaryDirectory, { recursive: true, force: true }); } catch (_) { /* 临时副本 */ }
+          }
+        }
+        if (signal.aborted) throw abortError();
+        const relations = source ? [{ type: 'frame-of', artifactId: source.artifact.id }] : [];
+        const mediaType = frameOptions.format === 'png' ? 'image/png' : 'image/jpeg';
+        const artifacts = frames.map((frame, index) => createCoreArtifact(dataRoot, {
+          bytes: frame.buffer,
+          mediaType,
+          kind: 'video-frame',
+          metadata: {
+            frameIndex: index + 1,
+            atSec: frame.atSec,
+            width: frame.width,
+            height: frame.height
+          },
+          relations
+        }));
+        return Object.freeze({
+          contractVersion: COMMAND_CONTRACT_VERSION,
+          command: name,
+          media: Object.freeze({ ...media }),
+          artifacts: Object.freeze(artifacts)
+        });
+      });
+    }
+    // task.reobserve 是人工触发观察的对外命令名（DSH API/工作台），与 task.observe
+    // 共用同一份门与单步 poll 实现；语义不区分，绝不 submit。
+    if (name === 'task.observe' || name === 'task.reobserve') {
+      exactInput(input, ['task_id']);
+      return runtime.run('execute', async ({ dataRoot }) => {
+        const before = inspectCoreTask(dataRoot, input.task_id);
+        if (before.acceptance !== 'accepted' || !before.remoteTaskId || !['none', 'unknown'].includes(before.outcome)) throw commandError('IRIS_TASK_NOT_OBSERVABLE', 'Task 没有可观察的远端受理事实，或已终止；不会重新提交');
+        if (typeof ports.resolveTaskAdapter !== 'function') throw commandError('IRIS_COMMAND_PROVIDER_REQUIRED', 'task.observe 需要宿主显式提供 Task Provider resolver');
+        const adapter = await ports.resolveTaskAdapter(before);
+        if (!adapter || adapter.id !== before.providerId || !adapter.capabilities?.includes(before.capability)) throw commandError('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Task Provider resolver 返回了不匹配的 Adapter');
+        if (!hasProviderOperation(adapter, 'poll')) throw commandError('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', 'Task 原 Provider 不支持 poll；不会重新提交');
+        const task = await createProviderTaskRunner(runtime).observe(input.task_id, adapter, { resumeActive: true });
+        return Object.freeze({ contractVersion: COMMAND_CONTRACT_VERSION, command: name, taskId: task.id, task });
+      });
+    }
+    // task.redeliver：只对 outcome=succeeded / deliveryState=failed 的任务重新取回
+    // 已生成的远端产物（re-poll 拿产物清单，绝不 submit，也不会重新生成）。
+    if (name === 'task.redeliver') {
+      exactInput(input, ['task_id']);
+      return runtime.run('execute', async ({ dataRoot }) => {
+        const before = inspectCoreTask(dataRoot, input.task_id);
+        if (before.outcome !== 'succeeded' || before.deliveryState !== 'failed' || !before.remoteTaskId) throw commandError('IRIS_TASK_NOT_REDELIVERABLE', 'Task 不处于可重新交付状态；不会重新生成');
+        if (typeof ports.resolveTaskAdapter !== 'function') throw commandError('IRIS_COMMAND_PROVIDER_REQUIRED', 'task.redeliver 需要宿主显式提供 Task Provider resolver');
+        const adapter = await ports.resolveTaskAdapter(before);
+        if (!adapter || adapter.id !== before.providerId || !adapter.capabilities?.includes(before.capability)) throw commandError('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Task Provider resolver 返回了不匹配的 Adapter');
+        if (!hasProviderOperation(adapter, 'poll')) throw commandError('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', 'Task 原 Provider 不支持 poll；不会重新生成');
+        const task = await createProviderTaskRunner(runtime).redeliver(input.task_id, adapter);
+        return Object.freeze({ contractVersion: COMMAND_CONTRACT_VERSION, command: name, taskId: task.id, task });
+      });
+    }
+    // task.cancel：只对已受理、有远端 ID、结果未定论且非终态的任务开放。
+    // 只有 Provider 明确确认才写 outcome=canceled；不支持或无法确认时保持真实状态。
+    if (name === 'task.cancel') {
+      exactInput(input, ['task_id']);
+      return runtime.run('execute', async ({ dataRoot }) => {
+        const before = inspectCoreTask(dataRoot, input.task_id);
+        if (before.acceptance !== 'accepted' || !before.remoteTaskId
+            || !['none', 'unknown'].includes(before.outcome) || before.phase === 'terminal') {
+          throw commandError('IRIS_TASK_NOT_CANCELABLE', 'Task 缺少可取消的远端受理事实，或已终止');
+        }
+        if (before.cancelState !== 'none') {
+          throw commandError('IRIS_TASK_CANCEL_ALREADY_REQUESTED', '该 Task 已请求过取消；请显式重新观察以确认远端真实状态');
+        }
+        if (typeof ports.resolveTaskAdapter !== 'function') throw commandError('IRIS_COMMAND_PROVIDER_REQUIRED', 'task.cancel 需要宿主显式提供 Task Provider resolver');
+        const adapter = await ports.resolveTaskAdapter(before);
+        if (!adapter || adapter.id !== before.providerId || !adapter.capabilities?.includes(before.capability)) throw commandError('IRIS_PROVIDER_TASK_IDENTITY_MISMATCH', 'Task Provider resolver 返回了不匹配的 Adapter');
+        const task = await createProviderTaskRunner(runtime).cancel(input.task_id, adapter);
+        return Object.freeze({ contractVersion: COMMAND_CONTRACT_VERSION, command: name, taskId: task.id, task });
+      });
+    }
+    // task.retry：D4 重试为新任务。产生新的真实计费，必须显式 confirm_billing；
+    // 只对终态且未成功交付的 Task 开放；新 Task 有全新 id/attempts/binding 并记录
+    // 单向 retriedFrom 关系，旧 Task 不动；Core 不持久化 Prompt，prompt 必须由
+    // 调用方重新提供（绝不从旧记录"恢复"）。
+    if (name === 'task.retry') {
+      exactInput(input, ['task_id', 'provider_input', 'model_ref', 'confirm_billing']);
+      if (input.confirm_billing !== true) {
+        throw commandError('IRIS_COMMAND_BILLING_CONFIRM_REQUIRED', '重试会创建新任务并可能产生重复生成费用；必须显式确认计费');
+      }
+      return runtime.run('execute', async ({ dataRoot }) => {
+        const before = inspectCoreTask(dataRoot, input.task_id);
+        if (before.phase !== 'terminal' || (before.outcome === 'succeeded' && before.deliveryState === 'ready')) {
+          throw commandError('IRIS_TASK_NOT_RETRYABLE', '只有终态且未成功交付的 Task 可以重试为新任务');
+        }
+        let normalized;
+        try { normalized = normalizeGenerationInput(before.capability, input.provider_input); }
+        catch (error) {
+          if (error instanceof GenerationInputError) throw commandError('IRIS_COMMAND_INPUT_INVALID', error.message);
+          throw error;
+        }
+        const providerInput = normalized.providerInput;
+        if (Object.hasOwn(input.provider_input, 'model_ref')) {
+          throw commandError('IRIS_COMMAND_INPUT_INVALID', 'retry 的模型覆盖请使用外层 model_ref');
+        }
+        const modelRef = String(input.model_ref || '').trim();
+        if (input.model_ref !== undefined && !modelRef) throw commandError('IRIS_COMMAND_INPUT_INVALID', 'model_ref 必须是 providerId::modelId 复合引用');
+        if (typeof ports.resolveTaskCandidates !== 'function') throw commandError('IRIS_COMMAND_PROVIDER_REQUIRED', 'task.retry 需要宿主显式提供候选链 resolver');
+        const candidates = await ports.resolveTaskCandidates({ capability: before.capability, modelRef });
+        const result = await createProviderTaskRunner(runtime).submit({
+          capability: before.capability,
+          candidates,
+          providerInput,
+          retriedFrom: before.id
+        });
+        return Object.freeze({
+          contractVersion: COMMAND_CONTRACT_VERSION,
+          command: name,
+          taskId: result.taskId,
+          retriedFrom: before.id,
+          task: result.task,
+          ...(result.localError ? { localError: result.localError } : {})
+        });
+      });
+    }
+    if (name === 'task.inspect') {
+      exactInput(input, ['task_id']);
+      return runtime.run('inspect', ({ dataRoot }) => Object.freeze({
+        contractVersion: COMMAND_CONTRACT_VERSION,
+        command: name,
+        task: inspectCoreTask(dataRoot, input.task_id)
+      }));
+    }
+    if (name === 'task.list') {
+      exactInput(input, ['offset', 'limit']);
+      return runtime.run('inspect', ({ dataRoot }) => Object.freeze({
+        contractVersion: COMMAND_CONTRACT_VERSION,
+        command: name,
+        ...listCoreTasks(dataRoot, input)
+      }));
+    }
+    if (name === 'artifact.inspect') {
+      exactInput(input, ['artifact_id']);
+      return runtime.run('inspect', ({ dataRoot }) => Object.freeze({
+        contractVersion: COMMAND_CONTRACT_VERSION,
+        command: name,
+        artifact: inspectCoreArtifact(dataRoot, input.artifact_id)
+      }));
+    }
+    if (name === 'artifact.list') {
+      exactInput(input, ['offset', 'limit']);
+      return runtime.run('inspect', ({ dataRoot }) => Object.freeze({
+        contractVersion: COMMAND_CONTRACT_VERSION,
+        command: name,
+        ...listCoreArtifacts(dataRoot, input)
+      }));
+    }
+    if (name === 'artifact.rebuild') {
+      exactInput(input, []);
+      return runtime.run('recover', ({ dataRoot }) => Object.freeze({
+        contractVersion: COMMAND_CONTRACT_VERSION,
+        command: name,
+        ...rebuildCoreArtifactIndex(dataRoot)
+      }));
+    }
+    exactInput(input, ['artifact_id', 'output_path']);
+    return runtime.run('execute', ({ dataRoot }) => Object.freeze({
+      contractVersion: COMMAND_CONTRACT_VERSION,
+      command: name,
+      ...exportCoreArtifact(dataRoot, input.artifact_id, input.output_path)
+    }));
+  }
+
+  return Object.freeze({ contractVersion: COMMAND_CONTRACT_VERSION, commands: CORE_COMMANDS, execute });
+}

package/lib/config.js

@@ -10,7 +10,7 @@ import os from 'node:os';
 import * as cap from './capability.js';
 import * as models from './models.js';
 import { atomicWritePrivate, chmodPrivateFile, privateSibling } from './private-storage.js';
-import { inferMediaProtocol } from './provider-protocol.js';
+import { selectMediaProtocol, isConfiguredProvider } from './provider-protocol.js';
 import { redactProviderMessage } from './provider-contract.js';
 import {
   PROVIDER_HEALTH_FRESH_MS,
@@ -32,6 +32,7 @@ function validateStoredConfig(value) {
     if (!isPlainObject(provider)) throw new Error('provider 条目必须是对象');
     if (provider.id !== undefined && typeof provider.id !== 'string') throw new Error('provider.id 必须是字符串');
     if (provider.baseUrl !== undefined && typeof provider.baseUrl !== 'string') throw new Error('provider.baseUrl 必须是字符串');
+    if (provider.mediaBaseUrl !== undefined && typeof provider.mediaBaseUrl !== 'string') throw new Error('provider.mediaBaseUrl 必须是字符串');
     if (provider.apiKey !== undefined && typeof provider.apiKey !== 'string') throw new Error('provider.apiKey 必须是字符串');
     if (provider.models !== undefined && !Array.isArray(provider.models)) throw new Error('provider.models 必须是数组');
     for (const model of provider.models || []) {
@@ -43,10 +44,27 @@ function validateStoredConfig(value) {
   }
 }
 
+/**
+ * 供应商认证方式：'bearer'（默认，需要 apiKey）或 'none'（本地/内网无鉴权端点）。
+ * T-01：解除 ComfyUI、Ollama、本地 TTS 等本地部署的硬编码阻塞（审计 C-1）。
+ * 无 auth 字段时一律视为 'bearer'——现有用户行为完全不变。
+ */
+function authModeOf(provider) {
+  return provider && provider.auth === 'none' ? 'none' : 'bearer';
+}
+
+/** 该供应商是否缺少必需凭据（'none' 认证永不缺）。 */
+function missingCredentials(provider) {
+  if (!provider || authModeOf(provider) === 'none') return false;
+  return typeof provider.apiKey !== 'string' || !provider.apiKey.trim();
+}
+
 function normalizeStoredProvider(provider) {
-  if (provider.mediaProtocol === 'dashscope' || provider.mediaProtocol === 'openai-images') return false;
-  provider.mediaProtocol = inferMediaProtocol(provider.baseUrl);
-  return true;
+  const selected = selectMediaProtocol(provider);
+  const changed = provider.mediaProtocol !== selected.mediaProtocol
+    || (provider.protocolInferred === true) !== selected.protocolInferred;
+  Object.assign(provider, selected);
+  return models.migrateProviderModels(provider) || changed;
 }
 
 export function irisHome() {
@@ -134,15 +152,17 @@ export function importFromWorkbench(workbenchConfigPath) {
   for (const p of list) {
     if (!p || typeof p.apiKey !== 'string' || !p.apiKey.trim() ||
         typeof p.baseUrl !== 'string' || !p.baseUrl.trim()) continue;
-    c.providers.push({
+    const imported = {
       id: 'iris_' + Math.random().toString(36).slice(2, 8),
       name: p.name || p.id,
-      type: p.type === 'anthropic' ? 'anthropic' : 'openai',
+      type: typeof p.type === 'string' && p.type.trim() ? p.type.trim() : 'openai',
       baseUrl: p.baseUrl,
       apiKey: p.apiKey,
       enabled: p.enabled !== false,
-      mediaProtocol: inferMediaProtocol(p.baseUrl)
-    });
+      mediaProtocol: p.mediaProtocol
+    };
+    normalizeStoredProvider(imported);
+    c.providers.push(imported);
     n++;
   }
   if (n) persist();
@@ -150,7 +170,7 @@ export function importFromWorkbench(workbenchConfigPath) {
 }
 
 export function providers() {
-  return load().providers.filter((p) => p.enabled && p.apiKey);
+  return load().providers.filter(isConfiguredProvider);
 }
 
 export function providerById(id) {
@@ -189,16 +209,7 @@ export function pickFor(capability) {
  */
 export function pickAllFor(capability) {
   const pool = models.modelPool(providers());
-  const chosen = [];
-  const seen = new Set();
-  const add = (m) => {
-    const k = m.providerId + '\u0000' + m.id;
-    if (!seen.has(k)) { seen.add(k); chosen.push(m); }
-  };
-  for (const ref of assignmentOrder(capability)) {
-    for (const m of pool) if (m.ref === ref && m.capabilities.includes(capability)) add(m);
-  }
-  for (const m of pool) if (m.capabilities.includes(capability)) add(m);
+  const chosen = models.orderedModels(pool, capability, assignments()[capability]);
   const out = [];
   for (const m of chosen) {
     const p = providerById(m.providerId);
@@ -214,21 +225,7 @@ export function assignments() {
   return load().assignments || {};
 }
 
-function resolveAssignment(pool, raw, capability) {
-  let providerId = '';
-  let modelId = '';
-  if (raw && typeof raw === 'object') {
-    providerId = String(raw.providerId || '');
-    modelId = String(raw.modelId || raw.id || '');
-  } else if (typeof raw === 'string') {
-    const parsed = models.parseModelRef(raw);
-    if (parsed) ({ providerId, modelId } = parsed);
-    else modelId = raw; // v1 旧格式：纯 model id，按池顺序取第一个
-  }
-  return pool.find((m) => m.id === modelId
-    && (!providerId || m.providerId === providerId)
-    && m.capabilities.includes(capability)) || null;
-}
+const resolveAssignment = models.resolvePoolModel;
 
 /** 归一化某能力的有序分配列表 → [providerId::modelId, ...]。 */
 export function assignmentOrder(capability) {
@@ -302,7 +299,7 @@ export function capabilitiesOf(p) {
 }
 
 const HEALTH_SENSITIVE_FIELDS = new Set([
-  'type', 'baseUrl', 'apiKey', 'mediaProtocol',
+  'auth', 'type', 'baseUrl', 'mediaBaseUrl', 'apiKey', 'mediaProtocol',
   'imageModel', 'videoModel', 'ttsModel', 'transcribeModel', 'visionModel'
 ]);
 
@@ -411,7 +408,7 @@ export function recordProviderHealth(id, modelId, capability, result) {
 /** 返回单个 Provider × Model × Capability 的安全状态。 */
 export function modelHealth(id, modelId, capability, { now = Date.now() } = {}) {
   const provider = load().providers.find((item) => item.id === id);
-  if (!provider || provider.enabled === false || !provider.apiKey) return { status: 'unconfigured' };
+  if (!provider || provider.enabled === false || missingCredentials(provider)) return { status: 'unconfigured' };
   const observation = healthObservation(provider, modelId, capability);
   const status = healthObservationState(observation, { now });
   const evidence = status === 'verified'
@@ -467,8 +464,8 @@ export function upsert(provider) {
     const i = c.providers.findIndex((p) => p.id === id);
     if (i >= 0) {
       const previous = c.providers[i];
-      if (rest.mediaProtocol === 'auto') rest.mediaProtocol = inferMediaProtocol(rest.baseUrl ?? previous.baseUrl);
       const next = { ...previous, ...rest };
+      if (Object.prototype.hasOwnProperty.call(rest, 'mediaProtocol')) next.protocolInferred = false;
       normalizeStoredProvider(next);
       resetHealthOnCriticalChange(previous, next, rest);
       if (Object.prototype.hasOwnProperty.call(rest, 'models')) pruneHealthToEffectiveModels(next);
@@ -478,7 +475,7 @@ export function upsert(provider) {
     }
   }
   const fresh = { id: 'iris_' + Math.random().toString(36).slice(2, 8), ...rest };
-  if (fresh.mediaProtocol === 'auto') delete fresh.mediaProtocol;
+  fresh.protocolInferred = false;
   normalizeStoredProvider(fresh);
   c.providers.push(fresh);
   persist();
@@ -500,21 +497,22 @@ export function removeProvider(id) {
   return true;
 }
 
-/** 设置一个供应商的模型池（覆盖显式 models 数组；空数组 = 回退到自动发现/旧字段） */
+/** 显式替换模型池；空数组表示没有可用模型。发现使用合并入口。 */
 export function setProviderModels(id, modelEntries) {
   const c = load();
   const p = c.providers.find((x) => x.id === id);
   if (!p) return null;
   if (Array.isArray(modelEntries)) {
-    // 保留同名模型已有的 verified/source（重新发现不丢实测结果）
-    const prev = {};
-    for (const m of p.models || []) if (m && m.id) prev[m.id] = m;
+    // 保留同名模型的实测结果；手工能力标注优先于后续自动发现。
+    const prev = new Map();
+    for (const m of p.models || []) if (m && m.id) prev.set(m.id, m);
     p.models = modelEntries.map((m) => {
       const entry = typeof m === 'string' ? { id: m } : { id: m.id, capabilities: m.capabilities };
-      const old = prev[entry.id];
+      const old = prev.get(entry.id);
       if (old) {
         if (old.verified) entry.verified = old.verified;
         if (old.source) entry.source = old.source;
+        if (old.source === 'manual' && Array.isArray(old.capabilities)) entry.capabilities = old.capabilities;
       }
       if (m && m.verified) entry.verified = m.verified;
       if (m && m.source) entry.source = m.source;
@@ -526,6 +524,19 @@ export function setProviderModels(id, modelEntries) {
   return p;
 }
 
+/** 发现只追加或更新；用户手工项和未再返回的旧项始终保留。 */
+export function mergeDiscoveredModels(id, modelEntries) {
+  const provider = load().providers.find((p) => p.id === id);
+  if (!provider) return null;
+  const merged = new Map(models.providerModels(provider).map((m) => [m.id, m]));
+  for (const model of modelEntries) {
+    const previous = merged.get(model.id);
+    if (previous?.source === 'manual') continue;
+    merged.set(model.id, { ...previous, ...model, source: 'discovered' });
+  }
+  return setProviderModels(id, [...merged.values()]);
+}
+
 /** 找 provider 里的某个模型条目（可变引用） */
 function findModelEntry(p, modelId) {
   return (p.models || []).find((m) => m && m.id === modelId);
@@ -546,6 +557,7 @@ export function addProviderModel(id, modelId, capabilities) {
   } else if (Array.isArray(capabilities)) {
     entry.capabilities = capabilities;
   }
+  entry.source = 'manual';
   pruneHealthToEffectiveModels(p);
   persist();
   return entry;
@@ -573,6 +585,7 @@ export function setModelCapabilities(id, modelId, capabilities) {
   if (!entry) return false;
   const nextCapabilities = (Array.isArray(capabilities) ? capabilities : []).filter((x) => cap.isKnownCapability(x));
   entry.capabilities = nextCapabilities;
+  entry.source = 'manual';
   pruneHealthToEffectiveModels(p);
   persist();
   return true;