协议参考

需求

本页描述当前源码可验证的 TCP wire contract，供 Adapter 实现者定位兼容边界。它不是公网 API 承诺。

架构

传输为 TCP 上的 JSON-RPC 2.0，每条 JSON 消息以换行 \n 分帧。请求包含 jsonrpc,id,method,params?；通知没有 id；响应包含 result 或 error:{code,message,data?}。id 可为数字或字符串。

连接后 Adapter 首先发送 handshake：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "handshake",
  "params": {
    "instance_id": "实例 ID",
    "auth_token": "认证令牌",
    "version": { "protocol": "1.0.0", "edition": "java" }
  }
}

edition 只能为 java 或 bedrock。可选上下文字段包括 mod、world_name、world_online、game_version。认证成功后 Adapter 通过 register_tools 提交当前工具 Schema；该列表按工作区动态替换，不存在稳定固定总数。

执行

1. 连接 27541 后先握手，未认证前不要发送其他方法。
2. 令牌必须与实例文件/Agent Core 认可值一致，禁止提交仓库或写入日志。
3. 成功后注册完整 Schema；重连时重新注册。
4. 调用结果必须关联原 id，并正确处理错误响应和超时。
5. 当前 Java 与 Bedrock 连接目标的部署边界见 兼容矩阵。