@mokuyoaxis/dsh-iris 0.2.0 → 0.2.1

package/bin/dsh-iris.js

@@ -1,14 +1,31 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
+import path from 'node:path';
 import { createCommandService } from '../lib/command-service.js';
 import { createCoreRuntime } from '../lib/core-runtime.js';
 import { recoverCoreWriterLease } from '../lib/core-lease-recovery.js';
 import { doctor, formatDoctorReport } from '../lib/doctor.js';
 import { loadProviderCatalog, providerCatalogSnapshot, catalogCapabilitySnapshot, imageCandidatesFromCatalog, providerForTaskFromCatalog, providerTaskBinding, transcribeCandidatesFromCatalog, ttsCandidatesFromCatalog, videoCandidatesFromCatalog } from '../lib/provider-catalog.js';
 import { createConfiguredProviderAdapter } from '../lib/provider-adapters.js';
+import { providerForImageModel } from '../lib/provider-protocol.js';
 import { prepareProviderInput } from '../lib/provider-adapter.js';
 import { createProviderTaskRunner } from '../lib/provider-task-runner.js';
 import { GenerationInputError, normalizeGenerationInput } from '../lib/generation-input.js';
+import { executeVisionCommand, normalizeVisionInput } from '../lib/headless-vision.js';
+import { videoTaskCandidates } from '../lib/video-input.js';
+import { createChromiumBrowser } from '../lib/chromium-browser.js';
+import { executeConfigCommand, recordCatalogRateLimit } from '../lib/provider-config-service.js';
+import { probeVisionModel } from '../lib/vision-model-routing.js';
+import { RED_TEST_IMAGE } from '../lib/vision.js';
+import { parseModelRef, modelRef as qualifiedModelRef } from '../lib/models.js';
+import { coreTaskWaitFinished } from '../lib/task-wait.js';
+
+function trackedProviderAdapter(provider, options, task) {
+  return createConfiguredProviderAdapter(provider, {
+    modelId: parseModelRef(task?.modelRef)?.modelId,
+    onRateLimit: event => recordCatalogRateLimit(options['provider-config'], event)
+  });
+}
 
 class CliUsageError extends Error {
   constructor(message) {
@@ -21,27 +38,48 @@ class CliUsageError extends Error {
 function usage() {
   return [
     'Usage:',
+    '  JSON input: --input <json>, --input-file <path>, or --input - (stdin).',
     '  dsh-iris doctor [--data-root <absolute-path>] [--json]',
     '  dsh-iris runtime recover --data-root <absolute-path> --confirm-stale-pid <pid>',
     '  dsh-iris providers list --provider-config <absolute-path>',
     '  dsh-iris capabilities list --provider-config <absolute-path>',
+    '  dsh-iris config <init|show|check> --provider-config <absolute-path>',
+    '  dsh-iris providers <add|set> --provider-config <absolute-path> --input <provider-json>',
+    '  dsh-iris providers remove <provider-id> --provider-config <absolute-path>',
+    '  dsh-iris models list --provider-config <absolute-path>',
+    '  dsh-iris models <add|remove|caps|protocol|vision-input> <providerId::modelId> --provider-config <absolute-path> [--input <json>]',
+    '  dsh-iris models discover <provider-id> --provider-config <absolute-path> [--apply <true|false>]',
+    '  dsh-iris models test <providerId::modelId> --capability <vision|tts|image-gen|video-gen|transcribe> --provider-config <absolute-path> [--data-root <absolute-path>]',
+    '  dsh-iris assignments <list|set|clear> --provider-config <absolute-path> [--input <json>]',
+    '  dsh-iris vision <look|locate|ocr|summarize> --provider-config <absolute-path> --input <json> [--model-ref <providerId::modelId>] [--format <json|text>] [--output <path>] [--timeout-ms <1..120000>]',
+    '    Core artifact_id / frame_artifact_ids inputs or transcribe=true require --data-root <absolute-path>; summarize supports --sheet-output <path>.',
     '  dsh-iris run crop --data-root <absolute-path> --input <json>',
     '  dsh-iris media diff --data-root <absolute-path> --input <json>',
     '  dsh-iris media frames --data-root <absolute-path> --input <json>',
+    '  dsh-iris media html --data-root <absolute-path> --input <json> --browser-executable <absolute-path> [--browser-no-sandbox <true|false>] [--output <absolute-path>]',
     '  dsh-iris run image --data-root <absolute-path> --provider-config <absolute-path> --input <json>',
     '  dsh-iris run video --data-root <absolute-path> --provider-config <absolute-path> --input <json>',
     '  dsh-iris run tts --data-root <absolute-path> --provider-config <absolute-path> --input <json>',
     '  dsh-iris run transcribe --data-root <absolute-path> --provider-config <absolute-path> --input <json>',
     '  dsh-iris task inspect <id> --data-root <absolute-path>',
     '  dsh-iris task list --data-root <absolute-path>',
+    '    list supports --offset, --limit, --status, --capability, --provider-id, --model-ref, --outcome, --delivery-state.',
+    '  dsh-iris <task|artifact> inspect-many --data-root <absolute-path> --input <json>',
     '  dsh-iris task observe <id> --data-root <absolute-path> --provider-config <absolute-path>',
+    '  dsh-iris task wait <id> --data-root <absolute-path> [--provider-config <absolute-path>] [--timeout-ms <1..1200000>] [--poll-interval-ms <50..60000>]',
     '  dsh-iris task redeliver <id> --data-root <absolute-path> --provider-config <absolute-path>',
     '  dsh-iris task cancel <id> --data-root <absolute-path> --provider-config <absolute-path>',
     '  dsh-iris task retry <id> --data-root <absolute-path> --provider-config <absolute-path> --input <json> --confirm-billing [--model-ref <providerId::modelId>]',
     '  dsh-iris artifact inspect <id> --data-root <absolute-path>',
     '  dsh-iris artifact list --data-root <absolute-path>',
+    '    artifact list supports --offset, --limit, --kind, --media-type, --task-id.',
+    '  dsh-iris artifact export-many --data-root <absolute-path> --input <json> --output <absolute-directory>',
     '  dsh-iris artifact export <id> --data-root <absolute-path> --output <absolute-path>',
     '  dsh-iris artifact rebuild --data-root <absolute-path>',
+    '  dsh-iris core <delete|cleanup> --data-root <absolute-path> [--input <json>] [--confirm-delete]',
+    '    Default is a read-only preview. delete selects task_ids/artifact_ids; cleanup executes only explicitly selected preview paths.',
+    '  dsh-iris core transactions --data-root <absolute-path>',
+    '  dsh-iris core restore <transaction-id> --data-root <absolute-path>',
     '',
     'Commands never start DSH. run image and the task observe/redeliver/cancel/retry verbs contact a provider only when explicitly requested; credentials come from a private file. observe polls once, redeliver only re-downloads, and cancel is recorded as canceled only when the provider explicitly confirms; none of them ever submits an existing task again. task retry creates a NEW task that may incur duplicate generation billing and requires --confirm-billing; the prompt must be supplied again because Core never persists prompts.'
   ].join('\n');
@@ -52,15 +90,32 @@ function flags(args, allowed) {
   for (let index = 0; index < args.length; index += 2) {
     const flag = args[index];
     const name = typeof flag === 'string' && flag.startsWith('--') ? flag.slice(2) : '';
-    if (!name || !allowed.includes(name) || index + 1 >= args.length || String(args[index + 1]).startsWith('--')) {
+    if (!name || !(allowed.includes(name) || name === 'input-file' && allowed.includes('input')) || index + 1 >= args.length || String(args[index + 1]).startsWith('--')) {
       throw new CliUsageError('参数无效：' + String(flag || ''));
     }
     if (Object.prototype.hasOwnProperty.call(parsed, name)) throw new CliUsageError('参数重复：--' + name);
     parsed[name] = args[index + 1];
   }
+  if (parsed['input-file']) {
+    if (parsed.input !== undefined) throw new CliUsageError('--input 与 --input-file 只能选一个');
+    parsed.input = readJsonSource(parsed['input-file']);
+  } else if (parsed.input === '-') parsed.input = readJsonSource(0);
   return parsed;
 }
 
+function readJsonSource(file) {
+  let fd;
+  try {
+    fd = file === 0 ? 0 : fs.openSync(file, 'r');
+    const bytes = Buffer.alloc(2 * 1024 * 1024 + 1);
+    let offset = 0, count;
+    while (offset < bytes.length && (count = fs.readSync(fd, bytes, offset, bytes.length - offset, null))) offset += count;
+    if (offset === bytes.length) throw new Error('too large');
+    return bytes.subarray(0, offset).toString('utf8');
+  } catch (_) { throw new CliUsageError('无法读取 JSON 输入，或大小超过 2 MiB'); }
+  finally { if (fd !== undefined && fd !== 0) fs.closeSync(fd); }
+}
+
 function required(value, flag) {
   if (!String(value || '').trim()) throw new CliUsageError('缺少参数：--' + flag);
   return String(value);
@@ -87,6 +142,7 @@ function generationInput(capability, input, options) {
 
 /** C-8: catchable signals dispose active runtimes before the CLI exits. */
 const activeRuntimes = new Set();
+const cliAbortController = new AbortController();
 let shuttingDown = false;
 
 function registerRuntime(runtime) {
@@ -104,6 +160,7 @@ for (const signal of ['SIGINT', 'SIGTERM']) {
     const exitCode = signal === 'SIGINT' ? 130 : 143;
     if (shuttingDown) process.exit(exitCode);
     shuttingDown = true;
+    cliAbortController.abort();
     disposeActiveRuntimes()
       .catch(() => {})
       .finally(() => process.exit(exitCode));
@@ -151,6 +208,19 @@ async function main(args) {
     return 0;
   }
 
+  if (args[0] === 'core' && ['delete', 'cleanup', 'transactions', 'restore'].includes(args[1])) {
+    const verb = args[1], restoring = verb === 'restore', selecting = ['delete', 'cleanup'].includes(verb);
+    const rest = args.slice(restoring ? 3 : 2);
+    const confirmation = rest.filter(arg => arg === '--confirm-delete').length;
+    if (confirmation > 1 || (confirmation && !selecting)) throw new CliUsageError('--confirm-delete 参数无效或重复');
+    const options = flags(rest.filter(arg => arg !== '--confirm-delete'), ['data-root', ...(selecting ? ['input'] : [])]);
+    const input = restoring ? { transaction_id: required(args[2], 'transaction-id') } : selecting
+      ? { ...(options.input ? jsonInput(options.input) : {}), confirm_delete: confirmation === 1 } : {};
+    const result = await withRuntime(restoring || confirmation ? 'writer' : 'reader', options['data-root'], commands => commands.execute('core.' + verb, input));
+    console.log(JSON.stringify(result, null, 2));
+    return result.allowed === false ? 1 : 0;
+  }
+
   if (['providers', 'capabilities'].includes(args[0]) && args[1] === 'list') {
     const options = flags(args.slice(2), ['provider-config']);
     const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
@@ -159,6 +229,113 @@ async function main(args) {
     return 0;
   }
 
+  if (['config', 'providers', 'models', 'assignments'].includes(args[0])) {
+    const [group, verb] = args;
+    const verbs = { config: ['init', 'show', 'check'], providers: ['add', 'set', 'remove'], models: ['list', 'add', 'remove', 'caps', 'protocol', 'vision-input', 'discover', 'test'], assignments: ['list', 'set', 'clear'] };
+    if (!verbs[group].includes(verb)) throw new CliUsageError('未知配置命令');
+    const positional = (group === 'providers' && verb === 'remove') || (group === 'models' && verb !== 'list');
+    const id = positional ? required(args[2], group === 'providers' || verb === 'discover' ? 'provider-id' : 'model-ref') : undefined;
+    const options = flags(args.slice(positional ? 3 : 2), ['provider-config', 'input', 'apply', 'capability', 'data-root']);
+    if (options.apply !== undefined && !['true', 'false'].includes(options.apply)) throw new CliUsageError('--apply 必须是 true 或 false');
+    let input = options.input ? jsonInput(options.input) : {};
+    const probeInput = { ...input };
+    if (group === 'providers') input = ['add', 'set'].includes(verb) ? { provider: jsonInput(options.input) } : { provider_id: id };
+    if (group === 'models' && positional) {
+      if (verb === 'discover') input = { provider_id: id, apply: options.apply === 'true' };
+      else {
+        if (!parseModelRef(id)) throw new CliUsageError('模型必须用 providerId::modelId 复合引用');
+        input = { ...input, model_ref: id, ...(verb === 'test' ? { capability: required(options.capability, 'capability') } : {}) };
+      }
+    }
+    const result = await executeConfigCommand(required(options['provider-config'], 'provider-config'), group === 'config' ? verb : group + '.' + verb, input, {
+      signal: cliAbortController.signal,
+      probe: async ({ provider, modelId, capability, signal }) => {
+        if (capability === 'vision') return probeVisionModel(provider, modelId, { bytes: Buffer.from(RED_TEST_IMAGE.split(',')[1], 'base64'), mediaType: 'image/png' }, { signal });
+        if (['video-gen', 'transcribe'].includes(capability) && !options.input) return {
+          skipped: true, ok: false, reason: '请用 models test --input 提供与 run video/transcribe 相同的真实素材；未发起请求'
+        };
+        return withRawRuntime('writer', options['data-root'], async runtime => {
+          const mediaCapability = capability === 'image-gen' ? 'image' : capability === 'video-gen' ? 'video' : capability;
+          if (mediaCapability === 'image') provider = providerForImageModel(provider, modelId);
+          const adapter = createConfiguredProviderAdapter(provider, { allowRateLimited: true, modelId });
+          let providerInput = mediaCapability === 'image'
+            ? { prompt: 'red circle', n: 1, ...(['openai-chat-images', 'openai-responses-images'].includes(adapter.protocol) ? {} : {
+              size: adapter.protocol === 'openai-images' ? '256x256' : '512*512'
+            }) }
+            : { text: '你好', voice: provider.ttsVoice || 'Cherry' };
+          let candidates = [{ adapter, model: qualifiedModelRef(provider.id, modelId), selectionReason: 'explicit', providerBinding: providerTaskBinding(provider) }];
+          if (['video', 'transcribe'].includes(mediaCapability)) {
+            const normalized = generationInput(mediaCapability, { ...probeInput, model_ref: qualifiedModelRef(provider.id, modelId) },
+              { allowVideoPaths: true, allowAudioPath: true });
+            providerInput = normalized.providerInput;
+            if (mediaCapability === 'video') candidates = videoTaskCandidates(candidates, normalized);
+            else if (normalized.audioPath) {
+              const prepared = await prepareProviderInput(adapter, { model: modelId, filePath: normalized.audioPath, signal });
+              providerInput = generationInput('transcribe', { audio_url: prepared.url }).providerInput;
+            }
+          }
+          const submitted = await createProviderTaskRunner(runtime).submit({ capability: mediaCapability,
+            candidates, providerInput });
+          const waited = await createCommandService(runtime, { resolveTaskAdapter: () => adapter }).execute('task.wait', {
+            task_id: submitted.task.id, timeout_ms: 60000, poll_interval_ms: 1000 });
+          const task = waited.task;
+          return { ok: task.outcome === 'succeeded' && task.deliveryState === 'ready', taskId: task.id,
+            category: task.lastError?.category, httpStatus: task.lastError?.httpStatus };
+        });
+      }
+    });
+    console.log(JSON.stringify(result, null, 2));
+    return result.valid === false || result.passed === false ? 1 : 0;
+  }
+
+  if (args[0] === 'vision' && ['look', 'locate', 'ocr', 'summarize'].includes(args[1])) {
+    const command = args[1];
+    const options = flags(args.slice(2), ['provider-config', 'input', 'model-ref', 'format', 'output', 'sheet-output', 'data-root', 'timeout-ms']);
+    const input = normalizeVisionInput(command, jsonInput(options.input));
+    const format = options.format || 'json';
+    if (!['json', 'text'].includes(format)) throw new CliUsageError('--format 只支持 json 或 text');
+    if (options['sheet-output'] && command !== 'summarize') throw new CliUsageError('--sheet-output 仅适用于 summarize');
+    const outputs = [options.output, options['sheet-output']].filter(Boolean).map(file => path.resolve(file));
+    if (new Set(outputs).size !== outputs.length) throw new CliUsageError('结果文件与拼图文件不能是同一路径');
+    for (const file of outputs) {
+      try {
+        if (fs.existsSync(file) || !fs.statSync(path.dirname(file)).isDirectory()) throw new Error();
+        fs.accessSync(path.dirname(file), fs.constants.W_OK);
+      } catch (_) { throw new CliUsageError('输出文件已存在或父目录不可写'); }
+    }
+    const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
+    const execute = runtime => executeVisionCommand({ command, input, catalog, runtime,
+      onRateLimit: event => recordCatalogRateLimit(options['provider-config'], event),
+      modelRef: options['model-ref'] || '', signal: cliAbortController.signal,
+      ...(options['timeout-ms'] !== undefined ? { timeoutMs: Number(options['timeout-ms']) } : {}) });
+    const completed = input.transcribe
+      ? await withRawRuntime('writer', options['data-root'], execute)
+      : input.artifact_id || input.frame_artifact_ids ? await withRawRuntime('reader', options['data-root'], execute) : await execute();
+    if (cliAbortController.signal.aborted) return 130;
+    const rendered = (format === 'text' ? completed.text : JSON.stringify(completed.result, null, 2)) + '\n';
+    try {
+      if (options.output) fs.writeFileSync(path.resolve(options.output), rendered, { flag: 'wx', mode: 0o600 });
+      if (options['sheet-output']) fs.writeFileSync(path.resolve(options['sheet-output']), completed.sheetBuffer, { flag: 'wx', mode: 0o600 });
+    } catch (_) { throw new CliUsageError('无法保存输出文件（不会覆盖已有文件）'); }
+    process.stdout.write(rendered);
+    return completed.exitCode;
+  }
+
+  if (args[0] === 'media' && args[1] === 'html') {
+    const options = flags(args.slice(2), ['data-root', 'input', 'browser-executable', 'browser-no-sandbox', 'output']);
+    if (options['browser-no-sandbox'] !== undefined && !['true', 'false'].includes(options['browser-no-sandbox'])) throw new CliUsageError('--browser-no-sandbox 必须是 true 或 false');
+    const browser = createChromiumBrowser({ executable: options['browser-executable'] || process.env.IRIS_BROWSER_EXECUTABLE,
+      noSandbox: options['browser-no-sandbox'] === 'true' });
+    const input = jsonInput(options.input);
+    if (options.output && (!path.isAbsolute(options.output) || fs.existsSync(options.output))) throw new CliUsageError('--output 必须是未存在的绝对路径');
+    const result = await withRuntime('writer', options['data-root'], async commands => {
+      const rendered = await commands.execute('media.html', input);
+      return options.output ? { ...rendered, export: await commands.execute('artifact.export', { artifact_id: rendered.artifact.id, output_path: options.output }) } : rendered;
+    }, { browser });
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
   if (args[0] === 'media' && ['diff', 'frames'].includes(args[1])) {
     const options = flags(args.slice(2), ['data-root', 'input']);
     const input = jsonInput(options.input);
@@ -180,37 +357,37 @@ async function main(args) {
 
   if (args[0] === 'run' && args[1] === 'image') {
     const options = flags(args.slice(2), ['data-root', 'provider-config', 'input']);
-    const { providerInput, modelRef } = generationInput('image', jsonInput(options.input));
+    const { providerInput, modelRef, sourceArtifactId } = generationInput('image', jsonInput(options.input));
     const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
     const routes = imageCandidatesFromCatalog(catalog, modelRef);
     await withRawRuntime('writer', options['data-root'], async (runtime) => {
       const candidates = routes.map((route) => ({
-        adapter: createConfiguredProviderAdapter(route.provider), model: route.modelRef,
+        adapter: trackedProviderAdapter(route.provider, options), model: route.modelRef,
         selectionReason: route.selectionReason,
         providerBinding: providerTaskBinding(route.provider)
       }));
       const result = await createProviderTaskRunner(runtime).submit({
         capability: 'image', candidates,
-        providerInput
+        providerInput, sourceArtifactId
       });
       console.log(JSON.stringify(result, null, 2));
     });
     return 0;
   }
 
-  // 视频输入冻结（E 阶段 Profile）：t2v/i2v 的 prompt/img_data_url/size/duration；
-  // s2v 上传流程不在 headless 面开放。
+  // 视频共用 Core；本地首帧/音频按实际候选在 Attempt 内准备。
   if (args[0] === 'run' && args[1] === 'video') {
     const options = flags(args.slice(2), ['data-root', 'provider-config', 'input']);
-    const { providerInput, modelRef } = generationInput('video', jsonInput(options.input));
+    const normalized = generationInput('video', jsonInput(options.input), { allowVideoPaths: true });
+    const { providerInput, modelRef } = normalized;
     const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
     const routes = videoCandidatesFromCatalog(catalog, modelRef);
     await withRawRuntime('writer', options['data-root'], async (runtime) => {
-      const candidates = routes.map((route) => ({
-        adapter: createConfiguredProviderAdapter(route.provider), model: route.modelRef,
+      const candidates = videoTaskCandidates(routes.map((route) => ({
+        adapter: trackedProviderAdapter(route.provider, options), model: route.modelRef,
         selectionReason: route.selectionReason,
         providerBinding: providerTaskBinding(route.provider)
-      }));
+      })), normalized);
       const result = await createProviderTaskRunner(runtime).submit({
         capability: 'video', candidates,
         providerInput
@@ -228,7 +405,7 @@ async function main(args) {
     const routes = ttsCandidatesFromCatalog(catalog, modelRef);
     await withRawRuntime('writer', options['data-root'], async (runtime) => {
       const candidates = routes.map((route) => ({
-        adapter: createConfiguredProviderAdapter(route.provider), model: route.modelRef,
+        adapter: trackedProviderAdapter(route.provider, options), model: route.modelRef,
         selectionReason: route.selectionReason,
         providerBinding: providerTaskBinding(route.provider)
       }));
@@ -251,14 +428,14 @@ async function main(args) {
     let providerInput = normalized.providerInput;
     if (normalized.audioPath) {
       if (!fs.existsSync(normalized.audioPath)) throw new CliUsageError('音频文件不存在');
-      const prepared = await prepareProviderInput(createConfiguredProviderAdapter(routes[0].provider), {
+      const prepared = await prepareProviderInput(trackedProviderAdapter(routes[0].provider, options), {
         model: routes[0].model, filePath: normalized.audioPath
       });
       providerInput = generationInput('transcribe', { audio_url: prepared.url }).providerInput;
     }
     await withRawRuntime('writer', options['data-root'], async (runtime) => {
       const candidates = routes.map((route) => ({
-        adapter: createConfiguredProviderAdapter(route.provider), model: route.modelRef,
+        adapter: trackedProviderAdapter(route.provider, options), model: route.modelRef,
         selectionReason: route.selectionReason,
         providerBinding: providerTaskBinding(route.provider)
       }));
@@ -271,12 +448,24 @@ async function main(args) {
     return 0;
   }
 
+  if (args[0] === 'task' && args[1] === 'wait' && args[2]) {
+    const options = flags(args.slice(3), ['data-root', 'provider-config', 'timeout-ms', 'poll-interval-ms']);
+    const input = { task_id: args[2], ...(options['timeout-ms'] !== undefined ? { timeout_ms: Number(options['timeout-ms']) } : {}),
+      ...(options['poll-interval-ms'] !== undefined ? { poll_interval_ms: Number(options['poll-interval-ms']) } : {}) };
+    const inspected = await withRuntime('reader', options['data-root'], commands => commands.execute('task.inspect', { task_id: args[2] }));
+    const catalog = coreTaskWaitFinished(inspected.task) ? null : loadProviderCatalog(required(options['provider-config'], 'provider-config'));
+    const result = await withRuntime(catalog ? 'writer' : 'reader', options['data-root'], commands => commands.execute('task.wait', input), {
+      ...(catalog ? { resolveTaskAdapter: task => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task), options, task) } : {}) });
+    console.log(JSON.stringify(result, null, 2));
+    return result.timedOut ? 3 : result.ready ? 0 : 1;
+  }
+
   if (args[0] === 'task' && args[1] === 'observe' && args[2]) {
     const options = flags(args.slice(3), ['data-root', 'provider-config']);
     const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
     await withRuntime('reader', options['data-root'], (commands) => commands.execute('task.inspect', { task_id: args[2] }));
     const result = await withRuntime('writer', options['data-root'], (commands) => commands.execute('task.observe', { task_id: args[2] }), {
-      resolveTaskAdapter: (task) => createConfiguredProviderAdapter(providerForTaskFromCatalog(catalog, task))
+      resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task), options, task)
     });
     console.log(JSON.stringify(result, null, 2));
     return 0;
@@ -287,7 +476,7 @@ async function main(args) {
     const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
     await withRuntime('reader', options['data-root'], (commands) => commands.execute('task.inspect', { task_id: args[2] }));
     const result = await withRuntime('writer', options['data-root'], (commands) => commands.execute('task.redeliver', { task_id: args[2] }), {
-      resolveTaskAdapter: (task) => createConfiguredProviderAdapter(providerForTaskFromCatalog(catalog, task))
+      resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task), options, task)
     });
     console.log(JSON.stringify(result, null, 2));
     return 0;
@@ -298,7 +487,7 @@ async function main(args) {
     const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
     await withRuntime('reader', options['data-root'], (commands) => commands.execute('task.inspect', { task_id: args[2] }));
     const result = await withRuntime('writer', options['data-root'], (commands) => commands.execute('task.cancel', { task_id: args[2] }), {
-      resolveTaskAdapter: (task) => createConfiguredProviderAdapter(providerForTaskFromCatalog(catalog, task))
+      resolveTaskAdapter: (task) => trackedProviderAdapter(providerForTaskFromCatalog(catalog, task), options, task)
     });
     console.log(JSON.stringify(result, null, 2));
     return 0;
@@ -327,7 +516,7 @@ async function main(args) {
             ? transcribeCandidatesFromCatalog(catalog, modelRef || undefined)
             : imageCandidatesFromCatalog(catalog, modelRef || undefined)
       ).map((route) => ({
-        adapter: createConfiguredProviderAdapter(route.provider),
+        adapter: trackedProviderAdapter(route.provider, options),
         model: route.modelRef,
         selectionReason: route.selectionReason,
         providerBinding: providerTaskBinding(route.provider)
@@ -346,9 +535,10 @@ async function main(args) {
   }
 
   if (args[0] === 'task' && args[1] === 'list') {
-    const options = flags(args.slice(2), ['data-root']);
+    const options = flags(args.slice(2), ['data-root', 'offset', 'limit', 'status', 'capability', 'provider-id', 'model-ref', 'outcome', 'delivery-state']);
+    const input = Object.fromEntries(Object.entries(options).filter(([key]) => key !== 'data-root').map(([key, value]) => [key.replaceAll('-', '_'), ['offset', 'limit'].includes(key) ? Number(value) : value]));
     const result = await withRuntime('reader', options['data-root'], (commands) =>
-      commands.execute('task.list', {}));
+      commands.execute('task.list', input));
     console.log(JSON.stringify(result, null, 2));
     return 0;
   }
@@ -362,13 +552,24 @@ async function main(args) {
   }
 
   if (args[0] === 'artifact' && args[1] === 'list') {
-    const options = flags(args.slice(2), ['data-root']);
+    const options = flags(args.slice(2), ['data-root', 'offset', 'limit', 'kind', 'media-type', 'task-id']);
+    const input = Object.fromEntries(Object.entries(options).filter(([key]) => key !== 'data-root').map(([key, value]) => [key.replaceAll('-', '_'), ['offset', 'limit'].includes(key) ? Number(value) : value]));
     const result = await withRuntime('reader', options['data-root'], (commands) =>
-      commands.execute('artifact.list', {}));
+      commands.execute('artifact.list', input));
     console.log(JSON.stringify(result, null, 2));
     return 0;
   }
 
+  if (['task', 'artifact'].includes(args[0]) && ['inspect-many', 'export-many'].includes(args[1])) {
+    if (args[0] === 'task' && args[1] === 'export-many') throw new CliUsageError('仅 Artifact 支持 export-many');
+    const exporting = args[1] === 'export-many';
+    const options = flags(args.slice(2), ['data-root', 'input', ...(exporting ? ['output'] : [])]);
+    const input = { ...jsonInput(options.input), ...(exporting ? { output_directory: required(options.output, 'output') } : {}) };
+    const result = await withRuntime(exporting ? 'writer' : 'reader', options['data-root'], commands => commands.execute(args[0] + '.' + args[1], input));
+    console.log(JSON.stringify(result, null, 2));
+    return result.results.some(entry => entry.error) ? 1 : 0;
+  }
+
   if (args[0] === 'artifact' && args[1] === 'rebuild') {
     const options = flags(args.slice(2), ['data-root']);
     const result = await withRuntime('writer', options['data-root'], (commands) =>

package/docs/AGENT_QUICKSTART.md

@@ -2,15 +2,18 @@
 
 把下面一段交给负责安装或使用 Iris 的 Agent。版本与发布状态以当前 [README](../README.md) 为准；Iris 和 DSH 的版本号独立。
 
+当前安装版本为 Iris 0.2.1。先核对宿主与实际安装版本，再使用新视觉命令或 Artifact 改图；旧宿主仍固定安装 0.1.4。
+
 ## 中文
 
 ```text
 请根据本仓库 README，帮我安装并使用 Iris（@mokuyoaxis/dsh-iris）。
-先确认运行环境、目标 DSH profile，并用 dsh --version 核对宿主；Iris 0.2.0 要求 Node.js >=22.0.0（旧 npm 0.1.4 的历史要求为 >=20.10.0）：
-- DSH 0.2.0-rc.2：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.0。
+先确认运行环境、目标 DSH profile，并用 dsh --version 核对宿主；Iris 0.2.x 要求 Node.js >=22.0.0（旧 npm 0.1.4 的历史要求为 >=20.10.0）：
+- DSH 0.2.0-rc.2：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.1。
 - DSH >=0.1.2-rc.1 <0.1.3-0 或 0.1.5-rc.1：固定安装 dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4；只下载用 npm pack @mokuyoaxis/dsh-iris@0.1.4。
 - 其他 DSH 版本：先报告没有支持声明，不自行升级宿主或跳过版本检查。
-没有 DSH、希望用 CLI 时，按 docs/HEADLESS_CLI.md 使用 npm 0.2.0；npm 0.1.4 不含新的 Core 媒体 CLI。
+没有 DSH、希望用 CLI 时，按 docs/HEADLESS_CLI.md 使用 npm 0.2.1；npm 0.1.4 不含新的 Core 媒体 CLI。
+先用 --help 和 Doctor 核对实际版本与命令。Iris 0.2.1 支持 OpenAI 兼容图片与视觉工作流；其他协议与 music 是后续计划。
 从 dsh-market 安装也要核对实际包名、版本和兼容范围；市场缓存不代表支持旧宿主，不对旧 DSH 安装 latest。
 若使用其他 profile，把示例中的 web 换成已确认的目标。保留完整 scoped 包名，不把 dsh-iris 当作同一 npm 包。
 安装后检查 Doctor 和工具可达性，再执行我指定的媒体任务；不要输出 API Key，重启宿主前说明影响。
@@ -22,11 +25,12 @@
 
 ```text
 Help me install and use Iris (@mokuyoaxis/dsh-iris) according to this repository's README.
-Check the environment, target DSH profile, and dsh --version first; Iris 0.2.0 requires Node.js >=22.0.0 (the published npm 0.1.4 historically requires >=20.10.0):
-- DSH 0.2.0-rc.2: pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.0.
+Check the environment, target DSH profile, and dsh --version first; Iris 0.2.x requires Node.js >=22.0.0 (the published npm 0.1.4 historically requires >=20.10.0):
+- DSH 0.2.0-rc.2: pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.2.1.
 - DSH >=0.1.2-rc.1 <0.1.3-0 or 0.1.5-rc.1: pin dsh plugin --profile web add @mokuyoaxis/dsh-iris@0.1.4; download only with npm pack @mokuyoaxis/dsh-iris@0.1.4.
 - Other DSH versions: report the missing support claim; do not upgrade the host or bypass its version checks automatically.
-For CLI use without DSH, follow docs/HEADLESS_CLI.md using npm 0.2.0; npm 0.1.4 does not include the new Core media CLI.
+For CLI use without DSH, follow docs/HEADLESS_CLI.md using npm 0.2.1; npm 0.1.4 does not include the new Core media CLI.
+Check --help, Doctor and the actual installed version before using commands. Iris 0.2.1 supports the OpenAI-compatible image and vision workflow; additional protocols and music remain future work.
 For dsh-market, check the actual package name, version, and compatibility range too. Cached listings do not establish older-host support; do not install latest on an old DSH host.
 Replace web with the confirmed profile when needed. Keep the scoped package name; unscoped dsh-iris is a different npm package.
 Check Doctor and tool availability after installation, then carry out my requested media task. Do not expose API keys; explain the impact before restarting the host.

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Iris 架构与边界
 
-状态：Iris `0.2.0` 提供可在无 DSH 进程中运行的实例化 Core Runtime、Headless CLI、共享 Provider 生命周期、Core Task/Attempt 与 Artifact Manifest，并让 DSH 逐项消费同一套事实。DSH 插件仅支持 `0.2.0-rc.2`，Node.js 最低为 22.0.0；旧宿主固定使用 npm `0.1.4`。Core 内部 API 尚未冻结为公共 SDK。
+状态：本文面向 **Iris 0.2.1**。0.2.0 建立实例化 Core Runtime、Headless CLI、共享 Provider 生命周期与 Task/Artifact 事实；0.2.1 补共享视觉、模型级图片协议、Artifact 编辑及维护入口。DSH 插件仅支持 `0.2.0-rc.2`，Node.js 最低为 22.0.0；旧宿主固定使用 npm `0.1.4`。Core 内部 API 尚未冻结为公共 SDK。
 
 ## 当前形态
 
@@ -22,7 +22,7 @@ DSH Host / Cordis                         Headless CLI
                               ┌────────────┴────────────┐
                               ▼                         ▼
                     Command Service v0          Provider Task Runner
-                    crop / diff / frames        submit / observe /
+                    crop / diff / frames / html submit / observe /
                     inspect / control           cancel / delivery
                               └────────────┬────────────┘
                                            ▼
@@ -35,20 +35,21 @@ DSH Host / Cordis                         Headless CLI
 
 `lib/index.js` 是 DSH 插件装配入口，`lib/dsh-host-adapter.js` 是原始 DSH/Cordis 对象进入 Iris 的服务端边界；`lib/dsh-core-adapter.js` 只负责选择 DSH profile 的 Core 数据根、恢复 Provider 配置和投影 Host DTO。`bin/dsh-iris.js` 不启动 DSH，也不推断 profile。`lib/api.js` 与 `lib/client.js` 是 Host 投影，不是真相来源。
 
-未迁移能力仍走 0.1.4 legacy 链。当前主要包括 s2v 数字人视频、视觉理解、长图 OCR、媒体摘要、HTML 渲染和提示词优化；它们不会被伪装成 Core 能力。
+0.2.1的 S2V 使用 Core Task/Attempt，HTML 使用 `media.html` 与显式 Browser Port；视觉和提示词预览通过共享 Model Ports 执行。纯视觉不创建 Task/Artifact，摘要主动转写仍使用 Core 任务。聊天改图属于媒体生成链，按来源 Artifact ID 创建新 Task 和关联产物。
 
-## 0.2.0 核心
+## 共享核心
 
 | 模块 | 职责 | DSH 运行时依赖 |
 |---|---|---:|
 | `core-contract.js` / `core-runtime.js` | 显式数据根、reader/writer 权限、单写者租约、取消与释放 | 无 |
 | `command-service.js` | 本地媒体命令、Task 控制面和 Artifact 查询/导出 | 无 |
 | `generation-input.js` | CLI、DSH 与重试共用的生成参数校验和 Provider 字段转换 | 无 |
-| `model-port-contract.js` / `model-invoker.js` | Text/Vision 内部契约、有限调用预算与取消；真实消费者尚未接入 | 无 |
+| `model-port-contract.js` / `model-invoker.js` | Text/Vision 内部契约、有限调用预算与取消 | 无 |
 | `core-tasks.js` | Core Task/Attempt 持久事实、受理与交付状态 | 无 |
 | `core-artifacts.js` / `core-artifact-store.js` | 对象、Manifest、SHA-256、关系边与可重建 Index | 无 |
 | `provider-contract.js` / `provider-adapter.js` | canonical 结果、错误脱敏、受理边界与 Provider v0 操作 | 无 |
-| `provider-adapters.js` | DashScope / OpenAI Images 协议实现和可选输入准备 | 无 |
+| `provider-adapters.js` | DashScope / Images / 聊天 / Responses 图片协议和可选输入准备 | 无 |
+| `vision-image-input.js` / `image-edit-input.js` | 视觉发送副本与聊天改图来源预检；Core 原图保持不变 | 无 |
 | `provider-task-runner.js` | 写前 Attempt、submit/poll/cancel/download 与 Profile 化交付 | 无 |
 | `core-doctor.js` / `core-lease-recovery.js` | 只读完整性诊断与需显式确认的陈旧租约恢复 | 无 |
 | `provider-catalog.js` | 显式 Provider 配置、能力候选和原 Task Adapter 恢复 | 无 |
@@ -56,7 +57,7 @@ DSH Host / Cordis                         Headless CLI
 | `dsh-host-adapter.js` / `index.js` | Host 能力映射、工具/路由/Skill 与生命周期装配 | 有 |
 | `client.js` | DSH Web Slot、统一任务/作品区、泡泡和提示词入口 | 有 |
 
-完整规则见 [Core Runtime v0](CORE_RUNTIME_CONTRACT.md)、[Artifact Manifest v0](ARTIFACT_MANIFEST.md)、[Provider Adapter v0](PROVIDER_ADAPTER_CONTRACT.md) 与 [DSH → Core 渐进迁移](DSH_CORE_MIGRATION.md)。这些是 rc 候选内部契约，不是第三方 SDK 兼容承诺。
+完整规则见 [Core Runtime v0](CORE_RUNTIME_CONTRACT.md)、[Artifact Manifest v0](ARTIFACT_MANIFEST.md)、[Provider Adapter v0](PROVIDER_ADAPTER_CONTRACT.md) 与 [DSH → Core 渐进迁移](DSH_CORE_MIGRATION.md)。这些仍是内部契约，不是第三方 SDK 兼容承诺。
 
 ## Task、Attempt 与 Artifact
 
@@ -65,23 +66,29 @@ DSH Host / Cordis                         Headless CLI
 - 生成结果与本地交付是两类事实。远端成功后下载失败仍保持 `outcome=succeeded / deliveryState=failed`，可显式重新交付而不重新生成。
 - 新 Attempt 可选保存阶段时间戳与模型选择来源；旧记录缺少这些字段仍可读取。
 - Artifact Manifest v0 保存内容哈希、媒体类型、中性元数据和关系边；不保存 Prompt、API Key、签名 URL、Provider 端点或宿主绝对路径。
-- Core Task/Artifact 的删除与清理能力在 0.2.0 中保持封闭：DSH 与 CLI 都不提供 delete、clear 或 orphan purge。Doctor 只报告，不自动修复。
+- Core/CLI 已提供默认只读预览、明确选择与确认、文件隔离和恢复的删除/清理 Command，保护活跃 Task 和引用；索引更新只使用已提交记录，不升级或接回孤儿。DSH 作品区共用删除预览、隔离与事务恢复，永久 purge 未开放。Doctor 只报告，不自动修复。见 [CLI 管理与补齐](CLI_MANAGEMENT.md)。
 
-0.1.4 的 `tasks.json`、`artifacts.json`、`outputs/` 与上传目录继续作为 legacy 数据存在；Core 使用隔离的 `core-v0`。已迁移的新图片、视频、TTS 与转写任务不双写 legacy，回退到 0.1.4 时也不删除或改写 Core 数据。
+0.1.4 的 `tasks.json`、`artifacts.json`、`outputs/` 与上传目录继续作为 legacy 数据存在；Core 使用隔离的 `core-v0`。已迁移的新图片、视频、S2V、TTS 与转写任务不双写 legacy，回退到 0.1.4 时也不删除或改写 Core 数据。
 
 ## Provider 边界
 
 Provider Adapter v0 固定 discovery、submit、poll、cancel、download 与 error mapping 六类生命周期操作；提交前的临时输入上传是可选准备能力，不自动成为 Core 事实。协议实现只接收显式凭据、模型和媒体端点，Core 保存复合模型身份与非敏感 binding，不保存端点原文。
 
-Core Runner 不拥有后台 timer。Headless `task observe` 每次最多 poll 一次；DSH 的有界自动观察属于 Host，插件释放时停止 timer 并中止在途观察，但不会把“停止本地观察”写成“远端已取消”。端点或协议 binding 漂移时恢复在联网前拒绝。
+Core Runner 不拥有后台 timer。Headless `task observe` 每次最多 poll 一次，`task wait` 仅在本次命令内有界观察；DSH 的有界自动观察属于 Host，插件释放时停止 timer 并中止在途观察，但不会把“停止本地观察”写成“远端已取消”。端点或协议 binding 漂移时恢复在联网前拒绝。
 
 每个操作必须明确声明 supported 或 unsupported。当前 DashScope 与 OpenAI Images 媒体协议没有经过验证的远端取消实现，因此取消请求如实返回 not-supported，而不是伪造 canceled。完整受理与错误规则见 [Provider 提交契约 v0](PROVIDER_SUBMISSION_CONTRACT.md)。
 
-## Text/Vision 共享边界（M1 已实现）
+## Text/Vision 共享边界
 
-[Text/Vision Model Port v0](MODEL_PORT_CONTRACT.md) 的纯契约、调用控制与 test-only Fake Port 已实现，尚未接入真实消费者。它以 `describe()` 和单轮 `complete()` 统一文本/视觉输入、正常终态、预算、取消与安全错误；图片以字节和 MIME 进入共享层，模型选择、会话与附件桥接保留在入口/适配器。
+[Text/Vision Model Port v0](MODEL_PORT_CONTRACT.md) 的纯契约、调用控制与 test-only Fake Port 已发布于 0.2.0。它以 `describe()` 和单轮 `complete()` 统一文本/视觉输入、正常终态、预算、取消与安全错误；图片以字节和 MIME 进入共享层，模型选择、会话与附件桥接保留在入口/适配器。
 
-提示词优化与视觉理解不创建媒体生成 Task，不进入 Provider Task Runner。提示词优化的功能定位与输入隔离正在讨论，其接入待后续确定；look/relook、定位、OCR 与摘要仍按独立切片迁移。现有 Host 方法、配置与 CLI 均未因 M1 改变；自持文本目录和独立入口需要另行审查。
+0.2.1通过 `prompt-optimizer-core.js` → `model-invoker.js` → `dsh-text-model-adapter.js` 接入首个提示词消费者；`prompt-optimizer.js` 继续拥有 v1 配置、模型选择、reasoning 策略和 Host 投影。共享核心不读取 Host/配置/Store，不取得 writer，也不创建媒体 Task/Attempt/Artifact。规则与预览见 [提示词优化系统](PROMPT_OPTIMIZER.md)。
+
+单图视觉将 Agent/工作台 look/relook 和显式视觉实测接入 `vision-core.js` 与 HTTP/DSH Vision Port：共享 120 秒整体预算、完整终态与候选策略，图片桥接核验原图与实际附件，接受合法宿主规范化。DSH 附件保存属于宿主副作用，不是 Core Artifact；rc.2 保存不可取消的限制如实保留。见 [单图视觉调用](VISION_MODEL.md)。视觉 CLI 复用这些业务；可选 `visionInput` 在入口层控制发送副本。未新增公共 SDK export，自持文本目录和独立提示词入口另行安排。
+
+OCR 切片通过 `ocr-model-routing.js` 在入口解引用前建立整体 operation，`ocr.js` 仅接收图片字节和模型端口，使用现有 Sharp 做有限分块；全部块复用 `completeVision`，没有每块重置计时或调用额度。普通块失败可以产生明确部分结果，取消/超时终止整次操作；不取得 Core writer 或写入 Task/Artifact。见 [长图 OCR](OCR_MODEL.md)。
+
+定位、拼图摘要与生成后自述复用 `runVisionOperation`，`locate.js` / `summarize.js` 消费共享端口；入口处理附件、抽帧和可选 Core 转写，摘要读取已成功转写的文本 Artifact。纯视觉业务不写 Task/Artifact。legacy 视觉兼容实现保留，现有入口不再调用。见 [复合视觉调用](COMPOSITE_VISION.md)。
 
 ## Host Port 与 Headless 边界
 
@@ -90,7 +97,7 @@ Core Runner 不拥有后台 timer。Headless `task observe` 每次最多 poll
 | 工具注册与 Fiber 生命周期 | `ctx.tools` / `ctx.effect` | 不注册 DSH 工具；CLI/Core 不受影响 |
 | Web 路由 | `webServer` 或 `httpServer` | 无工作台 API 和同源媒体路由；CLI 直接导出 Artifact |
 | UI Slot | DSH Web Client | 不影响 Core Task、Artifact 与离线 Doctor |
-| Browser | DSH browser service | HTML 渲染不可用；本地媒体命令不受影响 |
+| Browser | DSH browser service | CLI 可显式提供独立 Chromium Browser Port；未提供时 HTML 不可用 |
 | 会话附件与输入草稿 | session/input ports | CLI 使用显式文件或 JSON 输入，不创建会话对象 |
 | Skills registry | DSH skills service | 随包 Skill 不自动注册；CLI/Core 仍可用 |
 
@@ -98,14 +105,14 @@ Command、Core Store、Provider Runner 和 Headless CLI 不接收原始 `ctx`、
 
 ## 事件、UI 与媒体读取
 
-DSH 工作台把 Core 与 legacy Task 合并到一个用户任务区，把 Core 图片与旧 `outputs/` 合并到一个作品区。普通投影只有五类用户状态；原始 Attempt 事实留在高级诊断。刷新、展开、关闭、读取作品和查询状态都不得触发 submit、poll 或隐式修复。
+DSH 工作台把 Core 与 legacy Task 合并到一个用户任务区，把 Core 与旧 `outputs/` 的图片、视频、音频和文本合并到一个作品区。普通投影只有五类用户状态；原始 Attempt 事实留在高级诊断。刷新、展开、关闭、读取作品和查询状态都不得触发 submit、poll 或隐式修复。
 
 Core 媒体路由按随机 Artifact ID 读取并逐次验证 SHA-256；它没有独立 token。浏览器请求还受可信 Host、`Origin`/`Sec-Fetch-Site` 和 `Referrer-Policy: no-referrer` 约束。Artifact ID 是持有者标识，不等于多租户认证；Iris 与 DSH 仍处于同一本机信任域。
 
 ## 非目标与发布边界
 
-- `0.2.0` 不启动独立常驻服务，也不复制 DSH 聊天界面。
+- `0.2.1` 不启动独立常驻服务，也不复制 DSH 聊天界面。
 - 不迁移到 SQLite/JSONL，不原地改写 0.1.4 数据，不自动接管不确定的写者租约。
-- 不在本候选新增 Gemini、Fal、Replicate 或本地模型协议；注册表只是后续接入点。
+- 0.2.1 未新增原生 Gemini、Fal、Replicate 或本地模型协议；注册表只是后续接入点。
 - 不把离线测试、一次 canary 或 Headless 可运行等同于公开 Core API 已冻结。
-- rc.1 仍须通过最终包审计、仓库外安装、跨平台 CI、Android 目视、回退和机器可读验证摘要后才能发布。
+- 发布检查覆盖版本元数据、实际包审计、仓库外安装与跨平台 CI；浏览器/移动端和真实异步重启范围单独记录，不由程序化检查推定通过。

package/docs/ARTIFACT_LIBRARY.md

@@ -1,12 +1,12 @@
-# Iris 作品库 v0
+# Iris legacy 作品库 v0
 
-状态：v0.1.4 候选实现。
+状态：自 v0.1.4 实现，Iris 0.2.1 保留兼容。本文只描述旧 `outputs/` 与最小索引；当前工作台同时展示 Core Artifact，分页、过滤、批量下载与可恢复隔离见 [工作台作品管理](WORKBENCH_ARTIFACTS.md)。
 
 作品库解决“清除任务历史后仍能看到本地作品”的问题。任务记录描述执行过程；作品记录只负责本地媒体的发现、展示和访问。两者生命周期彼此独立。
 
 ## 用户语义
 
-- 新生成并成功落盘的图片、视频和音频会自动进入作品库。
+- 旧链路生成并成功落盘的图片、视频和音频会进入此索引；0.2.1 的 Core 媒体链路使用独立 Manifest，并由统一作品库展示。
 - 首次升级到带作品库的版本时，Iris 会扫描现有 `outputs/` 并建立最小索引。
 - “清空已完成”或“清理 7 天前”只删除终态任务记录，作品仍可从工作台和泡泡打开。
 - “找回本地作品”会重新扫描 `outputs/`，补录受支持的普通媒体文件，并移除文件已经不存在的失效索引。
@@ -19,6 +19,6 @@
 
 作品链接继续复用 `/iris/media`，使用 128-bit 随机能力令牌并只从索引解析文件。错误 ID、令牌、文件名或路径穿越输入统一返回 404。作品库不是备份：删除作品文件、删除整个 Iris 数据目录或存储损坏仍可能造成数据丢失，重要作品应另行备份。
 
-## 与未来 Artifact Manifest 的边界
+## 与 Core Artifact Manifest 的边界
 
-v0 不是完整 Artifact Manifest：没有内容哈希、去重、旁车数据、来源/派生关系、引用图或跨宿主导出契约。完整 Manifest 完成崩溃一致性和安全评审后，再承载收藏、标签、搜索、筛选和批量导出等能力。
+legacy v0 没有内容哈希、去重、旁车数据、来源/派生关系、引用图或跨宿主导出契约。[Artifact Manifest v0](ARTIFACT_MANIFEST.md) 已在 0.2.0 实现，Core 保存 SHA-256、关系边和可重建索引，不原地改写旧作品。0.2.1 的统一工作台已提供分页、过滤、显式选择与批量 ZIP 下载；收藏、标签和搜索仍属后续计划。旧文件的永久删除与 Core 的可恢复隔离具有不同语义。