@mokuyoaxis/dsh-iris 0.2.0 → 0.2.1

package/lib/locate.js

@@ -6,20 +6,80 @@
  * 保证 iris_crop 可以无缝接力裁剪（vision-router 的 vision_ground 同款契约）。
  *
  * 实现：
- * - 复用阶段 1 的 VisionBackend 链（askWithBackends）做识图；
+ * - 消费共享 Vision Ports；
  * - 提示词强制模型只回严格 JSON bbox；
  * - 解析/校验/钳制：JSON 提取、字段数字校验、x1<x2 且 y1<y2、轻微越界 clamp、
  *   完全越界报错、found=false 明确返回。
  */
-import { askWithBackends } from './vision.js';
+import { completeVision } from './vision-core.js';
+import { ModelPortError } from './model-port-contract.js';
+import { createVisionInputObserver } from './vision-image-input.js';
 
-export class LocateError extends Error {
+export class LocateError extends ModelPortError {
   constructor(message) {
-    super(message);
+    super('IRIS_MODEL_PROTOCOL_INVALID', { stage: 'normalize', invocation: 'responded' });
+    this.message = message;
     this.name = 'LocateError';
   }
 }
 
+export function normalizeLocateTarget(target) {
+  const value = String(target || '').trim();
+  if (!value) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+  return value.slice(0, 200);
+}
+
+function locatePrompt(target, width, height, normalized = false) {
+  const coordinates = normalized
+    ? `坐标必须使用 0–1000 归一化坐标：x=像素x/${width}*1000，y=像素y/${height}*1000；左上角(0,0)，右下角(1000,1000)，不得直接输出像素坐标`
+    : '本次输入图片的像素坐标，图片左上角为(0,0)';
+  return `在图片中定位「${target}」。只返回一个 JSON 对象，不要输出任何其他文字或解释。格式：`
+    + `{"x1":左上角x,"y1":左上角y,"x2":右下角x,"y2":右下角y}`
+    + `（图片尺寸 ${width}x${height}；${coordinates}；要求 x1<x2 且 y1<y2）。`
+    + `请确保 bbox 完全包围目标，不得遗漏目标的任何部分。如果图片中没有该目标，返回 {"found":false}。`;
+}
+
+/** 输入已显式转正；将四角逆变换回原始像素，向外取整以供原图裁剪。 */
+export function mapLocateBbox(bbox, input) {
+  if (bbox.found === false) return bbox;
+  const { width: W, height: H } = input.source;
+  const orientation = input.orientation;
+  const swapped = orientation >= 5 && orientation <= 8;
+  const sx = (swapped ? H : W) / (input.coordinateSpace === 'normalized-1000' ? 1000 : input.sent.width);
+  const sy = (swapped ? W : H) / (input.coordinateSpace === 'normalized-1000' ? 1000 : input.sent.height);
+  const inverse = (x, y) => {
+    switch (orientation) {
+      case 2: return [W - x, y];
+      case 3: return [W - x, H - y];
+      case 4: return [x, H - y];
+      case 5: return [y, x];
+      case 6: return [y, H - x];
+      case 7: return [W - y, H - x];
+      case 8: return [W - y, x];
+      default: return [x, y];
+    }
+  };
+  const corners = [[bbox.x1, bbox.y1], [bbox.x1, bbox.y2], [bbox.x2, bbox.y1], [bbox.x2, bbox.y2]]
+    .map(([x, y]) => inverse(x * sx, y * sy));
+  const xs = corners.map(([x]) => x), ys = corners.map(([, y]) => y);
+  // 消除比例换算在整数边缘的浮点误差，再对真实小数向外取整。
+  const edge = (value, round) => Math.abs(value - Math.round(value)) < 1e-9 ? Math.round(value) : round(value);
+  return { found: true, x1: Math.max(0, edge(Math.min(...xs), Math.floor)), y1: Math.max(0, edge(Math.min(...ys), Math.floor)),
+    x2: Math.min(W, edge(Math.max(...xs), Math.ceil)), y2: Math.min(H, edge(Math.max(...ys), Math.ceil)) };
+}
+
+/** 工厂钩子局限于本次业务，协议适配器不解析 bbox；候选各用自己的真实输入。 */
+export function createLocateImageRequest(target, inputs) {
+  target = normalizeLocateTarget(target);
+  const observe = createVisionInputObserver(inputs);
+  return async args => {
+    const input = await observe(args);
+    input.coordinateSpace = 'normalized-1000';
+    return { prompt: locatePrompt(target, input.sent.width, input.sent.height, true),
+      mapText: text => JSON.stringify(mapLocateBbox(parseLocateBbox(text, 1000, 1000, { round: false }), input)) };
+  };
+}
+
 /** 从模型回答里提取第一个平衡的 {...} JSON 对象文本；无则 null */
 export function extractBboxJson(answer) {
   const text = String(answer || '');
@@ -38,57 +98,55 @@ export function extractBboxJson(answer) {
 
 /**
  * 在原图上定位目标，返回原像素 bbox。
- * @param {Array} backends 有序视觉后端（buildVisionBackendsFromHost 产物）
- * @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}>}
+ * @param {Array} ports 有序 Vision Ports
+ * @param {{target:string, image:object, width:number, height:number}}
+ * @returns {Promise<object>} 完整模型结果及 bbox
  * @throws LocateError 模型未返回有效 bbox / bbox 完全越界 / 字段非法
  */
-export async function locateObject(backends, { target, imageDataUrl, width, height, signal }) {
+export async function locateObject(ports, { target, image, width, height }, options = {}) {
+  target = normalizeLocateTarget(target);
   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: 图片尺寸无效');
+    throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
   }
-  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 prompt = locatePrompt(target, W, H);
 
-  const { answer, via, model } = await askWithBackends(backends, { question: prompt, imageDataUrl, signal });
+  const result = await completeVision(ports, { prompt, image }, options);
+  return { ...result, bbox: parseLocateBbox(result.text, W, H) };
+}
 
+/** 保持原像素解析与钳制规则；格式失败不再发起模型调用。 */
+export function parseLocateBbox(answer, W, H, { round = true } = {}) {
   const jsonText = extractBboxJson(answer);
-  if (!jsonText) throw new LocateError('iris_locate: 模型未返回有效 JSON：' + String(answer).slice(0, 160));
+  if (!jsonText) throw new LocateError('iris_locate: 模型未返回有效 JSON');
   let obj;
   try {
     obj = JSON.parse(jsonText);
   } catch (_) {
-    throw new LocateError('iris_locate: bbox JSON 解析失败：' + jsonText.slice(0, 160));
+    throw new LocateError('iris_locate: bbox JSON 解析失败');
   }
-  if (obj && obj.found === false) return { found: false, via, model };
+  if (obj && obj.found === false) return { found: false };
 
   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));
+    throw new LocateError('iris_locate: bbox 字段必须是数字');
   }
   if (!(x1 < x2 && y1 < y2)) {
-    throw new LocateError(`iris_locate: bbox 无效（要求 x1<x2 且 y1<y2，得到 ${x1},${y1},${x2},${y2}）`);
+    throw new LocateError('iris_locate: bbox 无效（要求 x1<x2 且 y1<y2）');
   }
   // 完全越界（与图片无交集）→ 报错；否则钳制到图片边界
   if (x1 >= W || x2 <= 0 || y1 >= H || y2 <= 0) {
-    throw new LocateError(`iris_locate: bbox 完全超出图片边界 ${W}x${H}：${x1},${y1},${x2},${y2}`);
+    throw new LocateError('iris_locate: bbox 完全超出图片边界');
   }
-  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));
+  const pixel = v => round ? (v < 0 ? Math.round(v) : Math.ceil(v)) : v;
+  const clamp = (v) => Math.max(0, Math.min(pixel(v), W));
+  const clampY = (v) => Math.max(0, Math.min(pixel(v), H));
   return {
     found: true,
     x1: clamp(x1),
     y1: clampY(y1),
     x2: clamp(x2),
-    y2: clampY(y2),
-    via,
-    model
+    y2: clampY(y2)
   };
 }

package/lib/media-probe.js

@@ -125,7 +125,8 @@ export async function extractFrames({ inputPath, maxFrames = 8, targetWidth = 64
     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();
+    const names = fs.readdirSync(outDir).filter((f) => f.endsWith('.jpg') || f.endsWith('.png'))
+      .sort((a, b) => Number(a.match(/\d+/)[0]) - Number(b.match(/\d+/)[0]));
     for (const name of names) {
       const idx = Number(name.replace(/^f/, '').replace(/\.(jpg|png)$/, ''));
       if (!Number.isFinite(idx) || idx < 1 || idx > n) continue; // 只取前 N 帧

package/lib/model-call-runtime.js

@@ -0,0 +1,45 @@
+'use strict';
+/** 协议适配器的有界等待；调用方仍须把 signal 传给实际 I/O。 */
+import { ModelPortError, modelErrorRecord } from './model-port-contract.js';
+
+export function modelAbortError(signal, stage = 'prepare', invocation = 'not_invoked') {
+  return new ModelPortError(modelErrorRecord(signal?.reason).code === 'IRIS_MODEL_TIMEOUT'
+    ? 'IRIS_MODEL_TIMEOUT' : 'IRIS_MODEL_ABORTED', { stage, invocation });
+}
+
+export async function waitForModelWork(work, signal, stage = 'prepare', invocation = 'not_invoked') {
+  if (signal?.aborted) throw modelAbortError(signal, stage, invocation);
+  let listener;
+  const canceled = new Promise((_, reject) => {
+    listener = () => reject(modelAbortError(signal, stage, invocation));
+    signal?.addEventListener('abort', listener, { once: true });
+  });
+  // 延迟调用以便预先取消时零 I/O；race 同时消费晚到的 rejection。
+  const pending = Promise.resolve().then(() => {
+    if (signal?.aborted) throw modelAbortError(signal, stage, invocation);
+    return work();
+  });
+  try {
+    const result = await Promise.race([pending, canceled]);
+    if (signal?.aborted) throw modelAbortError(signal, stage, invocation);
+    return result;
+  } finally { signal?.removeEventListener('abort', listener); }
+}
+
+export function modelCallScope(parent, timeoutMs) {
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(parent.reason);
+  if (parent?.aborted) onAbort();
+  else parent?.addEventListener('abort', onAbort, { once: true });
+  const deadline = performance.now() + timeoutMs;
+  let timer;
+  const schedule = () => {
+    if (controller.signal.aborted) return;
+    const left = deadline - performance.now();
+    if (left <= 0) controller.abort(new ModelPortError('IRIS_MODEL_TIMEOUT'));
+    else timer = setTimeout(schedule, Math.min(2147483647, Math.ceil(left)));
+  };
+  schedule();
+  return { signal: controller.signal, abort: reason => controller.abort(reason),
+    dispose() { clearTimeout(timer); parent?.removeEventListener('abort', onAbort); } };
+}

package/lib/model-invoker.js

@@ -60,13 +60,15 @@ function scope({ parents = [], timeoutMs, startedAt = now() }) {
 /** abort 必须已传播到底层；race 只用于不合作的端口有界退出并处理晚到拒绝。 */
 async function waitForCompletion(work, signal) {
   let listener;
+  let cancelTimer;
   const interrupted = new Promise((_, reject) => {
-    listener = () => reject(signal.reason);
+    // 给合作的适配器一个事件循环拍完成清理并报告 responded；不合作端口仍有界退出。
+    listener = () => { cancelTimer = setTimeout(() => reject(signal.reason), 0); };
     if (signal.aborted) listener();
     else signal.addEventListener('abort', listener, { once: true });
   });
   try { return await Promise.race([work, interrupted]); }
-  finally { signal.removeEventListener('abort', listener); }
+  finally { clearTimeout(cancelTimer); signal.removeEventListener('abort', listener); }
 }
 
 function candidatePolicy(value) {

package/lib/model-port-contract.js

@@ -6,6 +6,7 @@ export const MODEL_IMAGE_MEDIA_TYPES = Object.freeze(['image/png', 'image/jpeg',
 
 const MESSAGES = Object.freeze({
   IRIS_MODEL_INPUT_INVALID: '模型请求或预算不合法',
+  IRIS_MODEL_IMAGE_TOO_LARGE: '图片超过模型输入预算',
   IRIS_MODEL_UNAVAILABLE: '模型能力不可用',
   IRIS_MODEL_INCOMPATIBLE: '模型端口或协议不兼容',
   IRIS_MODEL_UNSUPPORTED: '模型不支持所请求的能力或参数',
@@ -40,14 +41,19 @@ export class ModelPortError extends Error {
     if (typeof code !== 'string' || !Object.hasOwn(MESSAGES, code)) throw new TypeError('未知模型错误码');
     super(MESSAGES[code]);
     this.name = 'ModelPortError';
-    const { stage = 'validate', invocation = 'not_invoked', backendId, status } = details;
+    const { stage = 'validate', invocation = 'not_invoked', backendId, status, imageBytes, imageMaxBytes } = details;
     if (!STAGES.has(stage) || !INVOCATIONS.has(invocation)
         || (backendId !== undefined && !backendIdValid(backendId))
-        || (status !== undefined && (!Number.isInteger(status) || status < 100 || status > 599))) {
+        || (status !== undefined && (!Number.isInteger(status) || status < 100 || status > 599))
+        || [imageBytes, imageMaxBytes].some(value => value !== undefined && (!Number.isSafeInteger(value) || value <= 0))) {
       throw new TypeError('模型错误上下文不合法');
     }
-    const record = Object.freeze({ code, message: MESSAGES[code], stage, invocation,
-      ...(backendId !== undefined ? { backendId } : {}), ...(status !== undefined ? { status } : {}) });
+    const message = code === 'IRIS_MODEL_IMAGE_TOO_LARGE' && imageBytes
+      ? `图片大小 ${imageBytes} 字节${imageMaxBytes ? `，输入上限 ${imageMaxBytes} 字节` : '，超过模型输入上限'}；请调整账号或模型的看图输入预算`
+      : MESSAGES[code];
+    const record = Object.freeze({ code, message, stage, invocation,
+      ...(backendId !== undefined ? { backendId } : {}), ...(status !== undefined ? { status } : {}),
+      ...(imageBytes !== undefined ? { imageBytes } : {}), ...(imageMaxBytes !== undefined ? { imageMaxBytes } : {}) });
     ERROR_RECORDS.set(this, record);
     Object.assign(this, record);
   }
@@ -67,7 +73,9 @@ export function normalizeModelError(error, context = {}) {
   return new ModelPortError(record.code, {
     stage: record.stage, invocation: record.invocation,
     ...(record.backendId !== undefined ? { backendId: record.backendId } : {}),
-    ...(record.status !== undefined ? { status: record.status } : {}), ...context
+    ...(record.status !== undefined ? { status: record.status } : {}), ...context,
+    ...(record.imageBytes !== undefined ? { imageBytes: record.imageBytes } : {}),
+    ...(record.imageMaxBytes !== undefined ? { imageMaxBytes: record.imageMaxBytes } : {})
   });
 }
 

package/lib/models.js

@@ -13,6 +13,7 @@
  */
 import { CAPABILITIES } from './capability.js';
 import { isDashScopeBaseUrl, selectMediaProtocol } from './provider-protocol.js';
+import { modelRateLimit } from './provider-health.js';
 
 /** 能力 → provider 上的模型字段（保持向后兼容的返回形状） */
 export const CAP_FIELD = {
@@ -119,7 +120,8 @@ export function providerModels(p) {
   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 || {}) });
+    out.push({ id: name, providerId: p.id, ref: modelRef(p.id, name), capabilities: [...caps], ...(extra || {}),
+      ...(modelRateLimit(p, name) ? { rateLimited: true } : {}) });
   };
   // ① 显式 models 数组（带可选 capabilities 覆盖 + verified/source 透传）
   // 该字段一旦存在（含空数组）即为权威声明：用户可明确标记「此供应商没有可用模型」，
@@ -130,7 +132,9 @@ export function providerModels(p) {
       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 } : {};
+      const extra = typeof m === 'object' && m ? { verified: m.verified, source: m.source,
+        ...(m.imageProtocol !== undefined ? { imageProtocol: m.imageProtocol } : {}),
+        ...(m.visionInput !== undefined ? { visionInput: m.visionInput } : {}) } : {};
       push(id, caps, extra);
     }
     return out;
@@ -168,11 +172,12 @@ export function resolvePoolModel(pool, raw, capability) {
 }
 
 /** DSH 与 CLI 共用的候选顺序：分配优先、按池顺序补齐并去重。 */
-export function orderedModels(pool, capability, assignments) {
+export function orderedModels(pool, capability, assignments, { includeRateLimited = false } = {}) {
   const ordered = [];
   const seen = new Set();
   const add = (model) => {
-    if (model && model.capabilities.includes(capability) && !seen.has(model.ref)) {
+    if (model && (includeRateLimited || !model.rateLimited)
+        && model.capabilities.includes(capability) && !seen.has(model.ref)) {
       seen.add(model.ref);
       ordered.push(model);
     }
@@ -210,5 +215,5 @@ export function modelPool(providers) {
 
 /** 从池里挑有某能力的模型（按池顺序） */
 export function pickModel(pool, capability) {
-  return (pool || []).find((m) => m.capabilities.includes(capability)) || null;
+  return (pool || []).find((m) => !m.rateLimited && m.capabilities.includes(capability)) || null;
 }

package/lib/ocr-model-routing.js

@@ -0,0 +1,26 @@
+'use strict';
+/** OCR Host 边界：配置显式传入；同一 operation 从解引用开始覆盖整张长图。 */
+import { buildVisionModelCandidates } from './vision-model-routing.js';
+import { longOcr, normalizeOcrSettings, OCR_BUDGET } from './ocr.js';
+import { createModelOperation } from './model-invoker.js';
+import { ModelPortError, modelPortSnapshot, normalizeModelCall } from './model-port-contract.js';
+import { waitForModelWork } from './model-call-runtime.js';
+import { createVisionInputObserver } from './vision-image-input.js';
+
+export async function runOcrRequest(host, { providers = [], model, image, prepareImage, signal,
+  chunkHeight, overlap, maxDimension, maxInvocations, budget = OCR_BUDGET, onRateLimit }) {
+  const settings = normalizeOcrSettings({ chunkHeight, overlap, maxDimension, maxInvocations });
+  const operation = createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: settings.maxInvocations } });
+  try {
+    const inputs = new Map();
+    const candidates = buildVisionModelCandidates(host, { providers, model, onRateLimit, prepareImages: true,
+      prepareImageRequest: createVisionInputObserver(inputs) });
+    normalizeModelCall(modelPortSnapshot(candidates[0].port), { prompt: 'OCR',
+      image: { bytes: new Uint8Array([0]), mediaType: 'image/png' } }, { budget });
+    const resolved = await waitForModelWork(() => prepareImage ? prepareImage(operation.signal) : image, operation.signal);
+    return await longOcr({ image: resolved, ports: candidates.map(candidate => candidate.port), ...settings, operation, budget, inputs });
+  } catch (error) {
+    if (error instanceof ModelPortError) throw error;
+    throw new ModelPortError('IRIS_MODEL_REQUEST_FAILED', { stage: 'prepare', invocation: 'not_invoked' });
+  } finally { operation.dispose(); }
+}

package/lib/ocr.js

@@ -1,80 +1,126 @@
 'use strict';
-/**
- * Iris 长截图 OCR（阶段 3B）：视觉模型分块文字识别。
- *
- * 调研结论（RESEARCH.md §7）：qwen-vl 视觉模型中文零误差，tesseract.js 准确率差且置信度虚高。
- * 方案：复用阶段 1 VisionBackend 链，sharp 分块（1200px 高 + 120px 重叠避免切断文本行），
- * 逐块 OCR 后拼接。
- *
- * 契约：
- * - chunkHeight 默认 1200，overlap 默认 120
- * - 每块独立调用视觉模型，结果按 y 坐标顺序拼接
- * - 返回全文 + 分块明细 + 元数据
- */
+/** M4 OCR 业务：显式图片字节、Sharp 分块和共享 Vision Ports；无 Host/路径/Store。 */
 import sharp from 'sharp';
-import { askWithBackends } from './vision.js';
-import { imageDimensions } from './pixels.js';
+import { completeVision, VISION_BUDGET } from './vision-core.js';
+import { createModelOperation } from './model-invoker.js';
+import { ModelPortError, modelErrorRecord, modelPortSnapshot, normalizeModelCall } from './model-port-contract.js';
+import { waitForModelWork, modelAbortError } from './model-call-runtime.js';
 
-export class OcrError extends Error {
-  constructor(message) {
-    super(message);
+export const OCR_BUDGET = Object.freeze({ ...VISION_BUDGET });
+export const OCR_LIMITS = Object.freeze({ maxChunks: 32, maxInvocations: 64, maxPixels: 40000000 });
+
+export class OcrError extends ModelPortError {
+  constructor(code = 'IRIS_MODEL_INPUT_INVALID') {
+    super(code, { stage: 'prepare', invocation: 'not_invoked' });
     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）');
+/** 保留既有最小块高及 overlap 钳制；NaN/无限值不进入图片准备或循环。 */
+export function normalizeOcrSettings({ chunkHeight = 1200, overlap = 120, maxDimension = 2048,
+  maxInvocations = OCR_LIMITS.maxInvocations } = {}) {
+  if (typeof chunkHeight !== 'number' || !Number.isFinite(chunkHeight) || chunkHeight <= 0
+      || typeof overlap !== 'number' || !Number.isFinite(overlap)
+      || !Number.isSafeInteger(maxDimension) || maxDimension <= 0 || maxDimension > 4096
+      || !Number.isSafeInteger(maxInvocations) || maxInvocations <= 0 || maxInvocations > OCR_LIMITS.maxInvocations) {
+    throw new OcrError();
   }
-  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;
+  if (!Number.isSafeInteger(ch)) throw new OcrError();
+  return Object.freeze({ chunkHeight: ch, overlap: ov, maxDimension, maxInvocations });
+}
 
-  // 如果宽度超过 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;
+async function imageWork(action, signal) {
+  try { return await waitForModelWork(action, signal); }
+  catch (error) {
+    if (error instanceof ModelPortError) throw error;
+    throw new OcrError();
   }
-  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) });
+/** 一轮共用 operation：准备、全部块和候选切换均消费同一 deadline/次数。 */
+export async function longOcr({ image, ports, chunkHeight, overlap, maxDimension, maxInvocations,
+  signal, operation, budget = OCR_BUDGET, inputs }) {
+  const settings = normalizeOcrSettings({ chunkHeight, overlap, maxDimension, maxInvocations });
+  const op = operation || createModelOperation({ signal, budget: { timeoutMs: budget.timeoutMs, maxInvocations: settings.maxInvocations } });
+  try {
+    if (op.signal.aborted) throw modelAbortError(op.signal);
+    if (op.snapshot().maxInvocations > settings.maxInvocations) throw new OcrError();
+    if (!Array.isArray(ports) || !ports.length) throw new OcrError('IRIS_MODEL_UNAVAILABLE');
+    const input = normalizeModelCall(modelPortSnapshot(ports[0]), { prompt: OCR_PROMPT, image }, { budget }).request.image;
+    const source = Buffer.from(input.bytes);
+    const meta = await imageWork(() => sharp(source, { limitInputPixels: OCR_LIMITS.maxPixels }).metadata(), op.signal);
+    const W = meta.autoOrient?.width || meta.width, H = meta.autoOrient?.height || meta.height;
+    if (!Number.isSafeInteger(W) || !Number.isSafeInteger(H) || W <= 0 || H <= 0
+        || W * H > OCR_LIMITS.maxPixels || (meta.pages || 1) > 1
+        || ({ png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' })[meta.format] !== input.mediaType) {
+      throw new OcrError();
     }
-    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 };
-}
+    const width = Math.min(W, settings.maxDimension);
+    const height = W > width ? Math.max(1, Math.round(H * width / W)) : H;
+    const step = settings.chunkHeight - settings.overlap;
+    const totalChunks = Math.ceil(height / step);
+    if (totalChunks > OCR_LIMITS.maxChunks) throw new OcrError();
+    const img = W > width || meta.orientation > 1 ? await imageWork(() => sharp(source, { limitInputPixels: OCR_LIMITS.maxPixels })
+      .autoOrient().resize(width, height).png().toBuffer(), op.signal) : source;
+    const chunks = [];
+    let stopCode;
+    for (let index = 0; index < totalChunks; index++) {
+      if (op.signal.aborted) throw modelAbortError(op.signal);
+      const y = index * step, h = Math.min(settings.chunkHeight, height - y);
+      const chunk = { index: index + 1, y, height: h, text: '', status: 'skipped' };
+      if (stopCode) {
+        chunk.code = stopCode; chunk.error = modelErrorRecord(new ModelPortError(stopCode)).message;
+        chunks.push(chunk); continue;
+      }
+      try {
+        const snapshot = op.snapshot();
+        if (snapshot.invocations >= Math.min(snapshot.maxInvocations, settings.maxInvocations)) throw new ModelPortError('IRIS_MODEL_CALL_LIMIT');
+        const png = await imageWork(() => sharp(img, { limitInputPixels: OCR_LIMITS.maxPixels })
+          .extract({ left: 0, top: y, width, height: h }).png().toBuffer(), op.signal);
+        const result = await completeVision(ports, { prompt: OCR_PROMPT,
+          image: { bytes: new Uint8Array(png), mediaType: 'image/png' } }, { operation: op, budget });
+        chunk.text = result.text.trim(); chunk.status = 'succeeded';
+        chunk.identity = result.identity; chunk.errors = result.errors;
+        if (inputs?.has(result.identity.backendId)) chunk.input = inputs.get(result.identity.backendId);
+        if (result.usage) chunk.usage = result.usage;
+      } catch (error) {
+        const record = modelErrorRecord(error);
+        if (['IRIS_MODEL_ABORTED', 'IRIS_MODEL_TIMEOUT'].includes(record.code)) throw error;
+        if (op.signal.aborted) throw modelAbortError(op.signal);
+        if (record.code === 'IRIS_MODEL_CALL_LIMIT') stopCode = record.code;
+        else chunk.status = 'failed';
+        chunk.error = record.message; chunk.code = record.code;
+        chunk.errors = Object.freeze([...(error.errors || [record])]);
+      }
+      chunks.push(chunk);
+    }
+    if (op.signal.aborted) throw modelAbortError(op.signal);
+    const successfulChunks = chunks.filter(chunk => chunk.status === 'succeeded').length;
+    const failedChunks = chunks.filter(chunk => chunk.status === 'failed').length;
+    const skippedChunks = totalChunks - successfulChunks - failedChunks;
+    return { status: successfulChunks === totalChunks ? 'complete' : successfulChunks ? 'partial' : 'failed',
+      fullText: chunks.filter(chunk => chunk.status === 'succeeded').map(chunk => `[第${chunk.index}段 y=${chunk.y}] ${chunk.text}`).join('\n'),
+      chunks, totalChunks, successfulChunks, failedChunks, skippedChunks, width, height,
+      sourceWidth: W, sourceHeight: H,
+      invocations: op.snapshot().invocations, ...(stopCode ? { stopCode } : {}) };
+  } finally { if (!operation) op.dispose(); }
+}
+
+/** Agent/工作台共用明确的完成度，不把缺块或未处理误称为完整全文。 */
+export function formatOcrResult(result) {
+  const label = { complete: '完成', partial: '部分完成', failed: '失败' }[result.status];
+  const counts = result.status === 'complete' ? ''
+    : `（成功 ${result.successfulChunks} 块，失败 ${result.failedChunks} 块，未处理 ${result.skippedChunks} 块）`;
+  const stop = result.stopCode === 'IRIS_MODEL_CALL_LIMIT' ? '；已达到本次调用上限' : '';
+  const resized = result.chunks.filter(chunk => chunk.input?.resized);
+  const note = (result.sourceWidth > result.width || resized.length)
+    ? '\n[iris] OCR 输入已缩小，细小文字可能丢失；可提高 OCR 最大宽度或模型输入预算。'
+      + (resized.length ? '\n' + resized.map(chunk => `[第${chunk.index}段] ${chunk.input.source.width}x${chunk.input.source.height} → ${chunk.input.sent.width}x${chunk.input.sent.height}px`).join('\n') : '')
+    : '';
+  return `[iris] 长截图 OCR ${label}：${result.width}x${result.height}px，${result.totalChunks} 块${counts}${stop}\n`
+    + (result.fullText || '（没有完整识别结果）') + note;
+}

package/lib/prompt-optimizer-config.js

@@ -9,8 +9,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { irisHome } from './config.js';
 import { atomicWritePrivate, chmodPrivateFile, privateSibling } from './private-storage.js';
+import { PROMPT_TARGETS } from './prompt-optimizer-core.js';
 
-export const PROMPT_TARGETS = ['general', 'image', 'video', 's2v'];
+export { PROMPT_TARGETS } from './prompt-optimizer-core.js';
 
 const DEFAULT_VALUE = {
   version: 1,