FlowNex 能力管理整合业务线 AI 能力接入说明

1. 文档目的

本文面向需要将已有 AI 能力接入 FlowNex 的业务线团队，说明如何通过 FlowNex 能力管理功能，把各业务线已有的模型能力、识别能力、解析能力、生成能力、审核能力或业务 AI 服务，统一纳入 FlowNex 的能力目录、租户配置、运行调用、权限治理和观测体系。

接入后的目标是：

业务线 AI 能力以标准 capabilityCode 对外暴露。
调用方不感知厂商、模型、Endpoint、API Key 等内部实现。
租户可在能力管理中独立启用、配置、测试和治理能力。
只有通过行云 AI 算力专项学习服务、会议智能总结、智能项目管理、智能标书等 AI 应用中心前端应用发起的请求，才会通过 ai-app-runtime-gateway 的 application 路由进入 ai-app-service，再由 control-center 能力中心调用原子能力；现有飞书、钉钉、Web 前端、管理台、Skill、知识库、任务中心等交互仍走原链路 ai-claw-gateway -> control-center。
能力调用具备统一 trace、错误分类、脱敏、审计和后续统计基础。

2. 总体接入原则

FlowNex 能力管理采用“双网关接入、AI 应用服务只承载 AI 应用中心业务语义、control-center 能力中心集中治理、业务实现独立承载”的分工。

原则	说明
能力不绑定应用版本	所有 AI 应用默认可调用当前租户已发布且已启用的原子能力，不建设应用与能力绑定表。
调用方不直连厂商	AI 应用中心前端应用请求经过 `ai-app-runtime-gateway` 的 `application` 路由进入 `ai-app-service`；现有飞书、钉钉、Web 前端和非 AI 应用入口交互经过 `ai-claw-gateway -> control-center`；原子能力请求由 `control-center` 能力中心处理，调用方不能直接访问外部 AI 厂商。
能力契约稳定	业务线对外只暴露 `capabilityCode + contractVersion + requestSchema + responseSchema`。
配置与凭证内收	Provider、模型、Endpoint、Region、API Key 等配置由能力管理保存和加密治理。
一能力一内聚问题	每个能力只解决一个清晰问题，例如 `audio.transcription`、`doc.parse`、`image.ocr`。
业务数据仍归业务线	业务线服务只保存自身业务数据，不保存 FlowNex 登录态、厂商凭证或应用发布主数据。

3. 适用接入场景

场景	推荐接入方式	示例
已有外部厂商 AI 能力	新增平台能力定义、Provider Adapter 和租户连接配置	火山语音转写、OCR、内容审核
已有业务线内部 AI 服务	包装为能力 Provider，由 `control-center` 内部 Provider Adapter 适配调用	法务合同审核、财务票据解析、客服意图识别
AI 应用 H5 需要同步调用	通过 H5 SDK 调 `application` 路由，由 `ai-app-service` 转入能力中心	前端上传图片后调用 OCR
AI 应用 Java 后台任务需要调用	通过 `CapabilityPlatformClient` 调 `ai-app-service` 应用层能力入口，再进入 `control-center`	异步处理录音转写、文档解析
能力希望给 Agent 使用	P1 通过 Capability Tool Registry 暴露为 LangGraph Tool	`toolEnabled=true` 的文档解析、报表生成
需要流式或长任务能力	P1 增加异步 / 流式协议	实时语音识别、长视频解析

4. 接入角色与职责

角色	职责
业务线能力负责人	定义能力业务含义、输入输出、使用边界、测试样例和验收标准。
业务线服务研发	提供内部服务接口，或配合实现 Provider Adapter；负责业务结果落库和业务状态流转。
FlowNex 平台研发	维护能力定义、Handler Registry、统一执行器、`control-center` 能力中心和调用治理。
租户管理员	在能力管理后台为租户启用能力、配置连接、模型目标、路由策略并执行连接测试。
运维 / 安全	配置密钥、KMS 或主密钥、网络白名单、监控告警和审计策略。

5. 标准接入流程

5.1 能力盘点与准入评估

业务线接入前需要提交一份能力接入信息：

信息项	说明
能力名称	面向管理员和调用方展示的名称。
能力编码	全局唯一，建议使用领域前缀，例如 `audio.transcription`、`finance.invoice.parse`。
能力分类	音频、图像、文档、视频、审核、生成、业务识别等。
调用模式	同步、异步、流式；P0 优先同步能力。
输入 Schema	调用方需要传入哪些字段，哪些必填，字段约束是什么。
输出 Schema	能力成功后返回的稳定结构。
错误类型	参数错误、配置错误、厂商临时故障、业务拒绝、响应不完整等。
厂商或服务来源	外部厂商、内部业务服务、自研模型服务。
凭证要求	是否需要 API Key、AK/SK、Token、证书或专线。
安全边界	文件来源白名单、大小限制、敏感信息处理、数据留存要求。
验收样例	成功样例、失败样例、边界样例和回归样例。

5.2 定义平台能力

平台侧在 control-center 能力中心维护能力定义。能力定义是调用方可见的稳定契约，Agent 侧只保存必要的能力引用、快照和调用关系。

核心对象：

对象	职责
`CapabilityDefinition`	定义能力编码、名称、分类、输入输出 Schema、契约版本、发布状态和 Tool 元数据。
`CapabilityProvider`	定义该能力支持哪些厂商或业务实现，以及对应的 `adapterKey` 和配置 Schema。
`TenantCapability`	定义某租户是否启用该能力，以及路由策略。
`CapabilityConnection`	定义某租户、某能力、某 Provider 的连接参数和加密凭证。
`CapabilityModelTarget`	定义连接下的模型、默认参数、优先级、权重、超时和重试策略。

能力编码一旦发布，应保持稳定。后续如果输入输出不兼容，应升级 contractVersion，而不是直接破坏旧契约。

5.3 实现能力 Handler 与 Provider Adapter

每个能力需要在 control-center 侧接入执行实现。Capability Gateway、Capability Handler 和 Provider Adapter 都是 control-center 内部实现，不作为独立应用部署。

推荐结构：

层次	职责
Capability Gateway	`control-center` 内部能力调用治理模块，负责路由、鉴权、限流、审计、Trace、降级和错误映射。
Capability Handler	`control-center` 内部能力执行入口，校验平台统一输入并处理能力级业务逻辑。
Provider Adapter	`control-center` 内部 Provider 适配实现，将平台统一协议转换为厂商或业务线服务协议。
Source Gateway	如涉及文件，负责校验短链、Host 白名单、大小、超时和内容类型。
Response Mapper	把厂商或业务线响应转换为平台标准输出。

接入要求：

Handler 不读取 AI 应用业务数据库。
Provider Adapter 不暴露厂商原始响应给调用方。
厂商凭证明文只允许存在于单次调用栈。
不在日志、响应、Trace 中输出 API Key、Token、文件正文或完整 Prompt。
可重试错误和不可重试错误必须明确区分。

5.4 租户启用与连接配置

能力发布后，租户管理员通过能力管理配置能力是否可用。

配置内容包括：

配置项	说明
启用状态	`enabled=true` 后该租户内应用才可调用。
路由策略	P0 常用 `FIXED`；多连接时可使用 `PRIORITY_FAILOVER` 或 `WEIGHTED`。
连接参数	Endpoint、Region、资源 ID、白名单、超时、文件大小限制等。
厂商凭证	提交后由平台 AES-GCM 加密保存，读取时只返回脱敏摘要。
模型目标	模型编码、默认参数、优先级、权重、超时和重试策略。
连接测试	使用管理端测试接口验证配置可用性，并回写健康状态。

5.5 调用方接入

能力调用方分为 AI 应用中心 H5、AI 应用后端任务、Agent Tool 和管理员手工测试。只有 AI 应用中心 H5 与其后端任务会先经过 ai-app-runtime-gateway 和 ai-app-service，再由 control-center 能力中心执行原子能力；现有 Web 前端、飞书、钉钉、主站和管理台侧能力测试仍从 ai-claw-gateway 进入 control-center。

调用方	应用/能力入口	认证方式	适用场景
AI App H5	`POST /application/v1/platform/capabilities/{capabilityCode}/invoke`	`appSession` + 当前可信浏览器身份	经 `ai-app-runtime-gateway` 路由到 `ai-app-service`，用于前端同步调用 OCR、格式转换、内容解析等能力。
AI App Java	`POST /application/internal/v1/platform/capabilities/{capabilityCode}/invoke`	Service Token + 可信业务上下文	经 `ai-app-service` 转入 `control-center`，用于异步任务、重启恢复任务和后台业务编排。
管理员	`POST /api/control-center/admin/capabilities/{capabilityCode}/invoke`	管理员身份	配置验收、排障和手工测试。

H5 目标调用形态：

const result = await flowNex.capabilities.invoke('audio.transcription', {
  audioUrl,
  language: 'zh-CN',
  speakerDiarization: true
});

Java 应用层目标调用形态：

CapabilityInvocationResult result = capabilityPlatformClient.invoke(
    new CapabilityInvocationCommand("audio.transcription", input)
);

调用方不允许传入：

providerCode
modelCode
endpoint
apiKey
厂商私有鉴权参数
OSS 永久 objectKey

这些信息全部由 ai-app-service 和 control-center 能力中心根据租户配置决定。

6. 业务线 AI 能力接入模式

6.1 模式一：业务线已有外部厂商能力

适用于业务线当前直接调用火山、阿里、腾讯、百度、OpenAI、Claude 等外部能力。

接入后变化：

接入前	接入后
业务线保存厂商密钥	能力管理保存并加密厂商密钥
业务线直接拼厂商请求	Provider Adapter 统一转换请求
调用方依赖厂商响应	调用方只依赖平台标准响应
每个应用单独配置厂商	按租户 + 能力 + 连接统一配置
排障依赖应用日志	通过 traceId 串联 Runtime、Handler、Provider

推荐步骤：

抽象稳定能力编码和 Schema。
将厂商参数拆成连接配置、凭证配置和模型参数。
在 control-center 实现 Provider Adapter。
在能力管理中配置租户连接并测试。
改造业务线原调用逻辑，改为 application 路由和 control-center 能力中心调用。

6.2 模式二：业务线已有内部 AI 服务

适用于业务线已经有一个内部 AI HTTP/RPC 服务，例如票据解析、合同审查、客服质检、人事政策问答。

接入方式：

将内部服务视为一个 Provider。
在能力管理中配置内部服务 Endpoint、鉴权 Token、超时、重试策略。
在 control-center 编写 Provider Adapter 调业务线服务。
业务线服务继续保存自己的业务数据，但不再要求调用方感知其私有 API。

注意事项：

内部服务必须支持租户隔离，或由 Provider Adapter 注入可信租户上下文。
内部服务返回结果需要转换为平台标准响应。
内部服务的错误码需要映射为平台错误分类。
不建议让 H5 直接调用业务线内部 AI 服务。

6.3 模式三：AI 应用能力沉淀为平台原子能力

适用于某个 AI 应用中已经实现了可复用能力，例如录音应用里的离线转写。

接入方式：

从应用业务代码中拆出通用能力边界。
应用服务只保留业务受理、任务状态和结果落库。
通用能力迁移为平台 capabilityCode。
应用 Java 后台任务通过 CapabilityPlatformClient 调用能力。

录音离线转写的目标形态：

H5 上传录音文件。
Java 服务创建录音转写任务。
Java 服务向 Runtime 申请平台文件短链。
Java 服务调用 audio.transcription。
control-center 路由到火山 Provider。
标准转写结果返回 Java 服务。
Java 服务转换为录音领域模型并落库。

7. 文件类能力接入要求

如果能力输入涉及文件、图片、音频或视频，应优先使用 FlowNex 文件平台短期 URL，而不是永久 OSS 地址。

要求：

H5 不直接暴露 OSS objectKey。
应用业务库不保存永久物理文件地址。
ai-app-service / 文件平台校验文件归属、租户、用户、应用和命名空间。
Provider Source Gateway 只接受 HTTPS 和白名单 Host。
文件大小、下载超时、Content-Type、扩展名需要在连接配置中明确。
供应商侧短链过期后必须重新申请，不能缓存长期 URL。

8. 错误处理与重试规则

能力接入必须提供稳定错误分类。

错误类别	是否重试	处理规则
认证与上下文错误	否	`ai-app-runtime-gateway` 或 `ai-app-service` 拒绝，不进入 `control-center`。
能力未发布 / 租户未启用	否	返回配置类错误，提示管理员检查能力配置。
输入 Schema 不合法	否	调用方修正参数后重试。
文件来源不可信 / 文件超限	否	Source Gateway 拒绝，避免越权和费用放大。
厂商限流 / 网络超时	是	按 `retryPolicy` 有限重试或切换后备目标。
厂商鉴权失败 / 参数非法	否	停止 failover，避免重复计费。
Provider 响应不完整	否	调用方不得写成功终态，需记录 traceId 排障。

业务线需要在接入时提供失败样例，便于平台完成错误映射和验收。

9. 观测、审计与运营

每次能力调用至少应能通过 traceId 定位：

调用租户、用户、应用、版本和调用方类型。
capabilityCode、contractVersion、Provider、模型目标。
ai-app-runtime-gateway 路由耗时、ai-app-service 应用处理耗时、control-center 执行耗时、Provider 调用耗时。
路由策略、命中连接、是否发生 failover。
标准错误分类和是否 retryable。
Provider taskId 或外部请求 ID。

不得记录：

FlowNex Token
appSession
Runtime Service Token
internalToken
API Key、AK/SK、凭证明文
音频、图片、文档正文
完整 Prompt 或敏感业务输入

运营侧后续可以按租户、应用、能力、Provider、模型和错误类型统计调用量、成功率、平均耗时、P95/P99、失败分布和成本用量。

10. 新能力接入交付物

业务线接入一个新能力时，建议提交以下交付物：

交付物	说明
能力接入申请	能力名称、编码、分类、负责人、适用业务线、调用场景。
输入输出 Schema	JSON Schema 或等价结构说明，包含字段类型、必填、枚举、大小限制。
Provider 说明	厂商或内部服务协议、鉴权方式、超时、限流、错误码。
安全说明	数据是否出域、是否含敏感信息、文件白名单、留存要求。
测试样例	成功、失败、边界、超时、限流、响应缺字段样例。
验收报告	连接测试、手工调用、业务 E2E、异常矩阵、Trace 可定位结果。
回滚方案	能力禁用、连接下线、模型目标切换、业务侧降级策略。

11. 接入验收清单

11.1 平台侧验收

检查项	验收标准
能力定义	`capabilityCode` 全局唯一，Schema 完整，契约版本明确。
Provider 支持	Provider 与 `adapterKey` 配置正确，支持模型和配置 Schema 可读。
租户配置	租户可启用 / 禁用能力，连接和模型目标可维护。
凭证安全	凭证加密落库，详情接口不返回明文，日志无泄露。
连接测试	管理端连接测试可成功，并能回写健康状态。
统一调用	AI 应用中心 H5 / 后端任务通过 `application` 路由和 `ai-app-service` 调用；现有 Web、飞书、钉钉和 FlowNex 主站交互通过 `ai-claw-gateway -> control-center`；两类入口都不直连厂商，原子能力统一进入 `control-center` 能力中心。
错误映射	配置、输入、厂商临时故障、业务拒绝均有稳定错误分类。
Trace	一次调用可通过 traceId 按入口串联 `ai-claw-gateway` 或 `ai-app-runtime-gateway`，并继续关联 `ai-app-service`、`control-center` 和 Provider。

11.2 业务线侧验收

检查项	验收标准
业务结果	平台标准响应能正确转换为业务领域结果。
状态流转	成功、失败、超时、取消、重试后的业务状态明确。
幂等处理	后台异步任务重复调用不会重复写结果或重复计费。
降级策略	能力不可用时有用户可理解的提示或业务降级方案。
数据边界	业务库不保存厂商凭证、FlowNex Token 或永久 OSS objectKey。
回归样例	核心场景进入评测集或自动化测试，支撑后续能力升级。

12. 推荐接入里程碑

阶段	目标	输出
T0 能力评审	确认能力是否适合作为平台原子能力	能力接入申请、Schema 初稿、边界说明
T1 平台建模	完成能力定义、Provider 支持矩阵和租户配置模型	能力定义、Provider 配置、测试租户配置
T2 执行接入	实现 Handler、Provider Adapter、错误映射和 Trace	可手工调用的能力执行链路
T3 业务改造	业务线从直连厂商改为 Runtime 能力调用	H5 / Java 接入代码、业务状态流转
T4 联调验收	跑通真实 E2E 和异常矩阵	验收报告、问题清单、上线确认
T5 生产治理	补齐监控、告警、限流、健康探测和回滚预案	生产配置、告警规则、回滚方案

13. 示例：接入 `audio.transcription`

audio.transcription 是首个已迁移能力，适合作为其他业务线接入模板。

接入项	示例
能力编码	`audio.transcription`
能力含义	输入音频短期 URL，输出全文、时长、Provider 任务 ID 和说话人分段。
调用方	录音 AI 应用 Java 后台任务。
文件来源	通过 FlowNex 文件平台生成面向 Provider 的短期 GET URL。
Provider	`VOLCENGINE`
模型	`bigmodel`
Handler	`AudioTranscriptionCapabilityHandler`
关键边界	火山 API Key 来自能力连接密文，不来自录音应用配置。
业务落库	录音应用只保存转写结果和任务状态，不保存厂商凭证。

标准请求：

{
  "input": {
    "audioUrl": "https://short-lived-file-url/example.ogg",
    "fileName": "meeting.ogg",
    "contentType": "audio/ogg",
    "language": "zh-CN",
    "speakerDiarization": true
  }
}

标准响应：

{
  "capabilityCode": "audio.transcription",
  "providerCode": "VOLCENGINE",
  "modelCode": "bigmodel",
  "data": {
    "text": "这是火山引擎语音识别测试。",
    "durationMs": 1000,
    "providerTaskId": "asr_xxx",
    "segments": [
      {
        "segmentId": "asr_xxx_0",
        "speaker": "speaker_0",
        "startMs": 0,
        "endMs": 1000,
        "text": "这是火山引擎语音识别测试。"
      }
    ]
  },
  "traceId": "trace_xxx"
}

14. 业务线接入 FAQ

14.1 是否需要为每个 AI 应用绑定能力？

不需要。FlowNex 当前方案不建设应用与能力绑定表。只要当前租户已发布并启用该能力，应用通过可信 appSession 或 Service Token 即可调用。

14.2 业务线能否继续直接调用厂商？

新增和迁移场景不建议继续直连。统一接入能力管理后，厂商凭证、路由、模型、错误、Trace、审计和后续用量统计才能统一治理。

14.3 多个业务线使用同一个厂商密钥怎么办？

不建议共享明文密钥。能力管理按“租户 + 能力 + 连接”保存加密凭证。即使同一厂商用于不同能力，也应使用各自独立连接和密钥摘要。

14.4 能力配置变化是否需要重新发布 AI 应用？

不需要。应用版本与能力配置解耦。能力调用时由 control-center 读取当前租户能力配置，因此修改连接、模型目标或路由策略不生成应用新版本。

14.5 业务线已有异步长任务怎么办？

P0 同步能力优先。对于长任务、流式或回调型能力，建议先按同步包装可控场景；P1 再引入 executionMode、taskId、callback / poll、SSE 或 WebSocket 协议。

14.6 能力能否暴露给 Agent 自动调用？

可以作为 P1 演进。能力定义中已有 Tool 元数据预留，后续通过 Capability Tool Registry 将已发布且租户启用的能力暴露给 LangGraph Tool Registry，但最终执行仍回到 control-center 能力中心的统一能力执行器。