name: midnight-tooling:midnight-compatibility description: 用于检查Midnight版本兼容性、理解pragma language_version、验证编译器与运行时版本关系，或排查Midnight组件间版本不匹配错误时使用。

Midnight 版本兼容性

理解Midnight组件间的版本关系。

组件概览

Midnight开发涉及多个版本化组件：

组件	用途	版本检查命令
Compact 开发者工具	管理编译器的CLI	`compact --version`
Compact 编译器	将.compact文件编译为ZK电路	`compact compile --version`
compact-runtime	JavaScript运行时库	`npm list @midnight-ntwrk/compact-runtime`
ledger	核心账本类型	`npm list @midnight-ntwrk/ledger`
midnight.js	JavaScript SDK	`npm list @midnight-ntwrk/midnight.js`
证明服务器	ZK证明生成	Docker镜像标签

版本关系

语言版本（在pragma中）
         │
         ▼
┌─────────────────────────┐
│   Compact 编译器        │ ──── 生成 ───▶ 合约制品
│   （例如，0.26.0）      │
└─────────────────────────┘
         │
         │ 必须匹配
         ▼
┌─────────────────────────┐
│   compact-runtime       │
│   （例如，0.9.0）       │
└─────────────────────────┘
         │
         │ 与以下兼容
         ▼
┌─────────────────────────┐
│   ledger, midnight.js   │
│   证明服务器            │
└─────────────────────────┘

检查当前兼容性矩阵

权威来源是Midnight发布说明中的支持矩阵。

检查当前推荐版本：

/midnight:versions

或直接解析：

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/parse-support-matrix.py

Pragma 语言版本

每个Compact合约必须声明其语言版本：

pragma language_version 0.18;

ledger {
  // ...
}

Pragma 规则

必须匹配编译器能力：编译器必须支持声明的版本
一致性：项目中的所有合约应使用相同的pragma
升级时更新：升级编译器时，如果语言版本发生变化，请更新pragma

查找编译器的语言版本

编译器版本（例如，0.26.0）映射到语言版本（例如，0.18.0）：

# 检查发布说明以获取映射
/midnight:changelog compact

近期映射（请通过发布说明验证）：

编译器 0.26.0 → 语言 0.18.0 (Minokawa)
编译器 0.25.0 → 语言 0.17.0

包版本指南

使用精确版本

在 package.json 中，始终使用精确版本：

{
  "dependencies": {
    "@midnight-ntwrk/compact-runtime": "0.9.0",
    "@midnight-ntwrk/ledger": "4.0.0",
    "@midnight-ntwrk/midnight.js": "2.1.0"
  }
}

切勿使用：

^0.9.0 （允许次要版本更新）
~0.9.0 （允许补丁版本更新）
>=0.9.0 （允许任何较新版本）

为什么精确版本很重要

Midnight组件有严格的兼容性要求。一个组件的次要版本更新可能需要更新其他组件。使用范围版本可能导致：

静默不兼容
“在我机器上能运行”的问题
不同lockfile导致的CI失败

使用 npm ci

为了实现可重复构建，请使用 npm ci 而不是 npm install：

# npm ci 使用 package-lock.json 中的精确版本
npm ci

# npm install 可能会在semver范围内更新
npm install  # 生产环境请避免使用

编译器版本管理

列出可用版本

compact list

列出已安装版本

compact list --installed

切换默认版本

# 更新到最新版本
compact update

# 切换到特定版本
compact update 0.25.0

为单次编译使用特定版本

# 使用 +版本 前缀
compact compile +0.25.0 src/contract.compact contract/

这在以下情况下很有用：

针对多个编译器版本进行测试
在开发新合约的同时维护旧合约
渐进式迁移

证明服务器版本

证明服务器必须与您的合约兼容：

# 检查可用标签
docker search midnightnetwork/proof-server

# 拉取特定版本
docker pull midnightnetwork/proof-server:4.0.0

# 运行特定版本
docker run -p 6300:6300 midnightnetwork/proof-server:4.0.0 -- midnight-proof-server --network testnet

版本间的破坏性变更

升级时，请检查发布说明中的破坏性变更：

/midnight:changelog compact

常见的破坏性变更包括：

新的保留关键字（例如，0.18.0中的 slice）
运行时函数重命名
类型系统变更
新的pragma要求

版本升级工作流

检查当前版本：/midnight:versions
检查目标版本：查看兼容性矩阵
阅读发布说明：/midnight:changelog <组件>
更新 package.json：使用精确版本
更新编译器：compact update <版本>
更新 pragma：如果语言版本发生变化
清理安装：rm -rf node_modules && npm ci
重新编译：compact compile src/*.compact contract/
测试：运行您的测试套件

附加资源

references/compatibility-matrix.md - 详细的版本兼容性表
references/pragma-guide.md - Pragma声明指南

有关版本问题的故障排除，请参阅 midnight-debugging 技能。