abelien-harness 0.5.0 → 0.6.0

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

@@ -0,0 +1,116 @@
+// reference.finalize（P2-13.04）：核验 Agent 对已收集证据的判断，生成最终的 reference-evidence。
+// Agent 只给判断与原文引用；引用必须逐字出现在已保存的页面正文里，尺寸数字必须出现在引用中，
+// 比例判定由测量值与规格尺寸确定性计算，不接受 Agent 自填的判定。
+import { text, record, digest } from "../../abelien-harness/scripts/web/common.mjs";
+import { compareRatio } from "./measure.mjs";
+import { validateEvidence, invalid } from "./evidence.mjs";
+
+const normalize = value => value.replace(/\s+/g, " ").trim();
+const numbersIn = value => new Set((value.match(/\d+(?:\.\d+)?/g) ?? []).map(Number));
+const percent = value => `${Math.round(value * 1000) / 10}%`;
+
+function checkKeys(value, keys, label) { if (!record(value) || Object.keys(value).some(key => !keys.includes(key))) invalid(`${label} has unsupported fields`); }
+function words(value, label, max = 300) { if (!text(value) || value.length > max) invalid(`${label} must be 1–${max} chars`); return value.trim(); }
+
+export async function finalizeReference({ input, readResource, readBlob }) {
+  checkKeys(input, ["evidence_id", "identity", "similar", "excluded", "specs"], "input");
+  for (const name of ["similar", "excluded"]) if (input[name] !== undefined && (!Array.isArray(input[name]) || input[name].length > 12)) invalid(`${name} must be up to 12 entries`);
+  if (typeof readResource !== "function" || typeof readBlob !== "function") throw Object.assign(new Error("trusted resource and content readers are required"), { code: "REFERENCE_HOST" });
+  if (!/^reference-evidence:ref-[0-9a-f]{16}$/.test(input.evidence_id ?? "")) invalid("evidence_id must name a collected reference-evidence resource");
+  const resource = await readResource(input.evidence_id);
+  if (resource?.kind !== "reference-evidence" || resource.body?.status !== "collected") invalid("evidence_id must name a collected reference-evidence resource");
+  const collected = validateEvidence(resource.body), body = structuredClone(collected);
+  const pages = new Map(body.pages.map(page => [page.id, page])), items = new Map(body.items.map(item => [item.id, item]));
+  const pageText = new Map();
+  const quoteOn = (quote, label) => {
+    checkKeys(quote, ["page_id", "text"], label);
+    const page = pages.get(quote.page_id);
+    if (!page || page.status !== "read" || !page.text_blob_ref) invalid(`${label}.page_id must name a page that was read`);
+    if (!pageText.has(page.id)) pageText.set(page.id, normalize(String(readBlob(page.text_blob_ref)?.text ?? "")));
+    const quoted = words(quote.text, `${label}.text`, 500);
+    if (!pageText.get(page.id).includes(normalize(quoted))) invalid(`${label}.text must appear verbatim in page ${page.id}`);
+    return { page_id: page.id, text: quoted };
+  };
+  const itemOf = (id, kinds, label) => {
+    const item = items.get(id);
+    if (!item || !kinds.includes(item.kind)) invalid(`${label} must name an item of kind ${kinds.join(" or ")}`);
+    return item;
+  };
+  const unknowns = [...body.unknowns];
+
+  let identity = null;
+  if (input.identity !== undefined) {
+    checkKeys(input.identity, ["candidates", "chosen_item_id"], "identity");
+    const list = input.identity.candidates ?? [];
+    if (!Array.isArray(list) || list.length > 6) invalid("identity.candidates must be up to 6 entries");
+    const measurement = body.user_image?.measurement ?? null;
+    const candidates = list.map((c, i) => {
+      const label = `identity.candidates[${i}]`;
+      checkKeys(c, ["item_id", "name", "dimensions_mm", "quote"], label);
+      itemOf(c.item_id, ["candidate"], `${label}.item_id`);
+      // Dimensions are optional: a page may name the model without giving its size. The quote is always required.
+      const dims = c.dimensions_mm === undefined || c.dimensions_mm === null ? null : c.dimensions_mm;
+      const quote = quoteOn(c.quote, `${label}.quote`);
+      if (dims) {
+        checkKeys(dims, ["width", "depth", "height"], `${label}.dimensions_mm`);
+        const keys = ["width", "height", ...(dims.depth === undefined ? [] : ["depth"])], found = numbersIn(quote.text);
+        for (const key of keys) if (!Number.isFinite(dims[key]) || dims[key] <= 0 || dims[key] > 5000) invalid(`${label}.dimensions_mm.${key} must be 0–5000 mm`);
+        for (const key of keys) if (!found.has(dims[key])) invalid(`${label}.quote must contain the ${key} value ${dims[key]}`);
+      }
+      return { item_id: c.item_id, name: words(c.name, `${label}.name`, 120), dimensions_mm: dims ? { ...dims } : null, quote, ratio_check: compareRatio(measurement, dims) };
+    });
+    const chosen = input.identity.chosen_item_id ?? null;
+    if (chosen === null ? candidates.length > 0 : !candidates.some(c => c.item_id === chosen)) invalid("identity.chosen_item_id must name one of the candidates (null only when there are none)");
+    const pick = candidates.find(c => c.item_id === chosen) ?? null;
+    let conflict = null;
+    if (pick?.ratio_check.status === "mismatch") conflict = `所选型号「${pick.name}」与参考图比例不符（实测 ${pick.ratio_check.measured}，规格 ${pick.ratio_check.spec}）`;
+    else {
+      const others = candidates.filter(c => c !== pick && c.ratio_check.status === "consistent" && c.name !== pick?.name);
+      if (others.length && pick?.ratio_check.status !== "consistent") conflict = `另有比例一致的候选：${others.map(c => c.name).join("、")}`;
+    }
+    if (!pick) unknowns.push("型号未能识别");
+    else if (pick.ratio_check.status === "unknown") unknowns.push(`型号比例未核对（${pick.ratio_check.reason}）`);
+    for (const c of candidates) {
+      const item = items.get(c.item_id), r = c.ratio_check;
+      const ratio = r.status === "unknown" ? `比例未核对（${r.reason}）` : `实测高宽比 ${r.measured}，规格 ${r.spec}，相差 ${percent(r.relative_error)}`;
+      if (r.status === "mismatch") item.verdict = { code: "ratio_mismatch", basis: ratio };
+      else if (c.item_id === chosen) item.verdict = { code: "closest", basis: `选定为「${c.name}」；${ratio}` };
+      item.title = c.name;
+    }
+    identity = { candidates, chosen_item_id: chosen, conflict };
+  } else if (body.intent !== "create") unknowns.push("没有提交识别判断，型号保持未知");
+
+  const similar = (input.similar ?? []).map((s, i) => {
+    const label = `similar[${i}]`;
+    checkKeys(s, ["item_id", "decision", "borrowed", "why", "not_copied"], label);
+    const item = itemOf(s.item_id, ["similar"], `${label}.item_id`);
+    if (!["borrow", "skip"].includes(s.decision)) invalid(`${label}.decision must be borrow or skip`);
+    const why = words(s.why, `${label}.why`);
+    if (s.decision === "borrow") {
+      const borrowed = words(s.borrowed, `${label}.borrowed`), notCopied = s.not_copied === undefined ? null : words(s.not_copied, `${label}.not_copied`);
+      item.verdict = { code: "borrowed", basis: `借用：${borrowed}；原因：${why}${notCopied ? `；不照搬：${notCopied}` : ""}` };
+      return { item_id: s.item_id, decision: "borrow", borrowed, why, not_copied: notCopied };
+    }
+    item.verdict = { code: "not_copied", basis: why };
+    return { item_id: s.item_id, decision: "skip", borrowed: null, why, not_copied: null };
+  });
+
+  for (const [i, e] of (input.excluded ?? []).entries()) {
+    checkKeys(e, ["item_id", "reason"], `excluded[${i}]`);
+    const item = itemOf(e.item_id, ["candidate", "teardown", "similar"], `excluded[${i}].item_id`);
+    item.status = "excluded"; item.verdict = { code: "excluded", basis: words(e.reason, `excluded[${i}].reason`) };
+  }
+
+  if (input.specs !== undefined && (!Array.isArray(input.specs) || input.specs.length > 12)) invalid("specs must be up to 12 entries");
+  const specs = (input.specs ?? []).map((s, i) => {
+    checkKeys(s, ["title", "value", "quote"], `specs[${i}]`);
+    const quote = quoteOn(s.quote, `specs[${i}].quote`), page = pages.get(quote.page_id);
+    return { id: `sp${i + 1}`, kind: "spec", title: words(s.title, `specs[${i}].title`, 80), role: words(s.value, `specs[${i}].value`, 200),
+      source: { url: page.final_url ?? page.url, site: items.get(page.id)?.source?.site ?? "" }, image: null, verdict: null, status: "ready", query: null, quote };
+  });
+
+  const judgementDigest = digest(input);
+  return validateEvidence({ ...body, id: `${body.id}-f${judgementDigest.slice(0, 8)}`, status: "final", collected_id: body.id, judgement_digest: judgementDigest,
+    identity, similar, items: [...items.values(), ...specs.map(({ quote, ...item }) => ({ ...item, role: `${item.role}（引自 ${quote.page_id}）` }))], spec_quotes: specs.map(s => ({ id: s.id, quote: s.quote })),
+    unknowns: [...new Set(unknowns)] });
+}

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

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

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

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

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

@@ -0,0 +1,179 @@
+// reference.research（P2-13.04）：按 Agent 给出的检索计划执行确定性的收集——Volc 检索、公开页面安全直读、
+// 页面主图抓取、用户原图测量——全部落为证据，不做身份判断。判断由 Agent 读证据后经 reference.finalize 提交并核验。
+// 同一请求重复运行直接返回已有结果，不重复产生检索费用。
+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 { measurePng } from "./measure.mjs";
+import { SCHEMA, INTENTS, DEPTHS, PURPOSES, KIND_BY_PURPOSE, LIMITS, 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"); }
+}
+
+export function validateResearchInput(input) {
+  if (!record(input)) invalid("input must be an object");
+  const allowed = ["intent", "keep", "changeable", "depth", "text", "links", "user_image", "plan"];
+  if (Object.keys(input).some(key => !allowed.includes(key))) invalid("input has unsupported fields");
+  if (!INTENTS.includes(input.intent)) invalid(`intent must be one of ${INTENTS.join(", ")}`);
+  if (input.depth !== undefined && input.depth !== null && !DEPTHS.includes(input.depth)) invalid(`depth must be one of ${DEPTHS.join(", ")} or null`);
+  if (!text(input.text) || input.text.length > LIMITS.textChars) invalid(`text must be the user's words (1–${LIMITS.textChars} chars)`);
+  const links = input.links === undefined ? [] : input.links;
+  if (!Array.isArray(links) || links.length > LIMITS.links) invalid(`links must be up to ${LIMITS.links} URLs`);
+  let userImage = null;
+  if (input.user_image !== undefined && input.user_image !== null) {
+    const image = input.user_image;
+    if (!record(image) || image.media_type !== "image/png" || typeof image.base64 !== "string") invalid("user_image must be {media_type: \"image/png\", base64}; the host converts other formats to PNG");
+    const bytes = Buffer.from(image.base64, "base64");
+    if (!isPng(bytes) || bytes.length > LIMITS.userImageBytes) invalid(`user_image must be a PNG up to ${LIMITS.userImageBytes} bytes`);
+    userImage = { bytes, sha256: sha256(bytes) };
+  }
+  const plan = input.plan ?? {};
+  if (!record(plan) || Object.keys(plan).some(key => !["queries", "max_pages", "max_images"].includes(key))) invalid("plan has unsupported fields");
+  const queries = plan.queries ?? [];
+  if (!Array.isArray(queries) || queries.length > LIMITS.queries) invalid(`plan.queries must be up to ${LIMITS.queries} entries`);
+  const normalizedQueries = queries.map((q, i) => {
+    if (!record(q) || !PURPOSES.includes(q.purpose) || !text(q.query) || q.query.length > LIMITS.queryChars) invalid(`plan.queries[${i}] needs purpose (${PURPOSES.join(", ")}) and a query up to ${LIMITS.queryChars} chars`);
+    if (q.count !== undefined && (!Number.isSafeInteger(q.count) || q.count < 1 || q.count > LIMITS.count)) invalid(`plan.queries[${i}].count must be 1–${LIMITS.count}`);
+    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; };
+  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") },
+  };
+}
+
+const titleOf = html => {
+  const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+  return match ? 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; } }
+  }
+  return null;
+}
+
+/** Run tasks with bounded concurrency; results keep input order. */
+async function pool(list, task, limit = LIMITS.concurrency) {
+  const out = new Array(list.length); let next = 0;
+  await Promise.all(Array.from({ length: Math.min(limit, list.length) }, async () => {
+    while (next < list.length) { const index = next++; out[index] = await task(list[index], index); }
+  }));
+  return out;
+}
+
+/** Interleave search results so one query cannot use the whole page budget. */
+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); } };
+  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++) {
+    let added = false;
+    for (const search of searches) {
+      const result = search.results[rank];
+      if (!result) continue;
+      added = true;
+      try { push({ url: reader.normalizePublicSourceUrl(result.url).href, purpose: search.purpose, search_id: search.id, query: search.query, search_title: result.title }); } catch { /* not a public HTTPS result */ }
+    }
+    if (!added) break;
+  }
+  return queue;
+}
+
+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 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;
+
+  const unknowns = [], items = [];
+  let userImage = null;
+  if (request.userImage) {
+    const blobRef = writeBlob({ media_type: "image/png", base64: request.userImage.bytes.toString("base64") });
+    const measurement = measurePng(request.userImage.bytes);
+    if (measurement.status !== "measured") unknowns.push(`用户原图未能测量轮廓（${measurement.reason}）`);
+    userImage = { blob_ref: blobRef, sha256: request.userImage.sha256, media_type: "image/png", measurement };
+  }
+  items.push({ id: "u1", kind: "user_input", title: "你的输入", role: request.text, source: null,
+    image: userImage ? { blob_ref: userImage.blob_ref, sha256: userImage.sha256, media_type: "image/png" } : null, verdict: null, status: "ready", query: null });
+
+  const searches = [];
+  for (const [index, q] of request.plan.queries.entries()) {
+    const entry = { id: `s${index + 1}`, purpose: q.purpose, query: q.query, count: q.count, status: "completed", error_code: null, request_id: null, receipt_sha256: null, results: [] };
+    try {
+      const saved = await volc.volcWebSearch(volc.volcQueryRequest({ query: q.query, count: q.count }), { env, fetchImpl, timeoutMs: LIMITS.searchTimeoutMs });
+      entry.request_id = saved.request_id; entry.receipt_sha256 = saved.raw_sha256;
+      entry.results = (saved.response.Result.WebResults ?? []).filter(r => text(r?.Url)).map((r, rank) => ({ rank: rank + 1, url: r.Url, title: String(r.Title ?? ""), snippet: String(r.Snippet ?? r.Summary ?? "").slice(0, 300) }));
+      if (!entry.results.length) unknowns.push(`检索「${q.query}」没有结果`);
+    } catch (error) {
+      if (error?.code === "REFERENCE_WEB_CONFIG") throw error;
+      entry.status = "failed"; entry.error_code = error?.code ?? "REFERENCE_WEB_TRANSPORT";
+      unknowns.push(`检索「${q.query}」失败（${entry.error_code}）`);
+    }
+    searches.push(entry);
+  }
+
+  const readOptions = { lookup: ports.lookup, pageRequest: ports.pageRequest, dnsRequest: ports.dnsRequest, timeoutMs: LIMITS.pageTimeoutMs };
+  const queue = pageQueue(request.links, request.intent, searches, request.plan.max_pages);
+  // 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 };
+    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;
+      }
+    } catch (error) {
+      page.reason = reader.publicReadFailure(error)?.stage ?? error?.code ?? "read_failed";
+      if (!reader.publicReadFailure(error) && !String(error?.code ?? "").startsWith("REFERENCE_WEB_")) throw error;
+    }
+    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 wanted = pages.filter(page => page.image_url).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"));
+      }
+    } 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;
+  });
+  const imageOf = new Map(images.filter(i => i.status === "read").map(i => [i.page_id, { blob_ref: i.blob_ref, sha256: i.sha256, media_type: i.media_type }]));
+  for (const [index, page] of pages.entries()) {
+    items.push({ id: page.id, kind: KIND_BY_PURPOSE[page.purpose], title: page.title || site(page.url) || page.url, role: page.purpose === "identify" ? "候选产品" : page.purpose === "teardown" ? "逆向资料" : "相似产品",
+      source: { url: page.final_url ?? page.url, site: site(page.final_url ?? page.url) ?? "" }, image: imageOf.get(page.id) ?? null, verdict: null,
+      status: page.status === "read" ? "ready" : "unavailable", query: queue[index].query });
+  }
+  if (request.intent !== "create" && !pages.some(p => p.purpose === "identify" && p.status === "read")) unknowns.push("没有读到可用于识别产品的页面，型号保持未知");
+  if (request.intent === "create" && !pages.some(p => p.purpose === "similar" && p.status === "read")) unknowns.push("没有读到相似产品页面，可改按声学、供电、交互等子系统参考");
+
+  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 },
+  });
+}

package/skills/abelien-structure/SKILL.md

@@ -14,7 +14,7 @@ compatibility:
 
 ## 参与时机与交接
 
-- 硬件未选定：从用户需求及 appearance 外观目标提取尺寸、形态、开口、固定区域和运动空间约束，供 hardware 检索；此时无需完整建模。
+- 硬件未选定：先建立整机结构骨架，即按功能划分的分区与基准面（如声学腔与挡板、电子托板层与支柱、按键板、电池仓、运动关节），给出每个分区的可用空间（直径或盒体、高度预算、开口与朝向），连同用户需求及 appearance 外观目标中的尺寸、形态、开口、固定区域和运动空间约束一起供 hardware 检索；分区空间以对应槽位的 `fit_envelope` 交给 hardware：分区由锁定的外形或用户硬要求确定时 `basis` 记 `locked`（放不下的件会被拒绝），由结构推断时记 `inferred`（只影响排序），`zone` 写分区名；此时只建骨架与包络，不做完整建模，也不阻塞首张外观图。还原或修改现成产品且有拆解或官方结构资料时，骨架按来源架构建立；新创时可参考相似产品的架构；两者都标为推断。首张外观图之后，再结合真实器件尺寸确定托板、支柱、开孔和安装方式，与 hardware 往返迭代。
 - 硬件候选出现：核对尺寸、CAD 和可复用整机结构，做初步布局；候选几何不能被称为已采用产品。
 - 已有硬件起点：读取实际组件 ID、数量、来源及版本，复用资产并建立装配、轻量预览。
 - 用户修改或工程结果返回：只处理受影响的参数、资产和检查。纯颜色变化通常不重建几何；轮廓、分件、开口、组件或运动改变则重判相关检查。
@@ -45,7 +45,7 @@ compatibility:
 
 进程组清理保持 TERM → wait(2s) → KILL → wait。仅 Darwin 的 PermissionError 且原子进程已退出时，固定 `/bin/ps` 完整校验全表，证明原组无成员或全为同有效 UID 的 zombie 后才按已终止处理（该表接受 Darwin 的 `?` 未定运行态，它不使整表判废；原组自身成员为 `?` 仍不是 zombie，照旧失败）；活后代、未知探针与其他错误仍失败。边界见[执行参考](references/build123d-execution.md)。
 
-本包不注册空 `domain.json`、虚假的 `structure.*` capability 或占位 CAD 生成服务。需要有本地执行／渲染／看图能力的宿主，或另行接通对应后端。执行辅助工具是有界前台进程，不是跨请求的后台 Worker；中断后可核验并复用已完成产物，不能恢复一个已经消失的进程。
+本包随附 Structure Worker（`worker/`）及其宿主 CLI adapter：`domain.json` 注册的 `structure.*` 能力只供宿主调用，依赖宿主设置的文件根目录与 Worker 凭据，缺少即拒绝；Agent 不直接调用它们，CAD 仍经宿主的受管工具提交。上面三个执行辅助工具是有界前台进程，不是跨请求的后台 Worker；中断后可核验并复用已完成产物，不能恢复一个已经消失的进程。
 
 ## 还原与工程边界
 

package/skills/abelien-structure/domain.json

@@ -0,0 +1,64 @@
+{
+  "name": "abelien-structure",
+  "version": "0.1.0",
+  "description": "结构域的宿主 CLI adapter：组件拟合、工程产物校验、目标件渲染与 Structure Worker 任务。只供宿主经 ab capability run 调用：文件只能在宿主设置的 ABELIEN_STRUCTURE_IO_ROOT 内读写，连 Worker 需宿主设置的 AGENT_STRUCTURE_ORIGIN / AGENT_STRUCTURE_TOKEN；缺少即拒绝。",
+  "resources": [],
+  "capabilities": {
+    "structure.engineering-contract": {
+      "description": "返回工程拟合检查器的版本、检查项、未检查项、产物类型与策略，供宿主核对已存工程结果",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "engineeringContract" }
+    },
+    "structure.engineering-request-check": {
+      "description": "校验并归一化 component_fit 工程请求（不提交任务），返回归一化请求与三角形数",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "engineeringRequestCheck" }
+    },
+    "structure.attachment-baseline-check": {
+      "description": "按同一 Worker 基线的装配清单与 STEP 校验附件基线，返回已核对的附件基线",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "attachmentBaselineCheck" }
+    },
+    "structure.engineering-artifacts-check": {
+      "description": "校验工程拟合任务的产物字节与身份（stored=true 时按已存子集校验），返回报告、配方与装配",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "engineeringArtifactsCheck" }
+    },
+    "structure.component-fit": {
+      "description": "把生成件装进同一基线的目标部位，生成装配预览 GLB 并返回拟合报告",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "componentFit" }
+    },
+    "structure.component-fit-verify": {
+      "description": "按原始输入重算拟合，核对报告与装配 GLB 字节；不信任报告里自报的结论",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "componentFitVerify" }
+    },
+    "structure.target-placement": {
+      "description": "由可信基线 GLB 推导生成件到目标部位局部坐标的刚体变换",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "targetPlacement" }
+    },
+    "structure.target-image": {
+      "description": "请 Worker 在其运行时内渲染目标部位的单件图（协议 v3 /target-image），写出 PNG 与目标件 GLB",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "targetImage" }
+    },
+    "structure.worker-health": {
+      "description": "读取 Worker 的协议版本、检查器版本与 runtimeDigest",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "workerHealth" }
+    },
+    "structure.source-contract": {
+      "description": "读取 Worker 的建模源码契约（与 health 同一身份）",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "sourceContract" }
+    },
+    "structure.job-submit": {
+      "description": "在宿主给定的 scope 下向 Worker 提交 CAD 或工程拟合任务；同 key 重复提交返回同一任务",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "jobSubmit" }
+    },
+    "structure.job-lookup": {
+      "description": "按 upstream key 回读任务，用于提交响应丢失后的找回与状态轮询",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "jobLookup" }
+    },
+    "structure.job-cancel": {
+      "description": "取消指定任务",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "jobCancel" }
+    },
+    "structure.artifact-read": {
+      "description": "读取任务产物：媒体类型、头部哈希与字节哈希都须与宿主给出的预期一致才写出文件",
+      "adapter": { "type": "module", "path": "worker/cli-adapter.mjs", "export": "artifactRead" }
+    }
+  }
+}

package/skills/abelien-structure/references/build123d-execution.md

@@ -11,7 +11,7 @@
 
 核对实际 Python 解释器及 `build123d`、所用导出／渲染依赖能导入，记录真实工具版本。根据已安装版本的文档选择 API；无运行环境时交回明确缺口，不自动重装或升级共享环境。
 
-统一毫米与坐标系，通常 X 宽、Y 高、Z 深、正面 +Z；运动产品若用 Z 向上，须在参数和产物清单同时声明。组件保持原生比例；来源坐标修正与装配放置分开记录。尺寸、壁厚、间隙和运动范围集中在参数文件，阈值来自材料／工艺／真实规格或本次要求，不写全局猜测值。
+统一毫米与坐标系，通常 X 宽、Y 高、Z 深、正面 +Z；运动产品若用 Z 向上，须在参数和产物清单同时声明。组件保持原生比例；来源坐标修正与装配放置分开记录。尺寸、壁厚、间隙和运动范围集中在参数文件，阈值来自材料／工艺／真实规格或本次要求，不写全局猜测值。组件位置以骨架基准面表达：坐落件写成“所在基准面 + 间隙”，基准面高度由下层组件的原生尺寸加间隙推导，不为每个组件手填独立的绝对坐标；手填常数只用于来源给定的外形或开口位置，并在参数文件注明依据。
 
 ## 两个执行阶段
 

package/skills/abelien-structure/references/handoff.md

@@ -19,7 +19,7 @@
 ## 领域分工
 
 - hardware 判定型号、电气／接口兼容及覆盖；structure 验证具体空间、安装点、操作口和几何关系。hardware 的机械规格证据不能代替实际装配检查。
-- 无法安装时，返回受影响 slot／component、可用空间、干涉证据、替代尺寸约束及可选结构修改。没有用户授权改变硬要求时，不通过放宽要求解决。
+- 无法安装时，返回受影响 slot／component、可用空间、干涉证据、替代尺寸约束及可选结构修改。没有用户授权改变硬要求时，不通过放宽要求解决。调整顺序取决于哪些约束被锁定：外形被还原目标或用户硬要求锁定时，先由 hardware 在原要求下换件，再调整骨架（分区、层高、朝向），改变外形必须交 guide 由用户取舍并记为外观偏差，不得自行放大外壳；外形未锁定时，在 appearance 认可的外观容差内调整外形与换件同等可选，把选择依据写入结果。
 - 换型交回 hardware；算力／行为影响交回 algorithm。structure 不把局部设计建议写成新的已选 BOM。
 - 复用整机时保持组件数量和身份，核对继承范围。自定义机械件另列，避免把整机 BOM 与其子组件重复采购。
 - source BOM 是原产品证据，candidate BOM 是本次选型与装配；同功能替代不能写成原件。相关研究消费 hardware 的证据，不再启动第二套候选系统。