# 工作区 API

Source: https://langbot.app/docs/zh/plugin/dev/apis/workspace

在插件中读取和管理 Agent、流水线、机器人、模型、知识库等工作区资源。

工作区 API 让插件可以操作它所安装的工作区：列出和修改 Agent 与流水线、查询机器人、管理模型和知识库、读取监控数据等。它开放的操作与 LangBot 的 HTTP API、MCP 服务和工作区助手完全相同，因此成员能通过这些途径完成的事，插件都可以在成员授权的范围内自动完成。

每个操作都有一个稳定的 ID，例如 `pipeline.list` 或 `knowledge.base.retrieve`。插件只能调用自己[在 manifest 中声明](https://langbot.app/docs/zh/plugin/dev/permissions.md#声明权限)、并且已由成员授予该安装的操作。

## 调用操作

在任意组件中通过 `self.plugin.workspace` 调用。每个操作都有一个按 ID 命名、带类型标注的方法：

```python
from langbot_plugin.api.definition.components.tool.tool import Tool


class WorkspaceSummary(Tool):
    async def call(self, params, session, query_id):
        result = await self.plugin.workspace.pipeline.list()
        if not result["ok"]:
            return f"无法获取流水线列表：{result['error']['message']}"

        names = [pipeline["name"] for pipeline in result["result"]]
        return "流水线：" + "、".join(names)
```

方法以关键字参数传参，参数与操作的输入结构一一对应，编辑器里能看到它们的类型和说明。少数名称会被调整为合法的 Python 标识符：如果某一段恰好是 Python 关键字，会在末尾加下划线（例如 `import_`），其他非法字符会替换为下划线。发送时仍使用原始参数名。

如果需要在运行时决定调用哪个操作，可以直接按 ID 调用，效果与类型化方法完全相同：

```python
result = await self.plugin.workspace.call("knowledge.base.retrieve", kb_uuid=kb_uuid, query="退款政策")
```

`await self.plugin.workspace.list()` 返回该安装已获授权的操作及其输入结构，并按 `domains` 分组。可以用它动态生成工具列表，或在提供某项功能前先确认是否已获授权。

### 在运行器中

运行器通过 `ctx.api.workspace` 拿到与本次运行绑定的代理。它提供相同的方法，也由相同的安装授权控制；区别在于 LangBot 会把每次调用记录到当前运行下。

发起本次运行的 Agent 或流水线，可能限定了模型应当看到哪些工作区操作，这个选择通过 `ctx.resources.workspace_operations` 传入。如果运行器要把工作区操作作为工具提供给模型，应当只提供这些操作；列表为空时，一个都不要提供。LangBot 内置的 LocalAgent 就是这样做的。

## 返回结果与错误

工作区调用不会因为业务错误抛出异常，而是始终返回一个字典：

```python
# 成功
{"ok": True, "result": ..., "operation": {"id": "pipeline.list", ...}}

# 失败
{"ok": False, "error": {"code": "permission_denied", "message": "...", "details": {...}}}
```

读取 `result` 之前先检查 `ok`。常见错误码：

| 错误码                 | 含义                                                             |
| ------------------- | -------------------------------------------------------------- |
| `permission_denied` | 该安装没有获得这个操作的授权，或者安装已停用。`details.denied_operations` 列出缺少的操作 ID。 |
| `invalid_input`     | 参数不符合操作的输入结构。                                                  |
| `not_found`         | 引用的资源在当前工作区中不存在。                                               |
| `application_error` | 操作已执行但失败，`message` 中说明原因。                                      |

权限不足是预料之中的情况，因为成员可能只授予插件所声明权限的一部分。遇到时应说明缺少什么，而不是让整个命令或运行失败。

## 选择要声明的操作

每个操作都有风险等级，成员确认时可以看到：

- **读**：只返回数据，例如 `pipeline.list`、`stats.basic`。
- **写**：修改工作区配置，例如 `pipeline.update`、`knowledge.file.store`。
- **高危**：删除资源、影响 LangBot 之外的对象，或消耗大量资源，例如 `bot.delete`、`pipeline.chat.broadcast`。确认对话框会单独标出这类操作。

授予某个操作的成员，自己必须具备该操作要求的权限（见下表最后一列）。只申请插件真正需要的操作；申请大量高危操作，很可能会被拒绝或被删减。

`knowledge.*` 这类通配符会申请某个前缀下的所有操作，但并不是每个前缀都可以这样用，详见[通配符](https://langbot.app/docs/zh/plugin/dev/permissions.md#通配符)。

## 操作列表

下表按领域列出当前 LangBot 版本中插件可以申请的全部操作。方法写作 `workspace.…`：在组件中是 `self.plugin.workspace`，在运行器中是 `ctx.api.workspace`。SDK 的类型化方法就是根据这份目录生成的，因此表中的每个操作都有对应的方法。

### 适配器 (`adapter`)

| 操作    | ID 与方法                                    | 风险 | 授予者需要           |
| ----- | ----------------------------------------- | -- | --------------- |
| 适配器详情 | `adapter.get` `workspace.adapter.get()`   | 读  | `resource.view` |
| 适配器列表 | `adapter.list` `workspace.adapter.list()` | 读  | `resource.view` |

### 智能体 (`agent`)

| 操作      | ID 与方法                                              | 风险 | 授予者需要             |
| ------- | --------------------------------------------------- | -- | ----------------- |
| 创建智能体   | `agent.create` `workspace.agent.create()`           | 写  | `resource.manage` |
| 调试智能体   | `agent.debug` `workspace.agent.debug()`             | 写  | `runtime.operate` |
| 删除智能体   | `agent.delete` `workspace.agent.delete()`           | 高危 | `resource.manage` |
| 智能体详情   | `agent.get` `workspace.agent.get()`                 | 读  | `resource.view`   |
| 智能体列表   | `agent.list` `workspace.agent.list()`               | 读  | `resource.view`   |
| 智能体元数据  | `agent.metadata` `workspace.agent.metadata()`       | 读  | `resource.view`   |
| 运行事件流   | `agent.runs.events` `workspace.agent.runs.events()` | 读  | `resource.view`   |
| 智能体运行列表 | `agent.runs.list` `workspace.agent.runs.list()`     | 读  | `resource.view`   |
| 更新智能体   | `agent.update` `workspace.agent.update()`           | 写  | `resource.manage` |

### 机器人 (`bot`)

| 操作       | ID 与方法                                                            | 风险 | 授予者需要             |
| -------- | ----------------------------------------------------------------- | -- | ----------------- |
| 机器人管理员列表 | `bot.admins.list` `workspace.bot.admins.list()`                   | 读  | `resource.view`   |
| 创建机器人    | `bot.create` `workspace.bot.create()`                             | 写  | `resource.manage` |
| 删除机器人    | `bot.delete` `workspace.bot.delete()`                             | 高危 | `resource.manage` |
| 机器人详情    | `bot.get` `workspace.bot.get()`                                   | 读  | `resource.view`   |
| 应用群组过滤   | `bot.group_filter.apply` `workspace.bot.group_filter.apply()`     | 写  | `resource.manage` |
| 群组过滤预览   | `bot.group_filter.preview` `workspace.bot.group_filter.preview()` | 读  | `resource.manage` |
| 机器人列表    | `bot.list` `workspace.bot.list()`                                 | 读  | `resource.view`   |
| 机器人运行日志  | `bot.logs` `workspace.bot.logs()`                                 | 读  | `resource.view`   |
| 发送机器人消息  | `bot.message.send` `workspace.bot.message.send()`                 | 高危 | `runtime.operate` |
| 测试发送消息   | `bot.message.test` `workspace.bot.message.test()`                 | 写  | `resource.manage` |
| 路由预览     | `bot.routes.preview` `workspace.bot.routes.preview()`             | 读  | `resource.manage` |
| 路由状态     | `bot.routes.status` `workspace.bot.routes.status()`               | 读  | `resource.view`   |
| 机器人运行时状态 | `bot.runtime.get` `workspace.bot.runtime.get()`                   | 读  | `resource.view`   |
| 更新机器人    | `bot.update` `workspace.bot.update()`                             | 写  | `resource.manage` |

### 扩展 (`extension`)

| 操作     | ID 与方法                                        | 风险 | 授予者需要           |
| ------ | --------------------------------------------- | -- | --------------- |
| 扩展全览列表 | `extension.list` `workspace.extension.list()` | 读  | `resource.view` |

### 知识库 (`knowledge`)

| 操作       | ID 与方法                                                                              | 风险 | 授予者需要             |
| -------- | ----------------------------------------------------------------------------------- | -- | ----------------- |
| 创建知识库    | `knowledge.base.create` `workspace.knowledge.base.create()`                         | 写  | `resource.manage` |
| 删除知识库    | `knowledge.base.delete` `workspace.knowledge.base.delete()`                         | 高危 | `resource.manage` |
| 知识库详情    | `knowledge.base.get` `workspace.knowledge.base.get()`                               | 读  | `resource.view`   |
| 知识库列表    | `knowledge.base.list` `workspace.knowledge.base.list()`                             | 读  | `resource.view`   |
| 检索知识库    | `knowledge.base.retrieve` `workspace.knowledge.base.retrieve()`                     | 读  | `resource.view`   |
| 更新知识库    | `knowledge.base.update` `workspace.knowledge.base.update()`                         | 写  | `resource.manage` |
| 引擎创建配置结构 | `knowledge.engine.creation_schema` `workspace.knowledge.engine.creation_schema()`   | 读  | `resource.view`   |
| 知识引擎列表   | `knowledge.engine.list` `workspace.knowledge.engine.list()`                         | 读  | `resource.view`   |
| 引擎检索配置结构 | `knowledge.engine.retrieval_schema` `workspace.knowledge.engine.retrieval_schema()` | 读  | `resource.view`   |
| 删除知识库文件  | `knowledge.file.delete` `workspace.knowledge.file.delete()`                         | 高危 | `resource.manage` |
| 知识库文件列表  | `knowledge.file.list` `workspace.knowledge.file.list()`                             | 读  | `resource.view`   |
| 导入知识库文件  | `knowledge.file.store` `workspace.knowledge.file.store()`                           | 写  | `resource.manage` |
| 文档解析器列表  | `knowledge.parser.list` `workspace.knowledge.parser.list()`                         | 读  | `resource.view`   |

### MCP 服务 (`mcp`)

| 操作         | ID 与方法                                                        | 风险 | 授予者需要             |
| ---------- | ------------------------------------------------------------- | -- | ----------------- |
| MCP资源列表    | `mcp.resource.list` `workspace.mcp.resource.list()`           | 读  | `resource.view`   |
| 读取MCP资源    | `mcp.resource.read` `workspace.mcp.resource.read()`           | 读  | `resource.view`   |
| MCP资源模板列表  | `mcp.resource.templates` `workspace.mcp.resource.templates()` | 读  | `resource.view`   |
| 删除MCP服务    | `mcp.server.delete` `workspace.mcp.server.delete()`           | 高危 | `resource.manage` |
| MCP服务详情    | `mcp.server.get` `workspace.mcp.server.get()`                 | 读  | `resource.view`   |
| MCP服务列表    | `mcp.server.list` `workspace.mcp.server.list()`               | 读  | `resource.view`   |
| MCP服务日志    | `mcp.server.logs` `workspace.mcp.server.logs()`               | 读  | `audit.view`      |
| MCP服务运行时状态 | `mcp.server.runtime` `workspace.mcp.server.runtime()`         | 读  | `resource.view`   |
| 测试MCP服务连接  | `mcp.server.test` `workspace.mcp.server.test()`               | 写  | `resource.manage` |

### 模型 (`model`)

| 操作          | ID 与方法                                                                            | 风险 | 授予者需要                    |
| ----------- | --------------------------------------------------------------------------------- | -- | ------------------------ |
| 创建嵌入模型      | `model.embedding.create` `workspace.model.embedding.create()`                     | 写  | `provider_secret.manage` |
| 删除嵌入模型      | `model.embedding.delete` `workspace.model.embedding.delete()`                     | 高危 | `resource.manage`        |
| 嵌入模型详情      | `model.embedding.get` `workspace.model.embedding.get()`                           | 读  | `resource.view`          |
| 嵌入模型列表      | `model.embedding.list` `workspace.model.embedding.list()`                         | 读  | `resource.view`          |
| 按供应商列出嵌入模型  | `model.embedding.list_by_provider` `workspace.model.embedding.list_by_provider()` | 读  | `resource.view`          |
| 测试嵌入模型      | `model.embedding.test` `workspace.model.embedding.test()`                         | 写  | `provider_secret.manage` |
| 更新嵌入模型      | `model.embedding.update` `workspace.model.embedding.update()`                     | 写  | `provider_secret.manage` |
| 创建大语言模型     | `model.llm.create` `workspace.model.llm.create()`                                 | 写  | `provider_secret.manage` |
| 获取默认LLM模型   | `model.llm.default.get` `workspace.model.llm.default.get()`                       | 读  | `resource.manage`        |
| 删除大语言模型     | `model.llm.delete` `workspace.model.llm.delete()`                                 | 高危 | `resource.manage`        |
| 大语言模型详情     | `model.llm.get` `workspace.model.llm.get()`                                       | 读  | `resource.view`          |
| 大语言模型列表     | `model.llm.list` `workspace.model.llm.list()`                                     | 读  | `resource.view`          |
| 按供应商列出LLM模型 | `model.llm.list_by_provider` `workspace.model.llm.list_by_provider()`             | 读  | `resource.view`          |
| 获取标星LLM模型   | `model.llm.starred.get` `workspace.model.llm.starred.get()`                       | 读  | `resource.view`          |
| 设置标星LLM模型   | `model.llm.starred.set` `workspace.model.llm.starred.set()`                       | 写  | `provider_secret.manage` |
| 测试大语言模型     | `model.llm.test` `workspace.model.llm.test()`                                     | 写  | `provider_secret.manage` |
| 更新大语言模型     | `model.llm.update` `workspace.model.llm.update()`                                 | 写  | `provider_secret.manage` |
| 创建重排模型      | `model.rerank.create` `workspace.model.rerank.create()`                           | 写  | `provider_secret.manage` |
| 删除重排模型      | `model.rerank.delete` `workspace.model.rerank.delete()`                           | 高危 | `resource.manage`        |
| 重排模型详情      | `model.rerank.get` `workspace.model.rerank.get()`                                 | 读  | `resource.view`          |
| 重排模型列表      | `model.rerank.list` `workspace.model.rerank.list()`                               | 读  | `resource.view`          |
| 按供应商列出重排模型  | `model.rerank.list_by_provider` `workspace.model.rerank.list_by_provider()`       | 读  | `resource.view`          |
| 测试重排模型      | `model.rerank.test` `workspace.model.rerank.test()`                               | 写  | `provider_secret.manage` |
| 更新重排模型      | `model.rerank.update` `workspace.model.rerank.update()`                           | 写  | `provider_secret.manage` |

### 监控审计 (`monitoring`)

| 操作       | ID 与方法                                                                  | 风险 | 授予者需要             |
| -------- | ----------------------------------------------------------------------- | -- | ----------------- |
| 嵌入模型调用统计 | `monitoring.embedding_calls` `workspace.monitoring.embedding_calls()`   | 读  | `resource.view`   |
| 错误日志     | `monitoring.errors` `workspace.monitoring.errors()`                     | 读  | `resource.view`   |
| 执行详情     | `monitoring.execution.detail` `workspace.monitoring.execution.detail()` | 读  | `resource.view`   |
| 执行记录列表   | `monitoring.executions` `workspace.monitoring.executions()`             | 读  | `resource.view`   |
| 用户反馈列表   | `monitoring.feedback.list` `workspace.monitoring.feedback.list()`       | 读  | `resource.view`   |
| 用户反馈统计   | `monitoring.feedback.stats` `workspace.monitoring.feedback.stats()`     | 读  | `resource.view`   |
| 进行中任务监控  | `monitoring.inflight` `workspace.monitoring.inflight()`                 | 读  | `resource.view`   |
| 大模型调用统计  | `monitoring.llm_calls` `workspace.monitoring.llm_calls()`               | 读  | `resource.view`   |
| 消息详情     | `monitoring.message.detail` `workspace.monitoring.message.detail()`     | 读  | `resource.view`   |
| 消息历史查询   | `monitoring.messages` `workspace.monitoring.messages()`                 | 读  | `resource.view`   |
| 监控总览     | `monitoring.overview` `workspace.monitoring.overview()`                 | 读  | `resource.view`   |
| 会话分析     | `monitoring.session.analysis` `workspace.monitoring.session.analysis()` | 读  | `resource.view`   |
| 重置会话     | `monitoring.session.reset` `workspace.monitoring.session.reset()`       | 高危 | `resource.manage` |
| 会话列表     | `monitoring.sessions` `workspace.monitoring.sessions()`                 | 读  | `resource.view`   |
| 代币消耗统计   | `monitoring.tokens` `workspace.monitoring.tokens()`                     | 读  | `resource.view`   |
| 工具调用统计   | `monitoring.tool_calls` `workspace.monitoring.tool_calls()`             | 读  | `resource.view`   |

### 流水线 (`pipeline`)

| 操作      | ID 与方法                                                                | 风险 | 授予者需要             |
| ------- | --------------------------------------------------------------------- | -- | ----------------- |
| 广播聊天消息  | `pipeline.chat.broadcast` `workspace.pipeline.chat.broadcast()`       | 高危 | `runtime.operate` |
| 流水线连接状态 | `pipeline.chat.connections` `workspace.pipeline.chat.connections()`   | 读  | `runtime.operate` |
| 流水线聊天历史 | `pipeline.chat.history` `workspace.pipeline.chat.history()`           | 读  | `runtime.operate` |
| 重置聊天会话  | `pipeline.chat.reset` `workspace.pipeline.chat.reset()`               | 高危 | `runtime.operate` |
| 复制流水线   | `pipeline.copy` `workspace.pipeline.copy()`                           | 写  | `resource.manage` |
| 创建流水线   | `pipeline.create` `workspace.pipeline.create()`                       | 写  | `resource.manage` |
| 流水线默认配置 | `pipeline.defaults` `workspace.pipeline.defaults()`                   | 读  | `resource.view`   |
| 删除流水线   | `pipeline.delete` `workspace.pipeline.delete()`                       | 高危 | `resource.manage` |
| 获取流水线扩展 | `pipeline.extensions.get` `workspace.pipeline.extensions.get()`       | 读  | `resource.view`   |
| 更新流水线扩展 | `pipeline.extensions.update` `workspace.pipeline.extensions.update()` | 写  | `resource.manage` |
| 流水线详情   | `pipeline.get` `workspace.pipeline.get()`                             | 读  | `resource.view`   |
| 流水线列表   | `pipeline.list` `workspace.pipeline.list()`                           | 读  | `resource.view`   |
| 流水线元数据  | `pipeline.metadata` `workspace.pipeline.metadata()`                   | 读  | `resource.view`   |
| 执行流水线   | `pipeline.run` `workspace.pipeline.run()`                             | 写  | `runtime.operate` |
| 更新流水线   | `pipeline.update` `workspace.pipeline.update()`                       | 写  | `resource.manage` |

### 插件 (`plugin`)

| 操作          | ID 与方法                                                        | 风险 | 授予者需要             |
| ----------- | ------------------------------------------------------------- | -- | ----------------- |
| 获取插件配置      | `plugin.config.get` `workspace.plugin.config.get()`           | 读  | `resource.view`   |
| 插件调试信息      | `plugin.debug_info` `workspace.plugin.debug_info()`           | 读  | `resource.manage` |
| 插件详情        | `plugin.get` `workspace.plugin.get()`                         | 读  | `resource.view`   |
| GitHub发布包资源 | `plugin.github.assets` `workspace.plugin.github.assets()`     | 读  | `resource.view`   |
| GitHub发布版本  | `plugin.github.releases` `workspace.plugin.github.releases()` | 读  | `resource.view`   |
| 插件列表        | `plugin.list` `workspace.plugin.list()`                       | 读  | `resource.view`   |
| 插件运行日志      | `plugin.logs` `workspace.plugin.logs()`                       | 读  | `audit.view`      |
| 插件说明文档      | `plugin.readme` `workspace.plugin.readme()`                   | 读  | `resource.view`   |

### 模型供应商 (`provider`)

| 操作        | ID 与方法                                                      | 风险 | 授予者需要                    |
| --------- | ----------------------------------------------------------- | -- | ------------------------ |
| 创建供应商     | `provider.create` `workspace.provider.create()`             | 写  | `provider_secret.manage` |
| 删除供应商     | `provider.delete` `workspace.provider.delete()`             | 高危 | `resource.manage`        |
| 供应商详情     | `provider.get` `workspace.provider.get()`                   | 读  | `resource.view`          |
| 供应商列表     | `provider.list` `workspace.provider.list()`                 | 读  | `resource.view`          |
| 供应商模型数量   | `provider.models.count` `workspace.provider.models.count()` | 读  | `resource.view`          |
| 扫描供应商可用模型 | `provider.models.scan` `workspace.provider.models.scan()`   | 写  | `provider_secret.manage` |
| 更新供应商     | `provider.update` `workspace.provider.update()`             | 写  | `provider_secret.manage` |

### 请求器 (`requester`)

| 操作    | ID 与方法                                        | 风险 | 授予者需要           |
| ----- | --------------------------------------------- | -- | --------------- |
| 请求器详情 | `requester.get` `workspace.requester.get()`   | 读  | `resource.view` |
| 请求器列表 | `requester.list` `workspace.requester.list()` | 读  | `resource.view` |

### 技能 (`skill`)

| 操作         | ID 与方法                                                    | 风险 | 授予者需要             |
| ---------- | --------------------------------------------------------- | -- | ----------------- |
| 创建技能       | `skill.create` `workspace.skill.create()`                 | 写  | `resource.manage` |
| 删除技能       | `skill.delete` `workspace.skill.delete()`                 | 高危 | `resource.manage` |
| 技能文件列表     | `skill.file.list` `workspace.skill.file.list()`           | 读  | `resource.view`   |
| 读取技能文件     | `skill.file.read` `workspace.skill.file.read()`           | 读  | `resource.view`   |
| 写入技能文件     | `skill.file.write` `workspace.skill.file.write()`         | 写  | `resource.manage` |
| 技能详情       | `skill.get` `workspace.skill.get()`                       | 读  | `resource.view`   |
| 预览GitHub技能 | `skill.github.preview` `workspace.skill.github.preview()` | 读  | `resource.manage` |
| 技能列表       | `skill.list` `workspace.skill.list()`                     | 读  | `resource.view`   |
| 重新加载技能     | `skill.reload` `workspace.skill.reload()`                 | 写  | `resource.manage` |
| 更新技能       | `skill.update` `workspace.skill.update()`                 | 写  | `resource.manage` |

### 数据统计 (`stats`)

| 操作     | ID 与方法                                  | 风险 | 授予者需要           |
| ------ | --------------------------------------- | -- | --------------- |
| 基础数据统计 | `stats.basic` `workspace.stats.basic()` | 读  | `resource.view` |

### 工具 (`tool`)

| 操作   | ID 与方法                              | 风险 | 授予者需要           |
| ---- | ----------------------------------- | -- | --------------- |
| 工具详情 | `tool.get` `workspace.tool.get()`   | 读  | `resource.view` |
| 工具列表 | `tool.list` `workspace.tool.list()` | 读  | `resource.view` |