abelien-harness 0.4.0 → 0.6.0

package/skills/abelien-reference/schemas/reference-evidence.v1.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://git.abelien.cn/abelien/abelienharness/skills/abelien-reference/schemas/reference-evidence.v1.json",
+  "title": "abelien.reference-evidence.v1",
+  "description": "参考研究证据。status=collected 由 reference.research 产出，只有收集结果；status=final 由 reference.finalize 产出，带核验过的识别、相似产品与判定。宿主只展示与转存，不自行改写判定。",
+  "type": "object",
+  "required": ["id", "schema", "status", "intent", "keep", "changeable", "depth", "text", "user_image", "searches", "pages", "images", "items", "unknowns"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^ref-[0-9a-f]{16}(-f[0-9a-f]{8})?$" },
+    "schema": { "const": "abelien.reference-evidence.v1" },
+    "status": { "enum": ["collected", "final"] },
+    "request_digest": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "intent": { "enum": ["restore", "create", "modify"] },
+    "keep": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "changeable": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "depth": { "enum": ["appearance", "assembly", "functional", null] },
+    "text": { "type": "string", "minLength": 1 },
+    "user_image": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["blob_ref", "sha256", "media_type", "measurement"],
+          "properties": {
+            "blob_ref": { "$ref": "#/$defs/blobRef" },
+            "sha256": { "$ref": "#/$defs/sha256" },
+            "media_type": { "const": "image/png" },
+            "measurement": { "$ref": "#/$defs/measurement" }
+          }
+        }
+      ]
+    },
+    "searches": { "type": "array", "items": { "$ref": "#/$defs/search" } },
+    "pages": { "type": "array", "items": { "$ref": "#/$defs/page" } },
+    "images": { "type": "array", "items": { "$ref": "#/$defs/image" } },
+    "items": { "type": "array", "items": { "$ref": "#/$defs/item" } },
+    "unknowns": { "type": "array", "items": { "type": "string" } },
+    "collected_id": { "type": "string", "description": "status=final 时为来源收集结果的 id" },
+    "judgement_digest": { "type": "string" },
+    "identity": {
+      "description": "status=final；还原与改现成时为识别判断，新创时为 null",
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["candidates", "chosen_item_id", "conflict"],
+          "properties": {
+            "candidates": { "type": "array", "items": { "$ref": "#/$defs/candidate" } },
+            "chosen_item_id": { "type": ["string", "null"] },
+            "conflict": { "type": ["string", "null"] }
+          }
+        }
+      ]
+    },
+    "similar": { "type": "array", "items": { "$ref": "#/$defs/similar" } }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "blobRef": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "measurement": {
+      "type": "object",
+      "required": ["status", "method"],
+      "properties": {
+        "status": { "enum": ["measured", "unknown"] },
+        "method": { "const": "silhouette-v1" },
+        "reason": { "type": "string" },
+        "aspect_h_over_w": { "type": "number" },
+        "bbox": { "type": "object" },
+        "background": { "type": "object" }
+      }
+    },
+    "search": {
+      "type": "object",
+      "required": ["id", "purpose", "query", "count", "status", "results"],
+      "properties": {
+        "purpose": { "enum": ["identify", "teardown", "similar"] },
+        "status": { "enum": ["completed", "failed"] },
+        "error_code": { "type": ["string", "null"] },
+        "results": { "type": "array", "items": { "type": "object", "required": ["rank", "url", "title"] } }
+      }
+    },
+    "page": {
+      "type": "object",
+      "required": ["id", "url", "purpose", "status"],
+      "properties": {
+        "status": { "enum": ["read", "unavailable"] },
+        "text_blob_ref": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/blobRef" }] },
+        "excerpt": { "type": "string" },
+        "image_url": { "type": ["string", "null"] }
+      }
+    },
+    "image": {
+      "type": "object",
+      "required": ["id", "url", "page_id", "status"],
+      "properties": {
+        "status": { "enum": ["read", "unavailable"] },
+        "blob_ref": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/blobRef" }] },
+        "media_type": { "type": ["string", "null"] }
+      }
+    },
+    "verdict": {
+      "type": "object",
+      "required": ["code", "basis"],
+      "properties": {
+        "code": { "enum": ["closest", "ratio_mismatch", "excluded", "borrowed", "not_copied", "fits", "envelope"] },
+        "basis": { "type": "string", "minLength": 1 }
+      }
+    },
+    "item": {
+      "type": "object",
+      "description": "画布网格中的一格。verdict 只由 reference.finalize 的确定性检查给出。",
+      "required": ["id", "kind", "title", "role", "source", "image", "verdict", "status", "query"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["user_input", "candidate", "teardown", "spec", "similar"] },
+        "title": { "type": "string" },
+        "role": { "type": "string" },
+        "source": { "oneOf": [{ "type": "null" }, { "type": "object", "required": ["url", "site"], "properties": { "url": { "type": "string" }, "site": { "type": "string" } } }] },
+        "image": { "oneOf": [{ "type": "null" }, { "type": "object", "required": ["blob_ref", "sha256", "media_type"], "properties": { "blob_ref": { "$ref": "#/$defs/blobRef" }, "sha256": { "$ref": "#/$defs/sha256" }, "media_type": { "type": "string" } } }] },
+        "verdict": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/verdict" }] },
+        "status": { "enum": ["pending", "ready", "excluded", "unavailable"] },
+        "query": { "type": ["string", "null"], "description": "pending 时为真实检索词" }
+      }
+    },
+    "candidate": {
+      "type": "object",
+      "required": ["item_id", "name", "dimensions_mm", "quote", "ratio_check"],
+      "properties": {
+        "dimensions_mm": { "description": "页面未给尺寸时为 null，此时比例核对为 unknown", "oneOf": [{ "type": "null" }, { "type": "object", "required": ["width", "height"] }] },
+        "quote": { "type": "object", "required": ["page_id", "text"] },
+        "ratio_check": { "type": "object", "required": ["status"], "properties": { "status": { "enum": ["consistent", "mismatch", "unknown"] } } }
+      }
+    },
+    "similar": {
+      "type": "object",
+      "required": ["item_id", "decision", "why"],
+      "properties": { "decision": { "enum": ["borrow", "skip"] } }
+    }
+  }
+}

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

@@ -0,0 +1,60 @@
+// reference-evidence v1 的唯一字段定义与校验（P2-13.04）。schemas/reference-evidence.v1.json 与本文件的枚举保持一致，
+// 由测试核对；宿主据 schema 与 fixtures 做契约测试，不自行解释字段含义。
+import { createPublicReader } from "../../abelien-harness/scripts/web/public-read.mjs";
+import { createVolcSearch } from "../../abelien-harness/scripts/web/volc.mjs";
+import { redact } from "../../abelien-harness/scripts/web/redact.mjs";
+import { failure, text, record } from "../../abelien-harness/scripts/web/common.mjs";
+
+export const SCHEMA = "abelien.reference-evidence.v1";
+export const INTENTS = Object.freeze(["restore", "create", "modify"]);
+export const DEPTHS = Object.freeze(["appearance", "assembly", "functional"]);
+export const PURPOSES = Object.freeze(["identify", "teardown", "similar"]);
+export const ITEM_KINDS = Object.freeze(["user_input", "candidate", "teardown", "spec", "similar"]);
+export const ITEM_STATUSES = Object.freeze(["pending", "ready", "excluded", "unavailable"]);
+export const VERDICT_CODES = Object.freeze(["closest", "ratio_mismatch", "excluded", "borrowed", "not_copied", "fits", "envelope"]);
+export const EVIDENCE_STATUSES = Object.freeze(["collected", "final"]);
+export const KIND_BY_PURPOSE = Object.freeze({ identify: "candidate", teardown: "teardown", similar: "similar" });
+
+export const LIMITS = Object.freeze({ queries: 6, count: 5, pages: 12, images: 8, links: 5, textChars: 4000, queryChars: 200,
+  pageBytes: 8 * 1024 * 1024, imageBytes: 4 * 1024 * 1024, userImageBytes: 16 * 1024 * 1024, excerptChars: 1200, pageTimeoutMs: 30000, searchTimeoutMs: 30000, concurrency: 4 });
+
+export const CODES = Object.freeze({ transport: "REFERENCE_WEB_TRANSPORT", dns: "REFERENCE_WEB_DNS", access: "REFERENCE_WEB_URL", redirect: "REFERENCE_WEB_PAGE",
+  timeout: "REFERENCE_WEB_TIMEOUT", url: "REFERENCE_WEB_URL", config: "REFERENCE_WEB_CONFIG", readTimeout: "REFERENCE_PUBLIC_READ_TIMEOUT",
+  capability: "REFERENCE_WEB_CAPABILITY", provider: "REFERENCE_WEB_PROVIDER", auth: "REFERENCE_WEB_AUTH", rateLimit: "REFERENCE_WEB_RATE_LIMIT", response: "REFERENCE_WEB_RESPONSE" });
+
+export const reader = createPublicReader({ codes: CODES, userAgent: "Abelien-Reference-Evidence/1", accept: "text/html,text/plain,application/xhtml+xml", decodeCharset: true });
+export const imageReader = createPublicReader({ codes: CODES, userAgent: "Abelien-Reference-Evidence/1", accept: "image/png,image/jpeg,image/webp" });
+export const volc = createVolcSearch({ codes: CODES, ownsError: error => Boolean(error?.code?.startsWith("REFERENCE_WEB_")),
+  redact: (raw, env = {}) => redact(raw, [env.WEB_SEARCH_API_KEY].filter(text)), timeoutMessage: "reference network request timed out" });
+
+export const invalid = message => { throw failure("VALIDATION", message); };
+export const stringList = (value, label, max = 20) => {
+  if (!Array.isArray(value) || value.length > max || value.some(item => !text(item) || item.length > 500)) invalid(`${label} must be a list of up to ${max} non-empty strings`);
+  return value.map(item => item.trim());
+};
+export const site = url => { try { return new URL(url).hostname; } catch { return null; } };
+
+function checkItem(item, index) {
+  const at = `items[${index}]`;
+  if (!record(item) || !text(item.id) || !ITEM_KINDS.includes(item.kind) || !ITEM_STATUSES.includes(item.status) || typeof item.title !== "string" || typeof item.role !== "string") invalid(`${at} has invalid id, kind, status, title or role`);
+  if (item.source !== null && !(record(item.source) && text(item.source.url) && typeof item.source.site === "string")) invalid(`${at}.source must be null or {url, site}`);
+  if (item.image !== null && !(record(item.image) && /^sha256:[0-9a-f]{64}$/.test(item.image.blob_ref ?? "") && /^[0-9a-f]{64}$/.test(item.image.sha256 ?? "") && text(item.image.media_type))) invalid(`${at}.image must be null or {blob_ref, sha256, media_type}`);
+  if (item.verdict !== null && !(record(item.verdict) && VERDICT_CODES.includes(item.verdict.code) && text(item.verdict.basis))) invalid(`${at}.verdict must be null or {code, basis}`);
+  if (item.query !== null && typeof item.query !== "string") invalid(`${at}.query must be null or a string`);
+}
+
+/** Strict structural check of a reference-evidence v1 body; returns the body. */
+export function validateEvidence(body) {
+  if (!record(body) || body.schema !== SCHEMA || !text(body.id) || !EVIDENCE_STATUSES.includes(body.status)) invalid("not a reference-evidence v1 body");
+  if (!INTENTS.includes(body.intent) || (body.depth !== null && !DEPTHS.includes(body.depth))) invalid("intent or depth is invalid");
+  stringList(body.keep, "keep"); stringList(body.changeable, "changeable"); stringList(body.unknowns, "unknowns", 200);
+  for (const name of ["searches", "pages", "images", "items"]) if (!Array.isArray(body[name])) invalid(`${name} must be an array`);
+  body.items.forEach(checkItem);
+  const ids = body.items.map(item => item.id); if (new Set(ids).size !== ids.length) invalid("item ids must be unique");
+  if (body.status === "final") {
+    if (!record(body.identity) && body.identity !== null) invalid("identity must be null or an object");
+    if (!Array.isArray(body.similar)) invalid("similar must be an array");
+    if (!text(body.collected_id)) invalid("final evidence must name its collected_id");
+  }
+  return body;
+}

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

@@ -0,0 +1,116 @@
+// reference.finalize（P2-13.04）：核验 Agent 对已收集证据的判断，生成最终的 reference-evidence。
+// Agent 只给判断与原文引用；引用必须逐字出现在已保存的页面正文里，尺寸数字必须出现在引用中，
+// 比例判定由测量值与规格尺寸确定性计算，不接受 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));
+const percent = value => `${Math.round(value * 1000) / 10}%`;
+
+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(); }
+
+export async function finalizeReference({ input, readResource, readBlob }) {
+  checkKeys(input, ["evidence_id", "identity", "similar", "excluded", "specs"], "input");
+  for (const name of ["similar", "excluded"]) if (input[name] !== undefined && (!Array.isArray(input[name]) || input[name].length > 12)) invalid(`${name} must be up to 12 entries`);
+  if (typeof readResource !== "function" || typeof readBlob !== "function") throw Object.assign(new Error("trusted resource and content readers are required"), { code: "REFERENCE_HOST" });
+  if (!/^reference-evidence:ref-[0-9a-f]{16}$/.test(input.evidence_id ?? "")) invalid("evidence_id must name a collected reference-evidence resource");
+  const resource = await readResource(input.evidence_id);
+  if (resource?.kind !== "reference-evidence" || resource.body?.status !== "collected") invalid("evidence_id must name a collected reference-evidence resource");
+  const collected = validateEvidence(resource.body), body = structuredClone(collected);
+  const pages = new Map(body.pages.map(page => [page.id, page])), items = new Map(body.items.map(item => [item.id, item]));
+  const pageText = new Map();
+  const quoteOn = (quote, label) => {
+    checkKeys(quote, ["page_id", "text"], label);
+    const page = pages.get(quote.page_id);
+    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 (!pageText.get(page.id).includes(normalize(quoted))) invalid(`${label}.text must appear verbatim in page ${page.id}`);
+    return { page_id: page.id, text: quoted };
+  };
+  const itemOf = (id, kinds, label) => {
+    const item = items.get(id);
+    if (!item || !kinds.includes(item.kind)) invalid(`${label} must name an item of kind ${kinds.join(" or ")}`);
+    return item;
+  };
+  const unknowns = [...body.unknowns];
+
+  let identity = null;
+  if (input.identity !== undefined) {
+    checkKeys(input.identity, ["candidates", "chosen_item_id"], "identity");
+    const list = input.identity.candidates ?? [];
+    if (!Array.isArray(list) || list.length > 6) invalid("identity.candidates must be up to 6 entries");
+    const measurement = body.user_image?.measurement ?? null;
+    const candidates = list.map((c, i) => {
+      const label = `identity.candidates[${i}]`;
+      checkKeys(c, ["item_id", "name", "dimensions_mm", "quote"], label);
+      itemOf(c.item_id, ["candidate"], `${label}.item_id`);
+      // 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, ["width", "depth", "height"], `${label}.dimensions_mm`);
+        const keys = ["width", "height", ...(dims.depth === undefined ? [] : ["depth"])], found = numbersIn(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]}`);
+      }
+      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 chosen = input.identity.chosen_item_id ?? null;
+    if (chosen === null ? candidates.length > 0 : !candidates.some(c => c.item_id === chosen)) invalid("identity.chosen_item_id must name one of the candidates (null only when there are none)");
+    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}）`;
+    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 (!pick) unknowns.push("型号未能识别");
+    else 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;
+    }
+    identity = { candidates, chosen_item_id: chosen, conflict };
+  } else if (body.intent !== "create") unknowns.push("没有提交识别判断，型号保持未知");
+
+  const similar = (input.similar ?? []).map((s, i) => {
+    const label = `similar[${i}]`;
+    checkKeys(s, ["item_id", "decision", "borrowed", "why", "not_copied"], label);
+    const item = itemOf(s.item_id, ["similar"], `${label}.item_id`);
+    if (!["borrow", "skip"].includes(s.decision)) invalid(`${label}.decision must be borrow or skip`);
+    const why = words(s.why, `${label}.why`);
+    if (s.decision === "borrow") {
+      const borrowed = words(s.borrowed, `${label}.borrowed`), notCopied = s.not_copied === undefined ? null : words(s.not_copied, `${label}.not_copied`);
+      item.verdict = { code: "borrowed", basis: `借用：${borrowed}；原因：${why}${notCopied ? `；不照搬：${notCopied}` : ""}` };
+      return { item_id: s.item_id, decision: "borrow", borrowed, why, not_copied: notCopied };
+    }
+    item.verdict = { code: "not_copied", basis: why };
+    return { item_id: s.item_id, decision: "skip", borrowed: null, why, not_copied: null };
+  });
+
+  for (const [i, e] of (input.excluded ?? []).entries()) {
+    checkKeys(e, ["item_id", "reason"], `excluded[${i}]`);
+    const item = itemOf(e.item_id, ["candidate", "teardown", "similar"], `excluded[${i}].item_id`);
+    item.status = "excluded"; item.verdict = { code: "excluded", basis: words(e.reason, `excluded[${i}].reason`) };
+  }
+
+  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, ["title", "value", "quote"], `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),
+      source: { url: page.final_url ?? page.url, site: items.get(page.id)?.source?.site ?? "" }, image: null, verdict: null, status: "ready", query: null, quote };
+  });
+
+  const judgementDigest = digest(input);
+  return validateEvidence({ ...body, id: `${body.id}-f${judgementDigest.slice(0, 8)}`, status: "final", collected_id: body.id, judgement_digest: judgementDigest,
+    identity, similar, items: [...items.values(), ...specs.map(({ quote, ...item }) => ({ ...item, role: `${item.role}（引自 ${quote.page_id}）` }))], spec_quotes: specs.map(s => ({ id: s.id, quote: s.quote })),
+    unknowns: [...new Set(unknowns)] });
+}

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

@@ -0,0 +1,62 @@
+// 轮廓测量（P2-13.04）：对单色背景或透明背景的产品图取主体包围盒，得到高宽比。
+// 只在背景可判定时给结论；背景杂乱、全空或解码失败都记为 unknown，并写明原因，不估算。
+import { decodePng } from "./png.mjs";
+
+export const MEASURE_METHOD = "silhouette-v1";
+const COLOR_DELTA = 24, ALPHA_MIN = 32, BORDER_NOISE_MAX = 0.1;
+const median = values => { const sorted = [...values].sort((a, b) => a - b); return sorted[sorted.length >> 1]; };
+
+function borderPixels(width, height) {
+  const out = [];
+  for (let x = 0; x < width; x++) out.push(x, (height - 1) * width + x);
+  for (let y = 1; y < height - 1; y++) out.push(y * width, y * width + width - 1);
+  return out;
+}
+
+/** rgba: 8-bit RGBA samples. Returns { status: "measured", ... } or { status: "unknown", reason }. */
+export function measureSilhouette({ width, height, rgba }) {
+  if (width < 8 || height < 8) return { status: "unknown", reason: "image_too_small", method: MEASURE_METHOD };
+  const border = borderPixels(width, height);
+  const transparentBorder = border.filter(i => rgba[i * 4 + 3] < ALPHA_MIN).length / border.length;
+  let foreground, background;
+  if (transparentBorder > 0.9) {
+    background = { mode: "alpha" };
+    foreground = i => rgba[i * 4 + 3] >= ALPHA_MIN;
+  } else {
+    const bg = [0, 1, 2].map(c => median(border.map(i => rgba[i * 4 + c])));
+    const differs = i => Math.max(Math.abs(rgba[i * 4] - bg[0]), Math.abs(rgba[i * 4 + 1] - bg[1]), Math.abs(rgba[i * 4 + 2] - bg[2])) > COLOR_DELTA || rgba[i * 4 + 3] < ALPHA_MIN;
+    if (border.filter(differs).length / border.length > BORDER_NOISE_MAX) return { status: "unknown", reason: "background_not_uniform", method: MEASURE_METHOD };
+    background = { mode: "color", rgb: bg };
+    foreground = differs;
+  }
+  const rows = new Uint32Array(height), cols = new Uint32Array(width);
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) if (foreground(y * width + x)) { rows[y]++; cols[x]++; }
+  const rowMin = Math.max(2, Math.ceil(width * 0.005)), colMin = Math.max(2, Math.ceil(height * 0.005));
+  const top = rows.findIndex(n => n >= rowMin), bottom = rows.findLastIndex(n => n >= rowMin);
+  const left = cols.findIndex(n => n >= colMin), right = cols.findLastIndex(n => n >= colMin);
+  if (top < 0 || left < 0) return { status: "unknown", reason: "no_foreground", method: MEASURE_METHOD };
+  const w = right - left + 1, h = bottom - top + 1;
+  if (w < 8 || h < 8) return { status: "unknown", reason: "foreground_too_small", method: MEASURE_METHOD };
+  return { status: "measured", method: MEASURE_METHOD, image: { width, height }, bbox: { x: left, y: top, width: w, height: h },
+    aspect_h_over_w: Math.round(h / w * 10000) / 10000, background };
+}
+
+export function measurePng(bytes) {
+  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; }
+  return measureSilhouette(image);
+}
+
+/**
+ * Front-view check: the visible outline of an upright product is width × height.
+ * Returns the relative error between the measured and spec height/width ratios against a tolerance.
+ */
+export const RATIO_TOLERANCE = 0.1;
+export function compareRatio(measurement, dimensions, tolerance = RATIO_TOLERANCE) {
+  if (measurement?.status !== "measured") return { status: "unknown", reason: "no_measurement" };
+  const { width, height } = dimensions ?? {};
+  if (!(width > 0) || !(height > 0)) return { status: "unknown", reason: "no_dimensions" };
+  const spec = height / width, measured = measurement.aspect_h_over_w, error = Math.abs(measured - spec) / spec;
+  return { status: error <= tolerance ? "consistent" : "mismatch", measured, spec: Math.round(spec * 10000) / 10000,
+    relative_error: Math.round(error * 10000) / 10000, tolerance };
+}

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

@@ -0,0 +1,86 @@
+// 零依赖 PNG 解码（P2-13.04）：只用 Node 自带 zlib。支持非隔行的灰度、RGB、调色板、灰度+透明、RGBA，
+// 位深按 PNG 规范（16 位取高字节）；含 tRNS 透明。隔行（Adam7）与超大图明确拒绝，由调用方记为未测量，不编造。
+import { inflateSync } from "node:zlib";
+
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+export const PNG_MAX_PIXELS = 40_000_000;
+export const isPng = bytes => Buffer.isBuffer(bytes) && bytes.length >= 8 && bytes.subarray(0, 8).equals(SIGNATURE);
+
+class PngError extends Error { constructor(reason, message) { super(message); this.code = "PNG_UNSUPPORTED"; this.reason = reason; } }
+const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+const DEPTHS = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+
+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) {
+  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) {
+    const length = bytes.readUInt32BE(offset), type = bytes.toString("latin1", offset + 4, offset + 8);
+    const start = offset + 8, end = start + length;
+    if (end + 4 > bytes.length) throw new PngError("truncated", "PNG chunk is truncated");
+    const data = bytes.subarray(start, end);
+    if (type === "IHDR") {
+      header = { width: data.readUInt32BE(0), height: data.readUInt32BE(4), depth: data[8], color: data[9], interlace: data[12] };
+    } else if (type === "PLTE") palette = data;
+    else if (type === "tRNS") trns = data;
+    else if (type === "IDAT") idat.push(data);
+    else if (type === "IEND") break;
+    offset = end + 4;
+  }
+  if (!header) throw new PngError("truncated", "PNG header is missing");
+  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 (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 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);
+    const prev = y ? lines.subarray((y - 1) * stride, y * stride) : null;
+    for (let i = 0; i < stride; i++) {
+      const left = i >= bpp ? row[i - bpp] : 0, up = prev ? prev[i] : 0, upLeft = prev && i >= bpp ? prev[i - bpp] : 0;
+      const value = filter === 0 ? src[i] : filter === 1 ? src[i] + left : filter === 2 ? src[i] + up
+        : filter === 3 ? src[i] + ((left + up) >> 1) : filter === 4 ? src[i] + paeth(left, up, upLeft) : NaN;
+      if (Number.isNaN(value)) throw new PngError("corrupt", `unknown PNG filter ${filter}`);
+      row[i] = value & 0xff;
+    }
+  }
+  const rgba = new Uint8Array(width * height * 4);
+  const sample = (row, index) => {
+    if (depth === 8) return row[index];
+    if (depth === 16) return row[index * 2];
+    const perByte = 8 / depth, byte = row[Math.floor(index / perByte)], shift = 8 - depth * (index % perByte + 1);
+    return (byte >> shift) & ((1 << depth) - 1);
+  };
+  const scale = depth < 8 && color !== 3 ? 255 / ((1 << depth) - 1) : 1;
+  const transparentGray = trns && color === 0 ? trns.readUInt16BE(0) : null;
+  const transparentRgb = trns && color === 2 ? [trns.readUInt16BE(0), trns.readUInt16BE(2), trns.readUInt16BE(4)] : null;
+  for (let y = 0; y < height; y++) {
+    const row = lines.subarray(y * stride, (y + 1) * stride);
+    for (let x = 0; x < width; x++) {
+      const o = (y * width + x) * 4, n = CHANNELS[color];
+      if (color === 3) {
+        const index = sample(row, x);
+        rgba[o] = palette[index * 3]; rgba[o + 1] = palette[index * 3 + 1]; rgba[o + 2] = palette[index * 3 + 2];
+        rgba[o + 3] = trns && index < trns.length ? trns[index] : 255;
+      } else if (color === 0 || color === 4) {
+        const raw16 = depth === 16 ? row.readUInt16BE(x * n * 2) : sample(row, x * n);
+        const gray = Math.round(sample(row, x * n) * scale);
+        rgba[o] = rgba[o + 1] = rgba[o + 2] = gray;
+        rgba[o + 3] = color === 4 ? sample(row, x * n + 1) : transparentGray !== null && raw16 === transparentGray ? 0 : 255;
+      } else {
+        rgba[o] = sample(row, x * n); rgba[o + 1] = sample(row, x * n + 1); rgba[o + 2] = sample(row, x * n + 2);
+        if (color === 6) rgba[o + 3] = sample(row, x * n + 3);
+        else if (transparentRgb && depth === 8 && rgba[o] === transparentRgb[0] && rgba[o + 1] === transparentRgb[1] && rgba[o + 2] === transparentRgb[2]) rgba[o + 3] = 0;
+        else if (transparentRgb && depth === 16 && row.readUInt16BE(x * 6) === transparentRgb[0] && row.readUInt16BE(x * 6 + 2) === transparentRgb[1] && row.readUInt16BE(x * 6 + 4) === transparentRgb[2]) rgba[o + 3] = 0;
+        else rgba[o + 3] = 255;
+      }
+    }
+  }
+  return { width, height, rgba };
+}