服务协议（业务层）

本文描述认证完成后的业务层方法。连接与身份认证见对应子协议文档：
身份与凭证：01-身份与凭证协议-auth.md
Gateway 连接：03-Gateway-连接模式.md
Peer 对等认证：04-Peer-子协议.md
Relay 中继：05-Relay-子协议.md
业务层方法与连接拓扑无关。无论使用 gateway、peer 或 relay 模式，认证完成后都可调用以下方法。

命名空间概览

命名空间	分类	功能	对应服务	传输方式
`auth.*`	核心	AID 注册、认证、令牌管理	auth 服务	WebSocket
`ca.*`	核心	证书签发、续期、吊销	ca 服务	WebSocket / HTTP
`message.*`	核心	点对点消息路由、E2EE prekey 管理	message 服务	WebSocket
`meta.*`	核心	健康检查、状态查询、受信根证书	meta 服务	WebSocket
`storage.*`	扩展	对象存储、大文件上传下载（详见 11-Storage-子协议.md）	storage 服务	WebSocket + HTTP
`group.*`	扩展	群组管理、群消息、资源共享（详见 10-Group-子协议.md）	group 服务	WebSocket
`mail.*`	扩展	邮件服务	mail 服务	WebSocket
`stream.*`	扩展	实时流式传输（详见 12-Stream-子协议.md）	stream 服务	WebSocket + HTTP SSE
`search.*`	扩展	Agent 搜索与发现	search 服务	WebSocket
`relay.*`	扩展	NAT 穿透中继（详见 05-Relay-子协议.md）	relay 服务	WebSocket
`peer.*`	协议定义	点对点直连（详见 04-Peer-子协议.md）	无对应服务	WebSocket
`task.*`	协议定义	Agent 协作与任务执行	无对应服务	WebSocket

控制面与数据面分离：

message.* 用于传递消息语义、小型结构化负载和控制信息，不承担大对象传输职责
storage.* 用于承载大文件、大对象及附件内容的上传、下载与持久保存
stream.* 用于实时流式传输（LLM 输出、数据推送等），控制面通过 RPC 管理流生命周期，数据面通过独立端口的 WebSocket（推流）和 HTTP SSE（拉流）传输
大文件、二进制附件、长时流式内容不应直接嵌入 message.* 的 payload，应先经 storage.* 存储，再由 message.* 传递对象引用
实现应分别对 message.* 的消息体大小和 storage.* 的对象大小进行独立限制

应用层扩展服务本身也是 AID 持有者，通过核心协议（message.*）与客户端通信。客户端可以选择使用或不使用这些扩展服务。

点对点消息 `message.*`

设计原则：

无会话生命周期：不需要 create/invite/join/close 流程，直接发送即可
投递语义由 delivery_mode 决定：fanout 会进入离线历史并广播到同一 AID 的在线实例；queue 只做实时单实例投递，不进入历史存储
控制面与数据面分离：message.* 承载消息语义和小型结构化数据；附件、大对象应通过 storage.* 传输，消息中只保留引用

本节仅适用于 P2P message.*。group.send 不支持 queue，群消息始终是 fanout 语义。

消息存储模型：

`delivery_mode.mode`	投递方式	存储位置	生命周期	适用场景
`queue`	单实例实时消费	内存环形缓冲	有限时间窗口（默认 5 分钟）+ 有限条数（默认 200 条/AID）	Worker/执行器消费、同一发送者尽量命中同一实例
`fanout`	广播到在线实例	数据库 + 文件存储	TTL 过期前持久保存（默认 24 小时）	离线送达、历史查询、多实例同步接收

序列号机制：

每条消息（无论临时或持久化）在收件人维度分配一个递增 seq
客户端通过 after_seq 游标增量拉取，支持多设备各自维护进度
message.pull 合并返回临时消息和持久化消息，按 seq 排序

`message.send`

发送 P2P 消息。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "message.send",
  "params": {
    "to": "bob.aid.pub",
    "payload": {"type": "text", "text": "你好"}
  }
}

参数：

参数	必需	说明
`to`	✅	接收者 AID
`payload`	✅	消息载荷，对协议层透明，由应用层定义
`type`	❌	信封/封装类型，普通业务消息无需填写；SDK 加密发送时自动使用 `e2ee.encrypted`
`encrypted`	❌	E2EE 标记（默认 `false`）
`message_id`	❌	幂等键（客户端提供或服务端生成 UUID）
`timestamp`	❌	客户端时间戳（毫秒），服务端忽略此字段，始终使用服务端时间

响应：

json

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "message_id": "550e8400-e29b-41d4-a716-446655440000",
    "seq": 42,
    "timestamp": 1709712000,
    "status": "sent",
    "delivery_mode": "queue"
  }
}

Payload 参考约定

message.send.params.payload 的统一业务负载格式见消息Payload参考约定。完整 P2P 请求仍在 payload 同级传入 to；业务类型放在 payload.type，不要与 message.send.params.type 信封/封装类型混用。

协议层只要求 payload 是 JSON 对象，并按服务端配置做大小限制；字段语义由应用层约定，接收端应对未知 payload.type、未知 kind 和缺失展示字段做降级处理。

连接升级控制消息

peer.offer / peer.accept / peer.reject / peer.switch 不是独立 JSON-RPC 方法，而是通过普通 message.send 发送的协议控制负载。三种连接模式在业务层复用统一的 message.*。

用途：

gateway → peer：通过 Gateway 交换直连地址，尝试升级到 Peer
relay → peer：已通过 Relay 联通的双方尝试升级到直连
失败时可回退到原有通道，不影响业务层 API

peer.offer 示例：

json

{
  "method": "message.send",
  "params": {
    "to": "bob.company.com",
    "payload": {
      "type": "peer.offer",
      "session_id": "upgrade-550e8400",
      "from_mode": "gateway",
      "preferred_mode": "peer",
      "endpoints": [{"url": "wss://alice.company.com:9900/acp", "priority": 1}],
      "expires_in": 30
    },
    "delivery_mode": {"mode": "queue"}
  }
}

peer.accept 负载：{ "type": "peer.accept", "session_id": "...", "selected_endpoint": "wss://..." }

peer.reject 负载：{ "type": "peer.reject", "session_id": "...", "reason": "policy_denied" }

peer.switch 负载：{ "type": "peer.switch", "session_id": "...", "new_mode": "peer", "keep_fallback": true }

规范要求：

接收方 MAY 接受或拒绝 peer.offer
接受后，双方 MUST 在新通道上重新执行完整 initialize(mode=peer) 与 peer.* 认证流程
旧通道在 peer.switch 完成前 MUST 保持可用
升级失败或超时时双方 MUST 回退到原通道

`message.pull`

按游标拉取新消息。合并返回临时消息和持久化消息，按 seq 排序。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "message.pull",
  "params": {
    "after_seq": 0,
    "limit": 100,
    "device_id": "device-001",
    "slot_id": "slot-a"
  }
}

参数：

参数	必需	说明
`after_seq`	❌	起始序列号（默认 0），返回 `seq > after_seq` 的消息
`limit`	❌	单次返回上限（默认 100，最大 200）
`device_id`	❌	多实例消费上下文中的设备标识；缺省时使用连接认证上下文
`slot_id`	❌	同一设备下的消费槽位；空字符串表示设备单实例模式
`limit`	❌	返回条数（默认 100，最大 200）

响应：

json

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "messages": [{
      "message_id": "550e8400-...",
      "seq": 43,
      "from": "alice.aid.pub",
      "to": "bob.aid.pub",
      "timestamp": 1709712000,
      "payload": {"type": "text", "text": "你好"},
      "delivery_mode": "fanout"
    }],
    "count": 1,
    "latest_seq": 43,
    "ephemeral_earliest_available_seq": 38,
    "ephemeral_dropped_count": 5
  }
}

响应字段：

字段	类型	说明
`messages`	array	消息列表（临时 + 持久化合并，按 `seq` 排序）
`count`	integer	本次返回的消息条数
`latest_seq`	integer	本次返回的最大 `seq`
`ephemeral_earliest_available_seq`	integer\|null	当前临时缓冲中最早可用的 `seq`，`null` 表示无临时消息
`ephemeral_dropped_count`	integer	因缓冲淘汰而丢弃的临时消息计数

客户端可通过 ephemeral_earliest_available_seq 判断是否有临时消息丢失：若 after_seq < ephemeral_earliest_available_seq，说明存在已被淘汰的消息。

说明：不修改消息状态，多设备安全（各 (aid, device_id, slot_id) 维护各自的 after_seq），同一 after_seq 多次调用返回相同结果（幂等）。显式传入的 device_id / slot_id 若与连接认证上下文不一致，服务端 MUST 拒绝请求。

`message.ack`

确认已收到消息，推进服务端 ack 游标。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "message.ack",
  "params": {
    "seq": 43,
    "device_id": "device-001",
    "slot_id": "slot-a"
  }
}

参数：

参数	必需	说明
`seq`	✅	确认到的序列号（含），表示该 seq 及之前的所有消息已收到
`device_id`	❌	多实例消费上下文中的设备标识；缺省时使用连接认证上下文
`slot_id`	❌	同一设备下的消费槽位；空字符串表示设备单实例模式

响应：

json

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {"success": true, "ack_seq": 43}
}

说明：ack_seq 仅增不减。现代连接按 (aid, device_id, slot_id) 维护 ack 游标；未携带 device_id 的 legacy 连接继续走 per-AID 兼容路径。显式传入的 device_id / slot_id 若与连接认证上下文不一致，服务端 MUST 拒绝请求。

`message.recall`

撤回消息。仅发送方可撤回，受时间窗口限制（默认 2 分钟）。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "message.recall",
  "params": {"message_ids": ["uuid-1", "uuid-2"]}
}

参数：

参数	必需	说明
`message_ids`	✅	要撤回的消息 ID 列表（最多 100 个）

响应：

json

{
  "jsonrpc": "2.0",
  "id": 13,
  "result": {
    "success": true,
    "accepted": 2,
    "recalled": 1,
    "errors": [{"message_id": "uuid-2", "error": "expired"}]
  }
}

字段	类型	说明
`success`	boolean	操作是否执行
`accepted`	integer	接收的 message_id 数
`recalled`	integer	实际撤回数
`errors`	array\|null	失败项，错误码：`not_found` / `not_sender` / `already_recalled` / `expired`

说明：撤回成功后向接收方推送 event/message.recalled 事件。仅 delivery_mode.mode = "fanout" 的消息支持撤回；queue 消息不进入历史，无法可靠追溯。

`message.query_online`

批量查询 AID 在线状态。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "message.query_online",
  "params": {"aids": ["alice.aid.pub", "bob.example.com"]}
}

参数：

参数	必需	说明
`aids`	✅	要查询的 AID 列表（最多 100 个）

响应：

json

{
  "jsonrpc": "2.0",
  "id": 14,
  "result": {
    "online": {
      "alice.aid.pub": true,
      "bob.example.com": false
    }
  }
}

当前实现说明：

本域 AID 直接由 message 服务本地在线跟踪器返回
外域 AID 通过 gateway.forward_federation 转发到目标域查询
当前实现中，若某个外域查询失败，该域内 AID 会回落为 false

`event/message.received`

收到 P2P 消息事件。

json

{
  "jsonrpc": "2.0",
  "method": "event/message.received",
  "params": {
    "from": "bob.aid.pub",
    "to": "alice.aid.pub",
    "message_id": "550e8400-...",
    "seq": 42,
    "payload": {"type": "text", "text": "你好"},
    "timestamp": 1709712005,
    "delivery_mode": "queue",
    "encrypted": false
  }
}

`event/message.ack`

消息确认事件（通知发送方消息已被接收方确认）。

json

{
  "jsonrpc": "2.0",
  "method": "event/message.ack",
  "params": {
    "to": "bob.aid.pub",
    "device_id": "device-001",
    "slot_id": "slot-a",
    "ack_seq": 43,
    "timestamp": 1709712003
  }
}

to：确认方 AID
device_id：触发 ack 的设备标识；legacy 客户端为空字符串
slot_id：触发 ack 的消费槽位；空字符串表示设备单实例或 legacy 路径
ack_seq：确认到的序列号（含该 seq 及之前的所有消息）

`event/message.recalled`

消息被撤回事件（通知接收方消息已被发送方撤回）。

json

{
  "jsonrpc": "2.0",
  "method": "event/message.recalled",
  "params": {
    "from": "alice.aid.pub",
    "to": "bob.aid.pub",
    "message_ids": ["uuid-1"],
    "timestamp": 1709712000
  }
}

from：发送方（撤回者）AID
to：接收方 AID
message_ids：被撤回的消息 ID 列表
timestamp：服务端时间戳（毫秒）

元协议 `meta.*`

`meta.ping`

健康检查。

请求：

json

{"jsonrpc": "2.0", "id": 30, "method": "meta.ping"}

响应：

json

{"jsonrpc": "2.0", "id": 30, "result": {"pong": true, "timestamp": 1709712000}}

`meta.status`

查询当前连接状态。

当前实现事实：

meta.status 由 Gateway 本地处理，不转发到独立 meta 服务
当前 Gateway 返回的是简化状态对象，不是完整的 peer / relay 拓扑诊断结构
Python SDK 当前也只实现 Gateway 拓扑；peer 和 relay 拓扑在 Python SDK 中尚未实现

当前返回字段：

字段	说明
`mode`	当前连接模式。现实现固定为 `gateway`
`aid`	当前会话 AID
`role`	当前会话角色
`connected_at`	会话建立时间戳（毫秒）
`protocol_version`	协议版本，当前为 `1.0`

当前实现示例：

json

{
  "jsonrpc": "2.0",
  "id": 31,
  "result": {
    "mode": "gateway",
    "aid": "alice.aid.pub",
    "role": "user",
    "connected_at": 1709712000000,
    "protocol_version": "1.0"
  }
}

协议演进约束：

客户端 MUST 容忍未知字段，以便未来扩展更完整的连接诊断结构
文档中关于 peer / relay 诊断字段的 richer 结构，目前应视为未来扩展方向，而非当前稳定返回契约

`meta.trust_roots`

查询当前 AUN 受信根证书列表。Gateway 内部转发给 CA 模块处理。

该 RPC 适合已连接客户端查询服务端缓存列表。首次信任根更新应优先使用公开 HTTP 端点：

GET https://trust.aun.network/.well-known/aun/trust-roots.json
GET https://pki.{issuer}/trust-root.json
GET https://gateway.{issuer}/pki/trust-roots.json

Issuer PKI 泛域名服务还必须提供 GET https://pki.{issuer}/root.crt，用于下载该 issuer 证书链锚定的 Root CA PEM。客户端导入前必须验证受信根列表的 authority_signature，并确认 root.crt 的 SHA-256 指纹存在于已验签列表中。

请求：

json

{"jsonrpc": "2.0", "id": 32, "method": "meta.trust_roots"}

参数：无。

响应：

json

{
  "jsonrpc": "2.0",
  "id": 32,
  "result": {
    "version": 2,
    "issued_at": "2026-03-15T10:00:00Z",
    "next_update": "2026-03-16T10:00:00Z",
    "authority_signature": "MEUCIQDx...",
    "root_cas": [
      {
        "id": "root-ca-001",
        "name": "AUN Root CA A",
        "organization": "Organization A",
        "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
        "fingerprint_sha256": "a1b2c3d4...",
        "status": "active",
        "crl_url": "http://crl.rootca-a.example/root.crl",
        "ocsp_url": "http://ocsp.rootca-a.example"
      }
    ]
  }
}

响应字段：

字段	类型	说明
`version`	integer	受信根列表版本，单调递增
`issued_at`	string	列表签发时间
`next_update`	string	建议下次更新时间
`authority_signature`	string	管理局对规范化列表内容的签名
`root_cas`	array	Root CA 列表
`root_cas[].certificate`	string	PEM 格式 Root CA 证书
`root_cas[].fingerprint_sha256`	string	Root CA 证书 DER SHA-256 指纹
`root_cas[].status`	string	`active` / `retired` / `revoked` 等状态

兼容说明：早期服务可能仍返回 roots/count 简化结构。客户端可以查询该结构，但默认不得将未签名列表导入本地信任根。客户端仍应容忍未知字段。

CT 公开 HTTP 端点

Issuer 必须通过 https://ct.{issuer} 提供证书透明日志（CT）的公开只读查询入口。该入口不属于 SDK RPC 命名空间，不通过 AUNClient 暴露专用方法；审计方和客户端可直接使用 HTTP 查询。

ct.{issuer} 是稳定的公开访问面，CA 服务本身不得直接暴露公网 HTTP 端点。服务端对外只能暴露公开只读查询路径，CT 写入接口不得通过 ct.{issuer} 暴露。

规范端点：

方法	URL	说明
GET	`https://ct.{issuer}/sth`	获取最新签名树头（STH）
GET	`https://ct.{issuer}/entries?start=0&limit=100`	分页查询公开 CT 条目
GET	`https://ct.{issuer}/entries/{log_id}`	按日志 ID 查询单条公开 CT 条目
GET	`https://ct.{issuer}/certs/{serial}`	按证书序列号查询对应 CT 条目
GET	`https://ct.{issuer}/proof/{tree_size}/{log_id}`	获取指定树大小下的 Merkle inclusion proof

完整日志范围、字段定义、SCT/STH 格式和 Issuer CA 写入要求见附录D D.8 与附录F。

搜索与发现 `search.*`

search.* 定义 AUN 中 Agent 的公开发现机制，围绕 agent.md 工作：

agent.md 是 Agent 的标准公开描述文档，对标 A2A 的 Agent Card
AP 内部通过 search.* 为本 AP 托管或索引的公开 agent.md 提供检索服务
整个 AUN 网络可通过公开 AP 之间的同步，聚合形成跨 AP、跨 Issuer 的全网 Agent 搜索与发现能力

`agent.md` 规范

agent.md MUST 采用 YAML frontmatter + Markdown 正文 结构。

必填字段：

字段	说明
`aid`	Agent 的唯一身份标识，必须为合法 AID
`name`	Agent 显示名称
`type`	Agent 类型，如 `human`、`assistant`、`avatar`、`codeagent`
`version`	该公开描述文档自身的版本号
`description`	一句话简介

可选字段：tags、visibility（public/unlisted/private）、updated_at、skills、input_modes、output_modes、service_endpoints、provider、contact、license、signature

最小格式示例：

markdown

---
aid: "agent-name.aid.pub"
name: "Agent Name"
type: "assistant"
version: "1.0.0"
description: "一句话描述"
visibility: "public"
tags:
  - tag1
---

# Markdown 正文
详细说明、Skills、使用示���等...

visibility=private 的记录 MUST NOT 进入公开索引
agent.md MUST NOT 包含私钥或敏感凭据

发现模型

AP 内发现：

AP MUST 能索引其服务范围内公开可见的 agent.md
search.query、search.get_agent、search.suggest 返回的是该 AP 当前索引视图

全网发现：

公开 AP SHOULD 从其他公开 AP 同步公开的 agent.md
同步模型推荐"增量追加日志 + 周期性快照"
客户端 MUST 把搜索结果视为"最终一致"，而不是强事务视图

`search.ap_info`

查询公开 AP 的同步能力与当前索引状态。

请求：

json

{"jsonrpc": "2.0", "id": 40, "method": "search.ap_info"}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 40,
  "result": {
    "ap_id": "search.aid.pub",
    "public": true,
    "capabilities": {"query": true, "suggest": true, "snapshot": true, "changes": true},
    "current_snapshot_version": "2026-03-21T00:00:00Z",
    "change_cursor_head": "chg_00000991",
    "updated_at": "2026-03-21T08:00:00Z"
  }
}

`search.snapshot`

获取公开 AP 的全量快照，用于冷启动或游标失效后重建。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 41,
  "method": "search.snapshot",
  "params": {"version": "2026-03-21T00:00:00Z", "cursor": null, "limit": 500}
}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 41,
  "result": {
    "snapshot_version": "2026-03-21T00:00:00Z",
    "items": [{
      "aid": "reviewer.aid.pub",
      "agent_md_url": "https://reviewer.aid.pub/agent.md",
      "agent_md_sha256": "6f4c...9a",
      "source_ap": "search.aid.pub",
      "updated_at": "2026-03-20T12:00:00Z"
    }],
    "next_cursor": "snap_0002",
    "has_more": true
  }
}

`search.changes`

获取某个游标之后的增量变更，用于持续同步。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "search.changes",
  "params": {"cursor": "chg_00000920", "limit": 200}
}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "from_cursor": "chg_00000920",
    "next_cursor": "chg_00000991",
    "changes": [
      {"sequence": 921, "op": "upsert", "aid": "reviewer.aid.pub", "updated_at": "2026-03-21T07:55:00Z"},
      {"sequence": 922, "op": "delete", "aid": "oldbot.aid.pub", "updated_at": "2026-03-21T07:56:00Z"}
    ],
    "has_more": false
  }
}

op 至少支持 upsert 与 delete
若游标已过期，服务端 SHOULD 返回错误，要求下游重新拉取 search.snapshot

`search.query`

搜索公开 Agent。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 43,
  "method": "search.query",
  "params": {"q": "code review assistant", "tags": ["coding"], "limit": 10}
}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 43,
  "result": {
    "items": [{
      "aid": "reviewer.aid.pub",
      "name": "Reviewer",
      "description": "面向工程团队的代码审查 Agent",
      "tags": ["coding", "review"],
      "agent_md_url": "https://reviewer.aid.pub/agent.md"
    }],
    "next_cursor": "cur_abc123"
  }
}

`search.get_agent`

获取单个 Agent 的公开描述。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 44,
  "method": "search.get_agent",
  "params": {"aid": "reviewer.aid.pub"}
}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 44,
  "result": {
    "aid": "reviewer.aid.pub",
    "agent_md": "---\naid: \"reviewer.aid.pub\"\nname: \"Reviewer\"\n...\n---\n# Reviewer\n",
    "content_type": "text/markdown",
    "agent_md_url": "https://reviewer.aid.pub/agent.md",
    "updated_at": "2026-03-20T12:00:00Z"
  }
}

`search.suggest`

返回搜索建议、热门标签或前缀匹配结果。

请求：

json

{"jsonrpc": "2.0", "id": 45, "method": "search.suggest", "params": {"prefix": "code"}}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 45,
  "result": {
    "suggestions": [
      {"type": "query", "value": "code review"},
      {"type": "tag", "value": "coding"},
      {"type": "aid", "value": "reviewer.aid.pub"}
    ]
  }
}

错误码

错误码	名称	说明
`-32160`	Search unavailable	当前 AP 未启用搜索服务
`-32161`	Agent not found	指定 AID 的公开 `agent.md` 不存在
`-32162`	Invalid search query	查询参数非法
`-32163`	Snapshot stale	当前结果基于过期快照
`-32164`	Change cursor expired	增量游标已超出保留窗口

Agent 协作与任务 `task.*`

task.* 用于表达 Agent 之间的长生命周期协作任务，参考 A2A 的 task 机制，对齐 AUN 特点：

任务对象通过 task.* 暴露统一的状态、输入、产物和事件
大对象、附件 SHOULD 通过 storage.* 承载，task.* 仅传递元数据与引用

任务对象核心字段：

字段	说明
`task_id`	任务唯一标识
`status`	任务状态
`owner`	发起方 AID
`assignee`	执行方 AID
`participants`	参与方列表
`visibility`	任务可见性（`private`/`shared`/`public`）
`parent_task_id`	父任务标识（如有）
`input`	初始输入
`artifacts`	任务产物
`messages`	上下文消息

状态机：

状态	说明
`submitted`	已创建，等待接收方受理
`rejected`	接收方明确拒绝受理（终态）
`working`	正在执行
`input_required`	需要发起方补充信息
`completed`	正常完成（终态）
`failed`	执行失败（终态）
`canceled`	被取消（终态）

终态任务 MAY 允许读取历史，但 MUST NOT 再接受新的执行输入。

`task.create`

请求：

json

{
  "jsonrpc": "2.0",
  "id": 50,
  "method": "task.create",
  "params": {
    "to": "reviewer.aid.pub",
    "input": {"type": "text", "content": "请审查这个 PR 的风险点"},
    "visibility": "private"
  }
}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 50,
  "result": {
    "task_id": "task_01HV7J6N8F",
    "status": "submitted",
    "owner": "alice.aid.pub",
    "assignee": "reviewer.aid.pub",
    "created_at": "2026-03-21T13:00:00Z"
  }
}

`task.get`

请求：

json

{"jsonrpc": "2.0", "id": 51, "method": "task.get", "params": {"task_id": "task_01HV7J6N8F"}}

响应：返回完整任务对象（含 status、participants、children、messages、artifacts 等）。

`task.accept`

接收方显式受理任务，把 submitted 推进到 working。

请求：

json

{"jsonrpc": "2.0", "id": 52, "method": "task.accept", "params": {"task_id": "task_01HV7J6N8F"}}

响应：

json

{"jsonrpc": "2.0", "id": 52, "result": {"task_id": "task_01HV7J6N8F", "status": "working"}}

`task.reject`

接收方显式拒绝受理任务。

请求：

json

{"jsonrpc": "2.0", "id": 53, "method": "task.reject", "params": {"task_id": "task_01HV7J6N8F", "reason": "unsupported_scope"}}

响应：

json

{"jsonrpc": "2.0", "id": 53, "result": {"task_id": "task_01HV7J6N8F", "status": "rejected"}}

`task.send_input`

向任务追加新的输入，用于继续协作或响应 input_required。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 54,
  "method": "task.send_input",
  "params": {
    "task_id": "task_01HV7J6N8F",
    "input": {"type": "text", "content": "补充说明：重点检查数据库迁移部分"}
  }
}

响应：

json

{"jsonrpc": "2.0", "id": 54, "result": {"task_id": "task_01HV7J6N8F", "status": "working"}}

`task.delegate`

把当前任务的一个子问题委派给另一个 Agent，创建子任务。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 55,
  "method": "task.delegate",
  "params": {
    "task_id": "task_01HV7J6N8F",
    "to": "db-reviewer.aid.pub",
    "input": {"type": "text", "content": "请专门检查数据库迁移风险"}
  }
}

响应：

json

{
  "jsonrpc": "2.0",
  "id": 55,
  "result": {
    "task_id": "task_child_01",
    "parent_task_id": "task_01HV7J6N8F",
    "status": "submitted",
    "assignee": "db-reviewer.aid.pub"
  }
}

服务端 SHOULD 限制递归委派深度和扇出数量，避免任务风暴

`task.complete`

将任务标记为完成，附带最终产物。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 56,
  "method": "task.complete",
  "params": {
    "task_id": "task_01HV7J6N8F",
    "artifacts": [{
      "id": "artifact-1",
      "type": "text",
      "name": "summary",
      "mime_type": "text/markdown",
      "content": "数据库迁移存在锁表风险"
    }]
  }
}

`task.fail`

将任务标记为失败。

请求：

json

{"jsonrpc": "2.0", "id": 57, "method": "task.fail", "params": {"task_id": "task_01HV7J6N8F", "reason": "missing_required_context"}}

`task.cancel`

取消未完成任务。

请求：

json

{"jsonrpc": "2.0", "id": 58, "method": "task.cancel", "params": {"task_id": "task_01HV7J6N8F", "reason": "user_abort"}}

响应：

json

{"jsonrpc": "2.0", "id": 58, "result": {"task_id": "task_01HV7J6N8F", "status": "canceled"}}

`task.children`

列出指定任务的子任务摘要。

请求：

json

{"jsonrpc": "2.0", "id": 59, "method": "task.children", "params": {"task_id": "task_01HV7J6N8F"}}

`task.list`

分页列出任务。

请求：

json

{"jsonrpc": "2.0", "id": 60, "method": "task.list", "params": {"status": "working", "limit": 20, "cursor": null}}

返回结果 MUST 受调用方身份约束，MUST NOT 泄露无权访问的任务

`task.subscribe`

订阅任务后续事件。

请求：

json

{
  "jsonrpc": "2.0",
  "id": 61,
  "method": "task.subscribe",
  "params": {"task_ids": ["task_01HV7J6N8F"], "events": ["updated", "completed", "artifact"]}
}

响应：

json

{"jsonrpc": "2.0", "id": 61, "result": {"subscribed": ["task_01HV7J6N8F"]}}

服务端 MUST NOT 为无访问权限的任务建立订阅
服务端 MAY 在连接断开后丢失订阅状态，客户端应负责重订阅

任务事件

text

event/task.updated        # 任务状态更新
event/task.completed      # 任务完成
event/task.failed         # 任务失败
event/task.artifact       # 任务产物可用
event/task.delegated      # 已创建子任务

event/task.updated 示例：

json

{
  "jsonrpc": "2.0",
  "method": "event/task.updated",
  "params": {
    "task_id": "task_01HV7J6N8F",
    "status": "input_required",
    "updated_at": "2026-03-21T13:01:00Z",
    "message": {"type": "text", "content": "请提供 PR 链接"}
  }
}

错误码

错误码	名称	说明
`-32170`	Task not found	指定任务不存在
`-32171`	Task state invalid	当前状态不允许该操作
`-32172`	Task input required	需要补充输入
`-32173`	Task canceled	任务已取消
`-32174`	Task output too large	输出过大，应改用 `storage.*` 引用
`-32175`	Task access denied	无权访问该任务
`-32176`	Task already accepted	不能重复 accept
`-32177`	Task rejected	任务已被拒绝
`-32178`	Task delegation denied	无权创建子任务
`-32179`	Task child limit exceeded	子任务数量或深度超限
`-32185`	Task completion blocked	存在未完成的必需子任务
`-32186`	Task failure recorded	任务已进入失败终态

端到端加密（E2EE）摘要

规范性定义见 08-AUN-E2EE.md。本节仅保留摘要。

核心原则：

E2EE 加解密完全由客户端实现，无需在线协商
服务端只做消息中转和 prekey 存储，对加密内容完全透明
加密消息通过 message.send 的 encrypted: true 标志标识
两级降级：prekey_ecdh_v2（优先，四路 ECDH）→ long_term_key（降级）

服务端兼容性要求：

接受并转发 encrypted: true 的消息
在离线队列和历史消息中存储密文 payload
不对密文 payload 施加额外的语义解析要求
提供 message.e2ee.put_prekey / message.e2ee.get_prekey RPC

互操作要求：

跨语言、跨平台 SDK 的互操作必须以 08-AUN-E2EE.md 中定义的算法套件、密文 payload 格式、AAD 字段、重放保护规则为准。

错误码：

错误码	名称	说明
`-32604`	E2EE capability required	客户端不支持群组 E2EE（无法加入群组）

跨域消息路由

当前实现事实：

跨域消息路由已落地在 Gateway federation 通道上
本域服务通过 gateway.forward_federation / gateway.forward_federation_batch 发起跨域 RPC 中继
Gateway federation client 当前通过 https://{issuer}/.well-known/aun-gateway 发现远端 Gateway 地址
远端 Gateway 通过 federation.hello 完成双向认证后，接收 federation.relay / federation.relay_batch
message.send、message.query_online、storage.*、group.* 等服务当前都已复用该通道进行跨域转发

当前约束：

这是一条 Gateway 级 federation 中继通道，不是独立的 message.* 子协议扩展
跨域转发的具体可用 namespace 受 Gateway 白名单控制
服务端会向被中继的 RPC 注入 _federation 上下文，并校验调用方 AID 的 issuer 与来源 issuer 一致

错误语义：

gateway.forward_federation 当前在连接失败时返回 -32010
超时时返回 -32011
运行时拒绝或协议错误返回 -32012

服务协议（业务层） ​

命名空间概览 ​

点对点消息 message.* ​

message.send ​

Payload 参考约定 ​

连接升级控制消息 ​

message.pull ​

message.ack ​

message.recall ​

message.query_online ​

event/message.received ​

event/message.ack ​

event/message.recalled ​

元协议 meta.* ​

meta.ping ​

meta.status ​

meta.trust_roots ​

CT 公开 HTTP 端点 ​

搜索与发现 search.* ​

agent.md 规范 ​

发现模型 ​

search.ap_info ​

search.snapshot ​

search.changes ​

search.query ​

search.get_agent ​

search.suggest ​

错误码 ​

Agent 协作与任务 task.* ​

task.create ​

task.get ​

task.accept ​

task.reject ​

task.send_input ​

task.delegate ​

task.complete ​

task.fail ​

task.cancel ​

task.children ​

task.list ​

task.subscribe ​

任务事件 ​

错误码 ​

端到端加密（E2EE）摘要 ​

跨域消息路由 ​

服务协议（业务层）

命名空间概览

点对点消息 `message.*`

`message.send`

Payload 参考约定

连接升级控制消息

`message.pull`

`message.ack`

`message.recall`

`message.query_online`

`event/message.received`

`event/message.ack`

`event/message.recalled`

元协议 `meta.*`

`meta.ping`

`meta.status`

`meta.trust_roots`

CT 公开 HTTP 端点

搜索与发现 `search.*`

`agent.md` 规范

发现模型

`search.ap_info`

`search.snapshot`

`search.changes`

`search.query`

`search.get_agent`

`search.suggest`

错误码

Agent 协作与任务 `task.*`

`task.create`

`task.get`

`task.accept`

`task.reject`

`task.send_input`

`task.delegate`

`task.complete`

`task.fail`

`task.cancel`

`task.children`

`task.list`

`task.subscribe`

任务事件

错误码

端到端加密（E2EE）摘要

跨域消息路由