abelien-harness 0.6.1 → 0.6.3

package/package.json

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

package/skills/abelien-harness/scripts/web/public-read.mjs

@@ -127,10 +127,20 @@ export function createPublicReader({ codes, userAgent, accept, decodeCharset = f
         try { addresses = await (lookup ? lookup(url.hostname) : dnsTransport === "doh" ? dohLookup(url.hostname, signal, dnsRequest) : dns.lookup(url.hostname, { all: true, verbatim: true })); }
         catch (err) { if (publicReadFailure(err) || networkError(err)) throw readFailure("dns"); throw err; }
         if (!Array.isArray(addresses) || !addresses.length || addresses.some(item => !publicAddress(item?.address) || isIP(item.address) !== item.family)) throw readFailure("access");
-        connections.push({ url: url.href, tls_hostname: url.hostname, addresses, address: addresses[0].address, family: addresses[0].family });
+        // IPv4 first: a host that publishes AAAA records first (cdn.shopify.com) otherwise hangs until the read timeout on a
+        // network without a working IPv6 route, where curl would have fallen back. A refused or unreachable address moves
+        // on to the next validated one; every address tried was checked above, so the connection stays pinned.
+        const ordered = [...addresses.filter(item => item.family === 4), ...addresses.filter(item => item.family !== 4)];
         let response;
-        try { response = await request(url.href, { address: addresses[0].address, family: addresses[0].family, signal, ...(maxBytes === undefined ? {} : { maxBytes }) }); }
-        catch (error) { if (publicReadFailure(error)) throw error; if (networkError(error)) throw readFailure("transport"); throw error; }
+        for (const [index, pinned] of ordered.entries()) {
+          connections.push({ url: url.href, tls_hostname: url.hostname, addresses, address: pinned.address, family: pinned.family });
+          try { response = await request(url.href, { address: pinned.address, family: pinned.family, signal, ...(maxBytes === undefined ? {} : { maxBytes }) }); break; }
+          catch (error) {
+            if (publicReadFailure(error)) throw error;
+            if (!networkError(error)) throw error;
+            if (index === ordered.length - 1 || signal?.aborted) throw readFailure("transport");
+          }
+        }
         const bytes = Buffer.from(response.bytes ?? []), headers = response.headers ?? {};
         if ([301, 302, 303, 307, 308].includes(response.status)) {
           if (n === maxRedirects || !headers.location) throw readFailure("redirect");

package/skills/abelien-reference/SKILL.md

@@ -21,9 +21,9 @@ compatibility:
 ## 流程
 
 1. **制定检索计划**：依据用户原话和 clarify 的意图判定，写出最多 6 条英文或中文检索，每条注明用途：`identify` 识别、`teardown` 逆向资料、`similar` 相似产品。用户给了链接时，链接优先读取。
-2. **收集**：调用 `reference.research`。它执行 Volc 检索（每条最多 5 个结果）、对公开 HTTPS 页面做安全直读、抓取页面主图、测量用户原图（PNG）的轮廓高宽比，然后把证据保存为 `reference-evidence`（status=collected）。同一请求重复调用直接返回已有结果，不会重复产生检索费用。
+2. **收集**：调用 `reference.research`。它执行 Volc 检索（每条最多 5 个结果）、对公开 HTTPS 页面做安全直读、为每个读到的页面找一张图、测量用户原图（PNG）的轮廓高宽比，然后把证据保存为 `reference-evidence`（status=collected）。图片格式按字节判断，宿主有转换器时统一存成 PNG；保存字节的 sha256 就是图片 id，画布只展示有图片 id 的条目，所以一般不要调小 `max_images`。同一请求重复调用直接返回已有结果，不会重复产生检索费用。
 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 自己发现更好的证据时，也不能在同一修订里覆盖已登记的那一份，要如实告诉用户，由用户决定是否换选。
 
 ## 调用
 
@@ -48,11 +48,11 @@ node "$AB" --workdir <作品目录> resource get reference-evidence:<id>
 node "$AB" --workdir <作品目录> capability run reference.finalize --input-file judgement.json
 ```
 
-参考图（base64 PNG）会超过命令行长度限制，所以输入用 `--input-file` 传入，文件必须放在作品目录内。宿主负责把 JPEG、WebP 等格式先转成 PNG，本包只解码 PNG。字段、上限、错误码和判定规则见[参考研究契约](references/research-contract.md)；数据格式见 `schemas/reference-evidence.v1.json`，样例见 `fixtures/`。
+参考图（base64 PNG）会超过命令行长度限制，所以输入用 `--input-file` 传入，文件必须放在作品目录内。用户原图由宿主先转成 PNG；页面图片由宿主提供的转换器（`ABELIEN_REFERENCE_IMAGE_CONVERTER`）统一转成 PNG，本包只解码 PNG。字段、上限、错误码和判定规则见[参考研究契约](references/research-contract.md)；数据格式见 `schemas/reference-evidence.v1.json`，样例见 `fixtures/`。
 
 ## 边界
 
-- **不编造**：读不到的页面、打不开的链接、测量不了的图片，一律记为不可用或未知，并写入 `unknowns`；其他检索照常继续。
+- **不编造**：读不到的页面、打不开的链接记为不可用（原因在 `pages[].reason`），测量不了的图片记为未知；`unknowns` 只写真正待核实的缺口，不逐条罗列打不开的页面。其他检索照常继续。
 - **第三方图片只作参考**：保存时附带来源和哈希，不进入图鉴、不进入公开分享，也不当作作品资产。
 - **找不到完整的相似产品时**，按声学、供电、交互等子系统分别参考，不硬凑数量。
 - **来源产品的功能不等于本次要实现的功能**：还原时，功能按目标深度由 clarify 写入候选需求。

package/skills/abelien-reference/domain.json

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

package/skills/abelien-reference/fixtures/create.final.json

@@ -50,7 +50,6 @@
       "excerpt": "床头故事机 A 腔体容积 300 mL，40 mm 全频喇叭，电池 2000 mAh。",
       "final_url": "https://shop.example.com/story-a",
       "id": "p1",
-      "image_url": null,
       "purpose": "similar",
       "raw_sha256": "db701b787482d7ae3c2967323df3013d93df7c7e628a801ab091218f55a1b87d",
       "reason": null,
@@ -59,7 +58,8 @@
       "text_blob_ref": "sha256:a871926ca4bf9606ff9abc75f7b5da5a99a41c7535f03e9572095b1a272b32bc",
       "text_sha256": "58a51339bbda6d0a69d726e2768faf47752f8529630a4705e5fe81552e187dff",
       "title": "床头故事机 A",
-      "url": "https://shop.example.com/story-a"
+      "url": "https://shop.example.com/story-a",
+      "image_candidates": []
     }
   ],
   "request_digest": "c26edd6284aed5b521396a1093bc0aeb9ff60d24f2c68d6bcf98a6529bd9c325",

package/skills/abelien-reference/fixtures/restore.collected.json

@@ -78,7 +78,9 @@
       "text_blob_ref": "sha256:a9d6a6d8668de3346efe1d94c1afd76e71faf37bee5a6e55d3a82f9bc60b9bf0",
       "text_sha256": "bae09c2d8ac69290d90e7cf69d7809858b1149a391400d40030037db41896415",
       "excerpt": "小爱音箱 Pro 参数 产品尺寸：118 × 118 × 215 mm，重量 1187 g。",
-      "image_url": "https://img.example.com/pro.png"
+      "image_candidates": [
+        "https://img.example.com/pro.png"
+      ]
     },
     {
       "id": "p2",
@@ -93,7 +95,7 @@
       "text_blob_ref": "sha256:3dd43ad1e906a2e95af747cc8f8386c00b43df981af8b8bafe45bb2d173e7e3c",
       "text_sha256": "2de9e3c9406bd62a2e9eef887fd42008382616377ac49fb751cd5a109f1e9a00",
       "excerpt": "小米AI音箱 规格 尺寸 88 mm × 88 mm × 211.6 mm",
-      "image_url": null
+      "image_candidates": []
     }
   ],
   "images": [
@@ -128,7 +130,8 @@
             255
           ]
         }
-      }
+      },
+      "source_media_type": "image/png"
     }
   ],
   "items": [

package/skills/abelien-reference/fixtures/restore.final.json

@@ -41,7 +41,8 @@
       "reason": null,
       "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11",
       "status": "read",
-      "url": "https://img.example.com/pro.png"
+      "url": "https://img.example.com/pro.png",
+      "source_media_type": "image/png"
     }
   ],
   "intent": "restore",
@@ -122,7 +123,6 @@
       "excerpt": "小爱音箱 Pro 参数 产品尺寸：118 × 118 × 215 mm，重量 1187 g。",
       "final_url": "https://www.mi.example.com/pro/specs",
       "id": "p1",
-      "image_url": "https://img.example.com/pro.png",
       "purpose": "identify",
       "raw_sha256": "109cbac90dd51ef3dddfd21c4a97168a25f097b4211b2146d21669281d06e3b8",
       "reason": null,
@@ -131,13 +131,15 @@
       "text_blob_ref": "sha256:a9d6a6d8668de3346efe1d94c1afd76e71faf37bee5a6e55d3a82f9bc60b9bf0",
       "text_sha256": "bae09c2d8ac69290d90e7cf69d7809858b1149a391400d40030037db41896415",
       "title": "小爱音箱 Pro 参数",
-      "url": "https://www.mi.example.com/pro/specs"
+      "url": "https://www.mi.example.com/pro/specs",
+      "image_candidates": [
+        "https://img.example.com/pro.png"
+      ]
     },
     {
       "excerpt": "小米AI音箱 规格 尺寸 88 mm × 88 mm × 211.6 mm",
       "final_url": "https://www.mi.example.com/gen1/specs",
       "id": "p2",
-      "image_url": null,
       "purpose": "identify",
       "raw_sha256": "c139f165c41dc34c2cd30a816a80d7cbef9ecbda49e7496d46163c8692da33c7",
       "reason": null,
@@ -146,7 +148,8 @@
       "text_blob_ref": "sha256:3dd43ad1e906a2e95af747cc8f8386c00b43df981af8b8bafe45bb2d173e7e3c",
       "text_sha256": "2de9e3c9406bd62a2e9eef887fd42008382616377ac49fb751cd5a109f1e9a00",
       "title": "小米AI音箱 规格",
-      "url": "https://www.mi.example.com/gen1/specs"
+      "url": "https://www.mi.example.com/gen1/specs",
+      "image_candidates": []
     }
   ],
   "request_digest": "40ece5312c4ecbf6f5548d36589de25734706b8a333d22e1a3c32adeb75e09f5",

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

@@ -17,32 +17,40 @@
 | `links` | 最多 5 个公开 HTTPS 链接，不得带凭据或指向内网 |
 | `user_image` | 可选，`{media_type: "image/png", base64}`，不超过 16MB；其他格式由宿主先转成 PNG |
 | `plan.queries` | 最多 6 条，每条为 `{purpose: identify / teardown / similar, query, count?: 1–5}` |
-| `plan.max_pages` / `plan.max_images` | 页面最多读几页（0–12，默认 8）、主图最多抓几张（0–8，默认 6） |
+| `plan.max_pages` / `plan.max_images` | 页面最多读几页（0–12，默认 8）、最多为几个页面找图（0–12，默认等于 `max_pages`，即每个读到的页面都找图）。画布只展示有图的条目，一般不要调小 `max_images` |
 
 ### 执行
 
 - **检索**：只用宿主环境变量 `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`、`itemprop=image`）、`image_src`、JSON-LD 的 `image`、正文中没有标成小于 200 像素的 `<img>`（优先 `data-src`），最多 4 个，记在页面的 `image_candidates`。路径或域名像头像、logo、图标、二维码的（如 `avatar`、`logo`、`icon`、`qrcode`）和 `data:` 地址不算候选；`http` 地址改走 `https`。逐个尝试，第一张读得到、能识别为图片、短边不小于 200 像素的被保存，后面的候选不再读取。
+  - 下载同样走钉住地址的直读，每张最多 8MB、15 秒。响应头只用来粗筛（`image/*` 或二进制流），格式**按字节判断**：PNG、JPEG、GIF、WebP、AVIF、HEIC、BMP、TIFF、ICO、SVG 都能识别；响应头写的格式不算数（CDN 常把 JPEG 标成 `image/png`）。
+  - 宿主提供了转换器（环境变量 `ABELIEN_REFERENCE_IMAGE_CONVERTER`，见「宿主责任」）时，每张图都交给它转成 PNG：长边不超过 1024 像素，不超过 2MB。转换器能解码的格式都能用，PNG 还会测量轮廓。没有转换器时，只保存按字节确认是 PNG、JPEG、WebP 且不超过 2MB 的原图，其他格式记为 `needs_converter`。
+  - 保存的字节存为内容 blob，它的 sha256 就是这张图的 **id**：`images[].sha256` 与引用它的 `items[].image.sha256` 相同，宿主按这个 id 转存和展示。同一张图出现在多个页面时 id 相同。`images[].media_type` 是保存字节的真实格式，`source_media_type` 是下载到的原图格式。
+  - 都没成功时，该页的图片记为 `unavailable`，`reason` 是最后一个候选的失败原因（如 `timeout`、`http_status`、`not_image`、`needs_converter`、`too_small`、`convert_failed`），条目的 `image` 为 `null`。
 - **用户原图**：存为内容 blob 并测量轮廓（`silhouette-v1`），得到包围盒和高宽比；背景必须是单色或透明。背景杂乱、没有主体、隔行 PNG、超大图都记为 `unknown`，并写明原因。
 - **幂等**：结果 id 由完整请求摘要（包括原图哈希）派生。已有同 id 的收集结果时直接返回，不再检索、不再读取。因此单条检索或页面的临时失败不会因为原样重试而自动恢复；要重试，就改写检索计划（比如换个检索词、改结果数），形成新的请求。
 
 ### 输出
 
-输出 `reference-evidence`，status=collected。`items` 中第一项是 `user_input`，其后每个页面对应一格：识别用途为 `candidate`，逆向用途为 `teardown`，相似用途为 `similar`。读不到的页面状态为 `unavailable`。此时还没有任何 `verdict`。
+输出 `reference-evidence`，status=collected。`items` 中第一项是 `user_input`，其后每个页面对应一格：识别用途为 `candidate`，逆向用途为 `teardown`，相似用途为 `similar`。读不到的页面状态为 `unavailable`，原因记在 `pages[].reason`，不再重复写进 `unknowns`；`unknowns` 只放真正待核实的缺口（检索失败或无结果、没读到可识别产品的页面、原图测不了等）。此时还没有任何 `verdict`。
+
+条目的 `image` 只能指向本份证据保存过的图（`images` 中 status=read 的一张，或用户原图），格式只能是 PNG、JPEG、WebP；校验不通过即 `VALIDATION`。
 
 `budget` 记录本次用量和截断：`queries`、`pages`、`images` 是已检索条数、已读页面数、已抓主图数；`skipped_pages` 是检索到、但因 `max_pages` 没有读取的去重公开页面数，`skipped_images` 是有主图、但因 `max_images` 没有抓取的页面数。宿主据此说明「已达本阶段检索上限」，不能把没读到当作没有。final 结果原样带上收集时的 `budget`。
 
-请求摘要包含证据格式版本（`EVIDENCE_SHAPE`，当前为 2）。旧版本 harness 收集的证据保留原 id，不会被复用，也不会被覆盖；同一请求按新格式重新收集，得到新 id。
+请求摘要包含证据格式版本（`EVIDENCE_SHAPE`，当前为 3：图片格式按字节判断、可经宿主转换器统一为 PNG）。旧版本 harness 收集的证据保留原 id，不会被复用，也不会被覆盖；同一请求按新格式重新收集，得到新 id。
 
 ## reference.finalize
 
 ### 输入
 
+除 `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 +65,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 带判断摘要），收集结果本身不变。
@@ -67,12 +75,16 @@
 | 码 | 含义 |
 | --- | --- |
 | `VALIDATION` | 输入不合规、引用不在原文、尺寸不在引用中、条目种类不符 |
-| `REFERENCE_WEB_CONFIG` | 缺少 `WEB_SEARCH_API_KEY`，或 DNS 配置非法 |
+| `REFERENCE_WEB_CONFIG` | 缺少 `WEB_SEARCH_API_KEY`、DNS 配置非法，或配置了转换器但路径不是已存在的绝对路径；都在发出任何请求之前失败 |
 | `REFERENCE_WEB_*` | 单条检索、读取的失败码，只记在对应的检索、页面或图片里，不使整次运行失败 |
 | `REFERENCE_HOST` | 宿主没有提供可信的资源读取、内容读写端口 |
 
 ## 宿主责任
 
 - 把上传的图片转成 PNG，写入作品目录中的输入文件，再用 `--input-file` 传入。
-- 只展示 `items` 和 `unknowns`；`verdict` 原样展示，不重新解释，也不改写。
+- 提供图片转换器，并把它的绝对路径放进环境变量 `ABELIEN_REFERENCE_IMAGE_CONVERTER`（可执行文件，或用当前 Node 运行的 `.mjs`/`.cjs`/`.js` 脚本）。协议：标准输入是下载到的原图字节；参数是 `--max-side <像素> --max-bytes <字节>`；标准输出是一张 PNG，长边和大小都不超过参数，按 EXIF 摆正、动图取第一帧、不带元数据；无法转换时以非零码退出。超过 20 秒、输出不是 PNG 或超出限制都视为失败，该候选跳过。转换器只拿到环境变量 `PATH`。
+- 只展示有图片 id 的条目：按 `items[].image.sha256` 转存和读取；没有图的条目、打不开的页面不上画布网格。
+- 定稿工具的参数定义直接用 `schemas/reference-judgement.v1.json`，`evidence_id` 由宿主填入，不让模型猜格式。
+- 定稿结果登记为本次需求修订的参考来源后，不再被同一修订的后续定稿替换；更正走需求修订（用户换选或修改需求），见 SKILL 的 K6。
+- `verdict` 原样展示，不重新解释，也不改写；`unknowns` 如实展示。
 - 第三方图片从内容 blob 转存到私有存储，展示时附来源，不进入图鉴或公开分享。

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

@@ -99,16 +99,21 @@
         "status": { "enum": ["read", "unavailable"] },
         "text_blob_ref": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/blobRef" }] },
         "excerpt": { "type": "string" },
-        "image_url": { "type": ["string", "null"] }
+        "image_candidates": { "description": "页面上按尝试顺序排列的候选图片地址（分享图、image_src、JSON-LD、正文大图），最多 4 个，已排除头像、logo 等", "type": "array", "items": { "type": "string" } }
       }
     },
     "image": {
+      "description": "每个页面最多一张图：按候选顺序尝试，第一张读到、格式可识别、短边不小于 200 像素的被保存。有宿主转换器时统一保存为 PNG；保存字节的 sha256 就是这张图的 id",
       "type": "object",
       "required": ["id", "url", "page_id", "status"],
       "properties": {
+        "url": { "type": "string", "description": "保存的那张图的地址；都失败时为最后尝试的地址" },
         "status": { "enum": ["read", "unavailable"] },
+        "reason": { "type": ["string", "null"], "description": "unavailable 时最后一个候选的失败原因，如 timeout、not_image、needs_converter、too_small" },
         "blob_ref": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/blobRef" }] },
-        "media_type": { "type": ["string", "null"] }
+        "sha256": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/sha256" }] },
+        "media_type": { "description": "保存字节的真实格式，按字节判断，不取响应头", "enum": ["image/png", "image/jpeg", "image/webp", null] },
+        "source_media_type": { "description": "下载到的原图格式（按字节判断）；转换前的格式，未识别为图片时为 null", "type": ["string", "null"] }
       }
     },
     "verdict": {
@@ -129,7 +134,7 @@
         "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" } } }] },
+        "image": { "description": "这一格的图：sha256 是图片 id，宿主按它转存与读取；没有图时为 null", "oneOf": [{ "type": "null" }, { "type": "object", "required": ["blob_ref", "sha256", "media_type"], "properties": { "blob_ref": { "$ref": "#/$defs/blobRef" }, "sha256": { "$ref": "#/$defs/sha256" }, "media_type": { "enum": ["image/png", "image/jpeg", "image/webp"] } } }] },
         "verdict": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/verdict" }] },
         "status": { "enum": ["pending", "ready", "excluded", "unavailable"] },
         "query": { "type": ["string", "null"], "description": "pending 时为真实检索词" }

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/evidence.mjs

@@ -4,6 +4,7 @@ import { createPublicReader } from "../../abelien-harness/scripts/web/public-rea
 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";
+import { PASS_THROUGH } from "./image-format.mjs";
 
 export const SCHEMA = "abelien.reference-evidence.v1";
 export const INTENTS = Object.freeze(["restore", "create", "modify"]);
@@ -17,18 +18,27 @@ export const KIND_BY_PURPOSE = Object.freeze({ identify: "candidate", teardown:
 
 /**
  * Version of the collected shape, part of every request digest: evidence collected by an older harness (e.g. without
- * budget.skipped_*) keeps its own id and is never reused or overwritten; the same request collects afresh under a new id.
+ * budget.skipped_*, or with an image whose media_type came from the response header) keeps its own id and is never
+ * reused or overwritten; the same request collects afresh under a new id.
  */
-export const EVIDENCE_SHAPE = 2;
-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 EVIDENCE_SHAPE = 3;
+/**
+ * imageBytes caps a download; savedImageBytes and imageSide cap what is saved, so the host can keep every saved image as
+ * it is. imageCandidates is how many pictures of one page are tried before the page is left without one.
+ */
+export const LIMITS = Object.freeze({ queries: 6, count: 5, pages: 12, images: 12, links: 5, textChars: 4000, queryChars: 200,
+  pageBytes: 8 * 1024 * 1024, imageBytes: 8 * 1024 * 1024, savedImageBytes: 2 * 1024 * 1024, imageSide: 1024, imageCandidates: 4,
+  userImageBytes: 16 * 1024 * 1024, excerptChars: 1200, pageTimeoutMs: 30000, imageTimeoutMs: 15000, convertTimeoutMs: 20000, 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" });
+// Prefer formats a host can keep as they are; anything else is still read and the bytes decide what it is.
+export const imageReader = createPublicReader({ codes: CODES, userAgent: "Abelien-Reference-Evidence/1", accept: "image/png,image/jpeg,image/webp,image/*;q=0.8" });
+/** Response types worth reading as a picture; the format itself is then decided by the bytes (image-format.mjs). */
+export const IMAGE_CONTENT_TYPES = Object.freeze(["image/", "application/octet-stream", "binary/octet-stream"]);
 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" });
 
@@ -43,7 +53,7 @@ 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.image !== null && !(record(item.image) && /^sha256:[0-9a-f]{64}$/.test(item.image.blob_ref ?? "") && /^[0-9a-f]{64}$/.test(item.image.sha256 ?? "") && PASS_THROUGH.includes(item.image.media_type))) invalid(`${at}.image must be null or {blob_ref, sha256, media_type: ${PASS_THROUGH.join(" / ")}}`);
   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`);
 }
@@ -59,6 +69,14 @@ export function validateEvidence(body) {
     || counts.some(key => !Number.isSafeInteger(budget[key]) || budget[key] < 0)) invalid(`budget must count ${counts.join(", ")}`);
   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");
+  // An item's picture is one this evidence saved: its sha256 is the picture's id, so it must name a saved image.
+  const saved = new Map(body.images.filter(image => record(image) && image.status === "read").map(image => [image.sha256, image]));
+  if ([...saved.values()].some(image => !PASS_THROUGH.includes(image.media_type) || !/^sha256:[0-9a-f]{64}$/.test(image.blob_ref ?? ""))) invalid("a saved image must have a blob_ref and a stored media_type");
+  if (body.user_image) saved.set(body.user_image.sha256, body.user_image);
+  body.items.forEach((item, index) => {
+    const image = item.image && saved.get(item.image.sha256);
+    if (item.image && (!image || image.blob_ref !== item.image.blob_ref || image.media_type !== item.image.media_type)) invalid(`items[${index}].image must be a saved image of this evidence`);
+  });
   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");

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/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/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

@@ -1,12 +1,14 @@
 // reference.research（P2-13.04）：按 Agent 给出的检索计划执行确定性的收集——Volc 检索、公开页面安全直读、
 // 页面主图抓取、用户原图测量——全部落为证据，不做身份判断。判断由 Agent 读证据后经 reference.finalize 提交并核验。
-// 同一请求重复运行直接返回已有结果，不重复产生检索费用。
+// 同一请求重复运行直接返回已有结果，不重复产生检索费用。页面图片的格式按字节判断，有宿主转换器时统一存成 PNG，
+// 存下的字节的 sha256 就是这张图的 id；宿主只展示有 id 的图。
 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 { decodeBody, decodeHtmlEntities } from "../../abelien-harness/scripts/web/public-read.mjs";
 import { isPng } 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";
+import { hostConverter, prepareImage } from "./image-format.mjs";
+import { SCHEMA, INTENTS, DEPTHS, PURPOSES, KIND_BY_PURPOSE, LIMITS, EVIDENCE_SHAPE, IMAGE_CONTENT_TYPES, reader, imageReader, volc, invalid, stringList, site, validateEvidence } from "./evidence.mjs";
 
 function normalizeLink(value) {
   try { return reader.normalizePublicSourceUrl(value).href; } catch { invalid("links must be public HTTPS URLs without credentials"); }
@@ -39,26 +41,72 @@ export function validateResearchInput(input) {
     return { purpose: q.purpose, query: q.query.trim(), count: q.count ?? LIMITS.count };
   });
   const bounded = (value, max, fallback, label) => { if (value === undefined) return fallback; if (!Number.isSafeInteger(value) || value < 0 || value > max) invalid(`plan.${label} must be 0–${max}`); return value; };
+  // Only pictures are shown on the canvas, so by default every page read gets its picture looked for.
+  const maxPages = bounded(plan.max_pages, LIMITS.pages, 8, "max_pages");
   return {
     intent: input.intent, keep: stringList(input.keep ?? [], "keep"), changeable: stringList(input.changeable ?? [], "changeable"),
     depth: input.depth ?? null, text: input.text.trim(), links: links.map(normalizeLink), userImage,
-    plan: { queries: normalizedQueries, max_pages: bounded(plan.max_pages, LIMITS.pages, 8, "max_pages"), max_images: bounded(plan.max_images, LIMITS.images, 6, "max_images") },
+    plan: { queries: normalizedQueries, max_pages: maxPages, max_images: bounded(plan.max_images, LIMITS.images, maxPages, "max_images") },
   };
 }
 
 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) : "";
 };
-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; } }
+// 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;
+/** Lazy-load stand-ins (Wix `blur_2`, LQIP, spacer GIFs): a blurred or blank copy of the real picture, never the picture. */
+export const PLACEHOLDER_IMAGE = /(?:^|[/_.,=&?-])(?:blur|lqip|placeholder|spacer|blank|lazy|loading)(?=$|[/_.,=&\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;
+const META_IMAGE = /^(?:og:image|og:image:url|og:image:secure_url|twitter:image|twitter:image:src|image)$/i;
+const attr = (tag, name) => {
+  const match = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i").exec(tag);
+  return match ? match[1] ?? match[2] ?? match[3] : null;
+};
+/** JSON-LD `image`: a URL, a list, an ImageObject, or nested in @graph and other objects. */
+function ldImages(node, out, depth = 0) {
+  if (depth > 6 || !node || typeof node !== "object") return;
+  if (Array.isArray(node)) { for (const entry of node) ldImages(entry, out, depth + 1); return; }
+  const take = value => typeof value === "string" ? out.push(value) : Array.isArray(value) ? value.forEach(take)
+    : record(value) && typeof (value.contentUrl ?? value.url) === "string" ? out.push(value.contentUrl ?? value.url) : undefined;
+  take(node.image); take(node.thumbnailUrl);
+  for (const [key, value] of Object.entries(node)) if (key !== "image" && value && typeof value === "object") ldImages(value, out, depth + 1);
+}
+/**
+ * The page's pictures in the order they are tried: share images (og/twitter/itemprop), image_src, JSON-LD, then body
+ * images not declared smaller than the floor. HTTP links are read over HTTPS; page furniture is never tried.
+ */
+export function imageCandidates(html, base) {
+  const raw = [];
+  for (const tag of html.match(/<meta\b[^>]*>/gi) ?? []) {
+    const key = attr(tag, "property") ?? attr(tag, "name") ?? attr(tag, "itemprop");
+    if (key && META_IMAGE.test(key.trim())) raw.push(attr(tag, "content"));
+  }
+  for (const tag of html.match(/<link\b[^>]*>/gi) ?? []) if (/^\s*image_src\s*$/i.test(attr(tag, "rel") ?? "")) raw.push(attr(tag, "href"));
+  for (const block of html.matchAll(/<script[^>]+type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)) {
+    try { ldImages(JSON.parse(block[1]), raw); } catch { /* malformed JSON-LD is skipped */ }
   }
-  return null;
+  for (const tag of html.match(/<img\b[^>]*>/gi) ?? []) {
+    const width = Number(attr(tag, "width")), height = Number(attr(tag, "height"));
+    if ((width && width < MIN_IMAGE_SIDE) || (height && height < MIN_IMAGE_SIDE)) continue;
+    raw.push(attr(tag, "data-src") ?? attr(tag, "data-original") ?? attr(tag, "src"));
+  }
+  const out = [];
+  for (const value of raw) {
+    if (!value || /^\s*data:/i.test(value)) continue;
+    let url;
+    try { url = new URL(decodeHtmlEntities(value.trim()), base); } catch { continue; }
+    if (url.protocol === "http:") url.protocol = "https:";
+    url.hash = "";
+    if (url.protocol !== "https:" || NOT_PRODUCT_IMAGE.test(`${url.hostname}${url.pathname}`) || PLACEHOLDER_IMAGE.test(`${url.pathname}${url.search}`)
+      || out.includes(url.href)) continue;
+    out.push(url.href);
+    if (out.length >= LIMITS.imageCandidates) break;
+  }
+  return out;
 }
 
 /** Run tasks with bounded concurrency; results keep input order. */
@@ -99,6 +147,8 @@ function pageQueue(links, intent, searches, max) {
 export async function researchReference({ input, env = {}, fetchImpl, readResource, writeBlob, ports = {} }) {
   const request = validateResearchInput(input);
   if (typeof writeBlob !== "function" || typeof readResource !== "function") throw Object.assign(new Error("trusted content writer and resource reader are required"), { code: "REFERENCE_HOST" });
+  // A misconfigured converter stops the run before any request, like a missing search key.
+  const convert = ports.convertImage ?? hostConverter(env);
   const requestDigest = digest({ ...request, userImage: request.userImage?.sha256 ?? null, shape: EVIDENCE_SHAPE });
   const id = `ref-${requestDigest.slice(0, 16)}`;
   const existing = await readResource(`reference-evidence:${id}`);
@@ -139,14 +189,14 @@ export async function researchReference({ input, env = {}, fetchImpl, readResour
   // Phase 1: read pages concurrently; results keep queue order.
   const pages = await pool(queue, async (entry, index) => {
     const page = { id: `p${index + 1}`, url: entry.url, purpose: entry.purpose, search_id: entry.search_id, status: "unavailable", reason: null, final_url: null, title: entry.search_title ?? "",
-      raw_sha256: null, text_blob_ref: null, text_sha256: null, excerpt: "", image_url: null };
+      raw_sha256: null, text_blob_ref: null, text_sha256: null, excerpt: "", image_candidates: [] };
     try {
       const read = await reader.fetchPublicPage(entry.url, { ...readOptions, maxBytes: LIMITS.pageBytes });
       const html = decodeBody(Buffer.from(read.raw_base64, "base64"), read.content_type);
       Object.assign(page, { status: read.status, reason: read.reason, final_url: read.final_url, raw_sha256: read.raw_sha256, title: titleOf(html) || page.title });
       if (read.status === "read") {
         page.text_blob_ref = writeBlob({ text: read.text }); page.text_sha256 = read.text_sha256; page.excerpt = read.text.slice(0, LIMITS.excerptChars);
-        page.image_url = read.content_type.includes("html") ? mainImageUrl(html, read.final_url) : null;
+        page.image_candidates = read.content_type.includes("html") ? imageCandidates(html, read.final_url) : [];
       }
     } catch (error) {
       page.reason = reader.publicReadFailure(error)?.stage ?? error?.code ?? "read_failed";
@@ -154,22 +204,28 @@ export async function researchReference({ input, env = {}, fetchImpl, readResour
     }
     return page;
   });
-  for (const page of pages) if (page.status !== "read") unknowns.push(`页面不可用：${page.url}（${page.reason}）`);
-  // Phase 2: main images for the first pages that have one, up to the image budget, fetched concurrently.
-  const withImage = pages.filter(page => page.image_url), wanted = withImage.slice(0, request.plan.max_images);
+  // A page that could not be read is already an unavailable page and item; it is not repeated in unknowns.
+  // Phase 2: one picture per page, up to the image budget, pages fetched concurrently. A page's candidates are tried in
+  // order until one reads as a real picture of at least the floor size; that saved picture's sha256 is its id.
+  const withImage = pages.filter(page => page.image_candidates.length), wanted = withImage.slice(0, request.plan.max_images);
   const images = await pool(wanted, async (page, index) => {
-    const entryImage = { id: `i${index + 1}`, url: page.image_url, page_id: page.id, status: "unavailable", reason: null, blob_ref: null, sha256: null, media_type: null, measurement: null };
-    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 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"));
+    const entryImage = { id: `i${index + 1}`, url: page.image_candidates[0], page_id: page.id, status: "unavailable", reason: null, blob_ref: null, sha256: null,
+      media_type: null, source_media_type: null, measurement: null };
+    for (const url of page.image_candidates) {
+      entryImage.url = url;
+      try {
+        const read = await imageReader.fetchPublicBytes(url, { ...readOptions, timeoutMs: LIMITS.imageTimeoutMs, maxBytes: LIMITS.imageBytes, contentTypes: IMAGE_CONTENT_TYPES });
+        if (read.status !== "read") { entryImage.reason = read.reason; continue; }
+        const ready = await prepareImage(Buffer.from(read.raw_base64, "base64"), { convert, maxSide: LIMITS.imageSide, maxBytes: LIMITS.savedImageBytes, timeoutMs: LIMITS.convertTimeoutMs });
+        entryImage.source_media_type = ready.source ?? null;
+        if (!ready.bytes) { entryImage.reason = ready.reason; continue; }
+        if (Math.min(ready.size.width, ready.size.height) < MIN_IMAGE_SIDE) { entryImage.reason = "too_small"; continue; }
+        return Object.assign(entryImage, { status: "read", reason: null, blob_ref: writeBlob({ media_type: ready.media_type, base64: ready.bytes.toString("base64") }),
+          sha256: sha256(ready.bytes), media_type: ready.media_type, measurement: ready.media_type === "image/png" ? measurePng(ready.bytes) : null });
+      } catch (error) {
+        entryImage.reason = imageReader.publicReadFailure(error)?.stage ?? error?.code ?? "read_failed";
+        if (!imageReader.publicReadFailure(error) && !String(error?.code ?? "").startsWith("REFERENCE_WEB_")) throw error;
       }
-    } catch (error) {
-      entryImage.reason = imageReader.publicReadFailure(error)?.stage ?? error?.code ?? "read_failed";
-      if (!imageReader.publicReadFailure(error) && !String(error?.code ?? "").startsWith("REFERENCE_WEB_")) throw error;
     }
     return entryImage;
   });