doc/tmp

0 Fork 0

Files

T

V-LiuShuang 63e9839b3b add

2026-09-23 13:58:45 +08:00

8.3 KiB

Raw Blame History

MIS-Paw 开放 API 使用文档

面向外部接入系统的开发者。当前提供文件上传和 Agent 对话两个接口。

API 根地址示例：https://misagent.lcfuturecenter.com

1. 快速开始

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

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

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	要上传的文件

示例：

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/1.1 200 OK
Content-Type: application/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 请求体

{
  "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，并在响应头返回：

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":[]}'

成功响应头：

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：

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 错误结构：

{
  "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. 文件+对话完整流程

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

# 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 响应头：

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 的并发请求。

8.3 KiB Raw Blame History Unescape Escape