agent-Specialization/api_doc

API v1 接入文档（多工作区 + 后台任务 + 轮询进度）

本目录面向第三方/多端（Web、Flutter、脚本、其它服务）对接，目标是：

• API 调用不依赖 WebSocket：网页刷新/断网/关闭不会影响后台任务运行；
• 客户端使用 HTTP 轮询获取与网页端一致的细粒度进度（token 输出、工具块、工具结果等）；
• API 账号与网页账号隔离：避免互相抢占任务/文件/对话状态。
• 多工作区并行：同一个 API 用户可以创建多个 workspace，每个 workspace 有独立容器/项目目录/对话数据；并发限制以 workspace 为粒度（同一 workspace 禁止并发）。

基本信息

• API 版本：v1
• 默认后端地址（生产示例）：https://agent.cyjai.com
  （本地开发仍可用 http://localhost:8091，按需替换）
• 鉴权方式：Authorization: Bearer <token>
• API 前缀：/api/v1
• 数据落盘：对话与文件落盘到 API 用户独立目录（见 auth.md）
• 任务与事件：仅内存保存（进程重启后任务/事件不可恢复）
• 默认最大迭代次数 max_iterations：100（可在调用 /api/v1/workspaces/{workspace_id}/messages 时覆盖）

接口一览（建议按 workspace 使用）

1. 工具列表：GET /api/v1/tools
2. 工作区管理：GET/POST /api/v1/workspaces、GET/DELETE /api/v1/workspaces/{workspace_id}
3. 对话（工作区内）：POST/GET /api/v1/workspaces/{workspace_id}/conversations、GET/DELETE /api/v1/workspaces/{workspace_id}/conversations/{conversation_id}
4. 发送消息/启动后台任务（工作区内）：POST /api/v1/workspaces/{workspace_id}/messages
5. 轮询任务事件：GET /api/v1/tasks/{task_id}?from=<offset>
6. 停止任务：POST /api/v1/tasks/{task_id}/cancel
7. 文件：上传仅限 user_upload/，但列目录/下载可遍历整个 project/：POST /api/v1/workspaces/{workspace_id}/files/upload、GET /api/v1/workspaces/{workspace_id}/files、GET /api/v1/workspaces/{workspace_id}/files/download
8. Prompt 管理（用户级共享）：GET/POST /api/v1/prompts、GET /api/v1/prompts/{name}
9. 个性化管理（用户级共享）：GET/POST /api/v1/personalizations、GET /api/v1/personalizations/{name}
10. 模型列表与健康检查：GET /api/v1/models、GET /api/v1/health

详细参数与返回请看：

• auth.md：API 用户与 Token、目录结构、安全注意事项
• workspaces.md：工作区概念、创建/删除/查询
• messages_tasks.md：发送消息/轮询/停止（工作区内发消息）
• conversations.md：对话列表/详情/删除（工作区内）
• events.md：事件流格式与事件类型说明（与 WebSocket 同源）
• files.md：上传/列目录/下载（工作区内）
• tools.md：工具分类/工具名列表返回格式
• prompts_personalization.md：Prompt 与个性化管理
• errors.md：HTTP 错误码与常见排查
• examples.md：curl/Python/JS/Flutter 示例
• openapi.yaml：OpenAPI 3.0 规范（可导入 Postman/Swagger）

快速开始（curl）

将 <TOKEN> 替换为你的 Bearer Token。
默认后端：https://agent.cyjai.com，本地调试请改为 http://localhost:8091。

0）创建工作区

curl -sS -X POST \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "workspace_id": "ws1" }' \
  https://agent.cyjai.com/api/v1/workspaces

1）创建对话（指定工作区）

curl -sS -X POST \
  -H "Authorization: Bearer <TOKEN>" \
  https://agent.cyjai.com/api/v1/workspaces/ws1/conversations

返回示例：

{ "success": true, "workspace_id": "ws1", "conversation_id": "conv_20260123_234245_036" }

2）发送消息（创建后台任务，指定工作区）

curl -sS -X POST \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_20260123_234245_036",
    "message": "请用中文简要介绍《明日方舟：终末地》",
    "run_mode": "fast",            # 可选：fast / thinking / deep
    "model_key": null,
    "max_iterations": 100         # 默认 100，示例显式填写便于对齐
  }' \
  https://agent.cyjai.com/api/v1/workspaces/ws1/messages

返回示例（202）：

{
  "success": true,
  "task_id": "60322db3-f884-4a1e-a9b3-6eeb07fbab47",
  "conversation_id": "conv_20260123_234245_036",
  "workspace_id": "ws1",
  "status": "running",
  "created_at": 1769182965.30
}

2）轮询进度（按 offset 增量拉取）

首次从 from=0 开始，之后使用返回中的 next_offset。

curl -sS \
  -H "Authorization: Bearer <TOKEN>" \
  "https://agent.cyjai.com/api/v1/tasks/60322db3-f884-4a1e-a9b3-6eeb07fbab47?from=0"

3）停止任务（可选）

curl -sS -X POST \
  -H "Authorization: Bearer <TOKEN>" \
  https://agent.cyjai.com/api/v1/tasks/60322db3-f884-4a1e-a9b3-6eeb07fbab47/cancel

统一约定：响应结构与错误处理

成功响应

大部分接口返回：

{ "success": true, ... }

失败响应

大部分失败返回：

{ "success": false, "error": "原因说明" }

并使用合适的 HTTP 状态码（如 400/401/404/409/503）。

重要限制（务必阅读）

• 单工作区禁止并发任务：同一个 API 用户的同一个 workspace_id 同一时间只允许一个 running/pending 任务。重复调用该 workspace 的 /messages 会返回 409；不同 workspace 之间可并行。
• 事件缓冲为内存队列（maxlen=1000）：任务特别长或轮询太慢会导致早期事件被丢弃；请按推荐频率轮询并在客户端持久化你需要的内容。
• 进程重启不可恢复：重启后任务/事件会消失，但对话/文件已落盘的不受影响。