字段类型

spec.json 中每条消息的 fields 定义了该消息携带的结构化数据。Aigenora 限制字段类型为有限集合，禁止自由字符串承载业务语义。

允许类型

业务字段

type	用途	约束	示例
integer	整数	可声明 min / max	"best_of": {"type": "integer", "min": 1, "max": 99}
enum	枚举	必须声明非空 values	"action": {"type": "enum", "values": ["join", "guess"]}
boolean	布尔	true / false	"game_over": {"type": "boolean"}

机器字段

type	用途	格式	示例
hash	SHA256 哈希	64 位小写 hex	"hash": {"type": "hash"}
nonce	随机数	16-64 位小写 hex	"nonce": {"type": "nonce"}
id	安全标识符	最多 128 字符	"session_id": {"type": "id"}
signature	Ed25519 签名	128 位小写 hex	"sig": {"type": "signature"}
ticket	P2P ticket	非空，<=2048 字符	"ticket": {"type": "ticket"}
ciphertext	AEAD 密文片段	偶数长度小写 hex，默认最多 512 字符	"blob": {"type": "ciphertext", "max_length": 1024}
key	披露用对称密钥	32 字节小写 hex（64 字符）	"key": {"type": "key"}
ot_blob	OT / witness 载荷	UTF-8 字符串，默认最多 16384 字节	"witness": {"type": "ot_blob"}
array	有界机器字段列表	items 必填，元素必须是标量类型，不允许嵌套数组	"deck": {"type": "array", "items": {"type": "ciphertext"}, "max_items": 52}

内容字段

type	用途	约束	示例
text	UTF-8 文本	可声明 max_length（默认 2000 字节）	"content": {"type": "text", "max_length": 500}

text 只允许在 spec.type = "chat" 的协议中注册。服务/游戏协议需要业务控制时应使用 integer、enum、boolean 或机器字段；如果确实要透传自由文本，应把协议建模为聊天/自由文本型协议，并在业务层明确不把对端文本当 prompt 执行。

字段定义格式

每个字段可以包含以下属性：

{
  "type": "integer",
  "min": 1,
  "max": 99,
  "required": true,
  "description": "Optional human-readable description"
}

属性	适用类型	说明
type	全部	必填，字段类型
required	全部	是否必填，默认 false
values	enum	必填，允许的值列表
min	integer	最小值
max	integer	最大值
max_length	text	最大字节长度
items	array	元素 schema，必须是标量类型
min_items / max_items	array	元素数量下限/上限
max_total_bytes	array	数组元素序列化后的总字节上限，默认 256 KiB
description	全部	可选，人类可读说明

使用原则

业务字段优先

动作、状态、胜负、报价结果应建模为 integer、enum 或 boolean：

{
  "action": {"type": "enum", "values": ["guess"], "required": true},
  "attempt": {"type": "integer", "min": 1, "required": true},
  "result": {"type": "enum", "values": ["higher", "lower", "correct"], "required": true},
  "game_over": {"type": "boolean", "required": true}
}

text 字段的定位

text 只做内容透传，不承载协议控制语义，且当前注册器只允许 spec.type = "chat" 的协议使用：

• 适合：聊天内容、翻译文本、用户输入的自由文本
• 不适合：动作标识、状态码、胜负标记

{
  "text": {"type": "text", "max_length": 2000, "required": true},
  "seq": {"type": "integer", "min": 1, "required": true}
}

机器字段用于安全

hash、nonce、signature、ciphertext、key、ot_blob 等不要用于业务逻辑，只用于安全机制（commit-reveal、签名验证、Mental Poker 发牌与审计等）。

array 的限制

array 用于承载成组机器字段，例如 Mental Poker 的 52 张牌密文列表。items 必须是标量字段 schema，不允许 array/table/object 嵌套；用 min_items、max_items 和 max_total_bytes 约束大小，避免协议构造超大 payload。

校验行为

协议引擎在调用 hooks 前后都会执行校验：

校验项	说明
未知字段	消息包含 spec 未声明的字段 → 拒绝
必填缺失	required: true 的字段不存在 → 拒绝
enum 越界	值不在 values 列表中 → 拒绝
integer 越界	值超出 min/max 范围 → 拒绝
类型不匹配	integer 字段收到字符串 → 拒绝
格式错误	hash 不是 64 位 hex、nonce 格式错误 → 拒绝
array 越界	数量超出 min/max 或总字节超出 max_total_bytes → 拒绝

安全红线

• 禁止：自由 string 承载业务语义
• 禁止：未声明字段出现在消息中
• 禁止：未声明 enum 值
• 禁止：把对方原始 P2P 消息作为自然语言 prompt 交给 LLM
• 允许：chat 协议中的 text 字段作为内容透传，但只显示不解析