@mokuyoaxis/dsh-iris 0.1.4 → 0.2.1

package/lib/headless-vision.js

@@ -0,0 +1,181 @@
+'use strict';
+/** 独立视觉入口：显式配置/媒体，已有 Core 帧只读，主动转写使用 writer。 */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import sharp from 'sharp';
+import { CommandError } from './command-service.js';
+import { visionCandidatesFromCatalog, transcribeCandidatesFromCatalog, providerForTaskFromCatalog, providerTaskBinding } from './provider-catalog.js';
+import { createConfiguredVisionModelPort, readVisionImageFile } from './vision-model-routing.js';
+import { createConfiguredProviderAdapter } from './provider-adapters.js';
+import { prepareProviderInput } from './provider-adapter.js';
+import { createProviderTaskRunner } from './provider-task-runner.js';
+import { CoreArtifactError, readCoreArtifactBytes } from './core-artifacts.js';
+import { createModelOperation } from './model-invoker.js';
+import { ModelPortError, modelErrorRecord } from './model-port-contract.js';
+import { completeVision, VISION_BUDGET } from './vision-core.js';
+import { locateObject, createLocateImageRequest } from './locate.js';
+import { createVisionInputObserver } from './vision-image-input.js';
+import { longOcr, normalizeOcrSettings, formatOcrResult } from './ocr.js';
+import { summarizeMedia } from './summarize.js';
+import { normalizeSummarySource, readSummaryFrames, summaryFrameRecords } from './summary-input.js';
+import { normalizeVisionImageSource, readVisionArtifact } from './vision-input.js';
+import { extractFrames, normalizeFramesOptions, probeVideo, extractAudioTrack, ffmpegAvailable } from './media-probe.js';
+import { waitForModelWork } from './model-call-runtime.js';
+
+function invalid(message) { throw new CommandError('IRIS_COMMAND_INPUT_INVALID', message); }
+
+export function normalizeVisionInput(command, input) {
+  const fields = {
+    look: ['image_path', 'artifact_id', 'question'], locate: ['image_path', 'artifact_id', 'target'],
+    ocr: ['image_path', 'artifact_id', 'chunk_height', 'overlap', 'max_dimension', 'max_invocations'],
+    summarize: ['video_path', 'frame_artifact_ids', 'question', 'max_frames', 'target_width', 'transcribe_text', 'transcribe', 'transcribe_model_ref']
+  }[command];
+  if (!fields) invalid('未知视觉命令');
+  if (!input || typeof input !== 'object' || Array.isArray(input)) invalid('--input 必须是 JSON 对象');
+  if (Object.keys(input).some(key => !fields.includes(key))) invalid('视觉输入含不支持的字段');
+  const fileField = command === 'summarize' ? 'video_path' : 'image_path';
+  const fileSource = command === 'summarize' ? normalizeSummarySource(input) === 'video'
+    : normalizeVisionImageSource(input) === 'image_path';
+  if (fileSource) {
+    if (typeof input[fileField] !== 'string' || !path.isAbsolute(input[fileField])) invalid(fileField + ' 必须是绝对路径');
+    try { if (!fs.statSync(input[fileField]).isFile()) throw new Error(); }
+    catch (_) { invalid('输入媒体文件不存在或不是普通文件'); }
+  }
+  for (const field of ['question', 'target', 'transcribe_text', 'transcribe_model_ref']) {
+    if (input[field] !== undefined && typeof input[field] !== 'string') invalid(field + ' 必须是字符串');
+  }
+  if (command === 'locate' && !input.target?.trim()) invalid('target 必须是非空字符串');
+  if (input.transcribe !== undefined && typeof input.transcribe !== 'boolean') invalid('transcribe 必须是布尔值');
+  if (input.transcribe && input.transcribe_text?.trim()) invalid('transcribe 与 transcribe_text 不能同时使用');
+  if (input.transcribe_model_ref !== undefined && !input.transcribe) invalid('transcribe_model_ref 需要 transcribe=true');
+  if (input.transcribe_model_ref !== undefined && !/^[^:]+::.+$/.test(input.transcribe_model_ref)) invalid('transcribe_model_ref 必须是 providerId::modelId');
+  if (command === 'ocr') normalizeOcrSettings({ chunkHeight: input.chunk_height, overlap: input.overlap,
+    maxDimension: input.max_dimension, maxInvocations: input.max_invocations });
+  if (command === 'summarize') {
+    try { normalizeFramesOptions({ maxFrames: input.max_frames, targetWidth: input.target_width }); }
+    catch (_) { invalid('max_frames 或 target_width 无效'); }
+  }
+  return input;
+}
+
+function selectedModel(completion, routes) {
+  const route = routes.find(value => value.provider.id === completion.identity?.providerId && value.model === completion.identity?.modelId);
+  return route ? { modelRef: route.modelRef, selectionReason: route.selectionReason } : {};
+}
+
+function completionResult(completion, routes) {
+  const { sheet: _sheet, ...result } = completion;
+  return { ...result, ...selectedModel(completion, routes) };
+}
+
+async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit }) {
+  const routes = transcribeCandidatesFromCatalog(catalog, input.transcribe_model_ref);
+  const candidates = routes.map(route => ({ adapter: createConfiguredProviderAdapter(route.provider, { onRateLimit }),
+    model: route.modelRef, selectionReason: route.selectionReason, providerBinding: providerTaskBinding(route.provider) }));
+  const audio = await waitForModelWork(() => extractAudioTrack({ inputPath: input.video_path, signal: operation.signal }), operation.signal);
+  const abortRuntime = () => { void runtime.dispose().catch(() => {}); };
+  operation.signal.addEventListener('abort', abortRuntime, { once: true });
+  let task;
+  try {
+    const prepared = await waitForModelWork(() => prepareProviderInput(candidates[0].adapter, {
+      model: routes[0].model, filePath: audio.filePath, signal: operation.signal
+    }), operation.signal);
+    const runner = createProviderTaskRunner(runtime);
+    const submitted = await waitForModelWork(() => runner.submit({ capability: 'transcribe', candidates,
+      providerInput: { audioUrl: prepared.url } }), operation.signal, 'invoke', 'unknown');
+    task = submitted.task;
+    if (task.acceptance === 'accepted' && task.outcome === 'none') {
+      const adapter = createConfiguredProviderAdapter(providerForTaskFromCatalog(catalog, task), { onRateLimit,
+        modelId: routes.find(route => route.modelRef === task.modelRef)?.model });
+      while (task.outcome === 'none') {
+        task = await waitForModelWork(() => runner.observe(task.id, adapter), operation.signal, 'read', 'responded');
+        if (task.outcome === 'none') await waitForModelWork(() => delay(1000, undefined, { signal: operation.signal }), operation.signal);
+      }
+    }
+    const report = { taskId: task.id, modelRef: task.modelRef, artifactIds: task.artifactIds, status: 'failed' };
+    if (task.outcome !== 'succeeded' || task.deliveryState !== 'ready') return { report, text: '' };
+    const texts = await runtime.run('inspect', ({ dataRoot }) => task.artifactIds.map(id => {
+      const artifact = readCoreArtifactBytes(dataRoot, id);
+      return artifact.artifact.mediaType.startsWith('text/') ? artifact.bytes.toString('utf8') : '';
+    }));
+    return { report: { ...report, status: 'complete' }, text: texts.filter(Boolean).join('\n') };
+  } catch (error) {
+    const record = modelErrorRecord(error);
+    if (['IRIS_MODEL_ABORTED', 'IRIS_MODEL_TIMEOUT'].includes(record.code)) throw error;
+    return { report: { status: 'failed', code: record.code, ...(task ? { taskId: task.id, modelRef: task.modelRef, artifactIds: task.artifactIds } : {}) }, text: '' };
+  } finally {
+    operation.signal.removeEventListener('abort', abortRuntime);
+    fs.rmSync(audio.outDir, { recursive: true, force: true });
+  }
+}
+
+export async function executeVisionCommand({ command, input, catalog, modelRef = '', runtime, signal, timeoutMs = VISION_BUDGET.timeoutMs, onRateLimit }) {
+  normalizeVisionInput(command, input);
+  if (modelRef && !/^[^:]+::.+$/.test(modelRef)) invalid('--model-ref 必须是 providerId::modelId');
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > VISION_BUDGET.timeoutMs) invalid('--timeout-ms 必须是 1–120000 的整数');
+  if (input.transcribe && !runtime) invalid('主动音轨转写需要 --data-root');
+  if ((input.artifact_id || input.frame_artifact_ids) && !runtime) invalid('读取 Core Artifact 需要 --data-root');
+  const routes = visionCandidatesFromCatalog(catalog, modelRef);
+  const inputs = new Map();
+  const prepareImageRequest = command === 'locate' ? createLocateImageRequest(input.target, inputs)
+    : command === 'ocr' ? createVisionInputObserver(inputs) : undefined;
+  const ports = routes.map(route => createConfiguredVisionModelPort(route.provider, route.model, { onRateLimit,
+    prepareImages: ['look', 'ocr', 'locate'].includes(command), orientImages: command === 'locate', prepareImageRequest }));
+  const budget = { ...VISION_BUDGET, timeoutMs };
+  const operation = createModelOperation({ signal, budget: { timeoutMs, maxInvocations: command === 'ocr' ? input.max_invocations ?? 64 : ports.length } });
+  const base = { schemaVersion: 1, command: 'vision.' + command, status: 'complete',
+    ...(input.artifact_id ? { artifactId: input.artifact_id } : {}) };
+  try {
+    if (command === 'summarize') {
+      let meta, frames;
+      if (input.frame_artifact_ids) {
+        ({ meta, frames } = await readSummaryFrames(runtime, input.frame_artifact_ids, operation.signal));
+      } else {
+        if (!ffmpegAvailable()) throw new CommandError('IRIS_MEDIA_TOOL_UNAVAILABLE', '视频摘要需要 PATH 中的 ffmpeg 和 ffprobe');
+        meta = await waitForModelWork(() => probeVideo(input.video_path), operation.signal);
+        frames = await waitForModelWork(() => extractFrames({ inputPath: input.video_path,
+          maxFrames: input.max_frames, targetWidth: input.target_width, signal: operation.signal }), operation.signal);
+      }
+      let transcript = input.transcribe_text || '', transcription = { status: transcript.trim() ? 'provided' : 'disabled' };
+      if (input.transcribe) {
+        const asr = meta.hasAudio ? await transcribeVideo({ catalog, input, runtime, operation, onRateLimit }) : { report: { status: 'no_audio' }, text: '' };
+        transcript = asr.text; transcription = asr.report;
+      }
+      const completion = await summarizeMedia({ ports, frames, question: input.question, transcript, operation, budget });
+      const sheet = completion.sheet;
+      const note = transcription.status === 'failed' ? '音轨转写失败，本次摘要只分析画面。' : '';
+      if (note) transcription.note = note;
+      return { result: { ...base, ...completionResult(completion, routes), meta,
+        frames: summaryFrameRecords(frames), transcription,
+        contactSheet: { mediaType: 'image/png', width: sheet.width, height: sheet.height,
+          sha256: createHash('sha256').update(sheet.buffer).digest('hex') } }, text: completion.text + (note ? '\n\n[iris] ' + note : ''), sheetBuffer: sheet.buffer, exitCode: 0 };
+    }
+    let image;
+    if (input.artifact_id) image = await readVisionArtifact(runtime, input.artifact_id, operation.signal);
+    else {
+      const mediaType = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif' }[path.extname(input.image_path).toLowerCase()];
+      if (!mediaType) invalid('图片只支持 PNG、JPEG、WebP、GIF');
+      image = await readVisionImageFile(input.image_path, mediaType, operation.signal);
+    }
+    if (command === 'ocr') {
+      const ocr = await longOcr({ image, ports, chunkHeight: input.chunk_height, overlap: input.overlap,
+        maxDimension: input.max_dimension, maxInvocations: input.max_invocations, operation, budget, inputs });
+      return { result: { ...base, ...ocr, chunks: ocr.chunks.map(chunk => ({ ...chunk, ...selectedModel(chunk, routes) })) },
+        text: formatOcrResult(ocr), exitCode: ocr.status === 'complete' ? 0 : 1 };
+    }
+    let completion;
+    if (command === 'locate') {
+      const { width, height } = await waitForModelWork(() => sharp(Buffer.from(image.bytes)).metadata(), operation.signal);
+      completion = await locateObject(ports, { target: input.target, image, width, height }, { operation, budget });
+      return { result: { ...base, ...completionResult(completion, routes), width, height,
+        input: inputs.get(completion.identity.backendId) }, text: JSON.stringify(completion.bbox), exitCode: 0 };
+    }
+    completion = await completeVision(ports, { prompt: input.question?.trim() || '请用中文描述这张图片的内容。', image }, { operation, budget });
+    return { result: { ...base, ...completionResult(completion, routes) }, text: completion.text, exitCode: 0 };
+  } catch (error) {
+    if (error instanceof ModelPortError || error instanceof CommandError || error instanceof CoreArtifactError || error.name === 'ProviderCatalogError') throw error;
+    throw new ModelPortError('IRIS_MODEL_INPUT_INVALID', { stage: 'prepare', invocation: 'not_invoked' });
+  } finally { operation.dispose(); }
+}

package/lib/host-runtime.js

@@ -11,6 +11,7 @@ export const HOST_CLIENT_PROTOCOL_VERSION = 0;
 
 export const EXPECTED_IRIS_TOOLS = Object.freeze([
   'iris_draw_image',
+  'iris_edit_image',
   'iris_generate_video',
   'iris_speak_text',
   'iris_transcribe_audio',

package/lib/http-vision-model-adapter.js

@@ -0,0 +1,187 @@
+'use strict';
+/** OpenAI-compatible Chat Completions SSE；凭据/端点只留在闭包内。 */
+import { ModelPortError, normalizeModelDescriptor, normalizeModelCall, normalizeModelCompletion,
+  createModelTextCollector } from './model-port-contract.js';
+import { modelCallScope, modelAbortError, waitForModelWork } from './model-call-runtime.js';
+import { createHash } from 'node:crypto';
+import { isFreeQuotaExhausted, retryAfterDelay } from './provider-health.js';
+import { prepareVisionImage } from './vision-image-input.js';
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const FRAME_LIMIT = 1024 * 1024;
+
+function usageSnapshot(value) {
+  if (!object(value)) return undefined;
+  const usage = {};
+  for (const [source, target] of [['prompt_tokens', 'inputTokens'], ['completion_tokens', 'outputTokens'], ['total_tokens', 'totalTokens']]) {
+    if (Number.isSafeInteger(value[source]) && value[source] >= 0) usage[target] = value[source];
+  }
+  const reasoning = value.completion_tokens_details?.reasoning_tokens;
+  if (Number.isSafeInteger(reasoning) && reasoning >= 0) usage.reasoningTokens = reasoning;
+  return Object.keys(usage).length ? usage : undefined;
+}
+
+export function createHttpVisionModelPort({ providerId, modelId, baseUrl, apiKey = '', imageInput, orientImages = false,
+  prepareImageRequest, fetch: fetchImpl = globalThis.fetch }) {
+  const descriptor = normalizeModelDescriptor({ contractVersion: 0, kind: 'vision',
+    identity: { origin: 'provider', backendId: 'iris-provider:' + createHash('sha256').update(JSON.stringify([providerId, modelId])).digest('hex'), providerId, modelId },
+    availability: 'available', features: { system: 'supported', temperature: 'supported', maxOutputTokens: 'supported', reasoning: 'unknown' } });
+  let endpoint;
+  try {
+    const url = new URL(String(baseUrl).replace(/\/+$/, '') + '/chat/completions');
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.hash || url.search) throw new Error();
+    endpoint = url.href;
+  } catch (_) { throw new ModelPortError('IRIS_MODEL_INPUT_INVALID'); }
+  return Object.freeze({
+    describe: () => normalizeModelDescriptor(descriptor),
+    async complete(request, options) {
+      const input = normalizeModelCall(descriptor, request, options);
+      if (input.options.signal?.aborted) throw modelAbortError(input.options.signal);
+      const scope = modelCallScope(input.options.signal, input.options.budget.timeoutMs);
+      const { signal } = scope;
+      const collector = createModelTextCollector({ maxOutputChars: input.options.budget.maxOutputChars, signal,
+        backendId: descriptor.identity.backendId });
+      let response, iterator, ended = false, invoked = false, responded = false, finished = false, done = false, usage;
+      const protocol = () => new ModelPortError('IRIS_MODEL_PROTOCOL_INVALID', { stage: 'read', invocation: responded ? 'responded' : 'unknown' });
+      const consume = data => {
+        if (!data) return;
+        if (done) throw protocol();
+        if (data === '[DONE]') {
+          if (!finished) throw new ModelPortError('IRIS_MODEL_INCOMPLETE', { stage: 'read', invocation: responded ? 'responded' : 'unknown' });
+          done = true; return;
+        }
+        let event;
+        try { event = JSON.parse(data); } catch (_) { throw protocol(); }
+        if (!object(event)) throw protocol();
+        if (event.error) throw new ModelPortError('IRIS_MODEL_REQUEST_FAILED', { stage: 'read', invocation: responded ? 'responded' : 'unknown' });
+        if (!Array.isArray(event.choices)) throw protocol();
+        if (event.usage !== undefined && event.usage !== null) {
+          if (!object(event.usage)) throw protocol();
+          usage = usageSnapshot(event.usage);
+        }
+        if (event.choices.length === 0 && object(event.usage)) return;
+        if (event.choices.length !== 1 || finished) throw protocol();
+        const choice = event.choices[0];
+        if (!object(choice) || choice.index !== undefined && choice.index !== 0 || !object(choice.delta)) throw protocol();
+        const delta = choice.delta;
+        if (delta.tool_calls !== undefined || delta.function_call !== undefined) collector.finish('tool-calls');
+        if (delta.refusal) collector.finish('content-blocked');
+        if (delta.content !== undefined && delta.content !== null) {
+          if (typeof delta.content !== 'string') throw protocol();
+          if (delta.content.length) responded = true;
+          collector.append(delta.content);
+        }
+        if (choice.finish_reason !== undefined && choice.finish_reason !== null) {
+          const reason = { stop: 'stop', length: 'length', tool_calls: 'tool-calls', function_call: 'tool-calls', content_filter: 'content-blocked' }[choice.finish_reason];
+          responded = true; collector.finish(reason || 'unknown'); finished = true;
+        }
+      };
+      try {
+        const image = imageInput ? await prepareVisionImage(input.request.image, imageInput, { signal, orient: orientImages }) : input.request.image;
+        const prepared = await waitForModelWork(() => prepareImageRequest?.({ request: input.request, image, signal, identity: descriptor.identity }), signal);
+        const prompt = prepared?.prompt ?? input.request.prompt;
+        normalizeModelCall(descriptor, { ...input.request, image, prompt }, input.options);
+        const body = { model: modelId, stream: true, messages: [
+          ...(input.request.system === undefined ? [] : [{ role: 'system', content: input.request.system }]),
+          { role: 'user', content: [{ type: 'text', text: prompt }, { type: 'image_url', image_url: {
+            url: `data:${image.mediaType};base64,${Buffer.from(image.bytes).toString('base64')}`
+          } }] }
+        ] };
+        if (input.request.generation?.temperature !== undefined) body.temperature = input.request.generation.temperature;
+        if (input.request.generation?.maxOutputTokens !== undefined) body.max_tokens = input.request.generation.maxOutputTokens;
+        response = await waitForModelWork(() => {
+          invoked = true;
+          const pending = Promise.resolve(fetchImpl(endpoint, { method: 'POST', redirect: 'error', signal,
+            headers: { 'Content-Type': 'application/json', ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}) }, body: JSON.stringify(body) }));
+          // fetch 不合作时，取消之后才到达的 body 也必须被释放。
+          return pending.then(value => {
+            if (signal.aborted) {
+              Promise.resolve(value?.body?.cancel?.()).catch(() => {});
+              throw modelAbortError(signal, 'invoke', 'unknown');
+            }
+            return value;
+          });
+        }, signal, 'invoke', 'unknown');
+        if (!response.ok) {
+          const body = [400, 403, 413, 429].includes(response.status) ? await waitForModelWork(() => response.json().catch(() => null), signal, 'read', 'rejected') : null;
+          // 只提取可验证的数值事实，不把供应商原文或凭据带到 UI/CLI。
+          const limit = [400, 413].includes(response.status)
+            ? /\b(\d+) bytes exceeds the (\d+)-byte limit\b/i.exec(String(body?.error?.message || body?.message || '')) : null;
+          const maxBytes = limit && Number(limit[1]) === image.bytes.byteLength && Number.isSafeInteger(Number(limit[2])) && Number(limit[2]) > 0
+            ? Number(limit[2]) : undefined;
+          if (maxBytes || response.status === 413) {
+            throw new ModelPortError('IRIS_MODEL_IMAGE_TOO_LARGE', { stage: 'invoke', invocation: 'rejected', status: response.status,
+              imageBytes: image.bytes.byteLength, ...(maxBytes ? { imageMaxBytes: maxBytes } : {}) });
+          }
+          const quota = isFreeQuotaExhausted({ status: response.status, ...(body?.error || body) });
+          const code = quota ? 'IRIS_MODEL_RATE_LIMITED' : [401, 403].includes(response.status) ? 'IRIS_MODEL_AUTH_FAILED'
+            : response.status === 429 ? 'IRIS_MODEL_RATE_LIMITED' : response.status === 400 ? 'IRIS_MODEL_INPUT_INVALID' : 'IRIS_MODEL_REQUEST_FAILED';
+          const error = new ModelPortError(code, { stage: 'invoke', invocation: code === 'IRIS_MODEL_REQUEST_FAILED' ? 'unknown' : 'rejected', status: response.status });
+          error.providerCode = (body?.error || body)?.code;
+          if (response.status === 429) error.retryAfterMs = retryAfterDelay(response.headers.get('retry-after'));
+          if (quota) error.quotaExhausted = true;
+          throw error;
+        }
+        if (!response.body || typeof response.body[Symbol.asyncIterator] !== 'function'
+            || !/^text\/event-stream(?:\s*;|$)/i.test(response.headers.get('content-type') || '')) throw protocol();
+        iterator = response.body[Symbol.asyncIterator]();
+        const decoder = new TextDecoder('utf-8', { fatal: true });
+        let buffer = '', data = [], frameLength = 0;
+        const line = value => {
+          if (!value) { consume(data.join('\n')); data = []; frameLength = 0; return; }
+          frameLength += value.length;
+          if (frameLength > FRAME_LIMIT) throw protocol();
+          if (value.startsWith(':')) return;
+          const split = value.indexOf(':');
+          const field = split < 0 ? value : value.slice(0, split);
+          let fieldValue = split < 0 ? '' : value.slice(split + 1);
+          if (fieldValue.startsWith(' ')) fieldValue = fieldValue.slice(1);
+          if (field === 'data') data.push(fieldValue);
+          else if (field === 'event' && fieldValue && fieldValue !== 'message') throw protocol();
+        };
+        const drain = final => {
+          while (true) {
+            const index = buffer.search(/[\r\n]/);
+            if (index < 0 || !final && index === buffer.length - 1 && buffer[index] === '\r') break;
+            const width = buffer[index] === '\r' && buffer[index + 1] === '\n' ? 2 : 1;
+            line(buffer.slice(0, index)); buffer = buffer.slice(index + width);
+          }
+          if (buffer.length > FRAME_LIMIT) throw protocol();
+        };
+        while (true) {
+          const next = await waitForModelWork(() => iterator.next(), signal, 'read', responded ? 'responded' : 'unknown');
+          if (next.done) { ended = true; break; }
+          if (!(next.value instanceof Uint8Array)) throw protocol();
+          // 分段解码限制未换行的帧内存，不依赖底层 chunk 大小。
+          for (let offset = 0; offset < next.value.length; offset += 16384) {
+            try { buffer += decoder.decode(next.value.subarray(offset, offset + 16384), { stream: true }); }
+            catch (_) { throw protocol(); }
+            drain(false);
+          }
+        }
+        try { buffer += decoder.decode(); } catch (_) { throw protocol(); }
+        drain(true);
+        // SSE 未以空行提交的尾帧不算有效终态。
+        if (buffer.trim() || data.length) throw new ModelPortError('IRIS_MODEL_INCOMPLETE', { stage: 'read', invocation: responded ? 'responded' : 'unknown' });
+        const collected = collector.complete();
+        const text = prepared?.mapText ? prepared.mapText(collected) : collected;
+        return normalizeModelCompletion(descriptor, { contractVersion: 0, text, finishReason: 'stop', identity: descriptor.identity,
+          ...(usage ? { usage } : {}) }, input.options.budget);
+      } catch (error) {
+        if (signal.aborted) throw modelAbortError(signal, invoked ? 'read' : 'prepare', responded ? 'responded' : invoked ? 'unknown' : 'not_invoked');
+        // 保留明确 HTTP 拒绝事实；其余错误让 collector 保留已收到部分正文的事实。
+        if (error instanceof ModelPortError && (error.invocation === 'rejected' || !invoked)) throw error;
+        collector.fail(error);
+      } finally {
+        if (!ended) {
+          scope.abort(new ModelPortError('IRIS_MODEL_ABORTED'));
+          const closing = iterator?.return ? () => iterator.return() : () => response?.body?.cancel?.();
+          // 主动启动清理，并处理不合作的 return 的晚到失败。
+          const pending = Promise.resolve().then(closing);
+          await Promise.race([pending, Promise.resolve()]).catch(() => {});
+        }
+        scope.dispose();
+      }
+    }
+  });
+}

package/lib/image-edit-input.js

@@ -0,0 +1,34 @@
+'use strict';
+/** 聊天改图只接受当前 Core 中的静态图片；输入原字节不进入 Task 记录。 */
+import sharp from 'sharp';
+import { inspectCoreArtifact, readCoreArtifactBytes } from './core-artifacts.js';
+import { waitForModelWork } from './model-call-runtime.js';
+
+function invalid(message) {
+  return Object.assign(new Error(message), { code: 'IRIS_IMAGE_EDIT_INPUT_INVALID' });
+}
+
+export function imageEditCandidates(candidates) {
+  if (candidates.some(candidate => candidate.selectionReason === 'explicit'
+      && candidate.adapter.protocol !== 'openai-chat-images')) {
+    throw invalid('指定模型的图片协议不支持聊天改图，请选择 openai-chat-images 模型');
+  }
+  const selected = candidates.filter(candidate => candidate.adapter.protocol === 'openai-chat-images');
+  if (!selected.length) throw invalid('未配置可用的 openai-chat-images 生图模型，无法编辑原图');
+  return selected;
+}
+
+export async function readImageEditArtifact(dataRoot, artifactId, signal) {
+  if (typeof artifactId !== 'string' || !/^artifact_[a-f0-9]{24}$/.test(artifactId)) {
+    throw invalid('source_artifact_id 必须是有效的 Core Artifact ID');
+  }
+  const artifact = inspectCoreArtifact(dataRoot, artifactId);
+  if (!['image/png', 'image/jpeg', 'image/webp'].includes(artifact.mediaType) || artifact.size > 20 * 1024 * 1024) {
+    throw invalid('改图来源必须是最多 20 MiB 的静态 PNG、JPEG 或 WebP Artifact');
+  }
+  const { bytes } = readCoreArtifactBytes(dataRoot, artifactId);
+  const metadata = await waitForModelWork(() => sharp(bytes).metadata(), signal);
+  if ({ png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' }[metadata.format] !== artifact.mediaType
+      || metadata.pages > 1) throw invalid('改图来源的真实格式必须与 MIME 一致，且不能是动画');
+  return { bytes: new Uint8Array(bytes), mediaType: artifact.mediaType };
+}