一、问题的本质1.1 传统模式的困境

留意一个具有代表性的企业运用情境，一个Nexus应用要去整合飞书的组织架构方面的数据。

传统做法：

# application.yml
feishu:
  server-url: https://feishu-api.company.com
  app-id: cli_xxx
  app-secret: xxx

这种做法存在几个问题：

硬编码依赖，服务地址得靠人工去配置，在环境迁移之际，极易出现差错，欠缺灵活性，没办法动态去切换服务提供者，不存在自动发现功能，新增服务时要手动更新配置，没有故障转移能力，当服务不可用时并无自动切换机制，1.2 核心矛盾。

传统模式存在着根本矛盾，具体表现为，应用所关注的是“能力”，然而配置所关注的却是“地址”。

对于用户而言，其真正所需要的乃是“读取组织数据”这般的能力，并非“连接到 192.168.1.100:8080”此等地址，把能力同地址予以解耦，这是我们设计时的出发点。

二、核心理念：场景驱动2.1 什么是场景？

场景，也就是Scene，它是一组彼此关涉能力的静态界定，叙述了“谁于何种情形之下能够做何事”。

name: auth
description: 认证场景，提供用户认证和组织数据访问能力
capabilities:
  - org-data-read
  - user-auth
roles:
  - roleId: org-provider
    required: true
    capabilities: [org-data-read, user-auth]

场景的特点：

2.2 场景 vs 服务2.3 从场景到组

场景是静态定义，组（Group）是场景在运行时的实例化。

场景与组的关系

运行时，auth场景能力定义角色约束，静态实例化auth-group-001成员，成员当中存在协作连接信息，有此情况。

组负责两件事：

实时连接状况反馈呈现了有关于：谁正处在在线状态、谁处于离线状态的场景实例关联处理情况是怎样的，还阐述了怎么样展开协作、怎么样去选择主导者这方面的内容，另外就是 2.4 场景与 Agent 之间的关系。

依存于 0.6.6 的 Agent 架构体系，场景跟角色的相互对应关联情况：

Agent 类型

场景角色

职责

服务提供者 ()

提供能力服务，创建场景组

服务消费者 ()

消费能力服务，加入场景组

场景协调者 ()

协调场景组，管理元数据

三、零配置发现机制3.1 设计目标

用户只需要表达"我需要什么能力"，系统自动完成：

3.2 发现流程

零配置发现流程

1. 用户发出的请求场景是处于("auth")状态下的，2. 该场景到底存不存在呢？要检查本地注册表，结果是否定的，3. 接着要查询技能中心API，查证是可以查的，4. 之后要加入场景组以获取组成员的信息，并进行4a步骤，也就是下载以及安装技能，5. 然后获取连接信息并自动解码，6. 最后确认服务是可用的。

3.3 多层发现策略

系统支持多种发现方式，按优先级自动切换：

3.4 UDP 广播发现（继承自 0.6.6）

基于 0.6.6 的安全广播消息格式：

发现请求消息：

DISCOVER:SKILL:{agentId};{skillName};{skillType};{endpoint};{timestamp};{signature}

加入响应消息：

JOIN_RESPONSE:SKILL:{agentId};{skillType};{sceneId};{status};{timestamp};{signature}

复制

安全机制：

3.5 连接信息解码

用户不需要知道服务的具体地址，连接信息从组中动态获取：

SceneJoinResult result = sdk.requestScene("auth").get();
// 自动获取连接信息
String endpoint = result.getEndpoint();  // 动态解析
String apiKey = result.getApiKey();      // 自动注入

这种"硬地址解码"机制，让应用完全与基础设施解耦。

四、双模式部署4.1 远程托管模式

技能运行在 ，用户只需配置认证信息：

InstallRequest.builder()
    .skillId("skill-org-feishu")
    .mode(InstallMode.REMOTE_HOSTED)
    .config("FEISHU_APP_ID", "xxx")
    .build();

优势：

4.2 本地部署模式

技能下载到本地运行：

InstallRequest.builder()
    .skillId("skill-org-feishu")
    .mode(InstallMode.LOCAL_DEPLOYED)
    .config("FEISHU_APP_ID", "xxx")
    .autoStart(true)
    .build();

优势：

4.3 与 VFS 的集成

基于 0.6.6 的 VFS 协议，本地部署的技能可以：

配置方面存在自动同步的情况，具体而言，配置文件借助 VFS 来同步数据，并且有着持久化这一特性，再说技能数据，其是存储于 VFS 的，另外还有故障恢复相关，也就是当 VFS 不可用时会自动切换至本地存储。

VFS 集成架构

技能，本地的实例，虚拟文件系统存储，同步远程托管的虚拟文件系统，不可用时，本地存储，降级模式，恢复后，自动同步，恢复后。

4.4 模式选择建议五、无中心组网5.1 为什么需要无中心？

传统中心化架构存在单点故障风险：

无中心组网借助 P2P 协议，使得每个节点都能够成为发现节点，进而消除了单点故障。

5.2 DHT

对于以 0.6.6 为基础的 P2P 协议，我们运用算法达成分布式哈希表（DHT）的实现：

DHT 架构

5.3 自组织特性

无中心组网具有自组织特性：

自打发现，新的节点会自动加入网络，自愈合方面，节点离线之后会自动重新挑选主节点，自负载这里，请求能够自然被自动路由至最优的节点codejock，自扩展范畴，新节点能自动去分担负载，5.4与0.6.6 Agent层次的融合。

无中心组网与 Agent 层次

多层控制及调配代理协调层级中的代理一号，分布式哈希表节点路由之代理二号，分布式哈希表众多节点里的分组A（认证相关）codejock，分组B（消息相关），结束代理一号，结束代理二号。

六、AI 友好设计6.1 .md 规范

技能通过自然语言描述，便于 AI 理解：

# skill-org-feishu
## 提供的能力
### org-data-read
读取飞书组织机构数据，包括部门树、成员列表等。
**参数：**
- orgId (可选): 组织ID
- includeInactive (可选): 是否包含停用成员
**返回：**
组织树结构
## 配置示例
```yaml
feishu:
  app-id: cli_xxx
  app-secret: xxx
```

复制

6.2 AI 调用流程

AI 调用流程

AI助手，1. 对.md读取，理解能力SDK进行调用，2. （“auth”）自动去发现，3. 获取连接信息，服务进行调用，4. 获取组织数据，返回结果。

6.3 与 0.6.6 模型的对应

0.6.6 概念

0.7.0 概念

说明

能力定义（继承）

Skill

Skill + Scene

技能 + 场景组织

如有侵权请联系删除！