初始化
This commit is contained in:
418
easyflow-chat-protocol.md
Normal file
418
easyflow-chat-protocol.md
Normal file
@@ -0,0 +1,418 @@
|
||||
|
||||
|
||||
# EasyFlow Chat Protocol Specification v1.1
|
||||
|
||||
* **Protocol Name:** `easyflow-chat`
|
||||
* **Version:** `1.1`
|
||||
* **Status:** Draft / Recommended
|
||||
* **Transport:** Server-Sent Events (SSE)
|
||||
* **Encoding:** UTF-8
|
||||
|
||||
|
||||
|
||||
## 1. 设计背景与目标
|
||||
|
||||
本协议用于描述 **EasyFlow 对话系统中的服务端事件流通信规范**，支持：
|
||||
|
||||
* AI 对话的 **流式输出**
|
||||
* 模型 **思考过程（Thinking）**
|
||||
* **工具调用（Tool Calling）**
|
||||
* **系统 / 业务错误**
|
||||
* **工作流 / Agent 状态**
|
||||
* **对话中的用户交互（表单、确认等）**
|
||||
* **中断与恢复（Suspend / Resume）**
|
||||
|
||||
设计目标：
|
||||
|
||||
* 前后端解耦
|
||||
* 协议长期可扩展
|
||||
* 不绑定具体模型厂商
|
||||
* 易于与 Workflow / Agent / Chain 架构集成
|
||||
|
||||
|
||||
|
||||
## 2. 传输层规范（Transport）
|
||||
|
||||
* 使用 HTTP + SSE（支持未来扩展为其他协议，比如 WebSocket 等）
|
||||
* Response Header：
|
||||
|
||||
```http
|
||||
Content-Type: text/event-stream
|
||||
Cache-Control: no-cache
|
||||
Connection: keep-alive
|
||||
```
|
||||
* 通信方向：**Server → Client**
|
||||
* 所有业务数据通过 `data` 字段传输，格式为 **JSON 字符串**
|
||||
|
||||
|
||||
|
||||
## 3. SSE Event 级别规范
|
||||
|
||||
### 3.1 Event Name（固定）
|
||||
|
||||
| event | 含义 |
|
||||
| - |-------|
|
||||
| message | 正常业务事件 |
|
||||
| error | 错误事件 |
|
||||
| done | 流结束事件 |
|
||||
|
||||
> ⚠️ **禁止在 event name 中承载业务语义**
|
||||
|
||||
|
||||
|
||||
## 4. 统一 Envelope 结构（核心）
|
||||
|
||||
### 4.1 基本结构
|
||||
|
||||
```json
|
||||
{
|
||||
"protocol": "easyflow-chat",
|
||||
"version": "1.1",
|
||||
"domain": "llm | tool | system | business | workflow | interaction | debug",
|
||||
"type": "string",
|
||||
"conversation_id": "string",
|
||||
"message_id": "string",
|
||||
"index": 0,
|
||||
"payload": {},
|
||||
"meta": {}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 4.2 字段说明
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
| -- |---------| -- |------------------------|
|
||||
| protocol | string | ✔ | 固定值 `easyflow-chat` |
|
||||
| version | string | ✔ | 协议版本 |
|
||||
| domain | string | ✔ | 事件所属领域 |
|
||||
| type | string | ✔ | 领域内事件类型 |
|
||||
| conversation_id | string | ✔ | 会话唯一标识 |
|
||||
| message_id | string | ✖ | assistant 消息 ID |
|
||||
| index | number | ✖ | 流式输出序号 |
|
||||
| payload | object | ✔ | 事件数据 |
|
||||
| meta | object | ✖ | 元信息（token、耗时等） |
|
||||
|
||||
|
||||
|
||||
## 5. Domain 定义
|
||||
|
||||
| Domain | 说明 |
|
||||
| -- | -- |
|
||||
| llm | 模型语义输出 |
|
||||
| tool | 工具调用与结果 |
|
||||
| system | 系统级事件 |
|
||||
| business | 业务规则 |
|
||||
| workflow | 工作流 / Agent 状态 |
|
||||
| interaction | 用户交互（表单等） |
|
||||
| debug | 调试信息 |
|
||||
|
||||
|
||||
|
||||
## 6. llm Domain
|
||||
|
||||
### 6.1 thinking
|
||||
|
||||
表示模型的思考过程。
|
||||
|
||||
#### 流式输出（delta）
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "llm",
|
||||
"type": "thinking",
|
||||
"payload": {
|
||||
"delta": "分析用户需求"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 完整输出（可选）
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "llm",
|
||||
"type": "message",
|
||||
"payload": {
|
||||
"content": "这是一个完整的回答"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### 6.2 message
|
||||
|
||||
#### 流式输出（delta）
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "llm",
|
||||
"type": "message",
|
||||
"index": 12,
|
||||
"payload": {
|
||||
"delta": "这是一个"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 完整输出（可选）
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "llm",
|
||||
"type": "message",
|
||||
"payload": {
|
||||
"content": "这是一个完整的回答"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 7. tool Domain
|
||||
|
||||
### 7.1 tool_call
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "tool",
|
||||
"type": "tool_call",
|
||||
"payload": {
|
||||
"tool_call_id": "call_1",
|
||||
"name": "search",
|
||||
"arguments": {
|
||||
"query": "SSE 协议设计"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 7.2 tool_result
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "tool",
|
||||
"type": "tool_result",
|
||||
"payload": {
|
||||
"tool_call_id": "call_1",
|
||||
"status": "success | error",
|
||||
"result": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 8. system Domain
|
||||
|
||||
### 8.1 error
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "system",
|
||||
"type": "error",
|
||||
"payload": {
|
||||
"code": "MODEL_CONFIG_INVALID",
|
||||
"message": "模型配置错误",
|
||||
"retryable": false,
|
||||
"detail": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 8.2 status
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "system",
|
||||
"type": "status",
|
||||
"payload": {
|
||||
"state": "initializing | running | suspended | resumed"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 9. business Domain
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "business",
|
||||
"type": "error",
|
||||
"payload": {
|
||||
"code": "QUOTA_EXCEEDED",
|
||||
"message": "配额不足"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 10. workflow Domain
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "workflow",
|
||||
"type": "status",
|
||||
"payload": {
|
||||
"node_id": "node_1",
|
||||
"state": "start | suspend | resume | end",
|
||||
"reason": "interaction"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 11. interaction Domain（对话内交互）
|
||||
|
||||
### 11.1 form_request
|
||||
|
||||
表示请求用户填写表单，对话进入挂起状态。
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "interaction",
|
||||
"type": "form_request",
|
||||
"payload": {
|
||||
"form_id": "user_info_form",
|
||||
"title": "补充信息",
|
||||
"description": "请填写以下信息以继续",
|
||||
"schema": {
|
||||
"type": "object",
|
||||
"required": ["age", "email"],
|
||||
"properties": {
|
||||
"age": {
|
||||
"type": "number",
|
||||
"title": "年龄"
|
||||
},
|
||||
"email": {
|
||||
"type": "string",
|
||||
"title": "邮箱",
|
||||
"format": "email"
|
||||
}
|
||||
}
|
||||
},
|
||||
"ui": {
|
||||
"submit_text": "继续",
|
||||
"cancel_text": "取消"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 表单 schema **符合 JSON Schema 标准**
|
||||
|
||||
|
||||
|
||||
### 11.2 form_cancel
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "interaction",
|
||||
"type": "form_cancel",
|
||||
"payload": {
|
||||
"form_id": "user_info_form"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 12. 表单提交与恢复（非 SSE）
|
||||
|
||||
表单提交通过 **普通 HTTP / WebSocket 请求**：
|
||||
|
||||
```json
|
||||
{
|
||||
"conversation_id": "conv_1",
|
||||
"form_id": "user_info_form",
|
||||
"values": {
|
||||
"age": 30,
|
||||
"email": "a@b.com"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
成功后服务端恢复 SSE 流。
|
||||
|
||||
|
||||
|
||||
## 13. done 事件（流结束）
|
||||
|
||||
```json
|
||||
{
|
||||
"domain": "system",
|
||||
"type": "done",
|
||||
"meta": {
|
||||
"prompt_tokens": 1234,
|
||||
"completion_tokens": 456,
|
||||
"latency_ms": 2300
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 14. 错误处理规则
|
||||
|
||||
* 收到 `event: error` 后客户端应终止流
|
||||
* 错误语义由：
|
||||
|
||||
```
|
||||
domain + type + payload.code
|
||||
```
|
||||
|
||||
共同决定
|
||||
|
||||
|
||||
|
||||
## 15. 状态机视角（推荐）
|
||||
|
||||
```text
|
||||
RUNNING
|
||||
↓
|
||||
LLM_OUTPUT
|
||||
↓
|
||||
INTERACTION_REQUESTED
|
||||
↓
|
||||
SUSPENDED
|
||||
↓
|
||||
FORM_SUBMITTED
|
||||
↓
|
||||
RESUMED
|
||||
↓
|
||||
RUNNING
|
||||
↓
|
||||
DONE
|
||||
```
|
||||
|
||||
|
||||
|
||||
## 16. 扩展与兼容规则
|
||||
|
||||
1. 可新增 domain
|
||||
2. 可新增 type
|
||||
3. 不允许删除已有字段
|
||||
4. payload 可自由扩展
|
||||
5. 1.x 版本保持向后兼容
|
||||
|
||||
|
||||
|
||||
## 17. 设计原则
|
||||
|
||||
> * SSE 只负责事件流
|
||||
> * domain 定义责任边界
|
||||
> * type 定义语义动作
|
||||
> * payload 定义数据结构
|
||||
> * 前端不依赖 event name 判断业务，不依赖协议本身，支持其他协议的扩展
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user