Files
LangBot/docs/zh/plugin/dev/permissions.mdx
huanghuoguoguo ae279d1544 feat(artifact): integrate SDK and knowledge consumers (#3067)
Integrate installation-private Artifact SDK operations, knowledge-file references, and compatible legacy uploads. Preserve permission and lifecycle boundaries and strengthen HTTP file delivery tests.
2026-11-17 23:29:20 +08:00

172 lines
14 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: 插件权限
description: 声明插件需要的权限,并了解工作区成员如何授予和撤销这些权限。
---
插件能做的远不止回复消息:它可以调用模型、读取知识库、通过任意机器人发消息,还能通过[工作区 API](/zh/plugin/dev/apis/workspace) 管理 Agent 和流水线。每个插件安装都运行在某一个工作区里,所以 LangBot 要求插件事先说明自己需要哪些能力,再由工作区成员确认授予。
整个流程分三步:
1. **声明**:插件在 `manifest.yaml` 里列出需要的权限。
2. **确认**:安装后,成员在插件详情页查看所申请的权限,授予全部或其中一部分。确认之前,插件安装保持停用状态。
3. **校验**:插件每次调用时,LangBot 都会检查该安装已获得的授权。超出授权范围的调用会返回 `permission_denied`。
声明权限并不等于获得权限,只有成员确认之后才会生效。
插件可显式申请 `artifact.create`、`artifact.get`、`artifact.read`、`artifact.read_content`、`artifact.retain`、`artifact.release` 和 `artifact.delete`。请逐项列出所需操作 ID:`artifact.*` 还包含仅供账户使用的发布和 Skill 来源操作,因此会被拒绝。类型化调用使用 `self.plugin.workspace.artifact.<method>(...)`,或 run 绑定的 `ctx.api.workspace` 代理。
## 声明权限
权限属于整个插件,所以写在 `manifest.yaml` 插件级的 `spec` 下,而不是某个组件里。同一份授权适用于插件的所有组件:命令、事件监听器、工具、知识引擎、解析器和运行器。
```yaml
apiVersion: v1
kind: Plugin
metadata:
author: acme
name: WeeklyReport
version: 1.0.0
spec:
permissions:
capabilities:
- models.invoke # 调用大模型
- bot.message.send # 把周报发到群里
- storage.plugin # 记录上次发送时间
workspace_operations:
- stats.basic # 读取工作区统计数据
- knowledge.* # 所有知识库操作
config: []
components: {}
```
两个列表对应两类不同的访问:
- **`capabilities`(插件能力)**:解锁 `self.plugin` 上的常规 SDK 方法,例如 `invoke_llm`、`send_message`、`set_plugin_storage`。全部 16 项见[下表](#插件能力)。
- **`workspace_operations`(工作区操作)**:解锁[工作区 API](/zh/plugin/dev/apis/workspace) 中的操作。这些操作与 LangBot 的 HTTP API、MCP 服务和工作区助手所用的完全相同,每一项都是一个操作 ID,例如 `pipeline.list`。
只声明插件真正用到的权限。清单越短、越合理,成员越愿意授予;授权范围越小,插件一旦被滥用,造成的影响也越小。
### 严格模式与兼容模式
声明方式决定了插件安装以哪种模式运行:
| manifest 写法 | 模式 | 行为 |
| --- | --- | --- |
| `permissions:` 下写了一个或两个列表 | 严格模式 | 成员可以授予全部,也可以只授予一部分。 |
| `permissions: {}` | 严格模式 | 插件不需要任何全局访问权限。 |
| 没有 `permissions` 字段 | 兼容模式 | 按旧版插件处理,见[兼容模式](#兼容模式)。 |
新插件都应该声明权限,哪怕是空集合。
### 通配符
工作区操作可以用 `.*` 结尾,一次申请某个前缀下的全部操作,例如 `knowledge.*` 或 `model.llm.*`。成员确认时,LangBot 会把通配符展开为具体的操作 ID 并保存下来。如果以后的 LangBot 版本在这个前缀下新增了操作,新操作不会自动授予,安装会重新进入待确认状态。
有些操作永远不能授予插件:流式操作、只允许其他调用方使用的操作(例如只有登录成员才能调用的操作),以及完全不通过 API 开放的操作。声明这类操作或未知的 ID 会让权限声明无效。通配符同理:只要前缀下包含这类操作,整个通配符就会被拒绝,所以 `bot.*`、`agent.*`、`pipeline.*`、`plugin.*` 和 `monitoring.*` 都不能用,需要逐个列出,或者改用更窄的前缀。
目前可用的通配符:
- 整个领域:`adapter.*`、`extension.*`、`knowledge.*`、`model.*`、`requester.*`、`stats.*`、`tool.*`
- 更窄的前缀:`agent.runs.*`、`bot.group_filter.*`、`bot.message.*`、`bot.routes.*`、`bot.runtime.*`、`mcp.resource.*`、`monitoring.execution.*`、`monitoring.feedback.*`、`monitoring.message.*`、`monitoring.session.*`、`pipeline.chat.*`、`pipeline.extensions.*`、`plugin.github.*`、`plugin.marketplace.*`、`provider.models.*`、`skill.file.*`,以及 `knowledge.` 和 `model.` 下的所有前缀
插件可以申请的全部操作见[工作区 API 操作列表](/zh/plugin/dev/apis/workspace#操作列表)。
## 插件能力
每项能力解锁一组 SDK 方法。确认这项能力的成员需要具备第三列的工作区权限;最后一列说明成员实际批准的是什么。
| 能力 | 解锁的 SDK 方法 | 授予者需要 | 含义 |
| --- | --- | --- | --- |
| `langbot.info` | `get_langbot_version` | `resource.view` | 只读 |
| `bot.read` | `get_bots`、`get_bot_info` | `resource.view` | 只读 |
| `bot.message.send` | `send_message` | `runtime.operate` | 可以给用户和群组发消息 |
| `bot.platform_api` | `call_platform_api` | `runtime.operate`、`resource.manage` | **危险**:直接调用 IM 平台原生接口 |
| `models.read` | `get_llm_models` | `resource.view` | 只读 |
| `models.invoke` | `invoke_llm`、`invoke_llm_with_usage`、`invoke_llm_stream`、`invoke_llm_stream_events`、`invoke_embedding`、`invoke_rerank` | `runtime.operate` | 消耗模型供应商额度 |
| `storage.plugin` | `get/set/delete_plugin_storage`、`get_plugin_storage_keys` | `resource.manage` | 读写插件自己的存储 |
| `storage.workspace` | `get/set/delete_workspace_storage`、`get_workspace_storage_keys` | `resource.manage` | 读写所有插件共享的存储 |
| `knowledge.read` | `list_knowledge_bases`、`retrieve_knowledge`、`get_knowledge_file_stream` | `resource.view` | 读取知识库 |
| `knowledge.vector` | `vector_upsert`、`vector_search`、`vector_delete`、`vector_list` | `resource.manage` | 写入向量库 |
| `knowledge.parser` | `list_parsers`、`invoke_parser` | `runtime.operate` | 运行文档解析器 |
| `config.read` | `get_config_file` | `resource.view` | 读取上传的配置文件 |
| `plugin_tools` | 对插件工具调用 `list_tools`、`get_tool_detail`、`call_tool` | `runtime.operate` | 运行其他插件的工具 |
| `mcp` | 对 MCP 工具调用 `call_tool` | `runtime.operate` | **危险**:运行 MCP 工具 |
| `sandbox` | `get_box_status`、`list_boxes`、`acquire_box`,以及对沙盒工具调用 `call_tool` | `runtime.operate` | **危险**:在沙盒中执行代码 |
| `plugin.read` | `list_plugins_manifest`、`list_commands` | `resource.view` | 列出已安装的插件 |
关于工具有两点需要注意。插件调用其他插件的工具时,那个工具按**它自己**安装的授权运行,而不是按你的授权。另外,能力是按工具来源分别检查的:只有 `plugin_tools` 并不能调用 MCP 工具或沙盒工具。
只作用于插件当前正在处理的事件或运行的调用,不需要任何能力。回复触发事件的会话、读取当前请求的变量、使用 LangBot 提供给运行器的工具,这些都由事件或运行本身授权,与安装授权无关。详见 [Agent 运行 API](/zh/plugin/dev/apis/agent-run) 和[流水线事件 API](/zh/plugin/dev/apis/pipeline-events)。
## 确认插件安装
以下途径由当前登录成员直接安装,安装后会自动确认插件声明的全部权限,不会停在待授权:初始化向导(勾选自动授权时)、在 Agent 或流水线表单里直接安装运行器或事件处理器、在知识库表单里直接安装知识引擎,以及流水线迁移和知识库迁移。自动确认同样受下面的“谁可以确认”规则限制,成员权限不足时安装任务会失败并说明原因。
其他途径新安装或升级后需要确认的插件,会在插件列表和详情页上显示 **待授权**,并保持停用。成员打开详情页的 **插件权限**,查看所申请的权限,取消勾选不想授予的项,再点 **授权**。确认对话框会单独标出危险能力和发消息能力。
谁可以确认:
- 只有登录 WebUI 的成员(以及支持管理员)可以新增授权。API Key、`lbctl`、处理器、插件和公开机器人都不行。通过 API Key 或 `lbctl` 安装的插件,需要成员之后在 WebUI 中确认。
- 成员需要 `resource.manage`,以及每项授权各自要求的权限:插件能力看上表,工作区操作看该操作自身的 `permission`。开发者角色拥有 `resource.view`、`resource.manage` 和 `runtime.operate`,因此可以授予所有插件能力;但这并不意味着他们能授予超出自身角色的操作,例如成员管理或 API Key 管理。
- 只要请求中有一项超出成员的权限上限,整个请求都会以 `permission_denied` 失败,响应中的 `denied_operations` 和 `denied_capabilities` 会列出具体是哪些项。LangBot 不会悄悄丢掉其中一部分。
严格模式下,成员可以只授予插件所声明权限中的任意子集,所以插件应当在缺少某项可选权限时平稳降级。
授权属于插件安装,而不属于某个成员。批准授权的成员之后即使换了角色或离开工作区,授权也依然有效。
### 安装时自动确认
初始化向导和流水线迁移在安装官方插件时,会一并确认它们声明的权限。这一步走的是与手动确认完全相同的检查:调用方必须是成员,并具备所有需要的权限。任何一项检查不通过,插件仍会安装,但保持待授权状态。在 HTTP 接口中,这对应 `POST /api/v1/plugins/install/marketplace` 的 `auto_confirm_permissions: true`;默认值为 `false`,API Key 也无法借此跳过成员确认。
### 由插件和 Agent 发起的安装
成员授予相应操作后,插件,或通过工作区工具调用的 Agent、流水线,可以用 `plugin.marketplace.search` 搜索插件市场,并用 `plugin.install.marketplace` 安装插件。安装操作标记为**高危**,为 Agent 或流水线勾选它时会显示敏感工具提示。这类调用方只能从插件市场新增安装:
- 传入 `auto_confirm_permissions: true` 会被拒绝,返回 `permission_denied`。新插件保持禁用,直到成员在插件详情页确认其权限。
- 安装已经安装的插件会失败,返回 `plugin_already_installed`;升级或重新安装仍由成员完成。
- 实例禁用插件市场时,两个操作都会返回 `marketplace_disabled`。
- 不能从 GitHub 或本地文件安装。
安装调用返回 `task_id`。轮询 `task.get`,直到 `status` 为 `succeeded` 或 `failed`;`pending_permission_confirmation: true` 表示插件正在等待成员确认。
## 撤销与升级
具备 `resource.manage` 的成员可以随时撤销授权:取消勾选后保存即可。撤销不需要确认,也不受权限上限限制。API Key 可以撤销,但永远不能新增。
插件升级时:
- 新版本仍然声明的权限,原有授权保留。
- 新版本新增的权限保持未授予,直到成员确认;安装会再次显示 **待授权**。
- 新版本不再声明的权限立即失效。
## 授权与 Agent、流水线设置的关系
在 Agent 或流水线里选择工具,并不会授予任何权限,只是缩小模型能看到的范围。像 LocalAgent 这样的运行器,提供给模型的是两者的交集:Agent(或流水线 **扩展集成** 页面)中选中的工具,与运行器插件安装已获得的操作授权。如果什么都没选,模型就拿不到任何工作区工具。
因此,能编辑 Agent 的成员可以选中一个自己无权授予的工作区操作:除非有足够权限的成员已经把这个操作授予了运行器插件,否则这个选择不会产生任何效果。
## 兼容模式
在插件权限机制出现之前编写的插件没有 `spec.permissions`,LangBot 以兼容模式运行它们:
- 它们获得固定的**全部 16 项旧版插件能力**,**不包含任何工作区操作**。
- 成员必须一次性确认整组能力,不能只确认其中一部分,因为 manifest 里没有信息能说明哪个子集是安全的。确认之后,成员可以逐项撤销。
- 确认需要同时具备 `resource.view`、`resource.manage` 和 `runtime.operate`。
- 以后 LangBot 新增的能力,不会自动加入已经确认过的这组授权。
升级 LangBot 之前就已存在的安装,会在迁移时直接带上这组已确认的授权,并保持原来的启用状态。已确认的兼容模式安装升级到另一个兼容模式版本时,会自动获得全部旧版能力并保持原来的启用状态。全新安装兼容模式插件、升级尚未确认的兼容模式安装,或者升级到删除了原有权限声明的版本,都会让它停用,直到成员再次确认。
## 处理被拒绝的调用
常规 SDK 方法会抛出错误,错误数据中带有 `code: permission_denied`,必要时还有 `denied_capabilities`。工作区 API 的调用不会抛出异常,而是返回 `{"ok": false, "error": {...}}`,错误码相同。无论哪种情况,都应把权限不足当作正常结果来处理:记录日志、告诉用户缺少哪项权限,然后在没有这项功能的情况下继续运行。
## 通过接口管理权限
WebUI 使用以下接口,你也可以用成员令牌调用:
- `GET /api/v1/plugins/{author}/{plugin_name}/permissions`:返回每一项已声明的权限及其 `granted`、`grantable` 状态,安装是否处于兼容模式或待确认,以及调用者的 `can_manage`、`can_confirm`。工作区操作带有所属的 `domain`,响应中的 `domains` 列出各领域的名称。
- `PUT /api/v1/plugins/{author}/{plugin_name}/permissions`:接收 `workspace_operations`、`capabilities` 和 `confirm`。`confirm: false` 时,列表必须是当前授权的子集,因此这种形式只能用来撤销;`confirm: true` 时适用上文的完整确认规则。
- 插件列表和详情接口的返回中包含 `permission_status`,其中有 `compatibility_mode` 和 `pending_confirmation`。
对应的 Application API 操作是 `plugin.permissions.get` 和 `plugin.permissions.update`。LangBot 的 MCP 服务提供 `get_plugin_permissions` 和 `revoke_plugin_permissions`;使用 API Key 认证的 MCP 客户端不能确认新的授权。