abelien-harness 0.6.0 → 0.6.1

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.1",
   "description": "npx-installable multi-agent skill harness: generic kernel + pluggable domain packs",
   "type": "module",
   "engines": {

package/skills/abelien-reference/SKILL.md

@@ -29,7 +29,15 @@ compatibility:
    - 比例判定由测量值和规格计算得出，不能由 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`，并在 `unknowns` 写明型号待定。
+- 这两种情况都属于需求修订：clarify 把用户的选择记成 source=user 的需求，后续阶段按 workspace 规则推进，本包只负责重新提交判断。
 
 ## 调用
 

package/skills/abelien-reference/domain.json

@@ -1,6 +1,6 @@
 {
   "name": "abelien-reference",
-  "version": "0.1.0",
+  "version": "0.2.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

@@ -31,6 +31,10 @@
 
 输出 `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
 
 ### 输入

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

@@ -6,7 +6,7 @@ import { text, record, digest, sha256 } from "../../abelien-harness/scripts/web/
 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";
+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"); }
@@ -70,12 +70,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 +93,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,7 +156,7 @@ 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 {
@@ -174,6 +185,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 },
   });
 }