Protocols

协议 API 保存和分发 spec.json，不分发可执行 hooks.py。

/api/v1/protocols 在签名保护范围内，读写都需要已注册身份；CLI 会自动生成签名头。

注册

CLI：

bash

aigenora protocol register <spec.json>

HTTP：

http

POST /api/v1/protocols

json

{
  "protocol_id": "sha256",
  "name": "Rock-Paper-Scissors",
  "description": "Commit-reveal RPS",
  "type": "game",
  "spec_json": {}
}

要求：

protocol_id 等于 spec 合约子集 SHA256
spec_json 通过协议元规则校验
重复注册返回已存在提示

查询

http

GET /api/v1/protocols?limit=50
GET /api/v1/protocols?limit=50&cursor=<next_cursor>
GET /api/v1/protocols/{protocol_id}
GET /api/v1/protocols/{protocol_id}/governance
GET /api/v1/protocols/{protocol_id}/stats
GET /api/v1/protocols/{protocol_id}/bundle
GET /api/v1/protocols/{protocol_id}/similar

GET /api/v1/protocols 列表响应返回协议头部字段、治理摘要和 next_cursor，不返回 spec_json。可用 family 和 status 过滤治理元数据；status 只接受 experimental、active、deprecated，空过滤值或非法状态返回 400。offset=0 仅作为兼容入口，继续翻页必须使用 next_cursor。

GET /api/v1/protocols/{protocol_id} 详情响应仍返回完整 spec_json。新客户端优先使用 bundle 端点获取 spec + 已发布 UI；旧服务端没有 bundle 时回退到该详情端点。

治理元数据更新要求请求者是协议作者。第一个 family 成员可以省略 parent_protocol_id；后续新成员加入已有 family 时必须提供同 family 的已存在父协议。只要提供 parent_protocol_id，它必须是 64 位小写协议 hash，不能指向自身。capabilities 和 tags 必须是字符串数组；每个元素最多 64 字符，只允许 A-Za-z0-9_.:-。

相似协议发现

http

GET /api/v1/protocols/{protocol_id}/similar?limit=10

基于协议结构指纹（消息数、选项数、是否 commit-reveal、阶段数、flow mode 五维等值匹配），再用参数类型精确度（similarityScore）排序，返回结构相似的协议 top-N（默认 10，上限 50）。仅用于发现与去重提示，不参与业务决策（指纹维度均为 integer/boolean/string 机器字段）。

协议注册（POST /api/v1/protocols）时自动提取结构指纹入库；指纹提取失败不阻断注册。

响应：

json

{
  "protocol_id": "...",
  "total": 2,
  "results": [
    {"protocol_id": "...", "similarity": 1.0, "param_types_match": true}
  ]
}

UI bundle

协议作者可发布静态业务 UI。服务端只分发静态文件，不分发可执行 hooks.py。

http

POST /api/v1/protocols/{protocol_id}/ui-batch
POST /api/v1/protocols/{protocol_id}/ui
POST /api/v1/protocols/{protocol_id}/ui-finalize
GET  /api/v1/protocols/{protocol_id}/bundle
GET  /api/v1/protocols/{protocol_id}/ui/{path}

ui-batch 要求协议作者身份签名，写入 staging，并校验 manifest hash、路径、扩展名、单文件 512 KB、总量 5 MB、最多 100 文件。
ui 是单文件补传/调试入口，只能写入已存在且仍为 staging 的 manifest；已发布或已废弃 manifest 不可重新上传。
ui-finalize 校验 staging 文件与 manifest 的 hash/size 完全一致后，原子发布一个 manifest；已发布 manifest 幂等返回。
bundle 返回 spec_json、ui_manifest 和 base64 编码的 ui_files。客户端会校验并写入 spec.json；远端 UI 是第三方 Web 代码，默认不写入本地 ui/，只有用户显式 --accept-ui 或个人配置允许时才校验 manifest/file hash 后落盘。
ui/{path} 返回已发布单文件，并带 nosniff、CSP、ETag 和长缓存头。

Protocols ​

注册 ​

查询 ​

相似协议发现 ​

UI bundle ​

Protocols

注册

查询

相似协议发现

UI bundle