agent-Specialization/api_doc/workspaces.md

工作区（Workspace）管理 API

本项目的 API v1 支持多工作区并行：

• 一个 API 用户可以创建多个 workspace_id
• 每个 workspace 有独立的：
  • 容器（运行隔离）
  • project/（工具读写的根目录）
  • data/（对话等数据落盘）
  • user_upload/（上传目录）
• 并发限制以 workspace 为粒度：同一 workspace 禁止并发任务，不同 workspace 可同时运行。

鉴权：所有接口均需要 Authorization: Bearer <TOKEN>

workspace_id 规则：

• 仅允许字符：字母/数字/./_/-
• 长度：1~40

---

1) 列出工作区

GET /api/v1/workspaces

成功响应（200）：

{
  "success": true,
  "items": [
    {
      "workspace_id": "ws1",
      "project_path": ".../api/users/api_demo/workspaces/ws1/project",
      "data_dir": ".../api/users/api_demo/workspaces/ws1/data",
      "has_conversations": true
    }
  ]
}

---

2) 创建/确保工作区存在

POST /api/v1/workspaces

Body(JSON)：

{ "workspace_id": "ws1" }

成功响应（200）：

{
  "success": true,
  "workspace_id": "ws1",
  "project_path": ".../api/users/<user>/workspaces/ws1/project",
  "data_dir": ".../api/users/<user>/workspaces/ws1/data"
}

错误：

• 400：workspace_id 不合法

---

3) 查询单个工作区

GET /api/v1/workspaces/{workspace_id}

成功响应（200）：

{
  "success": true,
  "workspace": {
    "workspace_id": "ws1",
    "project_path": "...",
    "data_dir": "...",
    "has_conversations": true
  }
}

错误：

• 404：workspace 不存在

---

4) 删除工作区

DELETE /api/v1/workspaces/{workspace_id}

说明：

• 会删除该 workspace 的 project/、data/、logs/ 等目录；
• 不会删除用户级共享的 prompts/personalization（它们不属于 workspace）；
• 如果该 workspace 有运行中的任务，会返回 409（禁止删除）。

成功响应（200）：

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

错误：

• 409：该工作区有运行中的任务
• 404：workspace 不存在