---
title: 工作区
source: https://vjmap.com/guide/service/api/07-workspace.html
---

# 工作区

> 分类代号：C.7  本章共 **5 个接口**

> 如果还没读过，建议先看 [入门 · 工作区](../04-workspace.md)，了解 vjmap 的命名空间模型。

工作区用来把地图 / KV / 全文搜索按"项目"隔开。默认所有地图都在"匿名工作区"；创建命名工作区后，URL 前缀由 `/api/v1/map/...` 变成 `/api/v1/workspace/{name}/...`。

---

## 快速索引

| 序号 | SDK 方法 | URL |
|----:|---------|-----|
| 48 | `get_workspaces` / `getWorkspaces` | `GET /api/v1/service/getWorkspace` |
| 49 | `workspace_create` / `workspaceCreate` | `POST /api/v1/service/workspaceCreate` |
| 50 | `workspace_modify` / `workspaceModify` | `POST /api/v1/service/workspaceModify` |
| 51 | `workspace_delete` / `workspaceDelete` | `DELETE /api/v1/service/workspaceDelete/{name}` |
| 52 | `workspace_status` / `workspaceStatus` | `GET /api/v1/service/workspaceStatus` |


---

## 48 · 列出工作区 `getWorkspace`

**URL**：`GET /api/v1/service/getWorkspace`

- 非 root 账户仅看到 **自己创建的** + **isPublic=true** 的工作区
- root（`AuthorityId:root`）账户看全部

### 响应（实采：创建 1 个后）

```json
[
  {
    "name": "nb_ws_1776831982",
    "alias": "nb 临时测试",
    "isPublic": false,
    "workDir": "nb_ws_1776831982",
    "idleCloseTime": 0,
    "disableFullSearch": false,
    "createTime": "2026-04-22 12:26:22"
  }
]
```

一个工作区都没有时返回 `null`（而不是空数组 `[]`）。

### Python

```python
ws_list = svc.get_workspaces() or []
for w in ws_list:
    print(w["name"], w["alias"])
```

### Node.js

```javascript
const ws = (await svc.getWorkspaces()) || [];
for (const w of ws) console.log(w.name, w.alias);
```

---

## 49 · 创建工作区 `workspaceCreate`

**URL**：`POST /api/v1/service/workspaceCreate`

### 请求 body

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 唯一工作区名（**会出现在 URL 路径**里，注意字符集） |
| `alias` | string | 显示名，任意字符 |
| `workDir` | string | 工作区数据目录名；空串表示与 `name` 一致 |
| `isPublic` | bool | 是否对所有登录用户可见 |
| `disableFullSearch` | bool | 是否禁用该工作区的全文搜索索引 |

### 响应（实采）

```json
{
  "data": "nb_ws_1776831982",
  "status": "ok"
}
```

### Python

```python
svc.workspace_create(
    name="myproj",
    alias="我的项目",
    is_public=False,
)
```

### Node.js

```javascript
await svc.workspaceCreate({ name: 'myproj', alias: '我的项目' });
```

---

## 50 · 修改工作区 `workspaceModify`

**URL**：`POST /api/v1/service/workspaceModify`

body 必须是 `getWorkspaces()` 返回的**完整 obj**（包含 `createTime` 在内所有字段）。常见用法：先拿再改再 POST。

### 响应（实采）

```json
{
  "name": "nb_ws_1776831982",
  "status": "success"
}
```

### Python

```python
ws_list = svc.get_workspaces() or []
me = next(w for w in ws_list if w["name"] == "myproj")
me["alias"] = "新别名"
me["disableFullSearch"] = True
svc.workspace_modify(me)
```

### Node.js

```javascript
const ws = (await svc.getWorkspaces()) || [];
const me = ws.find(w => w.name === 'myproj');
me.alias = '新别名';
await svc.workspaceModify(me);
```

---

## 51 · 删除工作区 `workspaceDelete`

**URL**：`DELETE /api/v1/service/workspaceDelete/{name}`

### 响应（实采）

```json
{
  "name": "nb_ws_1776831982",
  "status": "success"
}
```

> ⚠️ 删除**不会**自动清理工作区内的地图数据；如需彻底清除，先在该工作区内删完地图再删工作区。SDK 切换到目标工作区调 `delete_map / delete_map_file` 即可（见 [01-map-management](./01-map-management.md)）。

### Python

```python
svc.workspace_delete("myproj")
```

### Node.js

```javascript
await svc.workspaceDelete('myproj');
```

---

## 52 · 工作区状态 `workspaceStatus`

**URL**：`GET /api/v1/service/workspaceStatus`

查询当前**正在服务中的工作区**（已启用 fork 进程 / 加载了地图）。若无工作区处于活跃状态，返回 `null`。

### 响应（实采：无活跃工作区）

```json
null
```

活跃时形如：

```json
[
  { "name": "myproj", "status": "running", "pid": 12345, "memory": 128_000_000 }
]
```

---

## 在 SDK 中切换工作区

SDK 构造后，可以用 `svc.use_workspace("myproj")` 把后续所有 `map/...` / `cmd/...` 调用都前缀到 `/workspace/myproj/`：

```python
svc = vjmap.Vjmap(API, TOKEN)
svc.use_workspace("myproj")
svc.list_maps()            # -> /api/v1/workspace/myproj/cmd/listmaps/...
svc.use_workspace(None)    # 切回匿名
```

Node.js 同名方法 `svc.useWorkspace("myproj")`。

---