modsmith 0.6.2 → 0.7.1

package/AGENTS.md

@@ -61,12 +61,18 @@
   `manifest-io` / `calibrate-core` / `server-fingerprint` / `recipes` / `recipes-join` /
   `cortico-bridge` 的注入实现），测试覆盖它们；只有必须连服务器的（`calibrate` /
   `probe` / `verify` / `sidecar --build` / `recipes` 的捕获）才写 CLI 集成测试。
+- 清单/ids 改完先跑 `modsmith conformance`；`onboard` 已在 inspect 后和 ids 后自动跑，
+  fail 就停在 probe/sidecar 之前。碰撞/作物/实体规则只留在 `block-shapes.mjs` 一份。
 - **测试不许依赖本机路径**：用 `test/fixtures/tiny-mod.jar`（2.8KB 合成夹具，覆盖了
   单数/复数资源目录、tag 展开、作物推断、旧版 loot_tables）。
 - 每个真实事故都在 `test/` 里留一条回归。已经钉住的有：
   - `sidecar --no-build` 不许改清单
   - `inspect` 给了 `--pack` 不许提示"已有同名 mod"（会指回自己刚写的）
   - 去重与嫌疑判据的形状（`test/calibrate-core.test.mjs`：块内重复、放置 id 优先认领）
+  - 模板 state 索引**最后一个属性最快变化**（`test/block-shapes.test.mjs`：
+    按第一个属性最快算会让台阶上下形状互换；形状非空所以只查非空的检查发现不了）
+  - 串多步的 CLI 不会自己退出（`test/rcon.test.mjs`：RCON socket 必须能 `close()`；
+    onboard 走完 probe + verify 后曾挂住 20 分钟）
 - 判据写进日志/回执里时要能对上：报告的数字必须是**实际用到的那个数**
   （例如状态数按去重后累加，不按测量条数）。
 - **多包共用一个服务器时**：捕获的 `declare_recipes` 是整服快照，每份清单都会含别的包

package/README.md

@@ -1,5 +1,6 @@
 # modsmith
 
+[![npm](https://img.shields.io/npm/v/modsmith)](https://www.npmjs.com/package/modsmith)
 [![release](https://img.shields.io/github/v/release/xiaoxiao150/modsmith)](https://github.com/xiaoxiao150/modsmith/releases)
 [![tests](https://github.com/xiaoxiao150/modsmith/actions/workflows/test.yml/badge.svg)](https://github.com/xiaoxiao150/modsmith/actions/workflows/test.yml)
 [![license](https://img.shields.io/github/license/xiaoxiao150/modsmith)](LICENSE)
@@ -9,9 +10,10 @@
 items, recipes, tags, crops) plus **measured registry ids** that any mineflayer
 bot can use. It solves Minecraft 1.21's static-registry problem: mod blocks and
 items are never downloaded, their numeric ids depend on load order, and recipes
-live in serializers the bot doesn't know. modsmith reads the jar, measures the
-ids on a live server you own (OP + RCON), and fingerprints the result. It is the
-data layer for an AI companion that actually plays modded Minecraft.
+live in serializers the bot doesn't know. modsmith reads the jar, then either
+dumps the server registry (seconds, bundled dump mod) or falls back to measuring
+on a live server (OP + RCON), and fingerprints the result. It is the data layer
+for an AI companion that actually plays modded Minecraft.
 
 **中文一句话：**把 Fabric 模组 jar 变成机器人能读、能用的语义清单和实测数字 id；
 让她看得见模组方块、做得出模组配方、放得下模组装饰。
@@ -20,6 +22,28 @@ data layer for an AI companion that actually plays modded Minecraft.
 > modsmith 负责把她面前的任意模组变成可读的配方/站点/id 数据。
 > 方向与阶段见 [ROADMAP.md](ROADMAP.md)。
 
+## 接包时间：3 小时 → 几秒
+
+以前接一个大包要逐个 block state 做 `setblock` + 回读：TF 523 方块 / **17255 个状态**
+要跑 1.5 小时，Supplementaries 14996 个状态要接近 1 小时。现在：
+
+| | 逐状态 `calibrate` | `registry-dump` |
+|---|---|---|
+| 时间 | TF 约 1.5h，Supp 约 1h | dump + import，**秒级** |
+| 需要 | 服务器 + OP + RCON + 一个裸 bot | 服务端装一个 4KB 只读 mod，重启一次 |
+| 覆盖 | 清单声明的状态子集 | 服务端注册表的全部状态 |
+| 风险 | 区块失新/残留读数，靠自检兜底 | 注册表真值；只读、不注册内容 |
+
+jar 已经**内置在 modsmith 里**：`templates/registry-dump/modsmith-dump-0.1.2.jar`；
+`modsmith dump-jar` 直接打印路径，`onboard` 会自动找 `config/modsmith-dump.json`。
+仍然不会自动安装——装/删由人决定，因为那是改用户的服务器，不是改本地文件。
+
+dump 不只量 id：0.1.2 起同时导出实体注册表（名字、数字 id、生成组、碰撞箱）。
+没有这张表，暮色森林的 boss 在机器人眼里一律叫 `unknown`——她被娜迦打死了，
+战斗日志里连对手的名字都没有。
+
+dump 只替代 **id 测量**：`probe` / `verify` / `recipes` / `learn` 照样要跑。
+
 ## 没有它 / 有它
 
 | | 没有 modsmith | 有 modsmith |
@@ -37,7 +61,14 @@ data layer for an AI companion that actually plays modded Minecraft.
 
 ## 30 秒看到结果
 
-不需要服务器、不需要 npm install（`inspect` 只读 jar）：
+不需要服务器；`inspect` 只读 jar。已发布到 npm：
+
+```bash
+npm i -g modsmith          # 或者零安装：npx modsmith ...
+modsmith inspect path/to/mod.jar --out ./mods
+```
+
+不想装 npm 包也可以直接跑仓库：
 
 ```bash
 git clone --depth 1 https://github.com/xiaoxiao150/modsmith
@@ -47,25 +78,51 @@ node modsmith/bin/modsmith.mjs inspect path/to/mod.jar --out ./mods
 输出是 `mods/<pack>.json`：方块、物品、配方类型、tag、作物都在里面。要让它变成
 机器人真能用的数字 id，再按 [快速开始](#快速开始) 起一台自己的服务器跑 `calibrate`。
 
-> npm 包（`npx modsmith ...`）正在准备；发布前上面的 git 一行就是最短路径。
-
 ## 支持的包（实测，不是“理论上”）
 
 | 包 | MC / 依赖 | 覆盖 | 备注 |
 |---|---|---|---|
-| Farmer's Delight 3.3.6 | 1.21.1 / Fabric API | 131/132 方块、185/187 物品、1594 条可用配方 | 生产在用；站点 `cutting_board`/`cooking_pot` 已验证 |
-| Supplementaries 4.0.2 | 1.21.1 / Moonlight 3.7.2 | 237/271 方块、248/297 物品、306 条可用配方 | 装饰验收：两间 5×5 房间、25 件装饰 |
-| Twilight Forest 4.8.796 | 1.21.1 / Fabric | 接包中（4.8.629 的 2134 条配方存档） | 独立 TF 服，下一步 |
+| Farmer's Delight 3.3.6 | 1.21.1 / Fabric API | 131/131 方块、185/185 物品、1594 条可用配方 | 生产在用；站点 `cutting_board`/`cooking_pot` 已验证 |
+| More Delight 26.04.30 | 1.21.1 / FD | 0 方块、37/38 物品、51 条配方 | 农夫乐事扩展；纯物品/配方 |
+| Supplementaries 4.0.2 | 1.21.1 / Moonlight 3.7.2 | 237/237 方块、248/248 物品、306 条可用配方 | 装饰验收：两间 5×5 房间、25 件装饰 |
+| Twilight Forest 4.8.796 | 1.21.1 / Fabric API | 523/523 方块、660/718 物品、540 条配方、17255 状态 | 生产在用；9 个 boss 与实体名已进清单，维度传送待验 |
 
-缺失的方块不是“漏了”，是服务器没注册的兼容/技术方块；清单按实测裁剪，
+缺失的方块/物品不是“漏了”，是服务器没注册的兼容/技术变体；清单按实测裁剪，
 不会把装不出来的东西列给机器人。
 
-**预生成参考包**：[modsmith-0.6.2-reference-packs.zip](https://github.com/xiaoxiao150/modsmith/releases/download/v0.6.2/modsmith-0.6.2-reference-packs.zip)
+**预生成参考包（0.6.2，FD + Supplementaries）**：[modsmith-0.6.2-reference-packs.zip](https://github.com/xiaoxiao150/modsmith/releases/download/v0.6.2/modsmith-0.6.2-reference-packs.zip)
 （两份 manifest + 对应 ids + 精确 mod 列表）。manifest 可直接复用；`-ids.json`
 带服务器指纹，只对压缩包内 `SERVER-MODS.md` 那套完全相同的 mod 组合有效——
-换了 jar 请重新 `calibrate --fresh`，不要混用。
-
-## 状态（0.6.2，AI 陪伴：生活 / 装饰 / 冒险）
+换了 jar 请重新 dump/calibrate，不要混用。
+
+## 状态（0.7.1，AI 陪伴：生活 / 装饰 / 冒险）
+
+> 发布说明：npm registry 上的最新包仍是 **0.6.2**；0.7.1 目前以本仓库 / GitHub
+> release 为准（npm 发布账号还在安全暂停期）。不想等可以 `git clone` 后直接跑
+> `node bin/modsmith.mjs`。
+
+- **0.7.1（live 采样与形状索引修正）**：`conformance --live` 增加 RCON 写世界采样
+  （setblock 后等真实 `stateId` 再读 `shapes`，含上下两态对照），dev 服 FD 实测
+  40/9/0，报告在 [docs/conformance](docs/conformance/README.md)。采样抓出并修复
+  `templateShapeId` 的 P0：状态索引应按**最后一个属性最快**变化，原实现反了，导致
+  台阶 top/bottom 形状互换（楼梯同理）；`block-shapes.test.mjs` 已钉住。
+  `onboard` 支持 `--serializers` 显式指 sidesheet；RCON socket 现在会 `close()`，
+  `onboard` 九步跑完后进程不再挂住。`verify` 对没有写回命令的侧车站点显式报
+  “已知但未验”（不再是失败）；推断阶段也不再生成侧车命令，命令只由编译成功的
+  `sidecar` 写回。
+- **0.7.0（接包验收）**：新增 `modsmith conformance`（manifest/ids/registry 三层离线
+  检查）与只读 `--live` 参考消费；`onboard` 9 步里有两道早停。四包实测 0 fail，
+  报告在 [docs/conformance](docs/conformance/README.md)。碰撞/作物/实体规则收敛到
+  `block-shapes.mjs` 一份；TF 241 个假空气方块、`diggable` 绑 `solid`、番茄长苗
+  alias 都有回归。
+- **0.6.4（实体与 boss 可读）**：registry-dump 0.1.2 导出 `ENTITY_TYPE`（id/生成组/
+  碰撞箱），`import-dump` 写进 `<pack>-ids.json` 的 `entities`；`inspect` 从
+  `tags/entity_type/bosses.json` 读 boss 名单并带上实体中英文名。宿主因此能把
+  `unknown` 叫成「娜迦（twilightforest:naga）」并按 `monster` 组判敌对。
+  战术仍由她现场决定，清单只给事实。
+- **registry-dump 快路径（主线，随包内置）**：接包从逐状态数小时降到秒级；
+  `onboard` 自动优先用它，`calibrate` 只在没有服务器文件权限时作为退路。
+  dump jar 不自动安装，装/删由人决定。
 
 **数据层（本仓库）**
 
@@ -80,7 +137,7 @@ node modsmith/bin/modsmith.mjs inspect path/to/mod.jar --out ./mods
 - **inspect 契约修复（0.6.2）**：自定义序列化器把 `result` 写成字符串时统一收成
   `{id,count}`；原版 tag 可从服务器 jar 的 `data/minecraft/tags/` 展开并入
   `candidates`（`minecraft:wooden_slabs` 等），原版 tag 配方才装得进配方表。
-- **L2/L3 能力保持**：`onboard` 七步、`learn --infer`（默认合并人工站点、整段重推要
+- **L2/L3 能力保持**：`onboard` 九步（含两道 conformance 早停）、`learn --infer`（默认合并人工站点、整段重推要
   `--force`）、`verify --stations` 三种机制真执行、侧车熟成可跨重启、`probe --scan-blocks`
   全量窗口扫描。
 
@@ -93,8 +150,9 @@ node modsmith/bin/modsmith.mjs inspect path/to/mod.jar --out ./mods
   方块计数/可站格/门）、`place.face`（壁挂装饰）。真机验收：她在两间不同材质的
   5×5 房间里自己扫房、选材、贴出 **25 件装饰 + 两条横梁 + 两个遮阳篷**，并把
   暖/冷两套风格写进笔记。
-- **P3 冒险**：TF 4.8.796 Fabric jar 已下载，下一步建独立 TF 服接包；实体/战利品表
-  读取是它当"冒险包"的前置缺口。
+- **P3 冒险**：TF 4.8.796 已接入生产服（523 方块 / 540 条配方 / 9 个 boss）。
+  实体名与 boss 标记已进清单，`mc_entities` 能报"是谁、多远、是否敌对"；剩下的是
+  维度传送与战利品表读取。
 - 完整阶段与依赖见 [ROADMAP.md](ROADMAP.md)。
 
 **兼容性说明**
@@ -108,8 +166,60 @@ calibrate / probe / verify 是在**你自己的服务器上动手**：`forceload
 没有 OP 就是每条命令静默失败。支持范围也只有 Fabric（Forge/NeoForge 的 FML 握手
 是另一套协议，投入产出比差）。
 
+## 最快接包：注册表 dump（秒级，替代逐状态校准）
+
+`templates/registry-dump` 是一个只读的服务端 Fabric mod：启动后把服务端真实注册表写成
+`config/modsmith-dump.json`，**不注册任何方块/物品**。jar 已随包内置
+（`templates/registry-dump/modsmith-dump-0.1.2.jar`，4.6KB），运行 `modsmith dump-jar`
+可直接打印它的绝对路径；也可从
+[Release](https://github.com/xiaoxiao150/modsmith/releases/tag/registry-dump-v0.1.2) 下载。
+
+装一次 → 启动 → 拿 dump → 停服删 jar：
+
+```bash
+modsmith import-dump config/modsmith-dump.json \
+  --manifest mods/<pack>.json --ids mods/<pack>-ids.json \
+  --server-mods mods
+```
+
+`import-dump` 只保留清单声明的方块/物品，并收下这个命名空间的全部实体；剔除 vanilla
+区间（方块 stateId 与原版实体 id 0–129）与重复 stateId。TF 这种 523 方块 / 17255 状态
+的大包，从“逐状态 setblock 约 1.5 小时”变成秒级。
+
+## 接包验收（conformance）
+
+接包不再靠“陪玩一晚看崩不崩”。清单和 ids 一落地就跑一次离线验收：
+
+```bash
+modsmith conformance mods/<pack>.json \
+  --ids mods/<pack>-ids.json --server-mods mods
+```
+
+三层检查：
+
+- **manifest**：solid 必须有 box 或可映射形状、作物 alias 必须指向可收获阶段（不会把长苗当熟果）、配方 result/candidate 可解析；
+- **ids**：stateId 在原版区间外、无跨方块重复/重叠、item/entity id 在各自原版上限外、服务器指纹对得上；
+- **registry**：注入真实 prismarine 注册表后，每个 state 真的有 shape、楼梯上半/下半不同、作物 `diggable:true`、boss 真的进实体表、配方视图能消费。
+
+`onboard` 会自动跑这一步，失败就停在 probe/sidecar 之前；报告落在
+`mods/<pack>-conformance.json`。当前四个生产包离线检查都是 **0 fail**（警告是自定义
+序列化器/开门状态等已解释项）。
+
+要在一台真实服务器上只读验证一遍，加 `--live`：
+
+```bash
+modsmith conformance mods/<pack>.json --ids mods/<pack>-ids.json \
+  --server-mods mods --live --host 127.0.0.1 --port 25565
+```
+
+它会起一个临时 mineflayer bot（默认 `ModConform`），在 `inject_allowed` 前注入，
+检查方块形状/实体/boss 后退出；**不 setblock、不召唤、不聊天**，可以指向生产服。
+最小独立示例见 [`templates/reference-bot`](templates/reference-bot/README.md)。
+
 ## 四步
 
+先装：`npm i -g modsmith`（或每条命令前加 `npx`）。
+
 ```
 modsmith inspect  <mod.jar>           静态提取：方块/物品/配方/tag/中文名 + 推断作物
 modsmith calibrate <manifest.json>    连服务器量数字 id（/setblock + /give）
@@ -130,7 +240,7 @@ modsmith learn    <manifest.json>     LLM 读清单 + wiki，产出站点定义
 modsmith sidecar  <manifest.json>     给"服务端不开菜单"的站点生成侧车模组
 ```
 
-一条龙（六步按序串好，失败即停，`--resume` 断点续跑）：
+一条龙（九步按序串好，失败即停，`--resume` 断点续跑）：
 
 ```
 modsmith onboard <mod.jar> --pack <name> \
@@ -307,8 +417,9 @@ modsmith learn <manifest> --infer --evidence probe.json
 `verify --stations` **不静默跳过**：缺 `recipeType` 的、机制还没执行器的，都会显式报
 “已知但未验”，而不是从报告里消失。
 
-`onboard` 现在是 **7 步**：inspect → calibrate → probe（含方块扫描）→ recipes →
-learn（规则推断）→ verify（含站点实测）→ sidecar。`recipes` 排在 `learn`/`verify` 之前是
+`onboard` 现在是 **9 步**：inspect → conformance-manifest → calibrate/import-dump →
+conformance（ids+registry）→ probe（含方块扫描）→ recipes → learn（规则推断）→
+verify（含站点实测）→ sidecar。`recipes` 排在 `learn`/`verify` 之前是
 硬约束：jar 形状的配方里 `tool` 是对象（读不出刀后缀）、`cooking_time` 为空，先跑会把
 两步式误判成侧车、站点执行也会超时。