Buzz 如何通过 zip 链接添加社区插件并调整插件执行顺序？

Buzz 从 1.4.5 版本开始提供插件系统：插件可以扩展转写流程（在转写前处理音频、修改转写结果、或在转写保存后执行自定义动作），而无需改动核心代码。当你想安装社区分享的外部插件、并让多个插件按你期望的先后顺序执行钩子时，本文给出完整的操作路径：通过 zip 链接添加插件，以及在插件列表中调整执行顺序。以下操作均在 Buzz 图形界面内完成，不涉及命令行。

打开插件管理窗口

在 Buzz 主界面中，点击菜单 Help → Plugins（帮助 → 插件），打开插件管理窗口。窗口顶部有一条警告："Plugins run with full access to your system. Only install plugins from sources you trust."——插件对你的系统拥有完整访问权限，只安装你信任的来源。

通过 zip 链接添加社区插件

1. 在插件管理窗口右侧，点击 Add by URL...（通过 URL 添加）按钮。
2. 弹出的对话框标题为 "Plugin URL (.zip):"，在输入框中粘贴指向插件 .zip 文件的链接，点击 Ok。
3. Buzz 会显示 "Installing plugin..." 进度条，此时它在后台完成下载、解压、校验和安装。

这个 zip 包需要满足什么结构

根据 buzz/plugins/loader.py 中的解析逻辑和 插件开发指南 的 Packaging & distribution 一节，zip 包必须满足：

• 归档根目录，或唯一一个包装目录内（GitHub 下载的源码 zip 这种结构是支持的），存在 plugin.py 入口文件；
• plugin.py 中恰好定义 一个 BuzzPlugin 子类，且其 metadata.id 非空（插件 id 稳定、唯一，约定与文件夹名一致）；
• 可选地携带 locale/ 文件夹存放 <locale>.json 翻译文件；可选地在 metadata.pip_dependencies 中声明 pip 依赖。

一个可分发的插件包的最小布局（摘自 buzz/plugins/AGENTS.md）：

my_plugin/
  plugin.py            # 必需：定义一个 BuzzPlugin 子类
  locale/              # 可选：<locale>.json 翻译文件
    lv_LV.json

如何判断安装成功或失败

• 成功：进度条自动关闭，插件列表刷新，新插件出现在列表中并且默认处于启用状态（勾选框已勾选，见 buzz/plugins/manager.py 中 add_from_url 的自动启用逻辑）。安装后插件文件位于用户缓存目录 <user_cache_dir>/Buzz/plugins/<plugin_id>/。
• 失败：会弹出 "Add plugin failed" 警告框，内容为 "Could not install the plugin:" 加具体错误。常见错误原因（来自 loader.py 抛出的 PluginLoadError 消息）包括：
  • Failed to download plugin: ...——下载失败；
  • Downloaded file is not a valid zip: ...——链接指向的不是有效 zip；
  • Archive does not contain a plugin.py at its root or in a single folder——zip 结构不符合上述要求；
  • No BuzzPlugin subclass found in plugin.py 或 Multiple BuzzPlugin subclasses found ...——入口文件没有定义恰好一个插件子类。

失败时不会留下半成品安装。

调整插件执行顺序

多个插件同时启用时，钩子（check_skip、before_transcription、after_transcription、on_complete）按列表中用户的定义顺序依次执行，单个插件钩子里的异常会被记录日志，不会中断其他插件的执行（见 buzz/plugins/AGENTS.md 与 buzz/plugins/manager.py 中的 enabled_plugins_in_order）。

调整顺序有两种等价方式：

1. 拖拽：直接用鼠标拖动列表中的插件项改变位置（docs/docs/usage/7_plugins.md 中的说明）。
2. 移动按钮：选中一个插件后，点击右侧的 Move Up 或 Move Down 按钮逐位移动；位于首位的插件 Move Up 不可用，位于末位的插件 Move Down 不可用。

顺序和启用状态都会持久化保存，重启 Buzz 后依然生效。

配置与移除插件

• 配置：选中插件后点击 Settings... 按钮（或列表项旁的设置图标），打开为该插件生成的设置对话框。插件通过 config_fields 声明的配置项（文本、多行文本、复选框、密码）会出现在这里；其中密码类字段存储在操作系统 keyring 中，而不是明文设置文件。
• 移除：选中插件后点击 Remove 按钮，确认提示 "Remove plugin '<plugin_id>'?" 后删除。移除会删除插件目录、其已保存的配置和密码字段。

限制与注意事项

• 插件系统要求 Buzz 1.4.5 及以上版本。
• 插件声明的 pip_dependencies 会在首次加载时安装到用户缓存的 plugins_deps 目录；如果依赖安装失败，该插件会记录警告，其余插件照常加载。
• 如果安装后插件的翻译不显示，属于该社区插件自身缺少对应 locale/ 文件，不影响功能。
• 更多插件编写与打包细节（钩子线程模型、本地化规则、内置插件 ai_summary 参考实现）见 buzz/plugins/AGENTS.md；对话框交互逻辑见 buzz/widgets/plugins_dialog/plugins_dialog.py。