116 lines
2.1 KiB
Markdown
116 lines
2.1 KiB
Markdown
# 工作区（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）：
|
||
|
||
```json
|
||
{
|
||
"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)：
|
||
|
||
```json
|
||
{ "workspace_id": "ws1" }
|
||
```
|
||
|
||
成功响应（200）：
|
||
|
||
```json
|
||
{
|
||
"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）：
|
||
|
||
```json
|
||
{
|
||
"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）：
|
||
|
||
```json
|
||
{ "success": true, "workspace_id": "ws1" }
|
||
```
|
||
|
||
错误：
|
||
|
||
- `409`：该工作区有运行中的任务
|
||
- `404`：workspace 不存在
|
||
|