@mokuyoaxis/dsh-iris 0.1.4 → 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.
+```