插件使用

自 v0.91.0 起

插件是以 .tpg 文件分发的 Tavo 扩展包。

插件可能提供什么

插件自己的设置页。
将聊天文件解析为文本或 Markdown。
聊天输入框 + 菜单里的动作。
聊天右侧边栏里的动作。
聊天 UI 片段，既可以是游戏等沉浸式全屏界面，也可以是状态栏、局部控制面板或消息装饰。全屏界面的操作控件仍需避开顶部导航栏和系统安全区，辅助界面则建议只占用所需空间。
功能标签，让你知道它会改动哪些地方。

只安装可信插件

插件包可能包含脚本和 UI 片段。请只安装你信任的创作者提供的文件；如果无法确认来源和内容，不要安装陌生人转发或来源不明的 .tpg 文件。

安装插件

打开 设置。
进入 插件。
点击右上角导入按钮。
选择 .tpg 插件包。
阅读安装风险提示，只在信任该文件时继续。

安装后，插件会出现在插件列表中。

管理插件

在 设置 -> 插件 中，你可以：

启用或禁用插件。
打开插件设置页。
按名称、id、作者、简介或版本搜索已安装插件。
卸载插件。

如果插件提供了设置项，进入插件详情页后可以调整。该页面的重置操作会把带默认值的字段恢复为默认值。

聊天文档解析

文件处理插件可以把聊天文件转换成文本或 Markdown。安装官方「文档解析器」后，启用插件和高级渲染，从聊天输入框添加文件并发送。纳入上下文的历史附件也会使用当前启用的处理器，因此更改插件或格式开关会影响后续请求。解析结果会缓存，重启后可继续复用，可在「存储空间」中清理，文件或解析设置变化后会重新解析。

官方插件默认开启文本（TXT、Markdown、CSV/TSV、JSON/JSONL/NDJSON）和 PDF， Word（DOCX）、Excel（XLS/XLSX）、PowerPoint（PPTX）需要在插件设置中开启。 PDF 不做 OCR，DOC、PPT 不在此插件支持范围内。

插件设置可调整文件大小、解析结果长度、解析超时和文件内容模板。大小超限时会提示并保留草稿，不会截断结果，调整限制后可以重试。默认模板包含说明和文件信息，留空则直接发送解析正文。可使用 {{text}}、{{fileName}}、{{mimeType}} 插入正文、文件名和文件类型，参数会进行 XML 转义，且只替换一次。

没有匹配的启用处理器，或高级渲染未开启时，Tavo 会尝试按当前 API 协议发送原文件，是否接收取决于端点和模型。已匹配处理器解析失败时不会改为直接发送。

插件语言

支持国际化的插件会跟随 Tavo 明确选择的 App 语言。如果 Tavo 设为跟随系统，插件会使用设备当前语言，即使 Tavo 自身界面没有提供该语言。

插件可能没有覆盖所有语言或所有文案。Tavo 会先尝试用户语言和兼容变体，再回退到 English，然后是插件声明的默认文案。如果作者引用了未解析的翻译 key，最终可能会直接显示该 key。

更改 App 或系统语言后，插件名、动作标签、设置项等原生插件文案会自动更新。插件自己编写的 HTML/JavaScript UI 只有在插件监听 tavo.plugin.i18n.onChange 并自行重新渲染时才会更新。Tavo 不会自动改写任意插件 DOM。两种情况都不需要重新安装插件。

高级渲染

会修改聊天 UI 的插件需要开启 高级渲染 才能在聊天页生效。

聊天 UI 片段属于已安装插件的 runtime 代码，不会被聊天内容的 JavaScript 执行模式禁用；该模式只控制角色卡、模型输出和其它消息气泡内容中的脚本。

如果插件标注了 聊天 UI，但聊天页没有变化，请检查：

设置 -> 高级渲染 已开启。
插件本身已启用。
插件包内包含 manifest 引用的 UI 片段文件。

安装失败排查

如果插件无法安装，Tavo 会在写入已安装插件之前拒绝它。常见原因包括：

插件包根目录没有 manifest.json。
manifest.json 为空或不是合法 JSON。
插件包里有不安全路径，例如绝对路径或 ../。
manifest 声明了输入动作或侧边栏动作，但 entry 指向的文件不存在。
manifest 使用了不支持的字段或错误的贡献格式。
插件使用了当前 Tavo 尚不支持的新版 specVersion。请先将 Tavo 升级到最新版，再重新安装。

开发自己的插件

插件作者请阅读插件开发。里面会介绍插件包结构、manifest.json、HTML 片段、设置 schema，以及如何用 AI Agent 或对话式 AI 辅助编写插件。

目录