Plugin Usage

插件使用

面向桌面端用户。开发插件请看 插件开发。English: Plugin usage。

插件系统目前只在 Electron 桌面客户端可用。浏览器、Docker 前端镜像没有安装入口。

安全须知

• 带 worker.js / main 的本地插件拥有完整 Node.js 权限。Worker 只隔离崩溃和超时，不能阻止恶意代码读写本机文件、环境变量或自行联网。
• 只安装并启用你审查过、信任的代码。
• 页面型插件在受限 iframe 中运行，不能读取宿主页面、Token 或 Electron API。
• 启用时会列出 Manifest 中的全部权限。repositories:read / privateRepositories:read 会单独提示：读取范围包含你已收藏的私有仓库元数据。
• 宿主不会把 GitHub Token、AI Key、WebDAV 密码交给插件。

打开插件设置

1. 打开桌面客户端。
2. 进入 设置 → 插件。
3. 如果看到「插件系统目前仅在 Electron 桌面端可用」，说明当前不是桌面客户端。

插件安装目录位于应用用户数据目录下的 plugins/：

系统	目录
macOS	~/Library/Application Support/GitHub Stars Manager/plugins/
Windows	%APPDATA%\GitHub Stars Manager\plugins\
Linux	~/.config/GitHub Stars Manager/plugins/

同级还有 plugin-data/（隔离存储）和 plugin-logs/（脱敏日志）。不要手动改这些文件，除非你在排查问题。

安装

1. 在 设置 → 插件 点击 安装本地插件。
2. 选择插件目录（目录内必须有 manifest.json）。
3. 安装成功后插件出现在列表中，状态为 已禁用。

安装时宿主会复制整个目录，并拒绝：

• 符号链接
• 超过 2000 个文件，或合计超过 50 MiB
• 无效 / 过大的 manifest.json（上限 256 KiB）
• 入口文件落在插件目录外
• 已经安装过相同插件 ID

官方示例在仓库的 examples/plugins/。克隆源码后，安装时直接选对应子目录即可。

启用

1. 打开插件卡片上的开关。
2. 阅读确认框：Worker 不是沙箱，以及请求的权限列表。
3. 点击 确认并启用。

启用后状态变为 已启用。如果 Manifest 权限相对上次授权有增减，下次启动会进入 错误，提示权限已变更，需要重新确认。

停用会停止 Worker，并关闭已打开的插件页面。再次启用仍需当前 Manifest 权限全部获批。

插件会出现在哪里

只有 已启用且状态为 Active 的贡献项才会出现。

贡献	入口	说明
repository-card 操作	Stars 视图仓库卡片菜单	对当前仓库执行，例如复制 Markdown
bulk-toolbar 操作	多选仓库后的批量工具栏插件菜单	对选中的仓库执行
导出器 exporters	同一批量工具栏插件菜单	生成文本文件并触发浏览器下载
Release 处理器	Releases 时间线或仓库 Release 面板中的「插件资产推荐」	点 分析 得到推荐资源；有 downloads:create 时才显示 宿主下载
页面 pages	设置 → 插件 卡片上的 打开页面：…	在设置页内的隔离 iframe 中打开

repositoryProcessors（仓库处理器）目前已有宿主 API，但 没有独立按钮。用户界面不会单独列出它。

仓库操作结果

插件不能直接改宿主 UI。它返回一种意图，由宿主执行：

• 复制到剪贴板（需 clipboard:write）
• 保存为文本文件
• 在系统浏览器打开 HTTPS 链接（需 external:open，且不能带账号密码）
• 弹出提示

Release 推荐与下载

1. 打开某个 Release。
2. 在「插件资产推荐」中点 分析。
3. 查看推荐文件名、原因和置信度。
4. 若插件有 downloads:create，点 宿主下载。
5. 在系统保存对话框中确认来源、文件名和保存位置。

插件拿不到下载 URL 和本地路径，也不能自动安装。取消保存对话框不会报错。

插件网页搜索（SearXNG）

页面插件可以申请 web:search。默认关闭，没有内置公共搜索实例。

1. 在 设置 → 插件 顶部填写你信任的 SearXNG HTTPS 地址，例如 https://search.example.com。
2. 该实例必须开启 JSON 输出。
3. 点击 保存搜索服务。留空再保存即关闭。

每次插件搜索都会弹出确认框，展示实例地址和完整搜索词。拒绝则不会发出请求。不要把私有仓库、个人备注或密钥放进搜索词。

地址必须是公网 HTTPS 主机名：不能带账号密码、不能是 localhost / 内网 / IP。宿主会请求 {endpoint}/search?q=…&format=json，不跟随重定向。

卸载

点插件卡片上的删除按钮，然后选择：

选项	效果
保留数据并卸载	删除安装目录，保留 plugin-data 和日志
卸载并删除数据	同时删除该插件的隔离存储和日志

安装目录总会被删除。同 ID 再次安装时，若上次选择了保留数据，存储文件可能仍在。

官方示例

源码仓库 examples/plugins/：

目录	作用	启用后出现在
markdown-exporter	复制 / 导出星标为 Markdown	仓库卡片菜单、批量工具栏
smart-release-recommender	按当前系统架构推荐 Release 资源	Release 详情的「插件资产推荐」
repo-health-page	在隔离页面里搜索本地仓库快照	设置页 打开页面：Repository Health

安装后请先读该目录的 worker.js 或 ui/，再启用。

排错

现象	处理
设置里提示仅桌面端可用	改用 Releases 桌面客户端
安装失败	确认目录含合法 manifest.json，没有符号链接，体积未超限，插件 ID 未安装过
列表底部「无法加载的插件」	Manifest 或入口校验失败，错误码和原因会显示在条目上
状态为 错误	卡片会显示 lastError。常见原因：Worker 启动失败、调用超时（默认 5 秒）、权限相对上次授权已变更
页面搜索无结果	先同步星标；页面只搜索宿主内存里的脱敏快照，不是实时 GitHub
网页搜索失败	检查 SearXNG 是否 HTTPS、是否开启 JSON、是否公网可解析
AI 调用失败	先在设置里配置并激活 AI Provider；每次调用都要确认
启用 Worker 插件后本机异常	立刻停用并卸载。Worker 不是沙箱

刷新按钮会重新扫描 plugins/ 目录。