@mokuyoaxis/dsh-iris 0.2.3 → 0.2.4

package/lib/index.js

@@ -309,6 +309,30 @@ export async function apply(ctx) {
     return { blocks };
   }
 
+  safeRegister(host, {
+    name: 'iris_import_image',
+    description: 'Save a local image or a current-session image attachment as a persistent Iris image Artifact for later viewing, editing and export. Provide exactly one of image_path or attachment_id. Supports static PNG/JPEG/WebP up to 20 MiB, preserves the source, and never calls a model.',
+    parameters: {
+      type: 'object',
+      properties: {
+        image_path: { type: 'string', description: 'Absolute path to an image readable by the DSH host' },
+        attachment_id: { type: 'string', description: 'Image attachment from the current session, alternative to image_path' }
+      },
+      required: []
+    },
+    output: { schema: { type: 'object' }, render: (_args, value) => value.blocks },
+    isConcurrencySafe: () => true,
+    async execute(args, exec = {}) {
+      const imagePath = String(args.image_path || '').trim();
+      const attachmentId = String(args.attachment_id || '').trim();
+      if (Boolean(imagePath) === Boolean(attachmentId)) throw new Error('图片导入须选择image_path或attachment_id之一');
+      const input = imagePath ? { image_path: imagePath } : {
+        image_bytes: (await resolveVisionImageInput(dshHost(ctx), exec, { attachment_id: attachmentId }, exec.signal)).bytes
+      };
+      return runAction(dshHost(ctx), 'image_import', input, { signal: exec.signal });
+    }
+  });
+
   /* ---------- 🖼️ 画图 ---------- */
   safeRegister(host, {
     name: 'iris_draw_image',
@@ -321,7 +345,7 @@ export async function apply(ctx) {
         prompt: { type: 'string', description: 'Detailed visual description of the image to create' },
         size: { type: 'string', description: "Output size; DashScope uses 'W*H' (e.g. '1024*1024'), OpenAI uses 'WxH'. Default provider default." },
         n: { type: 'string', description: "Number of images, default '1'" },
-        model: { type: 'string', description: 'Override with a providerId::modelId reference (legacy bare model id also accepted)' }
+        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id also accepted)' }
       },
       required: ['prompt']
     },
@@ -383,12 +407,12 @@ export async function apply(ctx) {
 
   safeRegister(host, {
     name: 'iris_edit_image',
-    description: 'Edit an existing Core image by Artifact ID and an instruction using a configured openai-chat-images model. Returns new Core Artifacts and DSH image attachments; preserves the source image and records its provenance.',
+    description: 'Edit an existing Core image by Artifact ID and an instruction using an assigned chat-image model or native DashScope Qwen edit model. Returns new Core Artifacts and DSH image attachments; preserves the source image and records its provenance.',
     parameters: {
       type: 'object', properties: {
         source_artifact_id: { type: 'string', description: 'Core Artifact ID of the source PNG, JPEG or WebP image (up to 20 MiB)' },
         prompt: { type: 'string', description: 'Describe the changes and what should be preserved in the source image' },
-        model: { type: 'string', description: 'Optional providerId::modelId; image protocol must be openai-chat-images' },
+        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item; supports openai-chat-images or DashScope Qwen edit/max/plus and 2.0/pro models' },
         n: { type: 'string', description: "Number of images, default '1'" }
       }, required: ['source_artifact_id', 'prompt']
     },
@@ -419,7 +443,7 @@ export async function apply(ctx) {
         resolution: { type: 'string', description: "s2v only: output tier '480P' (default) or '720P'" },
         size: { type: 'string', description: "t2v/i2v only: output size 'W*H', e.g. '1280*720' (default)" },
         duration: { type: 'number', description: 't2v/i2v only: duration in seconds, if the model supports it' },
-        model: { type: 'string', description: 'Override with a providerId::modelId reference (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id accepted)' }
       },
       required: []
     },
@@ -468,7 +492,7 @@ export async function apply(ctx) {
     description: 'Generate music using a model explicitly assigned to Music. Returns audio artifact IDs and playback links. Lyrics, vocals and duration are prompt intentions. Configured 502 retries may generate again.',
     parameters: { type: 'object', properties: {
       prompt: { type: 'string', description: 'Describe the music, including any lyrics, vocals, mood or intended duration' },
-      model: { type: 'string', description: 'Assigned providerId::modelId reference' },
+      model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item' },
       timeout_ms: { type: 'integer', description: 'Per-attempt timeout; default 300000 ms' },
       retry_502: { type: 'integer', description: '502 regeneration retries, 0–5; default 2; each retry consumes another request' },
       retry_delay_ms: { type: 'integer', description: 'Delay between 502 retries; default 5000 ms' }
@@ -491,7 +515,7 @@ export async function apply(ctx) {
       properties: {
         text: { type: 'string', description: 'Text to speak' },
         voice: { type: 'string', description: "Voice name, e.g. 'Cherry' (DashScope qwen-tts voices)" },
-        model: { type: 'string', description: 'Override with a providerId::modelId reference (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional assigned providerId::modelId; selects only this item (legacy bare model id accepted)' }
       },
       required: ['text']
     },
@@ -528,7 +552,7 @@ export async function apply(ctx) {
       type: 'object',
       properties: {
         audio_path: { type: 'string', description: 'Absolute path to the audio file (wav/mp3)' },
-        model: { type: 'string', description: 'Override with a providerId::modelId transcription reference (legacy bare model id accepted)' }
+        model: { type: 'string', description: 'Optional assigned transcription providerId::modelId; selects only this item (legacy bare model id accepted)' }
       },
       required: ['audio_path']
     },
@@ -640,7 +664,7 @@ export async function apply(ctx) {
         target_width: { type: 'integer', description: 'Frame width for sampling (default 640)' },
         transcribe: { type: 'boolean', description: 'Auto-transcribe the audio track for video_path (default true unless transcribe_text is provided). Existing frames only consume explicit text.' },
         transcribe_text: { type: 'string', description: 'Optional existing transcript text; does not create a transcription task' },
-        model: { type: 'string', description: 'Override the configured vision model id' }
+        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: []
     },
@@ -702,7 +726,7 @@ export async function apply(ctx) {
         name: `iris-sheet-${Date.now()}.png`
       });
       if (exec.signal?.aborted) throw exec.signal.reason;
-      const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 全局视觉模型';
+      const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 当前默认模型';
       return {
         frames: summaryFrameRecords(frames),
         blocks: [
@@ -731,7 +755,7 @@ export async function apply(ctx) {
         image_path: { type: 'string', description: 'Absolute path to the image file (png/jpg/jpeg/webp)' },
         artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path)' },
         question: { type: 'string', description: 'Question or extraction request about the image; defaults to a detailed description' },
-        model: { type: 'string', description: 'Override the configured vision model id (default qwen-vl-plus)' }
+        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: []
     },
@@ -769,7 +793,7 @@ export async function apply(ctx) {
       properties: {
         attachment_id: { type: 'string', description: 'The attachment_id of an image that appeared in this session or was generated by iris' },
         question: { type: 'string', description: 'New question about the image pixels' },
-        model: { type: 'string', description: 'Override the configured vision model id' }
+        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: ['attachment_id', 'question']
     },
@@ -934,7 +958,7 @@ export async function apply(ctx) {
         artifact_id: { type: 'string', description: 'Existing Core image Artifact ID in the current profile (alternative to image_path or attachment_id)' },
         attachment_id: { type: 'string', description: 'Session attachment id of an image (alternative to image_path)' },
         target: { type: 'string', description: 'The object or UI element to locate, e.g. "send button"' },
-        model: { type: 'string', description: 'Override the vision model for this locate call (e.g. qwen3-vl-235b-a22b-thinking for higher grounding precision; default is the provider visionModel, typically qwen-vl-plus)' }
+        model: { type: 'string', description: 'Optional item from the vision assignment list (providerId::modelId or host:current-vision); selects only this item' }
       },
       required: ['target']
     },
@@ -1041,7 +1065,7 @@ export async function apply(ctx) {
     }
   });
 
-  console.log('[iris] tools registered: iris_draw_image, iris_edit_image, iris_generate_video, iris_generate_music, iris_speak_text, iris_transcribe_audio, iris_task_status, iris_look_at_image, iris_relook_attachment, iris_crop, iris_pixel_diff, iris_locate, iris_html_screenshot, iris_long_ocr, iris_video_frames, iris_media_summarize');
+  console.log('[iris] tools registered: iris_import_image, iris_draw_image, iris_edit_image, iris_generate_video, iris_generate_music, iris_speak_text, iris_transcribe_audio, iris_task_status, iris_look_at_image, iris_relook_attachment, iris_crop, iris_pixel_diff, iris_locate, iris_html_screenshot, iris_long_ocr, iris_video_frames, iris_media_summarize');
 };
 
 /* ---------------- 视觉路由（M3 补全）：look/relook 共用执行器 + 降级链 ---------------- */
@@ -1151,7 +1175,7 @@ export async function sessionAttachmentRef(host, exec, attachmentId) {
 /**
  * 看图问答（阶段 1：VisionBackend 降级链）。
  * 只取声明/推断出 vision 能力的自持栈 provider（严格选择），按序组装后端链，
- * 全局视觉模型兜底；每个后端的失败现场保留在 errors 里。
+ * 仅使用视觉功能的明确分配；宿主默认模型也需显式加入，每个后端失败保留在errors里。
  * @returns {{answer:string,via:'selfstack'|'global',model?:string,backendId:string}}
  */
 export async function askVision(host, { question, dataUrl, image, prepareImage, signal, model, budget }) {
@@ -1174,6 +1198,6 @@ export async function runVisionTool(host, exec, { origin, model, question, dataU
     model
   });
   const label = origin === 'relook' ? '重看回答' : '看图回答';
-  const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 全局视觉模型';
+  const viaLabel = via === 'selfstack' ? 'iris 自持栈' : 'DSH 当前默认模型';
   return `[iris] ${label}（${usedModel || '默认'} · ${viaLabel}）：\n${answer}` + (artifactId ? `\nCore Artifact: ${artifactId}` : '');
 }

package/lib/models.js

@@ -26,6 +26,11 @@ export const CAP_FIELD = {
 
 const MODEL_REF_SEP = '::';
 
+/** Explicit host resource; never a Provider account or an implicit fallback. */
+export const HOST_VISION_REF = 'host:current-vision';
+export const HOST_VISION_MODEL = Object.freeze({ ref: HOST_VISION_REF, id: 'current-vision',
+  providerId: HOST_VISION_REF, capabilities: Object.freeze([CAPABILITIES.VISION]), source: 'host' });
+
 /** 稳定的模型复合引用；provider/model 分别编码，避免同名模型跨账号碰撞。 */
 export function modelRef(providerId, modelId) {
   return encodeURIComponent(String(providerId || '')) + MODEL_REF_SEP + encodeURIComponent(String(modelId || ''));
@@ -142,6 +147,7 @@ export function resolveModelRef(provider, capability, requested = '') {
 
 /** 共享旧分配对象、裸名称和复合引用的解析，池顺序决定同名匹配。 */
 export function resolvePoolModel(pool, raw, capability) {
+  if (raw === HOST_VISION_REF) return pool.find(m => m.ref === raw && m.capabilities.includes(capability)) || null;
   let providerId = '';
   let modelId = '';
   if (raw && typeof raw === 'object') {
@@ -156,7 +162,7 @@ export function resolvePoolModel(pool, raw, capability) {
     && m.capabilities.includes(capability)) || null;
 }
 
-/** DSH 与 CLI 共用的候选顺序：分配优先、按池顺序补齐并去重。 */
+/** DSH 与 CLI 共用的执行名单：只按明确分配排序并去重。 */
 export function orderedModels(pool, capability, assignments, { includeRateLimited = false } = {}) {
   const ordered = [];
   const seen = new Set();
@@ -170,7 +176,6 @@ export function orderedModels(pool, capability, assignments, { includeRateLimite
   for (const raw of (Array.isArray(assignments) ? assignments : (assignments ? [assignments] : []))) {
     add(resolvePoolModel(pool, raw, capability));
   }
-  if (capability !== CAPABILITIES.MUSIC) for (const model of pool) add(model);
   return ordered;
 }
 
@@ -192,9 +197,10 @@ export function selectionReasonForModel(pool, capability, assignments, modelOrRe
 }
 
 /** 全局模型池：合并所有 provider 的模型 */
-export function modelPool(providers) {
+export function modelPool(providers, { includeHostVision = false } = {}) {
   const pool = [];
   for (const p of providers || []) pool.push(...providerModels(p));
+  if (includeHostVision) pool.push(HOST_VISION_MODEL);
   return pool;
 }
 

package/lib/ocr-model-routing.js

@@ -12,6 +12,7 @@ export async function runOcrRequest(host, { providers = [], model, image, prepar
   const settings = normalizeOcrSettings({ chunkHeight, overlap, maxDimension, maxInvocations });
   const operation = createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: settings.maxInvocations } });
   try {
+    if (operation.signal.aborted) throw new ModelPortError('IRIS_MODEL_ABORTED');
     const inputs = new Map();
     const candidates = buildVisionModelCandidates(host, { providers, model, onRateLimit, prepareImages: true,
       prepareImageRequest: createVisionInputObserver(inputs) });

package/lib/provider-adapters.js

@@ -10,7 +10,7 @@ import * as defaultTransport from './adapters.js';
 import { ProviderContractError, providerErrorRecord } from './provider-contract.js';
 import { writePrivateFile } from './private-storage.js';
 import { defineProviderAdapter } from './provider-adapter.js';
-import { selectMediaProtocol, providerApiKey, providerMediaBaseUrl, unsupportedProtocolError } from './provider-protocol.js';
+import { selectMediaProtocol, providerApiKey, providerMediaBaseUrl, unsupportedProtocolError, supportsImageEdit } from './provider-protocol.js';
 import { modelRateLimit, reportModelRateLimit, isFreeQuotaExhausted } from './provider-health.js';
 import { prepareVisionImage, visionInputLimits } from './vision-image-input.js';
 
@@ -132,6 +132,15 @@ function operationsForDashScope(provider, transport) {
         ...(request.timeoutMs ? { timeoutMs: request.timeoutMs } : {})
       };
       if (request.capability === 'image') {
+        let image;
+        if (input.image) {
+          if (!supportsImageEdit('dashscope', request.model)) throw new ProviderContractError('该 DashScope 模型尚未接入原生改图', {
+            stage: 'validate', category: 'invalid_request', acceptance: 'not_accepted'
+          });
+          const limits = visionInputLimits(provider, request.model);
+          image = await prepareVisionImage(input.image, { ...limits, maxBytes: Math.min(limits.maxBytes, 10 * 1024 * 1024) },
+            { signal: request.signal, orient: true });
+        }
         if (transport.dashscopeImageMode(request.model) === 'legacy-async') {
           const remoteTaskId = await transport.submitImage({
             ...common, prompt: input.prompt, size: input.size, n: input.n
@@ -139,7 +148,7 @@ function operationsForDashScope(provider, transport) {
           return { kind: 'accepted', remoteTaskId };
         }
         const urls = await transport.generateImageMultimodal({
-          ...common, prompt: input.prompt, size: input.size, n: input.n
+          ...common, prompt: input.prompt, size: input.size, n: input.n, ...(image ? { image } : {})
         });
         return {
           kind: 'completed', value: { kind: 'urls', items: urls },

package/lib/provider-catalog.js

@@ -58,20 +58,19 @@ const CANDIDATE_CAP_LABEL = Object.freeze({
   [CAPABILITIES.MUSIC]: '音乐'
 });
 
-/** 与稳定配置层相同的“手工顺序优先、池序补齐”候选规则。 */
+/** 与 DSH 相同的严格功能名单；CLI 不附加宿主资源。 */
 function candidatesFromCatalog(catalog, requestedModelRef, capability) {
   const label = CANDIDATE_CAP_LABEL[capability];
   if (!label) fail('IRIS_PROVIDER_TASK_OBSERVE_UNSUPPORTED', '当前 Headless 候选链只开放图片、视频、语音与转写能力');
   const providers = catalog.providers.filter(isConfiguredProvider);
   const configuredPool = modelPool(providers).filter((item) => item.capabilities.includes(capability));
-  const pool = capability === CAPABILITIES.MUSIC
-    ? orderedModels(configuredPool, capability, catalog.assignments?.[capability], { includeRateLimited: true }) : configuredPool;
+  const pool = orderedModels(configuredPool, capability, catalog.assignments?.[capability], { includeRateLimited: true });
   const requested = String(requestedModelRef || '').trim();
   if (requested) {
     const parsed = parseModelRef(requested);
     if (!parsed && requested.includes('::')) fail('IRIS_PROVIDER_MODEL_INVALID', 'model_ref 格式无效');
     const exact = resolvePoolModel(pool, requested, capability);
-    if (!exact) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `指定模型不存在、未启用或没有${label}能力`);
+    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
       ? '指定模型正在限流冷却，请稍后使用或手动实测'
@@ -82,14 +81,13 @@ function candidatesFromCatalog(catalog, requestedModelRef, capability) {
     })]);
   }
   const assignment = catalog.assignments?.[capability];
-  const ordered = orderedModels(pool, capability, assignment);
-  if (!ordered.length) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', capability === CAPABILITIES.MUSIC
-    ? '请先给 Music 功能分配可用音乐模型' : `provider-config 中没有可用${label}模型`);
+  const ordered = pool.filter(model => !model.rateLimited);
+  if (!ordered.length) fail('IRIS_PROVIDER_MODEL_UNAVAILABLE', `请先给${label}功能分配当前入口可用的模型`);
   return Object.freeze(ordered.map((item) => Object.freeze({
     provider: providers.find((provider) => provider.id === item.providerId),
     model: item.id,
     modelRef: item.ref,
-    selectionReason: selectionReasonForModel(pool, capability, assignment, item)
+    selectionReason: selectionReasonForModel(configuredPool, capability, assignment, item)
   })));
 }
 

package/lib/provider-config-service.js

@@ -3,7 +3,7 @@ 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 { providerModels, modelPool, parseModelRef, HOST_VISION_REF, capabilitiesOfDiscoveredModel, hasConfiguredModelCapabilities, resolvePoolModel } from './models.js';
 import { atomicWritePrivate, privateSibling, ensurePrivateDir } from './private-storage.js';
 import { createConfiguredProviderAdapter } from './provider-adapters.js';
 import { selectImageProtocol, normalizeImageProtocol, normalizeMusicProtocol } from './provider-protocol.js';
@@ -22,7 +22,7 @@ const caps = value => {
 };
 
 function assignmentSnapshot(catalog) {
-  const pool = modelPool(catalog.providers);
+  const pool = modelPool(catalog.providers, { includeHostVision: true });
   return Object.fromEntries(Object.entries(catalog.assignments || {}).map(([capability, value]) => {
     const refs = (Array.isArray(value) ? value : [value]).map(ref => resolvePoolModel(pool, ref, capability));
     return [safe(capability), { model_refs: refs.filter(Boolean).map(model => safe(model.ref)), invalidRefs: refs.filter(ref => !ref).length }];
@@ -59,7 +59,7 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     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);
+    const pool = modelPool(catalog.providers, { includeHostVision: true });
     for (const provider of catalog.providers) {
       try { normalizeVisionInputLimits(provider.visionInput); } catch (_) { issues.push('invalid_vision_input'); }
       for (const model of provider.models || []) {
@@ -201,8 +201,8 @@ export async function executeConfigCommand(configPath, command, input = {}, { si
     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('分配模型不存在或没有该能力');
+      const pool = modelPool(catalog.providers, { includeHostVision: true });
+      for (const ref of input.model_refs) if ((!parseModelRef(ref) && ref !== HOST_VISION_REF) || !resolvePoolModel(pool, ref, input.capability)) fail('分配模型不存在或没有该能力');
       catalog.assignments[input.capability] = input.model_refs;
     }
   } else fail('未知配置命令');

package/lib/provider-protocol.js

@@ -63,6 +63,12 @@ export function selectImageProtocol(provider, modelId) {
   return protocol === 'auto' ? selectMediaProtocol(provider) : { mediaProtocol: protocol, protocolInferred: false };
 }
 
+/** 已接入的带图编辑协议；这里只判断传输，不授予模型 image-gen 能力。 */
+export function supportsImageEdit(protocol, modelId) {
+  return protocol === 'openai-chat-images' || (protocol === 'dashscope'
+    && /^qwen-image-(?:edit(?:-(?:max|plus))?|2\.0(?:-pro)?)(?:-\d{4}-\d{2}-\d{2})?$/.test(String(modelId || '')));
+}
+
 /** 给已绑定图片模型的 Adapter/binding 投影协议，不改写账号默认值。 */
 export function providerForImageModel(provider, modelId) {
   return { ...provider, ...selectImageProtocol(provider, modelId) };

package/lib/vision-model-routing.js

@@ -1,6 +1,6 @@
 'use strict';
 /** Host 边界：显式配置选型、字节解析和结果投影。 */
-import { resolveModelRef, parseModelRef } from './models.js';
+import { resolveModelRef, parseModelRef, HOST_VISION_REF } from './models.js';
 import { providerApiKey } from './provider-protocol.js';
 import { createHttpVisionModelPort } from './http-vision-model-adapter.js';
 import { prepareDshVisionModelPort } from './dsh-vision-model-adapter.js';
@@ -79,18 +79,31 @@ export function createConfiguredVisionModelPort(provider, model, { allowRateLimi
 export function buildVisionModelCandidates(host, { providers = [], model, allowRateLimited = false, onRateLimit, prepareImages = false,
   orientImages = false, prepareImageRequest } = {}) {
   const candidates = [], seen = new Set();
-  for (const provider of providers.filter(Boolean)) {
-    const ref = resolveModelRef(provider, 'vision', model);
+  let selected = providers.filter(Boolean);
+  const requested = String(model || '').trim();
+  if (requested) {
+    const parsed = parseModelRef(requested);
+    const provider = selected.find(p => p.id === HOST_VISION_REF ? requested === HOST_VISION_REF
+      : parsed ? parsed.providerId === p.id && parsed.modelId === p.visionModel : requested === p.visionModel);
+    if (!provider) throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare', invocation: 'not_invoked' });
+    selected = [provider];
+  }
+  if (!selected.length) throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare', invocation: 'not_invoked' });
+  for (const provider of selected) {
+    if (provider.id === HOST_VISION_REF) {
+      const hostCandidate = deferredDshPort(host, { prepareImages, orientImages, prepareImageRequest });
+      candidates.push({ ...hostCandidate, id: 'dsh-vision:default', via: 'global', backendId: 'dsh-global', model: 'DSH 当前默认模型' });
+      continue;
+    }
+    const ref = resolveModelRef(provider, 'vision', provider.visionModel);
     const parsed = parseModelRef(ref);
     // 显式模型会把同账号的多份池记录解析为同一复合引用，只保留首次候选。
     if (parsed && seen.has(ref)) continue;
     if (parsed) seen.add(ref);
-    const port = createConfiguredVisionModelPort(provider, model, { allowRateLimited, onRateLimit, prepareImages, orientImages, prepareImageRequest });
+    const port = createConfiguredVisionModelPort(provider, provider.visionModel, { allowRateLimited, onRateLimit, prepareImages, orientImages, prepareImageRequest });
     const id = port.describe().identity.backendId;
     candidates.push({ port, id, via: 'selfstack', backendId: provider.id, model: parsed?.modelId || '' });
   }
-  const hostCandidate = deferredDshPort(host, { prepareImages, orientImages, prepareImageRequest });
-  candidates.push({ ...hostCandidate, id: 'dsh-vision:default', via: 'global', backendId: 'dsh-global', model: '宿主视觉模型' });
   return candidates;
 }
 
@@ -137,6 +150,7 @@ function projectError(record, candidates) {
 /** prepareImage 的信号覆盖文件/会话读取；函数开始时即建立整体预算。 */
 export async function runVisionOperation(host, { providers, model, signal, budget = VISION_BUDGET, onRateLimit, prepareImages = false,
   orientImages = false, prepareImageRequest }, consume) {
+  if (signal?.aborted) throw new ModelPortError('IRIS_MODEL_ABORTED');
   const candidates = buildVisionModelCandidates(host, { providers, model, onRateLimit, prepareImages, orientImages, prepareImageRequest });
   const operation = createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: candidates.length } });
   try {
@@ -167,8 +181,8 @@ export async function runVisionRequest(host, { providers, model, question, image
 /** 付费确认在动作入口；红图实测只有一个供应商，不退到 Host 冒充其能力。 */
 export async function probeVisionModel(provider, model, image, { signal, timeoutMs = 15000 } = {}) {
   try {
-    const [candidate] = buildVisionModelCandidates(null, { providers: [provider], model, allowRateLimited: true });
-    const result = await completeVision([candidate.port], { prompt: '这张图片是什么颜色？请只回答颜色名称（中文）。', image },
+    const port = createConfiguredVisionModelPort(provider, model, { allowRateLimited: true });
+    const result = await completeVision([port], { prompt: '这张图片是什么颜色？请只回答颜色名称（中文）。', image },
       { signal, budget: { ...VISION_BUDGET, timeoutMs } });
     return { ok: /红|red/i.test(result.text), answer: result.text };
   } catch (error) {

package/package.json

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

package/user_guide.md

@@ -1,12 +1,12 @@
 # dsh-iris 用户指南
 
-本指南说明如何安装、配置和使用 Iris 0.2.3。升级范围见 [CHANGELOG](CHANGELOG.md) 和 [发布说明](docs/releases/0.2.3.md)。
+本指南对应Iris 0.2.4。发布状态见 [README](README.md)，升级范围见 [CHANGELOG](CHANGELOG.md) 和 [发布说明](docs/releases/0.2.4.md)。
 
-0.2.2 的能力来自明确功能标签、旧能力字段绑定或供应商能力元数据，账号和名称不再自动赋能。已有明确配置保留；仅有裸账号的配置需要先给实际模型设置功能，再加入有序候选池。
+功能来自明确标签、旧能力字段绑定或供应商能力元数据，账号和名称不会自动赋能。0.2.4还要求把模型明确加入对应功能名单；空名单停止新调用。已有配置保留，详见 [升级说明](docs/FUNCTION_MODEL_ASSIGNMENTS.md)。
 
 ## 安装
 
-先运行 `dsh --version`。Iris `0.2.3` 仅声明支持 DSH `0.2.0-rc.2`；旧 DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 使用固定版本 Iris `0.1.4`。验证边界见[适配说明](docs/DSH_RC2_ADAPTATION.md)。还需要 PATH 中的 `pnpm`，以及至少一个媒体或视觉服务供应商。Iris 0.2.x 要求 Node.js 22.0.0 或更高版本，旧 npm 0.1.4 的历史要求为 20.10.0；如果所用 DSH 版本要求更高，以 DSH 为准。Iris 0.1.1 及后续 0.1.x 不兼容 DSH 0.1.0/0.1.1 的旧客户端 Runtime。
+先运行 `dsh --version`。Iris 0.2.4支持DSH `0.2.0-rc.2` 或 `0.2.1-alpha.4`；Iris0.2.0–0.2.3仅支持rc.2。旧DSH `>=0.1.2-rc.1 <0.1.3-0` 或 `0.1.5-rc.1` 固定使用Iris0.1.4，见 [兼容矩阵](docs/DSH_COMPATIBILITY.md)。还需要PATH中的pnpm及至少一个所需功能的供应商。Iris最低Node.js为22.0.0，宿主要求更高时以宿主为准；旧npm0.1.4的历史要求为20.10.0。
 
 在上述旧 DSH 范围内，从 npm 安装固定稳定版到 Web profile：
 
@@ -17,12 +17,12 @@ dsh web
 
 npm 上无 scope 的 `dsh-iris` 是另一款插件；安装或更新 Iris Media 时必须使用完整 scoped 包名。
 
-只下载旧稳定包可运行 `npm pack @mokuyoaxis/dsh-iris@0.1.4`，安装为普通 npm 依赖可运行 `npm install @mokuyoaxis/dsh-iris@0.1.4`；后者不会自动加入 DSH profile。固定版本仍可在 latest 更新后安装，0.1.4 不包含新的 Core 媒体 CLI。DSH rc.2 使用 0.2.3。
+只下载旧稳定包可运行 `npm pack @mokuyoaxis/dsh-iris@0.1.4`，安装为普通npm依赖可运行 `npm install @mokuyoaxis/dsh-iris@0.1.4`；后者不会自动加入DSH profile。0.1.4不包含新的Core媒体CLI。
 
-在 DSH `0.2.0-rc.2` 上，从 npm 安装：
+在DSH rc.2或alpha.4上，固定安装0.2.4：
 
 ```bash
-dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.3
+dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.4
 dsh web
 ```
 
@@ -30,7 +30,7 @@ dsh web
 
 ### 独立 CLI
 
-无需 DSH，在自己的项目安装 `npm install @mokuyoaxis/dsh-iris@0.2.3`，通过 `npx dsh-iris --help` 查看入口。详见 [Headless CLI](docs/HEADLESS_CLI.md) 和 [视觉 CLI](docs/VISION_CLI.md)。
+无需DSH，在自己的项目安装 `npm install @mokuyoaxis/dsh-iris@0.2.4`，通过 `npx dsh-iris --help` 查看入口。发布状态见README，完整说明见 [Headless CLI](docs/HEADLESS_CLI.md) 和 [视觉CLI](docs/VISION_CLI.md)。
 
 其他 DSH 版本，包括 `0.2.0` 正式版与其他 rc，须另行验收。让 Agent 协助安装时，可使用[简要 Prompt](docs/AGENT_QUICKSTART.md)。
 
@@ -44,6 +44,12 @@ dsh --profile web --dump-config
 
 输出中应出现 `@mokuyoaxis/dsh-iris` 配置层和唯一行 ID `mokuyoaxis-dsh-iris`。DSH 的插件命令和 profile 机制见[官方说明](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md)。
 
+## 导入已有图片（0.2.4）
+
+在作品区展开“导入图片”，选择上传文件、会话附件或宿主路径，点击“保存到作品”。支持最多20 MiB的静态PNG/JPEG/WebP，保存原字节副本、保留原文件，不需要供应商或模型分配。成功后可使用图片卡的看图、OCR、改图及下载。
+
+导入要求Iris0.2.4，0.2.3没有此工具。Agent入口为 `iris_import_image`，CLI入口为 `artifact import`；上传临时副本与持久作品的区别及示例见 [图片导入](docs/IMAGE_IMPORT.md)。
+
 ## 最快配置：DashScope
 
 打开“设置 → Iris 工作台”，然后：
@@ -55,7 +61,7 @@ dsh --profile web --dump-config
 5. 展开刚添加的供应商，点击“发现模型”。
 6. 若模型显示“未标注功能”，点击其“设置功能”，勾选已确认支持的功能并保存。
 
-如果只有一个供应商，可以先保留“能力分配”为自动。Iris 会从模型池中为画图、视频、语音、转写和视觉能力选择第一个匹配模型。需要固定模型或设置故障转移顺序时，再到“能力分配（failover 顺序）”中调整。
+0.2.4中，单个供应商也需要在“功能分配（调用顺序）”为所需功能选择模型；未分配时不调用模型池。0.2.3仅Music采用严格名单，升级影响见 [功能模型分配](docs/FUNCTION_MODEL_ASSIGNMENTS.md)。
 
 保存供应商和修改能力分配都会立即生效，不需要重启 DSH。
 
@@ -129,10 +135,10 @@ Iris 先按画图、视频、语音、转写和视觉功能组织候选池，再
 
 每项能力都可以设置一个有序的“供应商 + 模型”列表。界面显示的是模型名和供应商，配置中保存为 `providerId::modelId` 复合引用，因此不同供应商的同名模型不会冲突。
 
-- 图片、视频、语音、转写与视觉未手工分配时，从模型池第一个匹配项开始；音乐仅使用明确分配名单。
-- 手工列表中的模型优先，并按列表顺序尝试。
-- 除音乐外，模型池中其余具备该能力的模型仍会作为后续候选。
-- 点击“恢复自动”会清除手工顺序；音乐清空名单后需重新分配才能生成。
+- 六类功能仅使用各自分配名单，每次按名单顺序选择，不补入其他模型。
+- 临时指定模型须已分配，本次只调用该项。
+- “清空分配”停止新调用，模型、任务与作品保留；已有任务按原绑定观察和补交付。
+- 视觉可明确加入“DSH 当前默认模型”并排序；未加入时不使用宿主视觉。
 
 生成类故障转移只覆盖上传、提交和同步生成阶段。远端一旦受理异步任务，Iris 就会继续跟踪这个任务，不会因轮询或下载失败自动重提，以免重复生成和计费。
 
@@ -172,9 +178,9 @@ Core 图片卡可直接点击“看图”或“OCR”；结果可以复制、下
 
 ### 按 Artifact ID 改图
 
-Core 静态 PNG/JPEG/WebP 图片卡可点击“改图”，填写修改指令，再选择聊天生图模型。点击“生成修改版”才调用模型，修改版保存为关联原图的新作品，原图保留；可继续看图、OCR、下载或编辑。
+Core 静态 PNG/JPEG/WebP 图片卡可点击“改图”，填写修改指令，再选择已分配的带图编辑模型。点击“生成修改版”才调用模型，修改版保存为关联原图的新作品，原图保留；可继续看图、OCR、下载或编辑。
 
-Agent 可调用 `iris_edit_image`，提供 `source_artifact_id`、`prompt` 与可选 `model_ref`。CLI 使用 `run image` 的同名字段，详见 [Artifact 聊天改图](docs/CLI_MANAGEMENT.md#artifact-聊天改图)。仅支持 `openai-chat-images` 的带图生成，不提供 mask、多参考图或连续编辑历史。
+Agent可调用 `iris_edit_image`，提供 `source_artifact_id`、`prompt` 与可选 `model`；CLI使用 `run image`，模型字段为 `model_ref`，见 [Artifact改图](docs/CLI_MANAGEMENT.md#artifact-聊天改图)。支持openai-chat-images带图生成，0.2.4另支持DashScope原生Qwen edit/max/plus、2.0/pro及日期快照。不提供mask、多参考图或连续编辑历史。
 
 ## 高级配置文件
 
@@ -381,11 +387,13 @@ npx @mokuyoaxis/dsh-iris doctor --json
 
 已安装包也可以直接运行 `dsh-iris doctor`。退出码为 `0`（正常）、`1`（警告）和 `2`（硬错误）。Doctor 会执行一个随后立即删除的本地写入探针，并检查配置、任务、能力分配、临时文件和产物引用；输出不含完整 API Key。离线模式无法检查 DSH 工具/客户端是否已经装载，也不会用付费请求验证 Provider。
 
-**0.2.0** 另提供 `doctor --data-root <绝对路径> --json`：只读盘点指定 Core 数据根的 Task、Artifact、Index 和租约，不执行上述写入探针，也不自动修复。`providers list` 与 `capabilities list` 可用 `--provider-config <私有配置绝对路径>` 只读查看脱敏供应商摘要和按配置排序的候选链；它们不代表远端能力已实测。异常退出留下租约时，先用显式 Doctor 查看 owner，再按 [Headless CLI 的恢复步骤](docs/HEADLESS_CLI.md#异常退出后的写者租约)人工确认并运行 `runtime recover`，不要手动删除租约。安装 Iris 后使用 `dsh-iris` 命令；临时运行可用 `npx --package @mokuyoaxis/dsh-iris@0.2.3 dsh-iris ...`。旧版 0.1.4 不包含这些 Core 命令。
+**0.2.0** 另提供 `doctor --data-root <绝对路径> --json`：只读盘点指定 Core 数据根的 Task、Artifact、Index 和租约，不执行上述写入探针，也不自动修复。`providers list` 与 `capabilities list` 可用 `--provider-config <私有配置绝对路径>` 只读查看脱敏供应商摘要和按配置排序的候选链；它们不代表远端能力已实测。异常退出留下租约时，先用显式 Doctor 查看 owner，再按 [Headless CLI 的恢复步骤](docs/HEADLESS_CLI.md#异常退出后的写者租约)人工确认并运行 `runtime recover`，不要手动删除租约。安装 Iris 后使用 `dsh-iris` 命令；临时运行可用 `npx --package @mokuyoaxis/dsh-iris@0.2.4 dsh-iris ...`。旧版 0.1.4 不包含这些 Core 命令。
 
 ## Host Doctor
 
-DSH运行后打开“设置 → Iris工作台 → 宿主诊断”。卡片检查宿主/服务端/客户端版本、当前工具和随包Skill、四组路由与四个UI Slot。0.2.3 包含 16 个工具（含音乐）和三项 Skill；升级后需重启服务端、刷新页面，并为要使用的功能分配模型。点击“刷新”查看结果，原始JSON可在已认证的同一浏览器访问 `/iris/api/doctor`。
+DSH运行后打开“设置 → Iris工作台 → 宿主诊断”。卡片检查宿主/服务端/客户端版本、当前工具和随包Skill、四组路由与四个UI Slot。0.2.4包含17个工具和三项Skill；升级后检查服务端实际装载、刷新页面，并为所需功能分配模型。点击“刷新”查看结果，原始JSON可在已认证的同一浏览器访问 `/iris/api/doctor`。
+
+0.2.4新增图片导入后检查17个工具，三项Skill保持；0.2.3为16个工具。
 
 Host Doctor 不打开 Browser、不读取附件或会话、不调用模型，也不请求供应商。报告中的 `exitCode` 是诊断严重度，不是 HTTP 状态：`0` 全部健康，`1` 有可降级警告，`2` 有硬错误。未安装 HTML Browser 时出现一条 Browser 警告是预期降级；如果提示尚未收到客户端握手，刷新 DSH 页面后再点“刷新”。若显示 `not found`，通常是前端已更新而 DSH 后端仍运行旧插件代码，应重启 DSH 后再刷新页面。
 
@@ -425,7 +433,7 @@ dsh plugin --profile web remove @mokuyoaxis/dsh-iris
 - **没有可用模型**：先确认供应商已启用且 Key 有效，再运行“发现模型”；未标注模型需通过“设置功能”选择用途，不支持 `/models` 时手动添加并标注。
 - **OpenAI 兼容图片请求走错协议**：核对模型的有效图片协议；`/images/generations` 使用 `openai-images`，网关聊天图片扩展使用 `openai-chat-images`，同步 `/responses` 生图使用 `openai-responses-images`。可在生图模型行或 CLI `models protocol` 设置模型级覆盖，不需要改变同账号其他模型的接口。
 - **反向代理访问返回 `untrusted host`**：把浏览器实际使用的域名或 `host:port` 加入 `IRIS_TRUSTED_HOSTS`，保留 Host，并确认代理层已经启用认证。
-- **看图可用但 Iris 模型池显示为空**：Agent 视觉工具可以回退到 DSH 全局视觉模型；需要在工作台操作时仍建议配置 Iris 的 `vision` 模型。
+- **模型池为空时使用宿主看图**：0.2.4需在视觉分配中明确加入“DSH 当前默认模型”；宿主默认模型须声明图片输入。也可配置并分配自持 `vision` 模型。
 - **视频摘要提示 ffmpeg 不可用**：安装系统级 `ffmpeg` 和 `ffprobe`，并确保 DSH 进程的 PATH 能找到它们。
 - **本地文件不存在**：这里的“本地”指 DSH 宿主，不一定是浏览器所在设备；优先用“上传文件”。
 - **视频任务长时间运行**：不要重复提交。用 `iris_task_status` 或工作台任务详情查询原任务。