add
This commit is contained in:
V-LiuShuang committed
1 parent
a18d11ea91
commit
63e9839b3b
1 file changed
+229
+229
@@ -0,0 +1,229 @@
|
|||||||
|
# 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 的并发请求。
|
||||||
Reference in new issue
Block a user