@mokuyoaxis/dsh-iris 0.2.5 → 0.2.7

package/lib/dsh-host-adapter.js

@@ -5,6 +5,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { defineHostAdapter } from './host-contract.js';
 import { BrowserHtmlRenderer } from './render.js';
+import { resolveRenderAddress } from './render-address.js';
+import { createDshProviderSource } from './dsh-provider-source.js';
 
 export function detectDshVersion({ entry = process.argv[1] } = {}) {
   if (!entry) return 'unknown';
@@ -159,8 +161,10 @@ export function createDshHostAdapter(ctx, { version = detectDshVersion() } = {})
 
   const browser = service(ctx, 'browser');
   if (browser && ['open', 'openUrl', 'screenshot', 'close'].every((name) => typeof browser[name] === 'function')) {
-    const renderer = new BrowserHtmlRenderer({ browser });
+    const getAddress = () => resolveRenderAddress(service(ctx, 'webServer') || service(ctx, 'httpServer'));
+    const renderer = new BrowserHtmlRenderer({ browser, getAddress });
     ports.browser = Object.freeze({
+      get address() { return getAddress(); },
       async renderHtml(input) {
         const { png } = await renderer.render(input);
         return { bytes: new Uint8Array(png), mediaType: 'image/png' };
@@ -201,6 +205,15 @@ export function createDshHostAdapter(ctx, { version = detectDshVersion() } = {})
   } else unavailable.skills = unavailableFor(skills, 'DSH Skill registry 需要 register');
 
   const llm = service(ctx, 'llm');
+  const settings = service(ctx, 'settings');
+  if (typeof llm?.listProviders === 'function' && typeof llm?.listConfigurableProviders === 'function'
+      && typeof settings?.describe === 'function') {
+    ports.providerConnections = createDshProviderSource(() => ({
+      llm: service(ctx, 'llm'), settings: service(ctx, 'settings'), credentials: service(ctx, 'credentials')
+    }));
+  } else unavailable.providerConnections = {
+    kind: 'unavailable', reason: '当前 DSH 未提供供应商连接目录与设置接口，可继续手动添加供应商'
+  };
   const defaults = service(ctx, 'agentDefaultModel');
   if (llm && typeof llm.stream === 'function') {
     ports.textModel = Object.freeze({

package/lib/dsh-provider-config.js

@@ -0,0 +1,35 @@
+import { allProviders } from './config.js';
+import { hasProviderConfigScope, withProviderConfigScope } from './provider-config-scope.js';
+import { DshProviderSourceError } from './dsh-provider-source.js';
+
+export function normalizeDshProvider(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+      || typeof value.provider !== 'string' || !value.provider.trim()
+      || typeof value.settingsNs !== 'string' || !value.settingsNs.trim()
+      || Object.keys(value).some(key => !['provider', 'settingsNs'].includes(key))) {
+    throw Object.assign(new Error('DSH 连接引用需要 provider 和 settingsNs'), { code: 'IRIS_CONFIG_INPUT_INVALID' });
+  }
+  return { provider: value.provider.trim(), settingsNs: value.settingsNs.trim() };
+}
+
+/** Existing request handlers see resolved copies; the persistent store stays raw. */
+export async function withDshProviderConfig(host, callback, { signal, fresh = false } = {}) {
+  if (!fresh && hasProviderConfigScope()) return callback();
+  const providers = allProviders();
+  if (!providers.some(provider => provider.dshProvider)) return callback();
+  const resolved = await Promise.all(providers.map(async provider => {
+    if (!provider.dshProvider || provider.enabled === false) return provider;
+    try {
+      if (typeof host?.ports?.providerConnections?.resolve !== 'function') {
+        throw new DshProviderSourceError('当前宿主无法解析 DSH 连接，请检查原连接或改用手动供应商');
+      }
+      const value = await host.ports.providerConnections.resolve(provider.dshProvider, { signal });
+      return { ...provider, baseUrl: value.baseUrl, apiKey: value.apiKey };
+    } catch (error) {
+      if (!(error instanceof DshProviderSourceError)) throw error;
+      return { ...provider, enabled: false, connectionError: error.message };
+    }
+  }));
+  signal?.throwIfAborted();
+  return withProviderConfigScope(resolved, callback);
+}

package/lib/dsh-provider-source.js

@@ -0,0 +1,102 @@
+/** Read only public DSH services; never open profile or credential files. */
+export class DshProviderSourceError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DshProviderSourceError';
+    this.code = 'IRIS_DSH_PROVIDER_UNAVAILABLE';
+  }
+}
+
+const unavailable = message => { throw new DshProviderSourceError(message); };
+const refName = value => typeof value === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+const recordId = value => typeof value === 'string' && /^[a-z][a-z0-9-]*$/.test(value);
+
+async function credentialRead(read) {
+  try { return await read(); }
+  catch (_) { unavailable('DSH 凭据服务读取失败，请在宿主检查该连接'); }
+}
+
+function endpoint(value) {
+  let url;
+  try { url = new URL(value); } catch (_) { unavailable('DSH 连接没有可复用的 HTTP(S) 地址'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    unavailable('DSH 连接地址包含不支持的协议或凭据参数');
+  }
+  return url.href.replace(/\/+$/, '');
+}
+
+export function createDshProviderSource(services) {
+  function entries() {
+    const { llm, settings, credentials } = services();
+    if (typeof llm?.listProviders !== 'function' || typeof llm?.listConfigurableProviders !== 'function'
+        || typeof settings?.describe !== 'function') {
+      unavailable('当前 DSH 未提供连接目录与设置接口，请手动添加 Iris 供应商');
+    }
+    const active = new Set(llm.listProviders().map(provider => provider.id));
+    const forms = settings.describe({ redactSecrets: true });
+    return llm.listConfigurableProviders().filter(entry => active.has(entry.provider)).map(entry => {
+      let profile = forms.find(form => form.ns === entry.settingsNs)?.value;
+      for (const key of entry.settingsPath) profile = profile && Object.hasOwn(profile, key) ? profile[key] : undefined;
+      return { entry, profile, credentials };
+    });
+  }
+
+  async function facts({ entry, profile, credentials }) {
+    if (!profile || typeof profile !== 'object' || Array.isArray(profile)) unavailable('DSH 连接设置不可读取');
+    if (profile.headers && Object.keys(profile.headers).length) unavailable('该 DSH 连接含自定义请求头，当前请手动配置 Iris 供应商');
+    const baseUrl = endpoint(profile.baseURL || entry.defaultBaseURL);
+    if (!credentials) unavailable('当前 DSH 没有凭据解析服务，请手动配置 Iris 供应商');
+    if (profile.apiKeyEnv !== undefined) {
+      if (!refName(profile.apiKeyEnv) || typeof credentials.describe !== 'function'
+          || typeof credentials.resolve !== 'function') unavailable('DSH 凭据引用不可用');
+      if (!(await credentialRead(() => credentials.describe(profile.apiKeyEnv))).configured) unavailable('DSH 连接尚未配置可用密钥');
+      return { baseUrl, ref: profile.apiKeyEnv };
+    }
+    // This is the documented api-key record space owned by llm-pi-ai.
+    if (entry.settingsNs === 'llm-pi-ai' && recordId(entry.provider)
+        && typeof credentials.describeRecord === 'function' && typeof credentials.readRecord === 'function') {
+      const key = 'llm-pi-ai/' + entry.provider;
+      const info = await credentialRead(() => credentials.describeRecord(key));
+      if (info.configured) {
+        if (info.kind !== 'api-key') unavailable('该 DSH 连接使用登录授权，当前不支持将其用于媒体请求');
+        return { baseUrl, recordKey: key };
+      }
+    }
+    for (const ref of entry.nativeAuth?.env || []) {
+      if (refName(ref) && typeof credentials.describe === 'function' && typeof credentials.resolve === 'function'
+          && (await credentialRead(() => credentials.describe(ref))).configured) return { baseUrl, ref };
+    }
+    unavailable('该 DSH 连接没有可复用的 API Key；登录授权和专有认证需单独适配');
+  }
+
+  async function list() {
+    return Promise.all(entries().map(async source => {
+      const { entry } = source;
+      const common = { provider: entry.provider, settingsNs: entry.settingsNs, name: entry.displayName || entry.provider };
+      try { return { ...common, baseUrl: (await facts(source)).baseUrl, available: true }; }
+      catch (error) {
+        if (!(error instanceof DshProviderSourceError)) throw error;
+        return { ...common, available: false, reason: error.message };
+      }
+    }));
+  }
+
+  async function resolve(reference, { signal } = {}) {
+    signal?.throwIfAborted();
+    const source = entries().find(({ entry }) => entry.provider === reference.provider && entry.settingsNs === reference.settingsNs);
+    if (!source) unavailable('DSH 原连接已停用、移除或改变来源，请检查宿主供应商设置');
+    const plan = await facts(source);
+    let key;
+    if (plan.ref) key = (await credentialRead(() => source.credentials.resolve(plan.ref)))?.value;
+    else {
+      const record = await credentialRead(() => source.credentials.readRecord(plan.recordKey));
+      if (record?.kind === 'api-key') key = record.key;
+    }
+    signal?.throwIfAborted();
+    if (typeof key !== 'string' || !key.trim() || /[\r\n]/.test(key)) unavailable('DSH 原连接没有可用于媒体请求的 API Key');
+    // Even accidental JSON serialization of this Host-only result excludes the key.
+    return Object.freeze(Object.defineProperty({ baseUrl: plan.baseUrl }, 'apiKey', { value: key }));
+  }
+
+  return Object.freeze({ list, resolve });
+}

package/lib/flow-store.js

@@ -0,0 +1,195 @@
+'use strict';
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomicCreatePrivate, atomicWritePrivate } from './private-storage.js';
+import { WRITER_LEASE_DIR, WRITER_INTENT_FILE } from './core-writer-lease.js';
+import { normalizeGenerationInput } from './generation-input.js';
+import { parseModelRef } from './models.js';
+
+const RUN = /^run_[a-f0-9]{24}$/;
+const TASK = /^task_[a-f0-9]{24}$/;
+const ARTIFACT = /^artifact_[a-f0-9]{24}$/;
+const SHA = /^[a-f0-9]{64}$/;
+const BINDING = /^sha256:[a-f0-9]{64}$/;
+const RECIPE = 'image-edit/v0';
+
+export class FlowError extends Error {
+  constructor(code, message) { super(message); this.name = 'FlowError'; this.code = code; }
+}
+export function flowFail(code, message) { throw new FlowError(code, message); }
+
+function keys(value, allowed, required = allowed) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).every(key => allowed.includes(key)) && required.every(key => Object.hasOwn(value, key)));
+}
+function iso(value) { return typeof value === 'string' && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value; }
+const copy = value => Object.freeze(structuredClone(value));
+export const flowId = prefix => prefix + '_' + crypto.randomBytes(12).toString('hex');
+export const flowSha256 = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+
+export function validFlowBinding(value) {
+  return keys(value, ['runId', 'stepId', 'inputDigest']) && RUN.test(value.runId)
+    && value.stepId === 'edit' && BINDING.test(value.inputDigest);
+}
+export function flowTaskBinding(run) { return { runId: run.id, stepId: 'edit', inputDigest: run.inputDigest }; }
+
+function inputDigest(run) {
+  return 'sha256:' + flowSha256(JSON.stringify([RECIPE, run.source.artifactId, run.source.sha256,
+    run.input.model_ref, run.providerBinding, run.input.prompt, run.input.size ?? null, 1]));
+}
+
+function reference(value) { return keys(value, ['artifactId', 'sha256']) && ARTIFACT.test(value.artifactId) && SHA.test(value.sha256); }
+function validate(run, expectedId) {
+  let normalized;
+  try { normalized = normalizeGenerationInput('image', run?.input); }
+  catch (_) { flowFail('IRIS_FLOW_RECORD_INVALID', '流程创作输入无效'); }
+  if (!keys(run, ['schemaVersion', 'recipe', 'id', 'revision', 'createdAt', 'updatedAt', 'source', 'input', 'providerBinding',
+    'inputDigest', 'edit', 'compare', 'output', 'comparison', 'selection'],
+  ['schemaVersion', 'recipe', 'id', 'revision', 'createdAt', 'updatedAt', 'source', 'input', 'providerBinding', 'inputDigest', 'edit', 'compare'])
+      || run.schemaVersion !== 0 || run.recipe !== RECIPE || !RUN.test(run.id) || run.id !== expectedId
+      || !Number.isSafeInteger(run.revision) || run.revision < 1 || !iso(run.createdAt) || !iso(run.updatedAt)
+      || !reference(run.source) || !BINDING.test(run.providerBinding)
+      || !parseModelRef(run.input.model_ref) || normalized.modelRef !== run.input.model_ref
+      || run.input.prompt !== normalized.providerInput.prompt || run.input.n !== 1
+      || (run.input.size !== undefined && run.input.size !== normalized.providerInput.size)
+      || normalized.sourceArtifactId !== run.source.artifactId
+      || !keys(run.edit, ['taskId', 'claimed']) || !TASK.test(run.edit.taskId) || typeof run.edit.claimed !== 'boolean'
+      || !keys(run.compare, ['artifactId']) || !ARTIFACT.test(run.compare.artifactId)
+      || run.compare.artifactId === run.source.artifactId || run.inputDigest !== inputDigest(run)
+      || (run.output !== undefined && (!reference(run.output) || !run.edit.claimed
+        || [run.source.artifactId, run.compare.artifactId].includes(run.output.artifactId)))
+      || (run.comparison !== undefined && (!reference(run.comparison) || !run.output || run.comparison.artifactId !== run.compare.artifactId))
+      || (run.selection !== undefined && (!reference(run.selection) || !run.comparison
+        || ![run.source, run.output].some(item => item.artifactId === run.selection.artifactId && item.sha256 === run.selection.sha256)))) {
+    flowFail('IRIS_FLOW_RECORD_INVALID', '流程记录结构或绑定摘要冲突');
+  }
+  return run;
+}
+
+function directory(root, leaf, create = false) {
+  let current = root;
+  for (const segment of ['flow-store', 'v0', ...(leaf ? [leaf] : [])]) {
+    current = path.join(current, segment);
+    if (create && !fs.existsSync(current)) fs.mkdirSync(current, { mode: 0o700 });
+    const stat = fs.lstatSync(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) flowFail('IRIS_FLOW_STORE_UNSAFE', '流程存储目录不安全');
+  }
+  return current;
+}
+function jsonFile(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 128 * 1024) flowFail('IRIS_FLOW_RECORD_INVALID', '流程记录不是受支持的普通文件');
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (_) { flowFail('IRIS_FLOW_RECORD_INVALID', '流程记录不是有效 JSON'); }
+}
+
+export function inspectFlowRoot(root) {
+  let marker;
+  try { marker = jsonFile(path.join(directory(root), 'root.json')); }
+  catch (error) {
+    if (error.code === 'ENOENT') flowFail('IRIS_FLOW_ROOT_REQUIRED', '请先在新的专用数据根执行 flow init，再导入图片');
+    throw error;
+  }
+  if (!keys(marker, ['schemaVersion', 'kind', 'createdAt']) || marker.schemaVersion !== 0
+      || marker.kind !== 'iris-image-flow-root' || !iso(marker.createdAt)) flowFail('IRIS_FLOW_RECORD_INVALID', '流程根声明无效或版本不受支持');
+  directory(root, 'runs');
+  return copy(marker);
+}
+
+export function initializeFlowRoot(root) {
+  try { fs.lstatSync(path.join(root, 'flow-store')); return inspectFlowRoot(root); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (fs.readdirSync(root).some(name => ![WRITER_LEASE_DIR, WRITER_INTENT_FILE].includes(name))) {
+    flowFail('IRIS_FLOW_ROOT_NOT_EMPTY', '流程只在新的专用数据根启用；不迁移已有 Task/Artifact 数据根');
+  }
+  directory(root, 'runs', true);
+  const marker = { schemaVersion: 0, kind: 'iris-image-flow-root', createdAt: new Date().toISOString() };
+  atomicCreatePrivate(path.join(directory(root), 'root.json'), JSON.stringify(marker, null, 2) + '\n');
+  return copy(marker);
+}
+
+function recordFile(root, id) {
+  if (typeof id !== 'string' || !RUN.test(id)) flowFail('IRIS_FLOW_ID_INVALID', 'Run ID 格式无效');
+  return path.join(directory(root, 'runs'), id + '.json');
+}
+export function readFlowRun(root, id) {
+  inspectFlowRoot(root);
+  let record;
+  try { record = jsonFile(recordFile(root, id)); }
+  catch (error) {
+    if (error.code === 'ENOENT') flowFail('IRIS_FLOW_NOT_FOUND', '流程记录不存在');
+    throw error;
+  }
+  return copy(validate(record, id));
+}
+
+/** Internal immutable creation intent; HTTP callers cannot choose these identities. */
+export function prepareFlowCreation({ source, input, providerBinding }) {
+  return { runId: flowId('run'), taskId: flowId('task'), comparisonArtifactId: flowId('artifact'),
+    createdAt: new Date().toISOString(), source, input, providerBinding };
+}
+
+export function validateFlowCreation(intent) {
+  if (!keys(intent, ['runId', 'taskId', 'comparisonArtifactId', 'createdAt', 'source', 'input', 'providerBinding'])) {
+    flowFail('IRIS_FLOW_RECORD_INVALID', '流程创建意图无效');
+  }
+  const record = { schemaVersion: 0, recipe: RECIPE, id: intent.runId, revision: 1,
+    createdAt: intent.createdAt, updatedAt: intent.createdAt, source: intent.source, input: intent.input,
+    providerBinding: intent.providerBinding, edit: { taskId: intent.taskId, claimed: false },
+    compare: { artifactId: intent.comparisonArtifactId } };
+  record.inputDigest = inputDigest(record);
+  return validate(record, record.id);
+}
+
+export function commitFlowCreation(root, intent, { allowCreate = true } = {}) {
+  inspectFlowRoot(root);
+  const record = validateFlowCreation(intent);
+  let current;
+  try { current = readFlowRun(root, record.id); }
+  catch (error) { if (error.code !== 'IRIS_FLOW_NOT_FOUND') throw error; }
+  if (current) {
+    if (current.createdAt !== record.createdAt || current.inputDigest !== record.inputDigest
+        || current.edit.taskId !== record.edit.taskId || current.compare.artifactId !== record.compare.artifactId) {
+      flowFail('IRIS_FLOW_INPUT_CONFLICT', '原流程与预留创建身份不一致');
+    }
+    return current;
+  }
+  if (!allowCreate) flowFail('IRIS_FLOW_NOT_FOUND', '原流程记录已不可用');
+  atomicCreatePrivate(recordFile(root, record.id), JSON.stringify(record, null, 2) + '\n');
+  return copy(record);
+}
+
+export function createFlowRun(root, input) {
+  return commitFlowCreation(root, prepareFlowCreation(input));
+}
+
+export function updateFlowRun(root, previous, patch) {
+  const current = readFlowRun(root, previous.id);
+  if (current.revision !== previous.revision) flowFail('IRIS_FLOW_REVISION_CONFLICT', '流程在本次操作期间已改变');
+  if (!keys(patch, ['edit', 'output', 'comparison', 'selection'], [])) throw new TypeError('未知流程更新字段');
+  const record = { ...current, ...patch, revision: current.revision + 1, updatedAt: new Date().toISOString() };
+  validate(record, current.id);
+  atomicWritePrivate(recordFile(root, record.id), JSON.stringify(record, null, 2) + '\n');
+  return copy(record);
+}
+
+export function listFlowRuns(root) {
+  inspectFlowRoot(root);
+  const records = [];
+  for (const name of fs.readdirSync(directory(root, 'runs'))) {
+    if (/^run_[a-f0-9]{24}\.json\.tmp-[1-9][0-9]*-[a-f0-9]{12}$/.test(name)) continue; // 保留未发布的原子写现场。
+    if (!/^run_[a-f0-9]{24}\.json$/.test(name)) flowFail('IRIS_FLOW_RECORD_INVALID', '流程目录包含未知记录，停止盘点');
+    records.push(readFlowRun(root, name.slice(0, -5)));
+  }
+  return records.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+
+/** 管理入口不能忽略损坏/未知的流程根，从而丢掉引用。普通 Core 根保持零写。 */
+export function flowReferences(root) {
+  try { fs.lstatSync(path.join(root, 'flow-store')); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  return listFlowRuns(root).map(run => ({ run, taskIds: [run.edit.taskId],
+    artifactIds: [...new Set([run.source.artifactId, run.compare.artifactId, run.output?.artifactId, run.selection?.artifactId].filter(Boolean))] }));
+}

package/lib/headless-vision.js

@@ -70,9 +70,9 @@ function completionResult(completion, routes) {
   return { ...result, ...selectedModel(completion, routes) };
 }
 
-async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit }) {
+async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit, onModelAvailability }) {
   const routes = transcribeCandidatesFromCatalog(catalog, input.transcribe_model_ref);
-  const candidates = routes.map(route => ({ adapter: createConfiguredProviderAdapter(route.provider, { onRateLimit }),
+  const candidates = routes.map(route => ({ adapter: createConfiguredProviderAdapter(route.provider, { onRateLimit, onModelAvailability }),
     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(() => {}); };
@@ -111,7 +111,7 @@ async function transcribeVideo({ catalog, input, runtime, operation, onRateLimit
   }
 }
 
-export async function executeVisionCommand({ command, input, catalog, modelRef = '', runtime, signal, timeoutMs = VISION_BUDGET.timeoutMs, onRateLimit }) {
+export async function executeVisionCommand({ command, input, catalog, modelRef = '', runtime, signal, timeoutMs = VISION_BUDGET.timeoutMs, onRateLimit, onModelAvailability }) {
   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 的整数');
@@ -121,7 +121,7 @@ export async function executeVisionCommand({ command, input, 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,
+  const ports = routes.map(route => createConfiguredVisionModelPort(route.provider, route.model, { onRateLimit, onModelAvailability,
     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 } });
@@ -140,7 +140,7 @@ export async function executeVisionCommand({ command, input, catalog, modelRef =
       }
       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: '' };
+        const asr = meta.hasAudio ? await transcribeVideo({ catalog, input, runtime, operation, onRateLimit, onModelAvailability }) : { report: { status: 'no_audio' }, text: '' };
         transcript = asr.text; transcription = asr.report;
       }
       const completion = await summarizeMedia({ ports, frames, question: input.question, transcript, operation, budget });

package/lib/host-contract.js

@@ -13,6 +13,7 @@ export const HOST_PORTS = Object.freeze([
   'attachments',
   'browser',
   'clientSlots',
+  'providerConnections',
   'routes',
   'sessions',
   'skills',

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

@@ -5,6 +5,7 @@ import { ModelPortError, normalizeModelDescriptor, normalizeModelCall, normalize
 import { modelCallScope, modelAbortError, waitForModelWork } from './model-call-runtime.js';
 import { createHash } from 'node:crypto';
 import { isFreeQuotaExhausted, retryAfterDelay } from './provider-health.js';
+import { isModelNotFound } from './model-directory.js';
 import { prepareVisionImage } from './vision-image-input.js';
 
 const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -103,7 +104,7 @@ export function createHttpVisionModelPort({ providerId, modelId, baseUrl, apiKey
           });
         }, 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;
+          const body = [400, 403, 404, 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;
@@ -114,10 +115,12 @@ export function createHttpVisionModelPort({ providerId, modelId, baseUrl, apiKey
               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'
+          const missing = isModelNotFound({ status: response.status, ...(body?.error || body) });
+          const code = missing ? 'IRIS_MODEL_UNAVAILABLE' : 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 (missing) error.providerCode = 'model_not_found';
           if (response.status === 429) error.retryAfterMs = retryAfterDelay(response.headers.get('retry-after'));
           if (quota) error.quotaExhausted = true;
           throw error;

package/lib/image-flow.js

@@ -0,0 +1,188 @@
+'use strict';
+
+import { createCoreArtifact, exportCoreArtifact, readCoreArtifactBytes } from './core-artifacts.js';
+import { assertFlowTaskMatches, claimFlowTask, findFlowTask, recoverCoreTask } from './core-tasks.js';
+import { deliveryCacheNeedsProvider } from './core-delivery-cache.js';
+import { normalizeGenerationInput } from './generation-input.js';
+import { imageEditCandidates, readImageEditArtifact } from './image-edit-input.js';
+import { parseModelRef } from './models.js';
+import { pixelDiff } from './pixels.js';
+import { createProviderTaskRunner } from './provider-task-runner.js';
+import { commitFlowCreation, flowFail, flowSha256, initializeFlowRoot, inspectFlowRoot, listFlowRuns, prepareFlowCreation, readFlowRun, updateFlowRun } from './flow-store.js';
+
+function exact(input, allowed) {
+  if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !allowed.includes(key))) {
+    flowFail('IRIS_FLOW_INPUT_INVALID', '流程输入包含不支持的字段');
+  }
+}
+const reference = artifact => ({ artifactId: artifact.id, sha256: artifact.digest.value });
+
+function readReference(root, expected) {
+  const value = readCoreArtifactBytes(root, expected.artifactId);
+  if (value.artifact.digest.value !== expected.sha256) flowFail('IRIS_FLOW_ARTIFACT_CONFLICT', '流程引用的作品摘要已改变');
+  return value;
+}
+
+function facts(root, run) {
+  const source = readReference(root, run.source);
+  const task = findFlowTask(root, run);
+  if (run.output) {
+    if (task.deliveryState !== 'ready' || task.artifactIds.length !== 1 || task.artifactIds[0] !== run.output.artifactId) {
+      flowFail('IRIS_FLOW_TASK_CONFLICT', '流程输出与原 Task 的交付事实不一致');
+    }
+    const { artifact } = readReference(root, run.output);
+    if (artifact.metadata.taskId !== task.id || !artifact.relations.some(edge => edge.type === 'derived-from' && edge.artifactId === source.artifact.id)) {
+      flowFail('IRIS_FLOW_ARTIFACT_CONFLICT', '流程输出缺少原 Task 或来源关系');
+    }
+  }
+  let comparison;
+  if (run.comparison) {
+    comparison = readReference(root, run.comparison).artifact;
+    if (comparison.kind !== 'pixel-diff' || comparison.relations.length !== 2
+        || ![run.source.artifactId, run.output.artifactId].every(id => comparison.relations.some(edge => edge.type === 'derived-from' && edge.artifactId === id))) {
+      flowFail('IRIS_FLOW_ARTIFACT_CONFLICT', '比较作品与流程来源不一致');
+    }
+  }
+  let status = 'not_started';
+  if (task?.acceptance === 'unknown' || ['unknown', 'failed', 'canceled'].includes(task?.outcome)) status = 'needs_attention';
+  else if (task?.deliveryState === 'ready') status = run.comparison ? run.selection ? 'selected' : 'awaiting_selection' : 'needs_comparison';
+  else if (task?.deliveryState === 'failed') status = 'delivery_failed';
+  else if (task?.attempts.length) status = task.acceptance === 'accepted' ? 'running' : 'needs_attention';
+  return { contractVersion: 0, run, task, status, ...(comparison ? { metrics: comparison.metadata } : {}) };
+}
+
+/** Internal fixed recipe. All state/leases belong to the supplied operation-scoped runtime. */
+export function createImageFlowService(runtime, { resolveImageCandidates, resolveTaskAdapter } = {}) {
+  function creationInput(input) {
+    const normalized = normalizeGenerationInput('image', input);
+    if (!normalized.sourceArtifactId || !parseModelRef(normalized.modelRef) || normalized.providerInput.n !== 1) {
+      flowFail('IRIS_FLOW_INPUT_INVALID', '首版流程需要来源 Artifact、明确 model_ref 和 n=1');
+    }
+    return { prompt: normalized.providerInput.prompt, model_ref: normalized.modelRef,
+      source_artifact_id: normalized.sourceArtifactId, n: 1,
+      ...(normalized.providerInput.size !== undefined ? { size: normalized.providerInput.size } : {}) };
+  }
+  async function prepareCreation(root, signal, input) {
+    const owned = creationInput(input);
+    inspectFlowRoot(root);
+    const source = await readImageEditArtifact(root, owned.source_artifact_id, signal);
+    const candidates = await candidatesFor(owned, signal);
+    return prepareFlowCreation({ source: { artifactId: owned.source_artifact_id, sha256: flowSha256(source.bytes) },
+      input: owned, providerBinding: candidates[0].providerBinding });
+  }
+  async function candidatesFor(runInput, signal, binding) {
+    if (!resolveImageCandidates) flowFail('IRIS_FLOW_PROVIDER_REQUIRED', '创建或首次提交流程需要显式 Provider 配置');
+    signal.throwIfAborted();
+    const candidates = await resolveImageCandidates({ modelRef: runInput.model_ref, signal });
+    signal.throwIfAborted();
+    const parsed = parseModelRef(runInput.model_ref);
+    if (!Array.isArray(candidates) || candidates.length !== 1 || candidates[0].model !== runInput.model_ref
+        || candidates[0].adapter?.id !== parsed.providerId || !/^sha256:[a-f0-9]{64}$/.test(candidates[0].providerBinding)) {
+      flowFail('IRIS_FLOW_INPUT_CONFLICT', '流程必须绑定单一明确模型和有效的连接摘要');
+    }
+    if (binding !== undefined && candidates[0].providerBinding !== binding) flowFail('IRIS_FLOW_PROVIDER_CHANGED', '连接或协议已改变；原流程不重新绑定或生成');
+    return imageEditCandidates([{ ...candidates[0], providerModel: parsed.modelId, selectionReason: 'explicit' }]);
+  }
+
+  async function adapterFor(task, signal) {
+    if (!resolveTaskAdapter) flowFail('IRIS_FLOW_PROVIDER_REQUIRED', '观察或远端补交付需要原 Task 的 Provider 配置');
+    const adapter = await resolveTaskAdapter(task, { signal });
+    signal.throwIfAborted();
+    return adapter;
+  }
+
+  async function continueRun(root, signal, id) {
+    let run = readFlowRun(root, id);
+    let task = facts(root, run).task;
+    if (task?.attempts.length && !run.edit.claimed) flowFail('IRIS_FLOW_TASK_CONFLICT', '步骤检查点与已开始的 Task 冲突');
+    const runner = createProviderTaskRunner(runtime);
+    if (!task || !task.attempts.length) {
+      const candidates = await candidatesFor(run.input, signal, run.providerBinding);
+      task = claimFlowTask(root, run.id);
+      if (!run.edit.claimed) run = updateFlowRun(root, run, { edit: { ...run.edit, claimed: true } });
+      signal.throwIfAborted();
+      const normalized = normalizeGenerationInput('image', run.input);
+      task = (await runner.submit({ capability: 'image', candidates, providerInput: normalized.providerInput,
+        sourceArtifactId: run.source.artifactId, flowRunId: run.id })).task;
+    } else {
+      task = recoverCoreTask(root, task.id);
+      assertFlowTaskMatches(task, run);
+      if (task.outcome === 'succeeded' && task.deliveryState === 'failed') {
+        const adapter = task.deliveryCache && !deliveryCacheNeedsProvider(root, task) ? undefined : await adapterFor(task, signal);
+        task = await runner.redeliver(task.id, adapter);
+      } else if (task.acceptance === 'accepted' && task.outcome === 'none' && task.remoteTaskId) {
+        task = await runner.observe(task.id, await adapterFor(task, signal), { resumeActive: true });
+      }
+    }
+    signal.throwIfAborted();
+    if (task.deliveryState !== 'ready') return facts(root, run);
+    if (task.artifactIds.length !== 1) flowFail('IRIS_FLOW_RESULT_UNSUPPORTED', '首版流程只支持一个改图结果，原 Task 与作品已保留');
+    const output = readCoreArtifactBytes(root, task.artifactIds[0]);
+    if (!run.output) run = updateFlowRun(root, run, { output: reference(output.artifact) });
+    facts(root, run);
+    if (!run.comparison) {
+      const source = readReference(root, run.source);
+      const diff = await pixelDiff({ inputA: source.bytes, inputB: output.bytes, grid: 8, topRegions: 3 });
+      signal.throwIfAborted();
+      const artifact = createCoreArtifact(root, { artifactId: run.compare.artifactId, createdAt: run.createdAt,
+        bytes: diff.heatmap, expectedDigest: flowSha256(diff.heatmap), expectedSize: diff.heatmap.length,
+        kind: 'pixel-diff', mediaType: diff.mime,
+        metadata: { ratio: diff.ratio, diffPixels: diff.diffPixels, totalPixels: diff.totalPixels,
+          width: diff.width, height: diff.height, worstRegions: diff.worstRegions },
+        relations: [run.source.artifactId, run.output.artifactId].map(artifactId => ({ type: 'derived-from', artifactId })) });
+      run = updateFlowRun(root, run, { comparison: reference(artifact) });
+    }
+    return facts(root, run);
+  }
+
+  async function execute(name, input = {}) {
+    if (name === 'flow.init') {
+      exact(input, []);
+      return runtime.run('execute', ({ dataRoot }) => ({ contractVersion: 0, root: initializeFlowRoot(dataRoot) }));
+    }
+    if (name === 'flow.create') {
+      const owned = creationInput(input);
+      return runtime.run('execute', async ({ dataRoot, signal }) => {
+        const run = commitFlowCreation(dataRoot, await prepareCreation(dataRoot, signal, owned));
+        return facts(dataRoot, run);
+      });
+    }
+    if (name === 'flow.list') {
+      exact(input, []);
+      return runtime.run('inspect', ({ dataRoot }) => {
+        const runs = listFlowRuns(dataRoot);
+        return { contractVersion: 0, total: runs.length, runs: runs.map(run => ({ id: run.id, recipe: run.recipe,
+          createdAt: run.createdAt, source: run.source, modelRef: run.input.model_ref, taskId: run.edit.taskId })) };
+      });
+    }
+    if (name === 'flow.inspect') {
+      exact(input, ['run_id']);
+      return runtime.run('inspect', ({ dataRoot }) => facts(dataRoot, readFlowRun(dataRoot, input.run_id)));
+    }
+    if (name === 'flow.continue') {
+      exact(input, ['run_id']);
+      return runtime.run('execute', ({ dataRoot, signal }) => continueRun(dataRoot, signal, input.run_id));
+    }
+    if (name === 'flow.select' || name === 'flow.export') {
+      exact(input, name === 'flow.select' ? ['run_id', 'artifact_id'] : ['run_id', 'output_path']);
+      return runtime.run('execute', ({ dataRoot }) => {
+        let run = readFlowRun(dataRoot, input.run_id);
+        facts(dataRoot, run);
+        if (!run.comparison) flowFail('IRIS_FLOW_NOT_READY', '请先完成改图与比较，再选择结果');
+        if (name === 'flow.select') {
+          const selected = [run.source, run.output].find(item => item.artifactId === input.artifact_id);
+          if (!selected) flowFail('IRIS_FLOW_SELECTION_INVALID', '只能选择本流程的原图或新版');
+          if (run.selection?.artifactId !== selected.artifactId) run = updateFlowRun(dataRoot, run, { selection: selected });
+          return facts(dataRoot, run);
+        }
+        if (!run.selection) flowFail('IRIS_FLOW_SELECTION_REQUIRED', '请先明确选择要导出的原图或新版');
+        return { ...facts(dataRoot, run), export: exportCoreArtifact(dataRoot, run.selection.artifactId, input.output_path) };
+      });
+    }
+    throw new TypeError('未知的内部 Flow 命令');
+  }
+  return Object.freeze({ execute, prepareCreation, inspectCreation: (root, intent, options) => {
+    readReference(root, intent.source);
+    return facts(root, commitFlowCreation(root, intent, options));
+  } });
+}