工作区

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

如果还没读过，建议先看 入门 · 工作区，了解 vjmap 的命名空间模型。

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

---

快速索引

---

48 · 列出工作区 getWorkspace

URL：GET /api/v1/service/getWorkspace

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

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

[
  {
    "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

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

Node.js

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

响应（实采）

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

Python

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

Node.js

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

---

50 · 修改工作区 workspaceModify

URL：POST /api/v1/service/workspaceModify

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

响应（实采）

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

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

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}

响应（实采）

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

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

Python

svc.workspace_delete("myproj")

Node.js

await svc.workspaceDelete('myproj');

---

52 · 工作区状态 workspaceStatus

URL：GET /api/v1/service/workspaceStatus

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

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

null

活跃时形如：

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

---

在 SDK 中切换工作区

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

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")。

---