@mokuyoaxis/dsh-iris 0.1.4 → 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

@@ -0,0 +1,220 @@
+'use strict';
+/** 有限操作内调用控制。只有 deadline timer；无后台任务、网络、配置或存储。 */
+import {
+  ModelPortError, modelErrorRecord, normalizeModelError, modelPortSnapshot,
+  normalizeModelCallOptions, normalizeModelCall, normalizeModelCompletion, normalizeModelOperationOptions
+} from './model-port-contract.js';
+
+const TIMER_MAX_MS = 2147483647;
+const now = () => performance.now();
+
+function scope({ parents = [], timeoutMs, startedAt = now() }) {
+  const controller = new AbortController();
+  const deadline = startedAt + timeoutMs;
+  const listeners = [];
+  let timer;
+  let failureCode;
+  let disposed = false;
+  const abort = (code) => {
+    if (controller.signal.aborted) return;
+    failureCode = code;
+    clearTimeout(timer);
+    controller.abort(new ModelPortError(code, { stage: 'invoke', invocation: 'unknown' }));
+  };
+  const schedule = () => {
+    if (disposed || controller.signal.aborted) return;
+    const remaining = deadline - now();
+    if (remaining <= 0) abort('IRIS_MODEL_TIMEOUT');
+    else timer = setTimeout(schedule, Math.min(TIMER_MAX_MS, Math.ceil(remaining)));
+  };
+  const seen = new Set();
+  for (const parent of parents) {
+    if (!parent.signal || seen.has(parent.signal)) continue;
+    seen.add(parent.signal);
+    const listener = () => abort(parent.code());
+    if (parent.signal.aborted) listener();
+    else {
+      parent.signal.addEventListener('abort', listener, { once: true });
+      listeners.push([parent.signal, listener]);
+    }
+  }
+  schedule();
+  return {
+    signal: controller.signal,
+    get failureCode() { return failureCode; },
+    // 超大 deadline 的浮点舍入不能让端口收到超过原始输入的预算。
+    remaining() { return Math.max(0, Math.min(timeoutMs, deadline - now())); },
+    check(context = {}) {
+      if (!controller.signal.aborted && now() >= deadline) abort('IRIS_MODEL_TIMEOUT');
+      if (controller.signal.aborted) throw new ModelPortError(failureCode, context);
+    },
+    abort,
+    dispose() {
+      disposed = true;
+      clearTimeout(timer);
+      for (const [signal, listener] of listeners) signal.removeEventListener('abort', listener);
+    }
+  };
+}
+
+/** abort 必须已传播到底层；race 只用于不合作的端口有界退出并处理晚到拒绝。 */
+async function waitForCompletion(work, signal) {
+  let listener;
+  let cancelTimer;
+  const interrupted = new Promise((_, reject) => {
+    // 给合作的适配器一个事件循环拍完成清理并报告 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 { clearTimeout(cancelTimer); signal.removeEventListener('abort', listener); }
+}
+
+function candidatePolicy(value) {
+  if (!value || Object.getPrototypeOf(value) !== Object.prototype) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+  const out = { skipUnavailable: false, allowRejected: false, allowEmptyResult: false };
+  for (const [key, field] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+    if (!Object.hasOwn(out, key) || !Object.hasOwn(field, 'value') || typeof field.value !== 'boolean') {
+      throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+    }
+    out[key] = field.value;
+  }
+  if (Object.getOwnPropertySymbols(value).length) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+  return out;
+}
+
+function mayContinue(error, policy) {
+  const { code, invocation } = modelErrorRecord(error);
+  if (invocation === 'not_invoked' && policy.skipUnavailable) {
+    return ['IRIS_MODEL_UNAVAILABLE', 'IRIS_MODEL_INCOMPATIBLE', 'IRIS_MODEL_UNSUPPORTED'].includes(code);
+  }
+  if (invocation === 'rejected' && policy.allowRejected) {
+    return ['IRIS_MODEL_AUTH_FAILED', 'IRIS_MODEL_RATE_LIMITED'].includes(code);
+  }
+  return policy.allowEmptyResult && invocation === 'responded' && code === 'IRIS_MODEL_EMPTY_RESULT';
+}
+
+function operation(options, startedAt) {
+  const total = scope({ timeoutMs: options.budget.timeoutMs, startedAt,
+    parents: options.signal ? [{ signal: options.signal, code: () => 'IRIS_MODEL_ABORTED' }] : [] });
+  let disposed = false;
+  let invocations = 0;
+  let pending = 0;
+
+  const check = () => {
+    if (disposed) throw new ModelPortError('IRIS_MODEL_ABORTED');
+    total.check();
+  };
+
+  const invoke = async (port, request, callOptions) => {
+    const callStartedAt = now();
+    check();
+    const descriptor = modelPortSnapshot(port);
+    const complete = port.complete;
+    if (typeof complete !== 'function') throw new ModelPortError('IRIS_MODEL_INCOMPATIBLE');
+    const local = normalizeModelCallOptions(descriptor, callOptions);
+    const backendId = descriptor.identity.backendId;
+    const child = scope({ timeoutMs: local.budget.timeoutMs, startedAt: callStartedAt, parents: [
+      { signal: total.signal, code: () => total.failureCode },
+      ...(local.signal ? [{ signal: local.signal, code: () => 'IRIS_MODEL_ABORTED' }] : [])
+    ] });
+    let entered = false;
+    let called = false;
+    let refunded = false;
+    try {
+      child.check({ backendId });
+      const input = normalizeModelCall(descriptor, request, local);
+      child.check({ backendId });
+      if (descriptor.availability !== 'available') {
+        throw new ModelPortError(descriptor.availability === 'incompatible' ? 'IRIS_MODEL_INCOMPATIBLE' : 'IRIS_MODEL_UNAVAILABLE', { backendId });
+      }
+      check();
+      if (invocations >= options.budget.maxInvocations) throw new ModelPortError('IRIS_MODEL_CALL_LIMIT', { backendId });
+      // 在调入 complete 之前占用次数，避免并发请求一起穿过最后一个额度。
+      invocations++;
+      pending++;
+      entered = true;
+      const controlledOptions = Object.freeze({ signal: child.signal,
+        budget: Object.freeze({ ...input.options.budget, timeoutMs: Math.max(1, Math.ceil(Math.min(child.remaining(), total.remaining()))) }) });
+      const work = Promise.resolve().then(() => {
+        child.check({ stage: 'invoke', invocation: 'not_invoked', backendId });
+        called = true;
+        return complete.call(port, input.request, controlledOptions);
+      });
+      const result = await waitForCompletion(work, child.signal);
+      child.check({ stage: 'normalize', invocation: 'responded', backendId });
+      const normalized = normalizeModelCompletion(descriptor, result, local.budget);
+      child.check({ stage: 'normalize', invocation: 'responded', backendId });
+      return normalized;
+    } catch (error) {
+      const record = modelErrorRecord(error);
+      // 只有可信契约错误明确说明尚未调用时，才返还预留次数。
+      if (entered && (!called || record.invocation === 'not_invoked' && ['validate', 'prepare', 'invoke'].includes(record.stage))) {
+        invocations--;
+        refunded = true;
+      }
+      if (child.signal.aborted) {
+        if (['IRIS_MODEL_ABORTED', 'IRIS_MODEL_TIMEOUT'].includes(child.failureCode)) total.abort(child.failureCode);
+        throw new ModelPortError(child.failureCode, { stage: entered && !refunded ? 'invoke' : 'validate',
+          invocation: !entered || refunded ? 'not_invoked' : record.invocation === 'responded' ? 'responded' : 'unknown', backendId });
+      }
+      // 输出/协议失败也通知底层停止，结果从不自动转为下一次调用。
+      child.abort(record.code);
+      if (['IRIS_MODEL_ABORTED', 'IRIS_MODEL_TIMEOUT'].includes(record.code)) total.abort(record.code);
+      throw normalizeModelError(error, { backendId });
+    } finally {
+      if (entered) pending--;
+      child.dispose();
+    }
+  };
+
+  return Object.freeze({
+    signal: total.signal,
+    invoke,
+    async runCandidates(ports, request, callOptions, policy = {}) {
+      check();
+      const rules = candidatePolicy(policy);
+      if (!Array.isArray(ports) || !ports.length || [...ports].some(port => !port)) throw new ModelPortError('IRIS_MODEL_INPUT_INVALID');
+      let lastError;
+      for (const port of [...ports]) {
+        check();
+        try { return await invoke(port, request, callOptions); }
+        catch (error) {
+          if (total.signal.aborted || disposed) throw error;
+          check();
+          if (!mayContinue(error, rules)) throw error;
+          lastError = error;
+        }
+      }
+      throw lastError;
+    },
+    snapshot() {
+      return Object.freeze({ invocations, pending, maxInvocations: options.budget.maxInvocations,
+        state: disposed ? 'disposed' : total.failureCode === 'IRIS_MODEL_TIMEOUT' ? 'timed_out' : total.signal.aborted ? 'aborted' : 'active' });
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      total.abort('IRIS_MODEL_ABORTED');
+      total.dispose();
+    }
+  });
+}
+
+/** 一个 OCR/候选等复合业务共用此 scope；调用方在 finally 中 dispose。 */
+export function createModelOperation(options) {
+  const startedAt = now();
+  return operation(normalizeModelOperationOptions(options), startedAt);
+}
+
+/** 默认只允许一次调用，自动释放操作 scope；不运行候选策略。 */
+export async function invokeModel(port, request, options) {
+  const startedAt = now();
+  const descriptor = modelPortSnapshot(port);
+  const local = normalizeModelCallOptions(descriptor, options);
+  const op = operation(normalizeModelOperationOptions({ budget: { timeoutMs: local.budget.timeoutMs, maxInvocations: 1 },
+    ...(local.signal ? { signal: local.signal } : {}) }), startedAt);
+  try { return await op.invoke(port, request, local); }
+  finally { op.dispose(); }
+}