代理联邦网络

v1.1.0 新功能

概述

代理联邦网络是 ChainlessChain 的去中心化 Agent 协作基础设施，提供 DID 身份管理、联邦发现、可验证凭证和跨组织任务路由能力。它使不同组织的 AI Agent 能够通过去中心化身份互相认证、按技能发现协作伙伴，并在 SLA 保障下完成跨组织的智能任务分配。

核心特性

🪪 DID 身份管理: 去中心化 Agent 身份创建、解析与撤销
🔍 联邦发现: 自动注册到网络，按技能发现可用 Agent
📜 可验证凭证: 颁发、验证、撤销 Agent 能力与委托凭证
🌐 跨组织路由: 跨组织边界的智能任务分配与 SLA 保障
⭐ 信誉评估: 基于任务完成质量的去中心化信誉评分系统
🛡️ 安全认证: DID 挑战-响应双向认证，会话 Token 管理

系统架构

┌──────────────────────────────────────────────┐
│              代理联邦网络                       │
├──────────────────────────────────────────────┤
│                                                │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │ Agent    │  │ Federated│  │ Credential │  │
│  │ DID      │  │ Registry │  │ Manager    │  │
│  │ (身份)   │  │ (注册表)  │  │ (凭证)    │  │
│  └────┬─────┘  └────┬─────┘  └─────┬──────┘  │
│       │              │              │          │
│  ┌────▼──────────────▼──────────────▼──────┐  │
│  │        Cross-Org Task Router            │  │
│  │        (跨组织任务路由)                   │  │
│  └─────────────────┬──────────────────────┘  │
│                    │                          │
│  ┌─────────────────▼──────────────────────┐  │
│  │         Reputation System              │  │
│  │         (信誉评分与排行)                 │  │
│  └────────────────────────────────────────┘  │
└──────────────────────────────────────────────┘

系统概述

代理联邦网络（Agent Federation）实现去中心化的 AI 代理协作，支持 DID 身份管理、代理发现、跨组织任务路由和信誉评估，构建可信的分布式 AI 代理网络。

核心能力

Agent DID：去中心化身份标识，支持创建、解析、撤销
联邦注册与发现：代理自动注册到联邦网络，按技能发现代理
可验证凭证：颁发、验证、撤销代理能力凭证
跨组织任务路由：跨组织边界的智能任务分配和执行
信誉系统：基于任务完成质量的去中心化信誉评估

IPC 通道

Agent DID

通道	说明
`agent-did:create`	创建 DID
`agent-did:resolve`	解析 DID
`agent-did:get-all`	获取所有 DID
`agent-did:revoke`	撤销 DID

联邦注册

通道	说明
`fed-registry:discover`	发现代理
`fed-registry:register`	注册代理
`fed-registry:query-skills`	按技能查询
`fed-registry:get-network-stats`	获取网络统计

可验证凭证

通道	说明
`agent-cred:issue`	颁发凭证
`agent-cred:verify`	验证凭证
`agent-cred:revoke`	撤销凭证

跨组织任务

通道	说明
`cross-org:route-task`	路由任务
`cross-org:get-task-status`	获取任务状态
`cross-org:cancel-task`	取消任务
`cross-org:get-log`	获取任务日志

信誉系统

通道	说明
`reputation:get-score`	获取信誉分
`reputation:get-ranking`	获取排行榜
`reputation:update`	更新信誉
`reputation:get-history`	获取信誉历史

配置

通道	说明
`decentralized:get-config`	获取去中心化配置

配置

在 .chainlesschain/config.json 中配置：

json

{
  "agentFederation": {
    "enabled": true,
    "registryUrl": "https://registry.chainlesschain.io",
    "autoRegister": true,
    "autoDiscover": true,
    "discoverInterval": 300000,
    "reputation": {
      "initialScore": 5.0,
      "decayFactor": 0.95,
      "minTasksForRanking": 3
    },
    "crossOrg": {
      "maxConcurrentTasks": 5,
      "defaultTimeout": 300000,
      "slaEnforcement": true
    }
  }
}

使用示例

加入联邦网络

打开「去中心化代理网络」页面
点击「创建 DID」生成代理身份
点击「注册代理」加入联邦网络
系统自动广播技能到网络

委派跨组织任务

在「代理发现」标签页搜索目标技能
从在线代理列表中选择合适的代理
点击「委派任务」，填写任务类型和描述
在「跨组织任务」标签页跟踪任务进度

信誉查看

切换到「信誉排行」标签页
查看全网代理信誉排行榜
点击代理查看详细信誉历史

故障排除

问题	解决方案
DID 创建失败	检查密钥生成环境和权限
发现不到代理	确认网络连接和注册中心地址
任务路由失败	检查目标代理在线状态和 SLA 配置
信誉分异常	查看信誉历史确认是否有负面事件

联邦节点不可达

现象: 调用 fed-registry:discover 或 fed-registry:register 超时或返回连接失败。

排查步骤:

确认 registryUrl 配置地址正确且可访问（curl 或浏览器测试）
检查本地网络代理/防火墙设置是否阻断了外部请求
确认 autoDiscover 和 autoRegister 是否为 true
查看日志中是否有 DNS 解析或 TLS 证书校验错误

DID 认证失败（挑战-响应错误）

现象: 跨组织调用时返回认证失败，Agent 被拒绝访问。

排查步骤:

确认本地 Agent DID 的 Ed25519 密钥未过期或被撤销
检查双方系统时间差是否在允许范围内（时间戳验证依赖时钟同步）
确认会话 Token 未过期（默认 TTL 1 小时），过期后需重新认证
查看 agent-did:resolve 是否能正常解析对方 DID 文档

跨组织任务超时

现象: cross-org:route-task 长时间无响应或返回超时错误。

排查步骤:

检查 crossOrg.defaultTimeout 配置是否设置过短（默认 300000ms）
确认目标 Agent 在线并有空闲处理能力（maxConcurrentTasks 未超限）
查看 cross-org:get-task-status 确认任务是否卡在某个中间状态
若目标 Agent 持续不响应，检查其心跳状态或尝试更换目标 Agent

故障排查

常见问题

症状	可能原因	解决方案
节点注册失败	DID 格式错误或注册服务不可达	验证 DID 格式，检查联邦注册中心网络连通性
跨组织路由超时	目标组织防火墙阻断或路由表过期	检查网络策略，执行 `federation route-refresh`
认证令牌过期	Token TTL 过短或时钟偏移	增大 `tokenTTL` 配置，同步系统时钟（NTP）
Agent 心跳丢失	网络抖动或心跳间隔过长	缩短 `heartbeatInterval`，检查网络稳定性
联邦发现服务无响应	发现服务未启动或端口被占用	重启发现服务，确认端口未冲突

常见错误修复

错误: REGISTRATION_FAILED 节点注册被拒

bash

# 检查 DID 有效性
chainlesschain did list --verbose

# 重新注册节点
chainlesschain a2a register --force --did <your-did>

错误: ROUTE_TIMEOUT 跨组织路由超时

bash

# 刷新路由表
chainlesschain a2a route-refresh

# 测试目标组织连通性
chainlesschain a2a ping --org <target-org-id>

错误: AUTH_TOKEN_EXPIRED 认证过期

bash

# 重新获取认证令牌
chainlesschain a2a auth-renew --agent-did <your-did>

# 检查系统时钟同步状态
chainlesschain doctor --check ntp

配置参考

完整配置项说明（.chainlesschain/config.json）：

配置项	类型	默认值	说明
`agentFederation.enabled`	boolean	`true`	是否启用联邦网络
`agentFederation.registryUrl`	string	`"https://registry.chainlesschain.io"`	联邦注册中心地址
`agentFederation.autoRegister`	boolean	`true`	启动时自动注册到联邦网络
`agentFederation.autoDiscover`	boolean	`true`	自动发现并缓存网络中的 Agent
`agentFederation.discoverInterval`	number	`300000`	自动发现轮询间隔（ms）
`agentFederation.reputation.initialScore`	number	`5.0`	新 Agent 初始信誉分（0–10）
`agentFederation.reputation.decayFactor`	number	`0.95`	每次衰减周期的信誉折损系数
`agentFederation.reputation.minTasksForRanking`	number	`3`	进入排行榜所需最少完成任务数
`agentFederation.crossOrg.maxConcurrentTasks`	number	`5`	单 Agent 最大并发跨组织任务数
`agentFederation.crossOrg.defaultTimeout`	number	`300000`	跨组织任务默认超时时间（ms）
`agentFederation.crossOrg.slaEnforcement`	boolean	`true`	是否强制执行 SLA 约束

最小配置示例

json

{
  "agentFederation": {
    "enabled": true,
    "registryUrl": "https://registry.chainlesschain.io",
    "crossOrg": {
      "defaultTimeout": 600000
    }
  }
}

离线/私有化部署配置

json

{
  "agentFederation": {
    "enabled": true,
    "registryUrl": "http://internal-registry.corp:8080",
    "autoDiscover": false,
    "crossOrg": {
      "slaEnforcement": false
    }
  }
}

性能指标

基准测试数据（v1.1.0，单节点，16 GB RAM）

操作	P50 延迟	P99 延迟	吞吐量
DID 创建（含密钥生成）	12 ms	45 ms	80 ops/s
DID 解析（本地缓存命中）	< 1 ms	3 ms	5000 ops/s
联邦注册（单节点写入）	20 ms	80 ms	50 ops/s
Agent 发现（本地注册表）	2 ms	10 ms	2000 ops/s
Agent 发现（联邦 DHT 查询）	80 ms	350 ms	200 ops/s
VC 凭证颁发（含 Ed25519 签名）	8 ms	30 ms	120 ops/s
VC 凭证验证	5 ms	20 ms	500 ops/s
跨组织任务路由（best-reputation）	50 ms	200 ms	100 ops/s
信誉分查询	3 ms	15 ms	1000 ops/s
信誉排行榜（Top 100）	10 ms	40 ms	300 ops/s

扩展性说明

联邦节点数: 单注册中心支持最多 10,000 个在线 Agent，超出后建议分片部署
凭证容量: 每个 Agent 最多持有 100 个有效凭证，超出时最旧凭证自动归档
内存占用: 基础联邦模块约占 80 MB；万级 Agent 缓存约额外占用 200 MB
心跳带宽: 每 2 分钟一次心跳，单心跳包约 512 B，千节点场景月流量 < 1 GB

测试覆盖率

测试文件

文件	测试数	覆盖模块
`tests/unit/ai-engine/agent-did.test.js`	28	DID 创建/解析/撤销、状态机
`tests/unit/ai-engine/federated-agent-registry.test.js`	34	注册、发现、DHT、心跳
`tests/unit/ai-engine/agent-credential-manager.test.js`	22	VC 颁发/验证/撤销、链式委托
`tests/unit/ai-engine/cross-org-task-router.test.js`	26	四种路由策略、超时、SLA
`tests/unit/ai-engine/agent-reputation.test.js`	20	四维评分、时间衰减、排行
`tests/integration/agent-federation-e2e.test.js`	15	完整联邦入网→发现→委派→信誉更新流程

合计: 145 个测试用例，行覆盖率 ≥ 87%

运行测试

bash

# 全量联邦网络测试
cd desktop-app-vue && npx vitest run tests/unit/ai-engine/agent-did tests/unit/ai-engine/federated-agent-registry tests/unit/ai-engine/agent-credential-manager

# 集成测试（需本地联邦注册服务）
cd desktop-app-vue && npx vitest run tests/integration/agent-federation-e2e

# 快速冒烟测试（仅核心 DID + 路由）
cd desktop-app-vue && npx vitest run tests/unit/ai-engine/agent-did tests/unit/ai-engine/cross-org-task-router

安全考虑

DID 密钥隔离: 每个 Agent 的 Ed25519 私钥存储在本地加密数据库，不随网络传播
挑战-响应认证: 双向 DID 认证采用随机挑战+时间戳，防止中间人和重放攻击
凭证有效期: 所有 VC 凭证设有过期时间，吊销注册表支持即时失效
信誉防篡改: 信誉评分由本地计算引擎生成，基于实际任务执行结果，不可外部注入
跨组织隔离: 不同组织的 Agent 注册表逻辑隔离，联邦查询需经认证授权
任务路由鉴权: 跨组织任务分配前验证目标 Agent 的在线状态和 SLA 合规性
会话 Token 管理: 认证会话设有 TTL（默认 1 小时），过期自动清理
数据传输加密: 所有联邦网络通信使用端到端加密，防止数据窃听

关键文件

文件	职责
`desktop-app-vue/src/main/ai-engine/cowork/agent-did.js`	Agent DID 身份管理
`desktop-app-vue/src/main/ai-engine/cowork/federated-agent-registry.js`	联邦注册表与发现
`desktop-app-vue/src/main/ai-engine/cowork/agent-credential-manager.js`	可验证凭证管理
`desktop-app-vue/src/main/ai-engine/cowork/cross-org-task-router.js`	跨组织任务路由
`desktop-app-vue/src/main/ai-engine/cowork/agent-reputation.js`	信誉评分系统

代理联邦网络 ​

概述 ​

核心特性 ​

系统架构 ​

系统概述 ​

核心能力 ​

IPC 通道 ​

Agent DID ​

联邦注册 ​

可验证凭证 ​

跨组织任务 ​

信誉系统 ​

配置 ​

配置 ​

使用示例 ​

加入联邦网络 ​

委派跨组织任务 ​

信誉查看 ​

故障排除 ​

联邦节点不可达 ​

DID 认证失败（挑战-响应错误） ​

跨组织任务超时 ​

故障排查 ​

常见问题 ​

常见错误修复 ​

配置参考 ​

最小配置示例 ​

离线/私有化部署配置 ​

性能指标 ​

基准测试数据（v1.1.0，单节点，16 GB RAM） ​

扩展性说明 ​

测试覆盖率 ​

测试文件 ​

运行测试 ​

安全考虑 ​

关键文件 ​

相关文档 ​

代理联邦网络

概述

核心特性

系统架构

系统概述

核心能力

IPC 通道

Agent DID

联邦注册

可验证凭证

跨组织任务

信誉系统

配置

配置

使用示例

加入联邦网络

委派跨组织任务

信誉查看

故障排除

联邦节点不可达

DID 认证失败（挑战-响应错误）

跨组织任务超时

故障排查

常见问题

常见错误修复

配置参考

最小配置示例

离线/私有化部署配置

性能指标

基准测试数据（v1.1.0，单节点，16 GB RAM）

扩展性说明

测试覆盖率

测试文件

运行测试

安全考虑

关键文件

相关文档