554ebc239a
用户要求：Create 与 Aeronautics 会引入大量原版没有的方块与危险区，
寻路必须一起优化。用户裁定：危险区用「表 + 命名推测并标记」，
动态机械用「警告 + 提高代价」。
## ★ 关键实测结论（本轮最重要）
我先按「给 mod 方块建语义表」做，实测覆盖率：
Create 643 个方块 → 显式表命中 9、命名规则推测 21、完全不识 613
覆盖率 4.7%
⇒ **手写表是死路**（64 mod / 1465 方块永远追不上）。
⇒ 但寻路真正需要的属性，**运行时全都有**：
Java 侧 blockinfo 已在读 BuiltInRegistries.BLOCK（**含 mod 运行时注册的方块**），
并返回 isSolid / destroySpeed / lightEmission / isAir / hasBlockEntity。
⇒ 正确做法是**问**，不是猜。
## 改动
新增 mcfold/solid.py：
- SolidSource 抽象：RegistrySolidSource（本机，快但无 mod）
vs RuntimeSolidSource（问 JVM，**含 mod**，准但要 JVM）
- 按 **state_id** 缓存（属性只依赖 state，不依赖坐标）
- attach_runtime() 批量探测（一次问一格要一次往返，批量才可用）
mcfold/pathfind.py：Terrain 改为「**先运行时缓存，再本机注册表**」；
can_dig 用 destroySpeed 判可挖（基岩官方约定是 -1 = 不可破坏），
不再靠名字猜「基岩挖不动」
新增 mcfold/modblocks.py（危险/会动这部分的表，配套覆盖率报告）：
- 语义取���：ground/passable/hazard/breakable/solid/dynamic/carrier/unknown
- 三级来源：显式表 → 命名规则（**标记 inferred**）→ **如实说不认识**
- ★ vanilla 与 mod **分开算覆盖率**：vanilla 语义由注册表给，
把它算成「未知」会让人误以为「连石头都认不出」
WorldState：加 solid_cache 字段
## 判据
test_pathfind 19 → 24 项，新增 5 项：
- mod 方块优先用运行时 isSolid（本机注册表确实认不出）
- 不可破坏吃 destroySpeed（含基岩 -1 约定）
- 两边都无数据 ⇒ 不知道（**不谎称可走**）
- 覆盖率报告如实（且区分 mod/vanilla）
- 语义查询永远返回带 inferred 标记的结构
★ 写判据时踩了两个坑（都是 fixture 形状错，不是代码错）：
1. `Chunk.sections[i]` 对应 y = MIN_Y + 16*i，MIN_Y=-64
⇒ 我按「第 0 个 section = y=0」写，查 y=0 拿到的是空气
2. 同一 section 内 16 格**只能一个值** ⇒ mod 方块与空气落同一 section 时，
空气格会变成 mod 方块（看着像代码 bug，其实是 fixture 形状问题）
⇒ 教训：**判据的 fixture 形状必须与被测代码的真实输入结构一致**。
226 项全通过。
mcfold — Minecraft 折叠层（净室 Python 实现）
按用户 2026-09-25 定向：净室 Python 实现，替代 Node/mineflayer 栈， 使产物可打包分发（无 Node 运行时依赖）。
架构
底层 mcfold（本工程，Python）
├─ 按实例文件夹读版本 → 自动选协议（P1 已完成）
├─ 声明式 protocol.json 解释器（protodef）
├─ 世界模型（chunk/方块，含 mod 注册表）
└─ 触发截屏 → 调脚手架 → 官方渲染 jar
中间 可包装为不同 agent 的插件
上层 面向 homeagent 的 Go 包装（复用现有 plugin.go 形状）
关键实测事实（决定设计）
| 事实 | 证据 |
|---|---|
| 实例文件夹 = 完整 MC 客户端安装 | versions/<id>/<id>.json + .jar |
| 加载器 id 不是协议版本 | minecraft-data('1.20.1-forge-47.4.0') → FAIL，必须走 inheritsFrom |
| protocol.json 是声明式的 | varint/pstring/mapper/switch 全是数据，非代码 |
| 因此协议不需重写，只需解释器 | 111 个 play 包由同一份 JSON 驱动 |
| 1.20.1 不在网络上传递方块注册表 | codec 仅 6 类，无 block ⇒ mod 方块必须另寻途径 |
| 1.20.2+ 有 configuration 阶段 | 会发 registry_data ⇒ mod 方块可行的版本分界 |
进度
- P1 按文件夹解析版本（
mcfold/version.py，6 项回归全绿） - P2 声明式 protodef 解释器（
mcfold/protodef.py） 真实握手字节解码通过（proto=763 / login success / play 包路由） - P3 最小客户端 + 跨实现互操作（
mcfold/client.py） Python 客户端 ←→ Node 服务端握手成功（两边独立实现，最有说服力）
已证实的结论
| 结论 | 证据 |
|---|---|
| 协议不需重写，只需解释声明式 JSON | 111 个 play 包由同一份 protocol.json 驱动 |
| Python 客户端能真连真服 | Node 侧日志 SERVER_GOT_LOGIN username= PyProbe |
| 协议号由实例文件夹决定 | 1.20.1/version.json → 763 |
| 区块格式必须自己解（协议层是声明式，但 chunkData 是不透明 buffer） | protocol.json 里 chunkData 只声明为 buffer |
| Python 解码器能解独立实现产出的区块 | prismarine-chunk 产样本 → 4/4 方块命中 |
| mod 方块在本机注册表里显式 unknown，而非静默错配 | state 99999 -> unknown(99999) |
进度（续）
-
P4 区块解析（
mcfold/chunk.py，11 项回归全绿） 位打包 / 单值·本地·全局调色板 / 生物群系 section / 世界边界 关键行为：越界 state id ⇒unknown(id)（对照 mineflayer 的静默错配） -
P5 mod jar 解析（
mcfold/modjar.py，8 项回归全绿） 三种加载器真实样本验证（Forge / NeoForge / Fabric）+ 多加载器 jar 诊断 可提取：mod id / 名称 / 版本 / 方块名清单 / 物品名清单 诚实边界：拿不到 state id（已在摘要里明说，见附录 D） -
P6 世界模型（
mcfold/world.py，7 项回归全绿） 多区块聚合 / 负坐标定位 / 世界高度边界 关键语义：unloaded（没收到）与air（真是空气）必须可区分 mod 方块计入unknown_state_ids，世界摘要带告警 -
P7 实例层（
mcfold/instance.py，8 项回归全绿） 传入文件夹路径 → 拉起实例 → 读 mod 注册方块表 → 连服 含：加载器版本归一化、裸名展开、歧义处理、越界 state id 归因到 mod
累计测试
| 套件 | 项数 |
|---|---|
| 版本解析 | 6 |
| protodef | 6 |
| 区块解析 | 11 |
| mod jar | 8 |
| 世界模型 | 7 |
| mod jar | 8 |
| 实例层 | 8 |
| 跨实现互操作 | 2 |
| 合计 | 48 |
统一入口：./run_tests.sh