14. 接口参考

API Reference 描述 FlowNex 对外和内部主要 API 分类。具体字段以各服务 client DTO 和 OpenAPI 文档为准，本章先定义接口边界和职责。

14.1 Conversation API

Conversation API 用于管理会话。

典型能力：

  1. 创建会话。
  2. 查询会话列表。
  3. 查询会话详情。
  4. 删除会话。
  5. 更新会话标题或配置。
  6. 查询会话上下文。

主要消费者：

  1. Web 客户端。
  2. 管理台。
  3. 渠道入站编排。

14.2 Task API

Task API 用于管理任务。

典型能力：

  1. 创建任务。
  2. 查询任务状态。
  3. 查询任务步骤。
  4. 取消任务。
  5. 更新任务结果。
  6. 查询任务文件。
  7. 查询任务回放。

Task API 是连接对话、runtime 和审计的核心 API。

14.3 Message API

Message API 用于管理用户消息和 Agent 回复。

典型能力：

  1. 创建用户消息。
  2. 创建 Agent 回复。
  3. 查询消息列表。
  4. 查询消息详情。
  5. 写入消息状态。
  6. 写入用户反馈。
  7. 关联消息附件。

Message API 中的 bizFeatures 可保存本轮业务扩展信息，例如知识库选择、反馈摘要、HITL 表单等。

14.4 Skill API

Skill API 用于管理 Skill。

典型能力：

  1. 查询 Skill 市场。
  2. 查询我的 Skill。
  3. 创建 Skill 草稿。
  4. 更新 Skill 草稿。
  5. 提交审核。
  6. 审核通过或拒绝。
  7. 安装 Skill。
  8. 启用或停用 Skill。
  9. 配置 Skill 预装。
  10. 查询 Skill 使用情况。

后续应增加：

  1. Skill 版本 API。
  2. Skill 评测 API。
  3. Skill 灰度 API。
  4. Skill 知识绑定 API。

14.5 Knowledge API

Knowledge API 用于知识库查询、映射和检索。

普通用户能力：

  1. 查询我可访问的知识库。
  2. 发起知识检索。
  3. 查询知识引用。

管理员能力：

  1. 创建本地知识资产映射。
  2. 更新知识资产状态。
  3. 配置知识可见范围。
  4. 查询知识命中统计。
  5. 管理 Skill 与知识绑定。

运行时能力：

  1. 使用 knowledgeAccess 发起限定范围检索。
  2. 回传知识命中轨迹。

14.6 Runtime API

Runtime API 连接 agent-runtime-gateway 和 share-harness。

典型能力：

  1. 初始化会话。
  2. 发起 infer。
  3. 变更模型。
  4. 变更 Agent 风格。
  5. 查询 runtime 健康状态。
  6. 接收 runtime 事件。

Runtime 请求应包含：

  1. conversationId。
  2. taskId。
  3. message。
  4. files。
  5. toolCodes。
  6. skillCodes。
  7. knowledgeAccess。
  8. channelType。
  9. messageBusinessType。
  10. 必要的用户访问 token。

14.7 AGFS API

AGFS API 用于文件系统访问和管理。

核心 API：

  1. 创建 Space。
  2. 创建 Mount。
  3. 查询文件状态。
  4. 读取文件。
  5. 写入文件。
  6. 查询目录。
  7. 删除文件。
  8. 创建 checkpoint。
  9. 回滚 checkpoint。
  10. 查询文件版本。
  11. 恢复文件版本。

AGFS API 应同时服务 MCP、Shell、FUSE 和业务管理台。

14.8 Admin API

Admin API 面向管理员。

典型能力：

  1. 用户管理。
  2. 角色管理。
  3. 权限管理。
  4. Skill 审核。
  5. 知识库管理。
  6. 能力包管理。
  7. 模型配置。
  8. Runtime 配置。
  9. 运营报表。
  10. 审计查询。

Admin API 必须有严格权限控制和审计日志。

14.9 Callback API

Callback API 用于 runtime 和异步系统回调业务层。

典型回调：

  1. 任务开始。
  2. 任务进度。
  3. Task Step 创建或更新。
  4. 文件产物生成。
  5. 任务完成。
  6. 任务失败。
  7. 知识命中回传。
  8. AGFS 文件事件。
  9. 多 Agent 子任务事件。

Callback API 应保证幂等，避免 runtime 重试导致重复写入。

14.10 Capability API

Capability API 用于业务线 AI 应用和原子化 AI 能力接入 FlowNex 后的统一注册、授权、调用和观测。

管理侧能力：

  1. 注册 Capability。
  2. 更新 Capability 元数据。
  3. 管理 Capability 版本。
  4. 定义输入输出 Schema。
  5. 绑定 Provider。
  6. 配置 Provider Adapter。
  7. 配置租户、部门、角色可见范围。
  8. 配置限流、超时、重试和降级策略。
  9. 查询能力调用统计。
  10. 查询能力回归测试结果。

运行时能力：

  1. 查询本轮可用 Capability 快照。
  2. 发起 Capability 调用。
  3. 查询调用状态。
  4. 回传调用 Trace。
  5. 回传错误映射和降级结果。

典型调用请求：

{
  "traceId": "trace-001",
  "tenantCode": "xy",
  "taskId": "task-10001",
  "capabilityCode": "invoice_ocr_extract",
  "capabilityVersion": "1.0.0",
  "providerCode": "finance_ai",
  "input": {
    "fileId": "agfs://space/file-node"
  }
}

典型返回：

{
  "success": true,
  "capabilityCode": "invoice_ocr_extract",
  "providerCode": "finance_ai",
  "output": {
    "invoiceNo": "12345678",
    "amount": "1024.00"
  },
  "durationMs": 860,
  "trace": {
    "adapterCode": "finance_ai_http_adapter",
    "retryCount": 0,
    "schemaVersion": "1.0.0"
  }
}

Capability API 的关键要求：

  1. 所有调用必须绑定 tenantCode、taskId 和 traceId。
  2. runtime 不直接持有 Provider 密钥。
  3. 输入输出必须符合 Schema。
  4. 错误码必须映射为平台统一错误。
  5. 高风险能力需要支持 HITL 或二次确认。
  6. 调用记录必须进入任务轨迹和审计日志。