插件开发

tessoa 插件 是运行在沙箱中的小程序，用 TypeScript 或 Rust 编写。插件可以向右键菜单添加命令、提供整页内容、为文件列表增加列，也可以在 设置（Settings） 中加入自己的选项。本页介绍如何用官方模板开发、测试和打包插件。开始之前，你需要在电脑上准备好命令行和 Git。

备注

本页介绍的插件平台需要 tessoa 0.29.0 或更新版本。创建、测试和打包插件不需要安装 tessoa；把插件安装到 tessoa 中试用时，需要 0.29.0 或更新版本。本页的插件与 预览插件 不同：预览插件由 tessoa 官方提供，负责视频、Office 文档等格式的预览。

插件的能力

插件可以提供下表中的一项或多项能力，每一项都在插件的清单文件 plugin.toml 中声明。

能力	说明
命令	显示在右键菜单中，作用于选中的文件，例如按拍摄日期重命名照片
页	一整个标签页，或侧栏中的一节，例如计算器、任务看板。插件描述页面内容，tessoa 按自己的风格绘制
列	文件列表中新增的一列，用户可以在 列头菜单 中显示它
设置	插件自己的选项，显示在 tessoa 的设置中，由 tessoa 保存
任务	在后台运行的耗时工作，会显示进度，用户可以取消

沙箱与权限

插件运行在独立进程的 WebAssembly 沙箱中。插件看不到文件路径，也不能自行读写磁盘、访问网络或启动程序。用户选中的文件以句柄的形式交给插件；插件需要修改文件时，由 tessoa 代为执行。这些修改可以撤销，并记录在 活动记录（Activity） 中。

插件可以使用的功能分为三级：

级别	获得方式	包括
自动	不需要声明	日志、通知、对话框、选中文件的名称和大小等信息、插件自己的存储、页、设置、任务
声明	在 plugin.toml 的 [permissions] 中列出，安装时向用户展示	读取交给插件的文件、重命名选中的文件、写入剪贴板、连接清单中列出的网站等
用户确认	声明之后，还需要用户在 tessoa 中确认	保留给以后的版本：读取整个文件夹、修改已有文件的内容

只声明插件实际用到的权限。权限名称的完整列表见模板中的 sdk/docs/guide/permissions.md。

准备开发环境

1. 打开 tessoa-plugin-template，单击 Use this template 创建你自己的仓库，然后克隆到本机。
2. 在仓库目录中运行装环境脚本。脚本只安装缺少的工具：TypeScript 需要 Node.js，Rust 需要 Rust，两种语言都需要命令行工具 tessoa-plugin。

系统	命令
Windows	powershell -ExecutionPolicy Bypass -File scripts/setup.ps1 -Lang ts
macOS、Linux	bash scripts/setup.sh --lang ts

用 Rust 编写时，把命令中的 ts 换成 rust。脚本只为当前用户安装，不需要管理员权限。

创建插件项目

1. 运行 tessoa-plugin init --lang ts --id com.example.my-plugin --name "我的插件"。该命令把所选语言的骨架移到仓库根目录，填入插件 id 和名称，并删除另一种语言的骨架。
2. 运行 tessoa-plugin doctor，检查所需工具是否齐全。修好标为 FAIL 的项目之后再继续。

插件 id 必须全局唯一，采用反写域名的形式，只能包含小写字母、数字、.、_ 和 -。

编写插件

插件由两部分组成：清单 plugin.toml 声明插件提供哪些能力、需要哪些权限；src/ 目录存放代码。下面的清单声明了一个右键菜单命令，它只在选中图片时出现，并需要读取和重命名选中文件的权限：

[plugin]
id = "com.example.rename-by-date"
name = "按拍摄日期重命名"
version = "0.1.0"
api = "tessoa:plugin@0.2.0"
min-host = "0.29.0"

[entry]
kind = "wasm"
file = "dist/plugin.wasm"

[[commands]]
id = "rename-by-date"
title = "按拍摄日期重命名"
where = ["context-menu"]
when = { ext = ["jpg", "jpeg", "heic", "png"], min-selected = 1 }

[permissions]
files = ["read-selected", "rename-selected"]

模板的 examples/ 目录中有几个完整的插件，各自带有测试，可以作为参考。清单各项的含义见 sdk/docs/guide/manifest.md，接口参考位于 sdk/docs/api/。

小技巧

模板按编程助手的工作方式组织：仓库根目录的 AGENTS.md 会把助手引向 sdk/ 中的说明书。用编程助手打开仓库，用一句话描述你需要的插件，例如「右键单击选中的照片，按拍摄日期重命名」，助手即可完成创建项目、编写、测试和打包。

测试与打包

测试场景写在 tests/scenarios/*.toml 中，测试用的文件放在 tests/fixtures/ 中。tessoa-plugin test 在真实的沙箱中、针对模拟的 tessoa 运行插件，因此测试时不需要安装 tessoa。

命令	作用
tessoa-plugin test	构建插件并运行全部测试场景
tessoa-plugin run	对指定的文件运行一个命令。文件会被实际修改
tessoa-plugin check	检查清单，并审查构建结果用到的接口
tessoa-plugin package	打包为 dist/<id>-<version>.zip；审查不通过时拒绝打包
tessoa-plugin upgrade	升级命令行工具和 sdk/，下载前核对签名和校验和

在 tessoa 中试用插件

1. 启动 tessoa 0.29.0 或更新版本。
2. 在插件项目中运行 tessoa-plugin install。该命令先构建并审查插件，再把项目文件夹交给正在运行的 tessoa。
3. 首次安装时，tessoa 在自己的窗口中列出插件需要的权限，确认之后插件生效。此后每次重新构建，tessoa 都会自动重新加载插件。

把插件安装到 tessoa 中需要有效授权；创建、测试和打包插件不需要授权。

发布插件

在插件社区发布插件的功能正在筹备中。在此之前，你可以把打包好的 ZIP 和源码放在自己的 GitHub 仓库中分享。模板中的骨架和例子按 MIT 许可发布，用它们开发的插件可以自由使用、修改、发布和出售；sdk/ 另有许可，见 sdk/LICENSE.zh-CN.md。

参见

插件社区 · 插件模板 · 预览插件 · 活动记录