agentmc/README.md

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）

累计测试

套件	项数
版本解析	6
protodef	6
区块解析	11
mod jar	8
跨实现互操作	2
合计	33