10 KiB
插件
插件是 WeKnora 扩展能力的打包与分发单元:模型厂商、数据源、联网搜索、文档解析、技能、MCP 服务等都可以由插件提供。内置能力本身也以内置插件的形式登记,和第三方插件共用一套目录与开关。
两类角色分工如下:
| 系统管理员 | 空间管理员 | |
|---|---|---|
| 做什么 | 安装、升级、回滚、卸载插件,填写平台配置 | 在本空间启用或停用插件,填写空间配置 |
| 入口 | 「设置 → 插件管理」 | 「设置 → 插件」 |
安装后的插件对所有空间可见,但默认停用,由各空间管理员自行启用。停用插件后,它的集成不再出现在类型列表中、不能新建,已有实例照常工作。
插件的运行方式
插件包是一个 .wkp 文件(根目录带 plugin.yaml 的 zip)。runtime.type 决定插件代码在哪里运行:
| 运行方式 | 说明 | 适用 |
|---|---|---|
declarative |
没有代码,由 WeKnora 解释清单 | 技能、模型厂商定义、远程 MCP |
host |
WeKnora 的插件宿主拉起的子进程,kind 为 binary 或 python |
自托管的代码插件 |
remote |
插件作者自行部署的 HTTP 服务,安装时登记地址 | SaaS 类插件、独立团队维护的服务 |
代码插件与 WeKnora 之间走统一的扩展协议 v1(HTTP + JSON,流式同步用 NDJSON)。
安装插件
- 以系统管理员身份打开「设置 → 插件管理」,点击「安装插件」。
- 上传
.wkp或填写下载地址。WeKnora 先解析插件包,展示它提供的能力、申请的权限(可访问的外部域名、Host API 权限等)和包摘要。 - 确认后安装。安装请求带着审阅时的摘要,下载地址在此期间换了内容会被拒绝。
同一插件再次安装更高版本即升级,旧版本保留,可在详情中回滚。
远程插件
runtime.type: remote 的插件在安装时还需填写服务地址:
- 服务在内网时,需把地址加入
SSRF_WHITELIST。 - 安装后 WeKnora 生成一个签名密钥,只显示这一次。把它配置为服务的
WEKNORA_PLUGIN_SECRET环境变量,服务据此确认请求来自 WeKnora。 - 插件详情中可以修改服务地址或轮换密钥。轮换后,服务换上新密钥之前的调用都会失败。
- 服务版本必须与安装的插件包一致,否则插件显示为异常、调用被拒绝。升级时同时升级服务与插件包。
运行代码插件
内嵌宿主(默认)
默认情况下,每个 app 进程自带插件宿主,在本机运行已安装的 host 插件:
- 插件进程只拿到
WEKNORA_PLUGIN_*环境变量,看不到数据库密码等 WeKnora 密钥。 - 出网流量经宿主的出口代理,只放行插件在
permissions.egress中声明的域名,内网地址一律拒绝。 - 宿主检查运行的进程与安装的包一致,健康检查失败时按退避重启,并在插件详情中显示为「异常」。
- Python 插件使用本机的
python3(可用WEKNORA_PLUGIN_PYTHON指定解释器)。Docker app 镜像已带 Python。 - 在 Linux 上,插件进程按
runtime.resources限制资源:- 内存总是受限。插件没有声明时,按
WEKNORA_PLUGIN_MEMORY_DEFAULT(如1Gi)限制,未设置则不限。 - CPU 需要把一个可写的 cgroup v2 目录委托给 WeKnora,并通过
WEKNORA_PLUGIN_CGROUP指定。设置后,每个插件进程进入各自的子 cgroup。
- 内存总是受限。插件没有声明时,按
独立插件宿主
插件较多、希望把插件与 app 隔开,或 app 节点不便运行 Python 时,可以单独运行 WeKnora plugin-host:
- 它与 app 使用同一镜像,共用数据库、Redis、对象存储和
SYSTEM_AES_KEY(或JWT_SECRET)。 - 启动后每 5 秒在 Redis 中通告自己运行的插件。app 按版本挑选最空闲的宿主,用由
SYSTEM_AES_KEY派生的密钥签名调用它。 - 宿主停止时先撤回通告,再等进行中的调用结束。
- 插件详情的「节点状态」中,
plugin-host:开头的就是独立宿主。
docker compose 启用方式:在 .env 中设置
WEKNORA_PLUGIN_EMBEDDED_KINDS=none
WEKNORA_PLUGIN_HOST_API_URL=http://app:8080
然后执行:
docker compose --profile plugin-host up -d
Helm 设置 pluginHost.enabled=true 即可。使用本地存储(STORAGE_TYPE=local)时,插件包存放在 data-files 卷中,该卷需支持多 Pod 读写(ReadWriteMany)。
相关环境变量:
| 变量 | 作用于 | 说明 |
|---|---|---|
WEKNORA_PLUGIN_EMBEDDED_KINDS |
app | app 自己运行的 kind(binary、python,逗号分隔);none 表示全部交给独立宿主。默认本机能跑的都跑 |
WEKNORA_PLUGIN_HOST_API_URL |
app、plugin-host | 不在 app 本机运行的插件(远程插件、独立宿主上的插件)回调 Host API 的地址 |
WEKNORA_PLUGIN_HOST_KINDS |
plugin-host | 宿主运行的 kind,默认本机能跑的都跑 |
WEKNORA_PLUGIN_HOST_ADDR |
plugin-host | 监听地址,默认 :8081 |
WEKNORA_PLUGIN_HOST_URL |
plugin-host | app 访问该宿主的地址,默认 http://<主机名>:<端口>;Helm 中为 Pod IP |
WEKNORA_PLUGIN_PYTHON |
两者 | Python 插件的解释器,默认 python3 |
独立宿主需要 Redis,且所有节点的 SYSTEM_AES_KEY(或 JWT_SECRET)必须一致。app 不运行某个 kind、又没有配置独立宿主时,该 kind 的插件在插件详情中显示为加载失败,并说明原因。
插件页面
插件可以在界面上加三种页面:
| 贡献点 | 出现在 | 默认最低角色 |
|---|---|---|
pages |
工具箱的一个标签页 | viewer |
settingsSections |
设置窗口「插件」分组下的一节 | admin |
kbTabs |
每个知识库的一个页签 | viewer |
页面是插件包 ui/ 目录下的 HTML,WeKnora 通过 /api/v1/plugin-ui/assets/... 提供。
- 隔离:页面在沙箱 iframe 中运行,没有同源权限,读不到 WeKnora 的登录状态和本地存储。严格的 CSP 禁止它访问网络。
- 通信:页面只能经
@weknora/plugin-ui桥与 WeKnora 通信,由 WeKnora 代发请求给插件后端,或者弹提示、确认框、跳转页面。 - 鉴权:每次请求,WeKnora 都校验空间已启用该插件、用户满足页面的最低角色,并把用户角色一并交给插件后端。
事件与 Webhook
事件:插件在 permissions.events 中声明要订阅的事件,安装时由系统管理员审阅。
| 事件 | 时机 |
|---|---|
knowledge.ingested |
文档处理完成、可被检索 |
knowledge.failed |
文档处理最终失败 |
knowledge.deleted |
文档被删除 |
chat.answered |
一次回答完成,含问题与回答内容 |
- 只有启用了该插件的空间才会向它投递事件。
- 事件经后台任务队列(有 Redis 时为 asynq)异步投递,至少一次。
- 插件返回可重试错误时,同一事件会以相同 ID 重新投递,最多 10 次。
Webhook:插件在 contributes.webhooks 中声明入站地址。
- 每个空间得到各自的秘密地址
/api/v1/plugin-callbacks/...,空间管理员可在「设置 → 插件」的「配置」中复制。 - 第三方系统调用该地址时,WeKnora 先校验地址、确认空间已启用插件,再把请求转给插件。
- 插件自行用空间配置里的密钥校验调用方。
- 设置
APP_EXTERNAL_URL后,插件还能拿到完整地址,自动向第三方注册。
插件工具
插件可以给 Agent 提供工具。工具统一按 MCP 服务接入:
- 启用了插件的空间,会在 MCP 服务列表中看到插件提供的服务(只读),其中的工具与其他 MCP 工具一样,可在 Agent 中选用,并沿用相同的工具审批设置。
- 代码插件可以自己提供工具,无需单独部署 MCP 服务。WeKnora 调用工具时带上当前空间的插件配置,所以工具使用的是空间管理员在「设置 → 插件」中填写的账号。
- 插件可以为工具结果声明展示方式(表格、卡片、键值、Markdown、插件页面),对话中按此展示结构化结果;模型读取的仍是文本结果。
动态选项与账号连接
插件的配置表单可以在填写时向插件取数据:
- 动态选项:下拉框的选项由插件实时给出,例如用填好的令牌列出项目。
- 修改选项所依赖的字段后,列表会重新加载。
- 编辑已保存的配置时,表单上没改动的密钥由服务端补齐,不会发回浏览器。
- 账号连接:字段显示为「连接账号」按钮,点击后在弹窗中完成第三方的 OAuth 授权。
- 令牌只保存在 WeKnora 服务端(加密)。每次调用插件时,WeKnora 换上有效的访问令牌,并在过期前自动刷新。
- 连接只属于发起它的空间。
使用账号连接前,系统管理员需要:
- 在第三方平台注册 OAuth 应用,回调地址填
<WeKnora 地址>/api/v1/plugin-oauth/callback。 - 在「设置 → 插件管理」的插件详情中,把应用的 Client ID 和 Secret 填进平台配置。
回调地址取自 APP_EXTERNAL_URL;未设置时,使用浏览器访问 WeKnora 所用的地址。
开发插件
- Go:pluginsdk,含协议定义、SDK、客户端和一致性测试工具
weknora-plugin-conformance。 - Python:pluginsdk/python,Python 3.9+,只依赖标准库。
- 示例:examples/plugins:
rss:数据源连接器,Go;subtitles:文档解析器,Go,使用 Host API;notebooks:Jupyter 笔记本解析器,Python;links:带三种页面的团队链接插件,Python;activity:订阅事件、接收 Webhook 的空间动态插件,Python;jira:Jira Cloud 问题同步与 Agent 工具(搜索、读取问题),支持 OAuth 授权或 API 令牌,带动态选项、增量同步与问题分诊技能,Go。
同一个插件既可以打包成 host 插件由 WeKnora 运行,也可以作为 remote 服务独立部署,代码不用改。