@mokuyoaxis/dsh-iris 0.2.5 → 0.2.7

package/lib/provider-protocol.js

@@ -114,6 +114,36 @@ export function isConfiguredProvider(provider) {
     && (provider.auth === 'none' || (typeof provider.apiKey === 'string' && provider.apiKey.trim())));
 }
 
+/** 已知需要其他接口的语音系列；自定义模型仍以明确配置和实测为准。 */
+export function dashscopeTtsProtocolIssue(modelId) {
+  const model = String(modelId || '');
+  if (/^qwen(?:\d+(?:\.\d+)?)?-(?:tts|omni|audio)-.*realtime(?:-|$)/i.test(model)) {
+    return '该实时语音模型需要 WebSocket，Iris 尚未接入该调用方式';
+  }
+  if (/^(?:qwen-audio-|cosyvoice(?:-|$)|sambert-|MiniMax\/speech-)/i.test(model)) {
+    return 'Iris 尚未接入该语音系列的合成接口；当前使用 Qwen-TTS 普通 HTTP 接口';
+  }
+  return '';
+}
+
+/** 复刻/设计模型不能沿用普通模型的默认音色。 */
+export function dashscopeTtsInputIssue(modelId, voice) {
+  return dashscopeTtsProtocolIssue(modelId)
+    || (/^qwen(?:\d+)?-tts-(?:vc|vd)(?:-|$)/i.test(String(modelId || '')) && !String(voice || '').trim()
+      ? '该模型需要先创建复刻或设计音色；请在语音功能填写与该模型匹配的音色 ID 后验证'
+      : '');
+}
+
+/** Protocol support is independent from model capability declarations and health. */
+export function supportsModelCapability(provider, modelId, capability, { checkEndpoint = true } = {}) {
+  if (capability === 'vision') return true;
+  if (capability === 'music-gen') return provider?.models?.some(model => model?.id === modelId && model.musicProtocol === 'gemini-web-music') === true;
+  const protocol = capability === 'image-gen' ? selectImageProtocol(provider, modelId).mediaProtocol : selectMediaProtocol(provider).mediaProtocol;
+  if (protocol === 'dashscope') return (capability !== 'tts' || !dashscopeTtsProtocolIssue(modelId))
+    && (!checkEndpoint || isDashScopeBaseUrl(providerMediaBaseUrl(provider)));
+  return capability === 'image-gen' && ['openai-images', 'openai-chat-images', 'openai-responses-images'].includes(protocol);
+}
+
 /**
  * 生图尺寸的协议差异集中在这里，调用点不再自带厂商假设。
  *

package/lib/provider-task-runner.js

@@ -11,6 +11,7 @@ import {
   beginCoreDelivery,
   completeCoreDelivery,
   createCoreTask,
+  claimFlowTask,
   failCoreDelivery,
   finalizeCoreNoAcceptance,
   inspectCoreTask,
@@ -33,6 +34,8 @@ import { ProviderContractError, providerErrorRecord, submitWithAcceptanceBoundar
 import { imageEditCandidates, readImageEditArtifact } from './image-edit-input.js';
 import { createDeliveryCache, newDeliveryPayloadPath, readDeliveryCache,
   readDeliveryPayload, recordDeliveryPayload } from './core-delivery-cache.js';
+import { readFlowRun, flowFail } from './flow-store.js';
+import { normalizeGenerationInput } from './generation-input.js';
 
 export const PROVIDER_TASK_RUNNER_VERSION = 0;
 
@@ -193,8 +196,11 @@ async function observeWithinRoot(dataRoot, taskId, adapter, signal) {
   } catch (error) {
     return recordCoreWatchError(dataRoot, taskId, error);
   }
-  const recorded = recordCorePollResult(dataRoot, taskId, result);
+  const cachedFlowResult = Boolean(before.flowBinding && result.kind === 'succeeded');
+  if (cachedFlowResult) createDeliveryCache(dataRoot, before, result.artifacts);
+  const recorded = recordCorePollResult(dataRoot, taskId, result, { deliveryCache: cachedFlowResult });
   if (result.kind !== 'succeeded') return recorded;
+  if (cachedFlowResult) return deliverCachedArtifacts(dataRoot, taskId, adapter, signal);
   return deliverArtifacts(dataRoot, taskId, adapter, result.artifacts, signal);
 }
 
@@ -288,13 +294,27 @@ export function createProviderTaskRunner(runtime) {
       const capability = String(input.capability || '').trim();
       let candidates = normalizedCandidates(capability, input.candidates);
       let providerInput = input.providerInput ?? {};
+      let flow;
+      if (input.flowRunId !== undefined) {
+        flow = readFlowRun(dataRoot, input.flowRunId);
+        const expected = normalizeGenerationInput('image', flow.input).providerInput;
+        if (capability !== 'image' || !flow.edit.claimed || input.sourceArtifactId !== flow.source.artifactId
+            || Object.keys(providerInput).length !== Object.keys(expected).length
+            || Object.keys(expected).some(key => providerInput[key] !== expected[key])
+            || candidates.length !== 1 || candidates[0].model !== flow.input.model_ref
+            || candidates[0].providerBinding !== flow.providerBinding) {
+          flowFail('IRIS_FLOW_INPUT_CONFLICT', '提交与流程已保存的输入或模型绑定冲突');
+        }
+      }
       if (input.sourceArtifactId !== undefined) {
         if (capability !== 'image') throw new TypeError('sourceArtifactId 仅用于图片编辑');
         candidates = imageEditCandidates(candidates);
         const image = await readImageEditArtifact(dataRoot, input.sourceArtifactId, signal);
         providerInput = { ...providerInput, image };
       }
-      const task = createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom, sourceArtifactId: input.sourceArtifactId });
+      const task = flow ? claimFlowTask(dataRoot, flow.id)
+        : createCoreTask(dataRoot, { capability, retriedFrom: input.retriedFrom, sourceArtifactId: input.sourceArtifactId });
+      if (flow && task.attempts.length) flowFail('IRIS_FLOW_TASK_ALREADY_STARTED', '该流程 Task 已有提交意图，禁止重新 submit');
       const completedResults = new Map();
       const wrapped = candidates.map(({ adapter, model, providerModel, prepareInput }) => ({
         id: adapter.id,

package/lib/render-address.js

@@ -0,0 +1,35 @@
+/** Local browser navigation address. Public media links keep their separate webBase() contract. */
+const DEFAULT_BASE = 'http://127.0.0.1:3080';
+
+function invalid(source, message) {
+  return Object.freeze({ source, status: 'invalid', code: 'IRIS_RENDER_ADDRESS_INVALID', message });
+}
+
+function checkedBase(value, source) {
+  let url;
+  try { url = new URL(value); }
+  catch (_) { return invalid(source, '截图地址无法解析；请设置有效的 DSH_WEB_BASE HTTP(S) 地址。'); }
+  if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password || url.search || url.hash) {
+    return invalid(source, '截图地址必须为 HTTP(S)，且不能包含登录凭据、查询参数或片段；请核对 DSH_WEB_BASE。');
+  }
+  return Object.freeze({ source, status: 'resolved', baseUrl: url.href.replace(/\/+$/, '') });
+}
+
+/** Only documented host/port/protocol properties are read; no request headers or private config. */
+export function resolveRenderAddress(listener, override = process.env.DSH_WEB_BASE) {
+  if (override) return checkedBase(String(override).trim(), 'environment');
+  const port = listener?.port;
+  const host = listener?.host;
+  if (typeof host !== 'string' || !host || !Number.isSafeInteger(port) || port < 1 || port > 65535) {
+    return Object.freeze({ source: 'default', status: 'fallback', baseUrl: DEFAULT_BASE,
+      message: '宿主未提供实际监听地址，暂用 127.0.0.1:3080；非默认部署请设置 DSH_WEB_BASE。' });
+  }
+  // Older supported DSH listeners are HTTP-only and have no protocol property.
+  const protocol = listener.protocol ?? 'http:';
+  if (!['http:', 'https:'].includes(protocol) || /[\s/@?#\\%]/.test(host)) {
+    return invalid('host', '宿主监听地址不能直接用于截图；请通过 DSH_WEB_BASE 指定浏览器可访问的 HTTP(S) 地址。');
+  }
+  const localHost = host === '0.0.0.0' ? '127.0.0.1' : (host === '::' || host === '[::]' ? '::1' : host);
+  const urlHost = localHost.includes(':') && !localHost.startsWith('[') ? '[' + localHost + ']' : localHost;
+  return checkedBase(protocol + '//' + urlHost + ':' + port, 'host');
+}

package/lib/render.js

@@ -15,8 +15,41 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { irisHome } from './config.js';
-import { webBase, mimeOf } from './media.js';
+import { mimeOf } from './media.js';
+import { resolveRenderAddress } from './render-address.js';
 import { ensurePrivateDir, writePrivateFile } from './private-storage.js';
+import { imageDimensions } from './pixels.js';
+
+const PNG_DATA_PREFIX = 'data:image/png;base64,';
+const MAX_SCREENSHOT_BYTES = 64 * 1024 * 1024;
+
+async function screenshotPng(result) {
+  const dataUrl = result?.dataUrl;
+  if (typeof dataUrl !== 'string' || !dataUrl.startsWith(PNG_DATA_PREFIX)) {
+    throw new RenderError('iris_html_screenshot: 浏览器没有返回 PNG 图片数据');
+  }
+  if (dataUrl.length > PNG_DATA_PREFIX.length + Math.ceil(MAX_SCREENSHOT_BYTES / 3) * 4) {
+    throw new RenderError('iris_html_screenshot: 截图超过 64 MiB，请缩短页面后重试');
+  }
+  const encoded = dataUrl.slice(PNG_DATA_PREFIX.length);
+  const png = Buffer.from(encoded, 'base64');
+  if (!png.length || png.length > MAX_SCREENSHOT_BYTES || png.toString('base64') !== encoded
+      || !png.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) {
+    throw new RenderError('iris_html_screenshot: 浏览器返回的 PNG 图片数据无效');
+  }
+  let dimensions;
+  try { dimensions = await imageDimensions(png); }
+  catch (cause) {
+    const error = new RenderError('iris_html_screenshot: 浏览器返回的 PNG 图片无法读取');
+    error.cause = cause;
+    throw error;
+  }
+  // 与独立 Chromium 后端保持相同的截图尺寸上限，采用实际图片尺寸而非浏览器声明值。
+  if (dimensions.width > 16384 || dimensions.height > 16384 || dimensions.width * dimensions.height > 40000000) {
+    throw new RenderError('iris_html_screenshot: 截图尺寸超过限制（边长 16384，4000 万像素）');
+  }
+  return png;
+}
 
 export class RenderError extends Error {
   constructor(message) {
@@ -60,22 +93,27 @@ export function renderRoot() {
 
 /**
  * 基于 DSH Adapter 持有的原生 browser 服务完成 HTML → PNG。
- * @param {{browser?: object, waitMs?: number}} opts browser 只在 DSH Adapter 内构造
+ * @param {{browser?: object, waitMs?: number, getAddress?: function}} opts browser 只在 DSH Adapter 内构造
  */
 export class BrowserHtmlRenderer {
-  constructor({ browser, waitMs = 1200 }) {
+  constructor({ browser, waitMs = 1200, getAddress = resolveRenderAddress }) {
     this.browser = browser;
     this.waitMs = waitMs;
+    this.getAddress = getAddress;
   }
 
   async render({ html, width, height, fullPage, signal }) {
     const b = this.browser;
-    if (!b || typeof b.open !== 'function' || typeof b.openUrl !== 'function' || typeof b.screenshot !== 'function') {
+    if (!b || !['open', 'openUrl', 'screenshot', 'close'].every((name) => typeof b[name] === 'function')) {
       throw new RenderError('iris: 浏览器服务不可用——需要启用兼容的 dsh-builtin-browser 插件');
     }
     const text = String(html || '').trim();
     if (!text) throw new RenderError('iris_html_screenshot: html 不能为空');
     throwIfAborted(signal);
+    const address = this.getAddress();
+    if (address.status === 'invalid') {
+      throw Object.assign(new RenderError(address.message), { code: address.code });
+    }
 
     // 每次调用独立子目录（随机名），写 index.html
     const dir = path.join(renderRoot(), crypto.randomBytes(6).toString('hex'));
@@ -88,24 +126,25 @@ export class BrowserHtmlRenderer {
     }
     const htmlPath = path.join(dir, 'index.html');
     writePrivateFile(htmlPath, content);
-    const url = `${webBase()}/iris/render/${path.basename(dir)}/index.html`;
-    const pngPath = path.join(dir, 'render.png');
-
+    const url = `${address.baseUrl}/iris/render/${path.basename(dir)}/index.html`;
     try {
-      const session = await b.open({ signal });
-      throwIfAborted(signal);
+      // open 只接受可选的会话名称；取消发生在打开期间时，取得会话后仍须关闭。
+      const session = await b.open();
       try {
-        await b.openUrl(session, { url, newTab: true, signal });
+        throwIfAborted(signal);
+        await b.openUrl(session, { url, newTab: true }, signal);
         throwIfAborted(signal);
         await waitForRender(this.waitMs, signal); // 等页面加载（无加载完成事件可用的折中）
         throwIfAborted(signal);
-        await b.screenshot(session, { fullPage: fullPage !== false, savePath: pngPath, signal });
+        // 不要求浏览器写入 Iris 私有目录，兼容 downloadDir 内的保存路径限制。
+        const result = await b.screenshot(session, { fullPage: fullPage !== false, format: 'png' }, signal);
+        throwIfAborted(signal);
+        const png = await screenshotPng(result);
         throwIfAborted(signal);
+        return { png };
       } finally {
         try { await b.close(session); } catch (_) { /* 幂等 */ }
       }
-      if (!fs.existsSync(pngPath)) throw new RenderError('iris_html_screenshot: 浏览器未产出截图文件');
-      return { png: fs.readFileSync(pngPath) };
     } finally {
       fs.rmSync(dir, { recursive: true, force: true }); // 用完即清
     }

package/lib/skill-installation.js

@@ -0,0 +1,199 @@
+/** Explicit, copy-based installation of the bundled Core skill. No host/model I/O. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = fileURLToPath(new URL('../', import.meta.url));
+const SKILL = 'iris-core';
+const RECEIPT = '.iris-install.json';
+const digest = value => crypto.createHash('sha256').update(value).digest('hex');
+const error = (code, message) => Object.assign(new Error(message), { code });
+const isWithin = (parent, child) => {
+  const relative = path.relative(parent, child);
+  return !relative || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith('..' + path.sep));
+};
+
+function stat(file) {
+  try { return fs.lstatSync(file); }
+  catch (cause) { if (cause.code === 'ENOENT') return null; throw cause; }
+}
+
+// Resolve existing ancestors without creating them, including for dry-run/status.
+function physicalPath(file) {
+  const entry = stat(file);
+  if (entry) return fs.realpathSync(file);
+  return path.join(physicalPath(path.dirname(file)), path.basename(file));
+}
+
+function readTree(root, { installed = false, expected } = {}) {
+  const files = Object.create(null), bytes = Object.create(null), directories = [];
+  const walk = (directory, prefix = '') => {
+    for (const name of fs.readdirSync(directory).sort()) {
+      if (installed && !prefix && name === RECEIPT) continue;
+      const relative = prefix + name, file = path.join(directory, name), entry = fs.lstatSync(file);
+      if (entry.isSymbolicLink() || (!entry.isDirectory() && !entry.isFile())) {
+        throw error('IRIS_SKILL_UNSAFE_PATH', 'Skill 中存在软链或特殊文件：' + relative);
+      }
+      if (entry.isDirectory()) {
+        directories.push(relative); walk(file, relative + '/');
+      } else {
+        // Added/size-changed user files need not be read to establish a conflict.
+        const content = !expected || expected[relative]?.size === entry.size ? fs.readFileSync(file) : null;
+        files[relative] = { size: entry.size, sha256: content ? digest(content) : null };
+        if (!installed) bytes[relative] = content;
+      }
+    }
+  };
+  walk(root);
+  return { files, bytes, directories: directories.sort() };
+}
+
+function sameTree(tree, recorded) {
+  const names = Object.keys(tree.files).sort(), other = Object.keys(recorded.files).sort();
+  return JSON.stringify(names) === JSON.stringify(other)
+    && names.every(name => tree.files[name].size === recorded.files[name].size
+      && tree.files[name].sha256 === recorded.files[name].sha256)
+    && JSON.stringify(tree.directories) === JSON.stringify([...recorded.directories].sort());
+}
+
+function validReceipt(value, packageName) {
+  const relative = name => typeof name === 'string' && name.length > 0 && !name.includes('\\')
+    && !name.includes('\0') && !name.split('/').some(part => !part || part === '.' || part === '..');
+  return value?.schemaVersion === 1 && value.packageName === packageName && value.skillName === SKILL
+    && typeof value.packageVersion === 'string' && value.packageVersion.length > 0
+    && value.files && !Array.isArray(value.files) && typeof value.files === 'object'
+    && Object.hasOwn(value.files, 'SKILL.md') && !Object.hasOwn(value.files, RECEIPT)
+    && Object.entries(value.files).every(([name, item]) => relative(name)
+      && Number.isSafeInteger(item?.size) && item.size >= 0 && /^[a-f0-9]{64}$/.test(item.sha256))
+    && Array.isArray(value.directories) && value.directories.every(relative);
+}
+
+function packageResources(packageRoot) {
+  const metadata = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  const source = fs.realpathSync(path.join(packageRoot, 'skills', SKILL));
+  const tree = readTree(source);
+  if (!tree.files['SKILL.md'] || tree.files[RECEIPT]) {
+    throw error('IRIS_SKILL_PACKAGE_INVALID', '包内缺少 Skill 入口，或含有不应发布的安装记录');
+  }
+  return { source, metadata, ...tree };
+}
+
+function inspect(destination, resources) {
+  const entry = stat(destination);
+  if (!entry) return { status: 'not_installed' };
+  if (entry.isSymbolicLink() || !entry.isDirectory()) return { status: 'unmanaged', reason: 'not_a_plain_directory' };
+  const receiptFile = path.join(destination, RECEIPT), receiptStat = stat(receiptFile);
+  if (!receiptStat?.isFile() || receiptStat.isSymbolicLink()) return { status: 'unmanaged', reason: 'no_valid_receipt' };
+  let receipt;
+  try { receipt = JSON.parse(fs.readFileSync(receiptFile, 'utf8')); }
+  catch (cause) {
+    if (!(cause instanceof SyntaxError)) throw cause;
+    return { status: 'unmanaged', reason: 'invalid_receipt' };
+  }
+  if (!validReceipt(receipt, resources.metadata.name)) return { status: 'unmanaged', reason: 'invalid_receipt' };
+  const base = { installedVersion: receipt.packageVersion };
+  let tree;
+  try { tree = readTree(destination, { installed: true, expected: receipt.files }); }
+  catch (cause) {
+    if (cause.code !== 'IRIS_SKILL_UNSAFE_PATH') throw cause;
+    return { ...base, status: 'modified', reason: 'unsafe_entry' };
+  }
+  if (!sameTree(tree, receipt)) return { ...base, status: 'modified', reason: 'local_changes' };
+  return { ...base, status: receipt.packageVersion === resources.metadata.version && sameTree(tree, resources)
+    ? 'current' : 'update_available' };
+}
+
+function resolveDirectory({ target, directory, env, home }) {
+  if (target !== undefined && target !== 'kimi') throw error('IRIS_SKILL_OPTIONS_INVALID', '当前仅支持 --target kimi；其他宿主请用 --directory');
+  if (directory === undefined) {
+    if (target !== 'kimi') throw error('IRIS_SKILL_OPTIONS_INVALID', '请明确指定 --target kimi 或 --directory');
+    const kimiHome = env.KIMI_CODE_HOME || path.join(home, '.kimi-code');
+    if (!path.isAbsolute(kimiHome)) throw error('IRIS_SKILL_OPTIONS_INVALID', 'KIMI_CODE_HOME 必须是绝对路径');
+    directory = path.join(kimiHome, 'skills');
+  }
+  if (typeof directory !== 'string' || !path.isAbsolute(directory)) throw error('IRIS_SKILL_OPTIONS_INVALID', 'directory 必须是绝对路径');
+  return physicalPath(path.resolve(directory));
+}
+
+function ensureDirectory(directory) {
+  const entry = stat(directory);
+  if (entry && (!entry.isDirectory() || entry.isSymbolicLink())) throw error('IRIS_SKILL_UNSAFE_PATH', '控制目录必须是普通目录：' + directory);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+}
+
+function archive(destination, control, action) {
+  const transaction = fs.mkdtempSync(path.join(control, 'backup-'));
+  const backupPath = path.join(transaction, SKILL);
+  fs.writeFileSync(path.join(transaction, 'move.json'), JSON.stringify({ schemaVersion: 1, action,
+    at: new Date().toISOString(), origin: destination, backupPath }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+  fs.renameSync(destination, backupPath);
+  return backupPath;
+}
+
+function copyResources(destination, resources) {
+  fs.mkdirSync(destination, { mode: 0o700 }); // Exclusive claim; never replace even an empty user directory.
+  for (const relative of resources.directories) fs.mkdirSync(path.join(destination, relative), { recursive: true, mode: 0o700 });
+  for (const [relative, bytes] of Object.entries(resources.bytes)) fs.writeFileSync(path.join(destination, relative), bytes, { flag: 'wx', mode: 0o600 });
+  fs.writeFileSync(path.join(destination, RECEIPT), JSON.stringify({ schemaVersion: 1,
+    packageName: resources.metadata.name, packageVersion: resources.metadata.version, skillName: SKILL,
+    installedAt: new Date().toISOString(), files: resources.files, directories: resources.directories
+  }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+}
+
+/** Internal CLI service. Explicit mutations only; no postinstall or public SDK export. */
+export function manageCoreSkill({ action, target, directory, dryRun = false }, {
+  packageRoot = PACKAGE_ROOT, env = process.env, home = os.homedir()
+} = {}) {
+  if (!['install', 'status', 'uninstall'].includes(action) || action === 'status' && dryRun) {
+    throw error('IRIS_SKILL_OPTIONS_INVALID', '使用 skills install/status/uninstall；status 不接受 --dry-run');
+  }
+  const resources = packageResources(packageRoot);
+  const resolved = resolveDirectory({ target, directory, env, home }), destination = path.join(resolved, SKILL);
+  if (isWithin(resources.source, destination) || isWithin(destination, resources.source)) {
+    throw error('IRIS_SKILL_OPTIONS_INVALID', '安装目标不能与包内 Skill 源目录重叠');
+  }
+  const base = { skill: SKILL, target: target || 'directory', directory: resolved, destination,
+    packageVersion: resources.metadata.version, discovery: 'not_checked' };
+  const before = inspect(destination, resources);
+  const result = { ...base, ...before };
+  if (action === 'status') return result;
+  const conflict = () => error('IRIS_SKILL_CONFLICT', '保留现有 Skill；目标没有有效归属记录、包含本地修改或软链。请先检查：' + destination);
+  if (['modified', 'unmanaged'].includes(before.status)) throw conflict();
+  if (action === 'install' && before.status === 'current'
+      || action === 'uninstall' && before.status === 'not_installed') return { ...result, action: 'unchanged', dryRun };
+  const operation = action === 'uninstall' ? 'uninstall' : before.status === 'not_installed' ? 'install' : 'update';
+  if (dryRun) return { ...result, action: operation, dryRun: true };
+  const controls = path.join(path.dirname(resolved), '.iris-skill-installs');
+  const control = path.join(controls, digest(resolved).slice(0, 16));
+  if (isWithin(resolved, control)) throw error('IRIS_SKILL_OPTIONS_INVALID', '安装目录必须允许在扫描目录之外保存备份');
+  ensureDirectory(controls); ensureDirectory(control);
+  const lock = path.join(control, 'lock.json');
+  let fd;
+  try { fd = fs.openSync(lock, 'wx', 0o600); }
+  catch (cause) {
+    if (cause.code !== 'EEXIST') throw cause;
+    throw error('IRIS_SKILL_BUSY', '已有安装操作或未核实的锁，保留现场：' + lock);
+  }
+  let backupPath;
+  try {
+    fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, destination }) + '\n');
+    const current = inspect(destination, resources);
+    if (current.status !== before.status || current.installedVersion !== before.installedVersion) {
+      throw error('IRIS_SKILL_CONFLICT', '安装状态已变化，请重新检查：' + destination);
+    }
+    ensureDirectory(resolved);
+    if (before.status !== 'not_installed') backupPath = archive(destination, control, operation);
+    if (action === 'uninstall') return { ...base, status: 'not_installed', action: 'uninstalled', backupPath };
+    copyResources(destination, resources);
+    return { ...base, status: 'current', installedVersion: resources.metadata.version,
+      action: operation === 'update' ? 'updated' : 'installed', ...(backupPath ? { backupPath } : {}) };
+  } catch (cause) {
+    if (backupPath) cause.message += '\n原版保存在：' + backupPath;
+    throw cause;
+  } finally {
+    fs.closeSync(fd);
+    fs.unlinkSync(lock); // Only this invocation's exclusively created coordination file.
+  }
+}

package/lib/vision-model-routing.js

@@ -7,7 +7,8 @@ import { prepareDshVisionModelPort } from './dsh-vision-model-adapter.js';
 import { createModelOperation } from './model-invoker.js';
 import { ModelPortError, normalizeModelDescriptor, normalizeModelCall, modelErrorRecord } from './model-port-contract.js';
 import { waitForModelWork } from './model-call-runtime.js';
-import { modelRateLimit, reportModelRateLimit } from './provider-health.js';
+import { modelRateLimit, reportModelRateLimit, recordModelAvailability } from './provider-health.js';
+import { modelAvailabilityBinding, modelUnavailable } from './model-directory.js';
 import { completeVision, VISION_BUDGET } from './vision-core.js';
 import { open } from 'node:fs/promises';
 import { DEFAULT_VISION_INPUT, visionInputLimits } from './vision-image-input.js';
@@ -47,7 +48,7 @@ function deferredDshPort(host, { prepareImages, orientImages, prepareImageReques
 }
 
 /** 配置只绑定一个自持模型；CLI 不附加宿主候选。 */
-export function createConfiguredVisionModelPort(provider, model, { allowRateLimited = false, onRateLimit, prepareImages = false,
+export function createConfiguredVisionModelPort(provider, model, { allowRateLimited = false, onRateLimit, onModelAvailability, prepareImages = false,
   orientImages = false, prepareImageRequest } = {}) {
   const parsed = parseModelRef(resolveModelRef(provider, 'vision', model));
   const id = 'iris-provider:' + encodeURIComponent(provider.id);
@@ -59,13 +60,25 @@ export function createConfiguredVisionModelPort(provider, model, { allowRateLimi
     baseUrl: provider.baseUrl, apiKey: providerApiKey(provider),
     orientImages, prepareImageRequest,
     ...(prepareImages ? { imageInput: visionInputLimits(provider, parsed.modelId) } : {}) });
+  const availability = result => {
+    const event = { ...result, stage: 'submit', source: allowRateLimited ? 'probe' : 'task',
+      binding: modelAvailabilityBinding(provider, parsed.modelId, 'vision') };
+    if (!recordModelAvailability(provider, parsed.modelId, 'vision', event)) return;
+    try { onModelAvailability?.({ providerId: provider.id, modelId: parsed.modelId, capability: 'vision', ...event }); }
+    catch (_) { console.warn('[iris] 模型可用性未能持久化，请检查配置写入权限'); }
+  };
   return Object.freeze({ describe: port.describe,
     async complete(request, options) {
-      if (!allowRateLimited && modelRateLimit(provider, parsed.modelId)) {
+      if (!allowRateLimited && (modelRateLimit(provider, parsed.modelId) || modelUnavailable(provider, parsed.modelId, 'vision'))) {
         throw new ModelPortError('IRIS_MODEL_UNAVAILABLE', { stage: 'prepare', invocation: 'not_invoked' });
       }
-      try { return await port.complete(request, options); }
+      try {
+        const result = await port.complete(request, options);
+        availability({ ok: true });
+        return result;
+      }
       catch (error) {
+        availability({ ok: false, httpStatus: error.status, providerCode: error.providerCode });
         reportModelRateLimit(provider, parsed.modelId, { status: error.status, code: error.code,
           providerCode: error.providerCode, retryAfterMs: error.retryAfterMs,
           ...(error.quotaExhausted ? { reason: 'free_quota' } : {}),
@@ -76,7 +89,7 @@ export function createConfiguredVisionModelPort(provider, model, { allowRateLimi
   });
 }
 
-export function buildVisionModelCandidates(host, { providers = [], model, allowRateLimited = false, onRateLimit, prepareImages = false,
+export function buildVisionModelCandidates(host, { providers = [], model, allowRateLimited = false, onRateLimit, onModelAvailability, prepareImages = false,
   orientImages = false, prepareImageRequest } = {}) {
   const candidates = [], seen = new Set();
   let selected = providers.filter(Boolean);
@@ -100,7 +113,7 @@ export function buildVisionModelCandidates(host, { providers = [], model, allowR
     // 显式模型会把同账号的多份池记录解析为同一复合引用，只保留首次候选。
     if (parsed && seen.has(ref)) continue;
     if (parsed) seen.add(ref);
-    const port = createConfiguredVisionModelPort(provider, provider.visionModel, { allowRateLimited, onRateLimit, prepareImages, orientImages, prepareImageRequest });
+    const port = createConfiguredVisionModelPort(provider, provider.visionModel, { allowRateLimited, onRateLimit, onModelAvailability, prepareImages, orientImages, prepareImageRequest });
     const id = port.describe().identity.backendId;
     candidates.push({ port, id, via: 'selfstack', backendId: provider.id, model: parsed?.modelId || '' });
   }
@@ -148,10 +161,10 @@ function projectError(record, candidates) {
 }
 
 /** prepareImage 的信号覆盖文件/会话读取；函数开始时即建立整体预算。 */
-export async function runVisionOperation(host, { providers, model, signal, budget = VISION_BUDGET, onRateLimit, prepareImages = false,
+export async function runVisionOperation(host, { providers, model, signal, budget = VISION_BUDGET, onRateLimit, onModelAvailability, prepareImages = false,
   orientImages = false, prepareImageRequest }, consume) {
   if (signal?.aborted) throw new ModelPortError('IRIS_MODEL_ABORTED');
-  const candidates = buildVisionModelCandidates(host, { providers, model, onRateLimit, prepareImages, orientImages, prepareImageRequest });
+  const candidates = buildVisionModelCandidates(host, { providers, model, onRateLimit, onModelAvailability, prepareImages, orientImages, prepareImageRequest });
   const operation = createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: candidates.length } });
   try {
     const { completion: result, ...details } = await consume(candidates.map(candidate => candidate.port), operation);
@@ -168,8 +181,8 @@ export async function runVisionOperation(host, { providers, model, signal, budge
 }
 
 /** 单图与复合业务共用同一候选、整体预算和结果投影。 */
-export async function runVisionRequest(host, { providers, model, question, image, dataUrl, prepareImage, signal, budget = VISION_BUDGET, onRateLimit }) {
-  return runVisionOperation(host, { providers, model, signal, budget, onRateLimit, prepareImages: true }, async (ports, operation) => {
+export async function runVisionRequest(host, { providers, model, question, image, dataUrl, prepareImage, signal, budget = VISION_BUDGET, onRateLimit, onModelAvailability }) {
+  return runVisionOperation(host, { providers, model, signal, budget, onRateLimit, onModelAvailability, prepareImages: true }, async (ports, operation) => {
     normalizeModelCall(ports[0].describe(), { prompt: question,
       image: { bytes: new Uint8Array([0]), mediaType: 'image/png' } }, { budget });
     const resolved = await waitForModelWork(() => prepareImage ? prepareImage(operation.signal)
@@ -179,9 +192,9 @@ export async function runVisionRequest(host, { providers, model, question, image
 }
 
 /** 付费确认在动作入口；红图实测只有一个供应商，不退到 Host 冒充其能力。 */
-export async function probeVisionModel(provider, model, image, { signal, timeoutMs = 15000 } = {}) {
+export async function probeVisionModel(provider, model, image, { signal, timeoutMs = 15000, onModelAvailability } = {}) {
   try {
-    const port = createConfiguredVisionModelPort(provider, model, { allowRateLimited: true });
+    const port = createConfiguredVisionModelPort(provider, model, { allowRateLimited: true, onModelAvailability });
     const result = await completeVision([port], { prompt: '这张图片是什么颜色？请只回答颜色名称（中文）。', image },
       { signal, budget: { ...VISION_BUDGET, timeoutMs } });
     return { ok: /红|red/i.test(result.text), answer: result.text };

package/lib/workbench-artifacts.js

@@ -1,7 +1,6 @@
 'use strict';
 /** Host 作品目录：两种既有存储保持原样，在展示边界统一过滤、排序与分页。 */
 import * as legacy from './artifacts.js';
-import { galleryArtifactsForDsh } from './dsh-core-adapter.js';
 import { mimeOf } from './media.js';
 
 export function normalizeGalleryQuery(input = {}) {
@@ -22,7 +21,7 @@ export async function workbenchArtifacts(input, options = {}) {
   let droppedCore = 0, coreError = '';
   if (query.source !== 'legacy') {
     try {
-      const core = await galleryArtifactsForDsh(options);
+      const core = await options.core.galleryArtifactsForDsh(options);
       droppedCore = core.dropped;
       for (const artifact of core.artifacts) {
         if (artifact.kind === 'host-input') continue;

package/lib/workbench-management.js

@@ -5,7 +5,6 @@ import crypto from 'node:crypto';
 import { setImmediate } from 'node:timers/promises';
 import * as legacy from './artifacts.js';
 import { mimeOf } from './media.js';
-import { inspectWorkbenchArtifactForDsh, inspectProviderTaskForDsh, maintainWorkbenchForDsh, readCoreArtifactMediaForDsh } from './dsh-core-adapter.js';
 import { workbenchZip } from './workbench-zip.js';
 
 export const MAX_WORKBENCH_SELECTION = 200;
@@ -56,7 +55,7 @@ function safeMetadata(metadata) {
 export async function workbenchDetail(source, id, options = {}) {
   validItem({ source, id }); active(options.signal);
   if (source === 'core') {
-    const artifact = await inspectWorkbenchArtifactForDsh(id, options);
+    const artifact = await options.core.inspectWorkbenchArtifactForDsh(id, options);
     return { item: { id, source, file: id + EXTENSIONS[artifact.mediaType], mime: artifact.mediaType,
       kind: artifact.kind, size: artifact.size, createdAt: artifact.createdAt, digest: artifact.digest.value,
       relations: artifact.relations, metadata: safeMetadata(artifact.metadata), integrity: 'verified',
@@ -82,7 +81,7 @@ export async function downloadWorkbenchSelection(input, options = {}) {
   bytes = 0;
   for (const detail of details) {
     active(options.signal);
-    const data = detail.source === 'core' ? (await readCoreArtifactMediaForDsh(detail.id, options)).bytes : fs.readFileSync(legacyFile(detail.id).abs);
+    const data = detail.source === 'core' ? (await options.core.readCoreArtifactMediaForDsh(detail.id, options)).bytes : fs.readFileSync(legacyFile(detail.id).abs);
     const digest = crypto.createHash('sha256').update(data).digest('hex');
     if (detail.source === 'core' && digest !== detail.digest) fail('IRIS_ARTIFACT_DIGEST_MISMATCH', '选中作品内容已改变', 409);
     bytes += data.length;
@@ -106,15 +105,15 @@ export async function deleteWorkbenchArtifacts(input, options = {}) {
       || new Set(taskIds).size !== taskIds.length) fail('IRIS_COMMAND_INPUT_INVALID', '关联任务 ID 无效');
   active(options.signal);
   const artifactIds = chosen.map(item => item.id);
-  const base = await maintainWorkbenchForDsh('core.delete', { artifact_ids: artifactIds }, options);
+  const base = await options.core.maintainWorkbenchForDsh('core.delete', { artifact_ids: artifactIds }, options);
   const referencing = [...new Set(base.blockers.filter(blocker => ['task_artifact_reference', 'task_input_reference'].includes(blocker.reason)).map(blocker => blocker.referencedBy))];
   if (taskIds.some(id => !referencing.includes(id))) fail('IRIS_COMMAND_INPUT_INVALID', '只能显式选择这些作品直接关联的任务');
-  if (input.confirm_delete === true) return { ok: true, ...await maintainWorkbenchForDsh('core.delete', {
+  if (input.confirm_delete === true) return { ok: true, ...await options.core.maintainWorkbenchForDsh('core.delete', {
     artifact_ids: artifactIds, task_ids: taskIds, confirm_delete: true }, options) };
-  const plan = taskIds.length ? await maintainWorkbenchForDsh('core.delete', { artifact_ids: artifactIds, task_ids: taskIds }, options) : base;
+  const plan = taskIds.length ? await options.core.maintainWorkbenchForDsh('core.delete', { artifact_ids: artifactIds, task_ids: taskIds }, options) : base;
   const tasks = [];
   for (const id of referencing) {
-    const task = await inspectProviderTaskForDsh(id, options);
+    const task = await options.core.inspectProviderTaskForDsh(id, options);
     tasks.push({ id, settled: task.phase === 'terminal' && task.acceptance !== 'unknown' && task.outcome !== 'unknown' });
   }
   return { ok: true, preview: true, allowed: plan.allowed, artifactIds, taskIds, files: plan.entries.length,
@@ -122,7 +121,7 @@ export async function deleteWorkbenchArtifacts(input, options = {}) {
 }
 
 export async function workbenchTransactions(options = {}) {
-  return { ok: true, ...await maintainWorkbenchForDsh('core.transactions', {}, options) };
+  return { ok: true, ...await options.core.maintainWorkbenchForDsh('core.transactions', {}, options) };
 }
 
 export async function restoreWorkbenchTransaction(input, options = {}) {
@@ -130,7 +129,7 @@ export async function restoreWorkbenchTransaction(input, options = {}) {
   if (input.confirm_restore !== true) fail('IRIS_WORK_RESTORE_CONFIRM_REQUIRED', '请明确确认恢复此隔离事务');
   if (typeof input.transaction_id !== 'string' || !/^delete_[a-f0-9]{24}$/.test(input.transaction_id)) fail('IRIS_COMMAND_INPUT_INVALID', '隔离事务 ID 无效');
   active(options.signal);
-  return { ok: true, ...await maintainWorkbenchForDsh('core.restore', { transaction_id: input.transaction_id }, options) };
+  return { ok: true, ...await options.core.maintainWorkbenchForDsh('core.restore', { transaction_id: input.transaction_id }, options) };
 }
 
 /** API 边界只返回固定提示和稳定码，避免底层 ENOENT/JSON 错误带出文件路径。 */