@mokuyoaxis/dsh-iris 0.2.0 → 0.2.2

package/lib/core-writer-lease.js

@@ -0,0 +1,134 @@
+'use strict';
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { CORE_CONTRACT_VERSION } from './core-contract.js';
+import { privateSibling } from './private-storage.js';
+
+export const WRITER_LEASE_DIR = '.iris-runtime-writer-v0';
+export const WRITER_INTENT_FILE = '.iris-runtime-writer-v0.owner.json';
+export function recoveryClaimFile(root, owner) {
+  return path.join(root, WRITER_LEASE_DIR + '.recovery-' + owner.instanceId + '.json');
+}
+const UUID = /^[a-f0-9-]{36}$/;
+const STALE = /^\.owner\.stale-([a-f0-9-]{36})\.json$/;
+
+export function writerOwnerStatus(pid) {
+  try { process.kill(pid, 0); return 'alive'; }
+  catch (error) { return error?.code === 'ESRCH' ? 'missing' : 'unknown'; }
+}
+
+export function newWriterOwner() {
+  return { contractVersion: CORE_CONTRACT_VERSION, instanceId: crypto.randomUUID(),
+    pid: process.pid, createdAt: new Date().toISOString() };
+}
+
+function checkedOwner(owner) {
+  if (owner?.contractVersion !== CORE_CONTRACT_VERSION || !Number.isSafeInteger(owner.pid) || owner.pid <= 0
+      || !UUID.test(String(owner.instanceId || '')) || !Number.isFinite(Date.parse(owner.createdAt))) {
+    throw new Error('incomplete owner');
+  }
+  return owner;
+}
+
+function readRecord(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384) throw new Error('invalid lease record');
+  const serialized = fs.readFileSync(file, 'utf8');
+  return { serialized, value: JSON.parse(serialized) };
+}
+
+function optionalRecord(file) {
+  try { return readRecord(file); }
+  catch (error) { if (error?.code === 'ENOENT') return null; throw error; }
+}
+
+/** 完整私有记录先在根中准备，再以 hard link 原子发布；已有目标绝不覆盖。 */
+export function publishLeaseRecord(root, target, value) {
+  const prepared = privateSibling(path.join(root, WRITER_INTENT_FILE), 'prepare');
+  let created = false;
+  try {
+    fs.writeFileSync(prepared, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    created = true;
+    fs.linkSync(prepared, target);
+  } finally {
+    if (created) { try { fs.unlinkSync(prepared); } catch (_) { /* 未发布的准备文件不占有租约 */ } }
+  }
+}
+
+export function withdrawLeaseRecord(target, value) {
+  if (readRecord(target).serialized !== JSON.stringify(value, null, 2) + '\n') throw new Error('published record changed');
+  fs.unlinkSync(target);
+}
+
+export function retireLeaseDirectory(source, target) {
+  try { fs.lstatSync(target); throw new Error('retirement destination already exists'); }
+  catch (error) { if (error?.code !== 'ENOENT') throw error; }
+  fs.renameSync(source, target);
+}
+
+/** 只读识别完整 owner、创建/释放意图及恢复链；未知内容和缺失证据拒绝。 */
+export function readWriterLease(root) {
+  const directory = path.join(root, WRITER_LEASE_DIR);
+  const intentFile = path.join(root, WRITER_INTENT_FILE);
+  const intent = optionalRecord(intentFile);
+  if (intent) checkedOwner(intent.value);
+  let stat;
+  try { stat = fs.lstatSync(directory); }
+  catch (error) { if (error?.code !== 'ENOENT') throw error; }
+  if (!stat && !intent) return null;
+  if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) throw new Error('invalid lease directory');
+  const entries = stat ? fs.readdirSync(directory).sort() : [];
+  const records = new Map();
+  for (const name of entries) {
+    if (name !== 'owner.json' && !STALE.test(name)) throw new Error('unexpected lease contents');
+    records.set(name, readRecord(path.join(directory, name)));
+  }
+  const ownerRecord = records.get('owner.json');
+  if (ownerRecord) checkedOwner(ownerRecord.value);
+  const staleRecords = entries.filter(name => STALE.test(name));
+  if (staleRecords.length > 1) throw new Error('ambiguous legacy recovery');
+  const staleRecord = staleRecords.length ? records.get(staleRecords[0]) : null;
+  if (staleRecord) checkedOwner(staleRecord.value);
+  if (staleRecord && !ownerRecord) throw new Error('legacy recovery PID unknown');
+  if (intent && ownerRecord && ownerRecord.serialized !== intent.serialized) {
+    throw new Error('intent owner mismatch');
+  }
+  if (staleRecord && ownerRecord && STALE.exec(staleRecords[0])[1] !== ownerRecord.value.instanceId) {
+    throw new Error('legacy recovery owner mismatch');
+  }
+  const original = staleRecord || ownerRecord || intent;
+  if (!original) throw new Error('owner evidence missing');
+  let owner = (ownerRecord || original).value;
+  const owners = [original.value];
+  if (owner.instanceId !== original.value.instanceId) owners.push(owner);
+  const claims = [];
+  for (;;) {
+    const file = recoveryClaimFile(root, owner);
+    const record = optionalRecord(file);
+    if (!record) break;
+    const claim = record.value;
+    if (claim?.schemaVersion !== 1 || claim.previousInstanceId !== owner.instanceId) throw new Error('invalid recovery claim');
+    claims.push({ file, ...record });
+    owner = checkedOwner(claim.owner);
+    if (owners.some(previous => previous.instanceId === owner.instanceId)) throw new Error('cyclic recovery chain');
+    owners.push(owner);
+    if (owners.length > 64) throw new Error('recovery chain too long');
+  }
+  const phase = owners.length > 1 || staleRecord ? 'recovering' : ownerRecord ? 'owned' : 'pending';
+  const fingerprint = crypto.createHash('sha256').update(JSON.stringify({
+    identity: stat ? [stat.dev, stat.ino] : null, intent: intent?.serialized,
+    records: [...records].map(([name, record]) => [name, record.serialized]),
+    claims: claims.map(record => [path.basename(record.file), record.serialized])
+  })).digest('hex');
+  return { directory, intentFile, intent, stat, entries, records, claims, owner, owners,
+    originalOwner: original.value, phase, fingerprint };
+}
+
+export function removeWriterIntent(lease) {
+  if (!lease.intent) return;
+  const actual = readRecord(lease.intentFile);
+  if (actual.serialized !== lease.intent.serialized) throw new Error('intent changed');
+  fs.unlinkSync(lease.intentFile);
+}

package/lib/dsh-core-adapter.js

@@ -2,16 +2,19 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { allProviders, irisHome } from './config.js';
+import { allProviders, irisHome, recordRateLimit } from './config.js';
 import { createCommandService } from './command-service.js';
-import { createCoreArtifact, inspectCoreArtifact, listCoreArtifacts, readCoreArtifactBytes } from './core-artifacts.js';
+import { createCoreArtifact, inspectCoreArtifact, listCoreArtifacts, listCoreArtifactMetadata, readCoreArtifactBytes } from './core-artifacts.js';
 import { createCoreRuntime } from './core-runtime.js';
+import { readSummaryFrames } from './summary-input.js';
+import { readVisionArtifact } from './vision-input.js';
 import { inspectCoreTask, listCoreTasks, recoverCoreTask } from './core-tasks.js';
 import { applyCoreAttentionAction, attentionDispositionOf, readCoreAttentionPrefs } from './core-attention.js';
 import { projectCoreTaskUserRow } from './core-user-projection.js';
 import { requireHostPort } from './host-contract.js';
 import { createProviderTaskRunner } from './provider-task-runner.js';
-import { createConfiguredProviderAdapter } from './provider-adapters.js';
+import { createConfiguredProviderAdapter as createProviderAdapter } from './provider-adapters.js';
+import { parseModelRef } from './models.js';
 import { imageCandidatesFromCatalog, providerForTaskFromCatalog, providerTaskBinding, transcribeCandidatesFromCatalog, ttsCandidatesFromCatalog, videoCandidatesFromCatalog } from './provider-catalog.js';
 
 let writerTail = Promise.resolve();
@@ -20,6 +23,10 @@ const DEFAULT_POLL_INTERVAL_MS = 2500;
 const DEFAULT_MAX_WATCH_MS = 20 * 60 * 1000;
 const POLL_ERROR_TOLERANCE = 5;
 
+function createConfiguredProviderAdapter(provider, options = {}) {
+  return createProviderAdapter(provider, { ...options, onRateLimit: recordRateLimit });
+}
+
 export class DshCoreAdapterError extends Error {
   constructor(code, message) {
     super(message);
@@ -99,6 +106,16 @@ export async function cropForDsh(input = {}) {
   }, input.signal);
 }
 
+/** Browser 只提供截图字节；DSH/CLI 共用 HTML Command 和 Artifact 提交。 */
+export function htmlForDsh(input = {}) {
+  return withWriter(async runtime => {
+    const commands = createCommandService(runtime, { browser: input.browser });
+    const result = await commands.execute('media.html', { html: input.html, width: input.width,
+      height: input.height, full_page: input.fullPage });
+    return runtime.run('inspect', ({ dataRoot }) => readCoreArtifactBytes(dataRoot, result.artifact.id));
+  }, input.signal);
+}
+
 /** DSH 只把图片来源转换为 Command 输入，差异算法与 Artifact 提交由 Core 执行。 */
 export function diffForDsh(input = {}) {
   return withWriter(async (runtime, commands) => {
@@ -142,12 +159,23 @@ export function framesForDsh(input = {}) {
   }, input.signal);
 }
 
+/** 已有抽帧 Artifact 直接进入共享摘要；reader 不取得写者租约。 */
+export function summaryFramesForDsh(input = {}) {
+  return withReader(runtime => readSummaryFrames(runtime, input.frameArtifactIds, input.signal), input.signal);
+}
+
+/** 共享单图读取器用于 look/locate/OCR，Host 不解释 Core 对象路径。 */
+export function visionImageForDsh(input = {}) {
+  return withReader(runtime => readVisionArtifact(runtime, input.artifactId, input.signal), input.signal);
+}
+
 /** 提交一个 Core Provider Task；Provider Adapter 由 DSH 配置边界选择后显式传入。 */
 export function submitProviderTaskForDsh(input = {}) {
   return withWriter((runtime) => createProviderTaskRunner(runtime).submit({
     capability: input.capability,
     candidates: input.candidates,
-    providerInput: input.providerInput
+    providerInput: input.providerInput,
+    sourceArtifactId: input.sourceArtifactId
   }), input.signal);
 }
 
@@ -272,7 +300,7 @@ export function retryProviderTaskForDsh(input = {}) {
         ? { text: input.text, ...(input.voice !== undefined ? { voice: input.voice } : {}) }
         : input.audio_url !== undefined
           ? { audio_url: input.audio_url }
-          : { prompt: input.prompt },
+          : { prompt: input.prompt, ...(input.sourceArtifactId !== undefined ? { source_artifact_id: input.sourceArtifactId } : {}) },
       model_ref: input.modelRef,
       confirm_billing: input.confirmBilling
     });
@@ -304,7 +332,7 @@ function observableProviderTask(task) {
 
 function configuredAdapterForTask(task) {
   const provider = providerForTaskFromCatalog({ providers: allProviders() }, task);
-  return createConfiguredProviderAdapter(provider);
+  return createConfiguredProviderAdapter(provider, { modelId: parseModelRef(task.modelRef)?.modelId });
 }
 
 function stopProviderWatch(taskId, expectedState) {
@@ -444,6 +472,30 @@ export function inspectProviderTaskForDsh(taskId, options = {}) {
     inspectCoreTask(dataRoot, taskId)), options.signal);
 }
 
+/** 作品目录与任务 snapshot 分开查询，目录不加载媒体字节、不取得 writer 租约。 */
+export function galleryArtifactsForDsh(options = {}) {
+  if (!fs.existsSync(dshCoreDataRoot())) return Promise.resolve({ artifacts: [], revision: 0, dropped: 0 });
+  return withReader((runtime) => runtime.run('inspect', ({ dataRoot }) =>
+    listCoreArtifactMetadata(dataRoot)), options.signal);
+}
+
+export function inspectWorkbenchArtifactForDsh(artifactId, options = {}) {
+  return withReader(runtime => runtime.run('inspect', ({ dataRoot }) =>
+    inspectCoreArtifact(dataRoot, artifactId)), options.signal);
+}
+
+/** 工作台管理沿用 CLI 的维护命令；预览/事务列表只读，执行使用既有串行 writer。 */
+export function maintainWorkbenchForDsh(command, input, options = {}) {
+  if (!['core.delete', 'core.transactions', 'core.restore'].includes(command)) {
+    throw new DshCoreAdapterError('IRIS_COMMAND_INPUT_INVALID', '不支持的作品管理命令');
+  }
+  if (command === 'core.transactions' && !fs.existsSync(dshCoreDataRoot())) return Promise.resolve({ transactions: [] });
+  if (command === 'core.restore' || input.confirm_delete === true) {
+    return withWriter((_runtime, commands) => commands.execute(command, input), options.signal);
+  }
+  return withReader(runtime => createCommandService(runtime).execute(command, input), options.signal);
+}
+
 /**
  * 工作台只读候选快照；数据根不存在时不创建任何目录。
  * userTasks 是用户任务区消费的五类状态安全投影（lib/core-user-projection.js），
@@ -533,8 +585,9 @@ export async function readCoreArtifactMediaForDsh(artifactId, options = {}) {
     const result = await withReader((runtime) => runtime.run('inspect', ({ dataRoot }) =>
       readCoreArtifactBytes(dataRoot, id)), options.signal);
     if (!result.artifact.mediaType.startsWith('image/') && result.artifact.mediaType !== 'video/mp4'
-        && !result.artifact.mediaType.startsWith('audio/') && result.artifact.mediaType !== 'text/plain') {
-      throw new DshCoreAdapterError('IRIS_DSH_ARTIFACT_UNSUPPORTED', '当前 DSH 媒体预览只支持图片、mp4 视频、音频与纯文本 Artifact');
+        && result.artifact.mediaType !== 'video/webm' && !result.artifact.mediaType.startsWith('audio/')
+        && result.artifact.mediaType !== 'text/plain' && result.artifact.mediaType !== 'application/json') {
+      throw new DshCoreAdapterError('IRIS_DSH_ARTIFACT_UNSUPPORTED', '当前 DSH 媒体预览不支持此 Artifact 类型');
     }
     return result;
   } catch (error) {
@@ -568,10 +621,11 @@ export async function projectCoreTaskForDsh(host, taskId, options = {}) {
     }
     let attachment;
     try {
+      const extension = item.artifact.mediaType === 'image/jpeg' ? 'jpg' : item.artifact.mediaType.slice(6);
       attachment = await attachments.saveImage({
         data: new Uint8Array(item.bytes),
         mediaType: item.artifact.mediaType,
-        name: 'iris-core-' + item.artifact.id + '.png'
+        name: 'iris-core-' + item.artifact.id + '.' + extension
       });
     } catch (_) {
       throw new DshCoreAdapterError('IRIS_DSH_PROJECTION_FAILED', 'Core 产物无法保存为 DSH attachment');

package/lib/dsh-text-model-adapter.js

@@ -0,0 +1,222 @@
+'use strict';
+/** DSH textModel 的单轮协议映射；宿主路由/会话封闭在适配器，不进入共享请求。 */
+import crypto from 'node:crypto';
+import { ModelPortError, modelErrorRecord, normalizeModelDescriptor, normalizeModelCall,
+  normalizeModelCompletion, createModelTextCollector } from './model-port-contract.js';
+
+const OFF_IDS = new Set(['off', 'none', 'disabled', 'disable', 'no-thinking']);
+const validId = value => typeof value === 'string' && value.length > 0 && value.length <= 256
+  && value === value.trim() && !/[\u0000-\u001f\u007f]/.test(value) && !value.startsWith('/') && !value.includes('://');
+
+function abortError(signal, stage, invocation) {
+  const code = modelErrorRecord(signal?.reason).code === 'IRIS_MODEL_TIMEOUT' ? 'IRIS_MODEL_TIMEOUT' : 'IRIS_MODEL_ABORTED';
+  return new ModelPortError(code, { stage, invocation });
+}
+
+/** 信号传入底层；race 仅保证不合作的元数据/迭代器不会让本地永远挂住。 */
+async function wait(work, signal, stage, invocation) {
+  if (!signal) return work;
+  let onAbort;
+  const canceled = new Promise((_, reject) => {
+    onAbort = () => reject(abortError(signal, stage, invocation));
+    if (signal.aborted) onAbort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  });
+  try { return await Promise.race([work, canceled]); }
+  finally { signal.removeEventListener('abort', onAbort); }
+}
+
+function descriptorFor(binding, metadata, kind = 'text') {
+  const efforts = metadata?.reasoning?.efforts;
+  const ids = Array.isArray(efforts) ? [...new Set(efforts.map(value => value?.id).filter(validId))] : [];
+  const offId = ids.find(id => OFF_IDS.has(id.toLowerCase()));
+  const known = Array.isArray(efforts) && efforts.every(value => validId(value?.id));
+  return { descriptor: normalizeModelDescriptor({ contractVersion: 0, kind,
+    identity: { origin: 'host', backendId: 'dsh-' + kind + ':' + crypto.createHash('sha256').update(JSON.stringify([binding.provider, binding.model])).digest('hex'),
+      providerId: binding.provider, modelId: binding.model }, availability: 'available',
+    // 这些字段有明确的 DSH GenerateOptions 映射，不代表已证明远端模型能力。
+    features: { system: 'supported', temperature: 'supported', maxOutputTokens: 'supported', reasoning: known ? 'supported' : 'unknown' },
+    ...(known ? { reasoning: { off: offId ? 'supported' : 'unsupported', effortIds: ids } } : {}) }), offId: known ? offId : undefined };
+}
+
+function usageSnapshot(value) {
+  if (!value || typeof value !== 'object') return undefined;
+  const usage = {};
+  for (const key of ['outputTokens', 'totalTokens', 'reasoningTokens']) {
+    if (Number.isSafeInteger(value[key]) && value[key] >= 0) usage[key] = value[key];
+  }
+  // rc.2 inputTokens 不含缓存；这里只把权威的三个不重叠输入计数相加。
+  const inputs = [value.inputTokens, value.cacheReadTokens ?? 0, value.cacheWriteTokens ?? 0];
+  const inputTotal = inputs.reduce((sum, count) => sum + count, 0);
+  if (inputs.every(count => Number.isSafeInteger(count) && count >= 0) && Number.isSafeInteger(inputTotal)) usage.inputTokens = inputTotal;
+  return Object.keys(usage).length ? usage : undefined;
+}
+
+/** 元数据解析显式进行且受同一操作信号约束；describe 永远只复制已绑定事实。 */
+export async function prepareDshTextModelPort(textModel, binding, { signal } = {}) {
+  if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+  if (!textModel || typeof textModel.stream !== 'function') throw new ModelPortError('IRIS_MODEL_UNAVAILABLE');
+  if (!validId(binding?.provider) || !validId(binding?.model)) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+  const route = { provider: binding.provider, model: binding.model };
+  const sessionId = typeof binding.sessionId === 'string' && binding.sessionId.trim() && binding.sessionId.length <= 256 ? binding.sessionId.trim() : undefined;
+  let metadata;
+  if (typeof textModel.resolveModelInfo === 'function') {
+    try { metadata = await wait(Promise.resolve().then(() => {
+      if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+      return textModel.resolveModelInfo(route.provider, route.model, signal);
+    }), signal, 'prepare', 'not_invoked'); }
+    catch (_) { if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked'); }
+  }
+  if (signal?.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+  return createDshTextModelPort(textModel, { ...route, sessionId }, { metadata });
+}
+
+/** 已绑定事实的纯构造；用于缓存元数据/协议 fixture，不执行元数据查询。 */
+export function createDshTextModelPort(textModel, binding, { metadata } = {}) {
+  return createDshBoundModelPort(textModel, binding, { metadata });
+}
+
+/** 文本与视觉共用经过验证的 DSH 事件读取器；图片桥接仅由视觉适配器注入。 */
+export function createDshBoundModelPort(textModel, binding, { metadata, prepareImage, prepareImageRequest, kind = 'text' } = {}) {
+  if (!textModel || typeof textModel.stream !== 'function') throw new ModelPortError('IRIS_MODEL_UNAVAILABLE');
+  if (!validId(binding?.provider) || !validId(binding?.model)) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+  const route = { provider: binding.provider, model: binding.model };
+  // 不接受绑定身份与解析出的模型漂移；旧 fixture 未提供身份时保持 unknown。
+  if (metadata && (metadata.provider !== undefined && metadata.provider !== route.provider || metadata.id !== undefined && metadata.id !== route.model)) {
+    throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare', invocation: 'not_invoked' });
+  }
+  const sessionId = typeof binding.sessionId === 'string' && binding.sessionId.trim() && binding.sessionId.length <= 256 ? binding.sessionId.trim() : undefined;
+  const { descriptor, offId } = descriptorFor(route, metadata, kind);
+  const port = Object.freeze({
+    describe() { return normalizeModelDescriptor(descriptor); },
+    async complete(request, options) {
+      const input = normalizeModelCall(descriptor, request, options);
+      if (input.options.signal?.aborted) throw abortError(input.options.signal, 'invoke', 'not_invoked');
+      const controller = new AbortController();
+      const parent = input.options.signal;
+      const onAbort = () => controller.abort(parent.reason);
+      parent?.addEventListener('abort', onAbort, { once: true });
+      const deadline = performance.now() + input.options.budget.timeoutMs;
+      let timer;
+      const scheduleDeadline = () => {
+        const remaining = deadline - performance.now();
+        if (remaining <= 0) controller.abort(new ModelPortError('IRIS_MODEL_TIMEOUT'));
+        else timer = setTimeout(scheduleDeadline, Math.min(2147483647, Math.ceil(remaining)));
+      };
+      scheduleDeadline();
+      const signal = controller.signal;
+      const collector = createModelTextCollector({ maxOutputChars: input.options.budget.maxOutputChars, signal, backendId: descriptor.identity.backendId });
+      const sourceRequest = { ...route, messages: [{ role: 'user', content: [{ type: 'text', text: input.request.prompt }] }],
+        ...(input.request.system === undefined ? {} : { system: input.request.system }), signal,
+        ...(sessionId ? { sessionId } : {}) };
+      if (input.request.generation?.temperature !== undefined) sourceRequest.temperature = input.request.generation.temperature;
+      if (input.request.generation?.maxOutputTokens !== undefined) sourceRequest.maxTokens = input.request.generation.maxOutputTokens;
+      const reasoning = input.request.generation?.reasoning;
+      if (reasoning?.mode === 'off') sourceRequest.reasoningEffort = offId;
+      if (reasoning?.mode === 'effort') sourceRequest.reasoningEffort = reasoning.effortId;
+      let iterator;
+      let usage;
+      let finished = false;
+      let ended = false;
+      let invoked = false;
+      let responded = false;
+      let prepared;
+      const blocks = new Map();
+      const blockId = index => {
+        if (!Number.isSafeInteger(index) || index < 0) throw new ModelPortError('IRIS_MODEL_PROTOCOL_INVALID', { stage: 'read', invocation: 'unknown' });
+        return String(index);
+      };
+      try {
+        if (kind === 'vision') {
+          if (typeof prepareImage !== 'function') throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare' });
+          const preparedImage = await wait(Promise.resolve().then(() => {
+            if (signal.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+            return prepareImage(input.request.image, signal);
+          }), signal, 'prepare', 'not_invoked');
+          if (signal.aborted) throw abortError(signal, 'prepare', 'not_invoked');
+          prepared = await wait(Promise.resolve().then(() => prepareImageRequest?.({ request: input.request,
+            image: preparedImage.image, signal, identity: descriptor.identity })), signal, 'prepare', 'not_invoked');
+          const prompt = prepared?.prompt ?? input.request.prompt;
+          normalizeModelCall(descriptor, { ...input.request, image: preparedImage.image, prompt }, input.options);
+          sourceRequest.messages[0].content[0].text = prompt;
+          sourceRequest.messages[0].content.push({ type: 'image', attachment: preparedImage.attachment });
+        }
+        invoked = true;
+        const stream = textModel.stream(sourceRequest);
+        if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') throw new ModelPortError('IRIS_MODEL_PROTOCOL_INVALID', { stage: 'invoke', invocation: 'unknown' });
+        iterator = stream[Symbol.asyncIterator]();
+        while (true) {
+          const next = await wait(Promise.resolve().then(() => iterator.next()), signal, 'read', responded ? 'responded' : 'unknown');
+          if (signal.aborted) throw abortError(signal, 'read', responded ? 'responded' : 'unknown');
+          if (next.done) { ended = true; break; }
+          const chunk = next.value;
+          if (!chunk || typeof chunk !== 'object' || finished) throw new ModelPortError('IRIS_MODEL_PROTOCOL_INVALID', { stage: 'read', invocation: 'responded' });
+          if (chunk.type === 'block-start') {
+            const id = blockId(chunk.index);
+            if (!['text', 'reasoning'].includes(chunk.blockType)) collector.finish(chunk.blockType === 'tool-call' ? 'tool-calls' : 'unknown');
+            if (blocks.has(id)) collector.finish('unknown');
+            blocks.set(id, chunk.blockType);
+            if (chunk.blockType === 'text') collector.append('', id);
+          } else if (chunk.type === 'text-delta') {
+            const id = blockId(chunk.index);
+            if (blocks.has(id) && blocks.get(id) !== 'text') collector.finish('unknown');
+            blocks.set(id, 'text');
+            if (typeof chunk.text === 'string' && chunk.text.length) responded = true;
+            collector.append(chunk.text, id);
+          } else if (chunk.type === 'reasoning-delta') {
+            const id = blockId(chunk.index);
+            if (typeof chunk.text !== 'string' || blocks.has(id) && blocks.get(id) !== 'reasoning') collector.finish('unknown');
+            blocks.set(id, 'reasoning');
+          } else if (chunk.type === 'block-end') {
+            const id = blockId(chunk.index);
+            if (chunk.block?.type === 'text') {
+              if (blocks.has(id) && blocks.get(id) !== 'text') collector.finish('unknown');
+              blocks.set(id, 'text');
+              if (typeof chunk.block.text === 'string' && chunk.block.text.length) responded = true;
+              collector.replace(chunk.block.text, id);
+            } else if (chunk.block?.type === 'reasoning') {
+              if (typeof chunk.block.text !== 'string' || blocks.has(id) && blocks.get(id) !== 'reasoning') collector.finish('unknown');
+              blocks.set(id, 'reasoning');
+            } else collector.finish(chunk.block?.type === 'tool-call' ? 'tool-calls' : 'unknown');
+          } else if (chunk.type === 'tool-call-delta') collector.finish('tool-calls');
+          else if (chunk.type === 'usage') usage = usageSnapshot(chunk.usage);
+          else if (chunk.type === 'finish') {
+            const kind = chunk.reason?.kind;
+            if (kind === 'aborted') throw new ModelPortError('IRIS_MODEL_ABORTED', { stage: 'read', invocation: responded ? 'responded' : 'unknown' });
+            if (kind === 'error') collector.fail(new ModelPortError('IRIS_MODEL_REQUEST_FAILED', { stage: 'read', invocation: 'unknown' }));
+            collector.finish(kind); finished = true;
+          } else if (chunk.type === 'error') collector.fail(chunk.error);
+          else if (chunk.type === undefined && typeof chunk.delta === 'string') {
+            if (chunk.delta.length) responded = true;
+            collector.append(chunk.delta, '0');
+          }
+          else collector.finish('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 abortError(signal, invoked ? 'read' : 'prepare', responded ? 'responded' : invoked ? 'unknown' : 'not_invoked');
+        if (!invoked) {
+          controller.abort(error);
+          const record = modelErrorRecord(error);
+          throw new ModelPortError(record.code, { stage: 'prepare', invocation: 'not_invoked',
+            ...(record.imageBytes ? { imageBytes: record.imageBytes } : {}),
+            ...(record.imageMaxBytes ? { imageMaxBytes: record.imageMaxBytes } : {}) });
+        }
+        // 只有受控模型错误可以离开协议边界；供应商原文不进入 UI/日志。
+        try { collector.fail(error); }
+        finally { controller.abort(error); }
+      } finally {
+        try {
+          if (!ended && iterator && typeof iterator.return === 'function') {
+            const closing = Promise.resolve().then(() => iterator.return());
+            await wait(closing, signal, 'read', 'unknown').catch(() => {});
+          }
+        } finally { clearTimeout(timer); parent?.removeEventListener('abort', onAbort); }
+      }
+    }
+  });
+  return Object.freeze({ port, offId });
+}

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

@@ -0,0 +1,75 @@
+'use strict';
+import { ModelPortError } from './model-port-contract.js';
+import { createDshBoundModelPort } from './dsh-text-model-adapter.js';
+import { waitForModelWork } from './model-call-runtime.js';
+import { createHash } from 'node:crypto';
+import sharp from 'sharp';
+import { prepareVisionImage } from './vision-image-input.js';
+
+/** rc.2 只接受附件引用；业务钩子使用核验后真正发给宿主的图片。 */
+export function createDshVisionModelPort(textModel, attachments, binding, { metadata, allowImageNormalization = false,
+  imageInput, orientImages = false, prepareImageRequest } = {}) {
+  if (!attachments || typeof attachments.saveImage !== 'function' || typeof attachments.readImage !== 'function') {
+    throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare' });
+  }
+  if (!metadata || metadata.provider !== binding?.provider || metadata.id !== binding?.model
+      || !Array.isArray(metadata.inputModalities) || !metadata.inputModalities.includes('image')) {
+    throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare' });
+  }
+  return createDshBoundModelPort(textModel, binding, { metadata, kind: 'vision', prepareImageRequest,
+    async prepareImage(image, signal) {
+      if (imageInput) image = await prepareVisionImage(image, imageInput, { signal, orient: orientImages });
+      const data = new Uint8Array(image.bytes);
+      // saveImage 在 rc.2 无取消参数；等待有界，迟到保存可留下 Host 附件，但绝不启动生成。
+      const ref = await waitForModelWork(() => attachments.saveImage({ data, mediaType: image.mediaType, name: 'iris-vision' }), signal);
+      if (!ref || typeof ref.attachmentId !== 'string' || !ref.attachmentId) {
+        throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare' });
+      }
+      const stored = await waitForModelWork(() => attachments.readImage(ref, signal), signal);
+      if (!(stored?.data instanceof Uint8Array) || stored.mediaType !== undefined && stored.mediaType !== ref.mediaType) {
+        throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare' });
+      }
+      const unchanged = ref.mediaType === image.mediaType && Buffer.from(stored.data).equals(Buffer.from(image.bytes));
+      if (!unchanged) {
+        // 正规宿主附件用内容哈希绑定读回字节；任意旧引用/损坏数据不能冒充压缩副本。
+        if (!allowImageNormalization || ref.attachmentId !== 'sha256:' + createHash('sha256').update(stored.data).digest('hex')
+            || ref.bytes !== stored.data.byteLength) throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare' });
+        const [source, normalized] = await waitForModelWork(() => Promise.all([
+          sharp(Buffer.from(image.bytes)).metadata(), sharp(Buffer.from(stored.data)).metadata()
+        ]), signal);
+        const original = ref.originalDimensions || ref;
+        const width = source.autoOrient?.width || source.width, height = source.autoOrient?.height || source.height;
+        if (original.width !== width || original.height !== height || ref.width !== normalized.width || ref.height !== normalized.height
+            || ref.width > width || ref.height > height
+            || ref.mediaType !== { jpeg: 'image/jpeg', png: 'image/png', webp: 'image/webp', gif: 'image/gif' }[normalized.format]) {
+          throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE', { stage: 'prepare' });
+        }
+      }
+      return { attachment: ref, image: { bytes: new Uint8Array(stored.data), mediaType: ref.mediaType } };
+    }
+  }).port;
+}
+
+/** 只在显式调用时读取默认选择/精确元数据；不把默认文本模型猜成视觉模型。 */
+export async function prepareDshVisionModelPort(textModel, attachments, { signal, ...options } = {}) {
+  try { return await waitForModelWork(async () => {
+    if (typeof textModel?.currentSelection !== 'function' || typeof textModel?.resolveModelInfo !== 'function') {
+      throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare' });
+    }
+    if (typeof attachments?.saveImage !== 'function' || typeof attachments?.readImage !== 'function') {
+      throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare' });
+    }
+    const selection = textModel.currentSelection();
+    if (typeof selection?.provider !== 'string' || !selection.provider.trim()
+        || typeof selection?.model !== 'string' || !selection.model.trim()) {
+      throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare' });
+    }
+    const binding = { provider: selection.provider, model: selection.model };
+    const metadata = await waitForModelWork(() => textModel.resolveModelInfo(binding.provider, binding.model, signal), signal);
+    return createDshVisionModelPort(textModel, attachments, binding, { metadata, ...options });
+  }, signal); }
+  catch (error) {
+    if (error instanceof ModelPortError) throw error;
+    throw new ModelPortError('IRIS_MODEL_REQUEST_FAILED', { stage: 'prepare', invocation: 'not_invoked' });
+  }
+}

package/lib/generation-input.js

@@ -1,10 +1,11 @@
 'use strict';
 
 import path from 'node:path';
+import fs from 'node:fs';
 
 const FIELDS = Object.freeze({
-  image: ['prompt', 'size', 'n'],
-  video: ['prompt', 'size', 'duration', 'img_data_url'],
+  image: ['prompt', 'size', 'n', 'source_artifact_id'],
+  video: ['prompt', 'size', 'duration', 'img_data_url', 'first_frame_path', 'audio_path', 'resolution'],
   tts: ['text', 'voice'],
   transcribe: ['audio_url', 'audio_path']
 });
@@ -33,7 +34,7 @@ function text(value, field, maxLength, required = false) {
  * 不读取配置或文件，不上传，不从旧 Task 恢复 Prompt/媒体地址。
  * Host 附件解析和本地音频上传仍由入口负责。
  */
-export function normalizeGenerationInput(capability, input, { allowAudioPath = false } = {}) {
+export function normalizeGenerationInput(capability, input, { allowAudioPath = false, allowVideoPaths = false } = {}) {
   const fields = Object.hasOwn(FIELDS, capability) ? FIELDS[capability] : null;
   if (!fields) fail('不支持的生成能力');
   if (!input || typeof input !== 'object' || Array.isArray(input)) fail('生成输入必须是 JSON 对象');
@@ -45,12 +46,40 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
   const modelRef = String(input.model_ref || '').trim();
   const providerInput = {};
   let audioPath;
+  let sourceArtifactId;
+  let firstFramePath, videoMode;
+  if (capability === 'video') {
+    audioPath = String(input.audio_path || '').trim();
+    firstFramePath = String(input.first_frame_path || '').trim();
+    if ((audioPath || firstFramePath) && !allowVideoPaths) fail('本地视频输入需要支持上传的入口');
+    if (firstFramePath && input.img_data_url !== undefined) fail('首帧路径与 img_data_url 不能同时提供');
+    for (const file of [firstFramePath, audioPath].filter(Boolean)) {
+      if (!path.isAbsolute(file)) fail('首帧和音频路径必须是绝对路径');
+      try { if (!fs.statSync(file).isFile()) throw new Error(); }
+      catch (_) { fail('首帧或音频文件不存在或不是普通文件'); }
+    }
+    if (audioPath && !firstFramePath) fail('s2v 需要 first_frame_path 和 audio_path');
+    videoMode = audioPath ? 's2v' : firstFramePath || input.img_data_url ? 'i2v' : 't2v';
+    if (videoMode === 's2v') {
+      if (input.size !== undefined || input.duration !== undefined || input.img_data_url !== undefined) fail('s2v 不支持 size、duration 或 img_data_url');
+      const resolution = input.resolution ?? '480P';
+      if (!['480P', '720P'].includes(resolution)) fail('s2v resolution 只支持 480P 或 720P');
+      providerInput.resolution = resolution;
+    } else if (input.resolution !== undefined) fail('resolution 仅适用于 s2v');
+  }
   if (capability === 'image' || capability === 'video') {
-    providerInput.prompt = text(input.prompt, 'prompt', 20000, true);
+    const prompt = text(input.prompt, 'prompt', 20000, videoMode !== 's2v');
+    if (prompt !== undefined) providerInput.prompt = prompt;
     const size = text(input.size, 'size', 64);
     if (size !== undefined) providerInput.size = size;
   }
   if (capability === 'image') {
+    if (input.source_artifact_id !== undefined) {
+      if (typeof input.source_artifact_id !== 'string' || !/^artifact_[a-f0-9]{24}$/.test(input.source_artifact_id)) {
+        fail('source_artifact_id 必须是有效的 Core Artifact ID');
+      }
+      sourceArtifactId = input.source_artifact_id;
+    }
     const n = input.n === undefined ? 1 : Number(input.n);
     if (!Number.isSafeInteger(n) || n < 1 || n > 4) fail('n 必须为 1–4 的整数');
     providerInput.n = n;
@@ -90,6 +119,8 @@ export function normalizeGenerationInput(capability, input, { allowAudioPath = f
   return Object.freeze({
     modelRef,
     providerInput: Object.freeze(providerInput),
-    ...(audioPath ? { audioPath } : {})
+    ...(sourceArtifactId ? { sourceArtifactId } : {}),
+    ...(audioPath ? { audioPath } : {}),
+    ...(capability === 'video' ? { firstFramePath, videoMode } : {})
   });
 }