tmp/chat-openapi.md

# MIS-Paw 开放 API 使用文档

> 面向外部接入系统的开发者。当前提供文件上传和 Agent 对话两个接口。
>
> API 根地址示例：`https://misagent.lcfuturecenter.com`

## 1. 快速开始

外部系统只需要使用 MIS-Paw 管理页面创建的完整 API Key。API Key 会唯一定位一个 Agent，因此请求中不需要传 `agentId`。

对外接口不要求登录态，也不要求 `Authorization`、`Clientid` 或 `Subsystem`。两个接口都必须携带：

```http
X-Paw-Api-Key: <完整 API Key>
```

API Key 必须通过 HTTPS 传输，不要写入日志、前端源码、URL 查询参数或错误信息。管理页面列表中的 Key 可能被掩码显示，调用时请复制完整值。

## 2. 接口总览

| 方法 | 路径 | 用途 | 请求类型 | 成功响应 |
|---|---|---|---|---|
| `POST` | `/api/files/upload` | 上传 Agent 对话附件 | `multipart/form-data` | JSON |
| `POST` | `/api/shareChat` | 调用 Agent 对话 | `application/json` | SSE |

网关和服务部署在带有统一前缀的环境时，将前缀拼接到上述路径前。例如实际地址可能是 `/paw/api/shareChat`；请以部署环境提供的 API 根地址为准。

## 3. 文件上传：`POST /api/files/upload`

### 3.1 请求

请求头：

| Header | 必填 | 值 |
|---|---:|---|
| `X-Paw-Api-Key` | 是 | 当前 Agent 的完整 API Key |
| `Content-Type` | 自动 | `multipart/form-data`，由 HTTP 客户端自动生成 boundary |

表单字段：

| 字段 | 必填 | 类型 | 说明 |
|---|---:|---|---|
| `file` | 是 | Binary | 要上传的文件 |

示例：

```bash
curl --fail-with-body -X POST "https://misagent.lcfuturecenter.com/api/files/upload" \
  -H "X-Paw-Api-Key: <完整 API Key>" \
  -F "file=@./demo.txt"
```

不要手动设置 `Content-Type: multipart/form-data`，否则可能缺少 boundary；让 curl、浏览器或 SDK 自动设置。

### 3.2 成功响应

```http
HTTP/1.1 200 OK
Content-Type: application/json
```

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "url": "/root/output/paw15004/.qwenpaw/workspaces/9U5Y2t5/media/1b3e01157eb74bb39c0329dc47d6235c_demo.txt",
    "fileName": "demo.txt",
    "fileSize": 84757
  }
}
```

`data.url` 是 QwenPaw 当前 Agent Workspace `media` 目录中的文件引用。它是不透明值，调用方必须完整保存并在对话请求中原样传回，不要拼接、截断、URL 解码后重组或自行构造本地路径。

文件上传调用不依赖缓存头完成业务处理；部署环境如配置了响应缓存策略，应将该响应设置为 `Cache-Control: no-store`。

上传接口不创建 Session，也不返回 `X-Paw-Session-Id`。文件真正被对话使用后，才会按 QwenPaw 原生机制进入聊天文件记录。

## 4. Agent 对话：`POST /api/shareChat`

### 4.1 请求头

| Header | 必填 | 说明 |
|---|---:|---|
| `X-Paw-Api-Key` | 是 | 定位 Agent 并完成 API Key 鉴权 |
| `X-Paw-Session-Id` | 否 | 续聊时传上一次响应中的值；首次请求可省略 |
| `Accept` | 否 | 推荐 `text/event-stream`；缺少时默认为 SSE。当前仅支持流式，不支持 `application/json` |
| `Content-Type` | 是 | `application/json` |

本接口不要求 `Authorization`、`Clientid`、`Subsystem`。不要把 API Key 或 Session ID 放在 URL 查询参数中。

### 4.2 请求体

```json
{
  "message": "这个文件内容是什么",
  "files": [
    {
      "url": "/root/output/paw15004/.qwenpaw/workspaces/9U5Y2t5/media/1b3e01157eb74bb39c0329dc47d6235c_demo.txt",
      "fileName": "demo.txt",
      "fileSize": 84757
    }
  ]
}
```

字段说明：

| 字段 | 必填 | 类型 | 说明 |
|---|---:|---|---|
| `message` | 是 | String | 用户消息；去除首尾空白后不能为空，即使只提问文件也必须填写 |
| `files` | 否 | Array | 文件引用列表；不传等同于空数组 |
| `files[].url` | 是（每个文件） | String | `/api/files/upload` 成功响应中的 `data.url`，必须原样传回 |
| `files[].fileName` | 是（每个文件） | String | 上传响应中的 `data.fileName` |
| `files[].fileSize` | 是（每个文件） | Long | 上传响应中的 `data.fileSize`，单位为字节 |

对外 DTO 不接收 `agentId`、`userId`、`sessionId`、`channel`、`stream` 或 QwenPaw Runtime 私有字段。

## 5. 流式对话（SSE）

### 5.1 首次请求

省略 `X-Paw-Session-Id`，服务端会按 QwenPaw Console 规则生成 Session ID，并在响应头返回：

```bash
curl -N --fail-with-body -X POST "https://misagent.lcfuturecenter.com/api/shareChat" \
  -H "X-Paw-Api-Key: <完整 API Key>" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"message":"你好","files":[]}'
```

成功响应头：

```http
Content-Type: text/event-stream;charset=UTF-8
Cache-Control: no-cache, no-transform
X-Paw-Session-Id: 1788156264286
```

响应体是现有 QwenPaw Console Chat 的 SSE 事件流，事件顺序和结束语义保持一致。客户端应按标准 SSE 读取 `data:` 事件，不要假设每一帧都是完整的最终答案。

### 5.2 续聊

保存首次响应的 `X-Paw-Session-Id`，后续请求用同一个 API Key 和同一个 Session ID：

```bash
curl -N --fail-with-body -X POST "https://misagent.lcfuturecenter.com/api/shareChat" \
  -H "X-Paw-Api-Key: <完整 API Key>" \
  -H "X-Paw-Session-Id: 1788156264286" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"message":"继续说明","files":[]}'
```

Session ID 是会话上下文标识，不是 API Key，也不是登录凭证。接入系统应按自己的用户或业务会话保存它；不同 API Key 不要主动共享同一个 Session ID。同一个 Session 同时只能有一个进行中的对话请求，否则可能返回 `409 SESSION_BUSY`。

## 6. 错误处理

建连前的错误通常返回 MIS 统一 JSON 错误结构：

```json
{
  "code": 401,
  "msg": "API Key 无效或已过期",
  "data": null,
  "errorCode": "API_KEY_INVALID"
}
```

常见状态码：

| HTTP | 场景 |
|---:|---|
| `400` | `message` 为空、文件元数据缺失或 Session 格式不合法 |
| `401` | 缺少、无效或已过期的 `X-Paw-Api-Key` |
| `403` | API Key 已停用，或文件不属于该 Key 定位的 Agent Workspace |
| `406` | `Accept` 不支持 |
| `409` | 同一个 Agent/Session 已有进行中的 Chat |
| `413` | 文件超过配置的大小限制 |
| `422` | Agent 创建人的模型 Key 不可用 |
| `503` | Agent 或 QwenPaw 实例不可用 |

如果 SSE 已经开始，之后发生的 Agent 错误仍以 SSE 事件返回，不会中途切换成 JSON。客户端需要同时处理 HTTP 建连错误和 SSE 错误事件。

## 7. 文件+对话完整流程

1. 使用 `X-Paw-Api-Key` 调用 `/api/files/upload`。
2. 保存响应中的 `data.url`、`data.fileName`、`data.fileSize`。
3. 调用 `/api/shareChat`，将这三个值放入 `files`，并填写 `message`。
4. 保存响应头 `X-Paw-Session-Id`。
5. 后续续聊时使用同一个 API Key，并回传保存的 Session ID。

```bash
# 1. 上传文件
curl -sS -X POST "https://misagent.lcfuturecenter.com/api/files/upload" \
  -H "X-Paw-Api-Key: <完整 API Key>" \
  -F "file=@./demo.txt"

# 2. 使用上传返回的 url 对话
curl -N -X POST "https://misagent.lcfuturecenter.com/api/shareChat" \
  -H "X-Paw-Api-Key: <完整 API Key>" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "这个文件内容是什么",
    "files": [{
      "url": "<上一步 data.url>",
      "fileName": "demo.txt",
      "fileSize": 84757
    }]
  }'
```

## 8. 浏览器跨域调用

如果由浏览器直接调用，预检请求不需要 API Key，但实际 `POST` 必须携带。前端需要能够读取 `X-Paw-Session-Id`，服务端跨域配置应允许以下请求头并暴露 Session 响应头：

```text
Allowed-Headers: Content-Type, Accept, X-Paw-Api-Key, X-Paw-Session-Id
Exposed-Headers: X-Paw-Session-Id, Content-Type, Cache-Control
```

不要在浏览器端把完整 API Key 固化到公开前端代码中；更适合由受控的后端接入系统代理调用。

## 9. 重试与费用提示

一期没有 HTTP 请求级幂等键。客户端在未收到完整响应时重试，可能重新启动一次 Agent 对话并产生新的模型费用；只有同一 Session 尚未结束时，才可能收到 `409 SESSION_BUSY`。请由调用方控制超时、重试次数和同一 Session 的并发请求。