197 lines
6.4 KiB
Markdown
197 lines
6.4 KiB
Markdown
# 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 鉴权管理
|
||
支持两种鉴权方式，通过配置文件切换：
|
||
1. **PAT (Personal Access Token)**: 适用于内部系统后台调用，长期有效。
|
||
2. **OAuth JWT**: 适用于需要代表不同用户身份调用的场景（高阶需求）。
|
||
|
||
*参考文档*: [OAuth JWT 授权](https://www.coze.cn/open/docs/developer_guides/oauth_jwt)
|
||
|
||
#### 2.2.2 智能对话 (Chat)
|
||
支持与指定 Bot 进行交互。
|
||
- **非流式**: 等待完整回复后返回。
|
||
- **流式 (Streaming)**: 使用 Server-Sent Events (SSE) 实时推送 Token，提升用户体验。
|
||
|
||
**接口地址**: `POST /chat`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"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"}
|
||
]
|
||
}
|
||
```
|
||
|
||
**响应示例 (非流式)**:
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"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。
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.coze</groupId>
|
||
<artifactId>coze-api</artifactId>
|
||
<version>0.4.2</version> <!-- 请检查 Maven Central 获取最新版本 -->
|
||
</dependency>
|
||
```
|
||
|
||
### 3.3 配置文件
|
||
在 `application.yml` 中配置：
|
||
|
||
```yaml
|
||
coze:
|
||
api:
|
||
base-url: https://api.coze.cn
|
||
token: ${COZE_API_TOKEN} # 优先使用环境变量
|
||
connect-timeout: 30000
|
||
read-timeout: 60000
|
||
```
|
||
|
||
### 3.4 异常处理
|
||
需捕获 SDK 抛出的异常并转换为标准 HTTP 响应：
|
||
- `CozeClientException`: 客户端错误 (配置、网络) -> 500
|
||
- `CozeServiceException`: 服务端错误 (参数、权限) -> 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. 验收标准
|
||
1. Chat 接口能正确响应 Bot 回复。
|
||
2. Workflow 能执行并返回 JSON 结果。
|
||
3. 流式请求能通过 SSE 逐步输出内容。
|
||
4. 异常情况下能返回友好的错误信息，不暴露堆栈。
|