@mokuyoaxis/dsh-iris 0.1.1 → 0.1.3

package/lib/doctor.js

@@ -0,0 +1,243 @@
+'use strict';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { attentionDisposition, deriveUserState, semanticViolations } from './task-semantics.js';
+
+const PACKAGE_FILE = new URL('../package.json', import.meta.url);
+
+function readPackageVersion() {
+  try { return JSON.parse(fs.readFileSync(PACKAGE_FILE, 'utf8')).version || 'unknown'; } catch (_) { return 'unknown'; }
+}
+
+function result(id, status, summary, suggestion) {
+  return { id, status, summary, ...(suggestion ? { suggestion } : {}) };
+}
+
+function parseVersion(value) {
+  const match = String(value || '').match(/^(\d+)\.(\d+)\.(\d+)/);
+  return match ? match.slice(1).map(Number) : [0, 0, 0];
+}
+
+function atLeast(actual, required) {
+  for (let i = 0; i < 3; i++) {
+    if (actual[i] !== required[i]) return actual[i] > required[i];
+  }
+  return true;
+}
+
+function readJson(file) {
+  if (!fs.existsSync(file)) return { exists: false, value: null };
+  try { return { exists: true, value: JSON.parse(fs.readFileSync(file, 'utf8')) }; }
+  catch (_) { return { exists: true, value: null, error: 'JSON 无法解析' }; }
+}
+
+function plain(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isGroupOrWorldAccessible(target) {
+  if (process.platform === 'win32' || !fs.existsSync(target)) return false;
+  try { return (fs.lstatSync(target).mode & 0o077) !== 0; } catch (_) { return false; }
+}
+
+function privateFileModeProblems(dataDir) {
+  if (process.platform === 'win32') return [];
+  return ['providers.json', 'tasks.json', 'prompt-optimizer.json']
+    .filter((name) => isGroupOrWorldAccessible(path.join(dataDir, name)));
+}
+
+function commandAvailable(command, runner) {
+  try {
+    const run = runner(command, ['-version']);
+    return Boolean(run && run.status === 0 && !run.error);
+  } catch (_) { return false; }
+}
+
+function nearestExisting(target) {
+  let current = target;
+  for (;;) {
+    if (fs.existsSync(current)) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function writableProbe(dataDir) {
+  const base = fs.existsSync(dataDir) ? dataDir : nearestExisting(path.dirname(dataDir));
+  if (!base) return false;
+  const probe = path.join(base, `.iris-doctor-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  try {
+    fs.writeFileSync(probe, 'probe', { flag: 'wx', mode: 0o600 });
+    fs.rmSync(probe);
+    return true;
+  } catch (_) {
+    try { fs.rmSync(probe, { force: true }); } catch (_) {}
+    return false;
+  }
+}
+
+function inspectConfig(dataDir, checks) {
+  const config = readJson(path.join(dataDir, 'providers.json'));
+  if (!config.exists) {
+    checks.push(result('config', 'warn', '尚未创建供应商配置', '启动 Iris 后在工作台添加供应商，或准备好 DSH_HOME 后再运行 doctor。'));
+    return { providers: [], assignments: {} };
+  }
+  if (config.error || !plain(config.value) || !Array.isArray(config.value.providers)
+      || !plain(config.value.assignments || {})) {
+    checks.push(result('config', 'error', 'providers.json 结构无效或无法解析', '先备份该文件，再从 Iris 工作台重新配置；不要把密钥粘贴到诊断输出。'));
+    return { providers: [], assignments: {} };
+  }
+  const providers = config.value.providers;
+  let incomplete = 0;
+  let enabled = 0;
+  let models = 0;
+  for (const provider of providers) {
+    if (!plain(provider)) { incomplete++; continue; }
+    if (provider.enabled !== false) enabled++;
+    if (provider.enabled !== false && (!String(provider.baseUrl || '').trim() || !String(provider.apiKey || '').trim())) incomplete++;
+    models += Array.isArray(provider.models) ? provider.models.length : 0;
+  }
+  if (incomplete) checks.push(result('providers', 'warn', `${incomplete} 个启用供应商缺少 Base URL、API Key 或结构无效`, '在 Iris 工作台补全或停用对应供应商。'));
+  else if (!enabled) checks.push(result('providers', 'warn', '没有启用的供应商', '在 Iris 工作台启用至少一个供应商。'));
+  else checks.push(result('providers', 'ok', `${enabled} 个供应商已启用；凭据未输出`));
+  const assignments = config.value.assignments || {};
+  const assignmentCount = Object.keys(assignments).length;
+  if (!models) checks.push(result('models', 'warn', '模型池为空或尚未发现模型', '在工作台对供应商执行“发现模型”，再核对能力标签。'));
+  else checks.push(result('models', 'ok', `模型池记录 ${models} 个模型，能力分配 ${assignmentCount} 项`));
+  return { providers, assignments };
+}
+
+function inspectTasks(dataDir, checks) {
+  const stored = readJson(path.join(dataDir, 'tasks.json'));
+  if (!stored.exists) {
+    checks.push(result('tasks', 'ok', '尚无任务记录'));
+    return [];
+  }
+  if (stored.error || !plain(stored.value) || !Array.isArray(stored.value.tasks)) {
+    checks.push(result('tasks', 'error', 'tasks.json 结构无效或无法解析', '保留损坏文件作为证据；重新启动 Iris 会尝试隔离并建立新任务表。'));
+    return [];
+  }
+  let invalid = 0;
+  let attention = 0;
+  for (const task of stored.value.tasks) {
+    if (!plain(task) || !String(task.id || '').trim()) { invalid++; continue; }
+    if (task.schemaVersion === 2) {
+      if (semanticViolations(task).length) invalid++;
+      const userState = deriveUserState(task);
+      if (['watching_paused', 'needs_attention', 'artifact_unavailable'].includes(userState)
+          && attentionDisposition(task).status !== 'acknowledged') attention++;
+    } else if (task.status === 'running' && !task.remoteTaskId) attention++;
+  }
+  if (invalid) checks.push(result('tasks', 'error', `${invalid} 条任务记录语义或结构无效`, '不要手工改写任务事实；先备份 tasks.json 并保留损坏证据。'));
+  else if (attention) checks.push(result('tasks', 'warn', `${stored.value.tasks.length} 条任务中有 ${attention} 条需要人工确认`, '在 Iris 工作台的“需要处理”分区查看，并选择重新观察、重新交付、标为已读或知情重试。'));
+  else checks.push(result('tasks', 'ok', `${stored.value.tasks.length} 条任务记录结构有效`));
+  return stored.value.tasks.filter(plain);
+}
+
+function inspectArtifacts(dataDir, tasks, checks) {
+  const outputs = path.join(dataDir, 'outputs');
+  const referenced = new Set();
+  let missing = 0;
+  for (const task of tasks) {
+    for (const name of task.files || []) {
+      const safe = path.basename(String(name));
+      referenced.add(safe);
+      try { if (!fs.statSync(path.join(outputs, safe)).isFile()) missing++; } catch (_) { missing++; }
+    }
+    for (const item of task.media || []) if (item && item.file) referenced.add(path.basename(String(item.file)));
+    for (const item of task.attachments || []) if (item && item.file) referenced.add(path.basename(String(item.file)));
+  }
+  let orphan = 0;
+  if (fs.existsSync(outputs)) {
+    for (const name of fs.readdirSync(outputs)) {
+      const target = path.join(outputs, name);
+      try { if (fs.lstatSync(target).isFile() && !referenced.has(name)) orphan++; } catch (_) {}
+    }
+  }
+  if (missing) checks.push(result('artifacts', 'warn', `${missing} 个任务产物不可访问；另有 ${orphan} 个孤儿文件`, '在工作台检查任务详情并运行孤儿产物扫描。'));
+  else if (orphan) checks.push(result('artifacts', 'warn', `${orphan} 个产物文件没有任务引用`, '先在工作台运行孤儿扫描，确认后再删除。'));
+  else checks.push(result('artifacts', 'ok', `${referenced.size} 个已引用产物可核对，未发现孤儿文件`));
+
+  const uploads = path.join(dataDir, 'uploads');
+  let temporary = 0;
+  if (fs.existsSync(uploads)) {
+    for (const name of fs.readdirSync(uploads)) if (name.endsWith('.part')) temporary++;
+  }
+  checks.push(temporary
+    ? result('temporary-files', 'warn', `${temporary} 个上传临时 .part 文件残留`, '确认没有上传进行中后重启 Iris，由启动清理逻辑处理。')
+    : result('temporary-files', 'ok', '未发现上传临时文件残留'));
+}
+
+/**
+ * 零网络离线诊断。仅创建并立即删除一个写入探针；不启动 DSH、不读取或输出 API Key。
+ */
+export async function doctor(options = {}) {
+  const dshHome = path.resolve(options.dshHome || process.env.DSH_HOME || path.join(os.homedir(), '.dsh'));
+  const dataDir = path.join(dshHome, 'iris', 'v1');
+  const runner = options.commandRunner || ((command, args) => spawnSync(command, args, { stdio: 'ignore', shell: false }));
+  const sharpLoader = options.sharpLoader || (() => import('sharp'));
+  const nodeVersion = options.nodeVersion || process.versions.node;
+  const checks = [];
+
+  checks.push(atLeast(parseVersion(nodeVersion), [20, 10, 0])
+    ? result('node', 'ok', `Node.js ${nodeVersion}`)
+    : result('node', 'error', `Node.js ${nodeVersion} 低于最低要求 20.10.0`, '升级 Node.js 后再运行 Iris。'));
+  try { await sharpLoader(); checks.push(result('sharp', 'ok', 'sharp 可加载')); }
+  catch (_) { checks.push(result('sharp', 'error', 'sharp 无法加载', '在当前平台重新安装 @mokuyoaxis/dsh-iris，确认 sharp 有可用的 ARM64/系统构建。')); }
+  for (const command of ['ffmpeg', 'ffprobe']) {
+    checks.push(commandAvailable(command, runner)
+      ? result(command, 'ok', `${command} 可用`)
+      : result(command, 'warn', `${command} 不可用`, '视频抽帧与摘要需要 ffmpeg/ffprobe；其他 Iris 能力不受影响。'));
+  }
+
+  const dataExists = fs.existsSync(dataDir);
+  if (dataExists) {
+    let symlink = false;
+    try { symlink = fs.lstatSync(dataDir).isSymbolicLink(); } catch (_) {}
+    if (symlink) checks.push(result('storage', 'error', 'Iris 数据目录是符号链接，私有边界无法保证', '改用真实的私有目录并人工迁移数据。'));
+    else if (!writableProbe(dataDir)) checks.push(result('storage', 'error', 'Iris 数据目录不可写', '修复当前用户对 $DSH_HOME/iris/v1 的写权限。'));
+    else if (isGroupOrWorldAccessible(dataDir)) checks.push(result('storage', 'warn', 'Iris 数据目录允许组或其他用户访问', '在 POSIX 上将目录权限收紧为 0700、文件收紧为 0600。'));
+    else {
+      const exposedFiles = privateFileModeProblems(dataDir);
+      checks.push(exposedFiles.length
+        ? result('storage', 'warn', `${exposedFiles.length} 个私有数据文件允许组或其他用户访问`, '在 POSIX 上将 providers.json、tasks.json 与提示词配置权限收紧为 0600。')
+        : result('storage', 'ok', 'Iris 数据目录可写、私有文件权限合格，临时探针已清理'));
+    }
+  } else {
+    checks.push(writableProbe(dataDir)
+      ? result('storage', 'ok', 'Iris 数据目录尚未创建；父目录可写，临时探针已清理')
+      : result('storage', 'error', 'Iris 数据目录不存在且父目录不可写', '设置一个当前用户可写的 DSH_HOME。'));
+  }
+
+  inspectConfig(dataDir, checks);
+  const taskRecords = inspectTasks(dataDir, checks);
+  inspectArtifacts(dataDir, taskRecords, checks);
+  checks.push(result('scope', 'ok', '离线模式未启动 DSH、未检查浏览器/工具注册，也未发送供应商请求'));
+
+  const errors = checks.filter((item) => item.status === 'error').length;
+  const warnings = checks.filter((item) => item.status === 'warn').length;
+  return {
+    schemaVersion: 1,
+    package: { name: '@mokuyoaxis/dsh-iris', version: options.packageVersion || readPackageVersion() },
+    mode: 'offline',
+    environment: { node: nodeVersion, platform: process.platform, arch: process.arch },
+    checks,
+    summary: { ok: checks.length - errors - warnings, warnings, errors },
+    exitCode: errors ? 2 : (warnings ? 1 : 0)
+  };
+}
+
+export function formatDoctorReport(report) {
+  const mark = { ok: '✓', warn: '!', error: '✗' };
+  const lines = [`Iris Doctor ${report.package.version} · ${report.mode}`];
+  for (const check of report.checks) {
+    lines.push(`${mark[check.status] || '-'} ${check.id}: ${check.summary}`);
+    if (check.suggestion) lines.push(`  建议：${check.suggestion}`);
+  }
+  lines.push(`结果：${report.summary.errors} 错误，${report.summary.warnings} 警告`);
+  return lines.join('\n');
+}

package/lib/index.js

@@ -21,9 +21,11 @@ import { serveRender, BrowserHtmlRenderer } from './render.js';
 import { ensurePrivateDir, hardenPrivateTree } from './private-storage.js';
 import { guarded } from './guard.js';
 import { longOcr } from './ocr.js';
-import { runAction, listActions } from './actions.js';
+import { runAction, listActions, taskPollDeps } from './actions.js';
 import { ffmpegAvailable, extractFrames, probeVideo, extractAudioTrack } from './media-probe.js';
 import { buildContactSheet, summarizeMedia } from './summarize.js';
+import { registerBundledSkills } from './bundled-skills.js';
+export { doctor, formatDoctorReport } from './doctor.js';
 
 const MEDIA_TYPES = {
   '.png': 'image/png',
@@ -80,48 +82,47 @@ function mountIrisRoutes(routeCtx) {
   }
 }
 
-/** 盯守依赖：按能力给轮询间隔与结果转存扩展名 */
+/** 向后兼容导出；真实实现与人工接管共用 actions.taskPollDeps。 */
 export function pollDeps(provider, cap) {
-  if (cap === 'transcribe') {
-    // 转写任务的结果在 transcription_text 而非 urls——重启接管必须走专用轮询器，
-    // 否则 pollTask 拿到空 urls，盯守会「成功」但转写文本静默丢失。
-    // （与 iris_transcribe_audio 工具内的盯守依赖保持同构。）
-    return {
-      key: () => provider.apiKey,
-      poll: async ({ key, remoteTaskId }) => {
-        const r = await adapters.pollTranscriptionTask({ key, baseUrl: provider.baseUrl, remoteTaskId });
-        return { done: r.done, ok: r.ok, urls: r.text ? [r.text] : [], message: r.message };
-      },
-      intervalMs: 2500,
-      onSuccess: async (t, r) => {
-        tasks.update(t.id, { transcribeText: (r.urls && r.urls.join('')) || '' });
-        return [];
-      }
-    };
+  return taskPollDeps(provider, { cap });
+}
+
+/** 旧 status 与 Task v2 事实轴共同决定工具是否应停止等待。 */
+export function taskWaitFinished(task) {
+  if (!task) return false;
+  if (task.status !== 'running') return true;
+  return tasks.isV2Task(task) && task.phase === 'terminal';
+}
+
+/** 把 v2 正交事实转换成不会误导用户的工具错误；空串表示已成功可交付。 */
+export function taskTerminalProblem(task, label = '任务') {
+  if (!task) return label + '记录不存在';
+  if (!tasks.isV2Task(task)) {
+    if (task.status === 'canceled') return '已取消';
+    if (task.status !== 'succeeded') return label + '失败：' + (task.error || '未知原因');
+    return '';
   }
-  return {
-    key: () => provider.apiKey,
-    poll: ({ key, remoteTaskId }) => adapters.pollTask({ key, baseUrl: provider.baseUrl, remoteTaskId }),
-    intervalMs: cap === 'video' ? 6000 : 2500,
-    onSuccess: async (t, r) => {
-      fs.mkdirSync(outputDir(), { recursive: true });
-      const names = [];
-      for (const url of r.urls || []) {
-        const name = `${t.id}-${names.length}.${adapters.extFromUrl(url, cap === 'video' ? 'mp4' : 'png')}`;
-        await adapters.downloadTo(url, path.join(outputDir(), name));
-        names.push(name);
-      }
-      // 登记媒体链接（token 授权），对话流里可点播
-      for (const n of names) registerMedia(t.id, path.join(outputDir(), n));
-      return names;
-    }
-  };
+  if (task.outcome === 'succeeded' && task.deliveryState === 'ready') return '';
+  if (task.outcome === 'succeeded' && task.deliveryState === 'failed') {
+    return label + '已成功，但产物交付失败：' + (task.error || '可稍后重新交付；禁止重新生成');
+  }
+  if (task.acceptance === 'unknown' || task.outcome === 'unknown') {
+    return label + '的远端受理或结果状态未知：' + (task.error || '禁止自动重提，请先人工确认');
+  }
+  if (task.cancelState === 'unknown') {
+    return label + '的远端取消状态未知：' + (task.error || '请先人工确认');
+  }
+  if (task.outcome === 'canceled') return '已取消';
+  if (task.outcome === 'failed') return label + '失败：' + (task.error || '供应商明确返回失败');
+  return task.phase === 'terminal'
+    ? label + '需要人工处理：' + (task.error || '状态未能自动收口')
+    : '';
 }
 
 /**
  * 在工具调用内同步等待任务到终态。
  * @returns 终态任务记录；null = 等待超时（任务已转后台继续盯守）
- * @throws 取消时抛错并标记 canceled
+ * @throws 取消时抛错并记录保守取消事实
  */
 async function awaitTerminal(taskId, { timeoutMs, signal }) {
   const deadline = Date.now() + timeoutMs;
@@ -131,7 +132,7 @@ async function awaitTerminal(taskId, { timeoutMs, signal }) {
       throw new Error('已取消');
     }
     const t = tasks.get(taskId);
-    if (t && t.status !== 'running') return t;
+    if (taskWaitFinished(t)) return t;
     if (Date.now() > deadline) return null;
     await new Promise((r) => setTimeout(r, 1000));
   }
@@ -155,7 +156,7 @@ function fmtTask(t) {
   return lines.join('\n');
 }
 
-export const name = 'dsh-iris';
+export const name = 'mokuyoaxis-dsh-iris';
 export const inject = ['tools'];
 
 /**
@@ -214,6 +215,15 @@ export async function apply(ctx) {
   // 若 webServer 已在运行，inject 回调也会触发；这里兜底立即挂载一次
   guard('媒体路由兜底挂载', () => mountIrisRoutes(ctx));
 
+  // DSH 的 Skill registry 是可选宿主能力。存在时把 npm 包内两项 Skill 注册到
+  // 全局层；项目目录中的同名 Skill 仍由 DSH 原生优先级覆盖。
+  ctx.inject(['skills'], (skillCtx) => {
+    guard('随包 Skill 注册', () => {
+      const names = registerBundledSkills(skillCtx);
+      console.log('[iris] 随包 Skill 已注册：' + names.join(' · '));
+    });
+  });
+
   const tools = ctx.tools;
   if (!tools || typeof tools.register !== 'function') {
     console.error('[iris] tools 服务不可用，跳过全部工具注册（宿主不受影响）');
@@ -246,14 +256,14 @@ export async function apply(ctx) {
       if (!prompt) throw new Error('iris: prompt 不能为空');
       const submitted = await runAction(ctx, 'image', args, { signal: exec.signal });
       let final = tasks.get(submitted.taskId);
-      if (final && final.status === 'running') {
+      if (final && !taskWaitFinished(final)) {
         final = await awaitTerminal(submitted.taskId, { timeoutMs: AWAIT_MS.image, signal: exec.signal });
       }
       if (!final) {
         return { blocks: [{ type: 'text', text: `[iris] 图像任务仍在后台盯守（task: ${submitted.taskId}）。稍后可用 iris_task_status 查询进度与文件路径。` }] };
       }
-      if (final.status === 'canceled') throw new Error('已取消');
-      if (final.status !== 'succeeded') throw new Error('生成失败：' + (final.error || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '图像生成');
+      if (terminalProblem) throw new Error(terminalProblem);
 
       const files = (final.files || []).map((f) => path.join(outputDir(), f));
       const blocks = [];
@@ -319,8 +329,8 @@ export async function apply(ctx) {
         return `[iris] 视频任务已提交并转入后台盯守（task: ${submitted.taskId}，remoteTask: ${submitted.remoteTaskId}）。\n` +
           '渲染通常需要数分钟；完成后用 iris_task_status 查询产物路径。';
       }
-      if (final.status === 'canceled') throw new Error('已取消');
-      if (final.status !== 'succeeded') throw new Error('视频生成失败：' + (final.error || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '视频生成');
+      if (terminalProblem) throw new Error(terminalProblem);
       const paths = (final.files || []).map((f) => path.join(outputDir(), f));
       const links = mediaLinksOf(final);
       const secs = Math.round((Date.now() - new Date(final.createdAt).getTime()) / 1000);
@@ -349,7 +359,8 @@ export async function apply(ctx) {
     async execute(args, exec) {
       const submitted = await runAction(ctx, 'tts', args, { signal: exec.signal });
       const final = tasks.get(submitted.taskId);
-      if (!final || final.status !== 'succeeded') throw new Error('语音合成失败：' + ((final && final.error) || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '语音合成');
+      if (terminalProblem) throw new Error(terminalProblem);
       const fileName = (final.files || [])[0];
       const p = path.join(outputDir(), fileName);
       const media = (final.media || [])[0];
@@ -376,8 +387,8 @@ export async function apply(ctx) {
       const submitted = await runAction(ctx, 'transcribe', args, { signal: exec.signal });
       const final = await awaitTerminal(submitted.taskId, { timeoutMs: 120000, signal: exec.signal });
       if (!final) return `[iris] 音频转写任务已提交并转入后台（task: ${submitted.taskId}）。完成后用 iris_task_status 查询。`;
-      if (final.status === 'canceled') throw new Error('已取消');
-      if (final.status !== 'succeeded') throw new Error('转写失败：' + (final.error || '未知原因'));
+      const terminalProblem = taskTerminalProblem(final, '音频转写');
+      if (terminalProblem) throw new Error(terminalProblem);
       return `[iris] 音频转写完成（${submitted.model || final.model}）：\n${final.transcribeText || ''}`;
     }
   });

package/lib/prompt-optimizer-config.js

@@ -0,0 +1,170 @@
+'use strict';
+/**
+ * Iris 提示词优化器配置。
+ *
+ * 与 providers.json 分离保存：这里不含凭据，只记录用户可导入/导出的 Prompt、
+ * 目标媒介要求与模型路由偏好。损坏配置会被隔离，运行时回退到内置默认值。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { irisHome } from './config.js';
+import { atomicWritePrivate, chmodPrivateFile, privateSibling } from './private-storage.js';
+
+export const PROMPT_TARGETS = ['general', 'image', 'video', 's2v'];
+
+const DEFAULT_VALUE = {
+  version: 1,
+  enabled: true,
+  systemPrompt: [
+    '你是 Iris 提示词编辑器。把用户草稿改写成一段可直接交给目标 AI 的高质量提示词。',
+    '必须保留原始意图、事实、专有名词、引号内原文、硬性约束和否定条件；不得臆造用户没有提供的事实。',
+    '只补充能提高可执行性、结构清晰度、风格一致性和验收明确度的具体信息。信息不足时保持克制，不替用户作关键决定。',
+    '默认沿用草稿的语言。只输出优化后的提示词正文，不解释、不加标题、不使用 Markdown 代码块。'
+  ].join('\n'),
+  targets: {
+    general: '适用于一般对话任务：明确目标、必要背景、约束、期望输出和验收标准；避免无意义地拉长文本。',
+    image: '适用于图像生成：在原意允许的范围内明确主体、环境、构图、视角、光线、色彩、材质、风格和负面约束。',
+    video: '适用于视频生成：在原意允许的范围内明确主体动作、场景变化、镜头运动、景别、节奏、时长感、连续性和负面约束。',
+    s2v: '适用于首尾帧视频：明确首帧到尾帧之间的动作、镜头、空间关系和连续性，避免引入与两端画面冲突的新主体。'
+  },
+  route: {
+    mode: 'session'
+  },
+  generation: {
+    temperature: 0.3,
+    reasoningEffort: 'off-if-supported',
+    maxOutputTokens: 1200,
+    timeoutMs: 45000
+  }
+};
+
+export const DEFAULT_PROMPT_OPTIMIZER_CONFIG = Object.freeze(structuredClone(DEFAULT_VALUE));
+
+function configFile() {
+  return path.join(irisHome(), 'prompt-optimizer.json');
+}
+
+function plain(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function text(value, fallback, field, maxLength) {
+  if (value === undefined) return fallback;
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${field} 必须是非空字符串`);
+  if (value.length > maxLength) throw new Error(`${field} 不能超过 ${maxLength} 个字符`);
+  return value.trim();
+}
+
+function boundedNumber(value, fallback, field, min, max) {
+  if (value === undefined) return fallback;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+    throw new Error(`${field} 必须是 ${min}–${max} 之间的数字`);
+  }
+  return value;
+}
+
+/** 规范化用户导入的完整或局部 JSON，不保留未知字段。 */
+export function normalizePromptOptimizerConfig(input) {
+  if (!plain(input)) throw new Error('提示词优化器配置根节点必须是对象');
+  if (input.version !== undefined && input.version !== 1) throw new Error('仅支持 version: 1');
+
+  const targetInput = input.targets === undefined ? {} : input.targets;
+  if (!plain(targetInput)) throw new Error('targets 必须是对象');
+  const targets = {};
+  for (const target of PROMPT_TARGETS) {
+    targets[target] = text(targetInput[target], DEFAULT_VALUE.targets[target], `targets.${target}`, 8000);
+  }
+
+  const routeInput = input.route === undefined ? {} : input.route;
+  if (!plain(routeInput)) throw new Error('route 必须是对象');
+  const mode = routeInput.mode === undefined ? DEFAULT_VALUE.route.mode : routeInput.mode;
+  if (mode !== 'session' && mode !== 'fixed') throw new Error('route.mode 只能是 session 或 fixed');
+  const route = { mode };
+  if (mode === 'fixed') {
+    route.provider = text(routeInput.provider, undefined, 'route.provider', 256);
+    route.model = text(routeInput.model, undefined, 'route.model', 256);
+    if (!route.provider || !route.model) throw new Error('fixed 路由必须同时提供 route.provider 与 route.model');
+  }
+
+  const generationInput = input.generation === undefined ? {} : input.generation;
+  if (!plain(generationInput)) throw new Error('generation 必须是对象');
+  const generation = {
+    temperature: boundedNumber(generationInput.temperature, DEFAULT_VALUE.generation.temperature, 'generation.temperature', 0, 2),
+    reasoningEffort: text(generationInput.reasoningEffort, DEFAULT_VALUE.generation.reasoningEffort, 'generation.reasoningEffort', 128),
+    maxOutputTokens: Math.round(boundedNumber(generationInput.maxOutputTokens, DEFAULT_VALUE.generation.maxOutputTokens, 'generation.maxOutputTokens', 64, 4096)),
+    timeoutMs: Math.round(boundedNumber(generationInput.timeoutMs, DEFAULT_VALUE.generation.timeoutMs, 'generation.timeoutMs', 1000, 120000))
+  };
+
+  if (input.enabled !== undefined && typeof input.enabled !== 'boolean') throw new Error('enabled 必须是布尔值');
+
+  return {
+    version: 1,
+    enabled: input.enabled === undefined ? DEFAULT_VALUE.enabled : input.enabled,
+    systemPrompt: text(input.systemPrompt, DEFAULT_VALUE.systemPrompt, 'systemPrompt', 16000),
+    targets,
+    route,
+    generation
+  };
+}
+
+let cache = null;
+let cacheSource = 'default';
+
+export function loadPromptOptimizerConfig() {
+  if (cache) return { source: cacheSource, config: structuredClone(cache) };
+  const file = configFile();
+  if (!fs.existsSync(file)) {
+    cache = structuredClone(DEFAULT_VALUE);
+    cacheSource = 'default';
+    return { source: cacheSource, config: structuredClone(cache) };
+  }
+  try {
+    cache = normalizePromptOptimizerConfig(JSON.parse(fs.readFileSync(file, 'utf8')));
+    cacheSource = JSON.stringify(cache) === JSON.stringify(DEFAULT_VALUE) ? 'default' : 'custom';
+  } catch (err) {
+    const backup = privateSibling(file, 'corrupted');
+    try {
+      fs.renameSync(file, backup);
+      chmodPrivateFile(backup);
+    } catch (_) { /* 隔离失败也必须能使用内置默认值 */ }
+    console.error('[iris] prompt-optimizer.json 已损坏，已回退内置默认值：', err && err.message);
+    cache = structuredClone(DEFAULT_VALUE);
+    cacheSource = 'default';
+  }
+  return { source: cacheSource, config: structuredClone(cache) };
+}
+
+export function importPromptOptimizerConfig(input) {
+  const next = normalizePromptOptimizerConfig(input);
+  atomicWritePrivate(configFile(), JSON.stringify(next, null, 2));
+  cache = next;
+  cacheSource = 'custom';
+  return { source: cacheSource, config: structuredClone(cache) };
+}
+
+export function setPromptOptimizerEnabled(enabled) {
+  if (typeof enabled !== 'boolean') throw new Error('enabled 必须是布尔值');
+  const next = normalizePromptOptimizerConfig({ ...loadPromptOptimizerConfig().config, enabled });
+  atomicWritePrivate(configFile(), JSON.stringify(next, null, 2));
+  cache = next;
+  cacheSource = JSON.stringify(cache) === JSON.stringify(DEFAULT_VALUE) ? 'default' : 'custom';
+  return { source: cacheSource, config: structuredClone(cache) };
+}
+
+export function resetPromptOptimizerConfig() {
+  const next = structuredClone(DEFAULT_VALUE);
+  atomicWritePrivate(configFile(), JSON.stringify(next, null, 2));
+  cache = next;
+  cacheSource = 'default';
+  return { source: cacheSource, config: structuredClone(cache) };
+}
+
+/** 仅供测试/热重载丢弃进程内缓存。 */
+export function resetPromptOptimizerConfigCache() {
+  cache = null;
+  cacheSource = 'default';
+}
+
+export function promptOptimizerConfigFile() {
+  return configFile();
+}