abelien-harness 0.0.0-stage → 0.3.0

package/.env.example

@@ -0,0 +1,48 @@
+# Harness automatically loads .env and then .env.local from its launch directory.
+# Existing process variables take precedence. Never commit real credentials.
+
+TOS_REGION=cn-beijing
+TOS_ENDPOINT=https://tos-s3-cn-beijing.volces.com
+TOS_BUCKET=your-bucket
+TOS_ACCESS_KEY_ID=
+TOS_SECRET_ACCESS_KEY=
+TOS_ADDRESSING_STYLE=virtual
+TOS_WIKI_PREFIX=hardware_profile_wiki/
+
+# Optional runtime controls
+TOS_SEARCH_CONCURRENCY=8
+TOS_MAX_FULL_WIKI_FETCH_PER_SLOT=24
+TOS_PUBLISH_CONCURRENCY=6
+TOS_ALLOW_LEGACY_MANIFEST_FALLBACK=false
+
+# Web deployment aliases are also accepted when the corresponding TOS_* value is absent:
+# CAD_STORAGE_REGION=cn-beijing
+# CAD_STORAGE_ENDPOINT=https://tos-s3-cn-beijing.volces.com
+# CAD_STORAGE_BUCKET=your-bucket
+# CAD_STORAGE_ACCESS_KEY=
+# CAD_STORAGE_SECRET_KEY=
+# CAD_STORAGE_ADDRESSING_STYLE=virtual
+
+# Optional external hardware revision service
+ABELIEN_HARDWARE_REVISE_URL=
+
+# 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=
+
+# Fixed prismer_then_volc policy; both Keys are trusted host-only.
+# Volc subscription/pay-as-you-go search Keys are distinct from Ark generation Keys.
+PRISMER_API_KEY=
+WEB_SEARCH_API_KEY=
+ABELIEN_HARDWARE_WEB_SEARCH_TIMEOUT_MS=30000
+ABELIEN_HARDWARE_WEB_PAGE_TIMEOUT_MS=30000
+# Host budget and loop abort independently bound Parse; unknown POSTs cannot retry.
+ABELIEN_HARDWARE_WEB_PARSE_TIMEOUT_MS=120000
+# system or explicit fixed Cloudflare doh; direct source connections/redirects pin public IP.
+# The submitted URL check alone does not certify remote Prismer redirect pinning.
+ABELIEN_HARDWARE_WEB_DNS_TRANSPORT=system
+
+# Opt-in audit v1: generic workflow definition snapshots and new evidence blobs.
+# Hardware pinned-result-v1 always pins definitions/results; legacy selection runs stay read-only.
+# Runs freeze the evidence mode. Existing references remain readable when false.
+AB_HARNESS_AUDIT_V1=false

package/README.md

@@ -1,3 +1,278 @@
-# Temporary Holding Version
+# AbelienHarness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+npx 可安装的多 agent skill harness：**通用内核 + 可插拔域包**。安装后进入各 agent
+的 skill 路径，agent 通过自带零依赖 CLI `ab` 调度资源定位、能力调度（mock/HTTP API）、
+结构化状态存储与可恢复 workflow。
+
+```text
+定位资源（如外观ID） → 调度能力（如 3D 模型生成/替换） → 组建状态管理 → workflow 编排
+```
+
+内核对领域不感知，随包分发 10 个 bundle。产品层：[abelien-workspace](skills/abelien-workspace/SKILL.md)（旅程、版本与确认）·
+[abelien-guide](skills/abelien-guide/SKILL.md)（对话调度与沟通）· [abelien-clarify](skills/abelien-clarify/SKILL.md)（需求澄清只读快照）。
+领域层：[abelien-hardware](skills/abelien-hardware/SKILL.md)（TOS 候选检索与修订）·
+[abelien-hardware-selection](skills/abelien-hardware-selection/SKILL.md)（本地三级分类选型）·
+[abelien-algorithm](skills/abelien-algorithm/SKILL.md)（基于已验证硬件、官方资料优先的联网算法选型）·
+[abelien-appearance](skills/abelien-appearance/SKILL.md) 与 [abelien-structure](skills/abelien-structure/SKILL.md)（外观与机械结构）·
+[abelien-3dgen](skills/abelien-3dgen/SKILL.md)（四家 provider 的 3D 构件生成，经 `ab generate 3d` 驱动）。
+
+## Quickstart
+
+```bash
+npx abelien-harness install                          # 默认 claude-code 全局
+npx abelien-harness install --target all             # claude-code + hermes + pi
+npx abelien-harness install --project                # 装到 <cwd>/.claude/skills
+npx abelien-harness install --skills-dir /any/dir    # 自定义目录
+npx abelien-harness list | update | remove
+```
+
+npm 上尚无 `abelien-harness` 发布工件（见下文「生产 Studio broker 客户端」的接线边界），
+当前从仓库内等义运行：`node bin/cli.mjs install --target <t>`，其余子命令同理。
+
+安装目标：
+
+| target | 目录 | 覆盖方式 |
+| ------ | ---- | -------- |
+| `claude-code` | `~/.claude/skills/`（`--project` → `<cwd>/.claude/skills/`） | `--skills-dir` |
+| `hermes` | `~/.hermes/skills/` | `HERMES_SKILLS_DIR` / `--skills-dir`（装后需重启 gateway） |
+| `pi` | `~/.pi/skills/` | `PI_SKILLS_DIR` / `--skills-dir` |
+
+安装回执 `<AB_HOME ?? ~>/.abelien/installed.json` 记录各目标与 bundle digest；
+`update` 对摘要比对，本地改动未提交时 fail-closed（`DRIFTED`，`--force` 覆盖）。
+全部目标通过漂移校验后，更新会清理已登记 bundle 在新版中退役的文件；普通 install 不清理未登记文件，其他 skill 与工作目录中的历史产物不受影响。
+**整包退役**：新版不再发布的 bundle（如域包合并后消失的旧域）在 `install` 与 `update` 下都会被整包移除并记入回执，
+避免残留目录被 `ab` 当活域加载（否则出现 `AMBIGUOUS_MACHINE`）；退役包若已被本地改动则不删除，只在安装输出里提示。
+**命名空间守卫**：安装器只增删改 `abelien-*` 前缀的 skill，绝不触碰其他 skill。
+
+## `ab` 命令速查
+
+运行时随内核 bundle 分发：`node <skills目录>/abelien-harness/scripts/ab.mjs <命令>`
+（零 npm 依赖，不依赖全局 PATH / `.bin`）。状态存于 workdir 的 `.abelien/`，
+跨目录操作加 `--workdir <dir>`。
+
+```text
+ab search_hardware <query> --category-path <l1/l2/l3[,..]> | --slots '<json>'
+ab resource put --kind <k> --id <localId> --body '<json>'
+ab resource get <id> | list [--kind <k>] | delete <id> | locate <query>
+ab capability list | run <name> [--input '<json>'] [--resource <id>]
+ab workflow list | run <name> [--input '<json>'] | status <runId> [--httl]
+          | advance <runId> --result '<json>' | --httl '<doc>' | --httl-file <path>
+          | resume <runId> | cancel <runId>
+ab studio probe
+ab studio replacement request --input '<json>'
+ab studio creation create --input '<json>' | active | get <creationOperationId>
+ab studio modification create --input '<json>' | active | get <modificationOperationId>
+ab studio tool register --input '<json>'
+ab studio invocation submit --input '<json>' | get <invocationId>
+ab receipt consume --file <path> | get --wait <waitId> [--digest <sha256>]
+ab machine list | get <name> | send <machine> <event> --instance <id>
+ab domain list | register <path>
+ab generate 3d <providers|submit|status|fetch> …
+ab doctor
+```
+
+输出契约：stdout 恒为单行 JSON——成功 `{ok:true,data}`（exit 0）；
+运行错误 `{ok:false,error:{code,message,details?}}`（exit 1）；
+用法错误同结构写 stderr（exit 2）。
+
+`workflow resume <runId>` 只接原运行 ID，恢复声明 checkpoint/awaitExternal 的原步骤。
+它复用冻结输入、原受信 step.resource 快照和已返回响应；未对账的 paid POST 不重发。
+输入、来源和单调延伸边界见 [workflow 持久协议](docs/architecture/workflow-persistence.md)。
+
+### 生产工具回执与原会话接续
+
+`receipt` 是 workflow 之外的可信收件箱。Web 把 `StudioHarnessReceiptEnvelope` v1 文件投递到
+EaaS 后执行 `abelien-harness receipt consume --file ... --workdir ...`，并用 `getFile` 回读
+`.abelien/receipts/acks/<waitId>.json` 校验 wait 与摘要。随后只把 `waitId/resultDigest` 作为唤醒身份
+交给同一 conversation；Agent 运行 `abelien-harness receipt get --wait ... --digest ... --workdir ...`
+读取已保存 envelope。聊天正文不是工具结果事实源。
+
+consume 的 `status:"consumed"` 只确认落盘：它不调用 `workflow advance`，也不完成当前 Agent step。
+重复同摘要幂等；同 wait 不同摘要冲突；取消或终态运行仍保存回执，但 workflow 观察会标为 terminal，
+不会伪造恢复。完整 envelope、路径、锁和摘要契约见
+[workflow 规范](skills/abelien-harness/references/workflow-spec.md#studio-工具回执收件箱)。
+
+同一 receipt 入口支持严格互斥的 creation/modification 谱系；creation 的 `cad.final` 回执要求精确
+preview 父候选与可信 definitionDigest 等待身份。预览通过、相同源码 final 构建和 final 再审查由 Web
+执行定义约束；本仓新增的只是受信创建客户端（`ab studio creation create|active|get` 回读，见
+[workflow 规范](skills/abelien-harness/references/workflow-spec.md)），没有第二份编排，也未据此宣称 EaaS 已发布或实测通过，既有 unknown 不重发。
+
+### 生产 Studio broker 客户端
+
+托管 Agent 调 Studio 工具时只使用上述 `ab studio` 封闭命令。Web 宿主将 server-fixed Web origin、
+draft／attempt／binding fence 和短期委托 token 写入 attempt 不可变文件，再由 EaaS 内 launcher 以
+0600 临时文件、fsync、rename 激活固定 `current.json`。launcher 按 generation、credential epoch 和
+数据库 attempt 创建时间拒绝晚到旧 attempt 覆盖。CLI 不接受模型提供的 origin、token 或 context
+路径，并在联网前逐项核对 context 与 token claims；Agent 可见输出会移除 policy 身份，provider、
+account、price 不进入该响应。
+
+POST 只对完全相同的序列化正文做一次有界回放；仍未知时返回 `STUDIO_WRITE_UNKNOWN`，调用方只能
+读取原 creation／modification／invocation，或以同一 command／operation 身份精确重放，不能换 ID。工具回执
+仍只用 `receipt get`，绝不调用 `workflow advance`。
+
+当前接线边界：Web 已为普通首轮 production EaaS turn 实现固定 Harness release 安装、
+actionScope／definitionDigest 选择、`state.probe` attempt 投递和同一远端回合内 marker 回调；
+tool-receipt successor 与已有可信 runtime decision 也可以取得后续 context。npm 上仍无可安装的
+`abelien-harness` 发布工件，目标 EaaS 凭据也未配置，所以尚未取得真实 Pi 消费／回执证据；这些
+本地契约与定向测试不能等同于首个真实 Web E2E 已完成。
+
+## Agent 集成
+
+现行入口不再维护独立的“主控业务提示词”。宿主指令只交代身份、skills 的用途、读取／调用方式与授权边界；具体对话调度放在 guide，作品旅程与业务规则放在 workspace，领域工作放在对应 skill。它们可以由同一个宿主 Agent 执行，不需要额外的主控 Agent；旧 controller 文档仅作历史参考，不与 skills 流程重复注入。
+
+- 对话调度与沟通由 [abelien-guide](skills/abelien-guide/SKILL.md) 负责：组织上下文、调用领域 skill、呈现问题和结果；阶段、版本和确认条件统一读取 workspace。
+- 作品规则由 [abelien-workspace](skills/abelien-workspace/SKILL.md) 维护：完整 A1–C、采用与版本、组合检查、确认和交付恢复。其 `user-journey` 是单个 Agent 步骤，Harness 提供通用运行机制；产品服务的实际接入边界见 workspace 调用说明。
+- 需求澄清为 [abelien-clarify](skills/abelien-clarify/SKILL.md)：把用户原话整理成 requirements、区分用户事实与系统假设、只问阻塞当前操作的问题，附只读校验脚本；共用表达规则随 guide 的 references 分发。两者的编辑源在 `abelienwebapplication/docs/agent-prd/v2`，快照对应的 commit 见下文「快照来源」。
+- 各 bundle 均为标准 `SKILL.md`（含 name/description/license/compatibility，
+  兼容 claude-code / hermes / pi），agent 按 description 触发词路由；claude-code 与
+  codex 的双入口收敛（根 `CLAUDE.md` / `AGENTS.md`）见 [docs/architecture/host-adapters.md](docs/architecture/host-adapters.md)。
+- workflow 驱动循环：`run` → 返回 `awaiting_agent` 时读 `steps[cursor].instruction`，
+  agent 判断后 `advance --result '<json>'`（或等价的 `--httl '<doc>'` / `--httl-file <path>`，
+  见 [docs/architecture/httl.md](docs/architecture/httl.md)）提交（只有明确放弃本次运行才 `cancel`；产品修改保持共创）→ 循环至终态。
+- 域包靠**同级目录自动发现**：与 `abelien-harness` 同 skills 目录的
+  `abelien-*/domain.json` 无需注册即可用；非标准布局用 `ab domain register`。
+- 协议细节见 `skills/abelien-harness/references/`（kernel-protocol /
+  adapter-contract / workflow-spec）。
+
+## 产品旅程与 PRD
+
+完整规则统一维护在 [workspace 用户旅程](skills/abelien-workspace/references/user-journey.md)。`user-journey` 是一个 Agent 驱动入口：A1–C 的判断与回流发生在 `drive-product-journey` 步骤内；必要答案、证据或能力未齐时保持暂停，真实同版确认快照保存并交代交付状态后才提交交接。JSON 的 `journey` 不由内核自动解释，`done` 不能证明产品确认。具体恢复及旧实例迁移见 [调用说明](skills/abelien-workspace/references/harness-binding.md)。
+
+```bash
+node skills/abelien-harness/scripts/ab.mjs --workdir <作品工作目录> workflow run user-journey --input '{"prompt":"用户真实创作意图"}'
+# awaiting_agent@drive-product-journey → Agent 按 workspace 规则、通过 guide 调度，在同一步骤内跨轮推进
+```
+
+### PRD 随需求对话维护
+
+PRD 以用户指定的飞书模板 revision 191 为结构依据，保留七块总览、逐条需求清单与图片引用；从 A1 起每轮登记／修改／撤回需求，保留 ID、来源与历史，选型和检查回来后再更新关联行。定义与写入语义集中在 [PRD 契约](skills/abelien-workspace/references/prd-contract.md)，模板随 workspace 安装。产品写入／回读接口尚未接入，不能把规则声明说成自动写入已实现。
+
+`user-journey-mock`、专属 workspace mock 能力和 draft／quote 样例状态机已移除，旧记录与 [MVP 实录](docs/mvp/journey.md) 仅用于历史核对，不再提供运行入口。当前 eval 共五条场景：`user-journey-entry` 只验证入口暂停，不表示产品 E2E 通过；`user-journey-cancelled` 验证取消是**终态**（落 `cancelled` 后 `advance` 与再次 `cancel` 都被拒）；`user-journey-hardware-verified` 与 `user-journey-hardware-pending-confirmation` 经**场景 http 桩**端到端驱动硬件阶段的接线（Agent 槽位真的进了请求体、选型资源落库、draft 记下 id 与 status）与门禁（`verified` 过门落 `selected`；`needs_confirmation` 不再被拒——不执行算法，以 `selected_pending_confirmation` 正常完成，仍不宣称 `verified`；`failed`／`unknown` 依旧 `GUARD_FAILED`）；`user-journey-hardware-candidates` 驱动**候选提案**路径（本地 `hardware.search` 按受控三级路径读 TOS，`hardware.finalize` 归一化为提案），三条实况断言锁 Catalog／索引／Wiki 各被真实读一次，且 draft 不带 `hardwareSelectionId`（候选不产生正式选型）。桩是评估进程内的假服务，**不**证明选型质量，也**不**证明服务端已就位。
+基础需求足够后推进首版；guide 在宿主实际展示条件满足时通过可选选择题卡片邀请交互细化并告知可“随时收尾”。PRD 从已保存需求起可读，不强制展开或增加文档确认关卡。收尾切入同一作品的[成果体验](skills/abelien-workspace/references/user-journey.md#result-experience)：收起全部编辑面板，有可运行仿真就进入仿真，否则按真实播放器能力提供 Three.js 状态动作演示；保留 PRD 查看／草稿或确认版导出及返回编辑入口。展示模式与方案确认独立，不能用收尾、演示状态或草稿导出触发 workflow 完成。宿主 UI／播放器仍须实际接入，历史入口测试不证明体验已实现。
+
+### 真实硬件阶段
+
+另有独立的 `user-journey-hardware` 阶段流程：输入 clarify 交回的 Requirements（context / reaction[] / limits[]，每条须带 `source ∈ {user,system}`、非空 `text` 与全局唯一 `id`，limits 另有 `strength ∈ {hard,preference}`；格式不合规在读取任何可信召回之前即失败），在 agent 暂停点按需加载同级 `abelien-hardware-selection` 的三级分类规则，再将槽位交给 `hardware.select`——它是该域包 `domain.json` 声明的 `{type:"module"}` 本地 adapter（`scripts/select.mjs`），不连网络、无服务端 URL。主流程先 TOS 搜索、再 Agent 证据判断、最后本地 `hardware.select`；未知不通过门禁。契约见选型域 selection-service-contract；verified 不是工程实测。算法与外观真实阶段尚未接到该流程。分类规则快照的来源见下文「快照来源」。
+
+### TOS 候选检索工具
+
+`hardware.search` 独立读取候选 Wiki，正式选型仍通过 `hardware.select`；TOS 结果不自动通过硬件选型门禁。
+
+发布搜索索引前，从同一份 `_manifest.json` 和 Markdown 构建分类索引；完整 Wiki 无需复制。先做不连接 TOS 的校验：
+
+```bash
+npm run publish:hardware-search-index -- \
+  --source /absolute/path/to/硬件wiki \
+  --dry-run
+```
+
+复制 `.env.example` 为 `.env.local` 并填写真实服务端配置后，一条命令完成版本化上传、远端全量校验、Catalog 最后激活和真实读取冒烟：
+
+```bash
+npm run publish:hardware-search-index -- \
+  --source /absolute/path/to/硬件wiki \
+  --env-file .env.local
+```
+
+（`--env-file` 与 Node ≥ 20.6 的自身选项同名，会被 Node 先截走且不从 argv 摘除：文件存在时恰好两边读数一致，路径写错时收到的却是 `node: <file>: not found` 与 exit 9，而非本工具的 JSON 错误。要稳定的失败语义就用 `AB_ENV_FILE=.env.local`。）
+
+如果旧上传器只上传了 Wiki Markdown、云端尚无 `_manifest.json`，首次加 `--bootstrap-manifest`；发布器会先逐个验证全部远端 Wiki 后才创建 Manifest。后续正常发布不再需要该参数。
+
+也可分别运行 `npm run verify:hardware-search-index` 和 `npm run smoke:hardware-search`。搜索默认要求索引存在；缺少 `_catalog.json` 会返回 `WIKI_SEARCH_INDEX_MISSING`，不会静默下载整个分类。迁移期可显式设置 `TOS_ALLOW_LEGACY_MANIFEST_FALLBACK=true`，但响应会标记 `legacy_manifest_full_scan`，不应作为长期生产配置。格式见 [search-index-format.md](skills/abelien-hardware/references/search-index-format.md)，发布操作见 [search-index-release.md](skills/abelien-hardware/references/search-index-release.md)。
+
+在本仓库内启动硬件阶段：
+
+```bash
+export TOS_REGION='cn-beijing'
+export TOS_ENDPOINT='https://tos-s3-cn-beijing.volces.com'
+export TOS_BUCKET='your-bucket'
+export TOS_ACCESS_KEY_ID='...'
+export TOS_SECRET_ACCESS_KEY='...'
+export ABELIEN_HARDWARE_REVISE_URL='https://your-selector.example/revise'
+node skills/abelien-harness/scripts/ab.mjs workflow run user-journey-hardware --input '{"requirements":{"context":{"text":"放在桌面上","source":"user"},"reaction":[{"id":"r-turn","text":"有人靠近时转头看向对方","source":"user"}],"limits":[{"id":"l-net","text":"不能联网","source":"user","strength":"hard"}]}}'
+# 返回 awaiting_agent 后，按请求读取 skills/abelien-hardware/SKILL.md，
+# 用其 scripts/load-guide.mjs 逐层加载规则，再对该 run 执行 workflow advance --result '{"slots":[...]}'。
+```
+
+示例中的凭据均为占位符。`ab` 和发布命令会自动读取启动目录的 `.env`、`.env.local`，进程变量优先；也接受 Web 部署使用的 `CAD_STORAGE_*` 别名。单元测试使用内存对象存储；只有发布命令末尾或独立 `smoke:hardware-search` 的目标环境结果才是生产连通性证据。
+
+## 写自己的域包
+
+最小结构（参考 `skills/abelien-hardware/`）：
+
+```text
+abelien-<slug>/
+├── SKILL.md          # 触发描述 + 驱动指引
+├── domain.json       # resources + capabilities（声明式 adapter）＋可选 requires
+├── workflows/*.json  # cli/agent 步骤混合的编排
+└── references/       # 领域文档（可选 scripts/ 放本地实现）
+```
+
+能力有三种 adapter 形状：`{type:"mock"}`（确定性派生，`{{hash}}` 保证测试可重复）、
+`{type:"http", ...}`（声明式调远端）、`{type:"module", ...}`（指向本包 `scripts/*.mjs` 的
+本地实现，如选型域的 `hardware.select`）。换 adapter 不改 `ab capability` / workflow 接口。
+
+域包若要在运行期 import 同级的另一个 bundle，把对方写进 `domain.json` 的
+**`requires`**（如 `abelien-hardware-selection` 声明 `["abelien-harness","abelien-hardware"]`）。
+skill-lint 双向守卫核对声明与实际 import 一致，打包校验再确认声明的包确实在包里
+——缺包在运行期只会是 `Cannot find module`。
+
+## 范式
+
+- 总纲（测试 · 评估 · 优化一体，同一场景工件的三种消费模式）：
+  [docs/paradigms/README.md](docs/paradigms/README.md)
+- 四篇：[开发](docs/paradigms/development.md) · [测试](docs/paradigms/testing.md) ·
+  [评估](docs/paradigms/evaluation.md) · [自递归优化](docs/paradigms/self-optimization.md)
+- 开发循环的操作手册（SDD 三角色/三脚本，claude-code 与 codex 双宿主同一循环）：
+  [docs/paradigms/development.md](docs/paradigms/development.md) §1
+- 架构侧配套论述：`docs/architecture/`（八篇：双层状态机、持久化哲学、HTTL、宿主适配、
+  3D 异步任务引擎、外观／结构协作边界、问题卡协议、可视化与自进化收口）
+
+## 文档地图
+
+完整产品用户旅程统一从 [Abelien 完整用户旅程](skills/abelien-workspace/references/user-journey.md) 阅读：两入口、A1–C 判断、修改回流、确认交付及分享预订。reference / mvp 保留来源与旧 mock 实录。
+
+`docs/` 分四层：**architecture**（本仓设计论述）→ **paradigms**（工程范式）→
+**reference**（对向工程文档的平移整合）→ **mvp**（验收与覆盖）。
+
+| 层 | 篇目 | 一句话 |
+| --- | --- | --- |
+| 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) / [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 步及真实实录）· 四维覆盖矩阵 + 缺口账本 |
+
+## 开发
+
+```bash
+npm test        # node --test（零依赖，含单元/契约/e2e smoke/docs-lint/skill-lint）
+npm run eval    # 5 条场景（入口暂停 + 取消终态 + 硬件阶段正例/门反例 + 候选提案，后三条经场景 http 桩），报告 append-only 落 eval/reports/
+npm run branch:new|sync|push:ready|land   # 分支纪律：切分支 / rebase 同步 / 绿了才推 / FF-only 落 main
+```
+
+设计文档：`docs/superpowers/specs/2026-09-16-abelien-harness-design.md`。
+
+### 快照来源
+
+`abelien-clarify`（含 guide 的 shared-response-rules）的规则正文是外部编辑源的只读快照，
+来源仓 URL、分支、完整 commit 与源内路径集中登记在 [tools/snapshot-sources.json](tools/snapshot-sources.json)：
+
+| 快照 | 来源 | 本地挂载（`checkout`，相对本仓） |
+| --- | --- | --- |
+| clarify | abelienwebapplication `develop` 的 `docs/agent-prd/v2` | `../abelienwebapplication`，`git fetch` 到锚定 commit 即可 |
+
+- `npm run sync:clarify` 默认从锚定 commit 的 git 对象同步，加 `--check` 只校验；`prepack` 跑它的 `--check`，
+  工作区里未提交的源改动不影响结果。硬件分类规则不再是外部快照：唯一正文就在
+  `skills/abelien-hardware/references/hardware-selection/`，`prepack` 以 `validate:hardware-selection-snapshot` 校验其完整性。
+- 升级快照：设置 `ABELIEN_AGENT_PRD_DIR` 指向新版源目录同步，经内容责任人审过后，
+  再把 `snapshot-sources.json` 的 commit 改成新版源已提交的 commit（未提交的源不能作为锚点）。
+- 锚定 commit 在本地不可得时，`--check` 打印挂载提示并跳过（fail-open，未设 CI 兜底）。
+- 2026-10-03 核对：clarify 五个同步文件在锚点 `f370e49e`→`f269c4b0` 间逐字节一致，更新的是
+  锚点记录而非快照正文。必要问题的选项上限沿用 clarify 的 `result / questions / note` 契约
+  （最多三个，可少于三个或纯自由输入），workspace 不设“恰好三个”下限；B3 的两项确认邀请与
+  确认门仍归 workspace。该对齐收口 [!2 note_545](https://git.abelien.cn/abelien/abelienharness/-/merge_requests/2#note_545)，
+  不代表真实产品旅程已验收。
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// bin/cli.mjs — npx 安装器入口（分发载体；装完后运行时不依赖 npm）
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { install, update, remove, listInstalled } from "../lib/installer.mjs";
+import { TARGET_NAMES } from "../targets/registry.mjs";
+import { consumeStudioReceipt, readStudioReceipt } from "../skills/abelien-harness/scripts/receipt.mjs";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+function flag(name) {
+  const i = args.indexOf(`--${name}`);
+  if (i < 0) return undefined;
+  const v = args[i + 1];
+  return v === undefined || v.startsWith("--") ? true : v;
+}
+const has = name => args.includes(`--${name}`);
+const skillsDir = typeof flag("skills-dir") === "string" ? flag("skills-dir") : undefined;
+const opts = {
+  packageRoot,
+  target: flag("target"),
+  project: has("project"),
+  skillsDir,
+  force: has("force"),
+};
+
+function print(results) {
+  for (const r of results) {
+    const action = r.removed ? `removed ${r.removed.join(", ")}` : `installed ${r.slugs.join(", ")}`;
+    console.log(`${path.basename(r.skillsDir)}: ${action} -> ${r.target} (${r.skillsDir})`);
+    if (r.retired?.length) console.log(`  retired: ${r.retired.join(", ")}（新版已不再发布，整包移除）`);
+    if (r.keptRetired?.length) console.log(`  kept: ${r.keptRetired.join(", ")}（本地有改动，未删除；确认后可手动移除）`);
+    for (const n of r.notes ?? []) console.log(`  note: ${n}`);
+  }
+}
+function usage() {
+  console.error(`usage: abelien-harness <install|update|remove|list> [--target ${TARGET_NAMES.join("|")}|all] [--project] [--skills-dir <dir>] [--force]
+       abelien-harness receipt consume --file <path> [--workdir <dir>]
+       abelien-harness receipt get --wait <waitId> [--digest <sha256>] [--workdir <dir>]`);
+  process.exit(2);
+}
+
+try {
+  switch (cmd) {
+    case "install": print(install(opts)); break;
+    case "update":  print(update(opts)); break;
+    case "remove":  print(remove(opts)); break;
+    case "list":    console.log(JSON.stringify(listInstalled({ env: process.env }), null, 2)); break;
+    case "receipt": {
+      const sub = args[1];
+      const workdir = typeof flag("workdir") === "string" ? path.resolve(flag("workdir"))
+        : process.env.AB_WORKDIR ? path.resolve(process.env.AB_WORKDIR) : process.cwd();
+      if (sub === "consume" && typeof flag("file") === "string") {
+        console.log(JSON.stringify(await consumeStudioReceipt({ workdir, file: flag("file") })));
+      } else if (sub === "get" && typeof flag("wait") === "string") {
+        console.log(JSON.stringify(readStudioReceipt({ workdir, waitId: flag("wait"), resultDigest: flag("digest") })));
+      } else usage();
+      break;
+    }
+    default: usage();
+  }
+} catch (e) {
+  console.error(`abelien-harness: ${e.code ?? "INTERNAL"}: ${e.message}${e.details ? ` ${JSON.stringify(e.details)}` : ""}`);
+  process.exit(String(e.code ?? "").startsWith("USAGE") ? 2 : 1);
+}

package/lib/bundle.mjs

@@ -0,0 +1,41 @@
+// lib/bundle.mjs
+import fs from "node:fs";
+import path from "node:path";
+import { canonicalJson, sha256Hex } from "../skills/abelien-harness/scripts/ab.mjs";
+
+export function listBundleFiles(dir, prefix = "") {
+  const out = [];
+  for (const d of fs.readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${d.name}` : d.name;
+    if (d.isDirectory()) out.push(...listBundleFiles(path.join(dir, d.name), rel));
+    else out.push(rel);
+  }
+  return out.sort();
+}
+
+export function bundleManifest(skillsRoot) {
+  const out = [];
+  for (const d of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (!d.isDirectory() || !d.name.startsWith("abelien-")) continue;   // 命名空间守卫
+    const dir = path.join(skillsRoot, d.name);
+    const files = {};
+    for (const rel of listBundleFiles(dir)) files[rel] = sha256Hex(fs.readFileSync(path.join(dir, rel), "utf8"));
+    out.push({ slug: d.name, dir, files, digest: sha256Hex(canonicalJson(files)) });
+  }
+  return out.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+export function copyBundle(entry, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const rel of Object.keys(entry.files)) {
+    const dest = path.join(destDir, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(path.join(entry.dir, rel), dest);
+  }
+}
+
+export function installedDigest(slugDir) {
+  const files = {};
+  for (const rel of listBundleFiles(slugDir)) files[rel] = sha256Hex(fs.readFileSync(path.join(slugDir, rel), "utf8"));
+  return sha256Hex(canonicalJson(files));
+}

package/lib/installer.mjs

@@ -0,0 +1,135 @@
+// lib/installer.mjs
+import fs from "node:fs";
+import path from "node:path";
+import { targets, homeDir } from "../targets/registry.mjs";
+import { bundleManifest, copyBundle, installedDigest, listBundleFiles } from "./bundle.mjs";
+import { atomicWriteJson, readJson, fail } from "../skills/abelien-harness/scripts/ab.mjs";
+
+const receiptFile = env => path.join(homeDir(env), ".abelien", "installed.json");
+const readReceipt = env => (fs.existsSync(receiptFile(env)) ? readJson(receiptFile(env)) : { version: 1, installs: [] });
+const writeReceipt = (env, r) => atomicWriteJson(receiptFile(env), r);
+
+function resolveTargets({ target, project, skillsDir, env }) {
+  const names = target === "all" ? Object.keys(targets) : [target ?? "claude-code"];
+  for (const n of names) if (!targets[n]) throw fail("USAGE", `unknown target: ${n} (known: ${Object.keys(targets).join(", ")})`);
+  return names.map(n => ({
+    name: n,
+    dir: skillsDir ? path.resolve(skillsDir) : targets[n].skillsDir({ project, env }),
+  }));
+}
+
+// 整包退役：回执登记过、本次包中已不再发布的 bundle（如域包合并后的旧域）必须整体移除，
+// 否则残留目录会被 ab discoverDomains 当活域加载，造成机器/能力二义（AMBIGUOUS_MACHINE）。
+// 命名空间守卫同 remove；摘要不符（本地改过）的退役包保留不动，只上报，绝不静默删用户改动。
+function retiredBundles(receipt, t, publishedSlugs, force) {
+  const record = receipt.installs.find(i => i.target === t.name && i.skillsDir === t.dir);
+  const removed = [];
+  const kept = [];
+  for (const [slug, entry] of Object.entries(record?.bundles ?? {})) {
+    if (!slug.startsWith("abelien-") || publishedSlugs.has(slug)) continue;
+    const dest = path.join(t.dir, slug);
+    if (!fs.existsSync(dest)) continue;
+    if (force || installedDigest(dest) === entry.digest) removed.push({ slug, dest });
+    else kept.push({ slug, entry });
+  }
+  return { removed, kept };
+}
+
+function doInstall(opts, retiredFiles = new Map()) {
+  const { packageRoot, target, project, skillsDir, env = process.env } = opts;
+  const manifest = bundleManifest(path.join(packageRoot, "skills"));
+  if (!manifest.length) throw fail("EMPTY_BUNDLE", "no abelien-* skill bundles found in package");
+  const publishedSlugs = new Set(manifest.map(m => m.slug));
+  const receipt = readReceipt(env);
+  const results = [];
+  for (const t of resolveTargets({ target, project, skillsDir, env })) {
+    fs.mkdirSync(t.dir, { recursive: true });
+    const { removed: retired, kept: keptRetired } = retiredBundles(receipt, t, publishedSlugs, opts.force);
+    const bundles = {};
+    for (const entry of manifest) {
+      const dest = path.join(t.dir, entry.slug);
+      copyBundle(entry, dest);
+      // update 已对全部目标完成回执／漂移校验；只清理该受管 bundle 的退役文件。
+      // 复制成功后才删除，普通 install 不清理未登记的用户文件。
+      for (const rel of retiredFiles.get(dest) ?? []) fs.unlinkSync(path.join(dest, rel));
+      retiredFiles.delete(dest); // 多个 target 可共享同一显式 skillsDir，避免重复清理。
+      bundles[entry.slug] = { digest: entry.digest };
+    }
+    for (const r of retired) fs.rmSync(r.dest, { recursive: true, force: true });
+    // 未被清理的退役包仍留在回执里：下一次 install/update 会再试（用户还原本地改动后即可清除）。
+    for (const k of keptRetired) bundles[k.slug] = k.entry;
+    results.push({
+      target: t.name,
+      skillsDir: t.dir,
+      slugs: manifest.map(m => m.slug),
+      notes: targets[t.name].notes,
+      retired: retired.map(r => r.slug),
+      keptRetired: keptRetired.map(k => k.slug),
+    });
+    const record = { target: t.name, skillsDir: t.dir, installedAt: new Date().toISOString(), bundles };
+    const existing = receipt.installs.find(i => i.target === t.name && i.skillsDir === t.dir);
+    if (existing) Object.assign(existing, record); else receipt.installs.push(record);
+  }
+  writeReceipt(env, receipt);
+  return results;
+}
+
+export const install = doInstall;
+
+export function update(opts) {
+  const { packageRoot, target, project, skillsDir, force, env = process.env } = opts;
+  const manifest = bundleManifest(path.join(packageRoot, "skills"));
+  const receipt = readReceipt(env);
+  const drifted = [];
+  const retiredFiles = new Map();
+  for (const t of resolveTargets({ target, project, skillsDir, env })) {
+    const record = receipt.installs.find(i => i.target === t.name && i.skillsDir === t.dir);
+    if (!record) throw fail("NOT_INSTALLED", `${t.name} at ${t.dir} is not installed; run install first`);
+    for (const entry of manifest) {
+      const dest = path.join(t.dir, entry.slug);
+      const recorded = record.bundles[entry.slug]?.digest;
+      if (fs.existsSync(dest) && recorded) {
+        if (installedDigest(dest) !== recorded) drifted.push({ target: t.name, slug: entry.slug });
+        retiredFiles.set(dest, listBundleFiles(dest).filter(rel => !Object.hasOwn(entry.files, rel)));
+      }
+    }
+  }
+  if (drifted.length && !force) {
+    throw fail("DRIFTED", "installed bundles were modified since install; use --force to overwrite", { drifted });
+  }
+  return doInstall(opts, retiredFiles);
+}
+
+export function remove({ target, project, skillsDir, env = process.env }) {
+  const receipt = readReceipt(env);
+  const keep = [];
+  const results = [];
+  const tss = resolveTargets({ target, project, skillsDir, env });
+  for (const inst of receipt.installs) {
+    if (!tss.some(t => t.name === inst.target && t.dir === inst.skillsDir)) { keep.push(inst); continue; }
+    const removed = [];
+    for (const slug of Object.keys(inst.bundles)) {
+      if (!slug.startsWith("abelien-")) continue;   // 命名空间守卫（纵深防御）
+      fs.rmSync(path.join(inst.skillsDir, slug), { recursive: true, force: true });
+      removed.push(slug);
+    }
+    results.push({ target: inst.target, skillsDir: inst.skillsDir, removed });
+  }
+  receipt.installs = keep;
+  writeReceipt(env, receipt);
+  return results;
+}
+
+export function listInstalled({ env = process.env }) {
+  return readReceipt(env).installs.map(i => ({
+    target: i.target,
+    skillsDir: i.skillsDir,
+    installedAt: i.installedAt,
+    bundles: Object.fromEntries(Object.entries(i.bundles).map(([slug, b]) => {
+      const dest = path.join(i.skillsDir, slug);
+      let state = "missing";
+      if (fs.existsSync(dest)) state = installedDigest(dest) === b.digest ? "ok" : "drifted";
+      return [slug, state];
+    })),
+  }));
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "abelien-harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "npx-installable multi-agent skill harness: generic kernel + pluggable domain packs",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "abelien-harness": "bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "targets/",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "eval": "node eval/run.mjs",
+    "prepare": "node scripts/install-hooks.mjs",
+    "branch:new": "node scripts/new-branch.mjs",
+    "sync": "node scripts/sync.mjs",
+    "push:ready": "node scripts/push-ready.mjs",
+    "land": "node scripts/land.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "release": "node scripts/release.mjs",
+    "build:hardware-search-index": "node skills/abelien-hardware/scripts/build-search-index.mjs",
+    "validate:hardware-selection-snapshot": "node skills/abelien-hardware/scripts/validate-selection-snapshot.mjs",
+    "publish:hardware-search-index": "node skills/abelien-hardware/scripts/publish-search-index.mjs",
+    "verify:hardware-search-index": "node skills/abelien-hardware/scripts/verify-search-index.mjs",
+    "smoke:hardware-search": "node skills/abelien-hardware/scripts/smoke-search-index.mjs",
+    "sync:hardware-selection": "node tools/sync-hardware-selection.mjs",
+    "sync:clarify": "node tools/sync-clarify.mjs",
+    "prepack": "npm run validate:hardware-selection-snapshot && node tools/sync-hardware-selection.mjs --check --strict && node tools/sync-clarify.mjs --check"
+  },
+  "license": "MIT"
+}