6.4 KiB
6.4 KiB
Coze API Java 集成产品需求文档 (PRD)
扣子团队版
1. 产品概述
1.1 产品背景
Coze (扣子) 是一个强大的 AI Agent 开发平台，支持用户快速构建基于大语言模型的各类 Bot 和 Workflow。为了将 Coze 平台构建的智能体能力接入到我们的 Java 后端系统中，实现业务流程自动化和智能对话功能，本项目计划集成 Coze Open API。
1.2 产品定位
为内部系统和第三方应用提供统一的 Coze 能力接入网关，屏蔽底层 API 细节，提供标准化的 Java 接口和 RESTful API，支持对话（Chat）、工作流（Workflow）和文件上传等核心功能。
1.3 目标用户
- 内部业务系统开发团队
- 需要接入 AI 客服/助手的前端应用
- 自动化任务流程设计者
2. 核心功能需求
2.1 功能模块概览
| 功能模块 | 描述 | 优先级 | 备注 |
|---|---|---|---|
| 鉴权管理 (Auth) | 支持 PAT (个人访问令牌) 和 OAuth JWT 两种模式 | P0 | 初期使用 PAT 快速接入 |
| 智能对话 (Chat) | 与 Coze Bot 进行多轮对话，支持流式 (SSE) / 非流式响应 | P0 | 核心交互能力 |
| 工作流执行 (Workflow) | 调用 Coze 定义的工作流，处理复杂业务逻辑 | P0 | 业务自动化 |
| 文件上传 (File) | 上传图片或文档，用于多模态对话或工作流输入 | P1 | 支持多模态 |
| 语音交互 (Voice) | 文本转语音 (TTS) / 语音转文本 (ASR) | P2 | 依赖 SDK WebSocket 能力 |
2.2 API 接口设计
2.2.1 鉴权管理
支持两种鉴权方式，通过配置文件切换：
- PAT (Personal Access Token): 适用于内部系统后台调用，长期有效。
- OAuth JWT: 适用于需要代表不同用户身份调用的场景（高阶需求）。
参考文档: OAuth JWT 授权
2.2.2 智能对话 (Chat)
支持与指定 Bot 进行交互。
- 非流式: 等待完整回复后返回。
- 流式 (Streaming): 使用 Server-Sent Events (SSE) 实时推送 Token，提升用户体验。
接口地址: POST /chat
请求参数:
{
"bot_id": "730454116184516****", // Coze Bot ID
"user_id": "user_123", // 业务系统用户ID
"query": "帮我写一个 Java 冒泡排序", // 用户输入
"stream": true, // true: 返回 SSE 流; false: 返回 JSON
"chat_history": [ // (可选) 历史上下文
{"role": "user", "content": "你好", "content_type": "text"},
{"role": "assistant", "content": "你好！", "content_type": "text"}
]
}
响应示例 (非流式):
{
"code": 200,
"data": {
"conversation_id": "737999610479815****",
"messages": [
{
"role": "assistant",
"type": "answer",
"content": "当然，这是 Java 冒泡排序的代码...",
"content_type": "text"
}
],
"usage": {
"token_count": 150
}
}
}
响应示例 (流式):
Content-Type: text/event-stream
data: {"event":"message", "content":"当然", "is_finish":false}
data: {"event":"message", "content":"，", "is_finish":false}
...
data: {"event":"done", "usage":{...}}
2.2.3 工作流执行 (Workflow)
触发 Coze 预定义的工作流。
接口地址: POST /workflow/run
请求参数:
{
"workflow_id": "73505836754923****",
"parameters": {
"input_text": "分析文本",
"input_image": "https://example.com/img.jpg"
}
}
2.2.4 文件上传
上传文件到 Coze 平台，获取 file_id。
接口地址: POST /file/upload
Content-Type: multipart/form-data
请求参数:
file: (Binary) 文件内容
3. 技术实现规范
3.1 项目结构
在 com.integration.api 包下扩展 Coze 相关模块：
models-integration/
├── src/main/java/com/integration/api/
│ ├── config/
│ │ └── CozeConfig.java # Coze Client Bean 配置
│ ├── controller/
│ │ └── CozeController.java # 对外 API 接口 (REST)
│ ├── service/
│ │ ├── CozeService.java # 业务逻辑接口
│ │ └── impl/
│ │ └── CozeServiceImpl.java # 调用 Coze SDK 实现
│ ├── dto/
│ │ ├── coze/
│ │ ├── CozeChatRequest.java # 请求 DTO
│ │ └── CozeBaseResponse.java # 统一响应 DTO
│ └── utils/
│ └── SseEmitterUtil.java # SSE 推送工具类
3.2 依赖管理
使用 Coze 官方 Java SDK。
<dependency>
<groupId>com.coze</groupId>
<artifactId>coze-api</artifactId>
<version>0.4.2</version> <!-- 请检查 Maven Central 获取最新版本 -->
</dependency>
3.3 配置文件
在 application.yml 中配置：
coze:
api:
base-url: https://api.coze.cn
token: ${COZE_API_TOKEN} # 优先使用环境变量
connect-timeout: 30000
read-timeout: 60000
3.4 异常处理
需捕获 SDK 抛出的异常并转换为标准 HTTP 响应：
CozeClientException: 客户端错误 (配置、网络) -> 500CozeServiceException: 服务端错误 (参数、权限) -> 400/401/429- 401: Token 无效
- 429: Rate Limit Exceeded (需实现重试机制)
4. 非功能需求
4.1 安全性
- Token 不得提交到代码仓库。
- 生产环境建议使用 OAuth JWT 模式以获得更细粒度的权限控制。
4.2 性能与稳定性
- 连接池: 使用 OkHttp 连接池复用连接。
- 流式响应: Chat 接口必须支持 SSE，避免长轮询等待。
- 超时控制: 明确设置 ReadTimeout，防止请求挂起。
4.3 可观测性
- 记录每次调用的
conversation_id和log_id(SDK 返回)，便于排查问题。 - 监控 Token 消耗量 (Usage)。
5. 项目里程碑
5.1 第一阶段 (MVP)
- 引入 Coze SDK (v0.4.2+)。
- 接入 OAuth JWT 授权流程
- 实现文件上传接口。
- 实现 Workflow 接口。
- 实现基础 Chat 接口 (非流式)。
- 实现 SSE 流式 Chat 接口。
6. 验收标准
- Chat 接口能正确响应 Bot 回复。
- Workflow 能执行并返回 JSON 结果。
- 流式请求能通过 SSE 逐步输出内容。
- 异常情况下能返回友好的错误信息，不暴露堆栈。