@mokuyoaxis/dsh-iris 0.1.0 → 0.1.2

package/lib/config.js

@@ -1,7 +1,7 @@
 'use strict';
 /**
  * Iris 配置存储：$DSH_HOME/iris/v1/providers.json
- * 结构与 ai-paint 工作台兼容（providers 数组同形），支持一键导入。
+ * Iris 独立持有配置；旧工作台仅作为用户显式指定的一次性导入来源。
  * Key 明文落盘（0600）；接口层永远不回明文。
  */
 import fs from 'node:fs';
@@ -9,6 +9,37 @@ import path from 'node:path';
 import os from 'node:os';
 import * as cap from './capability.js';
 import * as models from './models.js';
+import { atomicWritePrivate, chmodPrivateFile, privateSibling } from './private-storage.js';
+import { inferMediaProtocol } from './provider-protocol.js';
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateStoredConfig(value) {
+  if (!isPlainObject(value)) throw new Error('配置根节点必须是对象');
+  if (!Array.isArray(value.providers)) throw new Error('providers 必须是数组');
+  if (!isPlainObject(value.assignments)) throw new Error('assignments 必须是对象');
+  for (const provider of value.providers) {
+    if (!isPlainObject(provider)) throw new Error('provider 条目必须是对象');
+    if (provider.id !== undefined && typeof provider.id !== 'string') throw new Error('provider.id 必须是字符串');
+    if (provider.baseUrl !== undefined && typeof provider.baseUrl !== 'string') throw new Error('provider.baseUrl 必须是字符串');
+    if (provider.apiKey !== undefined && typeof provider.apiKey !== 'string') throw new Error('provider.apiKey 必须是字符串');
+    if (provider.models !== undefined && !Array.isArray(provider.models)) throw new Error('provider.models 必须是数组');
+    for (const model of provider.models || []) {
+      if (typeof model === 'string') continue;
+      if (!isPlainObject(model) || typeof model.id !== 'string' || !model.id.trim()) {
+        throw new Error('provider.models 条目必须是模型名或带 id 的对象');
+      }
+    }
+  }
+}
+
+function normalizeStoredProvider(provider) {
+  if (provider.mediaProtocol === 'dashscope' || provider.mediaProtocol === 'openai-images') return false;
+  provider.mediaProtocol = inferMediaProtocol(provider.baseUrl);
+  return true;
+}
 
 export function irisHome() {
   const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
@@ -35,16 +66,7 @@ function emitChange() {
 }
 
 function persist() {
-  fs.mkdirSync(path.dirname(storeFile()), { recursive: true });
-  const tmp = storeFile() + '.tmp';
-  // 0600 从创建时生效（含临时文件）；rename 保留 mode，chmod 兜底不依赖 umask
-  fs.writeFileSync(tmp, JSON.stringify(cache, null, 2), { mode: 0o600 });
-  fs.renameSync(tmp, storeFile());
-  try {
-    fs.chmodSync(storeFile(), 0o600);
-  } catch (_) {
-    /* ignore */
-  }
+  atomicWritePrivate(storeFile(), JSON.stringify(cache, null, 2));
   emitChange(); // 任何配置落盘 = 状态变了 → SSE 推送
 }
 
@@ -58,14 +80,22 @@ export function load() {
     return cache;
   }
   try {
-    cache = JSON.parse(fs.readFileSync(file, 'utf8'));
-    if (!Array.isArray(cache.providers)) cache.providers = [];
-    if (!cache.assignments || typeof cache.assignments !== 'object') cache.assignments = {};
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    let normalized = false;
+    if (isPlainObject(parsed) && parsed.assignments === undefined) {
+      parsed.assignments = {};
+      normalized = true;
+    }
+    validateStoredConfig(parsed);
+    cache = parsed;
+    for (const provider of cache.providers) normalized = normalizeStoredProvider(provider) || normalized;
+    if (normalized) persist();
   } catch (err) {
     // 文件存在但损坏：隔离，绝不静默覆盖证据
-    const backup = file + '.corrupted-' + Date.now();
+    const backup = privateSibling(file, 'corrupted');
     try {
       fs.renameSync(file, backup);
+      chmodPrivateFile(backup);
     } catch (_) {
       /* 隔离失败也继续 */
     }
@@ -81,7 +111,7 @@ export function resetCache() {
   cache = null;
 }
 
-/** 首次运行且 Iris 为空时，从工作台配置导入（迁移动作，非耦合） */
+/** 用户显式指定来源且 Iris 为空时，从工作台配置导入。 */
 export function importFromWorkbench(workbenchConfigPath) {
   const c = load();
   if (c.providers.length) return { imported: 0, reason: '已有配置，跳过导入' };
@@ -89,12 +119,13 @@ export function importFromWorkbench(workbenchConfigPath) {
   try {
     raw = JSON.parse(fs.readFileSync(workbenchConfigPath, 'utf8'));
   } catch (_) {
-    return { imported: 0, reason: '未找到工作台配置' };
+    return { imported: 0, reason: '来源文件不可读或 JSON 无效' };
   }
-  const list = Array.isArray(raw.providers) ? raw.providers : [];
+  const list = Array.isArray(raw?.providers) ? raw.providers : [];
   let n = 0;
   for (const p of list) {
-    if (!p || !p.apiKey || !p.baseUrl) continue;
+    if (!p || typeof p.apiKey !== 'string' || !p.apiKey.trim() ||
+        typeof p.baseUrl !== 'string' || !p.baseUrl.trim()) continue;
     c.providers.push({
       id: 'iris_' + Math.random().toString(36).slice(2, 8),
       name: p.name || p.id,
@@ -102,13 +133,12 @@ export function importFromWorkbench(workbenchConfigPath) {
       baseUrl: p.baseUrl,
       apiKey: p.apiKey,
       enabled: p.enabled !== false,
-      // 媒体生成默认走百炼协议；OpenAI Images 兼容后端由用户按需切换
-      mediaProtocol: /dashscope/i.test(p.baseUrl) ? 'dashscope' : 'openai-images'
+      mediaProtocol: inferMediaProtocol(p.baseUrl)
     });
     n++;
   }
   if (n) persist();
-  return { imported: n };
+  return n ? { imported: n } : { imported: 0, reason: '来源没有可导入的供应商' };
 }
 
 export function providers() {
@@ -271,12 +301,16 @@ export function upsert(provider) {
   if (id) {
     const i = c.providers.findIndex((p) => p.id === id);
     if (i >= 0) {
+      if (rest.mediaProtocol === 'auto') rest.mediaProtocol = inferMediaProtocol(rest.baseUrl ?? c.providers[i].baseUrl);
       c.providers[i] = { ...c.providers[i], ...rest };
+      normalizeStoredProvider(c.providers[i]);
       persist();
       return c.providers[i];
     }
   }
   const fresh = { id: 'iris_' + Math.random().toString(36).slice(2, 8), ...rest };
+  if (fresh.mediaProtocol === 'auto') delete fresh.mediaProtocol;
+  normalizeStoredProvider(fresh);
   c.providers.push(fresh);
   persist();
   return fresh;

package/lib/guard.js

@@ -1,41 +1,54 @@
 'use strict';
 /**
- * Iris 请求守卫（O2 授权边界，2026-09-03 修订为"发布安全优先"）。
+ * Iris 请求守卫。
  *
- * 调研宿主结论：DSH 在 `dsh-client-connection` 里有一套权威信任栅栏
- * `isTrustedApiRequest`（回环∪trustedHosts + Sec-Fetch-Site + Origin==Host），
- * 但它**只挂在 `/api` 前缀**。iris 注册的是 `/iris/*` 裸 prefix 路由，在栅栏之外，
- * 所以 iris 需自备一道——但必须**对齐宿主里"永不锁死合法用户"的那半，
- * 舍弃"会锁死 LAN/反代用户"的那半**。
- *
- * 威胁与处置（按发布安全排序）：
- * ① 驱动式 CSRF（真实、高价值）：恶意网页对 `/iris/api/actions/*` 发跨站 POST，
- *    触发付费生成/写盘。→ **挡**：POST 时 `Sec-Fetch-Site === cross-site` 拒绝；
- *    有 `Origin` 且 `Origin.host !== 请求 Host` 拒绝。合法同源用户（不管在回环/LAN/
- *    反代域名上访问，浏览器 Origin 总与 Host 同源）永不误伤；无 Origin 的 CLI/curl 放行。
- * ② DNS 重绑定读 state / 驱动 POST（低价值）：需要 Host 白名单才能挡，但白名单正是
- *    锁死 LAN/反代用户的元凶。用户裁定：iris 开源、反代场景无所谓 → **不挡**，
- *    读接口（GET/HEAD/SSE）完全放开（跨源读本就受 CORS 阻挡，媒体另有 token 能力凭证）。
- *
- * 净效果：**任何部署拓扑都不拦合法用户**，只挡跨站 CSRF 驱动付费动作。
+ * `/iris/*` 不经过 DSH 的 `/api` 信任栅栏，因此默认只接受回环 Host。
+ * LAN/反代场景需用 IRIS_TRUSTED_HOSTS 显式列出 host 或 host:port；这只是
+ * Host 边界，不是身份认证。POST 另外校验 Sec-Fetch-Site 与 Origin==Host。
  */
 
 /** 请求 Host 头 → host:port 规范化（小写，去 IPv6 方括号保留） */
 function authority(header) {
-  const h = String(header || '').trim().toLowerCase();
-  if (!h) return '';
-  return h;
+  return String(header || '').trim().toLowerCase();
+}
+
+function hostnameOf(value) {
+  try { return new URL('http://' + authority(value)).hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '').toLowerCase(); }
+  catch (_) { return ''; }
+}
+
+function isLoopbackHost(hostname) {
+  if (hostname === 'localhost' || hostname === '::1') return true;
+  const match = hostname.match(/^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  return !!match && match.slice(1).every((part) => Number(part) <= 255);
+}
+
+/** Host 是否属于默认回环或显式信任列表。列表格式：逗号分隔 host / host:port。 */
+export function isTrustedHost(hostHeader, configured = process.env.IRIS_TRUSTED_HOSTS || '') {
+  const host = authority(hostHeader);
+  const hostname = hostnameOf(host);
+  if (!host || !hostname) return false;
+  if (isLoopbackHost(hostname)) return true;
+  for (const raw of String(configured || '').split(',')) {
+    const entry = authority(raw);
+    if (!entry) continue;
+    if (entry === host) return true;
+    if (!entry.includes(':') && entry.replace(/\.$/, '') === hostname) return true;
+  }
+  return false;
 }
 
 /**
  * 纯函数裁决：{ok:true} 放行；否则 {ok:false, status, error}。
- * 非 POST 一律放行；POST 仅挡跨站/跨源（同源浏览器与无 Origin 的 CLI 放行）。
  * @param {{method?:string, headers?:object}} req node:http IncomingMessage 的最小面
  */
-export function checkRequest(req) {
+export function checkRequest(req, options = {}) {
   const headers = req.headers || {};
   const method = String(req.method || 'GET').toUpperCase();
-  if (method !== 'POST') return { ok: true }; // 读接口放开：跨源读受 CORS 挡，媒体有 token
+  if (!isTrustedHost(headers.host, options.trustedHosts)) {
+    return { ok: false, status: 403, error: 'untrusted host' };
+  }
+  if (method !== 'POST') return { ok: true };
 
   const sfs = String(headers['sec-fetch-site'] || '').toLowerCase();
   if (sfs === 'cross-site') return { ok: false, status: 403, error: 'cross-site request denied' };
@@ -50,7 +63,7 @@ export function checkRequest(req) {
     }
     if (oh !== authority(headers.host)) return { ok: false, status: 403, error: 'cross-origin request denied' };
   }
-  return { ok: true }; // 同源浏览器，或无 Origin 的本机 CLI/curl
+  return { ok: true };
 }
 
 /** 包裹路由 handler：未授权请求统一 403 人话 JSON，不进业务 handler */

package/lib/index.js

@@ -7,7 +7,6 @@
  * 架构纪律：无独立后台，与 DSH 俱荣俱损——定时器归 Fiber，产物落 $DSH_HOME。
  */
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import * as adapters from './adapters.js';
 import * as store from './config.js';
@@ -19,11 +18,13 @@ import { buildVisionBackends, askWithBackends } from './vision.js';
 import { cropImage, pixelDiff, imageDimensions } from './pixels.js';
 import { locateObject } from './locate.js';
 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 { ffmpegAvailable, extractFrames, probeVideo, extractAudioTrack } from './media-probe.js';
 import { buildContactSheet, summarizeMedia } from './summarize.js';
+import { registerBundledSkills } from './bundled-skills.js';
 
 const MEDIA_TYPES = {
   '.png': 'image/png',
@@ -38,8 +39,7 @@ const AWAIT_MS = { image: 180000, video: 480000 };
 
 function outputDir() {
   const dir = tasks.outputsDir();
-  fs.mkdirSync(dir, { recursive: true });
-  return dir;
+  return ensurePrivateDir(dir);
 }
 
 /* ---------------- 媒体路由：/iris/media/:taskId/:token/:name ---------------- */
@@ -90,7 +90,7 @@ export function pollDeps(provider, cap) {
     return {
       key: () => provider.apiKey,
       poll: async ({ key, remoteTaskId }) => {
-        const r = await adapters.pollTranscriptionTask({ 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,
@@ -102,7 +102,7 @@ export function pollDeps(provider, cap) {
   }
   return {
     key: () => provider.apiKey,
-    poll: ({ key, remoteTaskId }) => adapters.pollTask({ key, remoteTaskId }),
+    poll: ({ key, remoteTaskId }) => adapters.pollTask({ key, baseUrl: provider.baseUrl, remoteTaskId }),
     intervalMs: cap === 'video' ? 6000 : 2500,
     onSuccess: async (t, r) => {
       fs.mkdirSync(outputDir(), { recursive: true });
@@ -156,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'];
 
 /**
@@ -181,14 +181,18 @@ function safeRegister(ctx, definition) {
 }
 
 export async function apply(ctx) {
+  guard('Iris 私有存储权限收紧', () => hardenPrivateTree(store.irisHome()));
 
   guard('上传临时文件清理', () => purgeStaleUploads());
 
-  // 首次运行：从工作台导入（幂等）
+  // 仅按用户显式指定的路径导入旧配置；不扫描其他项目。
   guard('工作台导入', () => {
-    const wb = path.join(process.env.HOME || os.homedir(), 'projects', 'ai-paint', 'data', 'config.json');
+    const wb = process.env.IRIS_IMPORT_WORKBENCH_CONFIG;
+    if (!wb) return;
+    if (!path.isAbsolute(wb)) throw new Error('IRIS_IMPORT_WORKBENCH_CONFIG 必须是绝对路径');
     const imported = store.importFromWorkbench(wb);
     if (imported.imported) console.log(`[iris] 已从工作台导入 ${imported.imported} 个服务商`);
+    else console.log('[iris] 工作台导入：' + imported.reason);
   });
 
   // 接管上次进程未跑完的异步任务（恢复循环本身在 tasks.js 里逐任务防御）
@@ -211,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 服务不可用，跳过全部工具注册（宿主不受影响）');
@@ -1025,4 +1038,3 @@ async function describeFirstImage(ctx, ref, absPath, originalPrompt) {
     return ''; // 自述是增强项，失败不影响交付
   }
 }
-

package/lib/locate.js

@@ -2,7 +2,7 @@
 /**
  * Iris 模型驱动定位（阶段 3A）：iris_locate。
  *
- * 对齐 RESEARCH 4.2a：返回**原图像素 bbox**（x1/y1/x2/y2），不是相对或归一化坐标，
+ * 返回**原图像素 bbox**（x1/y1/x2/y2），不是相对或归一化坐标，
  * 保证 iris_crop 可以无缝接力裁剪（vision-router 的 vision_ground 同款契约）。
  *
  * 实现：

package/lib/media-probe.js

@@ -2,11 +2,11 @@
 /**
  * Iris 媒体分析探测（阶段 7.1）—— 视频抽帧。
  *
- * ffmpeg 是可选系统可执行文件：启动时用 `which` 探测，缺失则 `ffmpegAvailable()` 返回
+ * ffmpeg 是可选系统可执行文件：启动时直接执行版本探测，缺失则 `ffmpegAvailable()` 返回
  * false，抽帧工具在执行时报清晰的人话错误（其余功能不受影响）。静态版 ffmpeg
  * （johnvansickle）同样可用。本模块为纯后端：零 npm 依赖，可离线单测。
  *
- * 契约（对齐 RESEARCH §9.2）：
+ * 抽帧契约：
  * - 最多帧数上限 20（覆盖 5 分钟短视频，不超 LLM 上下文窗口）；
  * - 最大宽度 4096（含），缩放到 targetWidth，高度按比例取偶数；
  * - 帧数 = 请求数（时间均匀采样），短视频也能取到整 N 帧；
@@ -24,8 +24,8 @@ export const MIN_WIDTH = 16;
 /** 探测 ffmpeg / ffprobe 是否可用 */
 export function ffmpegAvailable() {
   try {
-    const ff = spawnSync('which', ['ffmpeg'], { encoding: 'utf8' });
-    const fp = spawnSync('which', ['ffprobe'], { encoding: 'utf8' });
+    const ff = spawnSync('ffmpeg', ['-version'], { stdio: 'ignore', windowsHide: true });
+    const fp = spawnSync('ffprobe', ['-version'], { stdio: 'ignore', windowsHide: true });
     return ff.status === 0 && fp.status === 0;
   } catch (_) {
     return false;

package/lib/media.js

@@ -3,7 +3,7 @@
  * Iris 媒体通道 —— 让视频/音频像图片一样在对话流里可点可播。
  *
  * 背景：DSH 附件服务只收图片（saveImage/readImage），mp4/wav 无原生通路。
- * 方案（学 vision-mix）：宿内 /iris/media 路由 + 工具结果返回播放链接。
+ * 方案：宿内 /iris/media 路由 + 工具结果返回播放链接。
  *
  * 安全边界：
  * - token 是能力凭证：crypto 随机 128bit，只存在任务记录里，URL 不可枚举

package/lib/private-storage.js

@@ -0,0 +1,77 @@
+'use strict';
+/**
+ * Iris 私有存储原语。
+ *
+ * POSIX 上目录统一 0700、文件统一 0600；Windows 的 mode 不能替代 ACL，
+ * 仍在创建时传入最小 mode，但公开文档不会把它描述成 Windows 访问控制。
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const HAS_POSIX_MODE = process.platform !== 'win32';
+
+function tryChmod(target, mode) {
+  if (!HAS_POSIX_MODE) return;
+  try { fs.chmodSync(target, mode); } catch (_) { /* 调用方仍可继续使用宿主文件系统 */ }
+}
+
+export function ensurePrivateDir(dir) {
+  const existed = fs.existsSync(dir);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  // 不擅自 chmod 调用方传入的既有父目录（例如适配器单测使用 os.tmpdir）。
+  // Iris 自有既有树由启动时 hardenPrivateTree() 明确收紧。
+  if (!existed) tryChmod(dir, 0o700);
+  return dir;
+}
+
+export function chmodPrivateFile(file) {
+  tryChmod(file, 0o600);
+}
+
+export function writePrivateFile(file, data, options = {}) {
+  ensurePrivateDir(path.dirname(file));
+  fs.writeFileSync(file, data, { ...options, mode: 0o600 });
+  chmodPrivateFile(file);
+}
+
+export function privateSibling(file, label = 'tmp') {
+  return `${file}.${label}-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+}
+
+export function atomicWritePrivate(file, data) {
+  ensurePrivateDir(path.dirname(file));
+  const tmp = privateSibling(file);
+  try {
+    fs.writeFileSync(tmp, data, { mode: 0o600, flag: 'wx' });
+    fs.renameSync(tmp, file);
+    chmodPrivateFile(file);
+  } finally {
+    try { fs.rmSync(tmp, { force: true }); } catch (_) { /* rename 成功后临时文件已不存在 */ }
+  }
+}
+
+/** 收紧既有 Iris 树；不跟随符号链接，也不修改文件内容。 */
+export function hardenPrivateTree(root) {
+  ensurePrivateDir(root);
+  if (!HAS_POSIX_MODE) return { directories: 0, files: 0, skipped: true };
+  let directories = 0;
+  let files = 0;
+  const walk = (target) => {
+    let st;
+    try { st = fs.lstatSync(target); } catch (_) { return; }
+    if (st.isSymbolicLink()) return;
+    if (st.isDirectory()) {
+      tryChmod(target, 0o700);
+      directories++;
+      for (const name of fs.readdirSync(target)) walk(path.join(target, name));
+      return;
+    }
+    if (st.isFile()) {
+      tryChmod(target, 0o600);
+      files++;
+    }
+  };
+  walk(root);
+  return { directories, files, skipped: false };
+}

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();
+}