@mokuyoaxis/dsh-iris 0.2.6 → 0.2.7

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/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 错误带出文件路径。 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mokuyoaxis/dsh-iris",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Multi-provider image, video, music, and speech generation, transcription, visual understanding, and prompt optimization with an integrated Iris workbench for DeepSeek Harness.",
   "type": "module",
   "main": "lib/index.js",
@@ -30,7 +30,8 @@
     "!docs/releases/0.1.3.md",
     ".dsh/skills/iris-use",
     ".dsh/skills/iris-verify-ui",
-    ".dsh/skills/iris-compose-media"
+    ".dsh/skills/iris-compose-media",
+    "skills/iris-core"
   ],
   "dsh": {
     "engines": {

package/skills/iris-core/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: iris-core
+description: "Create, edit, and retrieve persistent Iris images through the standalone CLI without a running DSH host. Use for local image imports, revisions, existing task inspection, and artifact export."
+---
+
+# Iris Core · 核心图片工作流
+
+Organize the work around the image the user wants to receive. Reuse existing assets and tasks, preserve originals, and report actual results. Use this skill for a single image operation or a sequence of image revisions and delivery steps.
+
+## Choose the execution path · 确认执行入口
+
+Use the [standalone CLI reference](references/cli.md) to confirm the installed command, explicit data root, and private provider configuration needed for generation. Reuse information already established in the conversation. Do not scan another application's configuration or assume a personal directory, provider, or model.
+
+A visible skill does not prove that its execution tools are available. Report a missing command, connection, or capability precisely. This edition binds to the existing CLI; future MCP and independent workbench integrations need their own verified invocation instructions.
+
+## Plan the image work · 按作品组织步骤
+
+- Import a local image when it needs to become a persistent source. Reuse an existing Artifact in the current root without importing it again.
+- Generate for a new image request. For a revision, pass the source Artifact and requested changes to create a related version while retaining the original. Retrieve existing results instead of regenerating them.
+- Omit the model override unless the user specifies one, allowing the configured capability policy to select candidates. An explicit model must be allowed for that capability. Names, catalog entries, and past success do not establish present availability.
+- Add only steps needed for the requested result. An explicit edit can proceed directly; a generation request does not require extra paid vision checks or another generation.
+- Wait for actual delivery before starting a dependent operation. When content verification is required, use an image-reading capability available in the current host. Metadata and file existence alone do not establish visual correctness.
+
+## Preserve asset identities · 保持作品与任务身份
+
+An Artifact ID identifies a persistent asset in a particular Core root; a Task ID identifies an actual operation. Host attachment IDs, file paths, and playback URLs have different meanings. Do not interchange them or construct storage paths from IDs.
+
+Keep the returned Task and Artifact IDs at each handoff. Export to a new, explicit path when a consumer needs a file, preserving the original media format. Use the host's actual capabilities to present that file as an attachment.
+
+## Continue from recorded facts · 根据事实继续
+
+Check the Task's `acceptance`, `outcome`, `deliveryState`, and available Artifacts. Exit code 0 alone does not prove that an image was delivered. Inspect an existing task first; read [task continuation and recovery](references/tasks.md) when waiting, redelivery, cancellation, or an informed retry is needed.
+
+Preserve the original Task after interruption or unknown acceptance; do not probe by submitting another generation. If no Task ID was returned, list tasks read-only in the original root and identify the relevant record. Report uncertainty when that association cannot be established. A busy root does not authorize deleting a lease, taking over a writer, or hiding the original task in a new root.
+
+## Deliver the result · 交付实际结果
+
+Return the actual image file or a host-accessible asset, with the Task/Artifact IDs needed to continue. Distinguish availability, export, display in the conversation, and visual verification. Report partial results and unmet conditions accurately.
+
+This edition covers images and their tasks. It does not imply support for video, speech, UI operations, or a production MCP service in this entry point. Existing DSH skills continue to guide DSH-native tools and workbench workflows.

package/skills/iris-core/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Iris Core · 图片创作"
+  short_description: "Create, edit and retrieve persistent Iris images"
+  default_prompt: "Use $iris-core to create or revise my image, reuse existing tasks and artifacts, and return the actual result."

package/skills/iris-core/references/cli.md

@@ -0,0 +1,95 @@
+# Standalone CLI · 图片与作品
+
+The current executable binding is `dsh-iris`, which uses shared Application/Core operations without a running DSH host. Check the installed command with `dsh-iris --help`. In a confirmed source checkout, `node /absolute/path/to/iris/bin/dsh-iris.js` is also available. A missing command does not authorize installing software or changing package versions.
+
+These image, artifact, and task commands exist in 0.2.6. This skill is a new, unreleased package resource. Development-only Flow commands, local HTTP writes, and a future UI are not prerequisites.
+
+## Establish the context · 明确本次上下文
+
+Obtain these values from the user or already established context:
+
+- `IRIS_DATA_ROOT`: an absolute Core root. Continue each task in its original root.
+- `IRIS_PROVIDER_FILE`: a private provider JSON file for generation/editing or remote observation. Import, export, and read-only inspection do not need it.
+- `IRIS_INPUT_FILE`: the operation's JSON input file, containing the actual request and necessary parameters.
+- `IRIS_TASK_ID` / `IRIS_ARTIFACT_ID`: IDs actually returned by Iris.
+- `IRIS_OUTPUT_FILE`: a new absolute output path requested by the user or chosen in the task workspace, with an extension matching the real media type.
+
+Quote these variables in the shell; they are example shell variables, not configuration Iris discovers automatically. Pass request content through a JSON file or stdin instead of inserting user prompts into shell code. Keep private creative input in appropriately protected files without overwriting existing user files.
+
+Do not assume a personal DSH root. Choose a task-specific root for new work when the context permits; changing roots cannot recover an existing task. Use an explicitly supplied provider configuration without printing its credentials.
+
+## Inspect configuration · 查询配置
+
+Read the configured candidate summary when the allowed scope is unclear; do not test configuration by generating:
+
+```bash
+dsh-iris capabilities list --provider-config "$IRIS_PROVIDER_FILE"
+```
+
+This reports configuration and historical evidence, not remote availability. Report an empty candidate list without adding vendor defaults or expanding the capability pool.
+
+## Import a local image · 导入本地图片
+
+Set `IRIS_INPUT_FILE` to a file containing `{"image_path":"/absolute/path/source.png"}`, then run:
+
+```bash
+dsh-iris artifact import --data-root "$IRIS_DATA_ROOT" --input-file "$IRIS_INPUT_FILE"
+```
+
+The source must be a static PNG/JPEG/WebP of at most 20 MiB. Keep the returned `artifact.id`, source file, and original bytes. Import does not call a provider or create a generation Task. A host upload must first become a readable file; this CLI does not accept a host attachment ID.
+
+## Generate an image · 生成新图
+
+Write the user's original or authorized revised request into the input file, for example:
+
+```json
+{"prompt":"An iris flower after the rain","n":1}
+```
+
+```bash
+dsh-iris run image --data-root "$IRIS_DATA_ROOT" --provider-config "$IRIS_PROVIDER_FILE" --input-file "$IRIS_INPUT_FILE"
+```
+
+Set `n` to the requested count (1–4); do not increase it for testing. Supply `size` only when requested and supported. Omit `model_ref` unless a model was specified; use an allowed `providerId::modelId` for an explicit choice. An explicit choice has no candidate fallback. Default candidate switching requires evidence of non-acceptance.
+
+## Edit an existing image · 编辑已有图片
+
+Use the same `run image` command with the actual source Artifact ID in the input:
+
+```json
+{"source_artifact_id":"artifact_0123456789abcdef01234567","prompt":"Make the background green while preserving the subject","n":1}
+```
+
+Replace the example ID with a real Artifact in the original root. The source is retained; the new Task's `sourceArtifactId` and new Artifact's `derived-from` relation record its origin. The model must be allowed for images and support an implemented edit protocol. Report an unsupported protocol without substituting a new text-to-image request.
+
+## Inspect tasks and artifacts · 查询原任务和作品
+
+```bash
+dsh-iris task inspect "$IRIS_TASK_ID" --data-root "$IRIS_DATA_ROOT"
+```
+
+```bash
+dsh-iris artifact inspect "$IRIS_ARTIFACT_ID" --data-root "$IRIS_DATA_ROOT"
+```
+
+Read the Task's `id`, `acceptance`, `outcome`, `deliveryState`, `artifactIds`, and Attempt facts. Read the Artifact's `id`, `mediaType`, size, digest, and provenance. `outcome=succeeded` with `deliveryState=ready` establishes completed local delivery. A failed operation can still have partial artifacts; preserve them.
+
+These inspections do not call providers, initialize missing roots, or require provider configuration. They do not advance a queued remote task.
+
+If a Task ID was not returned, list the original root's tasks read-only and identify the relevant record:
+
+```bash
+dsh-iris task list --data-root "$IRIS_DATA_ROOT" --capability image --limit 20
+```
+
+Retain uncertainty when the association is not reliable; the most recent task is not necessarily this request.
+
+## Export an artifact · 导出已有作品
+
+```bash
+dsh-iris artifact export "$IRIS_ARTIFACT_ID" --data-root "$IRIS_DATA_ROOT" --output "$IRIS_OUTPUT_FILE"
+```
+
+Export copies the original bytes without generation, conversion, or overwriting an existing file. Choose the extension from `mediaType`. Successful export does not establish display as a conversation attachment; use the current host to read or present the file as requested.
+
+For observation, redelivery, cancellation, or informed retries, read [task continuation and recovery](tasks.md) instead of using another generation command as recovery.

package/skills/iris-core/references/tasks.md

@@ -0,0 +1,58 @@
+# Image task recovery · 任务继续与恢复
+
+Inspect the Task in its original data root first. Tasks do not persist prompts; do not reconstruct the user's input from a task summary. Inspection has no provider side effects. Observe or recover only as needed for the current request.
+
+| Recorded fact | Action |
+|---|---|
+| Accepted and still queued/running | Observe or wait for the original Task; do not create another generation |
+| `outcome=succeeded`, `deliveryState=ready` | Retrieve existing Artifacts and export as needed |
+| `outcome=succeeded`, `deliveryState=failed` | Redeliver the original result, preferring a complete local cache |
+| Unknown acceptance/outcome, or an Attempt without a reliable response | Preserve the original Task and uncertainty; do not infer that no work or billing occurred |
+| User requests stopping | Stop subsequent generation; remote cancellation succeeds only with protocol support and provider confirmation |
+| User knowingly requests retrying a terminal task without successful delivery | Create a linked new Task with possible additional billing, preserving the original |
+
+An unfinished Attempt with `acceptance=none` does not prove that nothing was sent. Local timeout, CLI interruption, and stopping a local wait do not establish successful remote cancellation.
+
+## Observe and wait · 观察与等待
+
+Use the original provider binding. A single observation advances at most one poll:
+
+```bash
+dsh-iris task observe "$IRIS_TASK_ID" --data-root "$IRIS_DATA_ROOT" --provider-config "$IRIS_PROVIDER_FILE"
+```
+
+Use bounded waiting when needed, adjusting the limit to the user's task:
+
+```bash
+dsh-iris task wait "$IRIS_TASK_ID" --data-root "$IRIS_DATA_ROOT" --provider-config "$IRIS_PROVIDER_FILE" --timeout-ms 120000 --poll-interval-ms 2500
+```
+
+Observation and waiting do not resubmit or create a background loop. Terminal inspection needs no provider configuration. Report protocols without remote observation support. `task wait` exits 0 for ready, 1 for unsuccessful delivery, and 3 for timeout; timeout preserves the original task facts.
+
+## Redeliver · 补交付
+
+```bash
+dsh-iris task redeliver "$IRIS_TASK_ID" --data-root "$IRIS_DATA_ROOT" --provider-config "$IRIS_PROVIDER_FILE"
+```
+
+Recover the original result only when the Task state permits it. A complete cache can deliver offline; missing bytes may require retrieving the original remote result. Verify the original provider/model binding without switching to the current candidate pool or regenerating.
+
+## Cancel · 取消
+
+```bash
+dsh-iris task cancel "$IRIS_TASK_ID" --data-root "$IRIS_DATA_ROOT" --provider-config "$IRIS_PROVIDER_FILE"
+```
+
+Execute only when the task state and protocol permit it. Report unsupported or unconfirmed cancellation accurately instead of claiming that remote work was revoked.
+
+## Retry with informed authorization · 知情重试
+
+Use this operation after the user has authorized a retry with possible duplicate billing; do not ask again for authorization already given. Supply the prompt again in the input file, and the original `source_artifact_id` for an edit:
+
+```bash
+dsh-iris task retry "$IRIS_TASK_ID" --data-root "$IRIS_DATA_ROOT" --provider-config "$IRIS_PROVIDER_FILE" --confirm-billing --input-file "$IRIS_INPUT_FILE"
+```
+
+This creates a new Task with `retriedFrom`, leaving the original intact. `--confirm-billing` is a standalone switch with no following value. Specify a retry model with the outer `--model-ref` flag, not the `model_ref` field used by `run image` input.
+
+A busy root, stale lease, or mismatched binding is an execution gap. This skill does not delete leases, take over writers, migrate data, or reset configuration.