From 65710a4536ce57e6f032d54c8de6388e958f4300 Mon Sep 17 00:00:00 2001 From: lychang <632945494@qq.com> Date: Mon, 29 Jun 2026 02:12:44 +0800 Subject: [PATCH] =?UTF-8?q?=E7=81=B5=E9=9A=99(synapse)=20v1.0.0=20?= =?UTF-8?q?=E7=89=88=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 29 +- docs/00-record/00-meeting-workflow.md | 452 +++++++++++++++ .../2026-06-29-v1-draft-discussion.md | 111 ++++ .../2026-06-29-identity-protocol-v2.md | 468 ++++++++++++++++ .../capabilities-system.md | 0 docs/{implement => 02-guide}/components.md | 0 .../{implement => 02-guide}/content-system.md | 0 docs/{implement => 02-guide}/error-codes.md | 0 .../{implement => 02-guide}/grpc-transport.md | 0 docs/{implement => 02-guide}/hil-mechanism.md | 0 .../message-extensions.md | 0 .../transport-modes.md | 0 docs/{poster => 03-asset}/poster-amber.svg | 0 docs/{poster => 03-asset}/poster-aurora.svg | 0 docs/{poster => 03-asset}/poster-cyan.svg | 0 docs/{poster => 03-asset}/poster-emerald.svg | 0 docs/{poster => 03-asset}/poster-rose.svg | 0 docs/{poster => 03-asset}/poster-v0.svg | 0 docs/{poster => 03-asset}/poster-v1-a.svg | 0 docs/{poster => 03-asset}/poster-v1-b.svg | 0 docs/{poster => 03-asset}/poster.svg | 0 docs/v1/00_index.md | 20 +- docs/v1/01_raw-protocol.md | 105 ++-- docs/v1/02_a2a-protocol.md | 244 ++++---- docs/v1/03_a2n-protocol.md | 334 +++++------ docs/v1/04_p2a-protocol.md | 286 +++++----- docs/v1/05_identity-protocol-draft.md | 530 +++++++++--------- 27 files changed, 1819 insertions(+), 760 deletions(-) create mode 100644 docs/00-record/00-meeting-workflow.md create mode 100644 docs/00-record/2026-06-29-v1-draft-discussion.md create mode 100644 docs/01-draft/2026-06-29-identity-protocol-v2.md rename docs/{implement => 02-guide}/capabilities-system.md (100%) rename docs/{implement => 02-guide}/components.md (100%) rename docs/{implement => 02-guide}/content-system.md (100%) rename docs/{implement => 02-guide}/error-codes.md (100%) rename docs/{implement => 02-guide}/grpc-transport.md (100%) rename docs/{implement => 02-guide}/hil-mechanism.md (100%) rename docs/{implement => 02-guide}/message-extensions.md (100%) rename docs/{implement => 02-guide}/transport-modes.md (100%) rename docs/{poster => 03-asset}/poster-amber.svg (100%) rename docs/{poster => 03-asset}/poster-aurora.svg (100%) rename docs/{poster => 03-asset}/poster-cyan.svg (100%) rename docs/{poster => 03-asset}/poster-emerald.svg (100%) rename docs/{poster => 03-asset}/poster-rose.svg (100%) rename docs/{poster => 03-asset}/poster-v0.svg (100%) rename docs/{poster => 03-asset}/poster-v1-a.svg (100%) rename docs/{poster => 03-asset}/poster-v1-b.svg (100%) rename docs/{poster => 03-asset}/poster.svg (100%) diff --git a/README.md b/README.md index 016640c..bad1430 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ - - 灵隙 Synapse + + 灵隙 Synapse # 灵隙（Synapse）— 智能体协作协议栈 @@ -228,14 +228,14 @@ func main() { | [docs/v1/03_a2n-protocol.md](docs/v1/03_a2n-protocol.md) | A2N 协议（群组协作） | | [docs/v1/04_p2a-protocol.md](docs/v1/04_p2a-protocol.md) | P2A 协议（外部调用） | | [docs/v1/05_identity-protocol-draft.md](docs/v1/05_identity-protocol-draft.md) | 去中心化身份与寻址（草案） | -| [docs/v1/components.md](docs/implement/components.md) | 七大组件层规范 | -| [docs/v1/content-system.md](docs/implement/content-system.md) | 内容类型系统 | -| [docs/v1/capabilities-system.md](docs/implement/capabilities-system.md) | 能力发现系统 | -| [docs/v1/error-codes.md](docs/implement/error-codes.md) | 数字分段错误码 | -| [docs/v1/hil-mechanism.md](docs/implement/hil-mechanism.md) | 人工干预机制 (HiL) | -| [docs/v1/grpc-transport.md](docs/implement/grpc-transport.md) | gRPC 传输规范 | -| [docs/v1/transport-modes.md](docs/implement/transport-modes.md) | 传输模式说明 | -| [docs/v1/message-extensions.md](docs/implement/message-extensions.md) | 消息扩展机制 | +| [docs/v1/components.md](docs/02-guide/components.md) | 七大组件层规范 | +| [docs/v1/content-system.md](docs/02-guide/content-system.md) | 内容类型系统 | +| [docs/v1/capabilities-system.md](docs/02-guide/capabilities-system.md) | 能力发现系统 | +| [docs/v1/error-codes.md](docs/02-guide/error-codes.md) | 数字分段错误码 | +| [docs/v1/hil-mechanism.md](docs/02-guide/hil-mechanism.md) | 人工干预机制 (HiL) | +| [docs/v1/grpc-transport.md](docs/02-guide/grpc-transport.md) | gRPC 传输规范 | +| [docs/v1/transport-modes.md](docs/02-guide/transport-modes.md) | 传输模式说明 | +| [docs/v1/message-extensions.md](docs/02-guide/message-extensions.md) | 消息扩展机制 | --- @@ -246,9 +246,12 @@ synapse/ ├── cmd/ # 命令行入口（待实现） ├── configs/ # 配置文件目录 ├── docs/ # 文档 -│ ├── v0/ # v0 版本协议文档 -│ ├── v1/ # v1 版本协议文档 -│ └── poster*.svg # 宣传海报（多种配色） +│ ├── v0/ # v0 协议规范 +│ ├── v1/ # v1 协议规范 +│ ├── 00-record/ # 会议与决策记录 +│ ├── 01-draft/ # 草案与方案提议 +│ ├── 02-guide/ # 实现指南参考 +│ └── 03-asset/ # 资源附件（海报等） ├── internal/ # 内部实现代码 │ ├── agent/ # Agent 协议实现 │ │ ├── group/ # A2N 群组协议 diff --git a/docs/00-record/00-meeting-workflow.md b/docs/00-record/00-meeting-workflow.md new file mode 100644 index 0000000..8abaab1 --- /dev/null +++ b/docs/00-record/00-meeting-workflow.md @@ -0,0 +1,452 @@ +# 灵隙协议协作工作流程 + +> 版本：1.0.0 +> 状态：生效 +> 适用范围：docs/ 下所有协议文档的评审与修订 + +--- + +## 1. 文档角色体系 + +docs/ 下的文档按 **内容成熟度** 分为以下目录，每个目录有明确的角色边界： + +``` +docs/ +├── v{数字}/ 协议规范 — 已定稿的协议定义，只增不改 +├── 00-record/ 会议记录 — 协作过程中的决策记录 +├── 01-draft/ 草案 — 待评审的技术方案提议 +├── 02-guide/ 实现指南 — 已确认的实现参考和示例 +└── 03-asset/ 资源附件 — 海报、图表等非文本资产 +``` + +| 角色 | 目录 | 内容定位 | 可修改性 | +|------|------|---------|:--------:| +| **协议规范** | `v{数字}/` | 已确认的协议定义 | ❌ 锁定（仅通过新版本覆盖） | +| **会议记录** | `00-record/` | 协作中的决策记录 | ✅ 补充（不可推翻已确认条目） | +| **草案** | `01-draft/` | 待评审的技术提案 | ✅ 自由编辑 | +| **实现指南** | `02-guide/` | 参考实现的技术指南 | ✅ 更新 | +| **资源附件** | `03-asset/` | 海报、图表、图片等 | ✅ 更新 | +| **索引** | 各目录的 `00_index.md` | 目录清单和版本说明 | ✅ 同步更新 | + +--- + +## 2. 文档版本独立规则 + +每一份文档独立维护版本号，不依赖目录版本： + +### 2.1 版本号格式 + +``` +{v1}.{v2}.{v3} + +示例： + 0.1 = 初始草案 + 0.2 = 草案修订 + 1.0.0 = 首次定稿 + 1.1.0 = 兼容性修订 + 2.0.0 = 不兼容修订 +``` + +### 2.2 版本段含义 + +| 段位 | 含义 | 变更条件 | +|:---:|------|---------| +| **v1** | 主版本 | 不兼容的协议变更（如签名算法替换） | +| **v2** | 次版本 | 兼容的功能增补（如新增消息类型） | +| **v3** | 补丁 | 勘误、措辞澄清、格式调整 | + +### 2.3 状态标签 + +每个文档元信息头必须有版本和状态： + +```markdown +> 版本：0.3 +> 状态：草案 +``` + +```markdown +> 版本：1.0.0 +> 状态：生效 +``` + +```markdown +> 版本：1.0.0 +> 状态：作废 +> 作废原因：被 v2.0.0 替代 +``` + +| 状态 | 说明 | 出现位置 | +|------|------|---------| +| `草案` | 待评审的内容 | `01-draft/` | +| `生效` | 已确认的规范 | `v{数字}/` | +| `作废` | 已被替代的旧版本 | `v{数字}/`（保留历史） | + +### 2.4 版本与目录的对应关系 + +| 目录 | 文档版本范围 | 说明 | +|:----:|------------|------| +| `01-draft/` | `0.x` | 草案阶段，版本号从 0.1 起跳 | +| `v{数字}/` | `>= 1.0.0` | 定稿后从 1.0.0 开始，移入 v{数字} 目录 | +| `00-record/` | `1.0.0`（固定） | 会议记录不增量版本，日期区分 | +| `02-guide/` | `>= 1.0.0` | 实现指南跟随对应的协议版本 | + +--- + +## 3. 协作场景 + +定义三种协作场景，覆盖不同粒度的决策： + +### 3.1 方案讨论 + +| 项目 | 内容 | +|------|------| +| **触发条件** | 你对某个技术方向有想法，想讨论可行性 | +| **你的输入** | 一句话想法、一个疑问、一个未解决的问题 | +| **AI 产出** | 结构化分析（影响范围、可行方案、利弊对比） | +| **你的输出** | 决定方向：继续、换方案、搁置 | + +### 3.2 草案评审 + +| 项目 | 内容 | +|------|------| +| **触发条件** | `01-draft/` 下有草案需要评审 | +| **AI 准备** | 提取草案的变更摘要、与现有规范的冲突点、待决议问题列表 | +| **你的输入** | 逐条拍板：通过 / 驳回（说明方向）/ 搁置 | +| **AI 产出** | 按决议更新草案、生成会议记录、更新索引 | + +### 3.3 快速裁定 + +| 项目 | 内容 | +|------|------| +| **触发条件** | 发现现有规范中的歧义、矛盾或遗漏 | +| **AI 分析** | 指出问题所在、给出修正提案、标注影响范围 | +| **你的输入** | 一分钟内拍板 | +| **AI 产出** | 记录裁定到 `00-record/`，更新关联文档 | + +--- + +## 4. 协作前准备 + +### 4.1 你需要准备的 + +| 场景 | 你需要提供 | +|------|-----------| +| **方案讨论** | 一句话描述你想讨论的方向或问题 | +| **草案评审** | 指定要评审的草案文件路径（`01-draft/` 下） | +| **快速裁定** | 指出有疑问的协议条款（文件+行号/章节） | + +你不需要准备格式化的文档——AI 会将你的口语化表达转化为结构化内容。 + +### 4.2 AI 会准备的 + +根据你的输入，AI 自动准备以下内容： + +| 场景 | AI 准备的内容 | +|------|-------------| +| **方案讨论** | 关联文档引用、影响范围分析、多个可选方案对比 | +| **草案评审** | 变更摘要（如是修订版）、与现有规范的冲突矩阵、待决议问题列表 | +| **快速裁定** | 问题定位、修正提案、受影响的文档列表 | + +--- + +## 5. 协作流程 + +### 5.1 角色定义 + +整个协作中只有两个角色： + +| 角色 | 你是谁 | 你的职责 | +|------|--------|---------| +| **你** | 决策者 | 提出方向、拍板决议、确认产出 | +| **AI 助理** | 执行者 | 分析方案、生成文档、记录决策、管理文件 | + +AI 不做决策，只做**分析、建议和执行**。所有决议由你最终拍板。 + +### 5.2 标准交互流程 + +一次协作的通用交互步骤： + +``` +步骤 1 — 你提出问题 + 你说出想法、疑问或需求（可以是口语化的） + +步骤 2 — AI 结构化回应 + AI 提取关键信息，形成结构化内容供你评判： + ├── □ 问题重述（确认理解正确） + ├── □ 关联文档引用 + ├── □ 可选方案（如有） + ├── □ 影响范围评估 + └── □ 待确认事项（你需要拍板的问题） + +步骤 3 — 你给出决议 + 你对 AI 提出的选项拍板，或提出修改方向 + +步骤 4 — AI 执行 + AI 根据决议： + ├── □ 更新或创建文档 + ├── □ 生成会议记录 + └── □ 更新索引文件 + +步骤 5 — 你确认（可选） + 你可以要求 AI 展示变更摘要，确认无误后结束 +``` + +### 5.3 决议输入方式 + +你通过以下方式给出决议，AI 根据不同的输入方式执行相应操作： + +| 你的输入 | AI 理解方式 | AI 执行 | +|---------|-----------|---------| +| 直接说结论（如"用方案一"） | 明确选择 | 按选定方案执行 | +| 给出修改方向（如"把 X 改为 Y"） | 指令式修改 | 执行具体修改 | +| 提供替代方案（如"试试这样..."） | 新提议 | 分析后返回步骤 2 | +| 保留意见（如"先放一放"） | 搁置 | 记录到待决议问题列表，不生成文件 | +| 要求更多信息（如"展开说说 DHT 的缺点"） | 追问 | 深入分析后返回步骤 2 | + +### 5.4 记录方式 + +每一轮交互结束后，AI 自动将决议记录到会议文件 `00-record/`，你不需要手动记录。 + +| AI 自动记录的内容 | 存放位置 | +|-------------------|---------| +| 决议结论 | `00-record/{日期}-{主题}.md` 的"决议事项"章节 | +| 决议理由 | 同上 | +| 影响范围 | 同上 | +| 后续行动项 | 同上 | +| 新生成/更新的草案 | `01-draft/{日期}-{草案名}-v{次}.md` | + +### 5.5 一次协作中允许的操作 + +| 操作 | 规则 | 示例 | +|------|------|------| +| 切换话题 | 随时可以 | "不说签名了，聊聊 DHT" | +| 推翻之前的决议 | 可以，但需说明理由 | "刚才说的方案一我想了想还是不行，因为..." | +| 要求回滚 | 可以，AI 会从 git 历史恢复 | "把刚才生成的 draft 删掉" | +| 问多个问题 | 一个一个来，AI 会逐个回应 | 建议一个问题讨论完再提下一个 | +| 中途中断 | 随时可以，AI 会保存当前进度 | 下次继续时会提供断点摘要 | + +--- + +## 6. 协作产出 + +### 6.1 AI 实时产出的文件 + +协作过程中，AI 实时生成以下文件，你无需等待： + +``` +产出文件清单： +├── □ 会议记录 → 00-record/{日期}-{主题}.md +├── □ 更新后的草案 → 01-draft/{日期}-{草案名}-v{次}.md +└── □ 索引更新 → 各目录的 00_index.md（如有变动） +``` + +### 6.2 会议记录模板 + +```markdown +# 会议记录：{主题} + +> 日期：{YYYY-MM-DD} +> 类型：方案讨论 / 草案评审 / 快速裁定 + +--- + +## 议题 + +{一句话描述本次讨论的内容} + +--- + +## 决议事项 + +### 决议一：{决议标题} + +| 项目 | 内容 | +|------|------| +| **结论** | {结论简述} | +| **理由** | {决策理由} | +| **影响范围** | {影响的文档/模块列表} | + +### 决议二：{决议标题} + +... + +--- + +## 补充讨论要点 + +{讨论中出现的值得记录的信息} + +--- + +## 附录：关联文档 + +| 文档 | 说明 | 关系 | +|------|------|------| +| [{文档路径}](../path/to/doc.md) | {文档简述} | 本次讨论的基础/产出 | + +--- + +## 后续行动 + +| 事项 | 目标版本 | 状态 | +|------|---------|:----:| +| {事项} | v{数字} | 待办 / 进行中 / 完成 | +``` + +### 6.3 文件命名规范 + +``` +会议记录： {YYYY-MM-DD}-{英文短名}.md → 00-record/ +草案： {YYYY-MM-DD}-{草案名}-v{次}.md → 01-draft/ +协议规范文档： {编号}_{英文短名}.md → v{数字}/ +实现指南文档： {英文短名}.md → 02-guide/ +索引文件： 00_index.md → 各目录根目录 +资源文件： {英文短名}.{后缀} → 03-asset/ +``` + +--- + +## 7. 决议覆盖范围 + +在一次协作中，决议的影响范围按以下层次递进： + +``` + ┌─────────────────────────────────────────┐ + │ 单文件内的问题 │ + │ 范围：措辞澄清 / 勘误 / 歧义裁定 │ + │ 你的输入：一句拍板 │ + │ AI 产出：修改文件 + 记录到 00-record │ + └────────────────┬────────────────────────┘ + │ 涉及跨文件/跨协议 + ▼ + ┌─────────────────────────────────────────┐ + │ 跨文件的方案变更 │ + │ 范围：涉及多个协议文档的技术决策 │ + │ 你的输入：选择方案 + 确认影响范围 │ + │ AI 产出：更新多份文档 + 更新/生成草案 │ + └────────────────┬────────────────────────┘ + │ 涉及版本范围/兼容性 + ▼ + ┌─────────────────────────────────────────┐ + │ 版本级规划变更 │ + │ 范围：决定 v1.0 / v1.1 / v2.0 的内容 │ + │ 你的输入：指定版本范围和分工 │ + │ AI 产出：更新 00_index.md + 记录到 00-record │ + └─────────────────────────────────────────┘ +``` + +你可以在任何层次上拍板，AI 会自动跟进所有下游影响。 + +--- + +## 8. 草案晋升路径 + +一份草案从创建到定稿的标准路径： + +``` + ┌──────────┐ + │ 想法 │ + └────┬─────┘ + │ 你说出想法，AI 写出草案 + ▼ + ┌───────────┐ + │ 01-draft/ │ ←── 可任意修改 + │ v0.1 │ + └─────┬─────┘ + │ 你评审 + 拍板修改方向 + ▼ + ┌───────────┐ + │ 01-draft/ │ ←── 可修改 + │ v0.2 │ + └─────┬─────┘ + │ 你确认定稿 + ▼ + ┌───────────┐ + │ v{数字}/ │ ←── 锁定，只增不改 + │ v1.0.0 │ + └───────────┘ + │ 后续修订 + ▼ + ┌───────────┐ + │ v{数字}/ │ + │ v2.0.0 │ ←── 不兼容修订另开新版本 + └───────────┘ +``` + +| 阶段 | 版本号范围 | 目录 | 修改权限 | +|:----:|:----------:|:----:|:--------:| +| 初始创建 | 0.1 | `01-draft/` | 自由编辑 | +| 修订中 | 0.2, 0.3... | `01-draft/` | 自由编辑 | +| 评审通过 | 1.0.0 | 移入 `v{数字}/` | 锁定 | +| 兼容修订 | 1.1.0, 1.2.0... | `v{数字}/` | 仅追加，不修改已有内容 | +| 不兼容修订 | 2.0.0 | 新建 `v{数字+1}/` | 旧版本作废，新版本重新锁定 | + +--- + +## 9. 目录与文件命名规范 + +### 9.1 目录命名规则 + +| 规则 | 说明 | +|------|------| +| 协议规范目录 | 固定格式 `v{数字}`，数字表示协议主版本 | +| 其他内容目录 | 格式 `{两位数字}-{英文短名}`，数字按内容成熟度/使用频率排序 | + +**已定义目录**： + +``` +docs/ +├── v0/ v0 协议规范 +├── v1/ v1 协议规范 +├── 00-record/ 会议与决策记录 +├── 01-draft/ 草案与方案提议 +├── 02-guide/ 实现指南参考 +└── 03-asset/ 资源附件（海报、图表等） +``` + +如需新增目录，新目录的编号插在末尾（当前为 03），待下次整理时统一重排。 + +### 9.2 文件命名规则 + +``` +协议规范层（v{数字}/）： + {两位数字}_{英文短名}.md + 示例：01_raw-protocol.md + +会议记录层（00-record/）： + {YYYY-MM-DD}-{英文短名}.md + 示例：2026-06-29-v1-draft-discussion.md + +草案层（01-draft/）： + {YYYY-MM-DD}-{草案名}-v{次}.md + 示例：2026-06-29-identity-protocol-v2.md + +实现指南层（02-guide/）： + {英文短名}.md + 示例：components.md + +资源附件层（03-asset/）： + {英文短名}.{后缀} + 示例：poster.svg + +索引文件： + 00_index.md（各目录的根目录） +``` + +--- + +## 10. 免交互操作 + +以下情况不需要你开口，AI 直接执行： + +| 场景 | AI 自行操作 | 例外 | +|------|-----------|------| +| 草案内的措辞修正 | 直接修改 `01-draft/` 文件 | 涉及技术含义的措辞变化需先问你 | +| 漏洞/矛盾自查 | 发现后指出并给出修复提案，等你确认后执行 | - | +| 会议记录遗漏补充 | 直接追加，标注 `[后补]` | 不能推翻已记录的决议 | +| 实现指南更新 | 直接修改 `02-guide/` 文件 | 引用到协议层规范时需通知你 | +| 索引文件同步 | 直接修改 `00_index.md` | 版本号变更必须与你确认一致 | + +--- + +> *本文件本身遵循上述规范，如内容与实际操作不一致，以实际操作为准并及时修正本文件。* diff --git a/docs/00-record/2026-06-29-v1-draft-discussion.md b/docs/00-record/2026-06-29-v1-draft-discussion.md new file mode 100644 index 0000000..ca0d610 --- /dev/null +++ b/docs/00-record/2026-06-29-v1-draft-discussion.md @@ -0,0 +1,111 @@ +# 会议记录：v1 草案讨论会 + +> 日期：2026-06-29 +> 时长：1 session +> 主题：灵隙 v1 版本身份协议草案讨论 & 版本规划 + +--- + +## 会议议题 + +围绕 [v1 身份协议草案](../v1/05_identity-protocol-draft.md) 的技术方案与版本规划进行讨论。 + +--- + +## 决议事项 + +### 决议一：签名机制统一为非对称签名 + +| 项目 | 内容 | +|------|------| +| **结论** | 直接统一到非对称签名体系 | +| **默认算法** | Ed25519（高效、安全） | +| **兼容算法** | ECDSA-P256（跨链互操作）、ECDSA-secp256k1（兼容以太坊系） | +| **HMAC 定位** | 降级为可信内网链路的可选优化，不作为协议层的签名方案 | +| **影响范围** | [Raw协议](../v1/01_raw-protocol.md) 第4章签名机制需重写，统一为公钥签名；`signature` 字段含义从 HMAC 变更为 Ed25519/ECDSA 签名值；`signature_algorithm` 字段保留，默认值改为 `Ed25519` | + +### 决议二：区块链作为身份协议的核心组成部分 + +| 项目 | 内容 | +|------|------| +| **结论** | 区块链不是可选插件，而是身份协议的核心层 | +| **定位** | 三层发现架构中，区块链作为"最终一致性源"（Source of Truth） | +| **默认基础设施** | 每个 Synapse 网络应至少有一个链上注册表，作为 Agent 身份的最终存证 | +| **兼容性** | 支持多链：Ethereum（高价值）、Polygon（高频）、联盟链（企业） | +| **混合模式** | 本地缓存 + DHT 做快速查找，区块链做最终验证和仲裁 | + +### 决议三：DHT 分阶段实现 + +| 阶段 | 范围 | 说明 | +|------|------|------| +| **Phase 1（v1.0）** | 广播查询 + 中心目录 | 小型网络（<100 Agent），用灵脉 Meridian 作为可选目录，无 DHT | +| **Phase 2（v1.1）** | 分层 DHT | 中等规模（100-10000 Agent），引入分层路由 | +| **Phase 3（v1.2）** | 完整 Kademlia + 隐私保护 + 密钥轮换 | 大规模网络（>10000 Agent），支持密钥轮换和隐私保护 | + +### 决议四：七大组件实现推迟到 v1.1 + +| 项目 | 内容 | +|------|------| +| **结论** | v1 版本聚焦协议层定义（数据格式、消息类型、行为约束），不做具体落地实现 | +| **v1 范围** | Raw / A2A / A2N / P2A 四个协议规范 + 去中心化身份草案 | +| **v1.1 范围** | 七大组件（灵脉/灵玺/灵鉴/灵泊/灵瞰/灵衡/灵枢）的具体落地实现 | +| **v1.2 范围** | 完整 Kademlia DHT、隐私保护机制、密钥轮换、跨链互操作 | + +--- + +## 补充讨论要点 + +### 1. 协议层与实现层的明确边界 + +v1 的身份草案目前包含部分实现细节（如 Solidity 合约代码），需要在 v2 版本中剥离： +- **协议层（v1）**：只定义 AgentID 格式、签名算法、消息类型、生命周期状态机 +- **实现层（v1.1+）**：具体的区块链合约实现、DHT 协议栈、缓存策略 + +### 2. AgentID 命名空间治理 + +| 问题 | 方案 | +|------|------| +| namespace 的分配 | 官方保留 `synapse:` 前缀；企业自定义采用反向域名（如 `com.mycompany.agent:`） | +| alias 全局唯一性 | 不要求全局唯一，仅在本地或联盟内有效 | +| DID 兼容 | `did:synapse:` 独立成体系，与 `namespace:key_hash:alias` 格式并存 | + +### 3. 签名算法选择理由 + +选择 Ed25519 作为默认算法的原因： +- 比 ECDSA-P256 快 2-3 倍 +- 固定长度签名（64 字节），便于编码和存储 +- 抗侧信道攻击，实现简单 +- 所有主流语言均有成熟实现 + +### 4. 区块链选择建议 + +| 场景 | 推荐 | 理由 | +|------|------|------| +| 开发/测试 | 本地 Hardhat 私链 | 零成本、完全可控 | +| 企业联盟 | Hyperledger Fabric / 联盟链 | 隐私、可审计 | +| 公网生产 | Ethereum L2（Arbitrum/Optimism） | 低 Gas 成本、继承 L1 安全 | +| 高频场景 | Polygon / Solana | 确认快、成本低 | + +--- + +## 附录：关联文档 + +| 文档 | 说明 | 关系 | +|------|------|------| +| [v1 身份草案](../v1/05_identity-protocol-draft.md) | 现有 v1 身份协议草案 | 本次讨论的基础文档 | +| [身份草案 v2](../01-draft/2026-06-29-identity-protocol-v2.md) | 根据本次决议更新的草案 | 基于本次决议生成 | +| [Raw协议](../v1/01_raw-protocol.md) | 原始协议定义 | 签名方案受影响需更新 | +| [v1 索引](../v1/00_index.md) | v1 版本索引 | 版本范围需更新 | + +--- + +## 后续行动 + +| 事项 | 负责人 | 目标版本 | 状态 | +|------|--------|---------|------| +| 更新 Raw 协议签名方案 | - | v1.0 | 待办 | +| 更新身份草案为 v2 版本 | ✅ 已完成 | v1.0 | 完成 | +| 更新 v1 索引文件版本范围 | - | v1.0 | 待办 | +| 起草七大组件规范 | - | v1.1 | 待启动 | +| 起草 DHT 实现规范 | - | v1.1 | 待启动 | +| 链上合约实现 | - | v1.1 | 待启动 | diff --git a/docs/01-draft/2026-06-29-identity-protocol-v2.md b/docs/01-draft/2026-06-29-identity-protocol-v2.md new file mode 100644 index 0000000..65dea62 --- /dev/null +++ b/docs/01-draft/2026-06-29-identity-protocol-v2.md @@ -0,0 +1,468 @@ +# 灵隙去中心化身份与寻址协议 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 规范 | 协议层/实现层分离 | diff --git a/docs/implement/capabilities-system.md b/docs/02-guide/capabilities-system.md similarity index 100% rename from docs/implement/capabilities-system.md rename to docs/02-guide/capabilities-system.md diff --git a/docs/implement/components.md b/docs/02-guide/components.md similarity index 100% rename from docs/implement/components.md rename to docs/02-guide/components.md diff --git a/docs/implement/content-system.md b/docs/02-guide/content-system.md similarity index 100% rename from docs/implement/content-system.md rename to docs/02-guide/content-system.md diff --git a/docs/implement/error-codes.md b/docs/02-guide/error-codes.md similarity index 100% rename from docs/implement/error-codes.md rename to docs/02-guide/error-codes.md diff --git a/docs/implement/grpc-transport.md b/docs/02-guide/grpc-transport.md similarity index 100% rename from docs/implement/grpc-transport.md rename to docs/02-guide/grpc-transport.md diff --git a/docs/implement/hil-mechanism.md b/docs/02-guide/hil-mechanism.md similarity index 100% rename from docs/implement/hil-mechanism.md rename to docs/02-guide/hil-mechanism.md diff --git a/docs/implement/message-extensions.md b/docs/02-guide/message-extensions.md similarity index 100% rename from docs/implement/message-extensions.md rename to docs/02-guide/message-extensions.md diff --git a/docs/implement/transport-modes.md b/docs/02-guide/transport-modes.md similarity index 100% rename from docs/implement/transport-modes.md rename to docs/02-guide/transport-modes.md diff --git a/docs/poster/poster-amber.svg b/docs/03-asset/poster-amber.svg similarity index 100% rename from docs/poster/poster-amber.svg rename to docs/03-asset/poster-amber.svg diff --git a/docs/poster/poster-aurora.svg b/docs/03-asset/poster-aurora.svg similarity index 100% rename from docs/poster/poster-aurora.svg rename to docs/03-asset/poster-aurora.svg diff --git a/docs/poster/poster-cyan.svg b/docs/03-asset/poster-cyan.svg similarity index 100% rename from docs/poster/poster-cyan.svg rename to docs/03-asset/poster-cyan.svg diff --git a/docs/poster/poster-emerald.svg b/docs/03-asset/poster-emerald.svg similarity index 100% rename from docs/poster/poster-emerald.svg rename to docs/03-asset/poster-emerald.svg diff --git a/docs/poster/poster-rose.svg b/docs/03-asset/poster-rose.svg similarity index 100% rename from docs/poster/poster-rose.svg rename to docs/03-asset/poster-rose.svg diff --git a/docs/poster/poster-v0.svg b/docs/03-asset/poster-v0.svg similarity index 100% rename from docs/poster/poster-v0.svg rename to docs/03-asset/poster-v0.svg diff --git a/docs/poster/poster-v1-a.svg b/docs/03-asset/poster-v1-a.svg similarity index 100% rename from docs/poster/poster-v1-a.svg rename to docs/03-asset/poster-v1-a.svg diff --git a/docs/poster/poster-v1-b.svg b/docs/03-asset/poster-v1-b.svg similarity index 100% rename from docs/poster/poster-v1-b.svg rename to docs/03-asset/poster-v1-b.svg diff --git a/docs/poster/poster.svg b/docs/03-asset/poster.svg similarity index 100% rename from docs/poster/poster.svg rename to docs/03-asset/poster.svg diff --git a/docs/v1/00_index.md b/docs/v1/00_index.md index 0ea4134..638608a 100644 --- a/docs/v1/00_index.md +++ b/docs/v1/00_index.md @@ -51,16 +51,16 @@ v1 版本文档分为三层： 每个文档对应一个独立的功能模块： -| 文档 | 对应模块 | -|--------------------------------------------------|-----------------------------| -| [components.md](../implement/components.md) | 七大组件层（灵脉/灵玺/灵鉴/灵泊/灵瞰/灵衡/灵枢） | -| [content-system.md](../implement/content-system.md) | 内容类型系统 | -| [capabilities-system.md](../implement/capabilities-system.md) | 能力声明系统 | -| [grpc-transport.md](../implement/grpc-transport.md) | gRPC 传输协议 | -| [hil-mechanism.md](../implement/hil-mechanism.md) | HiL 三级升级机制 | -| [error-codes.md](../implement/error-codes.md) | 数字分段错误码系统 | -| [message-extensions.md](../implement/message-extensions.md) | 消息扩展字段 | -| [transport-modes.md](../implement/transport-modes.md) | 传输模式定义 | +| 文档 | 对应模块 | +|--------------------------------------------------------------|-----------------------------| +| [components.md](../02-guide/components.md) | 七大组件层（灵脉/灵玺/灵鉴/灵泊/灵瞰/灵衡/灵枢） | +| [content-system.md](../02-guide/content-system.md) | 内容类型系统 | +| [capabilities-system.md](../02-guide/capabilities-system.md) | 能力声明系统 | +| [grpc-transport.md](../02-guide/grpc-transport.md) | gRPC 传输协议 | +| [hil-mechanism.md](../02-guide/hil-mechanism.md) | HiL 三级升级机制 | +| [error-codes.md](../02-guide/error-codes.md) | 数字分段错误码系统 | +| [message-extensions.md](../02-guide/message-extensions.md) | 消息扩展字段 | +| [transport-modes.md](../02-guide/transport-modes.md) | 传输模式定义 | --- diff --git a/docs/v1/01_raw-protocol.md b/docs/v1/01_raw-protocol.md index 6c0b10a..9cb755a 100644 --- a/docs/v1/01_raw-protocol.md +++ b/docs/v1/01_raw-protocol.md @@ -16,23 +16,23 @@ ### 2.1 核心功能 -| 功能 | 说明 | -|-----|------| -| 统一消息信封 | 所有协议共用的消息格式 | -| 身份标识 | Agent 端点定义 | -| 时间戳 | 统一时间格式（RFC3339） | -| 消息签名 | HMAC 签名验证机制 | -| 关联机制 | correlation_id / reply_to 消息关联 | -| 协议版本 | 版本标识与兼容性 | +| 功能 | 说明 | +|--------|--------------------------------| +| 统一消息信封 | 所有协议共用的消息格式 | +| 身份标识 | Agent 端点定义 | +| 时间戳 | 统一时间格式（RFC3339） | +| 消息签名 | HMAC 签名验证机制 | +| 关联机制 | correlation_id / reply_to 消息关联 | +| 协议版本 | 版本标识与兼容性 | ### 2.2 扩展功能 -| 功能 | 说明 | -|-----|------| -| 会话关联 | conversation_id 多轮对话关联 | -| 消息存活 | TTL 消息过期机制 | -| 广播标识 | broadcast 广播消息标记 | -| 加密标识 | encrypt 消息加密标记 | +| 功能 | 说明 | +|------|----------------------------| +| 会话关联 | conversation_id 多轮对话关联 | +| 消息存活 | TTL 消息过期机制 | +| 广播标识 | broadcast 广播消息标记 | +| 加密标识 | encrypt 消息加密标记 | | 签名算法 | signature_algorithm 签名算法声明 | --- @@ -43,51 +43,51 @@ 所有协议消息必须使用统一信封格式： -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `id` | string | ✓ | 消息唯一标识（UUID） | -| `version` | string | ✓ | 协议版本（如 "1.0.0"） | -| `type` | string | ✓ | 消息类型（格式：`协议:类型`，如 `p2p:task_request`） | -| `sender` | AgentEndpoint | ✓ | 发送方端点 | -| `receiver` | AgentEndpoint | - | 接收方端点（广播时可为空） | -| `payload` | object | ✓ | 消息载荷（具体结构由消息类型定义） | -| `timestamp` | string | ✓ | 时间戳（RFC3339 格式） | +| 字段 | 类型 | 必填 | 说明 | +|-------------|---------------|:--:|---------------------------------------| +| `id` | string | ✓ | 消息唯一标识（UUID） | +| `version` | string | ✓ | 协议版本（如 "1.0.0"） | +| `type` | string | ✓ | 消息类型（格式：`协议:类型`，如 `p2p:task_request`） | +| `sender` | AgentEndpoint | ✓ | 发送方端点 | +| `receiver` | AgentEndpoint | - | 接收方端点（广播时可为空） | +| `payload` | object | ✓ | 消息载荷（具体结构由消息类型定义） | +| `timestamp` | string | ✓ | 时间戳（RFC3339 格式） | ### 3.2 关联字段 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `correlation_id` | string | - | 关联 ID（用于请求-响应关联） | -| `reply_to` | string | - | 回复的消息 ID | -| `group_id` | string | - | 群组 ID（群组消息必填） | +| 字段 | 类型 | 必填 | 说明 | +|------------------|--------|:--:|------------------| +| `correlation_id` | string | - | 关联 ID（用于请求-响应关联） | +| `reply_to` | string | - | 回复的消息 ID | +| `group_id` | string | - | 群组 ID（群组消息必填） | ### 3.3 安全字段 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `signature` | string | - | HMAC 签名（签名算法由 signature_algorithm 指定） | -| `signature_algorithm` | string | - | 签名算法（默认 "HMAC-SHA256"） | +| 字段 | 类型 | 必填 | 说明 | +|-----------------------|--------|:--:|---------------------------------------| +| `signature` | string | - | HMAC 签名（签名算法由 signature_algorithm 指定） | +| `signature_algorithm` | string | - | 签名算法（默认 "HMAC-SHA256"） | ### 3.4 扩展字段 -| 字段 | 类型 | 说明 | -|------|------|------| -| `conversation_id` | string | 会话 ID（多轮对话关联） | -| `ttl` | integer | 消息存活时间（秒） | -| `broadcast` | boolean | 是否广播消息 | -| `encrypt` | boolean | payload 是否加密 | +| 字段 | 类型 | 说明 | +|-------------------|---------|---------------| +| `conversation_id` | string | 会话 ID（多轮对话关联） | +| `ttl` | integer | 消息存活时间（秒） | +| `broadcast` | boolean | 是否广播消息 | +| `encrypt` | boolean | payload 是否加密 | ### 3.5 Agent 端点 Agent 身份标识结构： -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `agent_id` | string | ✓ | Agent 唯一标识 | -| `agent_name` | string | - | Agent 名称 | -| `system_id` | string | ✓ | 所属系统标识 | -| `endpoint` | string | ✓ | 回调端点 URL | -| `version` | string | - | Agent 版本 | +| 字段 | 类型 | 必填 | 说明 | +|--------------|--------|:--:|------------| +| `agent_id` | string | ✓ | Agent 唯一标识 | +| `agent_name` | string | - | Agent 名称 | +| `system_id` | string | ✓ | 所属系统标识 | +| `endpoint` | string | ✓ | 回调端点 URL | +| `version` | string | - | Agent 版本 | --- @@ -96,6 +96,7 @@ Agent 身份标识结构： ### 4.1 签名算法 支持算法： + - `HMAC-SHA256`（默认） - `HMAC-SHA512` @@ -112,6 +113,7 @@ signature_content = sender_id | receiver_id | timestamp | payload_json ### 4.3 签名验证 接收方必须： + 1. 提取 sender 的认证密钥 2. 使用相同算法重新计算签名 3. 比对签名是否一致 @@ -120,12 +122,12 @@ signature_content = sender_id | receiver_id | timestamp | payload_json ## 5. 协议类型前缀 -| 前缀 | 协议 | 说明 | -|------|------|------| -| `p2p:` | A2A 协议 | 点对点消息 | -| `group:` | A2N 协议 | 群组内消息 | -| `inter_group:` | A2N 协议 | 跨群组消息 | -| `caller:` | P2A 协议 | 外部调用消息 | +| 前缀 | 协议 | 说明 | +|----------------|--------|--------| +| `p2p:` | A2A 协议 | 点对点消息 | +| `group:` | A2N 协议 | 群组内消息 | +| `inter_group:` | A2N 协议 | 跨群组消息 | +| `caller:` | P2A 协议 | 外部调用消息 | --- @@ -134,6 +136,7 @@ signature_content = sender_id | receiver_id | timestamp | payload_json 格式：`协议前缀:消息类型` 示例： + - `p2p:task_request` - A2A 协议的任务请求 - `group:vote` - A2N 协议的投票消息 - `inter_group:escalate` - A2N 协议的跨群组升级 diff --git a/docs/v1/02_a2a-protocol.md b/docs/v1/02_a2a-protocol.md index f9f1f1b..eaedae2 100644 --- a/docs/v1/02_a2a-protocol.md +++ b/docs/v1/02_a2a-protocol.md @@ -13,6 +13,7 @@ A2A 协议定义两个 Agent 之间进行点对点任务协作的规范，包括任务提交、进度同步、信息补全、人类介入、能力发现等核心交互。 **适用场景**： + - 单个任务请求与响应 - 任务状态实时同步 - 任务取消 @@ -20,6 +21,7 @@ A2A 协议定义两个 Agent 之间进行点对点任务协作的规范，包括 - 人类介入决策 **非适用场景**： + - 多 Agent 群组协作（参见 A2N 协议） - 非 Agent 调用方接入（参见 P2A 协议） @@ -29,44 +31,44 @@ A2A 协议定义两个 Agent 之间进行点对点任务协作的规范，包括 ### 2.1 任务管理 -| 功能 | 说明 | -|-----|------| -| 任务提交 | 请求方向执行方提交任务 | -| 任务确认 | 执行方接受任务 | +| 功能 | 说明 | +|------|---------------| +| 任务提交 | 请求方向执行方提交任务 | +| 任务确认 | 执行方接受任务 | | 任务拒绝 | 执行方拒绝任务（附带原因） | -| 任务取消 | 请求方中途取消任务 | -| 任务进度 | 执行方实时上报进度 | -| 任务完成 | 执行方上报成功结果 | -| 任务失败 | 执行方上报失败原因 | +| 任务取消 | 请求方中途取消任务 | +| 任务进度 | 执行方实时上报进度 | +| 任务完成 | 执行方上报成功结果 | +| 任务失败 | 执行方上报失败原因 | ### 2.2 信息补全 -| 功能 | 说明 | -|-----|------| +| 功能 | 说明 | +|------|------------------| | 信息请求 | 执行方发现缺少必要信息时请求补充 | -| 信息提供 | 请求方提供补充信息 | +| 信息提供 | 请求方提供补充信息 | ### 2.3 人类介入（HiL） -| 功能 | 说明 | -|-----|------| -| HiL 请求 | 执行方请求人类决策 | +| 功能 | 说明 | +|--------|-------------| +| HiL 请求 | 执行方请求人类决策 | | HiL 响应 | 请求方返回人类决策结果 | ### 2.4 能力发现 -| 功能 | 说明 | -|-----|------| +| 功能 | 说明 | +|------|----------------| | 能力查询 | 查询对方支持的任务类型和能力 | -| 能力响应 | 返回能力清单 | +| 能力响应 | 返回能力清单 | ### 2.5 保活与确认 -| 功能 | 说明 | -|-----|------| -| 心跳 | 双向心跳保活 | -| ACK | 任务级确认 | -| 消息 ACK | 消息级确认 | +| 功能 | 说明 | +|---------|---------------| +| 心跳 | 双向心跳保活 | +| ACK | 任务级确认 | +| 消息 ACK | 消息级确认 | | 消息 NACK | 消息级否定确认（附带错误） | --- @@ -77,45 +79,45 @@ A2A 协议定义两个 Agent 之间进行点对点任务协作的规范，包括 ### 3.1 任务类消息 -| 消息类型 | 方向 | 说明 | -|---------|------|------| -| `p2p:task_request` | 请求方 → 执行方 | 提交任务请求 | -| `p2p:task_confirm` | 执行方 → 请求方 | 确认接受任务 | -| `p2p:task_reject` | 执行方 → 请求方 | 拒绝任务 | +| 消息类型 | 方向 | 说明 | +|--------------------------|-----------|--------| +| `p2p:task_request` | 请求方 → 执行方 | 提交任务请求 | +| `p2p:task_confirm` | 执行方 → 请求方 | 确认接受任务 | +| `p2p:task_reject` | 执行方 → 请求方 | 拒绝任务 | | `p2p:task_status_update` | 执行方 → 请求方 | 任务进度更新 | -| `p2p:task_complete` | 执行方 → 请求方 | 任务完成 | -| `p2p:task_failed` | 执行方 → 请求方 | 任务失败 | -| `p2p:task_cancel` | 请求方 → 执行方 | 取消任务 | -| `p2p:task_ack` | 双向 | 任务级确认 | +| `p2p:task_complete` | 执行方 → 请求方 | 任务完成 | +| `p2p:task_failed` | 执行方 → 请求方 | 任务失败 | +| `p2p:task_cancel` | 请求方 → 执行方 | 取消任务 | +| `p2p:task_ack` | 双向 | 任务级确认 | ### 3.2 信息类消息 -| 消息类型 | 方向 | 说明 | -|---------|------|------| -| `p2p:task_need_info` | 执行方 → 请求方 | 请求补充信息 | +| 消息类型 | 方向 | 说明 | +|--------------------------|-----------|--------| +| `p2p:task_need_info` | 执行方 → 请求方 | 请求补充信息 | | `p2p:task_info_provided` | 请求方 → 执行方 | 提供补充信息 | ### 3.3 HiL 类消息 -| 消息类型 | 方向 | 说明 | -|---------|------|------| +| 消息类型 | 方向 | 说明 | +|-----------------------|-----------|--------| | `p2p:task_need_human` | 执行方 → 请求方 | 请求人类介入 | -| `p2p:human_decision` | 请求方 → 执行方 | 人类决策结果 | +| `p2p:human_decision` | 请求方 → 执行方 | 人类决策结果 | ### 3.4 能力类消息 -| 消息类型 | 方向 | 说明 | -|---------|------|------| -| `p2p:capability_query` | 双向 | 查询对方能力 | +| 消息类型 | 方向 | 说明 | +|---------------------------|----|--------| +| `p2p:capability_query` | 双向 | 查询对方能力 | | `p2p:capability_response` | 双向 | 返回能力清单 | ### 3.5 保活与确认类消息 -| 消息类型 | 方向 | 说明 | -|---------|------|------| -| `p2p:heartbeat` | 双向 | 心跳保活 | -| `p2p:ack` | 双向 | 通用确认 | -| `p2p:nack` | 双向 | 通用否定确认 | +| 消息类型 | 方向 | 说明 | +|-----------------|----|--------| +| `p2p:heartbeat` | 双向 | 心跳保活 | +| `p2p:ack` | 双向 | 通用确认 | +| `p2p:nack` | 双向 | 通用否定确认 | --- @@ -123,22 +125,22 @@ A2A 协议定义两个 Agent 之间进行点对点任务协作的规范，包括 ### 4.1 状态定义 -| 状态 | 说明 | -|------|------| -| `idle` | 空闲（初始状态） | -| `pending` | 待确认（已发送请求） | -| `confirmed` | 已确认（执行方接受） | -| `executing` | 执行中 | -| `info_needed` | 需要信息 | -| `info_provided` | 信息已提供 | -| `need_human` | 需要人类介入 | -| `human_deciding` | 人类决策中 | -| `human_approved` | 人类已批准 | -| `human_rejected` | 人类已拒绝 | -| `completed` | 已完成（终态） | -| `failed` | 已失败（终态） | -| `cancelled` | 已取消（终态） | -| `rejected` | 已拒绝（终态） | +| 状态 | 说明 | +|------------------|------------| +| `idle` | 空闲（初始状态） | +| `pending` | 待确认（已发送请求） | +| `confirmed` | 已确认（执行方接受） | +| `executing` | 执行中 | +| `info_needed` | 需要信息 | +| `info_provided` | 信息已提供 | +| `need_human` | 需要人类介入 | +| `human_deciding` | 人类决策中 | +| `human_approved` | 人类已批准 | +| `human_rejected` | 人类已拒绝 | +| `completed` | 已完成（终态） | +| `failed` | 已失败（终态） | +| `cancelled` | 已取消（终态） | +| `rejected` | 已拒绝（终态） | ### 4.2 状态流转 @@ -236,86 +238,86 @@ idle → pending → confirmed → executing → completed ### 6.1 task_request 载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_id` | string | ✓ | 任务唯一标识（请求方生成） | -| `task_type` | string | ✓ | 任务类型 | -| `payload` | object | ✓ | 任务参数（结构由 task_type 决定） | -| `priority` | string | - | 优先级：`low`/`normal`/`high`/`urgent` | -| `transport_preferences` | object | - | 传输偏好（回调/轮询等） | +| 字段 | 类型 | 必填 | 说明 | +|-------------------------|--------|:--:|------------------------------------| +| `task_id` | string | ✓ | 任务唯一标识（请求方生成） | +| `task_type` | string | ✓ | 任务类型 | +| `payload` | object | ✓ | 任务参数（结构由 task_type 决定） | +| `priority` | string | - | 优先级：`low`/`normal`/`high`/`urgent` | +| `transport_preferences` | object | - | 传输偏好（回调/轮询等） | ### 6.2 task_confirm 载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_id` | string | ✓ | 任务标识 | -| `estimated_time` | string | - | 预估耗时（如 "30s-2min"） | +| 字段 | 类型 | 必填 | 说明 | +|------------------|--------|:--:|--------------------| +| `task_id` | string | ✓ | 任务标识 | +| `estimated_time` | string | - | 预估耗时（如 "30s-2min"） | ### 6.3 task_reject 载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_id` | string | ✓ | 任务标识 | -| `reason` | object | ✓ | 拒绝原因（含错误码和描述） | +| 字段 | 类型 | 必填 | 说明 | +|-----------|--------|:--:|---------------| +| `task_id` | string | ✓ | 任务标识 | +| `reason` | object | ✓ | 拒绝原因（含错误码和描述） | ### 6.4 task_status_update 载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_id` | string | ✓ | 任务标识 | -| `status` | string | ✓ | 当前状态 | -| `progress` | integer | - | 进度百分比（0-100） | -| `message` | string | - | 状态说明 | -| `eta` | string | - | 预估完成时间 | +| 字段 | 类型 | 必填 | 说明 | +|------------|---------|:--:|--------------| +| `task_id` | string | ✓ | 任务标识 | +| `status` | string | ✓ | 当前状态 | +| `progress` | integer | - | 进度百分比（0-100） | +| `message` | string | - | 状态说明 | +| `eta` | string | - | 预估完成时间 | ### 6.5 task_complete 载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_id` | string | ✓ | 任务标识 | -| `result` | object | ✓ | 任务结果（结构由 task_type 决定） | -| `summary` | string | - | 结果摘要 | -| `metadata` | object | - | 结果元数据 | +| 字段 | 类型 | 必填 | 说明 | +|------------|--------|:--:|------------------------| +| `task_id` | string | ✓ | 任务标识 | +| `result` | object | ✓ | 任务结果（结构由 task_type 决定） | +| `summary` | string | - | 结果摘要 | +| `metadata` | object | - | 结果元数据 | ### 6.6 task_failed 载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_id` | string | ✓ | 任务标识 | -| `error` | object | ✓ | 错误信息（错误码 + 描述 + 详情） | +| 字段 | 类型 | 必填 | 说明 | +|-----------|--------|:--:|---------------------| +| `task_id` | string | ✓ | 任务标识 | +| `error` | object | ✓ | 错误信息（错误码 + 描述 + 详情） | ### 6.7 task_need_info 载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_id` | string | ✓ | 任务标识 | -| `missing_fields` | array | ✓ | 缺失的字段列表 | -| `reason` | string | ✓ | 缺失原因 | +| 字段 | 类型 | 必填 | 说明 | +|------------------|--------|:--:|---------| +| `task_id` | string | ✓ | 任务标识 | +| `missing_fields` | array | ✓ | 缺失的字段列表 | +| `reason` | string | ✓ | 缺失原因 | ### 6.8 task_info_provided 载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_id` | string | ✓ | 任务标识 | -| `provided_info` | object | ✓ | 补充的信息 | +| 字段 | 类型 | 必填 | 说明 | +|-----------------|--------|:--:|-------| +| `task_id` | string | ✓ | 任务标识 | +| `provided_info` | object | ✓ | 补充的信息 | ### 6.9 task_need_human 载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_id` | string | ✓ | 任务标识 | -| `escalation_level` | integer | ✓ | 升级级别（1/2/3） | -| `reason` | object | ✓ | 介入原因 | -| `options` | array | - | 可选方案列表 | -| `suggested_value` | object | - | Agent 建议值 | +| 字段 | 类型 | 必填 | 说明 | +|--------------------|---------|:--:|-------------| +| `task_id` | string | ✓ | 任务标识 | +| `escalation_level` | integer | ✓ | 升级级别（1/2/3） | +| `reason` | object | ✓ | 介入原因 | +| `options` | array | - | 可选方案列表 | +| `suggested_value` | object | - | Agent 建议值 | ### 6.10 human_decision 载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_id` | string | ✓ | 任务标识 | -| `decision` | object | ✓ | 决策内容 | -| `decided_by` | object | ✓ | 决策者信息（用户 ID + 角色） | +| 字段 | 类型 | 必填 | 说明 | +|--------------|--------|:--:|-------------------| +| `task_id` | string | ✓ | 任务标识 | +| `decision` | object | ✓ | 决策内容 | +| `decided_by` | object | ✓ | 决策者信息（用户 ID + 角色） | --- @@ -323,8 +325,8 @@ idle → pending → confirmed → executing → completed 参见数字分段错误码系统（1000-9999）： -| 分段 | 类别 | -|------|------| +| 分段 | 类别 | +|-----------|------| | 1000-1999 | 系统错误 | | 2000-2999 | 任务错误 | | 3000-3999 | 信息错误 | @@ -338,12 +340,12 @@ idle → pending → confirmed → executing → completed Agent 实现 A2A 协议时必须提供： -| 接口 | 说明 | -|------|------| +| 接口 | 说明 | +|-------|------------------| | 消息处理器 | 接收并处理 p2p:* 类型消息 | -| 任务处理器 | 执行具体任务逻辑 | -| 回调发送器 | 发送进度、完成、失败等回调 | -| 状态查询 | 支持任务状态查询 | +| 任务处理器 | 执行具体任务逻辑 | +| 回调发送器 | 发送进度、完成、失败等回调 | +| 状态查询 | 支持任务状态查询 | --- diff --git a/docs/v1/03_a2n-protocol.md b/docs/v1/03_a2n-protocol.md index 7a649be..b83458c 100644 --- a/docs/v1/03_a2n-protocol.md +++ b/docs/v1/03_a2n-protocol.md @@ -13,6 +13,7 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范，包括群组管理、任务拆分与合并、群体决策、角色与权限、升级机制等。 **适用场景**： + - 复杂任务的拆分与并行执行（MapReduce 模式） - 多 Agent 协同完成单一目标 - 群体投票与共识决策 @@ -20,6 +21,7 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范，包括群 - 分级升级机制 **依赖关系**： + - 群组内成员间的单播通信复用 A2A 协议 --- @@ -28,53 +30,53 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范，包括群 ### 2.1 群组管理 -| 功能 | 说明 | -|-----|------| -| 群组创建 | Coordinator 创建群组，定义拓扑结构 | -| 群组解散 | Coordinator 解散群组 | -| 加入群组 | Agent 主动申请加入 | -| 离开群组 | 成员主动离开 | -| 邀请加入 | Coordinator 或成员邀请其他 Agent | -| 接受邀请 | 被邀请者接受邀请 | -| 拒绝邀请 | 被邀请者拒绝邀请 | -| 成员更新通知 | 成员变动时广播通知 | -| 角色变更 | Coordinator 调整成员角色 | -| 群组冻结 | 暂停群组活动 | -| 群组解冻 | 恢复群组活动 | +| 功能 | 说明 | +|--------|---------------------------| +| 群组创建 | Coordinator 创建群组，定义拓扑结构 | +| 群组解散 | Coordinator 解散群组 | +| 加入群组 | Agent 主动申请加入 | +| 离开群组 | 成员主动离开 | +| 邀请加入 | Coordinator 或成员邀请其他 Agent | +| 接受邀请 | 被邀请者接受邀请 | +| 拒绝邀请 | 被邀请者拒绝邀请 | +| 成员更新通知 | 成员变动时广播通知 | +| 角色变更 | Coordinator 调整成员角色 | +| 群组冻结 | 暂停群组活动 | +| 群组解冻 | 恢复群组活动 | ### 2.2 群组通信 -| 功能 | 说明 | -|-----|------| -| 广播 | 发送给所有成员 | -| 组播 | 发送给指定成员列表 | -| 单播 | 群内点对点（复用 A2A） | -| 消息中继 | 通过其他成员转发消息 | +| 功能 | 说明 | +|------|---------------| +| 广播 | 发送给所有成员 | +| 组播 | 发送给指定成员列表 | +| 单播 | 群内点对点（复用 A2A） | +| 消息中继 | 通过其他成员转发消息 | ### 2.3 任务协作 -| 功能 | 说明 | -|-----|------| -| 任务拆分 | Coordinator 将大任务拆分为子任务 | -| 任务分配 | 子任务分配给指定 Worker | -| 子任务进度 | Worker 上报子任务进度 | -| 结果合并 | Coordinator 合并子任务结果 | +| 功能 | 说明 | +|-------|------------------------| +| 任务拆分 | Coordinator 将大任务拆分为子任务 | +| 任务分配 | 子任务分配给指定 Worker | +| 子任务进度 | Worker 上报子任务进度 | +| 结果合并 | Coordinator 合并子任务结果 | ### 2.4 共识投票 -| 功能 | 说明 | -|-----|------| +| 功能 | 说明 | +|------|-----------------------------| | 发起投票 | Coordinator 或 Reviewer 发起投票 | -| 提交投票 | 成员提交选项及理由 | -| 达成共识 | 公布投票结果 | +| 提交投票 | 成员提交选项及理由 | +| 达成共识 | 公布投票结果 | ### 2.5 升级机制 -| 功能 | 说明 | -|-----|------| -| 共识僵局升级 | 投票无法达成共识时升级给人类 | -| 子任务阻塞升级 | 子任务阻塞时升级给人类 | -| 跨群组升级 | 升级到更高层级群组 | +| 功能 | 说明 | +|---------|----------------| +| 共识僵局升级 | 投票无法达成共识时升级给人类 | +| 子任务阻塞升级 | 子任务阻塞时升级给人类 | +| 跨群组升级 | 升级到更高层级群组 | --- @@ -82,52 +84,52 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范，包括群 ### 3.1 群组管理消息（前缀 `group:`） -| 消息类型 | 说明 | -|---------|------| -| `group:create` | 创建群组 | -| `group:disband` | 解散群组 | -| `group:join` | 加入群组 | -| `group:leave` | 离开群组 | -| `group:invite` | 邀请加入 | -| `group:accept_invite` | 接受邀请 | -| `group:reject_invite` | 拒绝邀请 | +| 消息类型 | 说明 | +|-----------------------|--------| +| `group:create` | 创建群组 | +| `group:disband` | 解散群组 | +| `group:join` | 加入群组 | +| `group:leave` | 离开群组 | +| `group:invite` | 邀请加入 | +| `group:accept_invite` | 接受邀请 | +| `group:reject_invite` | 拒绝邀请 | | `group:member_update` | 成员更新通知 | -| `group:role_change` | 角色变更 | +| `group:role_change` | 角色变更 | ### 3.2 群组通信消息（前缀 `group:`） -| 消息类型 | 说明 | -|---------|------| +| 消息类型 | 说明 | +|-------------------|----------| | `group:broadcast` | 广播（所有成员） | | `group:multicast` | 组播（指定成员） | -| `group:direct` | 群内单播 | -| `group:relay` | 消息中继 | +| `group:direct` | 群内单播 | +| `group:relay` | 消息中继 | ### 3.3 任务协作消息（前缀 `group:`） -| 消息类型 | 说明 | -|---------|------| -| `group:task_split` | 任务拆分 | -| `group:task_assign` | 任务分配 | -| `group:task_merge` | 结果合并 | +| 消息类型 | 说明 | +|-----------------------|-------| +| `group:task_split` | 任务拆分 | +| `group:task_assign` | 任务分配 | +| `group:task_merge` | 结果合并 | | `group:task_progress` | 子任务进度 | ### 3.4 共识投票消息（前缀 `group:`） -| 消息类型 | 说明 | -|---------|------| -| `group:vote` | 发起投票 | +| 消息类型 | 说明 | +|---------------------|------| +| `group:vote` | 发起投票 | | `group:vote_submit` | 提交投票 | -| `group:consensus` | 达成共识 | +| `group:consensus` | 达成共识 | ### 3.5 HiL 升级消息（前缀 `group:` / `inter_group:`） -| 消息类型 | 说明 | -|---------|------| -| `group:consensus_escalate` | 共识僵局升级给人类 | -| `group:subtask_escalate` | 子任务阻塞升级给人类 | -| `group:human_decision` | 人类决策结果 | -| `inter_group:escalate` | 跨群组升级 | +| 消息类型 | 说明 | +|----------------------------|------------| +| `group:consensus_escalate` | 共识僵局升级给人类 | +| `group:subtask_escalate` | 子任务阻塞升级给人类 | +| `group:human_decision` | 人类决策结果 | +| `inter_group:escalate` | 跨群组升级 | --- @@ -135,49 +137,49 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范，包括群 ### 4.1 群组拓扑结构 -| 拓扑类型 | 说明 | 适用场景 | -|---------|------|---------| -| `star` | 星型，中心 coordinator 协调 | 简单任务分发 | -| `mesh` | 网状，成员间可直接通信 | 对等协作 | -| `chain` | 链式，流水线模式 | 顺序处理 | -| `hierarchical` | 层级型，多层管理 | 大型复杂任务 | -| `fullmesh` | 全连接网状 | 高可靠协作 | +| 拓扑类型 | 说明 | 适用场景 | +|----------------|----------------------|--------| +| `star` | 星型，中心 coordinator 协调 | 简单任务分发 | +| `mesh` | 网状，成员间可直接通信 | 对等协作 | +| `chain` | 链式，流水线模式 | 顺序处理 | +| `hierarchical` | 层级型，多层管理 | 大型复杂任务 | +| `fullmesh` | 全连接网状 | 高可靠协作 | ### 4.2 成员角色 -| 角色 | 说明 | 权限 | -|------|------|------| +| 角色 | 说明 | 权限 | +|---------------|-----|------------------------| | `coordinator` | 协调者 | 创建/解散群组、任务拆分、发起投票、角色变更 | -| `worker` | 工作者 | 执行子任务、提交结果、投票 | -| `reviewer` | 审核者 | 审核结果、发起投票、升级请求 | -| `observer` | 观察者 | 只读，查看进度 | +| `worker` | 工作者 | 执行子任务、提交结果、投票 | +| `reviewer` | 审核者 | 审核结果、发起投票、升级请求 | +| `observer` | 观察者 | 只读，查看进度 | ### 4.3 群组状态 -| 状态 | 说明 | -|------|------| -| `creating` | 创建中 | -| `active` | 活跃 | -| `frozen` | 冻结（不可执行新任务） | -| `disbanded` | 已解散（终态） | +| 状态 | 说明 | +|-------------|-------------| +| `creating` | 创建中 | +| `active` | 活跃 | +| `frozen` | 冻结（不可执行新任务） | +| `disbanded` | 已解散（终态） | ### 4.4 合并策略 -| 策略 | 说明 | -|------|------| +| 策略 | 说明 | +|-----------------|-----------| | `first_success` | 首个成功结果即返回 | -| `majority` | 多数结果合并 | -| `weighted` | 按权重加权合并 | -| `custom` | 自定义合并逻辑 | +| `majority` | 多数结果合并 | +| `weighted` | 按权重加权合并 | +| `custom` | 自定义合并逻辑 | ### 4.5 共识类型 -| 类型 | 说明 | -|------|------| -| `majority` | 多数投票（>50%） | +| 类型 | 说明 | +|-----------------|------------| +| `majority` | 多数投票（>50%） | | `supermajority` | 绝对多数（>67%） | -| `unanimity` | 一致同意（100%） | -| `weighted` | 加权投票 | +| `unanimity` | 一致同意（100%） | +| `weighted` | 加权投票 | --- @@ -245,20 +247,20 @@ Coordinator 所有成员 ### 6.2 流程步骤 1. **任务拆分阶段** - - Coordinator 接收原始任务 - - 将任务拆分为多个子任务 - - 为每个子任务指定执行的 Worker - - 定义合并策略 + - Coordinator 接收原始任务 + - 将任务拆分为多个子任务 + - 为每个子任务指定执行的 Worker + - 定义合并策略 2. **并行执行阶段** - - 各 Worker 并行执行子任务 - - 定期上报进度 - - 子任务完成后上报结果 + - 各 Worker 并行执行子任务 + - 定期上报进度 + - 子任务完成后上报结果 3. **结果合并阶段** - - Coordinator 收集所有子任务结果 - - 按合并策略合并结果 - - 返回最终结果 + - Coordinator 收集所有子任务结果 + - 按合并策略合并结果 + - 返回最终结果 --- @@ -280,59 +282,59 @@ Coordinator 所有成员 ### 8.1 群组创建载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `group_id` | string | ✓ | 群组唯一标识 | -| `group_name` | string | - | 群组名称 | -| `topology` | string | ✓ | 拓扑结构 | -| `config` | object | - | 群组配置 | +| 字段 | 类型 | 必填 | 说明 | +|--------------|--------|:--:|--------| +| `group_id` | string | ✓ | 群组唯一标识 | +| `group_name` | string | - | 群组名称 | +| `topology` | string | ✓ | 拓扑结构 | +| `config` | object | - | 群组配置 | ### 8.2 群组配置 -| 字段 | 类型 | 说明 | -|------|------|------| -| `max_members` | integer | 最大成员数 | -| `vote_threshold` | float | 投票阈值 | -| `default_consensus_type` | string | 默认共识类型 | +| 字段 | 类型 | 说明 | +|--------------------------|---------|--------| +| `max_members` | integer | 最大成员数 | +| `vote_threshold` | float | 投票阈值 | +| `default_consensus_type` | string | 默认共识类型 | ### 8.3 子任务结构 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `subtask_id` | string | ✓ | 子任务标识 | -| `description` | string | ✓ | 子任务描述 | -| `assigned_to` | string | ✓ | 执行者 Agent ID | -| `dependencies` | array | - | 依赖的子任务 ID 列表 | -| `status` | string | ✓ | 子任务状态 | -| `payload` | object | ✓ | 子任务参数 | +| 字段 | 类型 | 必填 | 说明 | +|----------------|--------|:--:|--------------| +| `subtask_id` | string | ✓ | 子任务标识 | +| `description` | string | ✓ | 子任务描述 | +| `assigned_to` | string | ✓ | 执行者 Agent ID | +| `dependencies` | array | - | 依赖的子任务 ID 列表 | +| `status` | string | ✓ | 子任务状态 | +| `payload` | object | ✓ | 子任务参数 | ### 8.4 投票载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `vote_id` | string | ✓ | 投票标识 | -| `question` | string | ✓ | 投票问题 | -| `options` | array | ✓ | 选项列表 | -| `consensus_type` | string | ✓ | 共识类型 | -| `deadline` | string | - | 截止时间 | +| 字段 | 类型 | 必填 | 说明 | +|------------------|--------|:--:|------| +| `vote_id` | string | ✓ | 投票标识 | +| `question` | string | ✓ | 投票问题 | +| `options` | array | ✓ | 选项列表 | +| `consensus_type` | string | ✓ | 共识类型 | +| `deadline` | string | - | 截止时间 | ### 8.5 投票提交载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `vote_id` | string | ✓ | 投票标识 | -| `voter_id` | string | ✓ | 投票者 ID | -| `option_id` | string | ✓ | 选择的选项 | -| `reasoning` | string | - | 投票理由 | +| 字段 | 类型 | 必填 | 说明 | +|-------------|--------|:--:|--------| +| `vote_id` | string | ✓ | 投票标识 | +| `voter_id` | string | ✓ | 投票者 ID | +| `option_id` | string | ✓ | 选择的选项 | +| `reasoning` | string | - | 投票理由 | ### 8.6 共识结果载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `vote_id` | string | ✓ | 投票标识 | -| `winner` | string | ✓ | 获胜选项 | -| `vote_counts` | object | ✓ | 各选项票数 | -| `passed` | boolean | ✓ | 是否通过阈值 | +| 字段 | 类型 | 必填 | 说明 | +|---------------|---------|:--:|--------| +| `vote_id` | string | ✓ | 投票标识 | +| `winner` | string | ✓ | 获胜选项 | +| `vote_counts` | object | ✓ | 各选项票数 | +| `passed` | boolean | ✓ | 是否通过阈值 | --- @@ -340,21 +342,21 @@ Coordinator 所有成员 ### 9.1 升级场景 -| 场景 | 消息类型 | 说明 | -|------|---------|------| -| 共识僵局 | `group:consensus_escalate` | 投票超时未达成共识 | -| 子任务阻塞 | `group:subtask_escalate` | 子任务执行受阻 | -| 跨群组 | `inter_group:escalate` | 升级到上级群组 | +| 场景 | 消息类型 | 说明 | +|-------|----------------------------|-----------| +| 共识僵局 | `group:consensus_escalate` | 投票超时未达成共识 | +| 子任务阻塞 | `group:subtask_escalate` | 子任务执行受阻 | +| 跨群组 | `inter_group:escalate` | 升级到上级群组 | ### 9.2 升级载荷 -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `escalation_id` | string | ✓ | 升级标识 | -| `escalation_type` | string | ✓ | 升级类型 | -| `escalation_level` | integer | ✓ | 升级级别（1/2/3） | -| `context` | object | ✓ | 升级上下文 | -| `options` | array | - | 可选方案 | +| 字段 | 类型 | 必填 | 说明 | +|--------------------|---------|:--:|-------------| +| `escalation_id` | string | ✓ | 升级标识 | +| `escalation_type` | string | ✓ | 升级类型 | +| `escalation_level` | integer | ✓ | 升级级别（1/2/3） | +| `context` | object | ✓ | 升级上下文 | +| `options` | array | - | 可选方案 | --- @@ -362,16 +364,16 @@ Coordinator 所有成员 群组错误码分段：7000-7999 -| 错误码 | 名称 | 说明 | -|------|------|------| -| 7001 | 群组不存在 | | -| 7002 | 群组未激活 | | -| 7003 | 成员不存在 | | -| 7004 | 不是群组成员 | | -| 7005 | 未达成共识 | | -| 7006 | 角色不存在 | | -| 7007 | 已是成员 | | -| 7008 | 群组已满 | | +| 错误码 | 名称 | 说明 | +|------|--------|----| +| 7001 | 群组不存在 | | +| 7002 | 群组未激活 | | +| 7003 | 成员不存在 | | +| 7004 | 不是群组成员 | | +| 7005 | 未达成共识 | | +| 7006 | 角色不存在 | | +| 7007 | 已是成员 | | +| 7008 | 群组已满 | | --- @@ -379,12 +381,12 @@ Coordinator 所有成员 Agent 实现 A2N 协议时必须提供： -| 接口 | 说明 | -|------|------| +| 接口 | 说明 | +|---------|---------------| | 群组管理处理器 | 处理群组创建、加入、离开等 | -| 子任务处理器 | 执行分配的子任务 | -| 投票处理器 | 处理投票相关消息 | -| 升级处理器 | 处理升级请求 | +| 子任务处理器 | 执行分配的子任务 | +| 投票处理器 | 处理投票相关消息 | +| 升级处理器 | 处理升级请求 | --- diff --git a/docs/v1/04_p2a-protocol.md b/docs/v1/04_p2a-protocol.md index 76cd89a..98ae77f 100644 --- a/docs/v1/04_p2a-protocol.md +++ b/docs/v1/04_p2a-protocol.md @@ -15,12 +15,14 @@ P2A 协议定义**非 Agent 调用方**（如普通后端服务、前端应用 本协议将 A2A 协议的复杂性封装起来，提供简洁的 RESTful API，使调用方无需了解 A2A 协议细节即可使用 Agent 能力。 **适用场景**： + - 前端应用直接调用 Agent 能力 - 后端业务系统集成 Agent 服务 - 第三方开发者通过 API 接入 - 无需实现完整 A2A 协议的调用方 **设计原则**： + - **简单易用**：标准 RESTful API，JSON 格式 - **两种模式**：回调模式 + 轮询模式，调用方按需选择 - **认证简单**：API Key 认证，无需 HMAC 签名 @@ -33,44 +35,44 @@ P2A 协议定义**非 Agent 调用方**（如普通后端服务、前端应用 ### 2.1 任务提交 -| 功能 | 说明 | -|-----|------| -| JSON 提交 | application/json 格式提交任务 | -| Multipart 提交 | 带文件上传的任务提交 | +| 功能 | 说明 | +|--------------|-------------------------| +| JSON 提交 | application/json 格式提交任务 | +| Multipart 提交 | 带文件上传的任务提交 | ### 2.2 任务查询 -| 功能 | 说明 | -|-----|------| +| 功能 | 说明 | +|------|---------------| | 任务详情 | 获取完整任务信息（含结果） | -| 任务状态 | 简化版状态查询 | -| 任务列表 | 分页查询任务列表 | +| 任务状态 | 简化版状态查询 | +| 任务列表 | 分页查询任务列表 | ### 2.3 任务控制 -| 功能 | 说明 | -|-----|------| +| 功能 | 说明 | +|------|-----------| | 任务取消 | 取消正在执行的任务 | ### 2.4 能力查询 -| 功能 | 说明 | -|-----|------| +| 功能 | 说明 | +|------|------------------| | 能力清单 | 获取 Agent 支持的任务类型 | ### 2.5 通知机制 -| 功能 | 说明 | -|-----|------| +| 功能 | 说明 | +|------|--------------| | 回调通知 | 任务完成后主动回调调用方 | -| 轮询查询 | 调用方主动查询状态 | +| 轮询查询 | 调用方主动查询状态 | ### 2.6 认证 -| 功能 | 说明 | -|-----|------| -| API Key 认证 | X-API-Key 头部认证 | -| 回调验证 | X-Callback-Token 验证回调来源 | +| 功能 | 说明 | +|------------|-------------------------| +| API Key 认证 | X-API-Key 头部认证 | +| 回调验证 | X-Callback-Token 验证回调来源 | --- @@ -80,15 +82,15 @@ P2A 协议定义**非 Agent 调用方**（如普通后端服务、前端应用 ### 3.1 端点清单 -| 方法 | 路径 | 说明 | -|------|------|------| -| POST | `/task` | 提交任务（JSON） | -| POST | `/task/multipart` | 提交任务（带文件上传） | -| GET | `/task/{task_id}` | 获取任务详情 | -| GET | `/task/{task_id}/status` | 获取任务状态（简化版） | -| GET | `/tasks` | 获取任务列表 | -| POST | `/task/{task_id}/cancel` | 取消任务 | -| GET | `/capabilities` | 获取能力清单 | +| 方法 | 路径 | 说明 | +|------|--------------------------|-------------| +| POST | `/task` | 提交任务（JSON） | +| POST | `/task/multipart` | 提交任务（带文件上传） | +| GET | `/task/{task_id}` | 获取任务详情 | +| GET | `/task/{task_id}/status` | 获取任务状态（简化版） | +| GET | `/tasks` | 获取任务列表 | +| POST | `/task/{task_id}/cancel` | 取消任务 | +| GET | `/capabilities` | 获取能力清单 | --- @@ -96,13 +98,13 @@ P2A 协议定义**非 Agent 调用方**（如普通后端服务、前端应用 P2A 协议使用简化状态（5 种）： -| 状态 | 说明 | -|------|------| -| `received` | 已接收 | -| `processing` | 处理中 | -| `completed` | 已完成（终态） | -| `failed` | 已失败（终态） | -| `cancelled` | 已取消（终态） | +| 状态 | 说明 | +|--------------|---------| +| `received` | 已接收 | +| `processing` | 处理中 | +| `completed` | 已完成（终态） | +| `failed` | 已失败（终态） | +| `cancelled` | 已取消（终态） | 状态流转： @@ -119,6 +121,7 @@ received → processing → completed ### 5.1 API Key 认证 传递方式： + - HTTP Header：`X-API-Key: {api_key}` - URL Query：`?api_key={api_key}` @@ -134,26 +137,26 @@ received → processing → completed ### 6.1 任务提交请求（JSON） -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_type` | string | ✓ | 任务类型（如 `text_generation`） | -| `payload` | object | ✓ | 任务参数（结构由 task_type 决定） | -| `external_task_id` | string | - | 调用方的任务 ID，用于关联 | -| `priority` | string | - | 优先级：`low`/`normal`/`high`/`urgent`，默认 `normal` | -| `callback_url` | string | - | 回调 URL，不提供则需轮询 | -| `callback_token` | string | - | 回调验证 token | +| 字段 | 类型 | 必填 | 说明 | +|--------------------|--------|:--:|------------------------------------------------| +| `task_type` | string | ✓ | 任务类型（如 `text_generation`） | +| `payload` | object | ✓ | 任务参数（结构由 task_type 决定） | +| `external_task_id` | string | - | 调用方的任务 ID，用于关联 | +| `priority` | string | - | 优先级：`low`/`normal`/`high`/`urgent`，默认 `normal` | +| `callback_url` | string | - | 回调 URL，不提供则需轮询 | +| `callback_token` | string | - | 回调验证 token | ### 6.2 任务提交请求（Multipart） -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `task_type` | string | ✓ | 任务类型 | -| `payload` | string(JSON) | ✓ | 任务参数（JSON 字符串） | -| `external_task_id` | string | - | 外部任务 ID | -| `priority` | string | - | 优先级 | -| `callback_url` | string | - | 回调 URL | -| `callback_token` | string | - | 回调 token | -| `file` | file | - | 上传的文件（可多个） | +| 字段 | 类型 | 必填 | 说明 | +|--------------------|--------------|:--:|----------------| +| `task_type` | string | ✓ | 任务类型 | +| `payload` | string(JSON) | ✓ | 任务参数（JSON 字符串） | +| `external_task_id` | string | - | 外部任务 ID | +| `priority` | string | - | 优先级 | +| `callback_url` | string | - | 回调 URL | +| `callback_token` | string | - | 回调 token | +| `file` | file | - | 上传的文件（可多个） | --- @@ -161,77 +164,77 @@ received → processing → completed ### 7.1 任务提交响应 -| 字段 | 类型 | 说明 | -|------|------|------| -| `success` | boolean | 是否成功 | -| `task_id` | string | 服务端生成的任务 ID | -| `status` | string | 初始状态（通常为 `received`） | -| `message` | string | 提示信息 | -| `error` | object | 错误信息（失败时） | +| 字段 | 类型 | 说明 | +|-----------|---------|----------------------| +| `success` | boolean | 是否成功 | +| `task_id` | string | 服务端生成的任务 ID | +| `status` | string | 初始状态（通常为 `received`） | +| `message` | string | 提示信息 | +| `error` | object | 错误信息（失败时） | ### 7.2 任务详情响应 -| 字段 | 类型 | 说明 | -|------|------|------| +| 字段 | 类型 | 说明 | +|-----------|---------|------| | `success` | boolean | 是否成功 | -| `task` | object | 任务详情 | -| `error` | object | 错误信息 | +| `task` | object | 任务详情 | +| `error` | object | 错误信息 | ### 7.3 任务详情结构 -| 字段 | 类型 | 说明 | -|------|------|------| -| `id` | string | 任务 ID | -| `type` | string | 任务类型 | -| `status` | string | 任务状态 | -| `progress` | integer | 进度百分比（0-100） | -| `message` | string | 状态说明 | -| `created_at` | string | 创建时间（RFC3339） | -| `updated_at` | string | 更新时间（RFC3339） | -| `completed_at` | string | 完成时间（RFC3339） | -| `eta` | string | 预估完成时间 | -| `result` | object | 任务结果（结构由 task_type 决定） | -| `error` | object | 错误信息 | +| 字段 | 类型 | 说明 | +|----------------|---------|------------------------| +| `id` | string | 任务 ID | +| `type` | string | 任务类型 | +| `status` | string | 任务状态 | +| `progress` | integer | 进度百分比（0-100） | +| `message` | string | 状态说明 | +| `created_at` | string | 创建时间（RFC3339） | +| `updated_at` | string | 更新时间（RFC3339） | +| `completed_at` | string | 完成时间（RFC3339） | +| `eta` | string | 预估完成时间 | +| `result` | object | 任务结果（结构由 task_type 决定） | +| `error` | object | 错误信息 | ### 7.4 任务列表响应 -| 字段 | 类型 | 说明 | -|------|------|------| -| `success` | boolean | 是否成功 | -| `tasks` | array | 任务列表 | -| `total` | integer | 总数 | -| `limit` | integer | 每页数量 | -| `offset` | integer | 偏移量 | +| 字段 | 类型 | 说明 | +|------------|---------|-------| +| `success` | boolean | 是否成功 | +| `tasks` | array | 任务列表 | +| `total` | integer | 总数 | +| `limit` | integer | 每页数量 | +| `offset` | integer | 偏移量 | | `has_more` | boolean | 是否有更多 | ### 7.5 能力清单响应 -| 字段 | 类型 | 说明 | -|------|------|------| -| `agent_id` | string | Agent 唯一标识 | -| `agent_name` | string | Agent 名称 | -| `protocol_version` | string | 协议版本 | -| `supported_task_types` | array | 支持的任务类型列表 | -| `supported_content_types` | array | 支持的内容类型 | -| `max_file_size` | integer | 最大文件大小（字节） | -| `max_concurrent_tasks` | integer | 最大并发任务数 | -| `max_task_duration` | integer | 最大任务时长（秒） | -| `support_progress_updates` | boolean | 是否支持进度更新 | -| `support_streaming` | boolean | 是否支持流式传输 | -| `support_hil` | boolean | 是否支持人类介入 | -| `support_groups` | boolean | 是否支持群组协作 | +| 字段 | 类型 | 说明 | +|----------------------------|---------|------------| +| `agent_id` | string | Agent 唯一标识 | +| `agent_name` | string | Agent 名称 | +| `protocol_version` | string | 协议版本 | +| `supported_task_types` | array | 支持的任务类型列表 | +| `supported_content_types` | array | 支持的内容类型 | +| `max_file_size` | integer | 最大文件大小（字节） | +| `max_concurrent_tasks` | integer | 最大并发任务数 | +| `max_task_duration` | integer | 最大任务时长（秒） | +| `support_progress_updates` | boolean | 是否支持进度更新 | +| `support_streaming` | boolean | 是否支持流式传输 | +| `support_hil` | boolean | 是否支持人类介入 | +| `support_groups` | boolean | 是否支持群组协作 | ### 7.6 任务类型能力 -| 字段 | 类型 | 说明 | -|------|------|------| -| `type` | string | 任务类型标识 | -| `name` | string | 任务类型名称 | -| `description` | string | 描述 | +| 字段 | 类型 | 说明 | +|------------------|--------|--------------------| +| `type` | string | 任务类型标识 | +| `name` | string | 任务类型名称 | +| `description` | string | 描述 | | `estimated_time` | string | 预估耗时（如 "30s-2min"） | -| `input_schema` | string | 输入 Schema | -| `output_schema` | string | 输出 Schema | -| `capabilities` | array | 所需能力列表 | +| `input_schema` | string | 输入 Schema | +| `output_schema` | string | 输出 Schema | +| `capabilities` | array | 所需能力列表 | --- @@ -241,40 +244,40 @@ received → processing → completed 当任务完成时，服务端向调用方提供的 `callback_url` 发送回调： -| 字段 | 类型 | 说明 | -|------|------|------| -| `task_id` | string | 任务 ID | -| `external_task_id` | string | 外部任务 ID（如有） | -| `status` | string | 任务状态 | -| `progress` | integer | 进度 | -| `result` | object | 任务结果 | -| `error` | object | 错误信息 | -| `timestamp` | string | 时间戳（RFC3339） | +| 字段 | 类型 | 说明 | +|--------------------|---------|--------------| +| `task_id` | string | 任务 ID | +| `external_task_id` | string | 外部任务 ID（如有） | +| `status` | string | 任务状态 | +| `progress` | integer | 进度 | +| `result` | object | 任务结果 | +| `error` | object | 错误信息 | +| `timestamp` | string | 时间戳（RFC3339） | ### 8.2 回调 Header -| Header | 说明 | -|--------|------| +| Header | 说明 | +|--------------------|------------------------------------| | `X-Callback-Token` | 回调验证 token（如调用方提供了 callback_token） | -| `Content-Type` | `application/json` | +| `Content-Type` | `application/json` | --- ## 9. 错误响应结构 -| 字段 | 类型 | 说明 | -|------|------|------| +| 字段 | 类型 | 说明 | +|-----------|---------|-------| | `success` | boolean | false | -| `error` | object | 错误详情 | +| `error` | object | 错误详情 | 错误详情结构： -| 字段 | 类型 | 说明 | -|------|------|------| -| `code` | integer | 数字错误码 | -| `category` | string | 错误类别 | -| `message` | string | 错误描述 | -| `details` | object | 详细信息 | +| 字段 | 类型 | 说明 | +|---------------|---------|-----------| +| `code` | integer | 数字错误码 | +| `category` | string | 错误类别 | +| `message` | string | 错误描述 | +| `details` | object | 详细信息 | | `retry_after` | integer | 重试等待时间（秒） | --- @@ -284,6 +287,7 @@ received → processing → completed ### 10.1 回调模式 调用方提供 `callback_url`： + - 任务状态变化时主动回调 - 无需轮询 - 适用于实时性要求高的场景 @@ -291,6 +295,7 @@ received → processing → completed ### 10.2 轮询模式 调用方不提供 `callback_url`： + - 需主动调用 `/task/{task_id}/status` 查询 - 适用于无法接收回调的场景 - 推荐轮询间隔：5-10 秒 @@ -298,6 +303,7 @@ received → processing → completed ### 10.3 混合模式 调用方提供 `callback_url`，同时支持轮询： + - 回调为主，轮询兜底 - 适用于高可靠性场景 @@ -311,13 +317,13 @@ received → processing → completed P2A 协议是 A2A 协议的"简化入口"： -| P2A API | A2A 消息映射 | -|---------|-------------| -| POST `/task` | `p2p:task_request` | -| GET `/task/{id}` | 内部状态查询 | -| POST `/task/{id}/cancel` | `p2p:task_cancel` | -| GET `/capabilities` | `p2p:capability_query` + `p2p:capability_response` | -| 回调发送 | `p2p:task_complete` / `p2p:task_failed` 等 | +| P2A API | A2A 消息映射 | +|--------------------------|----------------------------------------------------| +| POST `/task` | `p2p:task_request` | +| GET `/task/{id}` | 内部状态查询 | +| POST `/task/{id}/cancel` | `p2p:task_cancel` | +| GET `/capabilities` | `p2p:capability_query` + `p2p:capability_response` | +| 回调发送 | `p2p:task_complete` / `p2p:task_failed` 等 | --- @@ -325,11 +331,11 @@ P2A 协议是 A2A 协议的"简化入口"： 实现 P2A 协议的服务端必须提供： -| 接口 | 说明 | -|------|------| -| 任务接收端点 | 接收任务提交请求 | -| 任务查询端点 | 提供任务状态和结果查询 | -| 任务取消端点 | 支持任务取消 | -| 能力查询端点 | 提供能力清单 | -| 回调发送器 | 支持向调用方回调 | +| 接口 | 说明 | +|---------|--------------------| +| 任务接收端点 | 接收任务提交请求 | +| 任务查询端点 | 提供任务状态和结果查询 | +| 任务取消端点 | 支持任务取消 | +| 能力查询端点 | 提供能力清单 | +| 回调发送器 | 支持向调用方回调 | | A2A 转换器 | 将 P2A 请求转换为 A2A 消息 | \ No newline at end of file diff --git a/docs/v1/05_identity-protocol-draft.md b/docs/v1/05_identity-protocol-draft.md index ddd9e46..4ac682c 100644 --- a/docs/v1/05_identity-protocol-draft.md +++ b/docs/v1/05_identity-protocol-draft.md @@ -18,6 +18,7 @@ ### 1.1 问题陈述 现有协议假设存在中心化的注册表（如灵脉 Meridian），但在以下场景中： + - 临时 P2P 网络 - 跨组织协作 - 离线/断网环境 @@ -27,13 +28,13 @@ ### 1.2 设计目标 -| 目标 | 说明 | -|-----|------| +| 目标 | 说明 | +|-------|-----------------| | 身份可验证 | AgentID 无法伪造或冒用 | -| 去中心化 | 无需中心化注册表 | -| 高可用 | 无单点故障 | -| 可扩展 | 支持大规模 Agent 网络 | -| 可读性 | 支持人类可读别名（可选） | +| 去中心化 | 无需中心化注册表 | +| 高可用 | 无单点故障 | +| 可扩展 | 支持大规模 Agent 网络 | +| 可读性 | 支持人类可读别名（可选） | --- @@ -52,41 +53,41 @@ AgentID = {namespace}:{key_hash}:{alias} did:synapse:abc123def456:chat-bot ``` -| 部分 | 格式 | 说明 | -|------|------|------| -| namespace | string | 命名空间（如 `synapse`） | -| key_hash | base58 | 公钥哈希的前 16 字节 | -| alias | string（可选） | 人类可读别名 | +| 部分 | 格式 | 说明 | +|-----------|------------|-------------------| +| namespace | string | 命名空间（如 `synapse`） | +| key_hash | base58 | 公钥哈希的前 16 字节 | +| alias | string（可选） | 人类可读别名 | ### 2.2 生成算法 ```go func GenerateAgentID(privateKey []byte, namespace string, alias string) string { - // 1. 从私钥派生公钥 - publicKey := crypto.GeneratePublicKey(privateKey) - - // 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) +// 1. 从私钥派生公钥 +publicKey := crypto.GeneratePublicKey(privateKey) + +// 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.3 ID 特性 -| 特性 | 说明 | -|------|------| -| 唯一性 | 相同公钥 → 相同 key_hash → 相同 AgentID | -| 不可伪造 | 无法在没有私钥的情况下生成有效 AgentID | -| 可验证 | 任何人都可以用公钥验证 AgentID 真实性 | -| 不可预测 | 私钥随机生成，key_hash 不可预测 | +| 特性 | 说明 | +|------|---------------------------------| +| 唯一性 | 相同公钥 → 相同 key_hash → 相同 AgentID | +| 不可伪造 | 无法在没有私钥的情况下生成有效 AgentID | +| 可验证 | 任何人都可以用公钥验证 AgentID 真实性 | +| 不可预测 | 私钥随机生成，key_hash 不可预测 | --- @@ -120,10 +121,10 @@ func GenerateAgentID(privateKey []byte, namespace string, alias string) string { ```go type SignedMessage struct { - Message *UnifiedSynapseMessage // 原始消息 - Signature []byte // 签名 - PublicKey []byte // 公钥 - AgentID string // Agent 标识 +Message *UnifiedSynapseMessage // 原始消息 +Signature []byte // 签名 +PublicKey []byte // 公钥 +AgentID string // Agent 标识 } ``` @@ -139,11 +140,11 @@ signature_content = ### 3.4 签名算法 -| 算法 | 说明 | -|------|------| -| Ed25519 | 默认，高效且安全 | -| ECDSA-P256 | 兼容性选项 | -| RSA-2048 | 遗留系统兼容 | +| 算法 | 说明 | +|------------|----------| +| Ed25519 | 默认，高效且安全 | +| ECDSA-P256 | 兼容性选项 | +| RSA-2048 | 遗留系统兼容 | --- @@ -151,11 +152,11 @@ signature_content = ### 4.1 发现机制选择 -| 场景 | 推荐机制 | -|------|---------| -| 小规模（<100 Agent） | 广播查询 | -| 中规模（100-10000） | 分层 DHT | -| 大规模（>10000） | 完整 Kademlia | +| 场景 | 推荐机制 | +|-----------------|-------------| +| 小规模（<100 Agent） | 广播查询 | +| 中规模（100-10000） | 分层 DHT | +| 大规模（>10000） | 完整 Kademlia | ### 4.2 广播查询协议 @@ -201,26 +202,26 @@ Agent A 想知道 Agent B 的 Endpoint： ### 4.4 DHT 消息类型 -| 消息类型 | 说明 | -|---------|------| -| `dht:ping` | 节点存活探测 | -| `dht:store` | 存储 Agent 记录 | -| `dht:find_node` | 查找附近节点 | +| 消息类型 | 说明 | +|------------------|-------------| +| `dht:ping` | 节点存活探测 | +| `dht:store` | 存储 Agent 记录 | +| `dht:find_node` | 查找附近节点 | | `dht:find_value` | 查找 Agent 记录 | -| `dht:notify` | 通知记录更新 | +| `dht:notify` | 通知记录更新 | ### 4.5 Agent 记录结构 ```go type AgentRecord struct { - AgentID string // Agent 唯一标识 - Alias string // 人类可读别名（可选） - Endpoint string // 网络地址 - PublicKey []byte // 公钥 - TTL int64 // 记录有效期（秒） - Version uint64 // 版本号（递增） - Signature []byte // Agent 对以上字段的签名 - Timestamp int64 // 发布时间戳 +AgentID string // Agent 唯一标识 +Alias string // 人类可读别名（可选） +Endpoint string // 网络地址 +PublicKey []byte // 公钥 +TTL int64 // 记录有效期（秒） +Version uint64 // 版本号（递增） +Signature []byte // Agent 对以上字段的签名 +Timestamp int64 // 发布时间戳 } ``` @@ -263,6 +264,7 @@ record_signature_content = ``` **核心思想**： + - Agent 在区块链智能合约中注册身份 - 注册需要质押一定数量的代币作为保证金 - 心跳通过交易上链更新 @@ -449,13 +451,13 @@ did:synapse:{method-specific-id} **DID 方法**： -| 方法 | 说明 | -|------|------| -| `did:synapse:ethereum` | 基于以太坊链上注册表 | -| `did:synapse:polygon` | 基于 Polygon 链 | -| `did:synapse:solana` | 基于 Solana 链 | -| `did:synapse:key` | 基于公钥的离链 DID | -| `did:synapse:dht` | 基于 DHT 的离链 DID | +| 方法 | 说明 | +|------------------------|----------------| +| `did:synapse:ethereum` | 基于以太坊链上注册表 | +| `did:synapse:polygon` | 基于 Polygon 链 | +| `did:synapse:solana` | 基于 Solana 链 | +| `did:synapse:key` | 基于公钥的离链 DID | +| `did:synapse:dht` | 基于 DHT 的离链 DID | **DID Document 示例**： @@ -466,18 +468,25 @@ did:synapse:{method-specific-id} "https://www.w3.org/ns/synapse/v1" ], "id": "did:synapse:ethereum:0x1234abcd5678", - "verificationMethod": [{ - "id": "did:synapse:ethereum:0x1234abcd5678#keys-1", - "type": "EcdsaSecp256k1VerificationKey2019", - "controller": "did:synapse:ethereum:0x1234abcd5678", - "publicKeyHex": "02b3..." - }], - "service": [{ - "id": "did:synapse:ethereum:0x1234abcd5678#synapse-agent", - "type": "SynapseAgent", - "serviceEndpoint": "https://agent-01.example.com/api/synapse" - }], - "synapse:capabilities": ["text_generation", "image_generation"], + "verificationMethod": [ + { + "id": "did:synapse:ethereum:0x1234abcd5678#keys-1", + "type": "EcdsaSecp256k1VerificationKey2019", + "controller": "did:synapse:ethereum:0x1234abcd5678", + "publicKeyHex": "02b3..." + } + ], + "service": [ + { + "id": "did:synapse:ethereum:0x1234abcd5678#synapse-agent", + "type": "SynapseAgent", + "serviceEndpoint": "https://agent-01.example.com/api/synapse" + } + ], + "synapse:capabilities": [ + "text_generation", + "image_generation" + ], "synapse:agentName": "智能写作助手", "synapse:version": "1.0.0" } @@ -485,14 +494,14 @@ did:synapse:{method-specific-id} ### 4.1.4 区块链平台选择 -| 平台 | 优点 | 缺点 | 适合场景 | -|------|------|------|---------| -| Ethereum | 生态最大、安全最高 | Gas 贵、延迟高 | 高价值交易、核心 Agent | -| Polygon | 低 Gas、快确认 | 中心化程度较高 | 中等价值、大量 Agent | -| Solana | 高吞吐、低延迟 | 稳定性偶有问题 | 高频心跳场景 | -| 联盟链 | 可控、隐私好 | 需要许可机制 | 企业内部、联盟合作 | -| L2 (Arbitrum) | 低 Gas、安全继承 | 复杂度较高 | 通用场景 | -| 本地私链 | 完全可控、零成本 | 信任范围有限 | 测试、内部系统 | +| 平台 | 优点 | 缺点 | 适合场景 | +|---------------|------------|-----------|----------------| +| Ethereum | 生态最大、安全最高 | Gas 贵、延迟高 | 高价值交易、核心 Agent | +| Polygon | 低 Gas、快确认 | 中心化程度较高 | 中等价值、大量 Agent | +| Solana | 高吞吐、低延迟 | 稳定性偶有问题 | 高频心跳场景 | +| 联盟链 | 可控、隐私好 | 需要许可机制 | 企业内部、联盟合作 | +| L2 (Arbitrum) | 低 Gas、安全继承 | 复杂度较高 | 通用场景 | +| 本地私链 | 完全可控、零成本 | 信任范围有限 | 测试、内部系统 | ### 4.1.5 混合架构（推荐） @@ -526,43 +535,43 @@ did:synapse:{method-specific-id} ```go type HybridLookup struct { - // L1: 本地缓存（内存，TTL 1分钟） - LocalCache map[string]*AgentRecord - - // L2: DHT 网络（分钟级一致性） - DHT DHTClient - - // L3: 区块链（最终一致性源） - Blockchain BlockchainClient +// L1: 本地缓存（内存，TTL 1分钟） +LocalCache map[string]*AgentRecord + +// L2: DHT 网络（分钟级一致性） +DHT DHTClient + +// L3: 区块链（最终一致性源） +Blockchain BlockchainClient } func (h *HybridLookup) Find(agentID string) (*AgentRecord, error) { - // 1. 查本地缓存 - if record, ok := h.LocalCache.Get(agentID); ok { - if record.IsFresh() { - return record, nil - } - } - - // 2. 查 DHT - if record, err := h.DHT.FindValue(agentID); err == nil { - // 验证签名 - if record.VerifySignature() { - h.LocalCache.Set(agentID, record) - return record, nil - } - } - - // 3. 查区块链（最终源） - if record, err := h.Blockchain.Lookup(agentID); err == nil { - // 验证链上签名（已由链上合约验证过） - h.LocalCache.Set(agentID, record) - // 广播到 DHT 加速后续查询 - h.DHT.Store(agentID, record) - return record, nil - } - - return nil, ErrAgentNotFound +// 1. 查本地缓存 +if record, ok := h.LocalCache.Get(agentID); ok { +if record.IsFresh() { +return record, nil +} +} + +// 2. 查 DHT +if record, err := h.DHT.FindValue(agentID); err == nil { +// 验证签名 +if record.VerifySignature() { +h.LocalCache.Set(agentID, record) +return record, nil +} +} + +// 3. 查区块链（最终源） +if record, err := h.Blockchain.Lookup(agentID); err == nil { +// 验证链上签名（已由链上合约验证过） +h.LocalCache.Set(agentID, record) +// 广播到 DHT 加速后续查询 +h.DHT.Store(agentID, record) +return record, nil +} + +return nil, ErrAgentNotFound } ``` @@ -570,13 +579,13 @@ func (h *HybridLookup) Find(agentID string) (*AgentRecord, error) { 区块链还可实现链上治理功能： -| 功能 | 说明 | -|------|------| +| 功能 | 说明 | +|------|---------------------------| | 质押机制 | Agent 注册需质押代币，恶意行为被 slash | -| 信誉评分 | 链上可查的 Agent 信誉分 | -| 服务定价 | 智能合约自动结算任务费用 | -| 争议仲裁 | 链上投票仲裁 Agent 纠纷 | -| 协议升级 | 通过 DAO 投票决定协议升级 | +| 信誉评分 | 链上可查的 Agent 信誉分 | +| 服务定价 | 智能合约自动结算任务费用 | +| 争议仲裁 | 链上投票仲裁 Agent 纠纷 | +| 协议升级 | 通过 DAO 投票决定协议升级 | --- @@ -584,12 +593,12 @@ func (h *HybridLookup) Find(agentID string) (*AgentRecord, error) { ### 5.1 冲突场景 -| 场景 | 说明 | -|------|------| -| 同一公钥注册多个别名 | 允许（同一 Agent 的多个别名） | -| 不同公钥生成相同 AgentID | 不可能（公钥哈希唯一） | -| 伪造他人 AgentID | 不可能（无法伪造签名） | -| Endpoint 欺骗 | 需要额外验证 | +| 场景 | 说明 | +|------------------|--------------------| +| 同一公钥注册多个别名 | 允许（同一 Agent 的多个别名） | +| 不同公钥生成相同 AgentID | 不可能（公钥哈希唯一） | +| 伪造他人 AgentID | 不可能（无法伪造签名） | +| Endpoint 欺骗 | 需要额外验证 | ### 5.2 Endpoint 绑定验证 @@ -611,33 +620,33 @@ func (h *HybridLookup) Find(agentID string) (*AgentRecord, error) { ```go // 挑战消息 type Challenge struct { - ChallengeID string // 挑战 ID - Nonce []byte // 随机数 - Timestamp int64 // 发送时间 +ChallengeID string // 挑战 ID +Nonce []byte // 随机数 +Timestamp int64 // 发送时间 } // 响应消息 type ChallengeResponse struct { - ChallengeID string // 对应的挑战 ID - Nonce []byte // 原样返回的随机数 - Signature []byte // 对 Nonce 的签名 +ChallengeID string // 对应的挑战 ID +Nonce []byte // 原样返回的随机数 +Signature []byte // 对 Nonce 的签名 } // 验证流程 func VerifyEndpoint(endpoint string, publicKey []byte, challenge *Challenge) bool { - // 1. 发送挑战到 Endpoint - resp := SendChallenge(endpoint, challenge) - - // 2. 验证响应 - if resp.ChallengeID != challenge.ChallengeID { - return false // 挑战 ID 不匹配 - } - if !bytes.Equal(resp.Nonce, challenge.Nonce) { - return false // Nonce 被篡改 - } - - // 3. 验证签名 - return crypto.Verify(publicKey, challenge.Nonce, resp.Signature) +// 1. 发送挑战到 Endpoint +resp := SendChallenge(endpoint, challenge) + +// 2. 验证响应 +if resp.ChallengeID != challenge.ChallengeID { +return false // 挑战 ID 不匹配 +} +if !bytes.Equal(resp.Nonce, challenge.Nonce) { +return false // Nonce 被篡改 +} + +// 3. 验证签名 +return crypto.Verify(publicKey, challenge.Nonce, resp.Signature) } ``` @@ -678,40 +687,40 @@ func VerifyEndpoint(endpoint string, publicKey []byte, challenge *Challenge) boo ### 6.2 生命周期消息 -| 状态 | 说明 | 触发条件 | -|------|------|---------| -| offline | 离线 | 初始状态或主动注销 | -| online | 上线中 | 注册完成，等待首次心跳 | -| active | 活跃 | 定期心跳维持 | +| 状态 | 说明 | 触发条件 | +|------------|-----|-----------------| +| offline | 离线 | 初始状态或主动注销 | +| online | 上线中 | 注册完成，等待首次心跳 | +| active | 活跃 | 定期心跳维持 | | refreshing | 刷新中 | 更新 Endpoint 或别名 | -| suspended | 挂起 | 心跳超时，未注销 | -| offline | 离线 | 注销或永久离线 | +| suspended | 挂起 | 心跳超时，未注销 | +| offline | 离线 | 注销或永久离线 | ### 6.3 消息类型 -| 消息类型 | 方向 | 说明 | -|---------|------|------| -| `identity:register` | → 网络 | 注册 Agent 身份 | -| `identity:refresh` | → 网络 | 刷新注册信息 | -| `identity:challenge` | 双向 | Endpoint 验证挑战 | -| `identity:challenge_response` | 双向 | 挑战响应 | -| `identity:revoke` | → 网络 | 注销身份 | -| `identity:lookup` | → 网络 | 查询 Agent 信息 | -| `identity:lookup_response` | → 网络 | 查询响应 | -| `identity:announce` | → 网络 | 广播在线状态 | -| `identity:heartbeat` | → 网络 | 心跳保活 | +| 消息类型 | 方向 | 说明 | +|-------------------------------|------|---------------| +| `identity:register` | → 网络 | 注册 Agent 身份 | +| `identity:refresh` | → 网络 | 刷新注册信息 | +| `identity:challenge` | 双向 | Endpoint 验证挑战 | +| `identity:challenge_response` | 双向 | 挑战响应 | +| `identity:revoke` | → 网络 | 注销身份 | +| `identity:lookup` | → 网络 | 查询 Agent 信息 | +| `identity:lookup_response` | → 网络 | 查询响应 | +| `identity:announce` | → 网络 | 广播在线状态 | +| `identity:heartbeat` | → 网络 | 心跳保活 | ### 6.4 Register 载荷 ```go type IdentityRegisterPayload struct { - AgentID string // Agent 标识 - Alias string // 人类可读别名 - Endpoint string // 网络地址 - PublicKey []byte // 公钥 - TTL int64 // 注册有效期 - Version uint64 // 版本号 - Signature []byte // Agent 签名 +AgentID string // Agent 标识 +Alias string // 人类可读别名 +Endpoint string // 网络地址 +PublicKey []byte // 公钥 +TTL int64 // 注册有效期 +Version uint64 // 版本号 +Signature []byte // Agent 签名 } ``` @@ -719,10 +728,10 @@ type IdentityRegisterPayload struct { ```go type IdentityHeartbeatPayload struct { - AgentID string // Agent 标识 - Endpoint string // 当前 Endpoint（可能变化） - TTL int64 // 续期时间 - Signature []byte // Agent 签名 +AgentID string // Agent 标识 +Endpoint string // 当前 Endpoint（可能变化） +TTL int64 // 续期时间 +Signature []byte // Agent 签名 } ``` @@ -732,48 +741,48 @@ type IdentityHeartbeatPayload struct { ### 7.1 威胁模型 -| 威胁 | 场景 | 防护措施 | -|------|------|---------| -| 身份伪造 | 攻击者声称自己是他人 | 公钥派生 ID + 签名验证 | -| Endpoint 欺骗 | 攻击者声称他人 Endpoint | 挑战-响应协议 | -| 重放攻击 | 攻击者重放旧消息 | 时间戳 + Nonce | -| 中间人攻击 | 拦截并修改消息 | TLS + 签名验证 | -| 女巫攻击 | 一个节点伪装多个身份 | 工作量证明或权益证明（可选） | -| 日食攻击 | 隔离目标节点 | 多路径查询 | +| 威胁 | 场景 | 防护措施 | +|-------------|------------------|----------------| +| 身份伪造 | 攻击者声称自己是他人 | 公钥派生 ID + 签名验证 | +| Endpoint 欺骗 | 攻击者声称他人 Endpoint | 挑战-响应协议 | +| 重放攻击 | 攻击者重放旧消息 | 时间戳 + Nonce | +| 中间人攻击 | 拦截并修改消息 | TLS + 签名验证 | +| 女巫攻击 | 一个节点伪装多个身份 | 工作量证明或权益证明（可选） | +| 日食攻击 | 隔离目标节点 | 多路径查询 | ### 7.2 重放攻击防护 ```go type AntiReplay struct { - RecentNonces map[string]int64 // nonce -> timestamp - Window time.Duration // 时间窗口（5分钟） +RecentNonces map[string]int64 // nonce -> timestamp +Window time.Duration // 时间窗口（5分钟） } func (a *AntiReplay) CheckAndAdd(nonce string, timestamp int64) bool { - // 1. 检查时间戳是否在窗口内 - now := time.Now().Unix() - if now - timestamp > int64(a.Window.Seconds()) { - return false // 时间戳太旧 - } - - // 2. 检查 Nonce 是否已使用 - if _, exists := a.RecentNonces[nonce]; exists { - return false // 重放 - } - - // 3. 记录 - a.RecentNonces[nonce] = timestamp - return true +// 1. 检查时间戳是否在窗口内 +now := time.Now().Unix() +if now - timestamp > int64(a.Window.Seconds()) { +return false // 时间戳太旧 +} + +// 2. 检查 Nonce 是否已使用 +if _, exists := a.RecentNonces[nonce]; exists { +return false // 重放 +} + +// 3. 记录 +a.RecentNonces[nonce] = timestamp +return true } ``` ### 7.3 私钥保护 -| 场景 | 建议 | -|------|------| -| 本地运行 | 使用密钥文件 + 操作系统密钥链 | -| 云端运行 | 使用 HSM/KMS | -| 嵌入式设备 | 使用 TPM | +| 场景 | 建议 | +|------------|---------------------------------| +| 本地运行 | 使用密钥文件 + 操作系统密钥链 | +| 云端运行 | 使用 HSM/KMS | +| 嵌入式设备 | 使用 TPM | | 多 Agent 共享 | 密钥分片（如 Shamir's Secret Sharing） | --- @@ -786,33 +795,33 @@ func (a *AntiReplay) CheckAndAdd(nonce string, timestamp int64) bool { ```go type AgentEndpoint struct { - AgentID string // 扩展：基于公钥派生 - AgentName string // 人类可读名称 - SystemID string // 所属系统 - Endpoint string // 回调端点 - Version string // Agent 版本 - - // 新增字段 - PublicKey []byte // 公钥（用于验证） - Namespace string // 命名空间 - Alias string // 人类可读别名 +AgentID string // 扩展：基于公钥派生 +AgentName string // 人类可读名称 +SystemID string // 所属系统 +Endpoint string // 回调端点 +Version string // Agent 版本 + +// 新增字段 +PublicKey []byte // 公钥（用于验证） +Namespace string // 命名空间 +Alias string // 人类可读别名 } ``` ### 8.2 与灵脉（Meridian）的整合 -| 模式 | 行为 | -|------|------| -| 中心化可用 | 使用灵脉作为主注册表，本草案作为备份 | -| 去中心化 | 使用本草案的 DHT 机制，完全去中心化 | -| 混合模式 | 核心 Agent 使用中心化，边缘 Agent 使用去中心化 | +| 模式 | 行为 | +|-------|--------------------------------| +| 中心化可用 | 使用灵脉作为主注册表，本草案作为备份 | +| 去中心化 | 使用本草案的 DHT 机制，完全去中心化 | +| 混合模式 | 核心 Agent 使用中心化，边缘 Agent 使用去中心化 | ### 8.3 与灵玺（Sigil）的整合 -| 组件 | 职责 | -|------|------| -| 灵玺（Sigil） | 密钥管理、签名验证 | -| 本草案 | ID 生成、发现协议、生命周期 | +| 组件 | 职责 | +|-----------|-----------------| +| 灵玺（Sigil） | 密钥管理、签名验证 | +| 本草案 | ID 生成、发现协议、生命周期 | --- @@ -820,36 +829,36 @@ type AgentEndpoint struct { ### 9.1 消息类型列表 -| 类型 | 协议前缀 | 说明 | -|------|---------|------| -| `identity:register` | 前端 | 注册身份 | -| `identity:refresh` | 前端 | 刷新注册 | -| `identity:revoke` | 前端 | 注销身份 | -| `identity:challenge` | 前端 | 挑战请求 | -| `identity:challenge_response` | 前端 | 挑战响应 | -| `identity:lookup` | 前端 | 查询身份 | -| `identity:lookup_response` | 前端 | 查询响应 | -| `identity:announce` | 前端 | 广播在线 | -| `identity:heartbeat` | 前端 | 心跳保活 | -| `dht:ping` | DHT | 节点探测 | -| `dht:store` | DHT | 存储记录 | -| `dht:find_node` | DHT | 查找节点 | -| `dht:find_value` | DHT | 查找值 | -| `dht:notify` | DHT | 通知更新 | +| 类型 | 协议前缀 | 说明 | +|-------------------------------|------|------| +| `identity:register` | 前端 | 注册身份 | +| `identity:refresh` | 前端 | 刷新注册 | +| `identity:revoke` | 前端 | 注销身份 | +| `identity:challenge` | 前端 | 挑战请求 | +| `identity:challenge_response` | 前端 | 挑战响应 | +| `identity:lookup` | 前端 | 查询身份 | +| `identity:lookup_response` | 前端 | 查询响应 | +| `identity:announce` | 前端 | 广播在线 | +| `identity:heartbeat` | 前端 | 心跳保活 | +| `dht:ping` | DHT | 节点探测 | +| `dht:store` | DHT | 存储记录 | +| `dht:find_node` | DHT | 查找节点 | +| `dht:find_value` | DHT | 查找值 | +| `dht:notify` | DHT | 通知更新 | --- ## 10. 待解决问题（Open Issues） -| 问题 | 说明 | 优先级 | -|------|------|--------| -| 隐私保护 | 公钥哈希是否暴露身份？ | 高 | -| 密钥轮换 | 私钥更换后如何保持 AgentID？ | 高 | -| 名称冲突 | 人类可读别名可能重复 | 中 | -| 性能优化 | DHT 查找延迟 | 中 | -| 移动 Agent | Endpoint 频繁变化 | 低 | -| 链上 Gas 成本 | 区块链交易费用 | 中 | -| DID 方法注册 | W3C 标准 DID 方法注册流程 | 低 | +| 问题 | 说明 | 优先级 | +|-----------|--------------------|-----| +| 隐私保护 | 公钥哈希是否暴露身份？ | 高 | +| 密钥轮换 | 私钥更换后如何保持 AgentID？ | 高 | +| 名称冲突 | 人类可读别名可能重复 | 中 | +| 性能优化 | DHT 查找延迟 | 中 | +| 移动 Agent | Endpoint 频繁变化 | 低 | +| 链上 Gas 成本 | 区块链交易费用 | 中 | +| DID 方法注册 | W3C 标准 DID 方法注册流程 | 低 | --- @@ -858,28 +867,31 @@ type AgentEndpoint struct { ### 11.1 分阶段实现 **Phase 1（最小可行）**： + - 实现 AgentID 公钥派生 - 实现消息签名验证 - 使用广播进行发现 **Phase 2（基本功能）**： + - 实现分层 DHT - 实现生命周期管理 - 实现挑战-响应协议 **Phase 3（完整功能）**： + - 实现完整 Kademlia - 实现隐私保护 - 实现密钥轮换 ### 11.2 推荐库 -| 功能 | 推荐库 | -|------|--------| -| 加密签名 | golang.org/x/crypto/ed25519 | -| Base58 | github.com/mr-tron/base58 | -| DHT | github.com/anacrolix/go-libutp 或自实现 | -| 分布式存储 | etcd/consul（混合模式） | +| 功能 | 推荐库 | +|--------|-------------------------------------| +| 加密签名 | golang.org/x/crypto/ed25519 | +| Base58 | github.com/mr-tron/base58 | +| DHT | github.com/anacrolix/go-libutp 或自实现 | +| 分布式存储 | etcd/consul（混合模式） | ---