@mokuyoaxis/dsh-iris 0.1.0

package/lib/locate.js

@@ -0,0 +1,94 @@
+'use strict';
+/**
+ * Iris 模型驱动定位（阶段 3A）：iris_locate。
+ *
+ * 对齐 RESEARCH 4.2a：返回**原图像素 bbox**（x1/y1/x2/y2），不是相对或归一化坐标，
+ * 保证 iris_crop 可以无缝接力裁剪（vision-router 的 vision_ground 同款契约）。
+ *
+ * 实现：
+ * - 复用阶段 1 的 VisionBackend 链（askWithBackends）做识图；
+ * - 提示词强制模型只回严格 JSON bbox；
+ * - 解析/校验/钳制：JSON 提取、字段数字校验、x1<x2 且 y1<y2、轻微越界 clamp、
+ *   完全越界报错、found=false 明确返回。
+ */
+import { askWithBackends } from './vision.js';
+
+export class LocateError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'LocateError';
+  }
+}
+
+/** 从模型回答里提取第一个平衡的 {...} JSON 对象文本；无则 null */
+export function extractBboxJson(answer) {
+  const text = String(answer || '');
+  const start = text.indexOf('{');
+  if (start < 0) return null;
+  let depth = 0;
+  for (let i = start; i < text.length; i++) {
+    if (text[i] === '{') depth++;
+    else if (text[i] === '}') {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+/**
+ * 在原图上定位目标，返回原像素 bbox。
+ * @param {Array} backends 有序视觉后端（buildVisionBackends 产物）
+ * @param {{target:string, imageDataUrl:string, width:number, height:number, signal?:AbortSignal}}
+ * @returns {Promise<{found:boolean, x1?:number, y1?:number, x2?:number, y2?:number, via?:string, model?:string}>}
+ * @throws LocateError 模型未返回有效 bbox / bbox 完全越界 / 字段非法
+ */
+export async function locateObject(backends, { target, imageDataUrl, width, height, signal }) {
+  const W = Math.floor(width);
+  const H = Math.floor(height);
+  if (!Number.isFinite(W) || !Number.isFinite(H) || W <= 0 || H <= 0) {
+    throw new LocateError('iris_locate: 图片尺寸无效');
+  }
+  const prompt =
+    `在图片中定位「${String(target).slice(0, 200)}」。` +
+    `只返回一个 JSON 对象，不要输出任何其他文字或解释。格式：` +
+    `{"x1":左上角x,"y1":左上角y,"x2":右下角x,"y2":右下角y}` +
+    `（原像素坐标，图片左上角为(0,0)，尺寸 ${W}x${H}，要求 x1<x2 且 y1<y2）。` +
+    `请确保 bbox 完全包围目标，不得遗漏目标的任何部分。` +
+    `如果图片中没有该目标，返回 {"found":false}。`;
+
+  const { answer, via, model } = await askWithBackends(backends, { question: prompt, imageDataUrl, signal });
+
+  const jsonText = extractBboxJson(answer);
+  if (!jsonText) throw new LocateError('iris_locate: 模型未返回有效 JSON：' + String(answer).slice(0, 160));
+  let obj;
+  try {
+    obj = JSON.parse(jsonText);
+  } catch (_) {
+    throw new LocateError('iris_locate: bbox JSON 解析失败：' + jsonText.slice(0, 160));
+  }
+  if (obj && obj.found === false) return { found: false, via, model };
+
+  const { x1, y1, x2, y2 } = obj || {};
+  if (![x1, y1, x2, y2].every((v) => Number.isFinite(v))) {
+    throw new LocateError('iris_locate: bbox 字段必须是数字：' + jsonText.slice(0, 160));
+  }
+  if (!(x1 < x2 && y1 < y2)) {
+    throw new LocateError(`iris_locate: bbox 无效（要求 x1<x2 且 y1<y2，得到 ${x1},${y1},${x2},${y2}）`);
+  }
+  // 完全越界（与图片无交集）→ 报错；否则钳制到图片边界
+  if (x1 >= W || x2 <= 0 || y1 >= H || y2 <= 0) {
+    throw new LocateError(`iris_locate: bbox 完全超出图片边界 ${W}x${H}：${x1},${y1},${x2},${y2}`);
+  }
+  const clamp = (v) => Math.max(0, Math.min(v < 0 ? Math.round(v) : Math.ceil(v), W));
+  const clampY = (v) => Math.max(0, Math.min(v < 0 ? Math.round(v) : Math.ceil(v), H));
+  return {
+    found: true,
+    x1: clamp(x1),
+    y1: clampY(y1),
+    x2: clamp(x2),
+    y2: clampY(y2),
+    via,
+    model
+  };
+}

package/lib/media-probe.js

@@ -0,0 +1,169 @@
+'use strict';
+/**
+ * Iris 媒体分析探测（阶段 7.1）—— 视频抽帧。
+ *
+ * ffmpeg 是可选系统可执行文件：启动时用 `which` 探测，缺失则 `ffmpegAvailable()` 返回
+ * false，抽帧工具在执行时报清晰的人话错误（其余功能不受影响）。静态版 ffmpeg
+ * （johnvansickle）同样可用。本模块为纯后端：零 npm 依赖，可离线单测。
+ *
+ * 契约（对齐 RESEARCH §9.2）：
+ * - 最多帧数上限 20（覆盖 5 分钟短视频，不超 LLM 上下文窗口）；
+ * - 最大宽度 4096（含），缩放到 targetWidth，高度按比例取偶数；
+ * - 帧数 = 请求数（时间均匀采样），短视频也能取到整 N 帧；
+ * - 返回帧的时间戳 = i * duration / n（i 从 0 起，均匀分布）。
+ */
+import { spawnSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const MAX_FRAMES = 20;
+export const MAX_WIDTH = 4096;
+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' });
+    return ff.status === 0 && fp.status === 0;
+  } catch (_) {
+    return false;
+  }
+}
+
+/** 用 ffprobe 读取视频元数据 */
+export function probeVideo(inputPath) {
+  if (!ffmpegAvailable()) throw new Error('iris: ffmpeg 不可用，无法分析视频（可选安装 ffmpeg/ffprobe 后启用）');
+  if (!fs.existsSync(inputPath)) throw new Error('iris: 视频文件不存在: ' + inputPath);
+  const r = spawnSync('ffprobe', [
+    '-v', 'error',
+    '-show_entries', 'format=duration,size:stream=width,height,codec_name,codec_type',
+    '-of', 'json',
+    inputPath
+  ], { encoding: 'utf8' });
+  if (r.status !== 0) throw new Error('iris: ffprobe 读取失败: ' + (r.stderr || '').slice(0, 300));
+  let data;
+  try { data = JSON.parse(r.stdout); } catch (_) { throw new Error('iris: ffprobe 输出解析失败'); }
+  const fmt = data.format || {};
+  const streams = Array.isArray(data.streams) ? data.streams : [];
+  const videoStream = streams.find((s) => s.codec_type === 'video' || s.width);
+  const audioStream = streams.find((s) => s.codec_type === 'audio');
+  return {
+    durationSec: Number(fmt.duration) || 0,
+    sizeBytes: Number(fmt.size) || 0,
+    width: videoStream ? Number(videoStream.width) || 0 : 0,
+    height: videoStream ? Number(videoStream.height) || 0 : 0,
+    codec: videoStream ? videoStream.codec_name || '' : '',
+    hasAudio: !!audioStream,
+    audioCodec: audioStream ? audioStream.codec_name || '' : ''
+  };
+}
+
+/** 校验并收敛抽帧参数，返回规范化配置 */
+export function normalizeFramesOptions({ maxFrames = 8, targetWidth = 640, quality = 85, format = 'jpeg' } = {}) {
+  if (format !== 'jpeg' && format !== 'png') throw new Error('iris: format 只支持 jpeg 或 png');
+  const n = Math.round(Number(maxFrames));
+  if (!Number.isFinite(n) || n < 1) throw new Error('iris: maxFrames 必须是 ≥1 的整数');
+  const clampedN = Math.min(n, MAX_FRAMES);
+  const w = Math.round(Number(targetWidth));
+  if (!Number.isFinite(w) || w < MIN_WIDTH) throw new Error(`iris: targetWidth 必须是 ≥${MIN_WIDTH} 的整数`);
+  const clampedW = Math.min(w, MAX_WIDTH);
+  const q = Math.round(Number(quality));
+  if (!Number.isFinite(q) || q < 1 || q > 100) throw new Error('iris: quality 必须是 1–100 的整数');
+  return { maxFrames: clampedN, targetWidth: clampedW, quality: q, format };
+}
+
+/** 目标缩放后尺寸：宽 = min(targetWidth, 源宽)，高按比例取偶数 */
+export function scaledDimensions(srcWidth, srcHeight, targetWidth) {
+  const outW = Math.min(targetWidth, Math.max(1, srcWidth));
+  const outH = Math.max(2, Math.round((srcHeight * outW) / Math.max(1, srcWidth)) & ~1);
+  return { width: outW, height: outH };
+}
+
+/** 异步跑 ffmpeg（不阻塞宿主事件循环），支持取消信号 */
+function runFfmpeg(args, { signal } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', (c) => { stderr += c; });
+    child.on('error', (e) => reject(e));
+    child.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error('iris: 抽帧失败: ' + stderr.slice(0, 300)));
+    });
+    if (signal) {
+      if (signal.aborted) { child.kill('SIGKILL'); reject(new Error('已取消')); return; }
+      signal.addEventListener('abort', () => { child.kill('SIGKILL'); reject(new Error('已取消')); }, { once: true });
+    }
+  });
+}
+
+/**
+ * 从视频抽取 N 张帧（时间均匀采样），输出 JPEG/PNG buffer 数组。
+ * @param {{inputPath:string, maxFrames?:number, targetWidth?:number, quality?:number, format?:'jpeg'|'png', signal?:AbortSignal}}
+ * @returns {Promise<Array<{buffer:Buffer, atSec:number, width:number, height:number}>>}
+ */
+export async function extractFrames({ inputPath, maxFrames = 8, targetWidth = 640, quality = 85, format = 'jpeg', signal } = {}) {
+  const opts = normalizeFramesOptions({ maxFrames, targetWidth, quality, format });
+  if (!ffmpegAvailable()) throw new Error('iris: ffmpeg 不可用，无法抽帧（可选安装 ffmpeg/ffprobe 后启用）');
+  if (!inputPath || typeof inputPath !== 'string') throw new Error('iris: inputPath 必须是视频文件的绝对路径');
+  if (!fs.existsSync(inputPath)) throw new Error('iris: 视频文件不存在: ' + inputPath);
+  const meta = probeVideo(inputPath);
+  const duration = meta.durationSec;
+  if (!(duration > 0)) throw new Error('iris: 无法读取视频时长（文件可能不是有效视频）');
+  const n = opts.maxFrames;
+  const { width: outW, height: outH } = scaledDimensions(meta.width, meta.height, opts.targetWidth);
+  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'iris-frames-'));
+  const ext = opts.format === 'png' ? '.png' : '.jpg';
+  try {
+    // fps 滤镜均匀抽帧：fps = n/duration（分数形式对短视频也精确产出 N 帧）
+    const fps = `${n}/${duration}`;
+    const outFile = path.join(outDir, 'f%d' + ext);
+    const args = ['-v', 'error', '-i', inputPath, '-vf', `fps=${fps},scale='min(${opts.targetWidth},iw)':-2`];
+    if (opts.format === 'png') args.push(outFile);
+    else args.push('-q:v', String(opts.quality), outFile);
+    await runFfmpeg(args, { signal });
+    const frames = [];
+    const names = fs.readdirSync(outDir).filter((f) => f.endsWith('.jpg') || f.endsWith('.png')).sort();
+    for (const name of names) {
+      const idx = Number(name.replace(/^f/, '').replace(/\.(jpg|png)$/, ''));
+      if (!Number.isFinite(idx) || idx < 1 || idx > n) continue; // 只取前 N 帧
+      const atSec = duration > 0 ? ((idx - 1) * duration) / n : 0;
+      frames.push({ buffer: fs.readFileSync(path.join(outDir, name)), atSec, width: outW, height: outH });
+    }
+    if (!frames.length) throw new Error('iris: 抽帧结果为空（ffmpeg 未产出任何帧）');
+    return frames;
+  } finally {
+    fs.rmSync(outDir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * 从视频提取音轨（mp3，libmp3lame；静态 ffmpeg 已内置）。7.3 摘要的音轨转写输入。
+ * @param {{inputPath:string, signal?:AbortSignal}} opts
+ * @returns {Promise<{filePath:string, outDir:string, mime:string}>} 调用方负责 finally 清理 outDir
+ */
+export async function extractAudioTrack({ inputPath, signal } = {}) {
+  if (!ffmpegAvailable()) throw new Error('iris: ffmpeg 不可用，无法提取音轨（可选安装 ffmpeg/ffprobe 后启用）');
+  if (!inputPath || typeof inputPath !== 'string') throw new Error('iris: inputPath 必须是视频文件的绝对路径');
+  if (!fs.existsSync(inputPath)) throw new Error('iris: 视频文件不存在: ' + inputPath);
+  const meta = probeVideo(inputPath);
+  if (!meta.hasAudio) throw new Error('iris: 该视频没有音轨，无需提取');
+  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), 'iris-audio-'));
+  const filePath = path.join(outDir, 'track.mp3');
+  try {
+    await runFfmpeg([
+      '-v', 'error', '-i', inputPath,
+      '-vn', '-acodec', 'libmp3lame', '-q:a', '4',
+      '-y', filePath
+    ], { signal });
+    if (!fs.existsSync(filePath) || fs.statSync(filePath).size === 0) {
+      throw new Error('iris: 音轨提取结果为空（ffmpeg 未产出音频）');
+    }
+    return { filePath, outDir, mime: 'audio/mpeg' };
+  } catch (err) {
+    fs.rmSync(outDir, { recursive: true, force: true });
+    throw err;
+  }
+}

package/lib/media.js

@@ -0,0 +1,172 @@
+'use strict';
+/**
+ * Iris 媒体通道 —— 让视频/音频像图片一样在对话流里可点可播。
+ *
+ * 背景：DSH 附件服务只收图片（saveImage/readImage），mp4/wav 无原生通路。
+ * 方案（学 vision-mix）：宿内 /iris/media 路由 + 工具结果返回播放链接。
+ *
+ * 安全边界：
+ * - token 是能力凭证：crypto 随机 128bit，只存在任务记录里，URL 不可枚举
+ * - 文件定位只信任务记录（taskId+token 精确匹配），URL 里的文件名段仅作展示，
+ *   绝不参与文件系统路径解析（防目录穿越）
+ * - 未命中一律 404（不给枚举线索）；仅允许 GET/HEAD
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import * as tasks from './tasks.js';
+
+const MIME = {
+  '.mp4': 'video/mp4',
+  '.mov': 'video/quicktime',
+  '.webm': 'video/webm',
+  '.wav': 'audio/wav',
+  '.mp3': 'audio/mpeg',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif'
+};
+
+/** Web 基址：默认本机 DSH GUI；反代/远程部署用 DSH_WEB_BASE 覆盖 */
+export function webBase() {
+  return String(process.env.DSH_WEB_BASE || 'http://127.0.0.1:3080').replace(/\/+$/, '');
+}
+
+export function mimeOf(name) {
+  return MIME[path.extname(String(name)).toLowerCase()] || 'application/octet-stream';
+}
+
+function kindLabel(mime) {
+  if (mime.startsWith('video/')) return '▶ 视频';
+  if (mime.startsWith('audio/')) return '♪ 音频';
+  if (mime.startsWith('image/')) return '🖼 图片';
+  return '📄 文件';
+}
+
+/**
+ * 把一个已落盘的产物登记为可访问媒体：生成 token、写进任务记录、返回链接信息。
+ * @returns {{file,token,mime,url}|null}
+ */
+export function registerMedia(taskId, absPath) {
+  const t = tasks.get(taskId);
+  if (!t) return null;
+  const file = path.basename(absPath);
+  if (!(t.media || []).some((e) => e.file === file)) {
+    const entry = {
+      file,
+      token: crypto.randomBytes(16).toString('hex'),
+      mime: mimeOf(file),
+      createdAt: new Date().toISOString()
+    };
+    tasks.update(taskId, { media: [...(t.media || []), entry] });
+    return { ...entry, url: mediaUrl(taskId, entry) };
+  }
+  const entry = t.media.find((e) => e.file === file);
+  return { ...entry, url: mediaUrl(taskId, entry) };
+}
+
+export function mediaUrl(taskId, entry) {
+  return `${webBase()}/iris/media/${taskId}/${entry.token}/${encodeURIComponent(entry.file)}`;
+}
+
+/** 任务记录里全部媒体的 Markdown 播放链接 */
+export function mediaLinksOf(task) {
+  return (task.media || []).map((e) => `- [${kindLabel(mimeOf(e.file))} 播放](${mediaUrl(task.id, e)})`);
+}
+
+/** 解析并授权一次媒体请求；未授权返回 null */
+export function authorizeMedia(taskId, token, name) {
+  const t = tasks.get(taskId);
+  const entry = t && (t.media || []).find((e) => e.token === token && e.file === name);
+  if (!entry) return null;
+  const abs = path.join(tasks.outputsDir(), entry.file);
+  if (!fs.existsSync(abs)) return null;
+  return { entry, abs, size: fs.statSync(abs).size };
+}
+
+/* ---------------- HTTP 服务（GET/HEAD + Range 流式） ---------------- */
+
+function sendText(res, status, text) {
+  if (res.writableEnded || res.destroyed) return; // 已结束连接不再写（与 api.js sendJson 同纪律）
+  if (!res.headersSent) res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
+  res.end(text);
+}
+
+/**
+ * 解析单段 Range 头：bytes=start-end / bytes=start- / bytes=-suffix。
+ * @returns {null|{invalid:true}|{start:number,end:number}} null = 无/不可解析 → 走 200 全量
+ */
+export function parseRange(header, size) {
+  const m = /^bytes=(\d*)-(\d*)$/.exec(String(header || '').trim());
+  if (!m) return null;
+  let start = m[1] === '' ? undefined : Number(m[1]);
+  let end = m[2] === '' ? undefined : Number(m[2]);
+  if (start === undefined && end === undefined) return null;
+  if (start === undefined) {
+    const suffix = end;
+    if (!Number.isFinite(suffix) || suffix <= 0) return null;
+    start = Math.max(0, size - suffix);
+    end = size - 1;
+  } else {
+    if (!Number.isFinite(start) || start < 0 || start >= size) return { invalid: true };
+    if (end === undefined || !Number.isFinite(end) || end >= size) end = size - 1;
+  }
+  if (start > end) return null;
+  return { start, end };
+}
+
+/**
+ * 流式服务媒体产物：支持 HEAD、单段 Range（206 Partial Content / 416）、
+ * 全量/部分都用 createReadStream 流式，避免大视频整体进内存。
+ * 未命中一律 404；仅 GET/HEAD。
+ */
+export function serveMedia(req, res) {
+  try {
+    const method = String(req.method || 'GET').toUpperCase();
+    if (method !== 'GET' && method !== 'HEAD') return sendText(res, 405, 'method not allowed');
+    const parts = String(req.url || '').split('?')[0].split('/').filter(Boolean);
+    // /iris/media/:taskId/:token/:name
+    if (parts.length !== 5 || parts[0] !== 'iris' || parts[1] !== 'media') return sendText(res, 404, 'not found');
+    let name;
+    try {
+      name = decodeURIComponent(parts[4]);
+    } catch (_) {
+      return sendText(res, 404, 'not found');
+    }
+    const hit = authorizeMedia(parts[2], parts[3], name);
+    if (!hit) return sendText(res, 404, 'not found'); // 未命中一律 404，不给枚举线索
+    const base = {
+      'Content-Type': hit.entry.mime,
+      'Content-Disposition': `inline; filename*=UTF-8''${encodeURIComponent(hit.entry.file)}`,
+      'Accept-Ranges': 'bytes',
+      'Cache-Control': 'private, max-age=3600',
+      'X-Content-Type-Options': 'nosniff'
+    };
+    const range = parseRange(req.headers && req.headers.range, hit.size);
+    if (range && range.invalid) {
+      res.writeHead(416, { ...base, 'Content-Range': `bytes */${hit.size}` });
+      res.end();
+      return;
+    }
+    if (range) {
+      const len = range.end - range.start + 1;
+      res.writeHead(206, { ...base, 'Content-Length': len, 'Content-Range': `bytes ${range.start}-${range.end}/${hit.size}` });
+      if (method === 'HEAD') return res.end();
+      const stream = fs.createReadStream(hit.abs, { start: range.start, end: range.end });
+      stream.on('error', () => { try { res.destroy(); } catch (_) {} });
+      res.on('close', () => { if (!res.writableEnded) stream.destroy(); }); // 客户端中途断开：立即释放读流，不留 fd 到 EOF
+      stream.pipe(res);
+      return;
+    }
+    res.writeHead(200, { ...base, 'Content-Length': hit.size });
+    if (method === 'HEAD') return res.end();
+    const stream = fs.createReadStream(hit.abs);
+    stream.on('error', () => { try { res.destroy(); } catch (_) {} });
+    res.on('close', () => { if (!res.writableEnded) stream.destroy(); });
+    stream.pipe(res);
+  } catch (err) {
+    sendText(res, 500, 'media error');
+  }
+}

package/lib/models.js

@@ -0,0 +1,128 @@
+'use strict';
+/**
+ * Iris 模型发现规则（阶段 6）。
+ *
+ * 目标：把「账号（key）」与「能力」解耦——一个 key 提供模型池，能力从池里选模型。
+ * 本模块是纯静态规则（零 API 调用）：模型名 → 能力标签。
+ *
+ * 池的来源：
+ *   ① provider 显式 `models` 数组（未来配置，可带 capabilities 覆盖）
+ *   ② 旧模型字段迁移：imageModel→image-gen、videoModel→video-gen、ttsModel→tts、
+ *      transcribeModel→transcribe、visionModel→vision
+ *   ③ 裸 DashScope 账号：已知模型清单（wan 系列 / qwen-vl / qwen-tts）作为池
+ */
+import { CAPABILITIES } from './capability.js';
+
+/** 能力 → provider 上的模型字段（保持向后兼容的返回形状） */
+export const CAP_FIELD = {
+  [CAPABILITIES.IMAGE]: 'imageModel',
+  [CAPABILITIES.VIDEO]: 'videoModel',
+  [CAPABILITIES.TTS]: 'ttsModel',
+  [CAPABILITIES.TRANSCRIBE]: 'transcribeModel',
+  [CAPABILITIES.VISION]: 'visionModel'
+};
+
+const MODEL_REF_SEP = '::';
+
+/** 稳定的模型复合引用；provider/model 分别编码，避免同名模型跨账号碰撞。 */
+export function modelRef(providerId, modelId) {
+  return encodeURIComponent(String(providerId || '')) + MODEL_REF_SEP + encodeURIComponent(String(modelId || ''));
+}
+
+/** 解析复合引用；旧的纯 model id 返回 null，由配置层按兼容规则解析。 */
+export function parseModelRef(ref) {
+  if (typeof ref !== 'string') return null;
+  const i = ref.indexOf(MODEL_REF_SEP);
+  if (i <= 0) return null;
+  try {
+    const providerId = decodeURIComponent(ref.slice(0, i));
+    const modelId = decodeURIComponent(ref.slice(i + MODEL_REF_SEP.length));
+    return providerId && modelId ? { providerId, modelId } : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/** 模型名模式 → 能力（静态规则，来源为 DashScope/OpenAI 已知模型命名族） */
+const MODEL_CAP_RULES = [
+  // 视频先于图像：wan*-t2v/s2v/i2v/video 不能被图像规则误吞
+  [/^wan.*-(t2v|s2v|i2v|r2v|video)/i, [CAPABILITIES.VIDEO]],
+  [/^wan.*-t2i/i, [CAPABILITIES.IMAGE]],
+  [/^wan.*image/i, [CAPABILITIES.IMAGE]], // wan2.7-image / -pro
+  [/^qwen-image-edit/i, []], // 纯编辑模型没有文生图能力，不自动加入 iris_draw_image
+  [/^qwen-image/i, [CAPABILITIES.IMAGE]], // qwen-image-3.0 / -max
+  [/^z-image/i, [CAPABILITIES.IMAGE]],
+  [/^qwen\d?-vl/i, [CAPABILITIES.VISION]], // qwen-vl / qwen3-vl / -max / -ocr
+  [/^qwen\d?-tts/i, [CAPABILITIES.TTS]], // qwen-tts / qwen3-tts-flash
+  [/^cosyvoice/i, [CAPABILITIES.TTS]],
+  [/^(?:qwen-audio-.*-asr-.*filetrans|qwen3-asr-.*filetrans|fun-asr(?:-|$)|paraformer)/i, [CAPABILITIES.TRANSCRIBE]],
+  [/^(?:qwen-audio-turbo|sensevoice)/i, []], // 音频理解模型/待下线模型不自动分配给文件转写
+  [/^gpt-image/i, [CAPABILITIES.IMAGE]],
+  [/^dall-e/i, [CAPABILITIES.IMAGE]],
+  [/^gemini/i, [CAPABILITIES.VISION]] // Gemini 默认按视觉能力纳入（可被显式配置覆盖）
+];
+
+/** 裸 DashScope 已知模型清单（无显式模型字段时作为池） */
+const DASHSCOPE_KNOWN = [
+  { id: 'wan2.2-t2i-flash', caps: [CAPABILITIES.IMAGE] },
+  { id: 'wan2.2-t2v-flash', caps: [CAPABILITIES.VIDEO] },
+  { id: 'wan2.2-s2v-flash', caps: [CAPABILITIES.VIDEO] },
+  { id: 'qwen-vl-plus', caps: [CAPABILITIES.VISION] },
+  // VERIFY 2026-09-03 实证：locate grounding 零偏差（qwen-vl-plus 仅 25x25 框选）
+  { id: 'qwen3-vl-235b-a22b-thinking', caps: [CAPABILITIES.VISION] },
+  { id: 'qwen-tts-latest', caps: [CAPABILITIES.TTS] },
+  { id: 'qwen-audio-3.0-asr-flash-filetrans', caps: [CAPABILITIES.TRANSCRIBE] }
+];
+
+/** 按模型名规则推断能力 */
+export function capabilitiesOfModel(modelName) {
+  const name = String(modelName || '');
+  for (const [re, caps] of MODEL_CAP_RULES) {
+    if (re.test(name)) return [...caps];
+  }
+  return [];
+}
+
+/** 一个 provider 的模型池条目列表：[{ id, providerId, capabilities:[], verified?, source? }] */
+export function providerModels(p) {
+  if (!p) return [];
+  const out = [];
+  const push = (id, caps, extra) => {
+    const name = String(id || '').trim();
+    if (!name || out.some((m) => m.id === name)) return;
+    out.push({ id: name, providerId: p.id, ref: modelRef(p.id, name), capabilities: [...caps], ...(extra || {}) });
+  };
+  // ① 显式 models 数组（带可选 capabilities 覆盖 + verified/source 透传）
+  if (Array.isArray(p.models) && p.models.length) {
+    for (const m of p.models) {
+      const id = typeof m === 'string' ? m : m && m.id;
+      // 显式空数组也是权威覆盖：用户可明确标记“此模型无能力”。
+      const caps = Array.isArray(m && m.capabilities) ? m.capabilities : capabilitiesOfModel(id);
+      const extra = typeof m === 'object' && m ? { verified: m.verified, source: m.source } : {};
+      push(id, caps, extra);
+    }
+    return out;
+  }
+  // ② 旧模型字段迁移
+  for (const [cap, field] of Object.entries(CAP_FIELD)) {
+    if (p[field]) push(p[field], [cap]);
+  }
+  if (out.length) return out;
+  // ③ 裸 DashScope 账号 → 已知模型池
+  if (/dashscope/i.test(String(p.baseUrl || ''))) {
+    for (const m of DASHSCOPE_KNOWN) push(m.id, m.caps);
+  }
+  return out;
+}
+
+/** 全局模型池：合并所有 provider 的模型 */
+export function modelPool(providers) {
+  const pool = [];
+  for (const p of providers || []) pool.push(...providerModels(p));
+  return pool;
+}
+
+/** 从池里挑有某能力的模型（按池顺序） */
+export function pickModel(pool, capability) {
+  return (pool || []).find((m) => m.capabilities.includes(capability)) || null;
+}

package/lib/ocr.js

@@ -0,0 +1,80 @@
+'use strict';
+/**
+ * Iris 长截图 OCR（阶段 3B）：视觉模型分块文字识别。
+ *
+ * 调研结论（RESEARCH.md §7）：qwen-vl 视觉模型中文零误差，tesseract.js 准确率差且置信度虚高。
+ * 方案：复用阶段 1 VisionBackend 链，sharp 分块（1200px 高 + 120px 重叠避免切断文本行），
+ * 逐块 OCR 后拼接。
+ *
+ * 契约：
+ * - chunkHeight 默认 1200，overlap 默认 120
+ * - 每块独立调用视觉模型，结果按 y 坐标顺序拼接
+ * - 返回全文 + 分块明细 + 元数据
+ */
+import sharp from 'sharp';
+import { askWithBackends } from './vision.js';
+import { imageDimensions } from './pixels.js';
+
+export class OcrError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'OcrError';
+  }
+}
+
+const OCR_PROMPT = '请完整读出图片中的全部文字，包括标点符号。按从上到下的顺序逐行输出。不要添加额外解释。';
+
+/**
+ * 分块 OCR：把长图按 chunkHeight 切片（重叠 overlap 避免切断文本行），逐块调用视觉模型，
+ * 拼接全文。
+ * @param {{input: Buffer|string, backends: Array, chunkHeight?:number, overlap?:number, signal?:AbortSignal, maxDimension?:number}}
+ * @returns {Promise<{fullText:string, chunks:Array, totalChunks:number, width:number, height:number}>}
+ *   chunks: [{y, height, text, error?}]
+ */
+export async function longOcr({ input, backends, chunkHeight = 1200, overlap = 120, signal, maxDimension = 2048 }) {
+  if (!Array.isArray(backends) || backends.length === 0) {
+    throw new OcrError('iris_long_ocr: 没有可用的视觉后端（至少需要一个 vision provider）');
+  }
+  const { width: W, height: H } = await imageDimensions(input);
+  if (W <= 0 || H <= 0) throw new OcrError('iris_long_ocr: 图片尺寸无效');
+  const ch = Math.max(100, Math.floor(chunkHeight));
+  const ov = Math.max(0, Math.min(Math.floor(overlap), ch - 1));
+  const step = ch - ov;
+
+  // 如果宽度超过 maxDimension，先等比缩放
+  let img = input;
+  if (W > maxDimension) {
+    const s = maxDimension / W;
+    const resized = await sharp(input).resize(Math.round(W * s), Math.round(H * s)).png().toBuffer();
+    img = resized;
+  }
+  const meta = await sharp(img).metadata();
+  const iw = meta.width || W;
+  const ih = meta.height || H;
+
+  const chunks = [];
+  let y = 0;
+  while (y < ih) {
+    const h = Math.min(ch, ih - y);
+    if (h <= 0) break;
+    try {
+      const png = await sharp(img).extract({ left: 0, top: y, width: iw, height: h }).png().toBuffer();
+      const dataUrl = `data:image/png;base64,${png.toString('base64')}`;
+      const { answer } = await askWithBackends(backends, {
+        question: OCR_PROMPT,
+        imageDataUrl: dataUrl,
+        signal
+      });
+      chunks.push({ y, height: h, text: String(answer || '').trim() });
+    } catch (err) {
+      chunks.push({ y, height: h, text: '', error: String((err && err.message) || err) });
+    }
+    y += step;
+  }
+  const fullText = chunks
+    .filter((c) => c.text)
+    .map((c, i) => `[第${i + 1}段 y=${c.y}] ${c.text}`)
+    .join('\n')
+    .trim();
+  return { fullText, chunks, totalChunks: chunks.length, width: meta.width || W, height: meta.height || H };
+}