diff --git a/01-agentnetworkprotocol-technical-white-paper.md b/01-agentnetworkprotocol-technical-white-paper.md index ac8d2c3..c884f39 100644 --- a/01-agentnetworkprotocol-technical-white-paper.md +++ b/01-agentnetworkprotocol-technical-white-paper.md @@ -154,7 +154,7 @@ sequenceDiagram Agent B Server->>Agent A Client: HTTP Response ``` -DID methods define how to create, resolve, update and deactivate DIDs and DID documents, as well as how to perform authentication and authorization. Among existing DID method drafts, the `did:web` method[^5] is built on mature Web technologies, allowing systems to create, update, and deactivate DIDs and DID documents using centralized technologies (such as cloud computing). Different systems achieve interoperability through the HTTP protocol, similar to email services on the internet, where each platform implements its own account system in a centralized way while enabling interconnection between platforms. +DID methods define how to create, resolve, update and deactivate DIDs and DID documents, as well as how to perform authentication and authorization. Among existing DID methods, the `did:web` method[^5] is built on mature Web technologies, allowing systems to create, update, and deactivate DIDs and DID documents using centralized technologies (such as cloud computing). Different systems achieve interoperability through the HTTP protocol, similar to email services on the internet, where each platform implements its own account system in a centralized way while enabling interconnection between platforms. Based on the `did:web` method, we have proposed a new DID method—`did:wba` (Web-Based Agent)—specifically designed for agent communication scenarios, adding cross-platform identity authentication processes and agent description services. The `did:wba` method inherits the advantages of `did:web` while further optimizing identity authentication mechanisms between agents, enhancing its applicability in agent networks. diff --git a/03-did-wba-method-design-specification.md b/03-did-wba-method-design-specification.md index 91dac9f..bf89b9e 100644 --- a/03-did-wba-method-design-specification.md +++ b/03-did-wba-method-design-specification.md @@ -1,4 +1,11 @@ -# did:wba Method Specification (V0.2) +# did:wba Method Specification + +- Document ID: ANP-03 +- Title: did:wba Method Specification +- Status: Released +- Version: 1.1 +- Language: English +- Applicability: This specification applies to web-based decentralized identity, cross-platform authentication, and agent communication scenarios in ANP. ## Abstract @@ -24,7 +31,7 @@ The did:wba DID method specification complies with the requirements specified in Based on the did:web method specification, this specification adds specification descriptions such as DID document limitations, cross-platform identity authentication processes, and agent description services, and proposes a new method name did:wba (Web-Based Agent). -Considering that the did:web method specification is still a draft, there may be changes in the future that are not suitable for agent communication scenarios. In addition, we have made some modifications to the specification, and reaching a consensus with the original author on the specification modification is also a long-term process, so we decided to use a new method name. +Considering that the did:web method is designed for native web-based DID use cases and may evolve in ways that do not fully fit agent communication scenarios, and that this specification introduces targeted modifications, reaching consensus with the original author on those modifications would be a long-term process. Therefore, we decided to use a new method name. In the future, we do not rule out the possibility of merging the did:wba specification into the did:web specification, and we will promote the realization of this goal. @@ -174,7 +181,7 @@ Due to the way most web servers render content, it is likely that a particular d ### 2.5 DID Document Description -Apart from DID Core, most related specifications are still in the draft stage. This section shows a subset of DID Documents used for authentication. To improve interoperability between systems, all fields marked as required must be supported by all systems, while fields marked as optional may be supported selectively. Fields defined in other standards but not listed here may also be supported selectively. +Apart from DID Core, related specifications may evolve over time. This section shows a subset of DID Documents used for authentication. To improve interoperability between systems, all fields marked as required must be supported by all systems, while fields marked as optional may be supported selectively. Fields defined in other standards but not listed here may also be supported selectively. **The recommended e1 path-type DID document example is as follows:** diff --git a/04-anp-did-wba-name-space-specification.md b/04-anp-did-wba-name-space-specification.md index a873530..9f1f371 100644 --- a/04-anp-did-wba-name-space-specification.md +++ b/04-anp-did-wba-name-space-specification.md @@ -1,8 +1,13 @@ -# ANP-DID:WBA Name Space Specification (Draft) +# ANP-DID:WBA Name Space Specification -Abbreviation: WNS (WBA Name Space) +- Document ID: ANP-04 +- Title: ANP-DID:WBA Name Space Specification +- Status: Released +- Version: 1.1 +- Language: English +- Applicability: This specification applies to human-readable Handle naming, WNS resolution, and did:wba name mapping in ANP. -Note: This specification is still in draft status and will undergo further optimization and iteration. +Abbreviation: WNS (WBA Name Space) ## Abstract diff --git a/06-anp-agent-communication-meta-protocol-specification.md b/06-anp-agent-communication-meta-protocol-specification.md index 285aadf..d5a1ef5 100644 --- a/06-anp-agent-communication-meta-protocol-specification.md +++ b/06-anp-agent-communication-meta-protocol-specification.md @@ -1,7 +1,14 @@ -# ANP-Agent Communication Meta-Protocol Specification(Draft) +# ANP-Agent Communication Meta-Protocol Specification (Draft) + +- Document ID: ANP-06 +- Title: ANP-Agent Communication Meta-Protocol Specification +- Status: Draft +- Version: 1.1-draft +- Language: English +- Applicability: This specification applies to protocol negotiation, protocol selection, and communication setup between ANP agents. Note: -- This chapter is in the draft stage and may undergo significant adjustments based on actual conditions. +- This specification is currently in draft status and has not been released. It may undergo significant adjustments based on implementation feedback and real-world use cases. - The current protocol implementation focuses on end-to-end message encryption and will later be modified to a solution based on did:wba and HTTP. ## Background diff --git a/07-anp-agent-description-protocol-specification.md b/07-anp-agent-description-protocol-specification.md index 40b8b47..39ac5ab 100644 --- a/07-anp-agent-description-protocol-specification.md +++ b/07-anp-agent-description-protocol-specification.md @@ -1,5 +1,12 @@ # ANP Agent Description Protocol Specification +- Document ID: ANP-07 +- Title: ANP Agent Description Protocol Specification +- Status: Released +- Version: 1.1 +- Language: English +- Applicability: This specification applies to Agent Description documents, interface descriptions, and capability publication in ANP. + ## Abstract This specification defines the Agent Description Protocol (ADP), a standardized protocol for describing agents. It defines how an agent publishes its public information, supported interfaces, and other details. Once other agents obtain this agent's description, they can exchange information and collaborate with this agent. diff --git a/08-ANP-Agent-Discovery-Protocol-Specification.md b/08-ANP-Agent-Discovery-Protocol-Specification.md index 109178f..4181027 100644 --- a/08-ANP-Agent-Discovery-Protocol-Specification.md +++ b/08-ANP-Agent-Discovery-Protocol-Specification.md @@ -1,4 +1,11 @@ -# ANP-Agent Discovery Protocol Specification (Draft) +# ANP-Agent Discovery Protocol Specification + +- Document ID: ANP-08 +- Title: ANP-Agent Discovery Protocol Specification +- Status: Released +- Version: 1.1 +- Language: English +- Applicability: This specification applies to active and passive discovery of agents and Agent Description documents in ANP. ## Abstract diff --git a/09-ANP-end-to-end-instant-messaging-protocol-specification.md b/09-ANP-end-to-end-instant-messaging-protocol-specification.md index bb545ba..41957b7 100644 --- a/09-ANP-end-to-end-instant-messaging-protocol-specification.md +++ b/09-ANP-end-to-end-instant-messaging-protocol-specification.md @@ -1,4 +1,11 @@ -# ANP End-to-End Instant Messaging Protocol Overview (Draft 1.0) +# ANP End-to-End Instant Messaging Protocol Overview + +- Document ID: ANP-09 +- Title: ANP End-to-End Instant Messaging Protocol Overview +- Status: draft +- Version: 1.1 +- Language: English +- Applicability: This document applies to the overview, layering, and Profile index of the ANP end-to-end instant messaging specification suite. > This document provides a top-level overview of the ANP end-to-end instant messaging specification suite. It is intended to help readers quickly understand the goals, layering, core ideas, and key technical directions of the protocol family. This document is not a clause-by-clause normative specification; normative requirements are defined by the individual Profile specifications. @@ -46,13 +53,14 @@ ANP discovers interactive service endpoints through DID documents, and uses this ### 2.3 Layered design instead of “one unified protocol” -ANP does not cram all the issues into one document, but splits them into 8 Profiles: +ANP does not cram all the issues into one document, but splits them into 9 Profiles: - P1/P2: Core Binding and Identity and Discovery - P3/P4: Basic business semantics of direct messaging and group messaging - P5/P6: E2EE Overlay of direct messaging and group messaging - P7: Attachments and large objects - P8: Federation, cross-domain service invocation and group event distribution +- P9: Group-message mentions and selector semantics The benefits of this design are: @@ -236,7 +244,7 @@ To ensure that even if the link is leaked, meaningful plaintext may not be obtai ## 6. Document structure -The following 8 Profiles constitute the current specification set of ANP: +The following 9 Profiles constitute the current specification set of ANP: |serial number|document|effect|Content overview| @@ -249,6 +257,7 @@ The following 8 Profiles constitute the current specification set of ANP: | 6 | [06-Group End-to-End Encryption](message/06-group-end-to-end-encryption.md) | Defines the group E2EE overlay | Specifies MLS-based group cryptographic state, KeyPackage publication and discovery, the mapping from base group methods to the cryptographic state machine, and the handling of `epoch` and forks. | | 7 | [07-Attachments and Object Transfer](message/07-attachments-and-object-transfer.md) | Defines attachments and large-object semantics | Specifies the `attachment_manifest`, Object Service, upload / commit / download tickets, object-level encryption, and how attachments are carried in direct messaging and group messaging. | | 8 | [08-Federation and Cross-Domain](message/08-federation-and-cross-domain.md) | Defines the principles of cross-domain service invocation | Specifies service roles, discovery and routing, service-to-service security, principles for direct cross-domain calls, group event distribution, and cross-domain success semantics. | +| 9 | [09-Message Mentions Extension](message/09-message-mentions.md) | Defines group-message mention payload semantics | Specifies structured mention objects, group selectors such as `@all`, `@agents`, and `@humans`, placement rules for Group Base and Group E2EE, and terminal-side validation. | The recommended reading order is: @@ -256,7 +265,7 @@ The recommended reading order is: - Read P1 / P2 first - Then read P3 / P4 - Then read P5 / P6 -- Finally read P7 / P8 +- Finally read P7 / P8 / P9 as needed --- diff --git a/README.cn.md b/README.cn.md index bb1fb6e..770cfb9 100644 --- a/README.cn.md +++ b/README.cn.md @@ -4,118 +4,153 @@ -## AgentNetworkProtocol(ANP) - -> TL;DR: ANP 致力于成为智能体互联网时代的 HTTP。 - - -### 目录 - -- [愿景定位](#愿景定位) -- [为什么需要 ANP](#为什么需要-anp) -- [协议三层架构](#协议三层架构) -- [快速上手](#快速上手) -- [协议SDK](#协议-sdk) -- [深入阅读](#深入阅读) -- [里程碑](#里程碑) -- [联系我们](#联系我们) -- [贡献](#贡献) - - [贡献者](#贡献者) -- [许可证](#许可证) -- [版权声明](#版权声明) +# Agent Network Protocol (ANP) -## 愿景定位 +> ANP 致力于成为智能体互联网时代的 HTTP：为智能体提供身份、命名、发现、协商、安全消息和应用层协作协议。 + +**当前规范集：** 核心协议文档已经围绕 ANP 1.1 版本线整理。已发布规范覆盖 `did:wba` 身份、WNS Handle、智能体描述、智能体发现、端到端即时消息，以及 AP2 智能体支付协议；元协议规范仍处于草案状态，当前尚未发布。 -AgentNetworkProtocol(ANP)是一个开源的智能体通信协议。 +**版本说明：** `版本：1.1` 表示规范/文档发布版本；它不改变 ANP 载荷字段 `protocolVersion`。本次发布未修改协议字段、流程或安全要求，因此示例与协议字段中的 `"protocolVersion": "1.0.0"` 保持不变。 -AgentNetworkProtocol(ANP)的目标是成为**智能体互联网时代的HTTP**。 +**备注：** 本项目未在任何平台、任何区块链发布数字货币。 -我们的愿景是**定义智能体之间的连接方式，为数十亿智能体构建一个开放、安全、高效的协作网络**。 +## 愿景定位 + +Agent Network Protocol（ANP）是一个开源的智能体通信协议，目标是定义智能体之间的连接方式，为数十亿智能体构建开放、安全、高效的协作网络。

- Agentic Web + Agentic Web

-我们相信，智能体互联网是继人类互联网之后的新一代信息基础设施，将彻底改变数字世界的连接方式与协作模式。在这个愿景中： +我们相信，智能体互联网是继人类互联网之后的新一代信息基础设施。在这个愿景中： -- **从平台中心到协议中心**：当前互联网生态系统是以平台为中心的模式，数据和服务被锁在"数字孤岛"中。智能体互联网将重塑这种不平衡格局，让互联网从封闭、碎片化的状态，回归开放、自由连接的本源。 +- **从平台中心到协议中心：** 数据和服务不应继续被锁在封闭平台里，智能体需要开放协议实现直接连接。 +- **连接即力量：** 每个智能体既可以是信息消费者，也可以是服务提供者，并能发现、连接和协作。 +- **AI 原生网络：** 智能体应通过语义明确、机器可读、可调用的协议交互，而不是只能模仿人类浏览网页。 -- **连接即力量**：在真正开放、互联的网络中，节点间的自由交互能最大限度激发创新潜力并创造巨大价值。未来每个智能体都将同时是信息消费者和服务提供者，每个节点都能无障碍地发现、连接并与网络中任何其他节点交互。 +## 为什么需要 ANP -- **AI原生网络**：不同于为人类设计的网页与界面，智能体互联网将构建一个面向AI友好的原生数据网络，所有节点都是可描述、可发现、可调用的智能体或数据单元，每个链接都是语义明确、结构统一的协议连接。 +当前互联网基础设施已经成熟，但仍缺少面向大规模智能体网络的通信和连接层。ANP 重点解决三类问题： -这个愿景需要一个类似HTTP之于人类互联网的基础协议——这正是ANP诞生的原因。 +- 🌐 **互联互通：** 让不同平台、不同域名下的智能体能够相互认证、发现和通信。 +- 🖥️ **原生接口：** 让 AI 使用 API、协议文档、结构化描述和协商接口，而不是模拟人类访问网页。 +- 🤝 **高效协作：** 让智能体能够自组织、自协商，构建更低成本的协作网络。 -**备注**：本项目未在任何平台、任何区块链发布数字货币。 +## 协议架构 -## 为什么需要 ANP +

+ 协议架构图 +

-当前互联网基础设施虽已相当完善，但针对智能体网络的特殊需求，当下仍缺乏最适合的通信和连接方案。我们致力于解决智能体网络面临的三大挑战： +ANP 构建在现有互联网基础设施之上，将已发布的协议能力组织为两个核心协议层，并在其上承载具体领域的应用协议： -- 🌐 **互联互通**：让所有的智能体相互之间都能够进行通信，打破数据孤岛，让AI能够获得完整的上下文信息。 -- 🖥️ **原生接口**：AI无需模仿人类访问互联网，AI应该用它最擅长的方式（API或通信协议）与数字世界交互。 -- 🤝 **高效协作**：利用AI，智能体之间可以自组织、自协商，构建比现有互联网更低成本、更高效率的协作网络。 +- 🌐 **开放互联网基础设施：** ANP 复用 HTTP、CA、DNS、CDN、Search、TLS 等成熟基础设施，而不是重新构建一套网络栈。 +- 🔒 **身份与加密通信层：** 基于 W3C DID 和 Web 基础设施，提供智能体身份、`did:wba` 认证和端到端加密消息基础能力。 +- 📡 **应用协议层：** 包含智能体描述、智能体发现和智能体应用协议。智能体支付、授权、认证、交易等领域协议构建在这一层之上。 +- 🧪 **元协议状态：** ANP-06 当前仍为草案，暂不属于已发布架构；待协议协商设计稳定后再发布。 -## 协议三层架构 +## 协议规范索引 -

- 协议分层图 -

+| 领域 | 文档 | 状态 | 定义内容 | +| --- | --- | --- | --- | +| 总览 | [ANP 技术白皮书](chinese/01-AgentNetworkProtocol技术白皮书.md) | 白皮书 | 愿景、设计原则和三层协议架构 | +| 身份 | [ANP-03：did:wba 方法规范](chinese/03-did-wba方法规范.md) | 已发布 v1.1 | Web DID 方法、跨平台认证、`e1_` Ed25519 绑定、`k1_` 兼容扩展 | +| 命名 | [ANP-04：基于 DID:WBA 的命名空间规范](chinese/04-ANP-基于DID-WBA的命名空间规范.md) | 已发布 v1.1 | WNS Handle（如 `alice.example.com`）、Handle 到 DID 的解析、DID 轮换支持 | +| 元协议 | [ANP-06：智能体通信元协议规范](chinese/06-ANP-智能体通信元协议规范.md) | Draft / 未发布 | 智能体之间的协议协商、协议选择和通信建立 | +| 描述 | [ANP-07：智能体描述协议规范](chinese/07-ANP-智能体描述协议规范.md) | 已发布 v1.1 | 智能体描述文档、接口描述和能力发布 | +| 发现 | [ANP-08：智能体发现协议规范](chinese/08-ANP-智能体发现协议规范.md) | 已发布 v1.1 | 基于 `.well-known` 的主动发现，以及向搜索智能体注册的被动发现 | +| 消息 | [ANP-09：端到端即时消息协议规范总纲](chinese/09-ANP-端到端即时消息协议规范.md) | 已发布 v1.1 | 私聊、群聊、端到端加密、附件、联邦和 mention 场景的 Profile 索引 | +| 支付 | [ANP-10：智能体支付协议规范（AP2）](chinese/application/10-ANP-智能体支付协议规范.md) | 中文草案 v0.1；英文 v1.1 | 智能体支付、授权凭证、收据、基于 DID 的签名和交易流程 | -- 🔒 **身份与加密通信层**：基于W3C DID（Decentralized Identifiers，去中心化标识符）规范，在现有成熟的Web基础设施上，构建一个去中心化的身份认证方案和端到端加密通信方案。它可以让任意平台之间的智能体进行身份认证，而不依赖于任何中心化系统。 -- 🌍 **元协议层**：元协议即协商智能体之间通信协议的协议。是智能体网络演进为自组织、自协商的高效协作网络的关键。 -- 📡 **应用协议层**：基于语义网相关规范，让智能体能够描述其他能力与支持的应用协议，并且高效的管理这些协议。 +### 即时消息 Profile + +ANP 端到端即时消息规范集拆分为多个独立 Profile： + +1. [P1 核心绑定](chinese/message/01-核心绑定.md)：JSON-RPC 2.0 绑定、请求/响应/错误约定。 +2. [P2 身份与发现](chinese/message/02-身份与发现.md)：基于 DID 的服务发现和端点能力发现。 +3. [P3 私聊基础语义](chinese/message/03-私聊基础语义.md)：私聊发送和回执。 +4. [P4 群组基础语义](chinese/message/04-群组基础语义.md)：群生命周期、成员关系和群消息语义。 +5. [P5 私聊端到端加密](chinese/message/05-私聊端到端加密.md)：私聊消息的 E2EE Overlay。 +6. [P6 群组端到端加密](chinese/message/06-群组端到端加密.md)：群消息的 E2EE Overlay。 +7. [P7 附件与对象传输](chinese/message/07-附件与对象传输.md)：Manifest、对象服务和大对象传输。 +8. [P8 联邦与跨域](chinese/message/08-联邦与跨域.md)：跨域路由、转发和结果见证。 +9. [P9 消息 Mention 扩展](chinese/message/09-消息Mention扩展.md)：群消息 mention 载荷和 selector 语义。 + +### DID 兼容性附录 + +- [附录 A：did:wba `k1_` 兼容扩展](chinese/附录A：did-wba-k1_兼容扩展.md) +- [附录 B：与原生 `did:web` 的兼容](chinese/附录B：与原生did-web-的兼容.md) ## 快速上手 -如果你想快速了解ANP的基本概念和使用方法，可以查看我们的入门指南：[ANP入门指南](docs/chinese/ANP入门指南.md) +- 如果想快速了解 ANP 概念和使用方式，请阅读 [ANP 入门指南](docs/chinese/ANP入门指南.md)。 +- 如果要实现智能体身份与认证，请从 [ANP-03：did:wba 方法规范](chinese/03-did-wba方法规范.md) 和两个 DID 兼容性附录开始。 +- 如果要发布智能体，请阅读 [ANP-07：智能体描述协议规范](chinese/07-ANP-智能体描述协议规范.md) 和 [ANP-08：智能体发现协议规范](chinese/08-ANP-智能体发现协议规范.md)。 +- 如果要构建即时消息，请从 [ANP-09](chinese/09-ANP-端到端即时消息协议规范.md) 开始，再按需选择具体 Profile。 +- 如果想运行 ANP 相关 Demo，请查看 [ANP 示例程序](docs/chinese/ANP示例程序.md)。 + +## 协议 SDK -如果你想快速的运行ANP相关demo，可以查看我们的示例程序说明文档：[ANP示例程序](docs/chinese/ANP示例程序.md) +ANP 的开源实现维护在 AgentConnect 仓库： -## 协议SDK +- [https://github.com/agent-network-protocol/AgentConnect](https://github.com/agent-network-protocol/AgentConnect) -我们正在开发一个开源的 AgentNetworkProtocol 实现，仓库地址：[https://github.com/agent-network-protocol/AgentConnect](https://github.com/agent-network-protocol/AgentConnect) +AgentConnect 重点提供 `did:wba`、身份认证、智能体描述、协议协商、安全通信和应用层协议的 SDK 支持。 + +## 仓库结构 + +- `01-*.md`、`03-*.md`、`04-*.md`、`06-*.md`、`07-*.md`、`08-*.md`、`09-*.md`：英文核心协议文档。 +- `application/`：AP2 等应用层协议。 +- `message/`：ANP 端到端即时消息 Profile 规范集。 +- `chinese/`：核心规范中文版及相关研究笔记。 +- `docs/`：指南、扩展阅读和社区运营文档。 +- `blogs/`：技术文章和协议分析。 +- `examples/`：ADP 示例资产和 API 接口示例。 +- `images/`、`standard/`：共享图和标准化参考资料。 ## 深入阅读 -- 完整资料见 [拓展阅读](docs/links.md) -- 查看详细设计请阅读 [ANP 技术白皮书](chinese/01-AgentNetworkProtocol技术白皮书.md) -- 协议开源实现 [AgentConnect 示例](https://github.com/agent-network-protocol/AgentConnect) -## 里程碑 +- [扩展阅读](docs/chinese/links.md) +- [ANP 技术白皮书](chinese/01-AgentNetworkProtocol技术白皮书.md) +- [AgentConnect 示例](https://github.com/agent-network-protocol/AgentConnect) -无论是协议还是开源代码实现，我们整体式是按照以下的顺序逐步的推进： +## 里程碑 -- [x] 构建身份认证与端到端加密通信协议与实现。这是我们整个项目的基础与核心，当前协议设计和代码基本完成。 -- [x] 元协议设计与元协议代码实现。当前协议设计和代码开发基本完成。 -- [x] 应用层协议设计与开发。 - - [x] 支持智能体描述。 - - [x] 支持智能体发现。 - - [ ] 特定领域使用的应用协议设计 +- [x] 定义并实现身份认证与安全通信基础。 +- [x] 发布 `did:wba` v1.1，默认支持 `e1_` Ed25519 路径绑定，并提供 `k1_` 与原生 `did:web` 兼容说明。 +- [x] 定义 WNS Handle，作为 DID 智能体的人类可读命名层。 +- [x] 发布智能体描述协议和智能体发现协议。 +- [ ] 元协议仍为草案，待稳定后发布。 +- [x] 将端到端即时消息拆分为总纲和九个可互操作 Profile。 +- [x] 在应用层加入 AP2 智能体支付协议。 +- [ ] 持续推进 SDK 实现与示例对齐 ANP 1.1 规范集。 +- [ ] 持续推进标准化工作，并扩展更多领域应用协议。 ## 联系我们 -我们已经成立了一个ANP开源技术社区，以开源社区的方式推进ANP的建设。诚挚的邀请您加入我们的开源技术社区，我们的创始委员会、社区顾问、技术委员会、发展委员会、企业观察员等团队持续招募中。 +我们已经成立 ANP 开源技术社区，以开源社区方式推进 ANP 建设。诚挚邀请你加入社区。 -邮箱：chgaowei@gmail.com -- Discord: [https://discord.gg/sFjBKTY7sB](https://discord.gg/sFjBKTY7sB) -- 官网：[https://agent-network-protocol.com/](https://agent-network-protocol.com/) +- 邮箱：chgaowei@gmail.com +- Discord：[https://discord.gg/sFjBKTY7sB](https://discord.gg/sFjBKTY7sB) +- 官网：[https://agent-network-protocol.com/](https://agent-network-protocol.com/) - GitHub：[https://github.com/agent-network-protocol/AgentNetworkProtocol](https://github.com/agent-network-protocol/AgentNetworkProtocol) - 微信：flow10240 ## 贡献 -我们欢迎任何形式的贡献，请参考 [CONTRIBUTING.cn.md](CONTRIBUTING.cn.md) 文件。 +我们欢迎任何形式的贡献，请参考 [CONTRIBUTING.cn.md](CONTRIBUTING.cn.md)。 ### 贡献者 -我们向所有为 Agent Network Protocol 项目做出贡献的人表示衷心的感谢。您可以在这里查看完整的贡献者列表： +感谢所有为 Agent Network Protocol 项目做出贡献的人。 -- [贡献者名单 (Chinese)](CONTRIBUTORS.cn.md) +- [贡献者名单](CONTRIBUTORS.cn.md) ## 许可证 -本项目基于 MIT 许可证开源，详情请参考 [LICENSE](LICENSE) 文件。但版权归属于常高伟（GaoWei Chang）。任何使用本项目的用户必须保留原始版权声明和许可证文件。 +本项目基于 MIT 许可证开源，详情请参考 [LICENSE](LICENSE)。版权归属于常高伟（GaoWei Chang）。任何使用本项目的用户必须保留原始版权声明和许可证文件。 + +## 版权声明 -## 版权声明 Copyright (c) 2024 GaoWei Chang 本文件依据 [MIT 许可证](./LICENSE) 发布，您可以自由使用和修改，但必须保留本版权声明。 diff --git a/README.md b/README.md index e82f08b..4bef8f8 100644 --- a/README.md +++ b/README.md @@ -4,121 +4,151 @@ -## Agent Network Protocol (ANP) +# Agent Network Protocol (ANP) -> TL;DR: ANP aims to become the HTTP of the Agentic Web era. +> ANP aims to become the HTTP of the Agentic Web era: a protocol suite for agent identity, naming, discovery, negotiation, secure messaging, and application-level collaboration. - +**Current specification set:** the core protocol documents have been organized around the ANP 1.1 release line. The released suite covers `did:wba` identity, WNS handles, agent description, agent discovery, end-to-end instant messaging, and the AP2 agent payment protocol. The meta-protocol specification remains a draft and is not released yet. -### Table of Contents +**Versioning note:** `Version: 1.1` identifies the specification/document release version. It does not change the ANP payload field `protocolVersion`; examples and protocol fields that use `"protocolVersion": "1.0.0"` remain unchanged because this release does not change protocol fields, flows, or security requirements. -- [Agent Network Protocol (ANP)](#agent-network-protocol-anp) - - [Table of Contents](#table-of-contents) -- [Vision and Positioning](#vision-and-positioning) -- [Why We Need ANP](#why-we-need-anp) -- [Three-Layer Protocol Architecture](#three-layer-protocol-architecture) -- [Quick Start](#quick-start) -- [Protocol SDK](#protocol-sdk) -- [Further Reading](#further-reading) -- [Milestones](#milestones) -- [Contact Us](#contact-us) -- [Contributing](#contributing) - - [Contributors](#contributors) -- [License](#license) -- [Copyright Notice](#copyright-notice) +**Note:** This project has not issued any digital currency on any platform or blockchain. ## Vision and Positioning -Agent Network Protocol (ANP) is an open-source communication protocol for intelligent agents. +Agent Network Protocol (ANP) is an open-source communication protocol for intelligent agents. Its goal is to define how agents connect with each other and to build an open, secure, and efficient collaboration network for billions of agents. -Agent Network Protocol (ANP) aims to become **the HTTP of the Agentic Web era**. +

+ Agentic Web +

+ +We believe the agent internet is the next generation of information infrastructure after the human-centric internet. In this vision: + +- **From platform-centric to protocol-centric:** data and services should not remain locked in isolated platforms. Agents need open protocols for direct connection. +- **Connection is power:** every agent can be both an information consumer and a service provider, able to discover, connect to, and collaborate with other nodes. +- **AI-native network:** agents should interact through semantically clear, machine-readable, and callable protocols rather than only through human-facing webpages. + +## Why We Need ANP + +Current internet infrastructure is mature, but it still lacks a communication and connection layer designed for large-scale agent networks. ANP focuses on three challenges: + +- 🌐 **Interconnection:** enable agents from different platforms and domains to authenticate, discover, and communicate with each other. +- 🖥️ **Native interfaces:** let AI use APIs, protocol documents, structured descriptions, and negotiated interfaces instead of imitating human browsing. +- 🤝 **Efficient collaboration:** allow agents to self-organize, self-negotiate, and build lower-cost collaboration networks. -Our vision is to **define how agents connect with each other, building an open, secure, and efficient collaboration network for billions of agents**. +## Protocol Architecture

- Agentic Web + Protocol Architecture Diagram

-We believe that the agent internet represents the next generation of information infrastructure succeeding the human-centric internet, which will fundamentally transform how the digital world connects and collaborates. In this vision: +ANP is built on existing Internet infrastructure and organizes the released protocol capabilities into two core protocol layers plus domain-specific application protocols: -- **From Platform-Centric to Protocol-Centric**: The current internet ecosystem is built around platforms, where data and services are locked in "digital silos." The agent internet will reshape this imbalance, returning the internet from a closed, fragmented state to its open, freely connected origins. +- 🌐 **Open Internet Infrastructure:** ANP reuses HTTP, CA, DNS, CDN, Search, and TLS instead of rebuilding a new network stack. +- 🔒 **Identity and Encrypted Communication Layer:** based on W3C DID and Web infrastructure. This layer provides agent identity, `did:wba` authentication, and end-to-end encrypted messaging foundations. +- 📡 **Application Protocol Layer:** includes Agent Description, Agent Discovery, and Agent Application Protocols. Domain protocols such as agent payment, authorization, authentication, and transaction protocols are built on top of this layer. +- 🧪 **Meta-protocol status:** ANP-06 remains a draft and is not part of the currently released architecture. It will be released after the protocol negotiation design is stabilized. -- **Connection is Power**: In a truly open, interconnected network, free interaction between nodes maximizes innovation potential and creates tremendous value. In the future, each agent will be both an information consumer and a service provider, with every node able to discover, connect, and interact with any other node in the network without barriers. +## Protocol Specification Index -- **AI-Native Network**: Unlike webpages and interfaces designed for humans, the agent internet will build an AI-friendly native data network where all nodes are describable, discoverable, and callable agents or data units, and every link is a semantically clear, structurally unified protocol connection. +| Area | Document | Status | What it defines | +| --- | --- | --- | --- | +| Overview | [ANP Technical White Paper](01-agentnetworkprotocol-technical-white-paper.md) | White paper | Vision, design principles, and the three-layer architecture | +| Identity | [ANP-03: did:wba Method Specification](03-did-wba-method-design-specification.md) | Released v1.1 | Web-based DID method, cross-platform authentication, `e1_` Ed25519 binding, `k1_` compatibility extension | +| Naming | [ANP-04: ANP-DID:WBA Name Space Specification](04-anp-did-wba-name-space-specification.md) | Released v1.1 | WNS handles such as `alice.example.com`, Handle-to-DID resolution, DID rotation support | +| Meta-protocol | [ANP-06: Agent Communication Meta-Protocol](06-anp-agent-communication-meta-protocol-specification.md) | Draft / not released | Protocol negotiation, selection, and communication setup between agents | +| Description | [ANP-07: Agent Description Protocol](07-anp-agent-description-protocol-specification.md) | Released v1.1 | Agent Description documents, interface descriptions, and capability publication | +| Discovery | [ANP-08: Agent Discovery Protocol](08-anp-agent-discovery-protocol-specification.md) | Released v1.1 | Active `.well-known` discovery and passive registration with search agents | +| Messaging | [ANP-09: End-to-End Instant Messaging Overview](09-ANP-end-to-end-instant-messaging-protocol-specification.md) | Released v1.1 | Profile index for direct messaging, group messaging, E2EE, attachments, federation, and mentions | +| Payments | [ANP-10: Agent Payment Protocol (AP2)](application/10-anp-agent-payment-protocol-specification.md) | Released v1.1 (EN); CN draft available | Agent-to-agent payments, mandates, receipts, DID-based signatures, and payment flows | -This vision requires a foundational protocol similar to what HTTP is for the human internet—this is precisely why ANP was created. +### Instant Messaging Profiles -**Note**: This project has not issued any digital currency on any platform or blockchain. +The ANP end-to-end instant messaging suite is split into focused profiles: -## Why We Need ANP +1. [P1 Core Binding](message/01-core-binding.md): JSON-RPC 2.0 binding, request/response/error conventions. +2. [P2 Identity and Discovery](message/02-identity-and-discovery.md): DID-based service discovery and endpoint capability discovery. +3. [P3 Direct Messaging Base Semantics](message/03-direct-messaging-base-semantics.md): direct message sending and receipts. +4. [P4 Group Messaging Base Semantics](message/04-group-messaging-base-semantics.md): group lifecycle, membership, and group message semantics. +5. [P5 Direct End-to-End Encryption](message/05-direct-end-to-end-encryption.md): E2EE overlay for direct messaging. +6. [P6 Group End-to-End Encryption](message/06-group-end-to-end-encryption.md): E2EE overlay for group messaging. +7. [P7 Attachments and Object Transfer](message/07-attachments-and-object-transfer.md): manifests, object services, and large-object transfer. +8. [P8 Federation and Cross-Domain](message/08-federation-and-cross-domain.md): cross-domain routing, relaying, and result witnessing. +9. [P9 Message Mentions Extension](message/09-message-mentions.md): group-message mention payloads and selector semantics. -While current internet infrastructure is quite comprehensive, there remains a lack of optimal communication and connection solutions for the specific needs of agent networks. We are committed to addressing three major challenges facing agent networks: +### DID Compatibility Appendices -- 🌐 **Interconnection**: Enabling all agents to communicate with each other, breaking down data silos, and allowing AI to access complete contextual information. -- 🖥️ **Native Interfaces**: AI should not need to mimic human internet browsing; instead, AI should interact with the digital world using its most proficient methods (APIs or communication protocols). -- 🤝 **Efficient Collaboration**: Using AI, agents can self-organize and self-negotiate to build a more cost-effective and efficient collaboration network than the existing internet. +- [Appendix A: did:wba `k1_` Compatibility Extension](appendix-a-did-wba-k1-compatibility-extension.md) +- [Appendix B: Compatibility with Native `did:web`](appendix-b-compatibility-with-native-did-web.md) -## Three-Layer Protocol Architecture +## Quick Start -

- Protocol Layer Diagram -

+- To understand ANP concepts and usage, read the [ANP Getting Started Guide](docs/anp-getting-started-guide.md) or the [Chinese guide](docs/chinese/ANP入门指南.md). +- To implement agent identity and authentication, start from [ANP-03: did:wba](03-did-wba-method-design-specification.md) and the two DID compatibility appendices. +- To publish an agent, read [ANP-07: Agent Description Protocol](07-anp-agent-description-protocol-specification.md) and [ANP-08: Agent Discovery Protocol](08-anp-agent-discovery-protocol-specification.md). +- To build messaging, start from [ANP-09](09-ANP-end-to-end-instant-messaging-protocol-specification.md) and then choose the required messaging profiles. +- To run demos, see [ANP Sample Programs](docs/chinese/ANP示例程序.md). -- 🔒 **Identity and Secure Communication Layer**: Based on the W3C DID (Decentralized Identifiers) specification, this layer leverages existing mature web infrastructure to create a decentralized identity authentication scheme and an end-to-end encrypted communication solution. It allows agents from any platform to authenticate each other without relying on any centralized system. -- 🌍 **Meta-Protocol Layer**: A protocol for negotiating communication protocols between agents. It is key to evolving the agent network into a self-organizing, self-negotiating, efficient collaboration network. -- 📡 **Application Protocol Layer**: Based on semantic web specifications, enabling agents to describe their capabilities and supported application protocols, and efficiently manage these protocols. +## Protocol SDK -## Quick Start +The open-source implementation of ANP is maintained in the AgentConnect repository: -If you want to quickly understand the basic concepts and usage of ANP, you can check our getting started guide: [ANP Getting Started Guide](docs/chinese/ANP入门指南.md) +- [https://github.com/agent-network-protocol/AgentConnect](https://github.com/agent-network-protocol/AgentConnect) -If you want to quickly run ANP-related demos, you can check our sample program documentation: [ANP Sample Programs](docs/chinese/ANP示例程序.md) +AgentConnect focuses on practical SDK support for `did:wba`, authentication, agent description, protocol negotiation, secure communication, and application protocols. -## Protocol SDK +## Repository Layout -We are developing an open-source implementation of AgentNetworkProtocol, and its repository can be found at: [https://github.com/agent-network-protocol/AgentConnect](https://github.com/agent-network-protocol/AgentConnect) +- `01-*.md`, `03-*.md`, `04-*.md`, `06-*.md`, `07-*.md`, `08-*.md`, `09-*.md`: core English protocol documents. +- `application/`: application-layer protocols such as AP2. +- `message/`: the ANP end-to-end instant messaging profile suite. +- `chinese/`: Chinese versions of core specifications and related research notes. +- `docs/`: guides, extended reading, and community operations documents. +- `blogs/`: articles and protocol analysis. +- `examples/`: sample ADP assets and API interface examples. +- `images/` and `standard/`: shared figures and standardization references. ## Further Reading -- Complete materials are available at [Extended Reading](docs/links.md) -- For detailed design, please read the [ANP Technical White Paper](/01-agentnetworkprotocol-technical-white-paper.md) -- Refer to the open-source implementation [AgentConnect Examples](https://github.com/agent-network-protocol/AgentConnect) +- [Extended Reading](docs/links.md) +- [ANP Technical White Paper](01-agentnetworkprotocol-technical-white-paper.md) +- [AgentConnect Examples](https://github.com/agent-network-protocol/AgentConnect) ## Milestones -For both the protocol and open-source code implementation, we are gradually advancing in the following order: - -- [x] Build identity authentication and end-to-end encrypted communication protocol and implementation. This is the foundation and core of our entire project, with protocol design and foundational code are substantially complete. -- [x] Meta-protocol design and meta-protocol code implementation. Current protocol design and code development are substantially complete. -- [x] Application layer protocol design and development. - - [x] Support for agent description. - - [x] Support for agent discovery. - - [ ] Application protocol design for specific domains. +- [x] Define and implement the identity authentication and secure communication foundation. +- [x] Release `did:wba` v1.1 with default `e1_` Ed25519 path binding and compatibility guidance for `k1_` and native `did:web`. +- [x] Define WNS handles as a human-readable naming layer for DID-based agents. +- [x] Release the Agent Description Protocol and Agent Discovery Protocol. +- [ ] Release the meta-protocol after the draft is stabilized. +- [x] Split end-to-end instant messaging into an overview plus nine interoperable profiles. +- [x] Add the AP2 agent payment protocol to the application layer. +- [ ] Continue aligning SDK implementations and examples with the 1.1 specification set. +- [ ] Continue standardization work and expand domain-specific application protocols. ## Contact Us -We have established an ANP open-source technical community to advance ANP development through an open-source community approach. We sincerely invite you to join our open-source technical community. Our founding committee, community advisors, technical committee, development committee, enterprise observers, and other teams are continuously recruiting. +We have established an ANP open-source technical community to advance ANP development through an open-source community approach. We sincerely invite you to join our community. -Email: chgaowei@gmail.com -- Discord: [https://discord.gg/sFjBKTY7sB](https://discord.gg/sFjBKTY7sB) -- Official website: [https://agent-network-protocol.com/](https://agent-network-protocol.com/) +- Email: chgaowei@gmail.com +- Discord: [https://discord.gg/sFjBKTY7sB](https://discord.gg/sFjBKTY7sB) +- Official website: [https://agent-network-protocol.com/](https://agent-network-protocol.com/) - GitHub: [https://github.com/agent-network-protocol/AgentNetworkProtocol](https://github.com/agent-network-protocol/AgentNetworkProtocol) - WeChat: flow10240 ## Contributing -We welcome contributions in any form. Please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file. +We welcome contributions in any form. Please refer to [CONTRIBUTING.md](CONTRIBUTING.md). ### Contributors -We extend our sincere gratitude to all contributors for their outstanding work and dedication to the Agent Network Protocol project. You can view the complete list of contributors here: +We extend our sincere gratitude to all contributors for their outstanding work and dedication to the Agent Network Protocol project. -- [Contributors (English)](CONTRIBUTORS.md) +- [Contributors](CONTRIBUTORS.md) ## License -This project is open-sourced under the MIT License. For details, please refer to the [LICENSE](LICENSE) file. However, the copyright is held by GaoWei Chang. Any user of this project must retain the original copyright notice and license file. +This project is open-sourced under the MIT License. For details, please refer to [LICENSE](LICENSE). The copyright is held by GaoWei Chang. Any user of this project must retain the original copyright notice and license file. ## Copyright Notice diff --git a/application/10-anp-agent-payment-protocol-specification.md b/application/10-anp-agent-payment-protocol-specification.md index d4ed5bb..40d14be 100644 --- a/application/10-anp-agent-payment-protocol-specification.md +++ b/application/10-anp-agent-payment-protocol-specification.md @@ -1,5 +1,12 @@ # ANP Agent Payment Protocol Specification (AP2) +- Document ID: ANP-10 +- Title: ANP Agent Payment Protocol Specification +- Status: Released +- Version: 1.1 +- Language: English +- Applicability: This specification applies to payment and transaction interactions between agents in the ANP application layer. + ## Abstract This specification defines the Agent Payment Protocol (AP2), a standardized protocol for payment and transaction interactions between intelligent agents. AP2 is an application layer protocol based on ANP (Agent Network Protocol) that enables secure, efficient peer-to-peer payment transactions between agents. diff --git "a/chinese/01-AgentNetworkProtocol\346\212\200\346\234\257\347\231\275\347\232\256\344\271\246.md" "b/chinese/01-AgentNetworkProtocol\346\212\200\346\234\257\347\231\275\347\232\256\344\271\246.md" index 0ae115b..6319c9f 100644 --- "a/chinese/01-AgentNetworkProtocol\346\212\200\346\234\257\347\231\275\347\232\256\344\271\246.md" +++ "b/chinese/01-AgentNetworkProtocol\346\212\200\346\234\257\347\231\275\347\232\256\344\271\246.md" @@ -155,7 +155,7 @@ sequenceDiagram ``` -DID 方法定义了如何创建、解析、更新和停用 DID 与 DID 文档，以及如何进行身份验证和授权。在现有的 DID 方法草案中，`did:web` 方法[^5] 基于成熟的 Web 技术构建，允许系统使用中心化技术（如云计算）来创建、更新、停用 DID 和 DID 文档。不同系统之间通过 HTTP 协议实现互操作，其效果类似于互联网的emai服务，各个平台以中心化的方式实现自己的账户体系，同时，各个平台之间可以互联互通。 +DID 方法定义了如何创建、解析、更新和停用 DID 与 DID 文档，以及如何进行身份验证和授权。在现有的 DID 方法中，`did:web` 方法[^5] 基于成熟的 Web 技术构建，允许系统使用中心化技术（如云计算）来创建、更新、停用 DID 和 DID 文档。不同系统之间通过 HTTP 协议实现互操作，其效果类似于互联网的emai服务，各个平台以中心化的方式实现自己的账户体系，同时，各个平台之间可以互联互通。 基于 `did:web` 方法，我们针对智能体通信的场景，添加了跨平台身份认证流程和智能体描述服务等规范，提出了一种新的 DID 方法——`did:wba`（Web-Based Agent）。`did:wba` 方法继承了 `did:web` 的优势，进一步优化了智能体间的身份认证机制，提升了在智能体网络中的适用性。 diff --git "a/chinese/03-did-wba\346\226\271\346\263\225\350\247\204\350\214\203.md" "b/chinese/03-did-wba\346\226\271\346\263\225\350\247\204\350\214\203.md" index 81bedc2..821eddf 100644 --- "a/chinese/03-did-wba\346\226\271\346\263\225\350\247\204\350\214\203.md" +++ "b/chinese/03-did-wba\346\226\271\346\263\225\350\247\204\350\214\203.md" @@ -1,4 +1,11 @@ -# did:wba方法规范（V0.2） +# did:wba方法规范 + +- 文档编号：ANP-03 +- 标题：did:wba方法规范 +- 状态：已发布 +- 版本：1.1 +- 语言：中文 +- 适用范围：本规范适用于 ANP 中基于 Web 的去中心化身份、跨平台身份认证与智能体通信场景。 ## 摘要 @@ -24,7 +31,7 @@ wba DID方法规范符合去中心化标识符V1.0[[DID-CORE](https://www.w3.org 本规范在did:web方法规范的基础上，添加了DID文档限定、跨平台身份认证流程、智能体描述服务等规范描述，提出了新的方法名did:wba(Web-Based Agent)。 -考虑到did:web方法规范仍然是一个草案，未来可能会有不适宜智能体通信场景的改动。另外，我们对规范做了部分修改，和原作者就规范修改达成共识也是一个长期过程，所以我们决定使用一个新的方法名。 +考虑到 did:web 方法主要面向原生 Web DID 场景，未来演进可能不完全适合智能体通信场景。另外，本规范对其进行了面向智能体通信的定向修改，和原作者就这些修改达成共识也是一个长期过程，所以我们决定使用一个新的方法名。 未来不排除将did:wba规范合并到did:web规范中的可能，我们会去推动这个目标的实现。 @@ -174,7 +181,7 @@ did:wba:example.com%3A3000:user:alice:e1_ ### 2.5 DID文档说明 -除DID核心规范外，其他大部分规范尚处于草案阶段。本章节将展示一个用于身份验证的DID文档的子集。为了提高系统间的兼容性，所有标注为必须的字段，所有系统必须支持；标注为可选的字段，可以选择性支持。未列出的其他标准中定义的字段，可以选择性支持。 +除 DID 核心规范外，相关规范可能会随时间演进。本章节将展示一个用于身份验证的 DID 文档的子集。为了提高系统间的兼容性，所有标注为必须的字段，所有系统必须支持；标注为可选的字段，可以选择性支持。未列出的其他标准中定义的字段，可以选择性支持。 **推荐的 e1 路径型 DID 文档示例如下：** diff --git "a/chinese/04-ANP-\345\237\272\344\272\216DID-WBA\347\232\204\345\221\275\345\220\215\347\251\272\351\227\264\350\247\204\350\214\203.md" "b/chinese/04-ANP-\345\237\272\344\272\216DID-WBA\347\232\204\345\221\275\345\220\215\347\251\272\351\227\264\350\247\204\350\214\203.md" index 36d7329..f6130f2 100644 --- "a/chinese/04-ANP-\345\237\272\344\272\216DID-WBA\347\232\204\345\221\275\345\220\215\347\251\272\351\227\264\350\247\204\350\214\203.md" +++ "b/chinese/04-ANP-\345\237\272\344\272\216DID-WBA\347\232\204\345\221\275\345\220\215\347\251\272\351\227\264\350\247\204\350\214\203.md" @@ -1,8 +1,13 @@ -# ANP-基于DID:WBA的命名空间规范 (Draft) +# ANP-基于DID:WBA的命名空间规范 -简称：WNS (WBA Name Space) +- 文档编号：ANP-04 +- 标题：ANP-基于DID:WBA的命名空间规范 +- 状态：已发布 +- 版本：1.1 +- 语言：中文 +- 适用范围：本规范适用于 ANP 中面向人类可读的 Handle 命名、WNS 解析与 did:wba 名称映射。 -备注：当前此规范仍是草案版本，会有进一步的优化与迭代。 +简称：WNS (WBA Name Space) ## 摘要 diff --git "a/chinese/06-ANP-\346\231\272\350\203\275\344\275\223\351\200\232\344\277\241\345\205\203\345\215\217\350\256\256\350\247\204\350\214\203.md" "b/chinese/06-ANP-\346\231\272\350\203\275\344\275\223\351\200\232\344\277\241\345\205\203\345\215\217\350\256\256\350\247\204\350\214\203.md" index 22a01f9..3d47b52 100644 --- "a/chinese/06-ANP-\346\231\272\350\203\275\344\275\223\351\200\232\344\277\241\345\205\203\345\215\217\350\256\256\350\247\204\350\214\203.md" +++ "b/chinese/06-ANP-\346\231\272\350\203\275\344\275\223\351\200\232\344\277\241\345\205\203\345\215\217\350\256\256\350\247\204\350\214\203.md" @@ -1,8 +1,15 @@ # ANP-智能体通信元协议规范（Draft） +- 文档编号：ANP-06 +- 标题：ANP-智能体通信元协议规范 +- 状态：Draft +- 版本：1.1-draft +- 语言：中文 +- 适用范围：本规范适用于 ANP 智能体之间的协议协商、协议选择与通信建立过程。 + 备注： -- 本章节内容为草稿阶段，后续可能会根据实际情况进行大幅调整。 -- 当前的协议实现就端到端消息加密，后面后修改为基于did:wba和http的方案。 +- 本规范当前仍处于草案状态，尚未发布，后续可能会根据实现反馈和实际场景进行较大调整。 +- 当前的协议实现聚焦于端到端消息加密，后续将调整为基于 did:wba 和 HTTP 的方案。 ## 背景 diff --git "a/chinese/07-ANP-\346\231\272\350\203\275\344\275\223\346\217\217\350\277\260\345\215\217\350\256\256\350\247\204\350\214\203.md" "b/chinese/07-ANP-\346\231\272\350\203\275\344\275\223\346\217\217\350\277\260\345\215\217\350\256\256\350\247\204\350\214\203.md" index 2303d1a..8f19791 100644 --- "a/chinese/07-ANP-\346\231\272\350\203\275\344\275\223\346\217\217\350\277\260\345\215\217\350\256\256\350\247\204\350\214\203.md" +++ "b/chinese/07-ANP-\346\231\272\350\203\275\344\275\223\346\217\217\350\277\260\345\215\217\350\256\256\350\247\204\350\214\203.md" @@ -1,5 +1,12 @@ # ANP-智能体描述协议规范 +- 文档编号：ANP-07 +- 标题：ANP-智能体描述协议规范 +- 状态：已发布 +- 版本：1.1 +- 语言：中文 +- 适用范围：本规范适用于 ANP 中智能体描述文档、接口描述与能力发布。 + ## 摘要 本规范定义了智能体描述协议（Agent Description Protocol, ADP），这是一个用于描述智能体的标准化协议。它定义了一个智能体如何对外发布其公开信息、支持的Interface等。其他智能体获得这个智能体的描述后，就可以与这个智能体进行信息的交换以及协作。 diff --git "a/chinese/08-ANP-\346\231\272\350\203\275\344\275\223\345\217\221\347\216\260\345\215\217\350\256\256\350\247\204\350\214\203.md" "b/chinese/08-ANP-\346\231\272\350\203\275\344\275\223\345\217\221\347\216\260\345\215\217\350\256\256\350\247\204\350\214\203.md" index 903f1d5..79f0edc 100644 --- "a/chinese/08-ANP-\346\231\272\350\203\275\344\275\223\345\217\221\347\216\260\345\215\217\350\256\256\350\247\204\350\214\203.md" +++ "b/chinese/08-ANP-\346\231\272\350\203\275\344\275\223\345\217\221\347\216\260\345\215\217\350\256\256\350\247\204\350\214\203.md" @@ -1,4 +1,11 @@ -# ANP-智能体发现协议规范（Draft） +# ANP-智能体发现协议规范 + +- 文档编号：ANP-08 +- 标题：ANP-智能体发现协议规范 +- 状态：已发布 +- 版本：1.1 +- 语言：中文 +- 适用范围：本规范适用于 ANP 中智能体与智能体描述文档的主动发现和被动发现。 ## 摘要 diff --git "a/chinese/09-ANP-\347\253\257\345\210\260\347\253\257\345\215\263\346\227\266\346\266\210\346\201\257\345\215\217\350\256\256\350\247\204\350\214\203.md" "b/chinese/09-ANP-\347\253\257\345\210\260\347\253\257\345\215\263\346\227\266\346\266\210\346\201\257\345\215\217\350\256\256\350\247\204\350\214\203.md" index c78a01f..f5363a5 100644 --- "a/chinese/09-ANP-\347\253\257\345\210\260\347\253\257\345\215\263\346\227\266\346\266\210\346\201\257\345\215\217\350\256\256\350\247\204\350\214\203.md" +++ "b/chinese/09-ANP-\347\253\257\345\210\260\347\253\257\345\215\263\346\227\266\346\266\210\346\201\257\345\215\217\350\256\256\350\247\204\350\214\203.md" @@ -1,4 +1,11 @@ -# ANP-端到端即时消息协议规范总纲（Draft 1.0） +# ANP-端到端即时消息协议规范总纲 + +- 文档编号：ANP-09 +- 标题：ANP-端到端即时消息协议规范总纲 +- 状态：已发布 +- 版本：1.1 +- 语言：中文 +- 适用范围：本文档适用于 ANP 端到端即时消息规范集的总体说明、分层说明与 Profile 索引。 > 本文是 ANP端到端即时消息规范集的总纲性说明，用于帮助读者快速理解整套协议的目标、分层、核心理念与关键技术路线。本文**不是**逐条规范性条文，规范性要求以各 Profile 原文为准。 @@ -46,13 +53,14 @@ ANP 通过 DID 文档发现可交互的服务端点，并以此建立后续的 ### 2.3 分层设计，而不是“大一统协议” -ANP 不把所有问题塞进一份文档，而是拆成 8 个 Profile： +ANP 不把所有问题塞进一份文档，而是拆成 9 个 Profile： - P1 / P2：共同绑定与身份发现 - P3 / P4：私聊和群聊的基础业务语义 - P5 / P6：私聊与群聊的 E2EE Overlay - P7：附件与大对象 - P8：联邦、跨域服务调用与群事件分发 +- P9：群消息 mention 与 selector 语义 这种设计的好处是： @@ -236,7 +244,7 @@ ANP 不把“绝对隐藏下载链接”作为核心安全手段，而是采用 ## 6. 文档结构 -以下 8 份 Profile 构成 ANP 当前规范集： +以下 9 份 Profile 构成 ANP 当前规范集： | 编号 | 文档 | 作用 | 内容概览 | @@ -249,6 +257,7 @@ ANP 不把“绝对隐藏下载链接”作为核心安全手段，而是采用 | 6 | [06-群组端到端加密](message/06-群组端到端加密.md) | 定义群组 E2EE Overlay | 规定基于 MLS 的群密码学状态、KeyPackage 发布与发现、群基础方法到密码学状态机的映射，以及 `epoch` 与分叉处理。 | | 7 | [07-附件与对象传输](message/07-附件与对象传输.md) | 定义附件与大对象语义 | 规定 `attachment_manifest`、Object Service、上传/提交/下载票据、对象级加密以及附件在私聊和群聊中的承载方式。 | | 8 | [08-联邦与跨域](message/08-联邦与跨域.md) | 定义跨域服务调用原则 | 规定服务角色、发现与路由、服务到服务安全、跨域直接调用原则、群事件分发以及跨域成功语义。 | +| 9 | [09-消息Mention扩展](message/09-消息Mention扩展.md) | 定义群消息 mention 载荷语义 | 规定结构化 mention 对象、`@all`、`@agents`、`@humans` 等 group selector、Group Base 与 Group E2EE 的放置规则以及终端侧校验。 | 建议阅读顺序为： @@ -256,7 +265,7 @@ ANP 不把“绝对隐藏下载链接”作为核心安全手段，而是采用 - 先读 P1 / P2 - 再读 P3 / P4 - 然后读 P5 / P6 -- 最后读 P7 / P8 +- 最后按需读 P7 / P8 / P9 --- diff --git "a/chinese/application/10-ANP-\346\231\272\350\203\275\344\275\223\346\224\257\344\273\230\345\215\217\350\256\256\350\247\204\350\214\203.md" "b/chinese/application/10-ANP-\346\231\272\350\203\275\344\275\223\346\224\257\344\273\230\345\215\217\350\256\256\350\247\204\350\214\203.md" index 9dc0cf3..7de6ee6 100644 --- "a/chinese/application/10-ANP-\346\231\272\350\203\275\344\275\223\346\224\257\344\273\230\345\215\217\350\256\256\350\247\204\350\214\203.md" +++ "b/chinese/application/10-ANP-\346\231\272\350\203\275\344\275\223\346\224\257\344\273\230\345\215\217\350\256\256\350\247\204\350\214\203.md" @@ -1,6 +1,11 @@ -# ANP-智能体支付协议规范 (draft) - -备注：当前此规范仍是草案版本，会有进一步的优化与迭代。 +# ANP-智能体支付协议规范（草案） + +- 文档编号：ANP-10 +- 标题：ANP-智能体支付协议规范 +- 状态：草案 +- 版本：0.1 +- 语言：中文 +- 适用范围：本规范适用于 ANP 应用层中智能体之间的支付与交易交互。 ## 摘要 diff --git "a/chinese/message/01-\346\240\270\345\277\203\347\273\221\345\256\232.md" "b/chinese/message/01-\346\240\270\345\277\203\347\273\221\345\256\232.md" index 7a4771c..0e592ed 100644 --- "a/chinese/message/01-\346\240\270\345\277\203\347\273\221\345\256\232.md" +++ "b/chinese/message/01-\346\240\270\345\277\203\347\273\221\345\256\232.md" @@ -1,9 +1,9 @@ -# ANP Profile 1：核心绑定（最终修订稿） +# ANP Profile 1：核心绑定 - 文档编号：ANP-P1 - 标题：核心绑定 -- 状态：Draft -- 版本：0.2.0（最终修订稿） +- 状态：已发布 +- 版本：1.1 - 语言：中文 - 适用范围：本 Profile 适用于所有 ANP 基础 Profile 与安全 Overlay Profile。 diff --git "a/chinese/message/02-\350\272\253\344\273\275\344\270\216\345\217\221\347\216\260.md" "b/chinese/message/02-\350\272\253\344\273\275\344\270\216\345\217\221\347\216\260.md" index 7e07b2e..6d60e89 100644 --- "a/chinese/message/02-\350\272\253\344\273\275\344\270\216\345\217\221\347\216\260.md" +++ "b/chinese/message/02-\350\272\253\344\273\275\344\270\216\345\217\221\347\216\260.md" @@ -1,9 +1,9 @@ -# ANP Profile 2：身份与发现（最终修订稿） +# ANP Profile 2：身份与发现 - 文档编号：ANP-P2 - 标题：身份与发现 -- 状态：Draft -- 版本：0.2.0（最终修订稿） +- 状态：已发布 +- 版本：1.1 - 语言：中文 - 适用范围：本 Profile 适用于 ANP 中 Agent 身份、Group 身份、服务发现与服务端点解释。 diff --git "a/chinese/message/03-\347\247\201\350\201\212\345\237\272\347\241\200\350\257\255\344\271\211.md" "b/chinese/message/03-\347\247\201\350\201\212\345\237\272\347\241\200\350\257\255\344\271\211.md" index 70e675d..f01a723 100644 --- "a/chinese/message/03-\347\247\201\350\201\212\345\237\272\347\241\200\350\257\255\344\271\211.md" +++ "b/chinese/message/03-\347\247\201\350\201\212\345\237\272\347\241\200\350\257\255\344\271\211.md" @@ -1,9 +1,9 @@ -# ANP Profile 3：私聊基础语义（最终修订稿） +# ANP Profile 3：私聊基础语义 - 文档编号：ANP-P3 - 标题：私聊基础语义 -- 状态：Draft -- 版本：0.2.1（最终修订稿） +- 状态：已发布 +- 版本：1.1 - 语言：中文 - 适用范围：本 Profile 适用于 Agent 与 Agent 之间的基础私聊语义，不包含端到端加密算法本身。 diff --git "a/chinese/message/04-\347\276\244\347\273\204\345\237\272\347\241\200\350\257\255\344\271\211.md" "b/chinese/message/04-\347\276\244\347\273\204\345\237\272\347\241\200\350\257\255\344\271\211.md" index f5ecafa..f7fbfaf 100644 --- "a/chinese/message/04-\347\276\244\347\273\204\345\237\272\347\241\200\350\257\255\344\271\211.md" +++ "b/chinese/message/04-\347\276\244\347\273\204\345\237\272\347\241\200\350\257\255\344\271\211.md" @@ -1,15 +1,15 @@ -# ANP Profile 4：群组基础语义（最终修订稿） +# ANP Profile 4：群组基础语义 - 文档编号：ANP-P4 - 标题：群组基础语义 -- 状态：Draft -- 版本：0.4.0（最终修订稿） +- 状态：已发布 +- 版本：1.1 - 语言：中文 - 适用范围：本 Profile 适用于基于 Group DID 的群生命周期、群管理与群消息基础语义，不包含群端到端加密算法本身。 --- -> 说明：本修订稿将 v1 核心收敛为“自助加入、直接加人”两条路径： +> 说明：本版本将 v1 核心收敛为“自助加入、直接加人”两条路径： > > 1. `group.invite`、`group.accept_invite` 与标准 `invitation` 对象已移出 v1 核心； > 2. `membership_request`、`membership_request_digest`、`group.approve_membership`、`group.reject_membership` 已移出 v1 核心； diff --git "a/chinese/message/05-\347\247\201\350\201\212\347\253\257\345\210\260\347\253\257\345\212\240\345\257\206.md" "b/chinese/message/05-\347\247\201\350\201\212\347\253\257\345\210\260\347\253\257\345\212\240\345\257\206.md" index 58b9763..30a1ba9 100644 --- "a/chinese/message/05-\347\247\201\350\201\212\347\253\257\345\210\260\347\253\257\345\212\240\345\257\206.md" +++ "b/chinese/message/05-\347\247\201\350\201\212\347\253\257\345\210\260\347\253\257\345\212\240\345\257\206.md" @@ -1,9 +1,9 @@ -# ANP Profile 5：私聊端到端加密（精修稿） +# ANP Profile 5：私聊端到端加密 - 文档编号：ANP-P5 - 标题：私聊端到端加密 -- 状态：Draft -- 版本：0.3.2（精修稿） +- 状态：已发布 +- 版本：1.1 - 语言：中文 - 适用范围：本 Profile 适用于基于 `agent_did` 的私聊端到端加密 Overlay。 - 依赖关系： diff --git "a/chinese/message/06-\347\276\244\347\273\204\347\253\257\345\210\260\347\253\257\345\212\240\345\257\206.md" "b/chinese/message/06-\347\276\244\347\273\204\347\253\257\345\210\260\347\253\257\345\212\240\345\257\206.md" index bbc6c09..9d90424 100644 --- "a/chinese/message/06-\347\276\244\347\273\204\347\253\257\345\210\260\347\253\257\345\212\240\345\257\206.md" +++ "b/chinese/message/06-\347\276\244\347\273\204\347\253\257\345\210\260\347\253\257\345\212\240\345\257\206.md" @@ -1,9 +1,9 @@ -# ANP Profile 6：群组端到端加密（MLS Usage Profile 修订稿） +# ANP Profile 6：群组端到端加密 - 文档编号：ANP-P6 - 标题：群组端到端加密 -- 状态：Draft -- 版本：0.3.2（MLS Usage Profile 修订稿） +- 状态：已发布 +- 版本：1.1 - 语言：中文 - 适用范围：本 Profile 适用于基于 Group DID 的群组端到端加密控制层，紧密配合 `anp.group.base.v1` 使用。 diff --git "a/chinese/message/07-\351\231\204\344\273\266\344\270\216\345\257\271\350\261\241\344\274\240\350\276\223.md" "b/chinese/message/07-\351\231\204\344\273\266\344\270\216\345\257\271\350\261\241\344\274\240\350\276\223.md" index 079fb9b..4a565e4 100644 --- "a/chinese/message/07-\351\231\204\344\273\266\344\270\216\345\257\271\350\261\241\344\274\240\350\276\223.md" +++ "b/chinese/message/07-\351\231\204\344\273\266\344\270\216\345\257\271\350\261\241\344\274\240\350\276\223.md" @@ -1,9 +1,9 @@ -# ANP Profile 7：Attachments and Object Transfer +# ANP Profile 7：附件与对象传输 - 文档编号：ANP-P7 - 标题：附件与对象传输 -- 状态：Draft -- 版本：0.5.0 +- 状态：已发布 +- 版本：1.1 - 语言：中文 - 适用范围：本 Profile 适用于 ANP 中附件、大对象与媒体对象的互通语义，支持私聊、群聊、非加密消息承载以及端到端加密消息承载。 diff --git "a/chinese/message/08-\350\201\224\351\202\246\344\270\216\350\267\250\345\237\237.md" "b/chinese/message/08-\350\201\224\351\202\246\344\270\216\350\267\250\345\237\237.md" index 32523ab..60386a0 100644 --- "a/chinese/message/08-\350\201\224\351\202\246\344\270\216\350\267\250\345\237\237.md" +++ "b/chinese/message/08-\350\201\224\351\202\246\344\270\216\350\267\250\345\237\237.md" @@ -1,9 +1,9 @@ -# ANP Profile 8：联邦与跨域（最终合并稿） +# ANP Profile 8：联邦与跨域 - 文档编号：ANP-P8 - 标题：联邦与跨域 -- 状态：Draft -- 版本：0.4.0（最终合并稿） +- 状态：已发布 +- 版本：1.1 - 语言：中文 - 适用范围：本 Profile 适用于 ANP 的跨域服务发现、服务到服务调用、群事件分发以及对象控制面的跨域调用。 diff --git "a/chinese/message/09-\346\266\210\346\201\257Mention\346\211\251\345\261\225.md" "b/chinese/message/09-\346\266\210\346\201\257Mention\346\211\251\345\261\225.md" new file mode 100644 index 0000000..70628af --- /dev/null +++ "b/chinese/message/09-\346\266\210\346\201\257Mention\346\211\251\345\261\225.md" @@ -0,0 +1,824 @@ +# ANP Profile 9：消息 Mention 扩展 + +- Document ID: ANP-P9 +- Title: Message Mentions Extension +- Status: draft +- Version: 1.1 +- Language: Chinese +- Applicability: 本 Profile 定义 ANP 群消息中的 mention 应用载荷扩展，用于同时表达人类可读和机器可读的 mention。它适用于 `anp.group.base.v1` 和 `anp.group.e2ee.v1` 中承载结构化 JSON 应用载荷的场景。 +- Dependencies: + - `anp.core.binding.v1` + - 使用非 E2EE 群消息时依赖 `anp.group.base.v1` + - 使用群 E2EE 消息时依赖 `anp.group.e2ee.v1` + +--- + +## 1. 目的 + +本 Profile 定义 ANP 群消息中 mention 的最小互操作表示。 + +Mention 是一个结构化应用层对象，用于把人类可见的界面表达： + +```text +@alice +@product-agent +@all +@agents +@humans +``` + +绑定到机器可读的目标，例如 DID 或群选择器。 + +本 Profile 标准化： + +1. 带 mention 的群消息应用载荷 JSON 结构； +2. mention 对象的最小字段； +3. 第一版支持的目标类型：`human`、`agent` 和 `group_selector`； +4. 第一版支持的群选择器：`all`、`agents` 和 `humans`； +5. `mentions` 的放置位置，确保它被外层 ANP 消息完整性机制覆盖； +6. 带 mention 群消息的发送者证明和校验模型。 + +本 Profile 不定义： + +- 新的 JSON-RPC 方法； +- 用于 `group.send` 或 `group.e2ee.send` 的新外层 `meta.profile`； +- 仅用于区分 mention 消息的新 content type； +- 仅用于区分 mention 消息的新 payload `protocol` 标记； +- mention 专属 sender 字段； +- mention 专属 proof 或 signature； +- 服务端 mention 权限模型； +- 服务端展开 `@all`、`@agents` 或 `@humans`； +- 已读状态、送达回执、通知投递或用户免打扰设置； +- 类似“支持某协议的 agents”这样的能力选择器； +- 超出 `owner`、`admin`、`member` 的自定义群治理角色； +- 私聊消息中的 mention 语义。 + +--- + +## 2. 术语和规范性约定 + +### 2.1 规范性关键词 + +本文中的 **MUST**、**MUST NOT**、**REQUIRED**、**SHALL**、**SHALL NOT**、**SHOULD**、**SHOULD NOT**、**RECOMMENDED**、**NOT RECOMMENDED**、**MAY**、**OPTIONAL** 按其大写形式解释为规范性要求。 + +### 2.2 术语 + +- **Mention**：用于标识消息中被提及目标的结构化应用层对象。 +- **Mention-bearing Group Message**：结构化 JSON 载荷中包含符合本 Profile 的顶层 `mentions` 数组的群应用消息。 +- **Surface Syntax**：人类可见的 mention 文本形式，例如 `@alice` 或 `@agents`。surface syntax 不是协议身份。 +- **Mention Target**：mention 的机器可读目标。它可以是 human DID、agent DID 或群选择器。 +- **Group Selector Mention**：目标为群范围选择器的 mention，例如 `all`、`agents` 或 `humans`。 +- **Terminal-side Validation**：接收客户端、用户代理或 Agent runtime 在收到或解密应用载荷之后执行的本地校验和处理。该术语不引入设备级或终端级协议身份。 +- **Group Host Service**：`anp.group.base.v1` 中定义的群服务。在本 Profile 中，它不校验 mention 语义。 + +--- + +## 3. 设计原则 + +### 3.1 `@` 是界面语法，不是身份 + +字符 `@` 及其后的文本只是人类界面语法。 + +单目标 mention 的协议身份是目标 DID： + +```json +{ + "target": { + "kind": "agent", + "did": "did:wba:example.com:agent:product-assistant" + } +} +``` + +群选择器 mention 的协议身份是作用于外层群消息上下文的 selector 值： + +```json +{ + "target": { + "kind": "group_selector", + "selector": "agents" + } +} +``` + +### 3.2 Mentions 不携带独立 sender + +mention 对象 **MUST NOT** 包含 `sender`、`sender_did`、`from` 或 `actor_did` 等发送者字段。 + +带 mention 群消息的发送者始终是外层 ANP 群消息的发送者： + +- Group Base 使用 `params.meta.sender_did`； +- Group E2EE 使用 `params.meta.sender_did` 以及 Group E2EE 消息认证上下文。 + +### 3.3 Mentions 不携带独立 proof + +mention 对象 **MUST NOT** 包含 `proof`、`signature`、`auth`、`origin_proof` 或任何等价的 mention 本地证明字段。 + +对于非 E2EE Group Base，带 mention 的载荷 **MUST** 位于 `params.body` 内，从而被 `auth.origin_proof` 绑定的 `Signed Request Object` 覆盖。 + +对于 Group E2EE，带 mention 的载荷 **MUST** 位于加密前对应的 inner plaintext 对象内。 + +### 3.4 v1 不定义服务端 mention 授权 + +本 Profile v1 不定义 mention 专属权限策略。 + +如果发送者根据适用的基础 Profile 有权发送外层群消息，则在 mention 层默认允许发送者包含任意受支持的 mention 目标： + +- 单个 human DID； +- 单个 agent DID； +- `@all`； +- `@agents`； +- `@humans`。 + +服务器、relay service、ingress service 和 Group Host Service **MUST NOT** 仅因为 mention target、mention selector 或 mention role 而拒绝消息。它们只继续执行外层 Profile 已经要求的校验，例如发送者认证、幂等性、target binding、content shape 和群发送权限。 + +该规则不限制普通运维管控，例如 payload 大小限制、明确记录的 mention 对象数量上限、速率限制、反滥用策略、反垃圾策略、畸形载荷拒绝或拒绝服务防护。此类管控属于运维策略，不属于 mention 专属授权。 + +### 3.5 群选择器不是群治理角色 + +selector 值 `all`、`agents` 和 `humans` **MUST NOT** 被解释为 P4 群治理角色。 + +P4 群治理角色仍然是： + +```text +owner +admin +member +``` + +本 Profile 的 group selector 是 mention target，不是授权角色。 + +--- + +## 4. Profile 绑定模型 + +### 4.1 扩展标记 + +本 Profile 不要求专用的 payload protocol name。 + +当结构化 JSON payload 位于本 Profile 支持的群消息载荷位置，并且包含符合本 Profile 的顶层 `mentions` 数组时，该 payload 即为带 mention 的 payload。 + +接收方 **MUST NOT** 要求或依赖顶层 `protocol` 字段来识别 mention。 + +如果结构化 JSON payload 不包含顶层 `mentions` 数组，则本 Profile 不适用于该 payload。 + +### 4.2 与外层 `meta.profile` 的关系 + +本 Profile **MUST NOT** 替代外层群消息操作中的 `params.meta.profile`。 + +外层群消息操作保持原有 Profile 名称，例如： + +- 非 Group E2EE 的 `group.send` 使用 `anp.group.base.v1`； +- `group.e2ee.send` 使用 `anp.group.e2ee.v1`。 + +### 4.3 Content type + +带 mention 的结构化载荷 **MUST** 使用普通 JSON 载荷承载。 + +对于非 E2EE Group Base： + +```json +"meta": { + "content_type": "application/json" +} +``` + +对于 Group E2EE inner plaintext： + +```json +{ + "application_content_type": "application/json" +} +``` + +实现 **MUST NOT** 仅为区分带 mention 的消息而定义新的 content type。 + +--- + +## 5. 带 Mention 的消息对象 + +### 5.1 推荐结构 + +带 mention 的消息载荷具有如下最小结构： + +```json +{ + "text": "@agents please summarize this discussion.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 7, + "unit": "unicode_code_point" + }, + "target": { + "kind": "group_selector", + "selector": "agents" + }, + "mention_role": "addressee" + } + ] +} +``` + +### 5.2 顶层字段 + +| 字段 | 要求 | 类型 | 语义 | +|---|---:|---|---| +| `text` | **MUST** | string | 包含 mention surface syntax 的人类可读消息文本。 | +| `mentions` | **MUST** | array | 本消息中的结构化 mention 对象。 | +| `annotations` | **MAY** | object | 应用扩展元数据。不用于路由、安全或授权。 | + +如果消息没有结构化 mention 语义，发送者 **SHOULD NOT** 包含顶层 `mentions` 字段，而应使用外层 Profile 的普通内容模型。 + +mention 处理器 **MAY** 忽略无法识别的顶层字段。 + +### 5.3 `mentions` 数组 + +`mentions` **MUST** 是数组。 + +每个元素 **MUST** 是第 5.4 节定义的 mention 对象。 + +同一个消息载荷内，`mentions[*].id` 的值 **MUST** 唯一。 + +`mentions` 的顺序 **SHOULD** 与 mention surface 在 `text` 中出现的顺序一致。 + +--- + +### 5.4 Mention 对象 + +最小 mention 对象如下： + +```json +{ + "id": "men_1", + "range": { + "start": 0, + "end": 7, + "unit": "unicode_code_point" + }, + "target": { + "kind": "group_selector", + "selector": "agents" + }, + "mention_role": "addressee" +} +``` + +字段要求： + +| 字段 | 要求 | 类型 | 语义 | +|---|---:|---|---| +| `id` | **MUST** | string | 消息内局部 mention 标识符，没有全局语义。 | +| `range` | **MUST** | object | mention surface 在 `text` 中的范围。 | +| `target` | **MUST** | object | 机器可读 mention 目标。 | +| `mention_role` | **MAY** | string | mention 角色。如果省略，接收方 **MUST** 按 `addressee` 解释。 | + +mention 对象 **MUST NOT** 包含： + +- `sender`； +- `sender_did`； +- `from`； +- `actor_did`； +- `auth`； +- `origin_proof`； +- `proof`； +- `signature`。 + +--- + +### 5.5 Mention range + +range 对象如下： + +```json +{ + "start": 0, + "end": 7, + "unit": "unicode_code_point" +} +``` + +字段要求： + +| 字段 | 要求 | 类型 | 语义 | +|---|---:|---|---| +| `start` | **MUST** | non-negative integer | `text` 中的闭区间起始偏移。 | +| `end` | **MUST** | non-negative integer | `text` 中的开区间结束偏移。 | +| `unit` | **MUST** | string | v1 中 **MUST** 为 `unicode_code_point`。 | + +规则： + +1. `start` **MUST** 小于 `end`。 +2. `end` **MUST NOT** 超过 `text` 中 Unicode code point 的数量。 +3. range 基于 JSON 解析后的 `text` 字符串精确值计算，在任何 UI 归一化、转写或 Markdown 渲染之前计算。 +4. `range` 标识的子串就是 mention surface。v1 中故意不在 mention 对象里重复 surface 字符串。 +5. 如果终端无法校验 range，终端 **MUST** 在 mention 触发层面忽略该 mention 对象，但 **MAY** 继续展示原始 `text`。 + +--- + +### 5.6 Mention target + +#### 5.6.1 单个 human target + +```json +{ + "kind": "human", + "did": "did:wba:example.com:user:alice", + "display_name": "Alice" +} +``` + +规则： + +- `kind` **MUST** 为 `human`。 +- `did` **MUST** 存在且 **MUST** 是 DID。 +- `display_name` **MAY** 作为发送端展示名快照存在。 +- `display_name` **MUST NOT** 被用作身份或授权证据。 + +#### 5.6.2 单个 agent target + +```json +{ + "kind": "agent", + "did": "did:wba:example.com:agent:product-assistant", + "display_name": "Product Assistant" +} +``` + +规则： + +- `kind` **MUST** 为 `agent`。 +- `did` **MUST** 存在且 **MUST** 是 DID。 +- `display_name` **MAY** 作为发送端展示名快照存在。 +- Agent 能力发现、Agent Description 解析和 profile 查询不属于本 Profile 范围。 + +#### 5.6.3 Group selector target + +```json +{ + "kind": "group_selector", + "selector": "agents" +} +``` + +规则： + +- `kind` **MUST** 为 `group_selector`。 +- `selector` **MUST** 是以下值之一： + - `all` + - `agents` + - `humans` +- 当 `kind = "group_selector"` 时，`did` **MUST NOT** 出现。 +- selector 的作用域是外层群消息上下文标识的群。 +- selector **MUST NOT** 被解释为 P4 群治理角色。 + +--- + +### 5.7 Mention role + +`mention_role` 字段是可选字段。 + +v1 允许的取值： + +| 值 | 语义 | +|---|---| +| `addressee` | 被 mention 的目标是注意力接收者。默认值。 | +| `cc` | 被 mention 的目标只是被抄送或引用，不一定需要行动。 | + +规则： + +- 如果省略 `mention_role`，接收方 **MUST** 按 `addressee` 解释。 +- 如果存在 `mention_role`，其值 **MUST** 是本节允许值之一。 +- `mention_role` **MUST NOT** 被用作群治理角色。 +- `mention_role` **MUST NOT** 用于覆盖群发送权限或任何外层 Profile 授权规则。 + +--- + +## 6. Group Selector 语义 + +### 6.1 `@all` + +`@all` 表示为： + +```json +{ + "target": { + "kind": "group_selector", + "selector": "all" + } +} +``` + +终端侧解释： + +```text +外层群上下文中的所有 active 群成员 +``` + +### 6.2 `@agents` + +`@agents` 表示为： + +```json +{ + "target": { + "kind": "group_selector", + "selector": "agents" + } +} +``` + +终端侧解释： + +```text +本地应用 roster 或 profile 层分类为 agent 的 active 群成员 +``` + +### 6.3 `@humans` + +`@humans` 表示为： + +```json +{ + "target": { + "kind": "group_selector", + "selector": "humans" + } +} +``` + +终端侧解释： + +```text +本地应用 roster 或 profile 层分类为 human 的 active 群成员 +``` + +### 6.4 Selector 解析快照 + +对于群消息，终端 **SHOULD** 在可用时基于该消息被接受时关联的 group state snapshot 解析 group selector。 + +在 Group Base 和 Group E2EE 中，这通常是已接受消息上下文中返回或投递的 `group_state_version`。 + +如果终端没有对应的精确 group state snapshot，终端 **MAY** 基于本地可用的最佳群状态解析 selector，并将结果标记为 best-effort。 + +### 6.5 Member kind 来源 + +成员被分类为 `human` 或 `agent` 属于应用层 roster 或 profile 属性。 + +本 Profile 不为此定义新的 P4 `group_member` 字段。 + +实现 **MUST NOT** 仅根据 `owner`、`admin` 或 `member` 等 P4 治理角色推断 `human` 或 `agent`。 + +--- + +## 7. 放置规则 + +### 7.1 非 E2EE Group Base + +对于 `anp.group.base.v1` 下的 `group.send`： + +- `params.meta.content_type` **MUST** 为 `application/json`； +- `params.body.payload` **MUST** 承载带 mention 的消息对象； +- `params.auth.origin_proof` 是 Group Base 要求的发送者证明； +- Group Host 执行现有 Group Base 校验； +- Group Host **MUST NOT** 执行 mention 专属授权或 selector 展开。 + +示例： + +```json +{ + "jsonrpc": "2.0", + "id": "req-group-mention-001", + "method": "group.send", + "params": { + "meta": { + "profile": "anp.group.base.v1", + "security_profile": "transport-protected", + "sender_did": "did:wba:example.com:user:alice", + "target": { + "kind": "group", + "did": "did:wba:groups.example.com:team:waic-demo" + }, + "operation_id": "msg-group-mention-001", + "message_id": "msg-group-mention-001", + "created_at": "2026-06-14T12:00:00Z", + "content_type": "application/json" + }, + "auth": { + "scheme": "anp-rfc9421-origin-proof-v1", + "origin_proof": { + "contentDigest": "sha-256=:BASE64_SHA256_DIGEST:", + "signatureInput": "sig1=(\"@method\" \"@target-uri\" \"content-digest\");created=1781438400;expires=1781438460;nonce=\"n-002\";keyid=\"did:wba:example.com:user:alice#key-1\"", + "signature": "sig1=:BASE64_SIGNATURE:" + } + }, + "body": { + "payload": { + "text": "@agents please summarize yesterday's meeting.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 7, + "unit": "unicode_code_point" + }, + "target": { + "kind": "group_selector", + "selector": "agents" + }, + "mention_role": "addressee" + } + ] + } + } + } +} +``` + +### 7.2 Group E2EE + +对于 `anp.group.e2ee.v1` 下的 `group.e2ee.send`： + +- 外层 `params.meta.content_type` 保持为 `application/anp-group-cipher+json`； +- 外层 `params.body` 承载 `group_cipher_object`； +- 带 mention 的对象 **MUST** 在 MLS `PrivateMessage` 加密前放入 inner `Group Application Plaintext.payload`； +- inner `application_content_type` **MUST** 为 `application/json`。 + +加密前 inner plaintext 示例： + +```json +{ + "application_content_type": "application/json", + "thread_id": "thr-001", + "payload": { + "text": "@all please review the agenda.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 4, + "unit": "unicode_code_point" + }, + "target": { + "kind": "group_selector", + "selector": "all" + } + } + ] + } +} +``` + +Group Host 看到的是外层 ciphertext object。它按照 Group E2EE 和 Group Base 规则认证并排序 `group.e2ee.send` 请求，但不检查或校验加密的 `mentions` 数组。 + +### 7.3 Incoming notification + +当 ANP service 使用 `group.incoming` 或对应 Group E2EE 投递路径推送带 mention 的群消息时： + +- 推送载荷 **MUST** 与已接受的原始消息语义等价； +- 如果外层 Profile 允许把原始 `auth.origin_proof` 复制到 notification 中，service **SHOULD** 包含无损复制，以便终端侧把 mention 载荷绑定到原始发送者； +- 中间服务在转发或推送消息时 **MUST NOT** 重写 `mentions`。 + +--- + +## 8. 发送者证明和密码学绑定 + +### 8.1 非 E2EE Group Base + +对于非 E2EE Group Base，带 mention 消息的发送者由外层 `auth.origin_proof` 证明。 + +校验主体是外层消息 sender： + +```text +params.meta.sender_did +``` + +`mentions` 数组受到保护，因为它位于 `Signed Request Object` 的 `body` 成员内。 + +### 8.2 Group E2EE + +对于 Group E2EE，`group.e2ee.send` 使用外层 Profile 的 origin proof 和 Group E2EE authenticated message 语义。 + +`mentions` 数组位于受 MLS 保护的 inner `Group Application Plaintext` 内。它对 Group Host 不可见，只在终端或 Agent runtime 解密之后校验。 + +### 8.3 无 mention 本地 proof + +v1 中 verifier **MUST NOT** 要求 mention 本地 signature 或 proof。 + +接收方 **MUST** 将嵌入 mention 对象内的任何 `proof`、`signature`、`origin_proof` 或 `auth` 字段视为不符合本 Profile。 + +--- + +## 9. 校验与处理 + +### 9.1 服务端处理 + +服务器、relay service、ingress service 和 Group Host Service： + +1. **MUST** 按外层 Profile 处理外层 ANP 群消息； +2. **MUST** 执行外层 Profile 要求的现有发送者认证、幂等性、target binding、security profile 和 payload carriage 校验； +3. 对群消息，**MUST** 按 Group Base / Group E2EE 要求执行群发送权限； +4. **MUST NOT** 执行 mention 专属授权； +5. **MUST NOT** 在消息接受阶段把 `@all`、`@agents` 或 `@humans` 展开为成员 DID 列表； +6. **MUST NOT** 仅因为服务端不知道某个 mention target DID 或 selector 覆盖面较大而拒绝消息； +7. **MUST** 保持带 mention 载荷不被未授权修改。 + +该规则不阻止服务器因普通外层 Profile 或运维原因拒绝消息，例如 JSON-RPC shape 无效、content type 不支持、origin proof 无效、群发送权限失败、ciphertext object 无效、幂等冲突、payload 大小限制、明确记录的 mention 对象数量上限、速率限制、反滥用策略、反垃圾策略或拒绝服务防护。 + +### 9.2 终端侧校验 + +支持本 Profile 的终端、客户端、用户代理或 Agent runtime **MUST** 在收到或解密应用载荷之后执行 mention 校验。 + +最小终端侧校验步骤如下： + +1. 在触发 mention 行为前，验证或依赖外层 Profile 的 authenticated sender context。 +2. 解析 JSON payload。 +3. 在应用本 Profile 前，检查 payload 包含顶层 `mentions` 数组。 +4. 检查 `text` 是 string。 +5. 检查 `mentions` 是 array。 +6. 检查每个 mention 对象具有唯一 `id`。 +7. 检查每个 `range` 对 `text` 有效。 +8. 检查 `target.kind` 是 `human`、`agent` 或 `group_selector` 之一。 +9. 如果 `target.kind = "human"` 或 `target.kind = "agent"`，检查 `target.did` 存在。 +10. 如果 `target.kind = "group_selector"`，检查 `target.selector` 是 `all`、`agents` 或 `humans` 之一。 +11. 如果存在 `mention_role`，检查其值是 `addressee` 或 `cc` 之一。 +12. 按本地策略执行渲染、通知或 Agent runtime 行为。 + +如果某个 mention 对象未通过终端侧校验，终端 **SHOULD** 在触发、通知或 Agent 激活层面忽略该 mention 对象，但 **MAY** 继续展示原始消息文本。 + +### 9.3 Mention 权限解释 + +v1 不存在 mention 专属权限策略。 + +如果满足以下条件，终端 **MUST** 在 wire-protocol 层把 mention 视为允许： + +1. 外层群消息已经按照适用的 ANP Message Profile 被接受或投递；并且 +2. mention 对象在本 Profile 下语法有效。 + +终端 **MAY** 应用本地用户偏好，例如免打扰、通知节流或反垃圾策略。这些本地偏好不是协议层 mention 授权，且 **MUST NOT** 表示为对 ANP 消息本身的拒绝。 + +--- + +## 10. 示例 + +### 10.1 在群中 mention 所有人类成员 + +```json +{ + "text": "@humans please confirm your attendance.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 7, + "unit": "unicode_code_point" + }, + "target": { + "kind": "group_selector", + "selector": "humans" + } + } + ] +} +``` + +### 10.2 在群中 Mention 单个 human + +```json +{ + "text": "@张三 please review this.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 3, + "unit": "unicode_code_point" + }, + "target": { + "kind": "human", + "did": "did:wba:example.com:user:zhangsan", + "display_name": "张三" + }, + "mention_role": "cc" + } + ] +} +``` + +### 10.3 在群中 Mention 单个 agent + +```json +{ + "text": "@InvoiceBot extract the invoice fields.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 11, + "unit": "unicode_code_point" + }, + "target": { + "kind": "agent", + "did": "did:wba:example.com:agent:invoice-bot", + "display_name": "InvoiceBot" + }, + "mention_role": "addressee" + } + ] +} +``` + +--- + +## 11. 安全考虑 + +### 11.1 Mention spoofing + +终端 **MUST NOT** 仅使用可见文本判断 mention 目标。 + +例如，文本 `@Alice` 不足以标识 Alice。终端必须使用对应的结构化 `mentions[*].target` 对象。 + +### 11.2 Display name 不是身份 + +`target.display_name` 只是展示名快照。 + +身份判断 **MUST** 基于单目标 mention 的 DID，或基于 group selector mention 的 selector 语义。 + +### 11.3 无服务端 mention 授权 + +由于 v1 的 mention 校验位于终端侧，服务器可能接受并投递一个后来无法通过终端侧 mention 校验的消息。 + +终端和 Agent runtime **MUST** 避免由无效 mention 对象触发特权行为。 + +### 11.4 E2EE 隐私 + +在 Group E2EE 模式中，mention 对象位于加密 plaintext 内。 + +服务器和 Group Host Service 不应期望检查或索引 mention target，除非未来扩展显式引入加密或隐私保护的通知 hint。 + +本 Profile v1 不定义此类 hint。 + +### 11.5 Replay 和重复处理 + +本 Profile 不定义 mention 专属 replay protection。 + +Replay 和重复处理继承自外层 ANP Message Profile，通过 `operation_id`、`message_id`、E2EE session state 或 group ordering semantics 完成。 + +--- + +## 12. 隐私考虑 + +### 12.1 最小元数据 + +Mention target 可能暴露社交注意力模式。 + +实现 **SHOULD** 将 `mentions` 保持在本 Profile 要求的受保护 payload 位置内，且 **SHOULD NOT** 把 mention target 复制到外层 metadata。 + +### 12.2 Group selector 隐私 + +`@agents` 或 `@humans` 等 group selector 可能暴露发送者的目标受众，但它避免在消息载荷中暴露展开后的成员 DID 列表。 + +实现 **SHOULD** 保留 selector，而不是在发送时将其展开为单个 DID。 + +--- + +## 13. 最小互操作要求 + +符合本 Profile 的实现至少 MUST 支持： + +1. 结构化 JSON 群消息 payload 中作为扩展标记的顶层 `mentions`； +2. `text` 加 `mentions` 的消息对象结构； +3. `human`、`agent` 和 `group_selector` 三类 mention target； +4. `all`、`agents` 和 `humans` 三个 group selector 值； +5. `unicode_code_point` mention range； +6. mention 对象 shape 和 range 的终端侧校验； +7. 不使用 mention 本地 sender 字段； +8. 不使用 mention 本地 proof 字段； +9. 非 E2EE `application/json` 群消息中，带 mention 的载荷位于 `params.body.payload`； +10. Group E2EE 消息中，带 mention 的载荷位于 inner `Group Application Plaintext.payload`； +11. 保留外层 ANP Message Profile 的发送者证明和发送权限语义； +12. v1 不做服务端 mention 授权或 selector 展开。 + +--- + +## 14. 未来扩展 + +未来版本可以定义： + +- 私聊消息中的 mention 语义； +- E2EE 消息的 mention notification hint； +- mention 专属通知投递策略； +- 能力选择器 mention，例如支持某个协议的 agents； +- 高风险操作的 mention-level human authorization； +- 富文本或多 body 的 mention anchoring； +- 跨群或外部 mention 引用； +- human / agent 分类的标准 roster 字段。 + +这些能力都刻意不放入 v1。 diff --git "a/chinese/\347\233\270\345\205\263\344\272\247\345\223\201\344\270\216\346\212\200\346\234\257/agent-discovery-en.svg" "b/chinese/\347\233\270\345\205\263\344\272\247\345\223\201\344\270\216\346\212\200\346\234\257/agent-discovery-en.svg" index 7b88139..ef6ced5 100644 --- "a/chinese/\347\233\270\345\205\263\344\272\247\345\223\201\344\270\216\346\212\200\346\234\257/agent-discovery-en.svg" +++ "b/chinese/\347\233\270\345\205\263\344\272\247\345\223\201\344\270\216\346\212\200\346\234\257/agent-discovery-en.svg" @@ -179,5 +179,5 @@ - Based on ANP-Agent Discovery Protocol Specification (Draft) + Based on ANP-Agent Discovery Protocol Specification (Version 1.1) diff --git "a/chinese/\347\233\270\345\205\263\344\272\247\345\223\201\344\270\216\346\212\200\346\234\257/agent-discovery.svg" "b/chinese/\347\233\270\345\205\263\344\272\247\345\223\201\344\270\216\346\212\200\346\234\257/agent-discovery.svg" index 3b7d9fa..a34ad9d 100644 --- "a/chinese/\347\233\270\345\205\263\344\272\247\345\223\201\344\270\216\346\212\200\346\234\257/agent-discovery.svg" +++ "b/chinese/\347\233\270\345\205\263\344\272\247\345\223\201\344\270\216\346\212\200\346\234\257/agent-discovery.svg" @@ -173,5 +173,5 @@ - 基于ANP-智能体发现协议规范（Draft） + 基于ANP-智能体发现协议规范（1.1版） diff --git a/docs/chinese/community-operations/operations-cn.md b/docs/chinese/community-operations/operations-cn.md index 21d3154..6e6a3f0 100644 --- a/docs/chinese/community-operations/operations-cn.md +++ b/docs/chinese/community-operations/operations-cn.md @@ -1,4 +1,4 @@ -# ANP开源技术社区运营策略(草案) +# ANP开源技术社区运营策略 **概述：** ANP是“智能体网络协议” (Agent Network Protocol)，本文设计一套详细的全球开源技术社区运营方案，以设计、完善和推广 ANP 协议为主要目标，并开发相关工具和参考实现。新社区将借鉴 FFmpeg、Linux 等成熟开源项目的实践经验，保持高度开放性和持续活力，免受任何个人或公司单独控制，避免内耗和分裂。下文将从社区治理、贡献者管理、平台使用、基金会运作、冲突防范等方面详细阐述。 diff --git a/docs/chinese/links.md b/docs/chinese/links.md index b1721cf..892c8e9 100644 --- a/docs/chinese/links.md +++ b/docs/chinese/links.md @@ -15,9 +15,10 @@ - [ANP Profile 6：群组端到端加密](/chinese/message/06-群组端到端加密.md) - [ANP Profile 7：附件与对象传输](/chinese/message/07-附件与对象传输.md) - [ANP Profile 8：联邦与跨域](/chinese/message/08-联邦与跨域.md) +- [ANP Profile 9：消息 Mention 扩展](/chinese/message/09-消息Mention扩展.md) - [元协议设计规范](/chinese/06-ANP-智能体通信元协议规范.md) -- [智能体描述协议规范（Draft）](/chinese/07-ANP-智能体描述协议规范.md) -- [智能体发现协议规范（Draft）](/chinese/08-ANP-智能体发现协议规范.md) +- [智能体描述协议规范](/chinese/07-ANP-智能体描述协议规范.md) +- [智能体发现协议规范](/chinese/08-ANP-智能体发现协议规范.md) ## 白皮书 (Whitepaper) diff --git a/docs/community-operations/community-operations.md b/docs/community-operations/community-operations.md index 44e85d3..79dcf18 100644 --- a/docs/community-operations/community-operations.md +++ b/docs/community-operations/community-operations.md @@ -1,4 +1,4 @@ -# ANP Open Source Community Operation Strategy (Draft) +# ANP Open Source Community Operation Strategy **Overview:** ANP stands for "Agent Network Protocol". This document outlines a detailed global open-source community operation plan aimed at designing, refining, and promoting the ANP protocol, as well as developing related tools and reference implementations. The new community will draw on the practical experiences of mature open-source projects such as FFmpeg and Linux, maintaining a high degree of openness and sustained vitality, free from control by any individual or company, and avoiding internal conflicts and divisions. The following sections will elaborate on community governance, contributor management, platform usage, foundation operations, and conflict prevention. diff --git a/docs/links.md b/docs/links.md index a5533c8..3683c00 100644 --- a/docs/links.md +++ b/docs/links.md @@ -15,9 +15,10 @@ For ease of reference, all ANP-related materials are organized by **Specificatio - [ANP Profile 6: Group End-to-End Encryption](/message/06-group-end-to-end-encryption.md) - [ANP Profile 7: Attachments and Object Transfer](/message/07-attachments-and-object-transfer.md) - [ANP Profile 8: Federation and Cross-Domain](/message/08-federation-and-cross-domain.md) +- [ANP Profile 9: Message Mentions Extension](/message/09-message-mentions.md) - [Meta-Protocol Design Specification](/06-anp-agent-communication-meta-protocol-specification.md) -- [Agent Description Protocol Specification (Draft)](/07-anp-agent-description-protocol-specification.md) -- [Agent Discovery Protocol Specification (Draft)](/08-anp-agent-discovery-protocol-specification.md) +- [Agent Description Protocol Specification](/07-anp-agent-description-protocol-specification.md) +- [Agent Discovery Protocol Specification](/08-anp-agent-discovery-protocol-specification.md) ## Whitepaper diff --git a/images/agent-discovery.svg b/images/agent-discovery.svg index 43fc6cf..d230a97 100644 --- a/images/agent-discovery.svg +++ b/images/agent-discovery.svg @@ -173,5 +173,5 @@ - 基于ANP-智能体发现协议规范（Draft） + 基于ANP-智能体发现协议规范（1.1版） diff --git a/images/anp-architecture2.png b/images/anp-architecture2.png new file mode 100644 index 0000000..2cbf938 Binary files /dev/null and b/images/anp-architecture2.png differ diff --git a/message/01-core-binding.md b/message/01-core-binding.md index ebaa81b..325cef0 100644 --- a/message/01-core-binding.md +++ b/message/01-core-binding.md @@ -1,9 +1,9 @@ -# ANP Profile 1: Core Binding (Final Revision) +# ANP Profile 1: Core Binding - Document ID: ANP-P1 - Title: Core Binding -- Status: Draft -- Version: 0.2.0 (Final Revision) +- Status: Released +- Version: 1.1 - Language: English - Applicability: This profile applies to all ANP basic profiles and security overlay profiles. diff --git a/message/02-identity-and-discovery.md b/message/02-identity-and-discovery.md index 6431584..e4f9eb3 100644 --- a/message/02-identity-and-discovery.md +++ b/message/02-identity-and-discovery.md @@ -1,9 +1,9 @@ -# ANP Profile 2: Identity and Discovery (Final Revision) +# ANP Profile 2: Identity and Discovery - Document ID: ANP-P2 - Title: Identity and Discovery -- Status: Draft -- Version: 0.2.0 (Final Revision) +- Status: Released +- Version: 1.1 - Language: English - Applicability: This Profile applies to Agent identity, Group identity, service discovery and service endpoint interpretation in ANP. diff --git a/message/03-direct-messaging-base-semantics.md b/message/03-direct-messaging-base-semantics.md index 83702f1..8aa32d6 100644 --- a/message/03-direct-messaging-base-semantics.md +++ b/message/03-direct-messaging-base-semantics.md @@ -1,9 +1,9 @@ -# ANP Profile 3: Direct Messaging Base Semantics (Final Revision) +# ANP Profile 3: Direct Messaging Base Semantics - Document ID: ANP-P3 - Title: Direct Messaging Base Semantics -- Status: Draft -- Version: 0.2.1 (Final Revision) +- Status: Released +- Version: 1.1 - Language: English - Applicability: This Profile applies to the basic direct messaging semantics between Agents and does not include the end-to-end encryption algorithm itself. diff --git a/message/04-group-messaging-base-semantics.md b/message/04-group-messaging-base-semantics.md index 1db00a0..95a4833 100644 --- a/message/04-group-messaging-base-semantics.md +++ b/message/04-group-messaging-base-semantics.md @@ -1,15 +1,15 @@ -# ANP Profile 4: Group Messaging Base Semantics (Final Revision) +# ANP Profile 4: Group Messaging Base Semantics - Document ID: ANP-P4 - Title: Group Messaging Base Semantics -- Status: Draft -- Version: 0.4.0 (Final Revision) +- Status: Released +- Version: 1.1 - Language: English - Applicability: This Profile applies to the group life cycle, group management and group message base semantics based on Group DID, and does not include the group end-to-end encryption algorithm itself. --- -> Note: This revised draft converges the v1 core into two paths: "self-service joining and direct addition": +> Note: This release converges the v1 core into two paths: "self-service joining and direct addition": > > 1. `group.invite`, `group.accept_invite` and standard `invitation` objects have been moved out of the v1 core; > 2. `membership_request`, `membership_request_digest`, `group.approve_membership`, and `group.reject_membership` have been moved out of the v1 core; diff --git a/message/05-direct-end-to-end-encryption.md b/message/05-direct-end-to-end-encryption.md index 60094cc..c6ff815 100644 --- a/message/05-direct-end-to-end-encryption.md +++ b/message/05-direct-end-to-end-encryption.md @@ -1,9 +1,9 @@ -# ANP Profile 5: Direct End-to-End Encryption (Refined Draft) +# ANP Profile 5: Direct End-to-End Encryption - Document ID: ANP-P5 - Title: Direct End-to-End Encryption -- Status: Draft -- Version: 0.3.2 (Refined Draft) +- Status: Released +- Version: 1.1 - Language: English - Applicability: This Profile applies to Direct End-to-End Encryption Overlay based on `agent_did`. - Dependencies: diff --git a/message/06-group-end-to-end-encryption.md b/message/06-group-end-to-end-encryption.md index 777fabe..fd37ab6 100644 --- a/message/06-group-end-to-end-encryption.md +++ b/message/06-group-end-to-end-encryption.md @@ -1,9 +1,9 @@ -# ANP Profile 6: Group End-to-End Encryption (MLS Usage Profile Revised Draft) +# ANP Profile 6: Group End-to-End Encryption - Document ID: ANP-P6 - Title: Group End-to-End Encryption -- Status: Draft -- Version: 0.3.2 (MLS Usage Profile Revised Draft) +- Status: Released +- Version: 1.1 - Language: English - Applicability: This Profile is suitable for the Group End-to-End Encryption control layer based on Group DID and works closely with `anp.group.base.v1`. diff --git a/message/07-attachments-and-object-transfer.md b/message/07-attachments-and-object-transfer.md index d897087..a494c96 100644 --- a/message/07-attachments-and-object-transfer.md +++ b/message/07-attachments-and-object-transfer.md @@ -2,8 +2,8 @@ - Document ID: ANP-P7 - Title: Attachments and Object Transfer -- Status: Draft -- Version: 0.5.0 +- Status: Released +- Version: 1.1 - Language: English - Applicability: This Profile is applicable to the interoperability semantics of attachments, large objects and media objects in ANP, and supports direct messaging, group messaging, unencrypted message bearers and end-to-end encryption message bearers. @@ -1567,7 +1567,7 @@ Content-Length: 1048592 } } ], - "caption": "Design draft", + "caption": "Design document", "primary_attachment_id": "att-group-e2ee-001" } } diff --git a/message/08-federation-and-cross-domain.md b/message/08-federation-and-cross-domain.md index c1e41be..7a1e377 100644 --- a/message/08-federation-and-cross-domain.md +++ b/message/08-federation-and-cross-domain.md @@ -1,9 +1,9 @@ -# ANP Profile 8: Federation and Cross-Domain (Final Consolidated Draft) +# ANP Profile 8: Federation and Cross-Domain - Document ID: ANP-P8 - Title: Federation and Cross-Domain -- Status: Draft -- Version: 0.4.0 (Final Consolidated Draft) +- Status: Released +- Version: 1.1 - Language: English - Applicability: This profile applies to ANP cross-domain service discovery, service-to-service invocation, group-event distribution, and cross-domain invocation of the object control plane. diff --git a/message/09-message-mentions.md b/message/09-message-mentions.md new file mode 100644 index 0000000..17cd9a7 --- /dev/null +++ b/message/09-message-mentions.md @@ -0,0 +1,824 @@ +# ANP Profile 9: Message Mentions Extension + +- Document ID: ANP-P9 +- Title: Message Mentions Extension +- Status: Released +- Version: 1.1 +- Language: English +- Applicability: This Profile defines an application-payload extension for expressing human-readable and machine-readable mentions in ANP group messages. It applies to `anp.group.base.v1` and `anp.group.e2ee.v1` when the carried application payload is structured JSON. +- Dependencies: + - `anp.core.binding.v1` + - `anp.group.base.v1` when used with group non-E2EE messages + - `anp.group.e2ee.v1` when used with group E2EE messages + +--- + +## 1. Purpose + +This Profile defines the minimum interoperable representation of mentions in ANP group messages. + +A mention is a structured application-layer object that binds a human-visible surface form such as: + +```text +@alice +@product-agent +@all +@agents +@humans +``` + +to a machine-readable target such as a DID or a group selector. + +This Profile standardizes: + +1. The JSON shape of a mention-bearing group message payload; +2. The minimum fields of a mention object; +3. The first-version supported target kinds: `human`, `agent`, and `group_selector`; +4. The first-version supported group selectors: `all`, `agents`, and `humans`; +5. The required placement of `mentions` so that it is covered by the enclosing ANP message integrity mechanism; +6. The sender-proof and validation model for mention-bearing group messages. + +This Profile does not define: + +- A new JSON-RPC method; +- A new outer `meta.profile` value for `group.send` or `group.e2ee.send`; +- A new content type solely for mentions; +- A new payload `protocol` marker solely for mentions; +- A new mention-specific sender field; +- A new mention-specific proof or signature; +- A server-side mention authorization model; +- Server-side expansion of `@all`, `@agents`, or `@humans`; +- Read status, delivery receipts, notification delivery, or user mute settings; +- Capability-based selectors such as "agents that support protocol X"; +- Custom group governance roles beyond `owner`, `admin`, and `member`; +- Direct-message mention semantics. + +--- + +## 2. Terminology and Normative Conventions + +### 2.1 Normative Keywords + +In this article, **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, **OPTIONAL** are interpreted as normative requirements according to their capitalized form. + +### 2.2 Terminology + +- **Mention**: A structured application-layer object that identifies a target mentioned in a message. +- **Mention-bearing Group Message**: A group application message whose structured JSON payload contains a top-level `mentions` array conforming to this Profile. +- **Surface Syntax**: The human-visible text form of a mention, such as `@alice` or `@agents`. The surface syntax is not the protocol identity. +- **Mention Target**: The machine-readable target of a mention. It may be a human DID, an agent DID, or a group selector. +- **Group Selector Mention**: A mention whose target is a group-scoped selector, such as `all`, `agents`, or `humans`. +- **Terminal-side Validation**: Local validation and processing performed by the receiving client, user agent, or Agent runtime after it receives or decrypts the application payload. This term does not introduce a device-level or terminal-level protocol identity. +- **Group Host Service**: The group service defined by `anp.group.base.v1`. In this Profile, it does not validate mention semantics. + +--- + +## 3. Design Principles + +### 3.1 `@` is surface syntax, not identity + +The character `@` and the text following it are human interface syntax only. + +The protocol identity of a single-target mention is the target DID: + +```json +{ + "target": { + "kind": "agent", + "did": "did:wba:example.com:agent:product-assistant" + } +} +``` + +The protocol identity of a group selector mention is the selector value scoped to the enclosing group message: + +```json +{ + "target": { + "kind": "group_selector", + "selector": "agents" + } +} +``` + +### 3.2 Mentions do not carry an independent sender + +A mention object **MUST NOT** contain a sender field such as `sender`, `sender_did`, `from`, or `actor_did`. + +The sender of a mention-bearing group message is always the sender of the enclosing ANP group message: + +- `params.meta.sender_did` for Group Base; +- `params.meta.sender_did` plus the Group E2EE message authentication context for Group E2EE. + +### 3.3 Mentions do not carry an independent proof + +A mention object **MUST NOT** contain `proof`, `signature`, `auth`, `origin_proof`, or any equivalent mention-local proof field. + +For non-E2EE Group Base, the mention-bearing payload **MUST** be located inside `params.body` so that it is covered by the `Signed Request Object` bound by `auth.origin_proof`. + +For Group E2EE, the mention-bearing payload **MUST** be located inside the corresponding inner plaintext object before encryption. + +### 3.4 Mention authorization is not a v1 server-side concern + +This Profile defines no mention-specific permission policy in v1. + +If the sender is allowed to send the enclosing group message under the applicable base Profile, the sender is allowed at the mention layer to include any supported mention target: + +- a single human DID; +- a single agent DID; +- `@all`; +- `@agents`; +- `@humans`. + +Servers, relay services, ingress services, and Group Host Services **MUST NOT** reject a message solely because of the mention target, mention selector, or mention role. They continue to enforce only the existing checks required by the enclosing Profile, such as sender authentication, idempotence, target binding, content-shape rules, and group send permission. + +This rule does not prevent ordinary operational enforcement such as payload-size limits, documented maximum mention-object counts, rate limits, anti-abuse controls, spam controls, malformed-payload rejection, or denial-of-service protection. Such enforcement is operational policy, not mention-specific authorization. + +### 3.5 Group selectors are not group governance roles + +The selector values `all`, `agents`, and `humans` **MUST NOT** be interpreted as P4 group governance roles. + +P4 group governance roles remain: + +```text +owner +admin +member +``` + +This Profile’s group selectors are mention targets, not authorization roles. + +--- + +## 4. Profile Binding Model + +### 4.1 Extension marker + +This Profile does not require a dedicated payload protocol name. + +A structured JSON payload is mention-bearing when it is carried in one of the supported group-message payload locations and contains a top-level `mentions` array conforming to this Profile. + +Receivers **MUST NOT** require or rely on a top-level `protocol` field to recognize mentions. + +If a structured JSON payload does not contain a top-level `mentions` array, this Profile does not apply to that payload. + +### 4.2 Relationship with outer `meta.profile` + +This Profile **MUST NOT** replace the outer `params.meta.profile` of the enclosing group message operation. + +The enclosing group message operation keeps its original Profile name, for example: + +- `anp.group.base.v1` for `group.send` without Group E2EE; +- `anp.group.e2ee.v1` for `group.e2ee.send`. + +### 4.3 Content type + +Mention-bearing structured payloads **MUST** use ordinary JSON payload carriage. + +For non-E2EE Group Base: + +```json +"meta": { + "content_type": "application/json" +} +``` + +For Group E2EE inner plaintext: + +```json +{ + "application_content_type": "application/json" +} +``` + +Implementations **MUST NOT** define a new content type solely to distinguish mention-bearing messages from other structured JSON application payloads. + +--- + +## 5. Mention-bearing Message Object + +### 5.1 Recommended structure + +A mention-bearing message payload has the following minimum structure: + +```json +{ + "text": "@agents please summarize this discussion.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 7, + "unit": "unicode_code_point" + }, + "target": { + "kind": "group_selector", + "selector": "agents" + }, + "mention_role": "addressee" + } + ] +} +``` + +### 5.2 Top-level fields + +| Field | Requirement | Type | Semantics | +|---|---:|---|---| +| `text` | **MUST** | string | Human-readable message text containing the mention surface syntax. | +| `mentions` | **MUST** | array | Structured mention objects in this message. | +| `annotations` | **MAY** | object | Application extension metadata. It is not used for routing, security, or authorization. | + +If the message has no structured mention semantics, the sender **SHOULD NOT** include a top-level `mentions` field and should instead use the ordinary content model of the enclosing Profile. + +Unrecognized top-level fields **MAY** be ignored by mention processors. + +### 5.3 `mentions` array + +`mentions` **MUST** be an array. + +Each element **MUST** be a mention object as defined in Section 5.4. + +`mentions[*].id` values **MUST** be unique within the same message payload. + +The order of `mentions` **SHOULD** follow the order in which mention surfaces appear in `text`. + +--- + +### 5.4 Mention object + +The minimum mention object is: + +```json +{ + "id": "men_1", + "range": { + "start": 0, + "end": 7, + "unit": "unicode_code_point" + }, + "target": { + "kind": "group_selector", + "selector": "agents" + }, + "mention_role": "addressee" +} +``` + +Field requirements: + +| Field | Requirement | Type | Semantics | +|---|---:|---|---| +| `id` | **MUST** | string | Message-local mention identifier. It has no global semantics. | +| `range` | **MUST** | object | Range of the mention surface in `text`. | +| `target` | **MUST** | object | Machine-readable mention target. | +| `mention_role` | **MAY** | string | Mention role. If omitted, the receiver **MUST** interpret it as `addressee`. | + +A mention object **MUST NOT** contain: + +- `sender`; +- `sender_did`; +- `from`; +- `actor_did`; +- `auth`; +- `origin_proof`; +- `proof`; +- `signature`. + +--- + +### 5.5 Mention range + +The range object is: + +```json +{ + "start": 0, + "end": 7, + "unit": "unicode_code_point" +} +``` + +Field requirements: + +| Field | Requirement | Type | Semantics | +|---|---:|---|---| +| `start` | **MUST** | non-negative integer | Inclusive start offset in `text`. | +| `end` | **MUST** | non-negative integer | Exclusive end offset in `text`. | +| `unit` | **MUST** | string | In v1, it **MUST** be `unicode_code_point`. | + +Rules: + +1. `start` **MUST** be less than `end`. +2. `end` **MUST NOT** exceed the number of Unicode code points in `text`. +3. The range is calculated over the exact JSON string value of `text` after JSON parsing and before any UI normalization, transliteration, or Markdown rendering. +4. The substring identified by `range` is the mention surface. The surface string is intentionally not duplicated in the mention object in v1. +5. If a terminal cannot validate the range, it **MUST** ignore that mention object for mention-triggering purposes, but it **MAY** still display the original `text`. + +--- + +### 5.6 Mention target + +#### 5.6.1 Single human target + +```json +{ + "kind": "human", + "did": "did:wba:example.com:user:alice", + "display_name": "Alice" +} +``` + +Rules: + +- `kind` **MUST** be `human`. +- `did` **MUST** exist and **MUST** be a DID. +- `display_name` **MAY** exist as a sender-side display snapshot. +- `display_name` **MUST NOT** be used as identity or authorization evidence. + +#### 5.6.2 Single agent target + +```json +{ + "kind": "agent", + "did": "did:wba:example.com:agent:product-assistant", + "display_name": "Product Assistant" +} +``` + +Rules: + +- `kind` **MUST** be `agent`. +- `did` **MUST** exist and **MUST** be a DID. +- `display_name` **MAY** exist as a sender-side display snapshot. +- Agent capability discovery, Agent Description resolution, and profile lookup are outside this Profile. + +#### 5.6.3 Group selector target + +```json +{ + "kind": "group_selector", + "selector": "agents" +} +``` + +Rules: + +- `kind` **MUST** be `group_selector`. +- `selector` **MUST** be one of: + - `all` + - `agents` + - `humans` +- `did` **MUST NOT** appear when `kind = "group_selector"`. +- The selector scope is the group identified by the enclosing group message context. +- The selector **MUST NOT** be interpreted as a P4 group governance role. + +--- + +### 5.7 Mention role + +The `mention_role` field is optional. + +Allowed values in v1: + +| Value | Semantics | +|---|---| +| `addressee` | The mentioned target is an intended recipient of attention. This is the default. | +| `cc` | The mentioned target is copied or referenced, but not necessarily expected to act. | + +Rules: + +- If `mention_role` is omitted, the receiver **MUST** interpret it as `addressee`. +- If `mention_role` is present, it **MUST** be one of the allowed values in this section. +- `mention_role` **MUST NOT** be used as a group governance role. +- `mention_role` **MUST NOT** be used to override group send permission or any enclosing Profile authorization rule. + +--- + +## 6. Group Selector Semantics + +### 6.1 `@all` + +`@all` is represented as: + +```json +{ + "target": { + "kind": "group_selector", + "selector": "all" + } +} +``` + +Terminal-side interpretation: + +```text +all active group members in the enclosing group context +``` + +### 6.2 `@agents` + +`@agents` is represented as: + +```json +{ + "target": { + "kind": "group_selector", + "selector": "agents" + } +} +``` + +Terminal-side interpretation: + +```text +active group members that the local application roster or profile layer classifies as agents +``` + +### 6.3 `@humans` + +`@humans` is represented as: + +```json +{ + "target": { + "kind": "group_selector", + "selector": "humans" + } +} +``` + +Terminal-side interpretation: + +```text +active group members that the local application roster or profile layer classifies as humans +``` + +### 6.4 Selector resolution snapshot + +For group messages, a terminal **SHOULD** resolve group selectors against the group state snapshot associated with the accepted message when that snapshot is available. + +In Group Base and Group E2EE, this is normally the `group_state_version` returned or delivered with the accepted message context. + +If the terminal does not have that exact group state snapshot, it **MAY** resolve the selector against the best available local group state and mark the result as best-effort. + +### 6.5 Member kind source + +The classification of a member as `human` or `agent` is an application-layer roster or profile attribute. + +This Profile does not define a new P4 `group_member` field for this classification. + +Implementations **MUST NOT** infer `human` or `agent` solely from a P4 governance role such as `owner`, `admin`, or `member`. + +--- + +## 7. Placement Rules + +### 7.1 Group Base without E2EE + +For `group.send` under `anp.group.base.v1`: + +- `params.meta.content_type` **MUST** be `application/json`; +- `params.body.payload` **MUST** carry the mention-bearing message object; +- `params.auth.origin_proof` is the sender proof required by Group Base; +- the Group Host applies the existing Group Base checks; +- the Group Host **MUST NOT** perform mention-specific authorization or selector expansion. + +Example: + +```json +{ + "jsonrpc": "2.0", + "id": "req-group-mention-001", + "method": "group.send", + "params": { + "meta": { + "profile": "anp.group.base.v1", + "security_profile": "transport-protected", + "sender_did": "did:wba:example.com:user:alice", + "target": { + "kind": "group", + "did": "did:wba:groups.example.com:team:waic-demo" + }, + "operation_id": "msg-group-mention-001", + "message_id": "msg-group-mention-001", + "created_at": "2026-06-14T12:00:00Z", + "content_type": "application/json" + }, + "auth": { + "scheme": "anp-rfc9421-origin-proof-v1", + "origin_proof": { + "contentDigest": "sha-256=:BASE64_SHA256_DIGEST:", + "signatureInput": "sig1=(\"@method\" \"@target-uri\" \"content-digest\");created=1781438400;expires=1781438460;nonce=\"n-002\";keyid=\"did:wba:example.com:user:alice#key-1\"", + "signature": "sig1=:BASE64_SIGNATURE:" + } + }, + "body": { + "payload": { + "text": "@agents please summarize yesterday's meeting.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 7, + "unit": "unicode_code_point" + }, + "target": { + "kind": "group_selector", + "selector": "agents" + }, + "mention_role": "addressee" + } + ] + } + } + } +} +``` + +### 7.2 Group E2EE + +For `group.e2ee.send` under `anp.group.e2ee.v1`: + +- the outer `params.meta.content_type` remains `application/anp-group-cipher+json`; +- the outer `params.body` carries `group_cipher_object`; +- the mention-bearing object **MUST** be placed inside the inner `Group Application Plaintext.payload` before MLS `PrivateMessage` encryption; +- the inner `application_content_type` **MUST** be `application/json`. + +Example inner plaintext before encryption: + +```json +{ + "application_content_type": "application/json", + "thread_id": "thr-001", + "payload": { + "text": "@all please review the agenda.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 4, + "unit": "unicode_code_point" + }, + "target": { + "kind": "group_selector", + "selector": "all" + } + } + ] + } +} +``` + +The Group Host sees the outer ciphertext object. It authenticates and orders the `group.e2ee.send` request according to Group E2EE and Group Base rules, but it does not inspect or validate the encrypted `mentions` array. + +### 7.3 Incoming notifications + +When an ANP service pushes a mention-bearing group message using `group.incoming` or the corresponding Group E2EE delivery path: + +- the pushed payload **MUST** remain semantically equivalent to the accepted original message; +- if the enclosing Profile allows the original `auth.origin_proof` to be copied into the notification, the service **SHOULD** include a lossless copy so that terminal-side verification can bind the mention-bearing payload to the original sender; +- intermediate services **MUST NOT** rewrite `mentions` when forwarding or pushing the message. + +--- + +## 8. Sender Proof and Cryptographic Binding + +### 8.1 Non-E2EE Group Base + +For non-E2EE Group Base, the sender of a mention-bearing message is proven by the enclosing `auth.origin_proof`. + +The verification subject is the enclosing message sender: + +```text +params.meta.sender_did +``` + +The `mentions` array is protected because it is inside the `body` member of the `Signed Request Object`. + +### 8.2 Group E2EE + +For Group E2EE, `group.e2ee.send` uses the origin proof and group E2EE authenticated message semantics of the enclosing Profile. + +The `mentions` array is inside the MLS-protected inner `Group Application Plaintext`. It is not visible to the Group Host and is validated only after decryption by terminals or Agent runtimes. + +### 8.3 No mention-local proof + +A verifier **MUST NOT** require a mention-local signature or proof in v1. + +A receiver **MUST** treat any `proof`, `signature`, `origin_proof`, or `auth` field embedded inside a mention object as invalid for this Profile. + +--- + +## 9. Validation and Processing + +### 9.1 Server-side processing + +Servers, relay services, ingress services, and Group Host Services: + +1. **MUST** process the enclosing ANP group message according to the enclosing Profile; +2. **MUST** perform existing sender authentication, idempotence, target binding, security profile, and payload-carriage checks required by the enclosing Profile; +3. For group messages, **MUST** enforce group send permission as required by Group Base / Group E2EE; +4. **MUST NOT** perform mention-specific authorization; +5. **MUST NOT** expand `@all`, `@agents`, or `@humans` into member DID lists as part of message acceptance; +6. **MUST NOT** reject a message solely because a mention target DID is unknown to the server or a selector is broad; +7. **MUST** preserve the mention-bearing payload without unauthorized modification. + +This rule does not prevent a server from rejecting a message for ordinary enclosing-Profile or operational reasons, such as invalid JSON-RPC shape, unsupported content type, invalid origin proof, failed group send permission, invalid ciphertext object, idempotency conflict, payload-size limit, documented maximum mention-object count, rate limit, anti-abuse policy, spam control, or denial-of-service protection. + +### 9.2 Terminal-side validation + +A terminal, client, user agent, or Agent runtime that supports this Profile **MUST** perform mention validation after it has received or decrypted the application payload. + +The minimum terminal-side validation steps are: + +1. Verify or rely on the enclosing Profile’s authenticated sender context before triggering mention behavior. +2. Parse the JSON payload. +3. Check that the payload contains a top-level `mentions` array before applying this Profile. +4. Check that `text` is a string. +5. Check that `mentions` is an array. +6. Check each mention object has a unique `id`. +7. Check each `range` is valid for `text`. +8. Check `target.kind` is one of `human`, `agent`, or `group_selector`. +9. If `target.kind = "human"` or `target.kind = "agent"`, check that `target.did` exists. +10. If `target.kind = "group_selector"`, check that `target.selector` is one of `all`, `agents`, or `humans`. +11. If `mention_role` exists, check that it is one of `addressee` or `cc`. +12. Apply local rendering, notification, or Agent runtime behavior according to local policy. + +If a mention object fails terminal-side validation, the terminal **SHOULD** ignore that mention object for triggering, notification, or Agent activation purposes, but **MAY** still display the original message text. + +### 9.3 Mention permission interpretation + +In v1, there is no mention-specific permission policy. + +A terminal **MUST** treat a mention as allowed at the wire-protocol layer if: + +1. the enclosing group message was accepted or delivered under the applicable ANP Message Profile; and +2. the mention object is syntactically valid under this Profile. + +A terminal **MAY** apply local user preferences such as muting, notification throttling, or spam control. Such local preferences are not protocol-level mention authorization and **MUST NOT** be represented as a rejection of the ANP message itself. + +--- + +## 10. Examples + +### 10.1 Mentioning all humans in a group + +```json +{ + "text": "@humans please confirm your attendance.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 7, + "unit": "unicode_code_point" + }, + "target": { + "kind": "group_selector", + "selector": "humans" + } + } + ] +} +``` + +### 10.2 Mentioning a single human in a group + +```json +{ + "text": "@张三 please review this.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 3, + "unit": "unicode_code_point" + }, + "target": { + "kind": "human", + "did": "did:wba:example.com:user:zhangsan", + "display_name": "张三" + }, + "mention_role": "cc" + } + ] +} +``` + +### 10.3 Mentioning a single agent in a group + +```json +{ + "text": "@InvoiceBot extract the invoice fields.", + "mentions": [ + { + "id": "men_1", + "range": { + "start": 0, + "end": 11, + "unit": "unicode_code_point" + }, + "target": { + "kind": "agent", + "did": "did:wba:example.com:agent:invoice-bot", + "display_name": "InvoiceBot" + }, + "mention_role": "addressee" + } + ] +} +``` + +--- + +## 11. Security Considerations + +### 11.1 Mention spoofing + +Terminals **MUST NOT** use the visible text alone to determine a mention target. + +For example, the text `@Alice` is not sufficient to identify Alice. The terminal must use the corresponding structured `mentions[*].target` object. + +### 11.2 Display name is not identity + +`target.display_name` is only a display snapshot. + +Identity decisions **MUST** be based on DID for single-target mentions or on selector semantics for group selector mentions. + +### 11.3 No server-side mention authorization + +Because mention validation is terminal-side in v1, a server may accept and deliver a message whose mention objects later fail terminal-side validation. + +Terminals and Agent runtimes **MUST** avoid triggering privileged behavior from invalid mention objects. + +### 11.4 E2EE privacy + +In Group E2EE mode, mention objects are inside encrypted plaintext. + +Servers and Group Host Services should not expect to inspect or index mention targets unless an explicit future extension introduces encrypted or privacy-preserving notification hints. + +This Profile does not define such hints in v1. + +### 11.5 Replay and duplicate handling + +This Profile defines no mention-specific replay protection. + +Replay and duplicate handling are inherited from the enclosing ANP Message Profile through `operation_id`, `message_id`, E2EE session state, or group ordering semantics. + +--- + +## 12. Privacy Considerations + +### 12.1 Minimum metadata + +Mention targets can reveal social attention patterns. + +Implementations **SHOULD** keep `mentions` inside the protected payload position required by this Profile and **SHOULD NOT** duplicate mention targets into outer metadata. + +### 12.2 Group selector privacy + +A group selector such as `@agents` or `@humans` may reveal the sender’s intended audience, but it avoids exposing an expanded member DID list in the message payload. + +Implementations **SHOULD** preserve the selector rather than expanding it into individual DIDs at send time. + +--- + +## 13. Minimum Interoperability Requirements + +An implementation conforming to this Profile MUST support at least: + +1. top-level `mentions` as the extension marker in structured JSON group-message payloads; +2. `text` plus `mentions` message object structure; +3. mention targets of kind `human`, `agent`, and `group_selector`; +4. group selector values `all`, `agents`, and `humans`; +5. `unicode_code_point` mention ranges; +6. terminal-side validation of mention object shape and ranges; +7. no mention-local sender field; +8. no mention-local proof field; +9. placement of mention-bearing payloads inside `params.body.payload` for non-E2EE `application/json` group messages; +10. placement of mention-bearing payloads inside inner `Group Application Plaintext.payload` for Group E2EE messages; +11. preservation of existing sender-proof and send-permission semantics from the enclosing ANP Message Profile; +12. no server-side mention authorization or selector expansion in v1. + +--- + +## 14. Future Extensions + +Future versions may define: + +- Direct-message mention semantics; +- Mention notification hints for E2EE messages; +- Mention-specific notification delivery policies; +- Capability selector mentions, such as agents that support a specific protocol; +- Mention-level human authorization for high-risk actions; +- Rich text or multiple-body mention anchoring; +- Cross-group or external mention references; +- Standard roster fields for human / agent classification. + +These features are intentionally outside v1.