abelien-harness 0.6.0 → 0.6.2

package/README.md

@@ -243,7 +243,7 @@ skill-lint 双向守卫核对声明与实际 import 一致，打包校验再确
 
 | 层 | 篇目 | 一句话 |
 | --- | --- | --- |
-| architecture | [state-machine](docs/architecture/state-machine.md) / [workflow-persistence](docs/architecture/workflow-persistence.md) / [httl](docs/architecture/httl.md) / [host-adapters](docs/architecture/host-adapters.md) / [generate3d](docs/architecture/generate3d.md) / [structure](docs/architecture/structure.md) / [structure-worker](docs/architecture/structure-worker.md) / [question-card](docs/architecture/question-card.md) / [visualization-rsi](docs/architecture/visualization-rsi.md) | 双层 FSM · 定义即数据／实例即文件 · HTTL 协议 · claude-code／codex 双入口收敛 · 声明式 provider + 异步任务引擎 · 外观／结构协作边界 · 问题卡与 ACL 前端协议（contract-ready） · `ab --visual` 可视化与自进化收口 |
+| architecture | [state-machine](docs/architecture/state-machine.md) / [workflow-persistence](docs/architecture/workflow-persistence.md) / [httl](docs/architecture/httl.md) / [host-adapters](docs/architecture/host-adapters.md) / [generate3d](docs/architecture/generate3d.md) / [structure](docs/architecture/structure.md) / [structure-worker](docs/architecture/structure-worker.md) / [structure-worker-protocol](docs/architecture/structure-worker-protocol.md) / [structure-cad-library](docs/architecture/structure-cad-library.md) / [structure-component-fit](docs/architecture/structure-component-fit.md) / [structure-worker-implementation](docs/architecture/structure-worker-implementation.md) / [question-card](docs/architecture/question-card.md) / [visualization-rsi](docs/architecture/visualization-rsi.md) | 双层 FSM · 定义即数据／实例即文件 · HTTL 协议 · claude-code／codex 双入口收敛 · 声明式 provider + 异步任务引擎 · 外观／结构协作边界 · 问题卡与 ACL 前端协议（contract-ready） · `ab --visual` 可视化与自进化收口 |
 | paradigms | [README](docs/paradigms/README.md) + development / testing / evaluation / self-optimization | 场景工件是唯一事实源：测试测零件、评估测整车、优化答归因 |
 | reference | [product-journey](docs/reference/product-journey.md) / [research-notes](docs/reference/research-notes.md) / [verification-method](docs/reference/verification-method.md) | PRD 旅程转译 · 基准研究与 EaaS 方法论 · 验证方法→场景判定器（每篇带 来源/取舍） |
 | mvp | [journey](docs/mvp/journey.md) / [coverage](docs/mvp/coverage.md) | 历史 MVP（已移除的 25 步及真实实录）· 四维覆盖矩阵 + 缺口账本 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abelien-harness",
-  "version": "0.6.0",
+  "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,13 +23,21 @@ 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 自填。
    
    所选候选比例不符时，结果会写明冲突，不会被隐藏。
-5. **交回**：final 结果的 `items` 就是画布网格的格子，`unknowns` 是需要如实展示的缺口。宿主展示的是证据，不是作品已确认。
+5. **交回**：final 结果的 `items` 就是画布网格的格子，`unknowns` 是需要如实展示的缺口，`budget` 说明检索有没有因上限停下。宿主展示的是证据，不是作品已确认。
+
+## 用户换选与排除（K6）
+
+首版之前不向用户提问；用户可以随时在画布或对话里改变参考。处理方式都是对**同一份收集结果**重新提交判断，不重新检索：
+
+- **换成某个候选**（画布「换成这款／就是这款」，或原话点名「参考产品换成 X」）：沿用原 `evidence_id`，把 `identity.chosen_item_id` 改成用户点名的候选，重新调用 `reference.finalize`。比例冲突照常由核验算出并写进 `identity.conflict`，如实展示，不再追问。
+- **不要参考某一条**（「不要参考这个」）：重新提交判断，把该条目放进 `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.1.0",
+  "version": "0.3.0",
   "description": "参考研究域包：按 Agent 的检索计划收集产品识别、逆向资料与相似产品证据（检索、公开页面、主图、用户原图测量），再核验 Agent 的判断，产出 reference-evidence v1；判定码来自确定性检查",
   "requires": [
     "abelien-harness"

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

@@ -2,7 +2,9 @@
   "budget": {
     "images": 0,
     "pages": 1,
-    "queries": 1
+    "queries": 1,
+    "skipped_pages": 0,
+    "skipped_images": 0
   },
   "changeable": [
     "外形",

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

@@ -184,6 +184,8 @@
   "budget": {
     "queries": 1,
     "pages": 2,
-    "images": 1
+    "images": 1,
+    "skipped_pages": 0,
+    "skipped_images": 0
   }
 }

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

@@ -2,7 +2,9 @@
   "budget": {
     "images": 1,
     "pages": 2,
-    "queries": 1
+    "queries": 1,
+    "skipped_pages": 0,
+    "skipped_images": 0
   },
   "changeable": [],
   "depth": "assembly",

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 的收集结果时直接返回，不再检索、不再读取。因此单条检索或页面的临时失败不会因为原样重试而自动恢复；要重试，就改写检索计划（比如换个检索词、改结果数），形成新的请求。
 
@@ -31,14 +31,20 @@
 
 输出 `reference-evidence`，status=collected。`items` 中第一项是 `user_input`，其后每个页面对应一格：识别用途为 `candidate`，逆向用途为 `teardown`，相似用途为 `similar`。读不到的页面状态为 `unavailable`。此时还没有任何 `verdict`。
 
+`budget` 记录本次用量和截断：`queries`、`pages`、`images` 是已检索条数、已读页面数、已抓主图数；`skipped_pages` 是检索到、但因 `max_pages` 没有读取的去重公开页面数，`skipped_images` 是有主图、但因 `max_images` 没有抓取的页面数。宿主据此说明「已达本阶段检索上限」，不能把没读到当作没有。final 结果原样带上收集时的 `budget`。
+
+请求摘要包含证据格式版本（`EVIDENCE_SHAPE`，当前为 2）。旧版本 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` 格 |
@@ -53,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 带判断摘要），收集结果本身不变。
@@ -70,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-evidence.v1.json

@@ -4,7 +4,7 @@
   "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"],
+  "required": ["id", "schema", "status", "intent", "keep", "changeable", "depth", "text", "user_image", "searches", "pages", "images", "items", "unknowns", "budget"],
   "properties": {
     "id": { "type": "string", "pattern": "^ref-[0-9a-f]{16}(-f[0-9a-f]{8})?$" },
     "schema": { "const": "abelien.reference-evidence.v1" },
@@ -35,6 +35,19 @@
     "images": { "type": "array", "items": { "$ref": "#/$defs/image" } },
     "items": { "type": "array", "items": { "$ref": "#/$defs/item" } },
     "unknowns": { "type": "array", "items": { "type": "string" } },
+    "budget": {
+      "description": "本次研究的用量：已检索条数、已读页面数、已抓主图数，以及因计划上限没有读取的去重公开页面数与主图数；宿主据此说明「已达检索上限」，不把没读到当作没有",
+      "type": "object",
+      "required": ["queries", "pages", "images", "skipped_pages", "skipped_images"],
+      "properties": {
+        "queries": { "type": "integer", "minimum": 0 },
+        "pages": { "type": "integer", "minimum": 0 },
+        "images": { "type": "integer", "minimum": 0 },
+        "skipped_pages": { "type": "integer", "minimum": 0 },
+        "skipped_images": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
     "collected_id": { "type": "string", "description": "status=final 时为来源收集结果的 id" },
     "judgement_digest": { "type": "string" },
     "identity": {

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

@@ -15,6 +15,11 @@ export const VERDICT_CODES = Object.freeze(["closest", "ratio_mismatch", "exclud
 export const EVIDENCE_STATUSES = Object.freeze(["collected", "final"]);
 export const KIND_BY_PURPOSE = Object.freeze({ identify: "candidate", teardown: "teardown", similar: "similar" });
 
+/**
+ * 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.
+ */
+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 });
 
@@ -49,6 +54,9 @@ export function validateEvidence(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`);
+  const budget = body.budget, counts = ["queries", "pages", "images", "skipped_pages", "skipped_images"];
+  if (!record(budget) || Object.keys(budget).length !== counts.length
+    || 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");
   if (body.status === "final") {

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,10 +3,10 @@
 // 同一请求重复运行直接返回已有结果，不重复产生检索费用。
 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, reader, imageReader, volc, invalid, stringList, site, validateEvidence } from "./evidence.mjs";
+import { SCHEMA, INTENTS, DEPTHS, PURPOSES, KIND_BY_PURPOSE, LIMITS, EVIDENCE_SHAPE, 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"); }
@@ -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;
 }
@@ -70,12 +76,20 @@ async function pool(list, task, limit = LIMITS.concurrency) {
   return out;
 }
 
-/** Interleave search results so one query cannot use the whole page budget. */
+/**
+ * Interleave search results so one query cannot use the whole page budget. Also counts the distinct public pages the
+ * cap left unread, so the host can say the research stopped at its limit instead of implying nothing else was found.
+ */
 function pageQueue(links, intent, searches, max) {
   const queue = [], seen = new Set();
-  const push = entry => { if (queue.length < max && !seen.has(entry.url)) { seen.add(entry.url); queue.push(entry); } };
+  let skipped = 0;
+  const push = entry => {
+    if (seen.has(entry.url)) return;
+    seen.add(entry.url);
+    if (queue.length < max) queue.push(entry); else skipped++;
+  };
   for (const url of links) push({ url, purpose: intent === "create" ? "similar" : "identify", search_id: null, query: null, search_title: null });
-  for (let rank = 0; queue.length < max; rank++) {
+  for (let rank = 0; ; rank++) {
     let added = false;
     for (const search of searches) {
       const result = search.results[rank];
@@ -85,16 +99,19 @@ function pageQueue(links, intent, searches, max) {
     }
     if (!added) break;
   }
-  return queue;
+  return Object.assign(queue, { skipped });
 }
 
 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" });
-  const requestDigest = digest({ ...request, userImage: request.userImage?.sha256 ?? null });
+  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}`);
-  if (existing?.body?.status === "collected" && existing.body.request_digest === requestDigest) return existing.body;
+  if (existing?.body?.status === "collected" && existing.body.request_digest === requestDigest) {
+    // Never reuse a body that fails today's contract; the kernel then refuses to overwrite it, so the conflict surfaces.
+    try { return validateEvidence(existing.body); } catch { /* fall through: the checkpoint reports the conflict */ }
+  }
 
   const unknowns = [], items = [];
   let userImage = null;
@@ -145,13 +162,15 @@ export async function researchReference({ input, env = {}, fetchImpl, readResour
   });
   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 wanted = pages.filter(page => page.image_url).slice(0, request.plan.max_images);
+  const withImage = pages.filter(page => page.image_url), 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 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"));
@@ -174,6 +193,7 @@ export async function researchReference({ input, env = {}, fetchImpl, readResour
   return validateEvidence({
     id, schema: SCHEMA, status: "collected", request_digest: requestDigest, intent: request.intent, keep: request.keep, changeable: request.changeable,
     depth: request.depth, text: request.text, user_image: userImage, searches, pages, images, items, unknowns,
-    budget: { queries: searches.length, pages: pages.length, images: images.length },
+    budget: { queries: searches.length, pages: pages.length, images: images.length,
+      skipped_pages: queue.skipped, skipped_images: withImage.length - wanted.length },
   });
 }