跳转到主要内容
插件代码只能做它的能力(capability)允许的事。插件在 plugin.toml 中声明能力;用户在安装时批准,新版本要求更多能力时再批准一次。缺少能力时调用受限函数会返回 Error::Denied("<capability>"),插件继续运行,可以降级处理(例如 Git Toolbox 没有 vcs.write 时依然显示分支)。
日志、通知、状态栏项、任务和运行时贡献不需要任何能力。

授权对话框

安装插件包,或允许链接插件、项目插件运行时,会弹出对话框(“安装 Word Tools 1.2.0?”或“允许 Word Tools 运行?”),逐项列出请求的能力:
  • 能力 id(如 net:api.example.com)及其允许做什么的说明;
  • 风险标记:低、中 或 高;
  • optional 能力前有复选框(低风险的默认勾选),required 能力前是圆点,安装即视为同意。
只要授予的能力里有高风险的,对话框就会提示:“高风险权限相当于在这台计算机上运行任意代码。”插件包未签名,或签名密钥与已安装版本不同时,对话框也会给出警告(见 审核规则与安全)。 之后:
  • 不要求新能力的更新沿用已安装版本的授权。要求更多能力的更新会在 设置 › 插件 中显示 需要授权,在你点击 查看权限… 并允许之前保持停用。
  • 可以在 设置 › 插件 的插件详情中撤销 optional 能力。
  • 链接的插件(openidea-plugin link)按文件夹授权;项目插件(.openidea/plugins)只在受信任的项目中、且你允许后才运行。

能力一览

API 一列是声明该能力时清单最低可以兼容的插件 API。例如声明了 net.http: 的清单必须要求 engines.openidea = "^1.4" 或更高,否则安装和 openidea-plugin check 都会拒绝。

进程

process:<program> 是最强的能力,相当于在机器上运行任意代码。
  • 声明一个程序名(process:checkstyle)。授权时,IDE 在项目所在机器的 PATH 中把它解析为绝对路径,并记录文件内容的哈希。每次启动前都会重新检查两者;文件被替换后会被拒绝,直到用户重新批准。
  • 用户可以在 设置 › 插件 中为 process: 授权选择其他可执行文件,全局或仅对当前项目生效。新选择同样会被批准并固定。插件代码仍然使用它声明的程序名。
  • process: 授权也会从贡献中推导出来:语言的 language-servers 和 debugger,以及运行检测器的 command。这些都是 optional 的,拒绝其中一个不影响插件的其他功能。
  • 进程在受信任项目的项目根目录中运行。插件只能新增环境变量,不能替换或删除已有的变量。

项目以外的文件

  • fs.read:<path> 授权读取打开的项目之外的一个目录(任意深度)或一个文件。路径先解析到真实位置再比较,所以指向授权目录之外的符号链接会被拒绝,/opt/see 也不覆盖 /opt/seeyon。授权整个文件系统(/、C:\)会被拒绝。~/ 表示用户主目录。
  • fs.write:<path> 授权在该路径下创建和替换文件。写入是原子的,会保留文件原有的编码和 BOM,单个文件上限 16 MiB;编辑器中该文件有未保存修改时写入会被拒绝。
  • host::fs::plugin_dir() 返回只属于该插件的私有目录,在其中读写不需要任何能力。它在重新加载、更新和重启后都保留,卸载时删除。

网络

  • net:<host> 允许通过 HTTPS(以及 HTTP 访问回环地址)连接该主机的任意端口。*.example.com 匹配所有子域名,不包括主域名本身。
  • net.http:<host> 允许未加密的 HTTP,但不包含 HTTPS。从 HTTPS 重定向到 HTTP 也需要 net.http:。
  • 每次重定向都会在连接前检查。响应上限 8 MiB。请求在项目所在的机器上发出。
  • net:ask(API 1.5)允许插件访问清单中没有列出的 HTTPS 主机。第一次请求新主机时会询问用户,显示插件名和主机名,选项为 这次允许、一直允许 和 拒绝(远程会话中为 本次会话内允许 和 拒绝)。“一直允许”按精确主机记住,并显示在插件的权限中,可以随时移除。没有窗口的调用(定时任务、事件处理、provider)从不询问,直接得到 denied。普通 HTTP 永远不走这个流程。

密钥

密钥在清单中声明,由用户在 设置 › 插件 中填写,保存在系统钥匙串里。
插件永远读不到密钥本身。它在请求头里写 {{secret:api-key}},由宿主在发出请求时填入。host::secret_is_set 可以判断用户是否已经填写。API 1.4 新增 secret_set 和 secret_delete(例如用来保存 OAuth token),它们同样不会返回密钥值。在远程项目中,密钥始终留在桌面端的钥匙串里。

受信任项目

无论插件被授予了什么,有些功能只在受信任项目中可用:运行进程、vcs_fetch 和较新的 Git 读取、数据库数据源、运行目标以及项目插件。在受限模式下打开的项目中,可以浏览插件市场,但不能改变正在运行哪些插件代码。