# 灵隙去中心化身份与寻址协议 v2(草案) > 版本:0.2(草案) > 状态:草案 > 层级:基础设施层 > 依赖:[灵隙原始协议 v1](../v1/01_raw-protocol.md) > 关联会议:[2026-06-29 v1草案讨论会](../00-record/2026-06-29-v1-draft-discussion.md) --- ## 摘要 本草案定义了灵隙协议栈中去中心化场景下的 Agent 身份认证与发现机制。v2 版本在 v1 草案基础上,根据 [2026-06-29 会议决议](../00-record/2026-06-29-v1-draft-discussion.md) 进行了以下核心调整: 1. **签名机制**:统一为非对称签名(Ed25519 默认) 2. **区块链定位**:从可选方案提升为身份协议的核心组成部分 3. **分层规范**:严格区分协议层(v1 本文件)与实现层(v1.1 的组件规范) 4. **版本规划**:DHT 实现按 Phase 分阶段推进 --- ## 1. 协议层定义范围 本文件**仅定义**以下协议层内容: - AgentID 的生成规则与格式 - 签名算法选择与验证流程 - 身份生命周期状态机 - 消息类型与载荷格式 - 发现协议的行为约束 **不包含**(移入实现层文档): - Solidity / 智能合约实现代码 → 移入 `v1.1 链上注册表实现规范` - DHT 协议栈实现细节 → 移入 `v1.1 DHT 实现规范` - 缓存策略与具体数据结构 → 移入 `v1.1 灵脉 Meridian 组件规范` --- ## 2. AgentID 生成规则 ### 2.1 ID 结构 ``` AgentID = {namespace}:{key_hash}[:{alias}] 示例: synapse:7hJ4x9K2mNpQ (无别名,官方命名空间) synapse:7hJ4x9K2mNpQ:llm-agent-01 (带别名) com.mycompany.agent:aB3dEfGhIjK (企业自定义命名空间) did:synapse:ethereum:0x1234... (DID 格式) ``` | 部分 | 格式 | 必填 | 说明 | |------|------|:----:|------| | namespace | string | ✓ | 命名空间标识 | | key_hash | base58 | ✓ | 公钥哈希的前 16 字节 | | alias | string | - | 人类可读别名(可选,不要求全局唯一) | ### 2.2 命名空间治理 | 命名空间 | 所有者 | 说明 | |---------|--------|------| | `synapse:` | 灵隙协议官方 | 官方保留前缀,推荐所有 Agent 使用 | | `did:synapse:` | 灵隙协议官方 | W3C DID 兼容格式,使用独立体系 | | `{反向域名}:` | 企业/组织 | 如 `com.mycompany.agent:`,无需注册 | | `test:` | 本地测试 | 仅用于开发测试环境 | ### 2.3 生成算法 ```go func GenerateAgentID(privateKey []byte, namespace string, alias string) string { // 1. 从私钥派生公钥(Ed25519) publicKey := ed25519.PrivateKey(privateKey).Public() // 2. 计算公钥哈希 hash := sha3.Sum256(publicKey) // 3. 取前 16 字节,Base58 编码 keyHash := base58.Encode(hash[:16]) // 4. 组装完整 ID if alias != "" { return fmt.Sprintf("%s:%s:%s", namespace, keyHash, alias) } return fmt.Sprintf("%s:%s", namespace, keyHash) } ``` ### 2.4 ID 特性 | 特性 | 说明 | |------|------| | 唯一性 | 相同公钥 → 相同 key_hash → 相同 AgentID | | 不可伪造 | 无法在没有私钥的情况下生成有效 AgentID | | 可验证 | 任何人都可以用公钥验证 AgentID 真实性 | | 不可预测 | 私钥随机生成,key_hash 不可预测 | --- ## 3. 签名机制 ### 3.1 签名算法栈 | 层级 | 算法 | 定位 | 说明 | |------|------|------|------| | **协议层(默认)** | **Ed25519** | 标准签名 | 所有消息的默认签名算法,64 字节签名值 | | **协议层(兼容)** | ECDSA-P256 | 跨链互操作 | 与支持 P256 的链(如 Solana)互操作 | | **协议层(兼容)** | ECDSA-secp256k1 | 以太坊系兼容 | 兼容以太坊、Polygon 等链 | | **传输层(可选)** | HMAC-SHA256 | 内网优化 | 仅在可信内网链路中使用,不作为消息签名的替代 | ### 3.2 签名内容 签名覆盖的字段(UTF-8 编码后签名): ``` signature_content = sender.agent_id | receiver.agent_id | timestamp | payload ``` 其中: - `sender.agent_id`:发送方完整 AgentID(字符串) - `receiver.agent_id`:接收方完整 AgentID(字符串,广播消息可省略) - `timestamp`:RFC3339 时间戳字符串 - `payload`:消息载荷的 JSON 序列化字符串 - 分隔符 `|` 为竖线字符(0x7C) ### 3.3 签名验证流程 ``` 发送方: 1. 用私钥对 signature_content 签名 2. 将签名值写入消息的 signature 字段 3. 将公钥 / 算法标识随消息一起发送 接收方: 1. 从消息中提取 sender.agent_id 和 sender.public_key 2. 用 public_key 重新计算 agent_id 的 key_hash 3. 与消息中 sender.agent_id 的 key_hash 部分比对 4. 如匹配,用公钥验证签名 5. 如验证通过,确认消息来源可信 ``` ### 3.4 消息签名格式 消息信封中与签名相关的字段定义: | 字段 | 类型 | 必填 | 默认值 | 说明 | |------|------|:----:|--------|------| | `signature` | string | ✓ | - | Ed25519 签名值(Base64 编码) | | `signature_algorithm` | string | ✓ | `Ed25519` | 签名算法标识 | | `public_key` | string | ✓ | - | 发送方公钥(Base64 编码) | ### 3.5 算法标识枚举 | 标识值 | 算法 | 签名长度 | |--------|------|---------| | `Ed25519` | Ed25519 | 64 字节 | | `ECDSA-P256` | ECDSA P-256 | 64-72 字节(DER 编码) | | `ECDSA-secp256k1` | ECDSA secp256k1 | 64-72 字节(DER 编码) | | `HMAC-SHA256` | HMAC SHA-256 | 32 字节(仅内网) | ### 3.6 公钥派生 AgentID 校验 接收方必须执行以下检查以验证消息来源的真实性: ``` 1. 从 signature_algorithm 字段获取算法标识 2. 对 public_key 字段中的公钥进行哈希(算法依赖公钥类型) 3. 取哈希值前 16 字节,Base58 编码 4. 与 sender.agent_id 中的 key_hash 部分比对 5. 不一致 → 丢弃消息,返回 identity:validation_failed 错误 6. 一致 → 用 public_key 验证 signature 7. 签名无效 → 丢弃消息,返回 identity:signature_mismatch 错误 ``` --- ## 4. 发现协议 ### 4.1 三层发现架构 ``` 查询优先级:本地缓存(快) → DHT(中) → 区块链(慢,最终源) ┌──────────────┐ │ Agent A │ │ (查询方) │ └──────┬───────┘ │ ┌─────────────┼─────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ L1: │ │ L2: │ │ L3: │ │ 本地缓存 │ │ DHT │ │ 区块链 │ │ (内存) │ │ (网络) │ │ (链上合约) │ │ 微秒级 │ │ 毫秒级 │ │ 秒~分钟级 │ │ TTL 1min │ │ 弱一致 │ │ 最终一致性源 │ └──────────┘ └──────────┘ └──────────────┘ ``` | 层级 | 组件 | 延迟 | 一致性 | v1.0 支持 | v1.1 支持 | v1.2 支持 | |------|------|------|--------|:---------:|:---------:|:---------:| | L1 | 本地缓存 | 微秒 | 最终(TTL) | ✓ | ✓ | ✓ | | L2 | 广播查询 | 毫秒 | 弱 | ✓ | - | - | | L2 | 分层 DHT | 毫秒~秒 | 最终 | - | ✓ | - | | L2 | 完整 Kademlia | 毫秒 | 强 | - | - | ✓ | | L3 | 区块链注册表 | 秒~分钟 | 最终一致性源 | ✓ | ✓ | ✓ | ### 4.2 L2 发现 — 广播查询(v1.0) 适用于小型网络,无需复杂路由: ``` 请求(广播): type: "identity:lookup" target_id: "目标 AgentID" requester_id: "查询方 AgentID" timestamp: "2026-06-29T12:00:00Z" 响应(单播给查询方): type: "identity:lookup_response" target_id: "目标 AgentID" endpoint: "http://target:8080" public_key: "Base64 编码的公钥" signature: "目标 Agent 对该端点的签名" ``` ### 4.3 L3 发现 — 区块链注册表(v1.0+,核心层) 区块链作为最终一致性源,所有 Agent 身份以链上记录为权威来源。 #### 4.3.1 链上记录结构(协议层定义,实现见 v1.1) ```go type OnChainAgentRecord struct { AgentID string // Agent 唯一标识 Endpoint string // 当前网络地址 PublicKey []byte // 公钥 Status string // 状态:registered/active/suspended/revoked RegisteredAt int64 // 注册时间戳 LastHeartbeat int64 // 最后心跳时间戳 } ``` #### 4.3.2 查询行为 ``` 1. 查询方构造 lookup 请求(可先查本地缓存,再查 DHT) 2. 本地和 DHT 均未命中 → 查询链上注册表 3. 收到链上记录后: a. 验证链上记录的签名(已在合约级别验证过) b. 更新本地缓存(设置 TTL) c. 可选:广播到 DHT 加速后续查询 4. 链上记录缺失 → 返回 Agent 不存在 ``` ### 4.4 发现消息类型 | 消息类型 | 方向 | 说明 | v1.0 | |---------|------|------|:----:| | `identity:lookup` | 广播 | 查询 Agent 信息 | ✓ | | `identity:lookup_response` | 单播 | 查询响应 | ✓ | | `identity:register` | → 链 | 注册 Agent 身份 | ✓ | | `identity:heartbeat` | → 链 | 心跳保活 | ✓ | | `identity:revoke` | → 链 | 注销身份 | ✓ | | `identity:challenge` | 双向 | Endpoint 验证挑战 | ✓ | | `identity:challenge_response` | 双向 | 挑战响应 | ✓ | | `dht:ping` | DHT | 节点探测 | v1.1 | | `dht:store` | DHT | 存储记录 | v1.1 | | `dht:find_value` | DHT | 查找 Agent 记录 | v1.1 | | `dht:find_node` | DHT | 查找附近节点 | v1.2 | | `dht:notify` | DHT | 通知记录更新 | v1.2 | --- ## 5. 身份生命周期 ### 5.1 状态机 ``` ┌──────────────┐ │ 离线 │ │ (offline) │ └──────┬───────┘ │ 链上注册成功 ▼ ┌──────────────┐ ┌─────────│ 活跃 │─────────┐ │ │ (active) │ │ │ └──────┬───────┘ │ │ │ 心跳刷新 │ 心跳超时 │ ▼ │ │ ┌──────────────┐ │ │ │ 待验证 │ │ │ │ (pending) │ │ │ └──────┬───────┘ │ │ │ │ │ ┌─────────┴─────────┐ │ │ ▼ ▼ │ │ ┌──────────┐ ┌──────────┐ │ │ │ 正常 │ │ 挂起 │ │ │ │ (active) │ │(suspended)│ │ │ └────┬─────┘ └────┬─────┘ │ └──────┴──────────────────┴───────┘ │ ▼ ┌──────────────┐ │ 已注销 │ │ (revoked) │ └──────────────┘ ``` ### 5.2 状态说明 | 状态 | 说明 | 链上状态 | DHT 可发现 | |------|------|:--------:|:----------:| | offline | 初始状态,未注册 | 无 | 否 | | active | 已注册,心跳正常 | Registered | 是 | | pending | 已注册,Endpoint 待验证 | Registered | 否 | | suspended | 心跳超时(3 倍间隔) | Registered | 否 | | revoked | 主动注销 | Revoked | 否 | ### 5.3 关键约束 | 行为 | 约束 | |------|------| | 注册 | 必须同时完成链上交易和本地签名验证 | | 心跳 | 默认间隔 1 小时,可配置 | | 挂起 | 超过 3 次心跳间隔未更新 → 自动挂起 | | 注销 | 链上 revoke 交易 → 状态切换为 revoked | | Endpoint 变更 | 必须通过心跳或更新交易声明新地址 | --- ## 6. Endpoint 验证 ### 6.1 挑战-响应协议 为防止 Endpoint 欺骗,引入双向认证: ``` 1. Agent A 声称自己是 "synapse:abc123:agent-A" 并声称其 Endpoint 是 "http://A:8080" 2. Agent B 收到声明后: a. 用 A 的公钥验证 AgentID 合法 b. 向 Endpoint 发送挑战(包含随机 Nonce) c. A 必须用私钥对 Nonce 签名响应 d. 响应通过 → Endpoint 绑定确认 ``` ### 6.2 消息载荷 ```go // 挑战消息(type: "identity:challenge") type ChallengePayload struct { ChallengeID string // 挑战唯一标识 Nonce []byte // 随机数(32 字节) Timestamp string // 发送时间(RFC3339) } // 响应消息(type: "identity:challenge_response") type ChallengeResponsePayload struct { ChallengeID string // 对应挑战 ID Nonce []byte // 原样返回的 Nonce Signature []byte // 对 Nonce 的 Ed25519 签名 } ``` --- ## 7. 安全考虑 ### 7.1 威胁模型 | 威胁 | 防护措施 | |------|---------| | 身份伪造 | 公钥派生 ID + 签名验证(公钥不匹配 → 丢弃) | | Endpoint 欺骗 | 挑战-响应协议(需私钥签名响应) | | 重放攻击 | 时间戳窗口(±5min)+ Nonce 去重 | | 中间人攻击 | TLS + 消息级签名验证 | | 女巫攻击 | 链上质押(可选,由实现层控制) | | 日食攻击 | 多路径查询(L1 → L2 → L3 多条路径) | ### 7.2 反重放机制 ```go type AntiReplayConfig struct { Window time.Duration // 时间窗口(默认 5 分钟) } // 接收消息时必须执行: // 1. 检查 timestamp 是否在 [now - Window, now + Window] 范围内 // 2. 检查 Nonce/CorrelationID 是否已处理过(内存去重集合) // 3. 以上任一不通过 → 丢弃并返回 identity:replay_detected 错误 ``` --- ## 8. 版本规划 | 版本 | 身份相关功能 | 签名方案 | 发现机制 | 组件实现 | |------|------------|---------|---------|---------| | **v1.0** | AgentID 生成、签名验证、生命周期定义 | Ed25519(默认)+ ECDSA(兼容) | 广播 + 区块链注册表(协议层定义) | 仅协议层定义 | | **v1.1** | 分层 DHT、缓存策略、链上合约实现 | 同上 + HMAC 内网优化 | 分层 DHT + 完整合约实现 | 七大组件落地 | | **v1.2** | 密钥轮换、隐私保护、跨链互操作 | 同上 + 零知识证明(可选) | 完整 Kademlia | DID 方法注册 | --- ## 9. 与现有协议的关系 ### 9.1 与 Raw 协议的关系 本草案扩展 [Raw 协议](../v1/01_raw-protocol.md) 的签名机制和 AgentEndpoint 定义: | Raw 协议字段 | 变更 | |-------------|------| | `signature` | 从 HMAC 变更为 Ed25519 签名 | | `signature_algorithm` | 默认值从 `HMAC-SHA256` 变更为 `Ed25519` | | `sender` | 新增 `public_key` 字段(可选携带) | ### 9.2 与灵脉(Meridian)的关系 | 模式 | 行为 | |------|------| | **中心化可用**(v1.0) | 灵脉作为可选中心目录,本草案的身份验证机制仍然生效 | | **去中心化**(v1.1) | 灵脉作为 DHT 引导节点(Bootstrap Node),不存储全量路由 | | **纯 Web3**(v1.2) | 完全去中心化,灵脉退化为本地路由缓存 | ### 9.3 与灵玺(Sigil)的关系 | 组件 | 职责边界 | |------|---------| | **本草案(协议层)** | 定义签名算法、验证流程、ID 生成规则 | | **灵玺 Sigil(v1.1 实现层)** | 密钥管理、签名/验证的 API 封装、密钥轮换逻辑 | --- ## 10. 待解决问题(Open Issues) | 问题 | 说明 | 优先级 | 目标版本 | |------|------|--------|:--------:| | 密钥轮换 | 更换私钥后 AgentID 会改变,如何保持身份连续性 | 高 | v1.2 | | 隐私保护 | 公钥哈希是否能追踪 Agent 行为 | 高 | v1.2 | | 名称冲突 | 人类可读别名可能重复 | 中 | v1.1 | | 链上 Gas 成本 | 频繁心跳会导致高额交易费用 | 中 | v1.1 | | DID 方法注册 | W3C 标准 DID 方法注册流程 | 低 | v1.2 | | 跨链互操作 | 不同链上的 Agent 如何互相发现 | 低 | v1.2 | --- ## 11. 参考资料 - [RFC 8032: Ed25519 Edwards-Curve Digital Signature Algorithm](https://datatracker.ietf.org/doc/html/rfc8032) - [Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-core/) - [Kademlia: A Peer-to-peer Information System Based on the XOR Metric](https://pdos.csail.mit.edu/~petar/papers/maymounkov-kademlia-lncs.pdf) --- ## 附录:本次版本变更记录 | 章节 | 变更内容 | 变更理由 | |------|---------|---------| | 整体 | 剥离 Solidity 合约实现、DHT 实现细节 | 遵循"协议层不包含实现细节"原则 | | 第3章 | 签名机制重写:Ed25519 默认,HMAC 降级 | [会议决议一](../00-record/2026-06-29-v1-draft-discussion.md#决议一签名机制统一为非对称签名) | | 第4章 | 区块链从"可选方案"提升为"核心组成部分" | [会议决议二](../00-record/2026-06-29-v1-draft-discussion.md#决议二区块链作为身份协议的核心组成部分) | | 第4章 | DHT 分阶段定义(v1.0 / v1.1 / v1.2) | [会议决议三](../00-record/2026-06-29-v1-draft-discussion.md#决议三dht-分阶段实现) | | 第8章 | 新增版本规划表 | [会议决议四](../00-record/2026-06-29-v1-draft-discussion.md#决议四七大组件实现推迟到-v11) | | 全文 | solidity 合约代码、完整 DHT 实现移至 v1.1 规范 | 协议层/实现层分离 |