abelien-harness 0.6.1 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abelien-harness",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "npx-installable multi-agent skill harness: generic kernel + pluggable domain packs",
   "type": "module",
   "engines": {

package/skills/abelien-reference/SKILL.md

@@ -23,7 +23,7 @@ compatibility:
 1. **制定检索计划**：依据用户原话和 clarify 的意图判定，写出最多 6 条英文或中文检索，每条注明用途：`identify` 识别、`teardown` 逆向资料、`similar` 相似产品。用户给了链接时，链接优先读取。
 2. **收集**：调用 `reference.research`。它执行 Volc 检索（每条最多 5 个结果）、对公开 HTTPS 页面做安全直读、抓取页面主图、测量用户原图（PNG）的轮廓高宽比，然后把证据保存为 `reference-evidence`（status=collected）。同一请求重复调用直接返回已有结果，不会重复产生检索费用。
 3. **阅读证据并判断**：用 `ab resource get` 读取收集结果，用页面摘录（`excerpt`）和正文判断：哪个候选最可能是用户要的产品、它的尺寸是多少；哪些相似产品可以借用、借用什么、为什么、哪些不照搬；哪些条目应排除。
-4. **核验**：调用 `reference.finalize` 提交判断，生成 status=final 的结果：
+4. **核验**：按 `schemas/reference-judgement.v1.json` 的格式调用 `reference.finalize` 提交判断，生成 status=final 的结果。还原与改现成必须显式给出 `identity.candidates` 和 `chosen_item_id`；定不下型号就把 `chosen_item_id` 设为 `null`，并在 `unidentified_reason` 写明原因。不要用空的 `identity` 试格式。核验规则：
    - 引用必须逐字出现在已保存的页面正文中；
    - 尺寸数字必须出现在引用里；
    - 比例判定由测量值和规格计算得出，不能由 Agent 自填。
@@ -36,8 +36,8 @@ compatibility:
 首版之前不向用户提问；用户可以随时在画布或对话里改变参考。处理方式都是对**同一份收集结果**重新提交判断，不重新检索：
 
 - **换成某个候选**（画布「换成这款／就是这款」，或原话点名「参考产品换成 X」）：沿用原 `evidence_id`，把 `identity.chosen_item_id` 改成用户点名的候选，重新调用 `reference.finalize`。比例冲突照常由核验算出并写进 `identity.conflict`，如实展示，不再追问。
-- **不要参考某一条**（「不要参考这个」）：重新提交判断，把该条目放进 `excluded`，`reason` 写明是用户不采用。被排除的是所选产品时，改选其余候选中比例一致的一个；没有合适的就把 `chosen_item_id` 设为 `null`，并在 `unknowns` 写明型号待定。
-- 这两种情况都属于需求修订：clarify 把用户的选择记成 source=user 的需求，后续阶段按 workspace 规则推进，本包只负责重新提交判断。
+- **不要参考某一条**（「不要参考这个」）：重新提交判断，把该条目放进 `excluded`，`reason` 写明是用户不采用。被排除的是所选产品时，改选其余候选中比例一致的一个；没有合适的就把 `chosen_item_id` 设为 `null`，并在 `unidentified_reason` 写明「用户排除了所选型号，其余候选不合适」。
+- 这两种情况都属于需求修订：clarify 把用户的选择记成 source=user 的需求，后续阶段按 workspace 规则推进，本包只负责重新提交判断。宿主把定稿登记为当前修订的参考来源，同一修订内不再替换，所以先修订需求、再重新提交判断；Agent 自己发现更好的证据时，也不能在同一修订里覆盖已登记的那一份，要如实告诉用户，由用户决定是否换选。
 
 ## 调用
 

package/skills/abelien-reference/domain.json

@@ -1,6 +1,6 @@
 {
   "name": "abelien-reference",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "参考研究域包：按 Agent 的检索计划收集产品识别、逆向资料与相似产品证据（检索、公开页面、主图、用户原图测量），再核验 Agent 的判断，产出 reference-evidence v1；判定码来自确定性检查",
   "requires": [
     "abelien-harness"

package/skills/abelien-reference/references/research-contract.md

@@ -23,7 +23,7 @@
 
 - **检索**：只用宿主环境变量 `WEB_SEARCH_API_KEY` 调 Volc。原始回执先脱敏，再计算摘要。单条检索失败时，该条记为 `failed`，并写明错误码，其余照常进行；缺少 key 时，在发出任何请求之前就以 `REFERENCE_WEB_CONFIG` 失败。
 - **页面**：先读链接，再从各条检索结果中轮流取页面，避免某一条检索占满读取预算。读取只走内核的安全直读：只读公网 HTTPS，每一跳都重新解析并钉住地址，限制重定向次数。每页最多读 8MB，超出时记为 `too_large`、不可用。正文存为内容 blob，资源里只保留前 1200 字的摘录。
-- **主图**：取页面的 `og:image`、`twitter:image` 或 `image_src`。图片同样走钉住地址的直读，每张不超过 4MB，只接受 PNG、JPEG、WebP，原始字节存为内容 blob。其中的 PNG 会额外测量轮廓。
+- **主图**：取页面的 `og:image`、`twitter:image` 或 `image_src`；路径像头像、logo、图标、二维码的（如 `avatar`、`logo`、`icon`、`qrcode`）跳过，改取该页下一个候选。图片同样走钉住地址的直读，每张不超过 4MB，只接受 PNG、JPEG、WebP，原始字节存为内容 blob。其中的 PNG 会额外测量轮廓。
 - **用户原图**：存为内容 blob 并测量轮廓（`silhouette-v1`），得到包围盒和高宽比；背景必须是单色或透明。背景杂乱、没有主体、隔行 PNG、超大图都记为 `unknown`，并写明原因。
 - **幂等**：结果 id 由完整请求摘要（包括原图哈希）派生。已有同 id 的收集结果时直接返回，不再检索、不再读取。因此单条检索或页面的临时失败不会因为原样重试而自动恢复；要重试，就改写检索计划（比如换个检索词、改结果数），形成新的请求。
 
@@ -39,10 +39,12 @@
 
 ### 输入
 
+除 `evidence_id` 外的字段（判断部分）由 `schemas/reference-judgement.v1.json` 定义；该文件自包含、每层都不接受多余字段，宿主可以原样用作工具参数定义。
+
 | 字段 | 规则 |
 | --- | --- |
 | `evidence_id` | 必须指向一份 status=collected 的 `reference-evidence:ref-…` |
-| `identity` | 可选，`{candidates: [{item_id, name, dimensions_mm?: {width, depth?, height}, quote: {page_id, text}}], chosen_item_id}`，最多 6 个候选；只要有候选，`chosen_item_id` 就必须是其中之一。引用是必填的识别依据；页面没有给出尺寸时，可以不填 `dimensions_mm`，此时比例记为未核对 |
+| `identity` | 还原与改现成**必填**，新创**不得提交**。`{candidates: [{item_id, name, dimensions_mm?: {width, depth?, height}, quote: {page_id, text}}], chosen_item_id, unidentified_reason?}`：`candidates` 与 `chosen_item_id` 必须显式给出（空对象、缺字段一律 `VALIDATION`），最多 6 个候选，没有可用候选时为空列表。`chosen_item_id` 是其中一个候选，或为 `null`；为 `null` 时必须写 `unidentified_reason`（1–300 字），写入 `unknowns`「型号未能识别：…」；选定了型号时不得写。引用是必填的识别依据；页面没有给出尺寸时，可以不填 `dimensions_mm`，此时比例记为未核对 |
 | `similar` | 可选，最多 12 条，每条为 `{item_id, decision: borrow / skip, borrowed?, why, not_copied?}`；`borrow` 时必须写明 `borrowed` |
 | `excluded` | 可选，最多 12 条，每条为 `{item_id, reason}` |
 | `specs` | 可选，最多 12 条，每条为 `{title, value, quote}`，生成 `spec` 格 |
@@ -57,7 +59,7 @@
 
 - 正面视角下，比较高宽比：规格比例为 `height / width`，与用户原图的实测值比较，相对误差不超过 10% 记为 `consistent`，否则记为 `mismatch`；没有测量或缺尺寸时记为 `unknown`。
 - 所选候选：比例一致或无法核对时，判定为 `closest`，依据中写明比例情况；比例不符时，判定为 `ratio_mismatch`，并在 `identity.conflict` 中写明。
-- 其他候选：比例不符时判定为 `ratio_mismatch`，其余不加判定，仍保留为候选，供用户切换。
+- 其他候选：比例不符时判定为 `ratio_mismatch`，其余不加判定，仍保留为候选，供用户切换。没有选定型号、却有比例一致的候选时，也写进 `identity.conflict`。
 - 相似产品：`borrow` 判定为 `borrowed`，依据中写明借用了什么、原因、哪些不照搬；`skip` 判定为 `not_copied`。
 - 排除项：状态改为 `excluded`，判定为 `excluded`。
 - 同一份收集结果可以多次提交不同判断，每次生成一份新的 final 结果（id 带判断摘要），收集结果本身不变。
@@ -74,5 +76,7 @@
 ## 宿主责任
 
 - 把上传的图片转成 PNG，写入作品目录中的输入文件，再用 `--input-file` 传入。
+- 定稿工具的参数定义直接用 `schemas/reference-judgement.v1.json`，`evidence_id` 由宿主填入，不让模型猜格式。
+- 定稿结果登记为本次需求修订的参考来源后，不再被同一修订的后续定稿替换；更正走需求修订（用户换选或修改需求），见 SKILL 的 K6。
 - 只展示 `items` 和 `unknowns`；`verdict` 原样展示，不重新解释，也不改写。
 - 第三方图片从内容 blob 转存到私有存储，展示时附来源，不进入图鉴或公开分享。

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

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://git.abelien.cn/abelien/abelienharness/skills/abelien-reference/schemas/reference-judgement.v1.json",
+  "title": "abelien.reference-judgement.v1",
+  "description": "reference.finalize 的判断部分，即输入去掉 evidence_id（由宿主按本轮收集结果填入）。宿主可以把本文件原样用作工具参数定义；字段与 scripts/finalize.mjs 的 JUDGEMENT_FIELDS 一致，由测试保证。引用、尺寸与比例的核验规则见 references/research-contract.md。",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "identity": {
+      "description": "还原（restore）与改现成（modify）必填，新创（create）不得提交。必须显式给出 candidates 与 chosen_item_id；定不下型号时 chosen_item_id 为 null，并在 unidentified_reason 写明原因。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["candidates", "chosen_item_id"],
+      "properties": {
+        "candidates": {
+          "description": "收集结果中 kind=candidate 的条目，最多 6 个；没有可用候选时为空列表。",
+          "type": "array",
+          "maxItems": 6,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["item_id", "name", "quote"],
+            "properties": {
+              "item_id": { "type": "string", "description": "收集结果中 kind=candidate 的条目 id" },
+              "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "型号名称" },
+              "dimensions_mm": {
+                "description": "页面给出的外形尺寸（毫米）；数字必须出现在 quote 里。页面没有尺寸时省略或为 null，比例记为未核对。",
+                "type": ["object", "null"],
+                "additionalProperties": false,
+                "required": ["width", "height"],
+                "properties": {
+                  "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 5000 },
+                  "depth": { "type": "number", "exclusiveMinimum": 0, "maximum": 5000 },
+                  "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 5000 }
+                }
+              },
+              "quote": {
+                "description": "识别依据：逐字出现在该页已保存正文中的一段话（空白会归一）。",
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["page_id", "text"],
+                "properties": {
+                  "page_id": { "type": "string", "description": "读取成功的页面 id，如 p1" },
+                  "text": { "type": "string", "minLength": 1, "maxLength": 500 }
+                }
+              }
+            }
+          }
+        },
+        "chosen_item_id": {
+          "description": "最可能是用户要的那个候选的 item_id；定不下时为 null。",
+          "type": ["string", "null"]
+        },
+        "unidentified_reason": {
+          "description": "chosen_item_id 为 null 时必填：为什么定不下型号（写进 unknowns）；选定了型号时不得提交。",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 300
+        }
+      }
+    },
+    "similar": {
+      "description": "相似产品的取舍，最多 12 条；只能指向 kind=similar 的条目。",
+      "type": "array",
+      "maxItems": 12,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["item_id", "decision", "why"],
+        "properties": {
+          "item_id": { "type": "string" },
+          "decision": { "enum": ["borrow", "skip"] },
+          "borrowed": { "type": "string", "minLength": 1, "maxLength": 300, "description": "decision=borrow 时必填：借用了什么" },
+          "why": { "type": "string", "minLength": 1, "maxLength": 300 },
+          "not_copied": { "type": "string", "minLength": 1, "maxLength": 300, "description": "可选：哪些不照搬" }
+        }
+      }
+    },
+    "excluded": {
+      "description": "排除的条目，最多 12 条；不能排除用户输入（user_input）。",
+      "type": "array",
+      "maxItems": 12,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["item_id", "reason"],
+        "properties": {
+          "item_id": { "type": "string" },
+          "reason": { "type": "string", "minLength": 1, "maxLength": 300 }
+        }
+      }
+    },
+    "specs": {
+      "description": "关键参数，最多 12 条，每条生成一个 spec 格；quote 规则同识别依据。",
+      "type": "array",
+      "maxItems": 12,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["title", "value", "quote"],
+        "properties": {
+          "title": { "type": "string", "minLength": 1, "maxLength": 80 },
+          "value": { "type": "string", "minLength": 1, "maxLength": 200 },
+          "quote": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["page_id", "text"],
+            "properties": {
+              "page_id": { "type": "string" },
+              "text": { "type": "string", "minLength": 1, "maxLength": 500 }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -9,11 +9,18 @@ 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}%`;
 
+/** Allowed fields of the judgement, level by level; schemas/reference-judgement.v1.json states the same and a test keeps them equal. */
+export const JUDGEMENT_FIELDS = Object.freeze({
+  judgement: ["identity", "similar", "excluded", "specs"], identity: ["candidates", "chosen_item_id", "unidentified_reason"],
+  candidate: ["item_id", "name", "dimensions_mm", "quote"], dimensions: ["width", "depth", "height"], quote: ["page_id", "text"],
+  similar: ["item_id", "decision", "borrowed", "why", "not_copied"], excluded: ["item_id", "reason"], spec: ["title", "value", "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(); }
 
 export async function finalizeReference({ input, readResource, readBlob }) {
-  checkKeys(input, ["evidence_id", "identity", "similar", "excluded", "specs"], "input");
+  checkKeys(input, ["evidence_id", ...JUDGEMENT_FIELDS.judgement], "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");
@@ -23,7 +30,7 @@ export async function finalizeReference({ input, readResource, readBlob }) {
   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);
+    checkKeys(quote, JUDGEMENT_FIELDS.quote, 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 ?? "")));
@@ -38,29 +45,37 @@ export async function finalizeReference({ input, readResource, readBlob }) {
   };
   const unknowns = [...body.unknowns];
 
+  // Restore and modify always state what the product is, explicitly: an empty or missing identity is a probe, not a judgement.
   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");
+  if (body.intent === "create") {
+    if (input.identity !== undefined) invalid("identity is only for restore and modify; create has no product to identify");
+  } else {
+    if (input.identity === undefined) invalid("identity is required for restore and modify: candidates and chosen_item_id, or chosen_item_id null with unidentified_reason");
+    checkKeys(input.identity, JUDGEMENT_FIELDS.identity, "identity");
+    if (!Object.hasOwn(input.identity, "candidates") || !Object.hasOwn(input.identity, "chosen_item_id")) invalid("identity must give candidates and chosen_item_id explicitly");
+    const list = input.identity.candidates;
+    if (!Array.isArray(list) || list.length > 6) invalid("identity.candidates must be up to 6 entries (an empty list when nothing matched)");
     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);
+      checkKeys(c, JUDGEMENT_FIELDS.candidate, 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`);
+        checkKeys(dims, JUDGEMENT_FIELDS.dimensions, `${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 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");
+    // Not choosing is a judgement too, so it says why; a chosen product needs no reason.
+    if (chosen === null) unknowns.push(`型号未能识别：${words(input.identity.unidentified_reason, "identity.unidentified_reason (required when chosen_item_id is null)")}`);
+    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}）`;
@@ -68,8 +83,7 @@ export async function finalizeReference({ input, readResource, readBlob }) {
       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}）`);
+    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)}`;
@@ -78,11 +92,11 @@ export async function finalizeReference({ input, readResource, readBlob }) {
       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);
+    checkKeys(s, JUDGEMENT_FIELDS.similar, 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`);
@@ -96,14 +110,14 @@ export async function finalizeReference({ input, readResource, readBlob }) {
   });
 
   for (const [i, e] of (input.excluded ?? []).entries()) {
-    checkKeys(e, ["item_id", "reason"], `excluded[${i}]`);
+    checkKeys(e, JUDGEMENT_FIELDS.excluded, `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}]`);
+    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),
       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/png.mjs

@@ -84,3 +84,31 @@ export function decodePng(bytes) {
   }
   return { width, height, rgba };
 }
+
+/**
+ * Pixel size from the header of a PNG, JPEG or WebP, without decoding; null when the header cannot be read.
+ * Used to drop page furniture (icons, avatars) before it is saved as a product picture.
+ */
+export function imageSize(bytes) {
+  if (!Buffer.isBuffer(bytes)) return null;
+  if (isPng(bytes) && bytes.length >= 24) return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+  if (bytes.length >= 4 && bytes[0] === 0xff && bytes[1] === 0xd8) {
+    let at = 2;
+    while (at + 9 < bytes.length) {
+      if (bytes[at] !== 0xff) return null;
+      const marker = bytes[at + 1];
+      if (marker === 0xff) { at += 1; continue; }
+      if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) { at += 2; continue; }
+      if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) return { width: bytes.readUInt16BE(at + 7), height: bytes.readUInt16BE(at + 5) };
+      at += 2 + bytes.readUInt16BE(at + 2);
+    }
+    return null;
+  }
+  if (bytes.length >= 30 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") {
+    const chunk = bytes.toString("ascii", 12, 16);
+    if (chunk === "VP8 ") return { width: bytes.readUInt16LE(26) & 0x3fff, height: bytes.readUInt16LE(28) & 0x3fff };
+    if (chunk === "VP8L") { const bits = bytes.readUInt32LE(21); return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 }; }
+    if (chunk === "VP8X") return { width: 1 + bytes.readUIntLE(24, 3), height: 1 + bytes.readUIntLE(27, 3) };
+  }
+  return null;
+}

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

@@ -3,8 +3,8 @@
 // 同一请求重复运行直接返回已有结果，不重复产生检索费用。
 import { Buffer } from "node:buffer";
 import { text, record, digest, sha256 } from "../../abelien-harness/scripts/web/common.mjs";
-import { decodeBody } from "../../abelien-harness/scripts/web/public-read.mjs";
-import { isPng } from "./png.mjs";
+import { decodeBody, decodeHtmlEntities } from "../../abelien-harness/scripts/web/public-read.mjs";
+import { isPng, imageSize } from "./png.mjs";
 import { measurePng } from "./measure.mjs";
 import { SCHEMA, INTENTS, DEPTHS, PURPOSES, KIND_BY_PURPOSE, LIMITS, EVIDENCE_SHAPE, reader, imageReader, volc, invalid, stringList, site, validateEvidence } from "./evidence.mjs";
 
@@ -48,15 +48,21 @@ export function validateResearchInput(input) {
 
 const titleOf = html => {
   const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
-  return match ? match[1].replace(/\s+/g, " ").trim().slice(0, 200) : "";
+  // Titles are shown as text, so entities are decoded once here (E5 acceptance showed "Hape Glow &amp; Play").
+  return match ? decodeHtmlEntities(match[1]).replace(/\s+/g, " ").trim().slice(0, 200) : "";
 };
+// Page furniture is not the product: a CSDN author avatar once became a candidate's picture (P2-13 acceptance, E1).
+export const NOT_PRODUCT_IMAGE = /(?:^|[/_.-])(?:avatar|logo|icon|favicon|sprite|badge|profile|userhead|headimg|portrait|qrcode)(?=$|[/_.\d-])/i;
+/** A main image whose shorter side is below this many pixels is an icon or thumbnail, not a product picture. */
+export const MIN_IMAGE_SIDE = 200;
 function mainImageUrl(html, base) {
-  const patterns = [/<meta[^>]+(?:property|name)=["'](?:og:image|og:image:url|twitter:image)["'][^>]*content=["']([^"']+)["']/i,
-    /<meta[^>]+content=["']([^"']+)["'][^>]*(?:property|name)=["'](?:og:image|og:image:url|twitter:image)["']/i,
-    /<link[^>]+rel=["']image_src["'][^>]*href=["']([^"']+)["']/i];
-  for (const pattern of patterns) {
-    const match = pattern.exec(html);
-    if (match) { try { return new URL(match[1].replace(/&amp;/g, "&"), base).href; } catch { return null; } }
+  const patterns = [/<meta[^>]+(?:property|name)=["'](?:og:image|og:image:url|twitter:image)["'][^>]*content=["']([^"']+)["']/gi,
+    /<meta[^>]+content=["']([^"']+)["'][^>]*(?:property|name)=["'](?:og:image|og:image:url|twitter:image)["']/gi,
+    /<link[^>]+rel=["']image_src["'][^>]*href=["']([^"']+)["']/gi];
+  for (const pattern of patterns) for (const match of html.matchAll(pattern)) {
+    let url;
+    try { url = new URL(decodeHtmlEntities(match[1]), base); } catch { continue; }
+    if (!NOT_PRODUCT_IMAGE.test(`${url.hostname}${url.pathname}`)) return url.href;
   }
   return null;
 }
@@ -162,7 +168,9 @@ export async function researchReference({ input, env = {}, fetchImpl, readResour
     try {
       const bytes = await imageReader.fetchPublicBytes(page.image_url, { ...readOptions, maxBytes: LIMITS.imageBytes, contentTypes: ["image/png", "image/jpeg", "image/webp"] });
       Object.assign(entryImage, { status: bytes.status, reason: bytes.reason });
-      if (bytes.status === "read") {
+      const size = bytes.status === "read" ? imageSize(Buffer.from(bytes.raw_base64, "base64")) : null;
+      if (size && Math.min(size.width, size.height) < MIN_IMAGE_SIDE) Object.assign(entryImage, { status: "unavailable", reason: "too_small" });
+      if (entryImage.status === "read") {
         const media = bytes.content_type.split(";")[0].trim();
         entryImage.blob_ref = writeBlob({ media_type: media, base64: bytes.raw_base64 }); entryImage.sha256 = bytes.raw_sha256; entryImage.media_type = media;
         if (media === "image/png") entryImage.measurement = measurePng(Buffer.from(bytes.raw_base64, "base64"));