abelien-harness 0.6.2 → 0.7.0

package/skills/abelien-reference/scripts/finalize.mjs

@@ -1,12 +1,32 @@
 // reference.finalize（P2-13.04）：核验 Agent 对已收集证据的判断，生成最终的 reference-evidence。
-// Agent 只给判断与原文引用；引用必须逐字出现在已保存的页面正文里，尺寸数字必须出现在引用中，
+// Agent 只给判断与原文引用；引用必须逐字出现在已保存的页面正文里（规范化空白与全半角后比较，至少 8 字），
+// 候选只能引用自己的页面，名称只有出现在引用里才替换标题；尺寸必须以带长度单位的数值出现在同一引用里；
+// 规格值必须能在引用中定位（数值类要求数字与单位同在引用里），否则拒绝。
 // 比例判定由测量值与规格尺寸确定性计算，不接受 Agent 自填的判定。
 import { text, record, digest } from "../../abelien-harness/scripts/web/common.mjs";
 import { compareRatio } from "./measure.mjs";
 import { validateEvidence, invalid } from "./evidence.mjs";
 
-const normalize = value => value.replace(/\s+/g, " ").trim();
-const numbersIn = value => new Set((value.match(/\d+(?:\.\d+)?/g) ?? []).map(Number));
+// NFKC folds full-width digits, letters and punctuation to their half-width forms before whitespace is collapsed.
+const normalize = value => value.normalize("NFKC").replace(/\s+/g, " ").trim();
+export const QUOTE_MIN_CHARS = 8;
+const LENGTH_MM = { mm: 1, "毫米": 1, cm: 10, "厘米": 10, m: 1000, "米": 1000, in: 25.4, inch: 25.4, inches: 25.4, "英寸": 25.4, '"': 25.4, "″": 25.4 };
+const UNIT = /^\s?(毫米|厘米|英寸|毫安时|千克|公斤|毫升|赫兹|分钟|小时|米|克|瓦|伏|升|元|天|["″]|[A-Za-z%°µμ℃]+)/;
+const CHAIN = /^\s*(?:[×xX*✕✖]|by)\s*\d/;
+/**
+ * Numbers in a (normalised) text with the unit written right after each one. In a chain such as
+ * "118 × 118 × 215 mm" every number takes the unit written after the last one.
+ */
+function quantities(value) {
+  const out = [...value.matchAll(/\d+(?:\.\d+)?/g)].map(m => {
+    const rest = value.slice(m.index + m[0].length), chained = CHAIN.test(rest);
+    return { value: Number(m[0]), chained, unit: chained ? null : (UNIT.exec(rest)?.[1].toLowerCase() ?? null) };
+  });
+  for (let i = out.length - 2; i >= 0; i--) if (out[i].chained) out[i].unit = out[i + 1].unit;
+  return out;
+}
+const lengthsMm = value => quantities(value).filter(q => q.unit in LENGTH_MM).map(q => q.value * LENGTH_MM[q.unit]);
+const sameLength = (a, b) => Math.abs(a - b) <= Math.max(0.05, b * 0.002);
 const percent = value => `${Math.round(value * 1000) / 10}%`;
 
 /** Allowed fields of the judgement, level by level; schemas/reference-judgement.v1.json states the same and a test keeps them equal. */
@@ -16,6 +36,24 @@ export const JUDGEMENT_FIELDS = Object.freeze({
   similar: ["item_id", "decision", "borrowed", "why", "not_copied"], excluded: ["item_id", "reason"], spec: ["title", "value", "quote"],
 });
 
+/**
+ * A spec value is a source fact only if its quote shows it: the normalised value is a substring of the quote, or
+ * every number in it appears in the quote with the same unit (lengths compare after conversion to millimetres).
+ * Otherwise the whole judgement is refused; an unverified value is never written as quoted.
+ */
+function verifyValue(value, quoteText, label) {
+  const v = normalize(value), q = normalize(quoteText);
+  if (q.includes(v)) return;
+  const wanted = quantities(v);
+  if (!wanted.length) invalid(`${label}.value must appear in its quote`);
+  const found = quantities(q);
+  for (const item of wanted) {
+    const hit = found.some(f => item.unit in LENGTH_MM && f.unit in LENGTH_MM ? sameLength(f.value * LENGTH_MM[f.unit], item.value * LENGTH_MM[item.unit])
+      : f.value === item.value && (item.unit === null || f.unit === item.unit));
+    if (!hit) invalid(`${label}.value ${item.value}${item.unit ? ` ${item.unit}` : ""} must appear with its unit in its quote`);
+  }
+}
+
 function checkKeys(value, keys, label) { if (!record(value) || Object.keys(value).some(key => !keys.includes(key))) invalid(`${label} has unsupported fields`); }
 function words(value, label, max = 300) { if (!text(value) || value.length > max) invalid(`${label} must be 1–${max} chars`); return value.trim(); }
 
@@ -35,6 +73,7 @@ export async function finalizeReference({ input, readResource, readBlob }) {
     if (!page || page.status !== "read" || !page.text_blob_ref) invalid(`${label}.page_id must name a page that was read`);
     if (!pageText.has(page.id)) pageText.set(page.id, normalize(String(readBlob(page.text_blob_ref)?.text ?? "")));
     const quoted = words(quote.text, `${label}.text`, 500);
+    if ([...normalize(quoted)].length < QUOTE_MIN_CHARS) invalid(`${label}.text must be a quote of at least ${QUOTE_MIN_CHARS} characters`);
     if (!pageText.get(page.id).includes(normalize(quoted))) invalid(`${label}.text must appear verbatim in page ${page.id}`);
     return { page_id: page.id, text: quoted };
   };
@@ -59,17 +98,22 @@ export async function finalizeReference({ input, readResource, readBlob }) {
     const candidates = list.map((c, i) => {
       const label = `identity.candidates[${i}]`;
       checkKeys(c, JUDGEMENT_FIELDS.candidate, label);
-      itemOf(c.item_id, ["candidate"], `${label}.item_id`);
+      const item = itemOf(c.item_id, ["candidate"], `${label}.item_id`);
+      // A candidate stands only on its own page: a quote from another page cannot promote it, and an
+      // unread page (too_large, unavailable) has no quote and therefore cannot become a candidate.
+      if (record(c.quote) && c.quote.page_id !== c.item_id) invalid(`${label}.quote must come from the candidate's own page ${c.item_id}`);
+      if (item.status !== "ready") invalid(`${label}.item_id must name a candidate page that was read`);
       // Dimensions are optional: a page may name the model without giving its size. The quote is always required.
       const dims = c.dimensions_mm === undefined || c.dimensions_mm === null ? null : c.dimensions_mm;
       const quote = quoteOn(c.quote, `${label}.quote`);
       if (dims) {
         checkKeys(dims, JUDGEMENT_FIELDS.dimensions, `${label}.dimensions_mm`);
-        const keys = ["width", "height", ...(dims.depth === undefined ? [] : ["depth"])], found = numbersIn(quote.text);
+        const keys = ["width", "height", ...(dims.depth === undefined ? [] : ["depth"])], found = lengthsMm(normalize(quote.text));
         for (const key of keys) if (!Number.isFinite(dims[key]) || dims[key] <= 0 || dims[key] > 5000) invalid(`${label}.dimensions_mm.${key} must be 0–5000 mm`);
-        for (const key of keys) if (!found.has(dims[key])) invalid(`${label}.quote must contain the ${key} value ${dims[key]}`);
+        for (const key of keys) if (!found.some(length => sameLength(length, dims[key]))) invalid(`${label}.quote must contain the ${key} value ${dims[key]} mm as a length with its unit (mm, cm, m, in)`);
       }
-      return { item_id: c.item_id, name: words(c.name, `${label}.name`, 120), dimensions_mm: dims ? { ...dims } : null, quote, ratio_check: compareRatio(measurement, dims) };
+      const name = words(c.name, `${label}.name`, 120), nameInQuote = normalize(quote.text).toLowerCase().includes(normalize(name).toLowerCase());
+      return { item_id: c.item_id, name, name_in_quote: nameInQuote, display: nameInQuote ? name : item.title, dimensions_mm: dims ? { ...dims } : null, quote, ratio_check: compareRatio(measurement, dims) };
     });
     const chosen = input.identity.chosen_item_id;
     if (chosen !== null && !candidates.some(c => c.item_id === chosen)) invalid("identity.chosen_item_id must name one of the candidates, or be null");
@@ -78,20 +122,21 @@ export async function finalizeReference({ input, readResource, readBlob }) {
     else if (input.identity.unidentified_reason !== undefined) invalid("identity.unidentified_reason is only for chosen_item_id null");
     const pick = candidates.find(c => c.item_id === chosen) ?? null;
     let conflict = null;
-    if (pick?.ratio_check.status === "mismatch") conflict = `所选型号「${pick.name}」与参考图比例不符（实测 ${pick.ratio_check.measured}，规格 ${pick.ratio_check.spec}）`;
+    if (pick?.ratio_check.status === "mismatch") conflict = `所选型号「${pick.display}」与参考图比例不符（实测 ${pick.ratio_check.measured}，规格 ${pick.ratio_check.spec}）`;
     else {
       const others = candidates.filter(c => c !== pick && c.ratio_check.status === "consistent" && c.name !== pick?.name);
-      if (others.length && pick?.ratio_check.status !== "consistent") conflict = `另有比例一致的候选：${others.map(c => c.name).join("、")}`;
+      if (others.length && pick?.ratio_check.status !== "consistent") conflict = `另有比例一致的候选：${others.map(c => c.display).join("、")}`;
     }
     if (pick?.ratio_check.status === "unknown") unknowns.push(`型号比例未核对（${pick.ratio_check.reason}）`);
     for (const c of candidates) {
       const item = items.get(c.item_id), r = c.ratio_check;
       const ratio = r.status === "unknown" ? `比例未核对（${r.reason}）` : `实测高宽比 ${r.measured}，规格 ${r.spec}，相差 ${percent(r.relative_error)}`;
       if (r.status === "mismatch") item.verdict = { code: "ratio_mismatch", basis: ratio };
-      else if (c.item_id === chosen) item.verdict = { code: "closest", basis: `选定为「${c.name}」；${ratio}` };
-      item.title = c.name;
+      else if (c.item_id === chosen) item.verdict = { code: "closest", basis: `选定为「${c.display}」；${ratio}` };
+      // Only a name the quote itself shows may replace the page title shown on the canvas.
+      if (c.name_in_quote) item.title = c.name;
     }
-    identity = { candidates, chosen_item_id: chosen, conflict };
+    identity = { candidates: candidates.map(({ display, ...c }) => c), chosen_item_id: chosen, conflict };
   }
 
   const similar = (input.similar ?? []).map((s, i) => {
@@ -118,8 +163,9 @@ export async function finalizeReference({ input, readResource, readBlob }) {
   if (input.specs !== undefined && (!Array.isArray(input.specs) || input.specs.length > 12)) invalid("specs must be up to 12 entries");
   const specs = (input.specs ?? []).map((s, i) => {
     checkKeys(s, JUDGEMENT_FIELDS.spec, `specs[${i}]`);
-    const quote = quoteOn(s.quote, `specs[${i}].quote`), page = pages.get(quote.page_id);
-    return { id: `sp${i + 1}`, kind: "spec", title: words(s.title, `specs[${i}].title`, 80), role: words(s.value, `specs[${i}].value`, 200),
+    const quote = quoteOn(s.quote, `specs[${i}].quote`), page = pages.get(quote.page_id), value = words(s.value, `specs[${i}].value`, 200);
+    verifyValue(value, quote.text, `specs[${i}]`);
+    return { id: `sp${i + 1}`, kind: "spec", title: words(s.title, `specs[${i}].title`, 80), role: value,
       source: { url: page.final_url ?? page.url, site: items.get(page.id)?.source?.site ?? "" }, image: null, verdict: null, status: "ready", query: null, quote };
   });
 

package/skills/abelien-reference/scripts/image-format.mjs

@@ -0,0 +1,87 @@
+// 参考图片的格式与统一转换（P2-13.06）：格式只按字节识别，不信响应头（E 新创验收：CSDN 的 JPEG 被标成 image/png，
+// 宿主私有存储按格式门禁拒收）。宿主可提供转换器，把任何能解码的图片统一转成 PNG；保存的字节即图片 id（sha256）的来源。
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { Buffer } from "node:buffer";
+import { failure } from "../../abelien-harness/scripts/web/common.mjs";
+import { isPng, imageSize } from "./png.mjs";
+
+/** Formats a host can store and a browser can show as they are; any other format needs the host's converter. */
+export const PASS_THROUGH = Object.freeze(["image/png", "image/jpeg", "image/webp"]);
+/** Absolute path of the host's converter: an executable, or a Node script (.mjs/.cjs/.js) run with this Node. */
+export const CONVERTER_ENV = "ABELIEN_REFERENCE_IMAGE_CONVERTER";
+
+const AVIF_BRANDS = new Set(["avif", "avis"]);
+const HEIF_BRANDS = new Set(["heic", "heix", "hevc", "hevx", "heim", "heis", "hevm", "hevs", "mif1", "msf1"]);
+const SVG_HEAD = /^(?:<\?xml[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*<svg[\s>]/i;
+
+/** The image format the bytes actually are, or null when they are not an image this module knows. */
+export function sniffImage(bytes) {
+  if (!Buffer.isBuffer(bytes) || bytes.length < 12) return null;
+  if (isPng(bytes)) return "image/png";
+  if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+  const head = bytes.toString("latin1", 0, 12);
+  if (head.startsWith("GIF87a") || head.startsWith("GIF89a")) return "image/gif";
+  if (head.startsWith("RIFF") && head.slice(8, 12) === "WEBP") return "image/webp";
+  if (head.slice(4, 8) === "ftyp") {
+    const size = Math.min(bytes.readUInt32BE(0), bytes.length), brands = [head.slice(8, 12)];
+    for (let at = 16; at + 4 <= size; at += 4) brands.push(bytes.toString("latin1", at, at + 4));
+    if (brands.some(brand => AVIF_BRANDS.has(brand))) return "image/avif";
+    if (brands.some(brand => HEIF_BRANDS.has(brand))) return "image/heic";
+    return null;
+  }
+  if (head.startsWith("BM") && bytes.readUInt32LE(2) <= bytes.length + 1024 && bytes.length >= 26) return "image/bmp";
+  if (head.startsWith("II*\0") || head.startsWith("MM\0*")) return "image/tiff";
+  if (bytes.readUInt32BE(0) === 0x00000100 && bytes.readUInt16LE(4) > 0) return "image/x-icon";
+  const textHead = bytes.toString("utf8", 0, Math.min(bytes.length, 4096)).replace(/^/, "").trimStart();
+  return SVG_HEAD.test(textHead) ? "image/svg+xml" : null;
+}
+
+/**
+ * The host's converter as a function, or null when the host provides none. Protocol: the source bytes on stdin;
+ * arguments `--max-side <px> --max-bytes <n>`; a PNG on stdout no larger than either limit (auto-rotated, first frame);
+ * a non-zero exit means the image cannot be converted. A configured path that is not absolute or does not exist fails
+ * the run before any request, like a missing search key.
+ */
+export function hostConverter(env = {}) {
+  const path = env[CONVERTER_ENV];
+  if (path === undefined || path === "") return null;
+  if (typeof path !== "string" || !isAbsolute(path) || !existsSync(path)) throw failure("REFERENCE_WEB_CONFIG", `${CONVERTER_ENV} must be the absolute path of an existing converter`);
+  const script = /\.(?:mjs|cjs|js)$/.test(path);
+  return (bytes, { maxSide, maxBytes, timeoutMs }) => new Promise(resolve => {
+    const child = spawn(script ? process.execPath : path, [...(script ? [path] : []), "--max-side", String(maxSide), "--max-bytes", String(maxBytes)],
+      { stdio: ["pipe", "pipe", "ignore"], env: { PATH: env.PATH ?? process.env.PATH ?? "" } });
+    const chunks = []; let size = 0, settled = false;
+    const finish = result => { if (settled) return; settled = true; clearTimeout(timer); child.kill("SIGKILL"); resolve(result); };
+    const timer = setTimeout(() => finish({ ok: false, reason: "convert_timeout" }), timeoutMs);
+    child.stdout.on("data", chunk => {
+      size += chunk.length;
+      if (size > maxBytes) finish({ ok: false, reason: "convert_too_large" }); else chunks.push(chunk);
+    });
+    child.on("error", () => finish({ ok: false, reason: "convert_failed" }));
+    child.on("close", code => finish(code === 0 ? { ok: true, bytes: Buffer.concat(chunks) } : { ok: false, reason: "convert_failed" }));
+    child.stdin.on("error", () => { /* the converter may exit before reading everything; its exit code decides */ });
+    child.stdin.end(bytes);
+  });
+}
+
+/**
+ * One fetched image made ready to save. With a converter every format becomes a PNG within the limits; without one,
+ * only PNG, JPEG and WebP pass through unchanged. Returns {bytes, media_type, size} or {reason}.
+ */
+export async function prepareImage(raw, { convert, maxSide, maxBytes, timeoutMs }) {
+  const source = sniffImage(raw);
+  if (!source) return { reason: "not_image" };
+  let bytes = raw, mediaType = source;
+  if (convert) {
+    const converted = await convert(raw, { maxSide, maxBytes, timeoutMs });
+    if (!converted.ok) return { reason: converted.reason, source };
+    if (!isPng(converted.bytes)) return { reason: "convert_invalid", source };
+    bytes = converted.bytes; mediaType = "image/png";
+  } else if (!PASS_THROUGH.includes(source)) return { reason: "needs_converter", source };
+  const size = imageSize(bytes);
+  if (!size || !size.width || !size.height) return { reason: "unreadable", source };
+  if (bytes.length > maxBytes || (convert && Math.max(size.width, size.height) > maxSide)) return { reason: convert ? "convert_invalid" : "too_large", source };
+  return { bytes, media_type: mediaType, source, size };
+}

package/skills/abelien-reference/scripts/measure.mjs

@@ -41,9 +41,11 @@ export function measureSilhouette({ width, height, rgba }) {
     aspect_h_over_w: Math.round(h / w * 10000) / 10000, background };
 }
 
-export function measurePng(bytes) {
+/** options.maxPixels lowers the pixel cap (never above PNG_MAX_PIXELS); a larger image is "png_too_large", not decoded. */
+export function measurePng(bytes, options = {}) {
   let image;
-  try { image = decodePng(bytes); } catch (error) { if (error?.code === "PNG_UNSUPPORTED") return { status: "unknown", reason: `png_${error.reason}`, method: MEASURE_METHOD }; throw error; }
+  // decodePng reports every failure (including zlib limits) as PNG_UNSUPPORTED; that image is simply not measurable.
+  try { image = decodePng(bytes, options); } catch (error) { return { status: "unknown", reason: `png_${error?.code === "PNG_UNSUPPORTED" ? error.reason : "corrupt"}`, method: MEASURE_METHOD }; }
   return measureSilhouette(image);
 }
 

package/skills/abelien-reference/scripts/png.mjs

@@ -1,5 +1,6 @@
 // 零依赖 PNG 解码（P2-13.04）：只用 Node 自带 zlib。支持非隔行的灰度、RGB、调色板、灰度+透明、RGBA，
 // 位深按 PNG 规范（16 位取高字节）；含 tRNS 透明。隔行（Adam7）与超大图明确拒绝，由调用方记为未测量，不编造。
+// 解压按 IHDR 算出的确切长度设上限（防解压炸弹），解压结果长度必须恰好等于该值；任何异常都归入 PngError。
 import { inflateSync } from "node:zlib";
 
 const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
@@ -13,7 +14,15 @@ const DEPTHS = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6
 function paeth(a, b, c) { const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c); return pa <= pb && pa <= pc ? a : pb <= pc ? b : c; }
 
 /** Returns { width, height, rgba } with 8-bit RGBA samples. Throws PngError with a stable reason. */
-export function decodePng(bytes) {
+export function decodePng(bytes, { maxPixels = PNG_MAX_PIXELS } = {}) {
+  try { return decode(bytes, maxPixels); } catch (error) {
+    if (error instanceof PngError) throw error;
+    // zlib, RangeError or a malformed chunk read: the image is not measurable; never let it escape.
+    throw new PngError(error?.code === "ERR_BUFFER_TOO_LARGE" || error instanceof RangeError ? "too_large" : "corrupt", `PNG cannot be decoded: ${error?.message ?? error}`);
+  }
+}
+
+function decode(bytes, maxPixels) {
   if (!isPng(bytes)) throw new PngError("not_png", "not a PNG file");
   let offset = 8, header = null; const idat = []; let palette = null, trns = null;
   while (offset + 8 <= bytes.length) {
@@ -33,11 +42,18 @@ export function decodePng(bytes) {
   const { width, height, depth, color, interlace } = header;
   if (!CHANNELS[color] || !DEPTHS[color].includes(depth)) throw new PngError("unsupported_format", `PNG color type ${color} depth ${depth} is not supported`);
   if (interlace !== 0) throw new PngError("interlaced", "interlaced PNG is not supported");
-  if (!width || !height || width * height > PNG_MAX_PIXELS) throw new PngError("too_large", "PNG dimensions are out of range");
+  if (!width || !height || width * height > Math.min(maxPixels, PNG_MAX_PIXELS)) throw new PngError("too_large", "PNG dimensions are out of range");
   if (color === 3 && !palette) throw new PngError("truncated", "palette PNG has no PLTE");
-  const raw = inflateSync(Buffer.concat(idat));
   const bitsPerPixel = CHANNELS[color] * depth, stride = Math.ceil(width * bitsPerPixel / 8), bpp = Math.max(1, bitsPerPixel >> 3);
-  if (raw.length < height * (stride + 1)) throw new PngError("truncated", "PNG image data is truncated");
+  const expected = height * (stride + 1);
+  let raw;
+  try { raw = inflateSync(Buffer.concat(idat), { maxOutputLength: expected }); }
+  catch (error) {
+    if (error?.code === "ERR_BUFFER_TOO_LARGE" || error instanceof RangeError) throw new PngError("too_large", "PNG image data inflates beyond its declared size");
+    throw new PngError(error?.code === "Z_BUF_ERROR" ? "truncated" : "corrupt", "PNG image data is not a valid zlib stream");
+  }
+  if (raw.length < expected) throw new PngError("truncated", "PNG image data is truncated");
+  if (raw.length !== expected) throw new PngError("too_large", "PNG image data is longer than its declared size");
   const lines = Buffer.alloc(height * stride);
   for (let y = 0; y < height; y++) {
     const filter = raw[y * (stride + 1)], src = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1)), row = lines.subarray(y * stride, (y + 1) * stride);