@mokuyoaxis/dsh-iris 0.1.0

package/lib/pixels.js

@@ -0,0 +1,140 @@
+'use strict';
+/**
+ * Iris 确定性像素工具后端（阶段 2）：iris_crop + iris_pixel_diff。
+ *
+ * 基于 sharp（Apache-2.0，本机 aarch64 proot Debian 已验证）。
+ * 契约（进入测试）：
+ * - crop：区域 (left,top,width,height) 必须为正且不越界；输出 PNG + 实际尺寸。
+ * - diff：尺寸不一致时以「较小者」为基准强制归一化（fit=fill），上限
+ *   MAX_DIFF_DIMENSION 防爆内存；alpha 通道不参与差异计算；颜色空间统一 sRGB。
+ * - 差异判定用 RGB 通道差之和阈值（容忍压缩噪声），diff ratio = 差异像素占比。
+ */
+import sharp from 'sharp';
+
+/** diff 归一化后的最大边长（防超大图整读内存） */
+const MAX_DIFF_DIMENSION = 1024;
+/** RGB 通道差之和超过该值才计为差异像素（容忍 JPEG 压缩噪声） */
+const DIFF_THRESHOLD = 30;
+
+export class PixelError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'PixelError';
+  }
+}
+
+/** 读图片宽高（iris_locate 等需要原图尺寸的地方用） */
+export async function imageDimensions(input) {
+  const meta = await sharp(input).metadata();
+  if (!meta.width || !meta.height) throw new PixelError('iris: 图片尺寸读取失败');
+  return { width: meta.width, height: meta.height };
+}
+
+/**
+ * 裁剪图片区域，输出 PNG + 实际尺寸。
+ * @param {{input: Buffer|string, left:number, top:number, width:number, height:number}}
+ * @returns {Promise<{buffer:Buffer, width:number, height:number, mime:string}>}
+ */
+export async function cropImage({ input, left, top, width, height }) {
+  const meta = await sharp(input).metadata();
+  const W = meta.width || 0;
+  const H = meta.height || 0;
+  const l = Math.floor(left);
+  const t = Math.floor(top);
+  const w = Math.floor(width);
+  const h = Math.floor(height);
+  for (const [name, v] of [['left', l], ['top', t], ['width', w], ['height', h]]) {
+    if (!Number.isFinite(v)) throw new PixelError(`iris_crop: ${name} 必须是数字`);
+  }
+  if (w <= 0 || h <= 0) throw new PixelError(`iris_crop: width/height 必须为正（得到 ${w}x${h}）`);
+  if (l < 0 || t < 0 || l + w > W || t + h > H) {
+    throw new PixelError(`iris_crop: 区域 (${l},${t},${w},${h}) 超出图片边界 ${W}x${H}`);
+  }
+  const { data, info } = await sharp(input)
+    .extract({ left: l, top: t, width: w, height: h })
+    .png()
+    .toBuffer({ resolveWithObject: true });
+  return { buffer: data, width: info.width, height: info.height, mime: 'image/png' };
+}
+
+/**
+ * 像素级 diff：输出 diff ratio、最差区域、热力图 PNG。
+ * @param {{inputA: Buffer|string, inputB: Buffer|string, grid?:number, topRegions?:number}}
+ * @returns {Promise<{ratio:number, diffPixels:number, totalPixels:number, width:number, height:number,
+ *   worstRegions:Array<{row:number,col:number,score:number}>, heatmap:Buffer, mime:string}>}
+ */
+export async function pixelDiff({ inputA, inputB, grid = 8, topRegions = 3 }) {
+  const [metaA, metaB] = await Promise.all([sharp(inputA).metadata(), sharp(inputB).metadata()]);
+  if (!metaA.width || !metaA.height || !metaB.width || !metaB.height) {
+    throw new PixelError('iris_pixel_diff: 图片尺寸读取失败');
+  }
+  // 尺寸策略：以较小者为基准归一化；超上限等比缩到 MAX_DIFF_DIMENSION 内
+  let targetW = Math.min(metaA.width, metaB.width);
+  let targetH = Math.min(metaA.height, metaB.height);
+  const cap = Math.max(targetW, targetH);
+  if (cap > MAX_DIFF_DIMENSION) {
+    const s = MAX_DIFF_DIMENSION / cap;
+    targetW = Math.max(1, Math.round(targetW * s));
+    targetH = Math.max(1, Math.round(targetH * s));
+  }
+
+  // 读取两图 RGB raw（去 alpha，统一到目标尺寸，强制拉伸对齐）
+  const [rawA, rawB] = await Promise.all([
+    sharp(inputA).resize(targetW, targetH, { fit: 'fill' }).removeAlpha().raw().toBuffer(),
+    sharp(inputB).resize(targetW, targetH, { fit: 'fill' }).removeAlpha().raw().toBuffer()
+  ]);
+  if (rawA.length !== targetW * targetH * 3 || rawB.length !== targetW * targetH * 3) {
+    throw new PixelError('iris_pixel_diff: 像素读取失败（尺寸不匹配）');
+  }
+
+  const N = targetW * targetH;
+  const mag = new Float32Array(N); // 每像素归一化差异幅值 0..1
+  let diffPixels = 0;
+  for (let i = 0; i < N; i++) {
+    const o = i * 3;
+    const d =
+      Math.abs(rawA[o] - rawB[o]) +
+      Math.abs(rawA[o + 1] - rawB[o + 1]) +
+      Math.abs(rawA[o + 2] - rawB[o + 2]);
+    mag[i] = d / 765;
+    if (d > DIFF_THRESHOLD) diffPixels++;
+  }
+  const ratio = N ? diffPixels / N : 0;
+
+  // 8x8（默认）网格：统计每格平均差异，取最差 topRegions
+  const g = Math.max(1, Math.floor(grid));
+  const gw = Math.ceil(targetW / g);
+  const gh = Math.ceil(targetH / g);
+  const cells = [];
+  for (let r = 0; r < g; r++) {
+    for (let c = 0; c < g; c++) {
+      let sum = 0;
+      let cnt = 0;
+      const y0 = r * gh;
+      const y1 = Math.min((r + 1) * gh, targetH);
+      const x0 = c * gw;
+      const x1 = Math.min((c + 1) * gw, targetW);
+      for (let y = y0; y < y1; y++) {
+        for (let x = x0; x < x1; x++) {
+          sum += mag[y * targetW + x];
+          cnt++;
+        }
+      }
+      cells.push({ row: r, col: c, score: cnt ? sum / cnt : 0 });
+    }
+  }
+  cells.sort((a, b) => b.score - a.score);
+  const worstRegions = cells.slice(0, Math.max(1, Math.floor(topRegions)));
+
+  // 热力图：灰度 PNG，亮度 = 差异幅值（放大低差异可见性）
+  const heat = Buffer.alloc(N * 3);
+  for (let i = 0; i < N; i++) {
+    const v = Math.min(255, Math.round(mag[i] * 255 * 2));
+    heat[i * 3] = v;
+    heat[i * 3 + 1] = v;
+    heat[i * 3 + 2] = v;
+  }
+  const heatmap = await sharp(heat, { raw: { width: targetW, height: targetH, channels: 3 } }).png().toBuffer();
+
+  return { ratio, diffPixels, totalPixels: N, width: targetW, height: targetH, worstRegions, heatmap, mime: 'image/png' };
+}

package/lib/render.js

@@ -0,0 +1,138 @@
+'use strict';
+/**
+ * Iris HTML 渲染抽象（阶段 3C/HTML 截图）。
+ *
+ * HtmlRenderer 接口：render({ html, width?, height?, fullPage? }) →
+ *   Promise<{ png: Buffer }>
+ *
+ * BrowserHtmlRenderer：基于宿主 webServer 的 /iris/render/ 静态路由 +
+ * dsh-builtin-browser 的 ctx.browser 服务（可选访问，软耦合）。
+ * - 不 import dsh-builtin-browser 包，只在运行时探测 ctx.get('browser')
+ * - HTML 通过宿主路由以同源 HTTP 打开（避免 file:// 的 CORS 限制）
+ * - 每次调用独立临时渲染目录，用后即删
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { irisHome } from './config.js';
+import { webBase, mimeOf } from './media.js';
+
+export class RenderError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'RenderError';
+  }
+}
+
+/** 渲染临时目录根：$DSH_HOME/iris/v1/render/ */
+export function renderRoot() {
+  return path.join(irisHome(), 'render');
+}
+
+/**
+ * 基于 ctx.browser（dsh-builtin-browser）的 HTML → PNG 渲染器。
+ * @param {{browser?: object, waitMs?: number}} opts browser 为 ctx.get('browser') 服务
+ */
+export class BrowserHtmlRenderer {
+  constructor({ browser, waitMs = 1200 }) {
+    this.browser = browser;
+    this.waitMs = waitMs;
+  }
+
+  async render({ html, width, height, fullPage }) {
+    const b = this.browser;
+    if (!b || typeof b.open !== 'function' || typeof b.openUrl !== 'function' || typeof b.screenshot !== 'function') {
+      throw new RenderError('iris: 浏览器服务不可用（ctx.get("browser") 为空）——需要启用 dsh-builtin-browser 插件');
+    }
+    const text = String(html || '').trim();
+    if (!text) throw new RenderError('iris_html_screenshot: html 不能为空');
+
+    // 每次调用独立子目录（随机名），写 index.html
+    const dir = path.join(renderRoot(), crypto.randomBytes(6).toString('hex'));
+    fs.mkdirSync(dir, { recursive: true });
+    let content = text;
+    if (width || height) {
+      const w = width ? Math.floor(width) : 'auto';
+      const h = height ? Math.floor(height) : 'auto';
+      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 });
+    const url = `${webBase()}/iris/render/${path.basename(dir)}/index.html`;
+    const pngPath = path.join(dir, 'render.png');
+
+    try {
+      const session = await b.open();
+      try {
+        await b.openUrl(session, { url, newTab: true });
+        if (this.waitMs > 0) {
+          await new Promise((r) => setTimeout(r, this.waitMs)); // 等页面加载（无加载完成事件可用的折中）
+        }
+        await b.screenshot(session, { fullPage: fullPage !== false, savePath: pngPath });
+      } finally {
+        try { await b.close(session); } catch (_) { /* 幂等 */ }
+      }
+      if (!fs.existsSync(pngPath)) throw new RenderError('iris_html_screenshot: 浏览器未产出截图文件');
+      return { png: fs.readFileSync(pngPath) };
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true }); // 用完即清
+    }
+  }
+}
+
+/* ---------------- /iris/render/ 静态路由（同源 HTTP 服务渲染目录） ---------------- */
+
+/**
+ * webServer 前缀路由 handler：GET/HEAD /iris/render/<dir>/<file>。
+ * 只服务 renderRoot() 下两级路径（随机子目录 + 单文件），路径穿越一律 404。
+ */
+export function serveRender(req, res) {
+  try {
+    const method = String(req.method || 'GET').toUpperCase();
+    if (method !== 'GET' && method !== 'HEAD') {
+      if (!res.headersSent) res.writeHead(405, { 'Content-Type': 'text/plain; charset=utf-8' });
+      res.end('method not allowed');
+      return;
+    }
+    const parts = String(req.url || '').split('?')[0].split('/').filter(Boolean);
+    // /iris/render/<dir>/<file> —— 恰好 4 段（iris/render/dir/file）
+    if (parts.length !== 4 || parts[0] !== 'iris' || parts[1] !== 'render') {
+      return send404(res);
+    }
+    const [, , subdir, file] = parts;
+    // 段必须是安全 basename（拒绝 .. / 空）
+    for (const seg of [subdir, file]) {
+      if (!seg || seg === '.' || seg === '..' || /[\\/]/.test(seg)) return send404(res);
+    }
+    const root = renderRoot();
+    const abs = path.join(root, subdir, file);
+    // 双保险：解析后必须仍在渲染根内
+    if (!abs.startsWith(root + path.sep) || !fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+      return send404(res);
+    }
+    const size = fs.statSync(abs).size;
+    // .html 必须是 text/html（Chromium 在 nosniff 下拒绝 octet-stream 的 HTML 导航 → ERR_ABORTED）
+    const ext = path.extname(file).toLowerCase();
+    const contentType = ext === '.html' || ext === '.htm'
+      ? 'text/html; charset=utf-8'
+      : mimeOf(file);
+    res.writeHead(200, {
+      'Content-Type': contentType,
+      'Content-Length': size,
+      'Cache-Control': 'no-store',
+      // 不可信 HTML 只负责排版截图：无脚本、无网络、无表单，且为 opaque origin。
+      'Content-Security-Policy': "sandbox; default-src 'none'; img-src data: blob:; style-src 'unsafe-inline'; font-src data:; connect-src 'none'; form-action 'none'; base-uri 'none'; frame-src 'none'",
+      'Referrer-Policy': 'no-referrer',
+      'X-Content-Type-Options': 'nosniff'
+    });
+    res.end(method === 'HEAD' ? undefined : fs.readFileSync(abs));
+  } catch (err) {
+    if (!res.headersSent) res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+    res.end('render error');
+  }
+}
+
+function send404(res) {
+  if (!res.headersSent) res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+  res.end('not found');
+}

package/lib/summarize.js

@@ -0,0 +1,111 @@
+'use strict';
+/**
+ * Iris 多模态上下文摘要（阶段 7.3）—— 把视频压成「一张联系表 + 一段转写文本」喂给视觉模型。
+ *
+ * 为什么是 contact sheet：
+ * - VisionBackend 一次 analyze 只送一张图（自持栈吃 dataUrl / 全局模型吃 attachment ref），
+ *   逐帧送 N 次要 N 次模型调用、费用与延迟都不可接受；
+ * - 把 N 帧缩略图按时间序拼成网格 + 每帧盖时间戳标签，一次视觉调用即可看全片（上下文压缩）。
+ *
+ * 契约：
+ * - buildContactSheet(frames, opts) → PNG buffer + 网格尺寸（纯 sharp，可离线测试）
+ * - summarizeMedia({backends, question?, transcript?, imageDataUrl, ref, signal})
+ *   → askWithBackends（复用阶段 1 降级链），prompt 里嵌入转写文本（若有）
+ */
+import sharp from 'sharp';
+
+export class SummarizeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SummarizeError';
+  }
+}
+
+const DEFAULT_QUESTION = '请根据这些视频关键帧（按时间顺序从左到右、从上到下排列）总结视频的画面内容、场景与主题。';
+
+/**
+ * 把 N 帧拼成带时间戳标签的联系表（PNG buffer）。
+ * @param {{frames:Array<{buffer:Buffer, atSec:number, width:number, height:number}>, cols?:number, maxSheetWidth?:number}}
+ * @returns {Promise<{buffer:Buffer, width:number, height:number, rows:number, cols:number}>}
+ */
+export async function buildContactSheet({ frames, cols = 3, maxSheetWidth = 1024 }) {
+  if (!Array.isArray(frames) || frames.length === 0) {
+    throw new SummarizeError('iris_media_summarize: 没有可拼的帧');
+  }
+  const n = frames.length;
+  const colsN = Math.max(1, Math.min(Math.floor(cols), n, 4));
+  const rowsN = Math.ceil(n / colsN);
+  // 每格宽度：以源帧宽为基准，但整表不超过 maxSheetWidth（防超上下文）
+  const cellW = Math.max(80, Math.min(frames[0].width || 640, Math.floor(maxSheetWidth / colsN)));
+  const labelH = 22; // 时间戳标签高度
+  const gap = 4;
+
+  // 先逐帧缩略图 + 时间戳标签合成单个 cell
+  const cells = [];
+  for (let i = 0; i < n; i++) {
+    const f = frames[i];
+    const w = Math.max(1, cellW);
+    const scale = w / Math.max(1, f.width || w);
+    const h = Math.max(1, Math.round((f.height || 0) * scale));
+    const thumb = await sharp(f.buffer)
+      .resize(w, h, { fit: 'fill' })
+      .png()
+      .toBuffer();
+    // 时间戳标签（SVG 覆盖在缩略图下方）
+    const label = Buffer.from(
+      `<svg width="${w}" height="${labelH}" xmlns="http://www.w3.org/2000/svg">` +
+      `<rect width="100%" height="100%" fill="rgba(0,0,0,0.62)"/>` +
+      `<text x="4" y="${labelH - 7}" font-family="monospace" font-size="12" fill="#ffffff">` +
+      `${f.atSec.toFixed(1)}s</text></svg>`
+    );
+    const cell = await sharp(thumb)
+      .composite([{ input: label, top: h, left: 0 }])
+      .png()
+      .toBuffer();
+    cells.push({ buffer: cell, width: w, height: h + labelH });
+  }
+
+  const cellH = cells[0].height;
+  const sheetW = colsN * cellW + (colsN - 1) * gap;
+  const sheetH = rowsN * cellH + (rowsN - 1) * gap;
+  const composite = cells.map((c, i) => ({
+    input: c.buffer,
+    left: (i % colsN) * (cellW + gap),
+    top: Math.floor(i / colsN) * (cellH + gap)
+  }));
+  const buffer = await sharp({
+    create: { width: sheetW, height: sheetH, channels: 3, background: { r: 16, g: 16, b: 20 } }
+  })
+    .composite(composite)
+    .png()
+    .toBuffer();
+  return { buffer, width: sheetW, height: sheetH, rows: rowsN, cols: colsN };
+}
+
+/** 组装摘要提示词：画面指令 + （可选）转写文本 */
+export function buildSummaryPrompt({ question, transcript }) {
+  const q = String(question || '').trim() || DEFAULT_QUESTION;
+  let prompt = q;
+  if (transcript && String(transcript).trim()) {
+    const t = String(transcript).trim();
+    prompt +=
+      `\n\n视频音轨的语音转写文本如下（可能不完整或含识别噪声）：\n` +
+      `"""\n${t.slice(0, 6000)}\n"""\n` +
+      `请结合转写内容补充说明视频的对话、旁白或口头信息（如有）。`;
+  }
+  return prompt;
+}
+
+/**
+ * 多模态摘要：contact sheet 图 + 可选转写文本 → 视觉后端链 → 摘要文本。
+ * @param {{backends:Array, question?:string, transcript?:string, imageDataUrl:string, ref?:object, signal?:AbortSignal}}
+ * @returns {Promise<{answer:string, via:string, model:string, backendId:string, errors:Array}>}
+ */
+export async function summarizeMedia({ backends, question, transcript, imageDataUrl, ref, signal }) {
+  if (!Array.isArray(backends) || backends.length === 0) {
+    throw new SummarizeError('iris_media_summarize: 没有可用的视觉后端（至少需要一个 vision provider）');
+  }
+  const { askWithBackends } = await import('./vision.js');
+  const prompt = buildSummaryPrompt({ question, transcript });
+  return askWithBackends(backends, { question: prompt, imageDataUrl, ref, signal });
+}