15. 开发者指南

Developer Guide 面向 FlowNex 的平台开发者和扩展开发者。

15.1 本地开发环境

本地开发通常需要启动：

  1. MySQL。
  2. Redis。
  3. RocketMQ。
  4. Nacos。
  5. agent-domain-service。
  6. user-domain-service。
  7. ai-claw-gateway。
  8. ai-app-runtime-gateway。
  9. ai-app-service。
  10. control-center。
  11. agent-runtime-gateway。
  12. share-harness。
  13. 前端应用。

开发建议：

  1. 优先阅读根目录 README.md 理解模块边界。
  2. 每个 Java 服务独立启动。
  3. Python runtime 单独管理依赖。
  4. migration 先在测试库验证。
  5. 修改跨服务 DTO 时同步更新调用方测试。

15.2 代码仓模块说明

核心模块：

  1. ai-claw-gateway：FlowNex 主站网关，负责 AI 应用入口之外的对话、管理台、Skill、知识库、任务中心和飞书等交互接入。
  2. ai-app-runtime-gateway：AI 应用中心专用接入网关，负责 application 前缀路由和 AI 应用前端连接承接。
  3. ai-app-service：AI 应用层聚合服务，负责应用交互接口、业务语义接口和业务数据落库。
  4. control-center：能力中心和编排协同服务，内部实现 Capability Gateway、Capability Registry、Provider Adapter 等能力治理模块。
  5. user-domain-service：用户域。
  6. agent-domain-service：Agent、会话、消息、任务、Skill 等领域。
  7. agent-runtime-gateway：运行时路由和事件回推。
  8. share-harness：Python Agent Runtime。
  9. xingyun-ai-common：公共能力。

Java 服务通常采用：

*-client
*-domain
*-application
*-infrastructure
*-server

分层约定：

  1. client：DTO 和 Facade。
  2. domain：领域模型和领域能力。
  3. application：应用服务和用例编排。
  4. infrastructure：数据库、Redis、RPC、外部系统适配。
  5. server：启动和配置装配。

15.3 新增一个 Tool

新增 Tool 的推荐步骤：

  1. 明确 Tool 的动作边界。
  2. 定义 Tool code。
  3. 定义入参 schema。
  4. 定义输出结构。
  5. 定义权限要求。
  6. 在能力注册处注册 Tool。
  7. 在 control-center 或领域服务中配置 Tool 授权。
  8. 在 share-harness 中实现 Tool 调用适配。
  9. 增加测试。
  10. 增加审计和错误映射。

Tool 设计原则：

  1. 入参结构化。
  2. 输出可裁剪。
  3. 错误可解释。
  4. 权限可控制。
  5. 调用可审计。

15.4 新增一个 Skill

新增 Skill 的推荐步骤：

  1. 编写 Skill 描述。
  2. 定义适用场景。
  3. 定义输入要求。
  4. 定义执行步骤。
  5. 定义输出格式。
  6. 声明建议 Tool。
  7. 绑定必要知识库。
  8. 提供示例。
  9. 提交审核。
  10. 发布并灰度。

高质量 Skill 应避免：

  1. 目标含糊。
  2. 输出格式不稳定。
  3. 隐含依赖未声明。
  4. 要求使用未授权 Tool。
  5. 把大量知识硬编码进 Skill。

15.5 新增一个知识检索 Provider

如果未来需要接入 OpenViking 之外的知识 Provider，应遵守统一适配边界。

新增步骤：

  1. 定义 Provider code。
  2. 实现检索 Adapter。
  3. 实现凭证和 endpoint 配置读取。
  4. 复用本地 KnowledgeAsset / KnowledgeMapping / KnowledgeAcl。
  5. 保证检索前权限裁剪。
  6. 输出统一 KnowledgeSearchResponse。
  7. 记录统一命中轨迹。

Provider 不应绕过本地权限系统。

15.5.1 新增一个业务线 Capability Provider

业务线 AI 能力接入 FlowNex 时，应以 Capability Provider 的方式接入，而不是让 Skill 或 Tool 直接调用业务线接口。

推荐步骤：

  1. 明确能力边界，判断是完整 AI 应用、原子能力还是业务系统动作。
  2. 定义 capabilityCode、版本、负责人和所属业务线。
  3. 定义输入 Schema、输出 Schema 和示例数据。
  4. 定义鉴权方式，但只保存凭证引用，不把密钥下发给 runtime。
  5. 实现 Provider Adapter，完成协议转换、字段映射、错误码映射、超时和重试。
  6. 在 Capability Registry 登记能力元数据。
  7. 在管理台配置租户、部门、角色、Agent 或 Skill 的可见范围。
  8. 将能力包装为 Tool，必要时再封装为 Skill。
  9. 接入 Trace、Metrics、Audit 和自动回归测试。
  10. 完成联调、灰度、验收和回滚预案。

Provider Adapter 至少需要处理：

能力 要求
鉴权 使用平台托管凭证或短期 token，不暴露密钥
Schema 校验 调用前校验输入，调用后校验输出
错误映射 将业务线错误码转换为 FlowNex 统一错误
幂等 写操作必须支持幂等键或业务去重
超时重试 明确哪些错误可重试，哪些错误不可重试
降级 Provider 不可用时返回可解释降级结果
审计 记录调用主体、能力、输入摘要、输出摘要和结果

接入验收建议：

  1. 能力在目录中可查询。
  2. 未授权用户无法调用。
  3. 已授权用户可通过 Agent / Skill 正常调用。
  4. 调用 Trace 可按 taskId 和 capabilityCode 查询。
  5. 错误码和异常提示清晰。
  6. 自动回归样例通过。
  7. 运营报表能看到调用量、成功率、耗时和失败原因。

15.6 新增一个 AGFS 插件

AGFS 插件用于扩展文件系统后端或特殊路径行为。

新增插件建议：

  1. 实现统一 FileSystem 接口。
  2. 支持 Read / Write / ReadDir / Stat / Mkdir / Open / Delete。
  3. 接入生命周期 Hook。
  4. 接入权限检查。
  5. 接入 Version Tree。
  6. 接入 checkpoint。
  7. 增加集成测试。

插件不应把业务租户逻辑硬编码到路径解析中。租户和项目隔离应通过 Space、Mount 和 rootFileId 表达。

15.7 新增一个 Runtime 事件

新增 Runtime 事件需要考虑：

  1. 事件名称。
  2. 事件 payload。
  3. 是否展示给用户。
  4. 是否持久化。
  5. 是否参与指标。
  6. 是否需要兼容旧客户端。
  7. 是否需要进入任务回放。

事件设计应尽量结构化，避免只传自然语言文本。

示例：

{
  "eventType": "knowledge.search.completed",
  "taskId": "10001",
  "providerResourceIds": ["kb_policy"],
  "hitCount": 3,
  "durationMs": 420
}

15.8 测试规范

测试应覆盖：

  1. 单元测试。
  2. Facade 契约测试。
  3. 应用服务测试。
  4. Mapper 测试。
  5. Runtime 工具测试。
  6. API 集成测试。
  7. 跨服务协议兼容测试。
  8. AGFS 文件一致性测试。
  9. 知识权限裁剪测试。
  10. Skill 绑定知识范围测试。

关键链路必须有回归测试：

  1. 创建消息和任务。
  2. 下发 runtime。
  3. runtime 回调。
  4. 知识检索。
  5. Skill 使用。
  6. 文件产物持久化。
  7. SSE 推送。

15.9 兼容性与版本策略

跨服务协议需要保持兼容。

变更原则：

  1. DTO 新增字段优先使用可选字段。
  2. runtime 请求新增字段应允许旧版本忽略。
  3. 事件 payload 新增字段不应破坏旧消费者。
  4. 数据库 migration 应可重复执行或具备保护。
  5. 新能力通过 feature flag 灰度。

版本对象包括：

  1. 服务版本。
  2. Runtime 协议版本。
  3. Skill 版本。
  4. Tool 版本。
  5. Knowledge mapping 版本。
  6. AGFS 文件版本。
  7. 多 Agent 策略版本。