@mokuyoaxis/dsh-iris 0.1.3 → 0.2.0

package/bin/dsh-iris.js

@@ -1,23 +1,402 @@
 #!/usr/bin/env node
+import fs from 'node:fs';
+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 { prepareProviderInput } from '../lib/provider-adapter.js';
+import { createProviderTaskRunner } from '../lib/provider-task-runner.js';
+import { GenerationInputError, normalizeGenerationInput } from '../lib/generation-input.js';
+
+class CliUsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CliUsageError';
+    this.code = 'IRIS_CLI_USAGE';
+  }
+}
 
 function usage() {
   return [
-    'Usage: dsh-iris doctor [--json]',
+    'Usage:',
+    '  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 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 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>',
+    '  dsh-iris task observe <id> --data-root <absolute-path> --provider-config <absolute-path>',
+    '  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>',
+    '  dsh-iris artifact export <id> --data-root <absolute-path> --output <absolute-path>',
+    '  dsh-iris artifact rebuild --data-root <absolute-path>',
     '',
-    'Runs offline diagnostics only. It does not start DSH or send provider requests.'
+    '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');
 }
 
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h')) {
-  console.log(usage());
-  process.exitCode = 0;
-} else if (args[0] !== 'doctor' || args.some((arg, index) => index > 0 && arg !== '--json')) {
-  console.error(usage());
-  process.exitCode = 2;
-} else {
-  const report = await doctor();
-  console.log(args.includes('--json') ? JSON.stringify(report, null, 2) : formatDoctorReport(report));
-  process.exitCode = report.exitCode;
+function flags(args, allowed) {
+  const parsed = {};
+  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('--')) {
+      throw new CliUsageError('参数无效：' + String(flag || ''));
+    }
+    if (Object.prototype.hasOwnProperty.call(parsed, name)) throw new CliUsageError('参数重复：--' + name);
+    parsed[name] = args[index + 1];
+  }
+  return parsed;
+}
+
+function required(value, flag) {
+  if (!String(value || '').trim()) throw new CliUsageError('缺少参数：--' + flag);
+  return String(value);
+}
+
+function jsonInput(value) {
+  try {
+    const parsed = JSON.parse(required(value, 'input'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not object');
+    return parsed;
+  } catch (error) {
+    if (error instanceof CliUsageError) throw error;
+    throw new CliUsageError('--input 必须是 JSON 对象');
+  }
+}
+
+function generationInput(capability, input, options) {
+  try { return normalizeGenerationInput(capability, input, options); }
+  catch (error) {
+    if (error instanceof GenerationInputError) throw new CliUsageError(error.message);
+    throw error;
+  }
+}
+
+/** C-8: catchable signals dispose active runtimes before the CLI exits. */
+const activeRuntimes = new Set();
+let shuttingDown = false;
+
+function registerRuntime(runtime) {
+  activeRuntimes.add(runtime);
+  return () => activeRuntimes.delete(runtime);
+}
+
+async function disposeActiveRuntimes() {
+  await Promise.allSettled([...activeRuntimes].map((runtime) => runtime.dispose().catch(() => {})));
+  activeRuntimes.clear();
+}
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    const exitCode = signal === 'SIGINT' ? 130 : 143;
+    if (shuttingDown) process.exit(exitCode);
+    shuttingDown = true;
+    disposeActiveRuntimes()
+      .catch(() => {})
+      .finally(() => process.exit(exitCode));
+  });
+}
+
+async function withRawRuntime(mode, dataRoot, callback) {
+  const runtime = createCoreRuntime({ dataRoot: required(dataRoot, 'data-root'), mode });
+  const unregister = registerRuntime(runtime);
+  try {
+    runtime.start();
+    return await callback(runtime);
+  } finally {
+    try { await runtime.dispose(); } finally { unregister(); }
+  }
+}
+
+async function withRuntime(mode, dataRoot, callback, ports = {}) {
+  return withRawRuntime(mode, dataRoot, (runtime) => callback(createCommandService(runtime, ports)));
+}
+
+async function main(args) {
+  if (!args.length || args.includes('--help') || args.includes('-h')) {
+    console.log(usage());
+    return args.length ? 0 : 2;
+  }
+
+  if (args[0] === 'doctor') {
+    const rest = args.slice(1);
+    if (rest.filter((arg) => arg === '--json').length > 1) throw new CliUsageError('参数重复：--json');
+    const options = flags(rest.filter((arg) => arg !== '--json'), ['data-root']);
+    const report = await doctor({ ...(options['data-root'] ? { dataRoot: options['data-root'] } : {}) });
+    console.log(rest.includes('--json') ? JSON.stringify(report, null, 2) : formatDoctorReport(report));
+    return report.exitCode;
+  }
+
+  if (args[0] === 'runtime' && args[1] === 'recover') {
+    const options = flags(args.slice(2), ['data-root', 'confirm-stale-pid']);
+    const confirmStalePid = Number(required(options['confirm-stale-pid'], 'confirm-stale-pid'));
+    if (!Number.isSafeInteger(confirmStalePid) || confirmStalePid <= 0) {
+      throw new CliUsageError('--confirm-stale-pid 必须是 Doctor 报告中的正整数 PID');
+    }
+    const result = recoverCoreWriterLease(required(options['data-root'], 'data-root'), { confirmStalePid });
+    console.log(JSON.stringify(result, null, 2));
+    return 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'));
+    const report = args[0] === 'providers' ? providerCatalogSnapshot(catalog) : catalogCapabilitySnapshot(catalog);
+    console.log(JSON.stringify(report, 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);
+    const command = args[1] === 'diff' ? 'media.diff' : 'media.frames';
+    const result = await withRuntime('writer', options['data-root'], (commands) =>
+      commands.execute(command, input));
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (args[0] === 'run' && args[1] === 'crop') {
+    const options = flags(args.slice(2), ['data-root', 'input']);
+    const input = jsonInput(options.input);
+    const result = await withRuntime('writer', options['data-root'], (commands) =>
+      commands.execute('crop', input));
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  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 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,
+        selectionReason: route.selectionReason,
+        providerBinding: providerTaskBinding(route.provider)
+      }));
+      const result = await createProviderTaskRunner(runtime).submit({
+        capability: 'image', candidates,
+        providerInput
+      });
+      console.log(JSON.stringify(result, null, 2));
+    });
+    return 0;
+  }
+
+  // 视频输入冻结（E 阶段 Profile）：t2v/i2v 的 prompt/img_data_url/size/duration；
+  // s2v 上传流程不在 headless 面开放。
+  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 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,
+        selectionReason: route.selectionReason,
+        providerBinding: providerTaskBinding(route.provider)
+      }));
+      const result = await createProviderTaskRunner(runtime).submit({
+        capability: 'video', candidates,
+        providerInput
+      });
+      console.log(JSON.stringify(result, null, 2));
+    });
+    return 0;
+  }
+
+  // 语音合成输入冻结（E2 Profile）：同步完成型，一次命令内完成 Task → Artifact。
+  if (args[0] === 'run' && args[1] === 'tts') {
+    const options = flags(args.slice(2), ['data-root', 'provider-config', 'input']);
+    const { providerInput, modelRef } = generationInput('tts', jsonInput(options.input));
+    const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
+    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,
+        selectionReason: route.selectionReason,
+        providerBinding: providerTaskBinding(route.provider)
+      }));
+      const result = await createProviderTaskRunner(runtime).submit({
+        capability: 'tts', candidates,
+        providerInput
+      });
+      console.log(JSON.stringify(result, null, 2));
+    });
+    return 0;
+  }
+
+  // 转写输入冻结（E3 Profile）：上传型异步——audio_url（公网/oss://）或
+  // audio_path（本地文件，经首选候选 Provider 的临时存储上传，签名 URL 不落 Core）。
+  if (args[0] === 'run' && args[1] === 'transcribe') {
+    const options = flags(args.slice(2), ['data-root', 'provider-config', 'input']);
+    const normalized = generationInput('transcribe', jsonInput(options.input), { allowAudioPath: true });
+    const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
+    const routes = transcribeCandidatesFromCatalog(catalog, normalized.modelRef);
+    let providerInput = normalized.providerInput;
+    if (normalized.audioPath) {
+      if (!fs.existsSync(normalized.audioPath)) throw new CliUsageError('音频文件不存在');
+      const prepared = await prepareProviderInput(createConfiguredProviderAdapter(routes[0].provider), {
+        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,
+        selectionReason: route.selectionReason,
+        providerBinding: providerTaskBinding(route.provider)
+      }));
+      const result = await createProviderTaskRunner(runtime).submit({
+        capability: 'transcribe', candidates,
+        providerInput
+      });
+      console.log(JSON.stringify(result, null, 2));
+    });
+    return 0;
+  }
+
+  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))
+    });
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (args[0] === 'task' && args[1] === 'redeliver' && 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.redeliver', { task_id: args[2] }), {
+      resolveTaskAdapter: (task) => createConfiguredProviderAdapter(providerForTaskFromCatalog(catalog, task))
+    });
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (args[0] === 'task' && args[1] === 'cancel' && 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.cancel', { task_id: args[2] }), {
+      resolveTaskAdapter: (task) => createConfiguredProviderAdapter(providerForTaskFromCatalog(catalog, task))
+    });
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (args[0] === 'task' && args[1] === 'retry' && args[2]) {
+    const rest = args.slice(3);
+    const confirmBilling = rest.includes('--confirm-billing');
+    const options = flags(rest.filter((arg) => arg !== '--confirm-billing'),
+      ['data-root', 'provider-config', 'input', 'model-ref']);
+    const input = jsonInput(options.input);
+    const catalog = loadProviderCatalog(required(options['provider-config'], 'provider-config'));
+    const dataRoot = required(options['data-root'], 'data-root');
+    await withRuntime('reader', dataRoot, (commands) => commands.execute('task.inspect', { task_id: args[2] }));
+    const result = await withRuntime('writer', dataRoot, (commands) => commands.execute('task.retry', {
+      task_id: args[2],
+      provider_input: input,
+      model_ref: options['model-ref'],
+      confirm_billing: confirmBilling
+    }), {
+      resolveTaskCandidates: ({ capability, modelRef }) => (capability === 'video'
+        ? videoCandidatesFromCatalog(catalog, modelRef || undefined)
+        : capability === 'tts'
+          ? ttsCandidatesFromCatalog(catalog, modelRef || undefined)
+          : capability === 'transcribe'
+            ? transcribeCandidatesFromCatalog(catalog, modelRef || undefined)
+            : imageCandidatesFromCatalog(catalog, modelRef || undefined)
+      ).map((route) => ({
+        adapter: createConfiguredProviderAdapter(route.provider),
+        model: route.modelRef,
+        selectionReason: route.selectionReason,
+        providerBinding: providerTaskBinding(route.provider)
+      }))
+    });
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (args[0] === 'task' && args[1] === 'inspect' && args[2]) {
+    const options = flags(args.slice(3), ['data-root']);
+    const result = await withRuntime('reader', options['data-root'], (commands) =>
+      commands.execute('task.inspect', { task_id: args[2] }));
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (args[0] === 'task' && args[1] === 'list') {
+    const options = flags(args.slice(2), ['data-root']);
+    const result = await withRuntime('reader', options['data-root'], (commands) =>
+      commands.execute('task.list', {}));
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (args[0] === 'artifact' && args[1] === 'inspect' && args[2]) {
+    const options = flags(args.slice(3), ['data-root']);
+    const result = await withRuntime('reader', options['data-root'], (commands) =>
+      commands.execute('artifact.inspect', { artifact_id: args[2] }));
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (args[0] === 'artifact' && args[1] === 'list') {
+    const options = flags(args.slice(2), ['data-root']);
+    const result = await withRuntime('reader', options['data-root'], (commands) =>
+      commands.execute('artifact.list', {}));
+    console.log(JSON.stringify(result, null, 2));
+    return 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) =>
+      commands.execute('artifact.rebuild', {}));
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (args[0] === 'artifact' && args[1] === 'export' && args[2]) {
+    const options = flags(args.slice(3), ['data-root', 'output']);
+    const result = await withRuntime('writer', options['data-root'], (commands) =>
+      commands.execute('artifact.export', {
+        artifact_id: args[2],
+        output_path: required(options.output, 'output')
+      }));
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  throw new CliUsageError('未知命令');
+}
+
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  const code = error && error.code || 'IRIS_CLI_FAILED';
+  const message = error && error.message || '命令执行失败';
+  console.error(code + ': ' + message);
+  if (error instanceof CliUsageError) console.error('\n' + usage());
+  process.exitCode = error instanceof CliUsageError ? 2 : 1;
 }

package/docs/AGENT_QUICKSTART.md

@@ -0,0 +1,35 @@
+# 给 AI Agent 的简要 Prompt
+
+把下面一段交给负责安装或使用 Iris 的 Agent。版本与发布状态以当前 [README](../README.md) 为准；Iris 和 DSH 的版本号独立。
+
+## 中文
+
+```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 >=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-market 安装也要核对实际包名、版本和兼容范围；市场缓存不代表支持旧宿主，不对旧 DSH 安装 latest。
+若使用其他 profile，把示例中的 web 换成已确认的目标。保留完整 scoped 包名，不把 dsh-iris 当作同一 npm 包。
+安装后检查 Doctor 和工具可达性，再执行我指定的媒体任务；不要输出 API Key，重启宿主前说明影响。
+查询、观察和重新取回不等于重新生成；任务已受理或受理未知时，不自动重新提交。
+最后报告所用 Iris/DSH 版本、安装来源和实际验证结果。
+```
+
+## English
+
+```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.
+- 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 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.
+Inspect, observe, and redeliver do not create a new generation. Never resubmit automatically after accepted or unknown acceptance.
+Report the Iris/DSH versions, installation source, and actual validation results.
+```

package/docs/ARCHITECTURE.md

@@ -1,81 +1,111 @@
 # Iris 架构与边界
 
-状态：v0.1.3 当前实现。本文描述已经存在的代码边界，不把 0.2+ 规划写成现成功能。
+状态：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 目前以 DeepSeek Harness 插件运行。DSH 提供 Agent 工具注册、会话附件、浏览器和 Web UI 插槽；Iris 自己负责供应商配置、媒体动作、可信任务、产物落盘、媒体授权路由和工作台投影。
+Iris 仍以一个 npm 包交付，但已有两个执行入口：DSH 插件负责 Agent 工具、会话附件、浏览器、Web UI 和后台观察；Headless CLI 在没有 DSH/Cordis 的进程中显式接收数据根与私有 Provider 配置。两者共用 Core Runtime、Provider Task Runner、Task/Artifact Store 和本地 Command，不能在同一数据根上同时充当写者。
 
 ```text
-DSH Host / Cordis
-  ├─ Agent tools ───────────────┐
-  ├─ Web slots / browser        │
-  └─ attachment/session ports   │
-                                ▼
-                         actions.runAction
-                         ├─ provider adapters
-                         ├─ Task / Attempt v2
-                         ├─ media delivery
-                         └─ vision / local media tools
-                                │
-                                ▼
-                     $DSH_HOME/iris/v1
-                     providers.json · tasks.json
-                     outputs/ · uploads/
+DSH Host / Cordis                         Headless CLI
+  ├─ Agent tools / Web UI                   ├─ explicit --data-root
+  ├─ attachment / browser ports             └─ private provider config
+  └─ bounded observation timers                       │
+               │                                      │
+     dsh-host-adapter.js                    bin/dsh-iris.js
+               │                                      │
+       dsh-core-adapter.js ────────────────┬───────────┘
+                                           ▼
+                                  Core Runtime v0
+                           explicit root · reader/writer
+                           lease · AbortSignal · disposal
+                              ┌────────────┴────────────┐
+                              ▼                         ▼
+                    Command Service v0          Provider Task Runner
+                    crop / diff / frames        submit / observe /
+                    inspect / control           cancel / delivery
+                              └────────────┬────────────┘
+                                           ▼
+                         Core Task Store + Artifact Manifest
+                         records · objects · SHA-256 · index
+                                           │
+                    DSH: $DSH_HOME/iris/v1/core-v0
+                    CLI: explicit absolute data root
 ```
 
-`lib/index.js` 是 DSH Host Adapter 的当前集中入口；`lib/client.js` 只消费同源 API 与 DSH UI Slot。`lib/api.js` 是工作台 HTTP 投影，不是真相来源。Task 的持久事实由 `lib/tasks.js` 管理。
+`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.0 核心
 
 | 模块 | 职责 | DSH 运行时依赖 |
 |---|---|---:|
-| `task-semantics.js` | Task v2 枚举、旧状态与用户状态派生、自洽校验 | 无 |
-| `provider-contract.js` | 提交结果、受理边界、错误脱敏、候选调度 | 无 |
-| `tasks.js` | Task/Attempt 持久化、观察、恢复与交付状态 | 无；数据根仍沿用 `DSH_HOME` |
-| `doctor.js` | 零网络离线环境与数据诊断 | 无 |
-| `actions.js` | GUI 与 Agent 共用动作 | 有宿主上下文参数，部分动作依赖 Browser/会话能力 |
-| `index.js` | DSH 工具、路由、Skill 与生命周期注册 | 有 |
-| `client.js` | DSH Web Slot、工作台、泡泡和提示词入口 | 有 |
-
-0.1.3 不声称已有完整独立 Core 或 Local Host Adapter。完整 Command Service、Host Port 接口和非 DSH 运行入口属于后续版本；本版先保证任务语义与离线 Doctor 不依赖 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 内部契约、有限调用预算与取消；真实消费者尚未接入 | 无 |
+| `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-task-runner.js` | 写前 Attempt、submit/poll/cancel/download 与 Profile 化交付 | 无 |
+| `core-doctor.js` / `core-lease-recovery.js` | 只读完整性诊断与需显式确认的陈旧租约恢复 | 无 |
+| `provider-catalog.js` | 显式 Provider 配置、能力候选和原 Task Adapter 恢复 | 无 |
+| `dsh-core-adapter.js` | DSH 数据根、后台观察与 Core 到 Host 的投影 | 有；DSH 专属边界 |
+| `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 兼容承诺。
 
 ## Task、Attempt 与 Artifact
 
-- 一个用户意图对应一个 Task；每个候选供应商调用对应一个稳定 Attempt。
-- Attempt 必须在可能发送计费请求前落盘。只有明确 `not_accepted` 才允许自动 failover。
-- 生成结果与本地交付是两类事实。生成成功后下载失败仍保持 `outcome=succeeded`。
-- 当前 Artifact 仍由任务中的文件、媒体令牌和附件记录表示；正式 Artifact Manifest、内容哈希和谱系属于 0.2.0。
-- 每次 v2 任务变更递增 Task `revision`；完整状态快照另带进程 `stateEpoch/stateRevision`，客户端拒绝同一 epoch 中迟到的旧快照。
+- 一个用户意图对应一个 Core Task；每次候选供应商调用对应一个稳定 Attempt。Attempt 必须在可能发送计费请求前落盘。
+- 只有明确 `not_accepted` 才允许自动切换候选；`accepted` 或 `unknown` 后禁止自动重提。重试会创建新 Task，并要求用户再次提供未持久化的输入和明确确认潜在费用。
+- 生成结果与本地交付是两类事实。远端成功后下载失败仍保持 `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 只报告，不自动修复。
 
-详细状态机见 [Task/Attempt v2 语义契约](TASK_SEMANTICS.md)，故障证据见 [故障注入矩阵](FAULT_INJECTION.md)。
+0.1.4 的 `tasks.json`、`artifacts.json`、`outputs/` 与上传目录继续作为 legacy 数据存在；Core 使用隔离的 `core-v0`。已迁移的新图片、视频、TTS 与转写任务不双写 legacy，回退到 0.1.4 时也不删除或改写 Core 数据。
 
 ## Provider 边界
 
-现有 DashScope 与 OpenAI Images 兼容分支仍位于 `adapters.js`，尚未宣称完整 Provider SDK。0.1.3 已冻结供应商提交所需的最小契约：复合模型身份、写前 Hook、四类提交结果、受理证据和安全错误。新增 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 漂移时恢复在联网前拒绝。
+
+每个操作必须明确声明 supported 或 unsupported。当前 DashScope 与 OpenAI Images 媒体协议没有经过验证的远端取消实现，因此取消请求如实返回 not-supported，而不是伪造 canceled。完整受理与错误规则见 [Provider 提交契约 v0](PROVIDER_SUBMISSION_CONTRACT.md)。
 
-完整接口与 conformance runner 延后到 0.1.4+，见 [Provider 提交契约 v0](PROVIDER_SUBMISSION_CONTRACT.md)。
+## Text/Vision 共享边界（M1 已实现）
 
-## Host Port 清单
+[Text/Vision Model Port v0](MODEL_PORT_CONTRACT.md) 的纯契约、调用控制与 test-only Fake Port 已实现，尚未接入真实消费者。它以 `describe()` 和单轮 `complete()` 统一文本/视觉输入、正常终态、预算、取消与安全错误；图片以字节和 MIME 进入共享层，模型选择、会话与附件桥接保留在入口/适配器。
 
-| 能力 | 当前来源 | 缺失时行为 |
+提示词优化与视觉理解不创建媒体生成 Task，不进入 Provider Task Runner。提示词优化的功能定位与输入隔离正在讨论，其接入待后续确定；look/relook、定位、OCR 与摘要仍按独立切片迁移。现有 Host 方法、配置与 CLI 均未因 M1 改变；自持文本目录和独立入口需要另行审查。
+
+## Host Port 与 Headless 边界
+
+| 能力 | DSH 来源 | 缺失或 Headless 时行为 |
 |---|---|---|
-| 工具注册与 Fiber 生命周期 | DSH `ctx.tools` / `ctx.effect` | 对应工具不注册；其余能力继续装载 |
-| Web 路由 | DSH `webServer` 或 `httpServer` | 工作台 API、媒体链接和 HTML 渲染不可用 |
-| UI Slot | DSH Web Client | 不影响 Host 侧任务与离线 Doctor |
-| Browser | DSH browser service | 仅 HTML 截图不可用 |
-| 会话附件与输入草稿 | DSH session/input ports | 退化为 Iris 自有产物或浏览器上传 |
-| Skills registry | DSH skills service | 随包 Skill 不自动注册；核心动作仍可用 |
+| 工具注册与 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 渲染不可用；本地媒体命令不受影响 |
+| 会话附件与输入草稿 | session/input ports | CLI 使用显式文件或 JSON 输入，不创建会话对象 |
+| Skills registry | DSH skills service | 随包 Skill 不自动注册；CLI/Core 仍可用 |
+
+Command、Core Store、Provider Runner 和 Headless CLI 不接收原始 `ctx`、会话对象或 Browser 对象。Host URL、attachment 与 UI 文案只在 DSH 投影层产生。
 
-这些依赖目前由 `index.js` 的可选注入和守卫集中处理。0.1.4 将把它们转成正式 Host Adapter 接口并增加 Local Host fixture。
+## 事件、UI 与媒体读取
 
-## 事件与 UI
+DSH 工作台把 Core 与 legacy Task 合并到一个用户任务区，把 Core 图片与旧 `outputs/` 合并到一个作品区。普通投影只有五类用户状态；原始 Attempt 事实留在高级诊断。刷新、展开、关闭、读取作品和查询状态都不得触发 submit、poll 或隐式修复。
 
-任务和配置写入会触发节流 SSE 快照。每份快照都有进程 epoch 与单调序号；慢消费者进入背压后只保留最新快照，重连仍通过持久化全量状态收敛。工作台只展示稳定人类状态，内部事实轴保留在 API 详情中供诊断和人工动作判断。
+Core 媒体路由按随机 Artifact ID 读取并逐次验证 SHA-256；它没有独立 token。浏览器请求还受可信 Host、`Origin`/`Sec-Fetch-Site` 和 `Referrer-Policy: no-referrer` 约束。Artifact ID 是持有者标识，不等于多租户认证；Iris 与 DSH 仍处于同一本机信任域。
 
-## 非目标
+## 非目标与发布边界
 
-- 不在 0.1.3 启动独立常驻服务或复制 DSH 聊天界面。
-- 不迁移到 SQLite/JSONL，不破坏旧任务读取。
-- 不新增 Gemini、Fal 或 Replicate 分支。
-- 不把离线 Doctor 的成功等同于 DSH Host、浏览器或真实供应商已可用。
+- `0.2.0` 不启动独立常驻服务，也不复制 DSH 聊天界面。
+- 不迁移到 SQLite/JSONL，不原地改写 0.1.4 数据，不自动接管不确定的写者租约。
+- 不在本候选新增 Gemini、Fal、Replicate 或本地模型协议；注册表只是后续接入点。
+- 不把离线测试、一次 canary 或 Headless 可运行等同于公开 Core API 已冻结。
+- rc.1 仍须通过最终包审计、仓库外安装、跨平台 CI、Android 目视、回退和机器可读验证摘要后才能发布。