abelien-harness 0.4.0 → 0.6.0

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

@@ -0,0 +1,102 @@
+{
+  "budget": {
+    "images": 0,
+    "pages": 1,
+    "queries": 1
+  },
+  "changeable": [
+    "外形",
+    "尺寸"
+  ],
+  "depth": null,
+  "id": "ref-c26edd6284aed5b5-f89f84f29",
+  "images": [],
+  "intent": "create",
+  "items": [
+    {
+      "id": "u1",
+      "image": null,
+      "kind": "user_input",
+      "query": null,
+      "role": "做一个放在床头、能讲睡前故事的小音箱",
+      "source": null,
+      "status": "ready",
+      "title": "你的输入",
+      "verdict": null
+    },
+    {
+      "id": "p1",
+      "image": null,
+      "kind": "similar",
+      "query": "bedside story speaker teardown",
+      "role": "相似产品",
+      "source": {
+        "site": "shop.example.com",
+        "url": "https://shop.example.com/story-a"
+      },
+      "status": "ready",
+      "title": "床头故事机 A",
+      "verdict": {
+        "code": "borrowed",
+        "basis": "借用：300 mL 声腔与 40 mm 全频喇叭；原因：体积与床头摆放相近；不照搬：外观与按键布局"
+      }
+    }
+  ],
+  "keep": [],
+  "pages": [
+    {
+      "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,
+      "search_id": "s1",
+      "status": "read",
+      "text_blob_ref": "sha256:a871926ca4bf9606ff9abc75f7b5da5a99a41c7535f03e9572095b1a272b32bc",
+      "text_sha256": "58a51339bbda6d0a69d726e2768faf47752f8529630a4705e5fe81552e187dff",
+      "title": "床头故事机 A",
+      "url": "https://shop.example.com/story-a"
+    }
+  ],
+  "request_digest": "c26edd6284aed5b521396a1093bc0aeb9ff60d24f2c68d6bcf98a6529bd9c325",
+  "schema": "abelien.reference-evidence.v1",
+  "searches": [
+    {
+      "count": 3,
+      "error_code": null,
+      "id": "s1",
+      "purpose": "similar",
+      "query": "bedside story speaker teardown",
+      "receipt_sha256": "b4f07afb377bbf9556aef08b61cebb2bf0264df8924f91b712227186cd7157bc",
+      "request_id": "req-[redacted]",
+      "results": [
+        {
+          "rank": 1,
+          "snippet": "",
+          "title": "Story box A",
+          "url": "https://shop.example.com/story-a"
+        }
+      ],
+      "status": "completed"
+    }
+  ],
+  "status": "final",
+  "text": "做一个放在床头、能讲睡前故事的小音箱",
+  "unknowns": [],
+  "user_image": null,
+  "collected_id": "ref-c26edd6284aed5b5",
+  "judgement_digest": "89f84f293a6781fed8f80ea7f03d57da892c67f70bfdd836003421f88b2b0730",
+  "identity": null,
+  "similar": [
+    {
+      "item_id": "p1",
+      "decision": "borrow",
+      "borrowed": "300 mL 声腔与 40 mm 全频喇叭",
+      "why": "体积与床头摆放相近",
+      "not_copied": "外观与按键布局"
+    }
+  ],
+  "spec_quotes": []
+}

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

@@ -0,0 +1,189 @@
+{
+  "id": "ref-40ece5312c4ecbf6",
+  "schema": "abelien.reference-evidence.v1",
+  "status": "collected",
+  "request_digest": "40ece5312c4ecbf6f5548d36589de25734706b8a333d22e1a3c32adeb75e09f5",
+  "intent": "restore",
+  "keep": [
+    "外形尺寸与比例"
+  ],
+  "changeable": [],
+  "depth": "assembly",
+  "text": "帮我根据图片还原小爱音箱",
+  "user_image": {
+    "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+    "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11",
+    "media_type": "image/png",
+    "measurement": {
+      "status": "measured",
+      "method": "silhouette-v1",
+      "image": {
+        "width": 400,
+        "height": 600
+      },
+      "bbox": {
+        "x": 62,
+        "y": 49,
+        "width": 276,
+        "height": 502
+      },
+      "aspect_h_over_w": 1.8188,
+      "background": {
+        "mode": "color",
+        "rgb": [
+          255,
+          255,
+          255
+        ]
+      }
+    }
+  },
+  "searches": [
+    {
+      "id": "s1",
+      "purpose": "identify",
+      "query": "Xiaomi XiaoAI speaker Pro dimensions",
+      "count": 5,
+      "status": "completed",
+      "error_code": null,
+      "request_id": "req-[redacted]",
+      "receipt_sha256": "099206543e4389fde6c4838d3fc0b125dce0fb98cd57384db3062e1abcede7a8",
+      "results": [
+        {
+          "rank": 1,
+          "url": "https://www.mi.example.com/pro/specs",
+          "title": "XiaoAI Speaker Pro",
+          "snippet": ""
+        },
+        {
+          "rank": 2,
+          "url": "https://www.mi.example.com/gen1/specs",
+          "title": "Mi AI Speaker",
+          "snippet": ""
+        }
+      ]
+    }
+  ],
+  "pages": [
+    {
+      "id": "p1",
+      "url": "https://www.mi.example.com/pro/specs",
+      "purpose": "identify",
+      "search_id": "s1",
+      "status": "read",
+      "reason": null,
+      "final_url": "https://www.mi.example.com/pro/specs",
+      "title": "小爱音箱 Pro 参数",
+      "raw_sha256": "109cbac90dd51ef3dddfd21c4a97168a25f097b4211b2146d21669281d06e3b8",
+      "text_blob_ref": "sha256:a9d6a6d8668de3346efe1d94c1afd76e71faf37bee5a6e55d3a82f9bc60b9bf0",
+      "text_sha256": "bae09c2d8ac69290d90e7cf69d7809858b1149a391400d40030037db41896415",
+      "excerpt": "小爱音箱 Pro 参数 产品尺寸：118 × 118 × 215 mm，重量 1187 g。",
+      "image_url": "https://img.example.com/pro.png"
+    },
+    {
+      "id": "p2",
+      "url": "https://www.mi.example.com/gen1/specs",
+      "purpose": "identify",
+      "search_id": "s1",
+      "status": "read",
+      "reason": null,
+      "final_url": "https://www.mi.example.com/gen1/specs",
+      "title": "小米AI音箱 规格",
+      "raw_sha256": "c139f165c41dc34c2cd30a816a80d7cbef9ecbda49e7496d46163c8692da33c7",
+      "text_blob_ref": "sha256:3dd43ad1e906a2e95af747cc8f8386c00b43df981af8b8bafe45bb2d173e7e3c",
+      "text_sha256": "2de9e3c9406bd62a2e9eef887fd42008382616377ac49fb751cd5a109f1e9a00",
+      "excerpt": "小米AI音箱 规格 尺寸 88 mm × 88 mm × 211.6 mm",
+      "image_url": null
+    }
+  ],
+  "images": [
+    {
+      "id": "i1",
+      "url": "https://img.example.com/pro.png",
+      "page_id": "p1",
+      "status": "read",
+      "reason": null,
+      "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+      "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11",
+      "media_type": "image/png",
+      "measurement": {
+        "status": "measured",
+        "method": "silhouette-v1",
+        "image": {
+          "width": 400,
+          "height": 600
+        },
+        "bbox": {
+          "x": 62,
+          "y": 49,
+          "width": 276,
+          "height": 502
+        },
+        "aspect_h_over_w": 1.8188,
+        "background": {
+          "mode": "color",
+          "rgb": [
+            255,
+            255,
+            255
+          ]
+        }
+      }
+    }
+  ],
+  "items": [
+    {
+      "id": "u1",
+      "kind": "user_input",
+      "title": "你的输入",
+      "role": "帮我根据图片还原小爱音箱",
+      "source": null,
+      "image": {
+        "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+        "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11",
+        "media_type": "image/png"
+      },
+      "verdict": null,
+      "status": "ready",
+      "query": null
+    },
+    {
+      "id": "p1",
+      "kind": "candidate",
+      "title": "小爱音箱 Pro 参数",
+      "role": "候选产品",
+      "source": {
+        "url": "https://www.mi.example.com/pro/specs",
+        "site": "www.mi.example.com"
+      },
+      "image": {
+        "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+        "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11",
+        "media_type": "image/png"
+      },
+      "verdict": null,
+      "status": "ready",
+      "query": "Xiaomi XiaoAI speaker Pro dimensions"
+    },
+    {
+      "id": "p2",
+      "kind": "candidate",
+      "title": "小米AI音箱 规格",
+      "role": "候选产品",
+      "source": {
+        "url": "https://www.mi.example.com/gen1/specs",
+        "site": "www.mi.example.com"
+      },
+      "image": null,
+      "verdict": null,
+      "status": "ready",
+      "query": "Xiaomi XiaoAI speaker Pro dimensions"
+    }
+  ],
+  "unknowns": [],
+  "budget": {
+    "queries": 1,
+    "pages": 2,
+    "images": 1
+  }
+}

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

@@ -0,0 +1,267 @@
+{
+  "budget": {
+    "images": 1,
+    "pages": 2,
+    "queries": 1
+  },
+  "changeable": [],
+  "depth": "assembly",
+  "id": "ref-40ece5312c4ecbf6-fd2b162cb",
+  "images": [
+    {
+      "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+      "id": "i1",
+      "measurement": {
+        "aspect_h_over_w": 1.8188,
+        "background": {
+          "mode": "color",
+          "rgb": [
+            255,
+            255,
+            255
+          ]
+        },
+        "bbox": {
+          "height": 502,
+          "width": 276,
+          "x": 62,
+          "y": 49
+        },
+        "image": {
+          "height": 600,
+          "width": 400
+        },
+        "method": "silhouette-v1",
+        "status": "measured"
+      },
+      "media_type": "image/png",
+      "page_id": "p1",
+      "reason": null,
+      "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11",
+      "status": "read",
+      "url": "https://img.example.com/pro.png"
+    }
+  ],
+  "intent": "restore",
+  "items": [
+    {
+      "id": "u1",
+      "image": {
+        "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+        "media_type": "image/png",
+        "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11"
+      },
+      "kind": "user_input",
+      "query": null,
+      "role": "帮我根据图片还原小爱音箱",
+      "source": null,
+      "status": "ready",
+      "title": "你的输入",
+      "verdict": null
+    },
+    {
+      "id": "p1",
+      "image": {
+        "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+        "media_type": "image/png",
+        "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11"
+      },
+      "kind": "candidate",
+      "query": "Xiaomi XiaoAI speaker Pro dimensions",
+      "role": "候选产品",
+      "source": {
+        "site": "www.mi.example.com",
+        "url": "https://www.mi.example.com/pro/specs"
+      },
+      "status": "ready",
+      "title": "小爱音箱 Pro",
+      "verdict": {
+        "code": "closest",
+        "basis": "选定为「小爱音箱 Pro」；实测高宽比 1.8188，规格 1.822，相差 0.2%"
+      }
+    },
+    {
+      "id": "p2",
+      "image": null,
+      "kind": "candidate",
+      "query": "Xiaomi XiaoAI speaker Pro dimensions",
+      "role": "候选产品",
+      "source": {
+        "site": "www.mi.example.com",
+        "url": "https://www.mi.example.com/gen1/specs"
+      },
+      "status": "ready",
+      "title": "小米AI音箱",
+      "verdict": {
+        "code": "ratio_mismatch",
+        "basis": "实测高宽比 1.8188，规格 2.4045，相差 24.4%"
+      }
+    },
+    {
+      "id": "sp1",
+      "kind": "spec",
+      "title": "外形尺寸",
+      "role": "Ø118 × 215 mm（引自 p1）",
+      "source": {
+        "url": "https://www.mi.example.com/pro/specs",
+        "site": "www.mi.example.com"
+      },
+      "image": null,
+      "verdict": null,
+      "status": "ready",
+      "query": null
+    }
+  ],
+  "keep": [
+    "外形尺寸与比例"
+  ],
+  "pages": [
+    {
+      "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,
+      "search_id": "s1",
+      "status": "read",
+      "text_blob_ref": "sha256:a9d6a6d8668de3346efe1d94c1afd76e71faf37bee5a6e55d3a82f9bc60b9bf0",
+      "text_sha256": "bae09c2d8ac69290d90e7cf69d7809858b1149a391400d40030037db41896415",
+      "title": "小爱音箱 Pro 参数",
+      "url": "https://www.mi.example.com/pro/specs"
+    },
+    {
+      "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,
+      "search_id": "s1",
+      "status": "read",
+      "text_blob_ref": "sha256:3dd43ad1e906a2e95af747cc8f8386c00b43df981af8b8bafe45bb2d173e7e3c",
+      "text_sha256": "2de9e3c9406bd62a2e9eef887fd42008382616377ac49fb751cd5a109f1e9a00",
+      "title": "小米AI音箱 规格",
+      "url": "https://www.mi.example.com/gen1/specs"
+    }
+  ],
+  "request_digest": "40ece5312c4ecbf6f5548d36589de25734706b8a333d22e1a3c32adeb75e09f5",
+  "schema": "abelien.reference-evidence.v1",
+  "searches": [
+    {
+      "count": 5,
+      "error_code": null,
+      "id": "s1",
+      "purpose": "identify",
+      "query": "Xiaomi XiaoAI speaker Pro dimensions",
+      "receipt_sha256": "099206543e4389fde6c4838d3fc0b125dce0fb98cd57384db3062e1abcede7a8",
+      "request_id": "req-[redacted]",
+      "results": [
+        {
+          "rank": 1,
+          "snippet": "",
+          "title": "XiaoAI Speaker Pro",
+          "url": "https://www.mi.example.com/pro/specs"
+        },
+        {
+          "rank": 2,
+          "snippet": "",
+          "title": "Mi AI Speaker",
+          "url": "https://www.mi.example.com/gen1/specs"
+        }
+      ],
+      "status": "completed"
+    }
+  ],
+  "status": "final",
+  "text": "帮我根据图片还原小爱音箱",
+  "unknowns": [],
+  "user_image": {
+    "blob_ref": "sha256:e2273b5b355a38441b20796072e08921b9ab30c4f37bb92070a53307af34a6f6",
+    "measurement": {
+      "aspect_h_over_w": 1.8188,
+      "background": {
+        "mode": "color",
+        "rgb": [
+          255,
+          255,
+          255
+        ]
+      },
+      "bbox": {
+        "height": 502,
+        "width": 276,
+        "x": 62,
+        "y": 49
+      },
+      "image": {
+        "height": 600,
+        "width": 400
+      },
+      "method": "silhouette-v1",
+      "status": "measured"
+    },
+    "media_type": "image/png",
+    "sha256": "da0fadd6fd3ab5ccfbac94ca4e3f2b48e440987eee6834f1c30f04c02abd5d11"
+  },
+  "collected_id": "ref-40ece5312c4ecbf6",
+  "judgement_digest": "d2b162cb00ce8cc52049f321226a89e4e0328b55d54fb022fb4a4539088882c0",
+  "identity": {
+    "candidates": [
+      {
+        "item_id": "p1",
+        "name": "小爱音箱 Pro",
+        "dimensions_mm": {
+          "width": 118,
+          "depth": 118,
+          "height": 215
+        },
+        "quote": {
+          "page_id": "p1",
+          "text": "产品尺寸：118 × 118 × 215 mm"
+        },
+        "ratio_check": {
+          "status": "consistent",
+          "measured": 1.8188,
+          "spec": 1.822,
+          "relative_error": 0.0018,
+          "tolerance": 0.1
+        }
+      },
+      {
+        "item_id": "p2",
+        "name": "小米AI音箱",
+        "dimensions_mm": {
+          "width": 88,
+          "depth": 88,
+          "height": 211.6
+        },
+        "quote": {
+          "page_id": "p2",
+          "text": "尺寸 88 mm × 88 mm × 211.6 mm"
+        },
+        "ratio_check": {
+          "status": "mismatch",
+          "measured": 1.8188,
+          "spec": 2.4045,
+          "relative_error": 0.2436,
+          "tolerance": 0.1
+        }
+      }
+    ],
+    "chosen_item_id": "p1",
+    "conflict": null
+  },
+  "similar": [],
+  "spec_quotes": [
+    {
+      "id": "sp1",
+      "quote": {
+        "page_id": "p1",
+        "text": "118 × 118 × 215 mm"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,74 @@
+# 参考研究契约（reference.research / reference.finalize）
+
+本文是 `abelien-reference` 两个 capability 的输入、输出、上限与错误码的正文。数据格式以 `schemas/reference-evidence.v1.json` 为准，样例见 `fixtures/`；判定逻辑在 `scripts/` 中，并有测试覆盖。
+
+## reference.research
+
+### 输入
+
+只接受下列字段，出现其他字段一律 `VALIDATION`：
+
+| 字段 | 规则 |
+| --- | --- |
+| `intent` | `restore` / `create` / `modify`，取自需求的 `intent.kind`（clarify 判定） |
+| `keep` / `changeable` | 保留项与可改项，各最多 20 条，每条 1–500 字 |
+| `depth` | `appearance` / `assembly` / `functional`，或 `null` |
+| `text` | 用户原话，1–4000 字 |
+| `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） |
+
+### 执行
+
+- **检索**：只用宿主环境变量 `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 会额外测量轮廓。
+- **用户原图**：存为内容 blob 并测量轮廓（`silhouette-v1`），得到包围盒和高宽比；背景必须是单色或透明。背景杂乱、没有主体、隔行 PNG、超大图都记为 `unknown`，并写明原因。
+- **幂等**：结果 id 由完整请求摘要（包括原图哈希）派生。已有同 id 的收集结果时直接返回，不再检索、不再读取。因此单条检索或页面的临时失败不会因为原样重试而自动恢复；要重试，就改写检索计划（比如换个检索词、改结果数），形成新的请求。
+
+### 输出
+
+输出 `reference-evidence`，status=collected。`items` 中第一项是 `user_input`，其后每个页面对应一格：识别用途为 `candidate`，逆向用途为 `teardown`，相似用途为 `similar`。读不到的页面状态为 `unavailable`。此时还没有任何 `verdict`。
+
+## reference.finalize
+
+### 输入
+
+| 字段 | 规则 |
+| --- | --- |
+| `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`，此时比例记为未核对 |
+| `similar` | 可选，最多 12 条，每条为 `{item_id, decision: borrow / skip, borrowed?, why, not_copied?}`；`borrow` 时必须写明 `borrowed` |
+| `excluded` | 可选，最多 12 条，每条为 `{item_id, reason}` |
+| `specs` | 可选，最多 12 条，每条为 `{title, value, quote}`，生成 `spec` 格 |
+
+### 核验
+
+- 引用经过空白归一后，必须逐字出现在该页已保存的正文里。只能引用读取成功的页面。
+- 给出尺寸时，宽、高（以及给出时的深）这些数字必须都出现在引用里；没给尺寸时，比例核对为 `unknown`（`no_dimensions`），并写入 `unknowns`。
+- 条目种类必须匹配：候选必须是 `candidate` 格，相似必须是 `similar` 格；排除不能作用于 `user_input`。
+
+### 判定（确定性）
+
+- 正面视角下，比较高宽比：规格比例为 `height / width`，与用户原图的实测值比较，相对误差不超过 10% 记为 `consistent`，否则记为 `mismatch`；没有测量或缺尺寸时记为 `unknown`。
+- 所选候选：比例一致或无法核对时，判定为 `closest`，依据中写明比例情况；比例不符时，判定为 `ratio_mismatch`，并在 `identity.conflict` 中写明。
+- 其他候选：比例不符时判定为 `ratio_mismatch`，其余不加判定，仍保留为候选，供用户切换。
+- 相似产品：`borrow` 判定为 `borrowed`，依据中写明借用了什么、原因、哪些不照搬；`skip` 判定为 `not_copied`。
+- 排除项：状态改为 `excluded`，判定为 `excluded`。
+- 同一份收集结果可以多次提交不同判断，每次生成一份新的 final 结果（id 带判断摘要），收集结果本身不变。
+
+## 错误码
+
+| 码 | 含义 |
+| --- | --- |
+| `VALIDATION` | 输入不合规、引用不在原文、尺寸不在引用中、条目种类不符 |
+| `REFERENCE_WEB_CONFIG` | 缺少 `WEB_SEARCH_API_KEY`，或 DNS 配置非法 |
+| `REFERENCE_WEB_*` | 单条检索、读取的失败码，只记在对应的检索、页面或图片里，不使整次运行失败 |
+| `REFERENCE_HOST` | 宿主没有提供可信的资源读取、内容读写端口 |
+
+## 宿主责任
+
+- 把上传的图片转成 PNG，写入作品目录中的输入文件，再用 `--input-file` 传入。
+- 只展示 `items` 和 `unknowns`；`verdict` 原样展示，不重新解释，也不改写。
+- 第三方图片从内容 blob 转存到私有存储，展示时附来源，不进入图鉴或公开分享。