@mokuyoaxis/dsh-iris 0.1.0 → 0.1.1

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,6 +18,7 @@ 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';
@@ -38,8 +38,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 +89,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 +101,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 });
@@ -181,14 +180,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 里逐任务防御）
@@ -1025,4 +1028,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/provider-protocol.js

@@ -0,0 +1,25 @@
+'use strict';
+/** 供应商媒体协议判断与 DashScope 凭据边界。 */
+
+const DASH_SCOPE_HOST = /^dashscope(?:-[a-z0-9-]+)?\.aliyuncs\.com$/i;
+
+export function isDashScopeBaseUrl(value) {
+  try {
+    const url = new URL(String(value || '').trim());
+    return url.protocol === 'https:' && !url.username && !url.password && DASH_SCOPE_HOST.test(url.hostname);
+  } catch (_) {
+    return false;
+  }
+}
+
+export function inferMediaProtocol(baseUrl) {
+  return isDashScopeBaseUrl(baseUrl) ? 'dashscope' : 'openai-images';
+}
+
+/** 返回官方 DashScope API 根；不满足边界时在 fetch 前拒绝。 */
+export function dashscopeApiBase(baseUrl) {
+  if (!isDashScopeBaseUrl(baseUrl)) {
+    throw new Error('iris: DashScope 协议只允许使用阿里云官方 HTTPS Base URL；已阻止发送 API Key');
+  }
+  return new URL('/api/v1', String(baseUrl).trim()).toString().replace(/\/$/, '');
+}

package/lib/render.js

@@ -16,6 +16,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { irisHome } from './config.js';
 import { webBase, mimeOf } from './media.js';
+import { ensurePrivateDir, writePrivateFile } from './private-storage.js';
 
 export class RenderError extends Error {
   constructor(message) {
@@ -49,7 +50,7 @@ export class BrowserHtmlRenderer {
 
     // 每次调用独立子目录（随机名），写 index.html
     const dir = path.join(renderRoot(), crypto.randomBytes(6).toString('hex'));
-    fs.mkdirSync(dir, { recursive: true });
+    ensurePrivateDir(dir);
     let content = text;
     if (width || height) {
       const w = width ? Math.floor(width) : 'auto';
@@ -57,7 +58,7 @@ export class BrowserHtmlRenderer {
       content = `<div style="min-width:${w}px;min-height:${h}px">${text}</div>`;
     }
     const htmlPath = path.join(dir, 'index.html');
-    fs.writeFileSync(htmlPath, content, { mode: 0o600 });
+    writePrivateFile(htmlPath, content);
     const url = `${webBase()}/iris/render/${path.basename(dir)}/index.html`;
     const pngPath = path.join(dir, 'render.png');
 

package/lib/tasks.js

@@ -1,6 +1,6 @@
 'use strict';
 /**
- * Iris 任务框架 —— ai-paint/lib/tasks.js 的「宿内版」。
+ * Iris 任务框架 —— 从早期独立工作台演进而来的「宿内版」。
  *
  * 与 DSH 俱荣俱损的三条纪律：
  * - 无独立进程：盯守定时器全部 unref（不拖住 DSH 退出），且随插件 Fiber 清理（stopWatchAll）
@@ -14,6 +14,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { irisHome } from './config.js';
+import { atomicWritePrivate, chmodPrivateFile, privateSibling } from './private-storage.js';
 
 const FILE = () => path.join(irisHome(), 'tasks.json');
 /** 产物目录：$DSH_HOME/iris/v1/outputs */
@@ -46,19 +47,24 @@ function emitChange() {
 }
 
 function persist() {
-  fs.mkdirSync(path.dirname(FILE()), { recursive: true });
-  const tmp = FILE() + '.tmp';
-  // 0600 从创建时生效（含临时文件）；rename 保留 mode，chmod 兜底不依赖 umask
-  fs.writeFileSync(tmp, JSON.stringify({ version: 1, tasks: cache.tasks }, null, 2), { mode: 0o600 });
-  fs.renameSync(tmp, FILE());
-  try {
-    fs.chmodSync(FILE(), 0o600);
-  } catch (_) {
-    /* ignore */
-  }
+  atomicWritePrivate(FILE(), JSON.stringify({ version: 1, tasks: cache.tasks }, null, 2));
   emitChange(); // 任何任务落盘 = 状态变了 → SSE 推送
 }
 
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateStoredTasks(value) {
+  if (!isPlainObject(value)) throw new Error('任务根节点必须是对象');
+  if (!Array.isArray(value.tasks)) throw new Error('tasks 必须是数组');
+  for (const task of value.tasks) {
+    if (!isPlainObject(task) || typeof task.id !== 'string' || !task.id.trim()) {
+      throw new Error('task 条目必须是带非空 id 的对象');
+    }
+  }
+}
+
 function load() {
   if (cache) return cache;
   const file = FILE();
@@ -70,12 +76,14 @@ function load() {
   }
   try {
     const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
-    cache = { version: 1, tasks: Array.isArray(raw.tasks) ? raw.tasks : [] };
+    validateStoredTasks(raw);
+    cache = { version: 1, tasks: raw.tasks };
   } catch (err) {
     // 文件存在但损坏：隔离，绝不静默覆盖证据
-    const backup = file + '.corrupted-' + Date.now();
+    const backup = privateSibling(file, 'corrupted');
     try {
       fs.renameSync(file, backup);
+      chmodPrivateFile(backup);
     } catch (_) {
       /* 隔离失败也继续 */
     }

package/lib/vision.js

@@ -2,7 +2,7 @@
 /**
  * Iris 视觉后端抽象（阶段 1）。
  *
- * 对齐 RESEARCH 4.1b 的 vision-mix 经验：把"识图"拆成「VisionBackend 接口 +
+ * 把“识图”拆成「VisionBackend 接口 +
  * 两个实现」，让自持栈与 DSH 全局模型可替换、按序降级。
  * - SelfStackVisionBackend：自持栈（OpenAI 兼容 /chat/completions，qwen-vl）
  * - GlobalLlmVisionBackend：DSH 全局视觉模型（ctx.llm.stream()）
@@ -141,7 +141,7 @@ const RED_HINTS = /红|red/i;
 
 /**
  * 视觉能力测试：向后端发固定红色测试图并提问，验证回答是否识别出红色。
- * 用于「测试并启用」流程（对齐 RESEARCH 4.5b 的 vision-mix 经验）。
+ * 用于用户显式触发的能力实测流程。
  * @param {object} backend VisionBackend 实例（有 analyze 方法）
  * @param {{timeoutMs?:number, signal?:AbortSignal}} opts
  * @returns {Promise<{ok:boolean, answer:string, error?:string, timedOut?:boolean}>}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mokuyoaxis/dsh-iris",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Give DeepSeek Harness eyes and hands: multi-provider media generation, vision routing, and an integrated Iris workbench.",
   "type": "module",
   "main": "lib/index.js",
@@ -24,16 +24,19 @@
     ".dsh/skills/iris-compose-media"
   ],
   "dsh": {
+    "engines": {
+      "dsh": ">=0.1.2-rc.1 <0.1.3-0"
+    },
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-locale",
-        "@deepseek-ai/dsh-client-ui-slots",
         "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-session",
         "@deepseek-ai/dsh-client-ui-settings"
       ]
     }
@@ -48,30 +51,31 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=20.9.0"
+    "node": ">=20.10.0"
   },
   "scripts": {
-    "test": "for f in tests/*.mjs; do node \"$f\" || exit 1; done",
-    "lint": "node tests/lint.mjs"
+    "test": "node scripts/test.mjs",
+    "lint": "node tests/lint.mjs",
+    "prepublishOnly": "npm test"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-client-locale": "*",
-    "@deepseek-ai/dsh-client-runtime": "*",
-    "@deepseek-ai/dsh-client-ui-conversation": "*",
-    "@deepseek-ai/dsh-client-ui-settings": "*",
-    "@deepseek-ai/dsh-client-ui-slots": "*"
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-session": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1"
   },
   "peerDependenciesMeta": {
-    "@deepseek-ai/dsh-client-runtime": {
+    "@deepseek-ai/dsh-client-locale": {
       "optional": true
     },
-    "@deepseek-ai/dsh-client-locale": {
+    "@deepseek-ai/dsh-client-ui-conversation": {
       "optional": true
     },
-    "@deepseek-ai/dsh-client-ui-slots": {
+    "@deepseek-ai/dsh-client-ui-renderer": {
       "optional": true
     },
-    "@deepseek-ai/dsh-client-ui-conversation": {
+    "@deepseek-ai/dsh-client-ui-session": {
       "optional": true
     },
     "@deepseek-ai/dsh-client-ui-settings": {

package/user_guide.md

@@ -4,7 +4,7 @@
 
 ## 安装
 
-你需要一个可用的 DeepSeek Harness、PATH 中的 `pnpm`，以及至少一个媒体或视觉服务供应商。dsh-iris 自身要求 Node.js 20.9 或更高版本；如果所用 DSH 版本要求更高，以 DSH 为准。
+你需要 DeepSeek Harness `>=0.1.2-rc.1 <0.1.3-0`、PATH 中的 `pnpm`，以及至少一个媒体或视觉服务供应商。dsh-iris 自身要求 Node.js 20.10 或更高版本；如果所用 DSH 版本要求更高，以 DSH 为准。Iris 0.1.1 不兼容 DSH 0.1.0/0.1.1 的旧客户端 Runtime。
 
 从 npm 安装到 Web profile：
 
@@ -20,7 +20,7 @@ dsh plugin --profile web add .
 dsh web
 ```
 
-浏览器默认打开 `http://127.0.0.1:3080`。插件安装后只会在下一次 DSH 启动时装载；如果 DSH 已经运行，请先停止再启动。
+浏览器默认打开 `http://127.0.0.1:3080`。插件安装后只会在下一次 DSH 启动时装载；如果 DSH 已经运行，请先停止再启动。启动输出包含一次性认证参数时，必须完整打开该 URL，不能只输入裸地址。
 
 可以在启动前检查组合配置：
 
@@ -50,10 +50,10 @@ Iris 当前支持两类调用路径：
 
 | 路径 | 可用能力 | 说明 |
 |---|---|---|
-| DashScope 百炼 | 图片、视频、TTS、转写、视觉 | 默认媒体协议，覆盖最完整 |
+| DashScope 百炼 | 图片、视频、TTS、转写、视觉 | 覆盖最完整；媒体请求只允许阿里云官方 HTTPS 域名 |
 | OpenAI 兼容 | Images 图片生成、Chat Completions 视觉 | 具体模型和能力取决于兼容服务 |
 
-工作台新增供应商时，媒体协议默认是 `dashscope`。接入 OpenAI Images 兼容服务时，需要在高级配置中把该供应商的 `mediaProtocol` 设为 `openai-images`；否则图片生成会按 DashScope 协议提交。
+工作台新增供应商时会按 Base URL 安全推断媒体协议：阿里云官方 DashScope HTTPS 域名使用 `dashscope`，其他地址使用 `openai-images`，也可以在供应商卡片中明确选择。即使配置被误标为 `dashscope`，Iris 也会在 fetch 前拒绝向非官方地址发送 DashScope API Key。
 
 同一个 OpenAI 兼容 Base URL 只有在实际提供相应接口时才能承担对应能力：图片生成需要 Images 接口，视觉理解需要支持图片输入的 Chat Completions 接口。通用 OpenAI 兼容端点目前不能替代 Iris 的 DashScope 视频、TTS 或转写协议。
 
@@ -73,12 +73,12 @@ Iris 当前支持两类调用路径：
 
 没有 `/models` 接口时，可以在供应商的模型池中手动添加模型名。Iris 能识别常见的 wan、qwen-vl、qwen-tts、qwen-audio ASR Filetrans、Fun-ASR、paraformer、gpt-image、dall-e 和 Gemini 命名；无法识别的模型需要在高级配置中显式填写 `capabilities`。
 
-模型旁的“测”会发起真实供应商请求，不是本地校验：
+点击模型旁单项能力标记会进行验证。视觉、图片和 TTS 会先显示确认框，再发起真实供应商请求，不是本地校验：
 
 - 视觉测试会发送一张最小测试图；
 - 图片和 TTS 测试会生成真实产物；
-- 视频测试只确认远端受理，不等待成片，但仍可能产生任务和费用；
-- 转写不使用空样本测试，应通过“音频转写”操作用真实音频验证。
+- 视频不会自动提交探针，因为“只确认受理”也可能创建计费任务；应通过“视频生成”操作验证。
+- 转写不使用空样本探针，应通过“音频转写”操作用真实音频验证。
 
 模型不必经过“测”才能使用。这个标记只记录人工触发的实测结果。
 
@@ -93,6 +93,24 @@ Iris 当前支持两类调用路径：
 
 生成类故障转移只覆盖上传、提交和同步生成阶段。远端一旦受理异步任务，Iris 就会继续跟踪这个任务，不会因轮询或下载失败自动重提，以免重复生成和计费。
 
+## 从旧工作台显式导入
+
+`ai-paint` 是 Iris 维护者本机未公开的前身项目，不是公开依赖。普通用户不需要、也不应该为了使用 Iris 去下载、安装或自行创建 ai-paint 目录；直接在 Iris 工作台添加供应商即可。
+
+旧版读取路径同时承担了本机迁移和密钥保护作用：由运行 DSH 的宿主进程直接读取维护者已有的本地配置，可以避免为了迁移把 API Key 重新粘贴到 Agent 会话、命令行参数或文档中。它不是一个配置服务，也不意味着 Iris 运行时应该长期依赖另一个项目。
+
+从 0.1.1 起，Iris 独立保存供应商、密钥、模型池和能力分配，位置为 `$DSH_HOME/iris/v1/providers.json`（未设置 `DSH_HOME` 时使用用户目录下的 `.dsh`）。修改 Iris 配置不会影响 ai-paint，反之亦然。
+
+默认启动不会扫描 ai-paint 或其他项目。推荐通过工作台手动添加供应商；需要迁移旧 ai-paint 配置时，先停止目标 DSH 实例并备份其 Iris 配置，再显式指定来源文件的绝对路径。Bash 示例：
+
+```bash
+IRIS_IMPORT_WORKBENCH_CONFIG="/absolute/path/ai-paint/data/config.json" dsh web
+```
+
+其他 Shell 请使用其环境变量设置方式。`IRIS_IMPORT_WORKBENCH_CONFIG` 的值只是来源配置文件的路径，不包含 API Key；该变量属于运行 DSH 的进程，目标仍由该进程的 `DSH_HOME` 决定。导入仅在 Iris 没有供应商时执行，复制供应商基本信息和凭据，不修改来源文件、不合并覆盖已有供应商，也不迁移模型池或能力分配。之后应在工作台检查协议并重新分配模型，后续启动不再设置此变量。
+
+变量未设置时不进行导入；相对路径会被拒绝。文件不可读、JSON 无效或没有有效供应商时会给出提示，不输出密钥。导入后的密钥写入 Iris 自己的配置文件，权限设为仅当前用户可读写；工作台和接口只返回密钥提示，不返回完整值。该操作不发送模型请求。
+
 ## 高级配置文件
 
 一般应使用 Iris 工作台。只有在配置工作台尚未覆盖的协议或模型能力时，才需要直接编辑：
@@ -132,7 +150,7 @@ $DSH_HOME/iris/v1/providers.json
 
 `assignments` 可以省略；省略后使用模型池顺序。包含特殊字符的 provider 或模型引用会经过 URL 编码，复杂引用建议在工作台中生成，不要手写。
 
-API Key 以明文保存在宿主侧的 `providers.json` 中，文件权限为 0600。状态接口和界面只返回掩码，不会显示完整 Key。不要把这个文件提交到版本库或发给他人。
+API Key 以明文保存在宿主侧的 `providers.json` 中。POSIX 上 Iris 目录为 `0700`、文件为 `0600`，0.1.1 首次启动会收紧既有 Iris 树但不修改内容或跟随符号链接；Windows 的 mode 不能替代 ACL。状态接口和界面只返回掩码，不会显示完整 Key。不要把这个文件提交到版本库或发给他人。
 
 ## 文件输入
 
@@ -177,7 +195,13 @@ Iris 会在会话输入区显示运行中任务，并在 Iris 工作台保留最
 | `$DSH_HOME/iris/v1/tasks.json` | 任务状态与附件索引 |
 | `$DSH_HOME/iris/v1/providers.json` | 供应商、模型池和能力分配 |
 
-音视频播放链接带随机令牌。反向代理或自定义 Web 地址下，可设置 `DSH_WEB_BASE`，例如 `https://dsh.example.com`，让 Iris 返回正确的媒体链接。
+音视频播放链接带随机令牌。默认只接受回环 Host。反向代理或 LAN 访问时，需要同时显式信任外部 Host，并按需设置媒体链接基址，例如：
+
+```bash
+IRIS_TRUSTED_HOSTS="dsh.example.com" DSH_WEB_BASE="https://dsh.example.com" dsh web
+```
+
+列表用逗号分隔，可填写 `host` 或精确的 `host:port`；反向代理应保留正确的 Host。`IRIS_TRUSTED_HOSTS` 只防止意外 Host 暴露，不验证用户身份。只要服务位于公网或不可信网络，就必须由反向代理或 DSH 部署层提供 HTTPS 和认证，不能把随机媒体令牌当作登录机制。
 
 ## 可选依赖
 
@@ -206,6 +230,7 @@ dsh plugin --profile web remove @mokuyoaxis/dsh-iris
 - **设置中没有 Iris 工作台**：确认插件已加入 Web profile，并在安装后重启 DSH；可用 `dsh plugin --profile web list` 和 `--dump-config` 检查。
 - **没有可用模型**：先确认供应商已启用且 Key 有效，再运行“发现模型”；不支持 `/models` 时手动添加。
 - **OpenAI 兼容图片请求走错协议**：确认该供应商的 `mediaProtocol` 是 `openai-images`。
+- **反向代理访问返回 `untrusted host`**：把浏览器实际使用的域名或 `host:port` 加入 `IRIS_TRUSTED_HOSTS`，保留 Host，并确认代理层已经启用认证。
 - **看图可用但 Iris 模型池显示为空**：Agent 视觉工具可以回退到 DSH 全局视觉模型；需要在工作台操作时仍建议配置 Iris 的 `vision` 模型。
 - **视频摘要提示 ffmpeg 不可用**：安装系统级 `ffmpeg` 和 `ffprobe`，并确保 DSH 进程的 PATH 能找到它们。
 - **本地文件不存在**：这里的“本地”指 DSH 宿主，不一定是浏览器所在设备；优先用“上传文件”。