abelien-harness 0.14.0 → 1.0.0

package/.env.example

@@ -41,6 +41,15 @@ ABELIEN_SOURCE_REGISTRY_TIMEOUT_MS=30000
 # ... or an absolute local directory for tests, offline runs and a single local host.
 ABELIEN_SOURCE_REGISTRY_DIR=
 
+# PDF reading for the web fallback (registry mode): the host installs mupdf.js separately (npm "mupdf") and points
+# at its dist/mupdf.js; drawing pages are read by an Ark vision endpoint (deepseek-v4-1-flash). Leave empty to
+# still fetch and register PDFs, with unreadable parts recorded as unavailable.
+ABELIEN_PDF_ENGINE_MODULE=
+ABELIEN_SOURCE_VISION_ENDPOINT_ID=
+ABELIEN_SOURCE_VISION_API_KEY=
+ABELIEN_SOURCE_VISION_TIMEOUT_MS=60000
+ABELIEN_SOURCE_VISION_CONCURRENCY=4
+
 # Optional loopback HTTP wrapper only; main hardware.select executes locally without a URL.
 # At least 32 bytes, keep the real token in a private env file. Do not expose this server publicly.
 ABELIEN_HARDWARE_SELECT_TOKEN=

package/README.md

@@ -12,8 +12,8 @@ npx 可安装的多 agent skill harness：**通用内核 + 可插拔域包**。
 [abelien-guide](skills/abelien-guide/SKILL.md)（对话调度与沟通）· [abelien-clarify](skills/abelien-clarify/SKILL.md)（需求澄清只读快照）。
 领域层：[abelien-hardware](skills/abelien-hardware/SKILL.md)（三级分类、OSS 召回、联网补位、本地选型与修订）·
 [abelien-algorithm](skills/abelien-algorithm/SKILL.md)（基于已验证硬件、官方资料优先的联网算法选型）·
-[abelien-appearance](skills/abelien-appearance/SKILL.md) 与 [abelien-structure](skills/abelien-structure/SKILL.md)（外观与机械结构）·
-宿主包：[abelien-structure-worker](skills/abelien-structure-worker/SKILL.md)（Structure Worker 与 `structure.*` 宿主专用能力）·
+[abelien-appearance](skills/abelien-appearance/SKILL.md) 与 [abelien-structure](skills/abelien-structure/SKILL.md)（外观与机械结构；读图出点位、骨架布局与换件条件的确定性动作）·
+宿主包：[abelien-structure-worker](skills/abelien-structure-worker/SKILL.md)（Structure Worker 与 14 个 `structure.*` 宿主专用能力）·
 [abelien-3dgen](skills/abelien-3dgen/SKILL.md)（四家 provider 的 3D 构件生成，经 `ab generate 3d` 与宿主 `mesh.generate` 使用）。
 
 ## Quickstart

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abelien-harness",
-  "version": "0.14.0",
+  "version": "1.0.0",
   "description": "npx-installable multi-agent skill harness: generic kernel + pluggable domain packs",
   "type": "module",
   "engines": {
@@ -21,6 +21,7 @@
     "test": "node --test",
     "eval": "node eval/run.mjs",
     "render:journey-plan": "node tools/render-journey-plan.mjs",
+    "render:actions": "node tools/render-actions.mjs",
     "prepare": "node scripts/install-hooks.mjs",
     "branch:new": "node scripts/new-branch.mjs",
     "sync": "node scripts/sync.mjs",

package/skills/abelien-algorithm/SKILL.md

@@ -29,6 +29,7 @@ metadata:
 4. 绑定：`algorithm.research`（`purpose=hardware`，查询带 `component_id`）→ `algorithm.finalize`（`operation=bind`，`research` 格式见 [algorithm-bindings.v1](schemas/algorithm-bindings.v1.json)）。来源只写 `research_id` 与 `page_id`，回执由 Harness 从自己存下的正文填写。
 5. 宿主在每个阶段开跑前用只读的 `algorithm.lane-state` 查当前需求有没有已提议的候选、候选有没有绑定到当前硬件，映射成 `workspace.lanes-next` 的 artifacts。
 6. 已有的 `user-journey-algorithm` workflow（先有 verified 硬件再研究）保持可用，供不走车道的宿主使用。
+7. 各动作的参数、取值范围与错误码见[动作参数与错误手册](references/actions.generated.md)（由动作定义生成，以它为准）。
 
 ## 核心边界
 

package/skills/abelien-algorithm/actions/algorithm.candidates.json

@@ -0,0 +1,43 @@
+{
+  "action_id": "algorithm.candidates",
+  "contract_version": 1,
+  "description": "核验 Agent 基于 implementation 研究为每个 reaction 提出的候选实现：引用须逐字出现在本次研究存下的正文，候选只能引用为自己 reaction 检索的页面，库内算法须来自研究输入的库清单；每个 reaction 要么有候选、要么写明未解决原因；保存为 status=proposed，不依赖硬件",
+  "audience": "agent",
+  "input_schema": "schemas/candidates-input.v1.json",
+  "output_schema": "schemas/candidates-result.v1.json",
+  "permissions": [
+    "algorithm.candidates",
+    "artifact.read",
+    "artifact.write"
+  ],
+  "effects": [
+    "data.read",
+    "artifact.write"
+  ],
+  "determinism": "deterministic",
+  "cache_policy": {
+    "mode": "disabled",
+    "allow_bypass": true
+  },
+  "errors": {
+    "VALIDATION": {
+      "category": "source",
+      "description": "research_id 不是 collected 的 implementation 研究、引用不在本次研究存下的正文、候选引用了别的 reaction 的页面、库内算法不在研究的库清单，或有 reaction 既没有候选也没有写明未解决原因",
+      "recovery": "correct_input"
+    },
+    "ALGORITHM_HOST": {
+      "category": "config",
+      "description": "宿主没有提供可信的资源读取、内容读写或资源列举端口",
+      "recovery": "await_configuration"
+    }
+  },
+  "result_checks": [
+    {
+      "kind": "output_schema"
+    },
+    {
+      "kind": "ref_integrity"
+    }
+  ],
+  "completion": "validated_result"
+}

package/skills/abelien-algorithm/actions/algorithm.finalize.json

@@ -0,0 +1,38 @@
+{
+  "action_id": "algorithm.finalize",
+  "contract_version": 1,
+  "description": "把 Agent 基于硬件型号和官方联网证据做出的算法绑定归一化为版本化选型资源；operation=bind 时候选取自 algorithm.candidates，来源回执从 Harness 自己存下的研究正文解析，硬件基线尚未 verified 时结果固定为 needs_confirmation",
+  "audience": "agent",
+  "input_schema": "schemas/finalize-input.v1.json",
+  "output_schema": "schemas/finalize-result.v1.json",
+  "permissions": [
+    "algorithm.finalize",
+    "artifact.read",
+    "artifact.write"
+  ],
+  "effects": [
+    "data.read",
+    "artifact.write"
+  ],
+  "determinism": "deterministic",
+  "cache_policy": {
+    "mode": "disabled",
+    "allow_bypass": true
+  },
+  "errors": {
+    "VALIDATION": {
+      "category": "source",
+      "description": "operation 不对、硬件基线缺失或修订过期（select 还要求 verified）、reaction 不完整或没覆盖全部需求、来源不是一手资料或没有可核对的回执、绑定没选该 reaction 已提议的候选",
+      "recovery": "correct_input"
+    }
+  },
+  "result_checks": [
+    {
+      "kind": "output_schema"
+    },
+    {
+      "kind": "ref_integrity"
+    }
+  ],
+  "completion": "validated_result"
+}

package/skills/abelien-algorithm/actions/algorithm.lane-state.json

@@ -0,0 +1,38 @@
+{
+  "action_id": "algorithm.lane-state",
+  "contract_version": 1,
+  "description": "只读：按本草稿已存的资源回答当前需求有没有已提议的候选（落点、reaction、limits 与研究时一致），以及这些候选有没有绑定到给定的硬件选型 id 与 revision；宿主把结果映射成 workspace.lanes-next 的 artifacts",
+  "audience": "agent",
+  "input_schema": "schemas/lane-state-input.v1.json",
+  "output_schema": "schemas/lane-state-result.v1.json",
+  "permissions": [
+    "algorithm.lane-state",
+    "artifact.read"
+  ],
+  "effects": [
+    "data.read"
+  ],
+  "determinism": "deterministic",
+  "cache_policy": {
+    "mode": "disabled",
+    "allow_bypass": true
+  },
+  "errors": {
+    "VALIDATION": {
+      "category": "source",
+      "description": "字段不在表内、需求不合规，或硬件选型 ID 与修订不成对",
+      "recovery": "correct_input"
+    },
+    "ALGORITHM_HOST": {
+      "category": "config",
+      "description": "宿主没有提供可信的资源读取、内容读写或资源列举端口",
+      "recovery": "await_configuration"
+    }
+  },
+  "result_checks": [
+    {
+      "kind": "output_schema"
+    }
+  ],
+  "completion": "validated_result"
+}

package/skills/abelien-algorithm/actions/algorithm.research.json

@@ -0,0 +1,70 @@
+{
+  "action_id": "algorithm.research",
+  "contract_version": 1,
+  "description": "执行 Agent 的检索计划并保存证据：purpose=implementation 只凭需求检索实现资料（可与硬件选型并行），purpose=hardware 检索已选型号的厂商资料；Volc 检索（每次最多 5 条）与公开 HTTPS 页面安全直读，正文按 sha256 存证；每条付费检索先存 sent 再发送，重跑复用已完成检索、结果未知时要求对账而不重发；同一请求完成后重复运行直接返回已有结果",
+  "audience": "agent",
+  "input_schema": "schemas/research-input.v1.json",
+  "output_schema": "schemas/research-result.v1.json",
+  "permissions": [
+    "algorithm.research",
+    "artifact.read",
+    "artifact.write"
+  ],
+  "effects": [
+    "data.read",
+    "network.read",
+    "artifact.write",
+    "budget.consume"
+  ],
+  "determinism": "nondeterministic",
+  "cache_policy": {
+    "mode": "disabled_by_default",
+    "allow_bypass": true
+  },
+  "errors": {
+    "VALIDATION": {
+      "category": "source",
+      "description": "输入不合规：字段不在表内、用途不对、reaction 不是 1–20 条、库清单重复、检索条目不是 1–8 条或指向不存在的 reaction／零件，或 hardware 用途的选型缺失或修订过期",
+      "recovery": "correct_input"
+    },
+    "ALGORITHM_WEB_CONFIG": {
+      "category": "config",
+      "description": "缺少检索凭据或网络配置非法；在任何请求之前失败",
+      "recovery": "await_configuration"
+    },
+    "ALGORITHM_WEB_CHECKPOINT_REQUIRED": {
+      "category": "config",
+      "description": "计划里有付费检索，但宿主没有提供检查点；在任何请求之前拒绝",
+      "recovery": "await_configuration"
+    },
+    "ALGORITHM_HOST": {
+      "category": "config",
+      "description": "宿主没有提供可信的资源读取、内容读写或资源列举端口",
+      "recovery": "await_configuration"
+    },
+    "ALGORITHM_WEB_RECONCILIATION_REQUIRED": {
+      "category": "unknown",
+      "description": "检查点里有已发送、结果未知的检索，或已存证据与本请求不符；不会自动重发，需对账",
+      "recovery": "reconcile"
+    },
+    "ALGORITHM_WEB_RESPONSE": {
+      "category": "unknown",
+      "description": "检索服务的回执格式不符；按原检查点对账",
+      "recovery": "reconcile"
+    },
+    "CAPABILITY_CHECKPOINT_CONFLICT": {
+      "category": "unknown",
+      "description": "内核码：同一请求并发运行时，后写入检查点者失败",
+      "recovery": "reconcile"
+    }
+  },
+  "result_checks": [
+    {
+      "kind": "output_schema"
+    },
+    {
+      "kind": "ref_integrity"
+    }
+  ],
+  "completion": "validated_result"
+}

package/skills/abelien-algorithm/bindings.json

@@ -0,0 +1,58 @@
+{
+  "schema": "abelien.bindings.v1",
+  "description": "本包的缺省部署 profile：全部动作由本包模块实现。",
+  "bindings": [
+    {
+      "action_id": "algorithm.research",
+      "transport": "module",
+      "location": "local",
+      "effects": [],
+      "cancel": "unsupported",
+      "submission": {
+        "idempotent_submit": true,
+        "query_by_operation": true,
+        "remote_task_identity": "none",
+        "not_found_definitive": false
+      }
+    },
+    {
+      "action_id": "algorithm.candidates",
+      "transport": "module",
+      "location": "local",
+      "effects": [],
+      "cancel": "unsupported",
+      "submission": {
+        "idempotent_submit": true,
+        "query_by_operation": false,
+        "remote_task_identity": "none",
+        "not_found_definitive": true
+      }
+    },
+    {
+      "action_id": "algorithm.lane-state",
+      "transport": "module",
+      "location": "local",
+      "effects": [],
+      "cancel": "unsupported",
+      "submission": {
+        "idempotent_submit": true,
+        "query_by_operation": false,
+        "remote_task_identity": "none",
+        "not_found_definitive": true
+      }
+    },
+    {
+      "action_id": "algorithm.finalize",
+      "transport": "module",
+      "location": "local",
+      "effects": [],
+      "cancel": "unsupported",
+      "submission": {
+        "idempotent_submit": true,
+        "query_by_operation": false,
+        "remote_task_identity": "none",
+        "not_found_definitive": true
+      }
+    }
+  ]
+}