# 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 判断业务，不依赖协议本身，支持其他协议的扩展