企业官网建设流程全解析

• 桌面应用

本文基于 Olib（OlibTauri 仓库）的 dev_docs/plugin-development.md 与随应用内置的 插件开发指南 展开，并结合src-tauri/src/plugins/下各模块源码（manifest / installer / runner / service / resolvers / location / usage / guide）与 内置插件清单 进行源码级印证。读者将掌握：插件系统为什么是"声明式"的、8 个 Rust 模块各自承担的职责、插件从"寻找工具 → 筛选 → 实测 → 写清单"到"加载 → 下载校验 → 安装 → 右键调用"的完整链路，以及清单 JSON 的全部字段规则、安全边界与常见排错方法——足以亲手为 Olib 写出一份可被信任、可正常安装运行的第三方插件清单。

Olib 的插件系统是其"按需扩展能力"的核心：用户不需要额外安装任何运行时，应用本身也不为每个工具编写专属代码。一个插件 = 一份 JSON 清单，把一个现成的命令行工具包装成书架右键菜单里的一个功能。下载、换源、sha256 校验、解压、调用、进度显示、卸载全部由 Olib 完成，插件作者（无论是人还是 AI Agent）不需要写一行 Rust、不需要编译。

一、整体架构：声明式插件与 8 个职责清晰的 Rust 模块

插件系统全部实现集中在 src-tauri/src/plugins/ 目录下，模块分工如下：

内置清单位于 src-tauri/plugins.builtin.json，通过include_str!编译进二进制（见 mod.rs），用户订阅的远程 registry 则缓存到app_data/registries/。

这套架构有一个核心设计原则：插件之间的所有差异都由清单声明，通用引擎不含任何插件专属逻辑。installer.rs的模块注释直接点明这一点："插件之间的差异全部由清单（manifest）声明，这里不含任何插件专属逻辑"。例如 Calibre 的路径长度上限、解压后多一层Calibre Portable子目录、stdout 的NN%进度格式、支持的输入输出格式，全部是 plugins.builtin.json 里的声明，而不是 Rust 里的硬编码（这一点在 dev_docs/format-conversion.md 中有明确说明）。

信任边界：清单来源决定安全级别

manifest.rs 定义了三种清单来源：

• Builtin：随应用编译，等同应用自身，允许使用动态解析器取最新版；
• Remote：用户订阅的远程 registry，必须提供 sha256；
• Local：开发者本地导入（调试用）。

安全模型的关键在于：安装即执行外部可执行文件，没有校验和等同于放任远程代码执行。因此第三方清单强制要求 sha256，否则整个插件源在加载阶段就会被拒绝。

二、插件源加载：内置 + 本地订阅 + 远程订阅

加载逻辑在 plugins/mod.rs 的init()中：

1. 先解析编译进二进制的内置清单（坏了属于应用自身缺陷，记录日志但不 panic）；
2. 再扫描app_data/registries/*.json（只认.json后缀），逐个解析；单个源解析失败只跳过该源，坏掉的第三方源不会拖垮内置插件；
3. 用HashSet去重：id 冲突时内置优先，第三方不能顶替官方插件。

对用户而言有两条接入通道：

• 「插件」页「刷新」按钮：调用reload_plugin_registries命令重新扫描（plugin_commands.rs）。AI Agent 刚放进本地registries/目录的新清单无需重启即可生效；
• 「添加插件源」：订阅远程 https 地址（AddSourceModal.tsx）。底层subscribe()（mod.rs）的执行顺序为：要求https://前缀 → 拉取 → 按第三方规则解析校验（不通过就不落盘）→ 以 URL 哈希命名写入registries/→ 重新加载。校验失败时整个源被拒，且不会把坏清单持久化到磁盘。

三、插件装在哪：默认路径、自定义位置与安全迁移

默认安装根目录（location.rs）：

• Windows：%ProgramData%\Olib\plugins\<id>\
• macOS / Linux：~/.olib/plugins/<id>\

刻意选择了短路径：某些安装器对路径长度有硬限制（Calibre 便携版要求总路径含自建的Calibre Portable子目录少于 59 个字符，参见 format-conversion.md 与 mod.rs 单测），app_data 这类长路径会导致静默失败。卸载 = 删除该插件的<id>目录，不写注册表、不留残留。

用户可在「插件」页顶部更改安装位置（配置项plugins_dir，空 = 默认），迁移逻辑在location.rs的relocate()中，有几条重要的行为约定：

• 改位置时把已知插件 id的子目录迁到新位置：同盘直接改名，跨盘复制后删除源；中途失败会回滚已迁的，保证要么全迁、要么全不迁；
• 旧目录里的其他内容不动，旧根目录空了才顺手删除；
• 迁移前停掉应用拉起的常驻服务（否则文件被占用、目录挪不动）；有插件正在安装或有插件任务在跑时拒绝迁移；
• 新位置已有同名子目录时不覆盖，保留新位置那份，旧目录原样留下；
• 清单声明了max_path_len的插件在新位置超长时，页面会提示「将无法在这里安装」（不阻止更改）；
• plugins_dir只能经set_plugins_location修改——config_commands.rs 中通用的set_config会以当前值覆盖前端传来的值，防止绕过迁移流程。

从源码结构看，set_plugins_location命令（plugin_commands.rs）与get_plugins_location共同构成这一配置项的唯二入口，前端 plugin.ts 将其封装为getPluginsLocation/setPluginsLocation。

四、内置插件与收录标准

当前内置 7 个插件（plugins.builtin.json），覆盖格式转换、PDF 工具、OCR、文档转换与文本处理：

收录到内置清单的条件：开源、可离线运行、不上传用户文件、license 明确、锁定版本并带 sha256。新增前还要按指南的「实测」步骤在中文路径 + 非工具目录下验证过命令。内置插件同样有测试钉住关键约束：builtin_registry_is_valid、version_pinned_builtin_sources_have_checksums（锁定版本的下载源没有校验和是明确的退步）等（mod.rs tests）。

五、面向插件作者 / AI Agent：四步开发法

完整的开发规范已内置到应用里：guide.md（编译进二进制）。用户打开「插件」页时，guide.rs 把它渲染——填入本机路径与内置插件列表——后写到%APPDATA%\com.shiyi0x7f.olibfluent\plugin-dev-guide.md，本机的 AI Agent（Claude Code、Codex、Cursor 等）直接读取该文件。前端 AgentGuide.tsx 提供「复制指令」按钮，生成一段引导 Agent 阅读指南、实测并落盘清单的 prompt。

指南把开发流程压缩为找工具 → 筛选 → 实测 → 写清单四步，每一步都要求实际执行命令验证，不要凭文档或记忆推测参数、路径和下载地址。

第一步：寻找候选工具

1. Scoop 软件仓库（最推荐）：Scoop 清单直接记录了"便携版 zip 的固定下载地址 + sha256"，正好是 Olib 需要的。关注version、architecture.64bit.url（或顶层url）、hash、extract_dir、bin。注意 URL 末尾若有#/xxx是 Scoop 的重命名标记要去掉；hash仍需下载后亲自复算核对；
2. GitHub 搜索：用英文关键词 +cli/command line，优先 star 多、最近一年内有发布的项目；
3. 查看发布文件：用 GitHub API 列出最新版 assets（releases/latest或按 tag 指定），挑选含windows/win64/x86_64/x64/msvc/mingw64/portable、扩展名为.zip（或可静默解压的自解压.exe）的文件；排除.msi、安装向导、arm64、32 位、源码包；若项目提供.sha256/checksums.txt，下载后交叉核对；
4. 官方网站的 Download / Portable 页面：只在前三步找不到时使用，且下载地址必须是固定版本、https。

第二步：筛选（必须全部满足，否则淘汰）

• 能用「一个输入文件 → 一个输出文件」的命令完成，参数里能写出{input}和{output}（只能从 stdin 读、只能输出到 stdout、只能指定输出目录、需要交互确认或只有 GUI 的淘汰）；
• Windows x64 便携包：zip 或可静默解压的自解压 exe，解压即用；单个裸 exe、msi、安装向导都不支持；
• 不依赖额外运行时（不能要求用户另装 Python、Java、.NET、Node.js、VC++ 运行库等，随包自带的除外）；
• 完全离线：处理过程不联网、不上传文件；
• 开源且 license 明确；体积几十 MB 内为佳，超过 200 MB 先征求用户同意；
• 不涉及去除 DRM 等版权风险功能。

第三步：实测（Windows PowerShell，逐条执行并记录）

# 1. 下载并计算 sha256（取小写），记录体积用于 min_bytes（取实际体积约 70%） Invoke-WebRequest "<下载地址>" -OutFile pkg.zip -UseBasicParsing (Get-FileHash pkg.zip -Algorithm SHA256).Hash.ToLower() (Get-Item pkg.zip).Length # 2. 解压到另一个空目录，记录主程序相对解压目录的路径（含压缩包自带的顶层目录） Expand-Archive pkg.zip x Get-ChildItem x -Recurse -Filter *.exe | ForEach-Object { $_.FullName } # 3. 运行 <exe> --help 确认参数写法 # 4. 准备真实样本文件，放在含中文和空格的路径下，如 D:\测试 目录\样例 书.pdf # 5. 切换到与工具无关的其他目录再运行完整命令（Olib 调用时不保证工作目录） & "<exe 绝对路径>" <参数，用样本路径代替 {input}，用输出路径代替 {output}> $LASTEXITCODE # 必须是 0 Test-Path "<输出路径>" # 必须是 True，并打开确认内容正确

两个容易踩坑的细则：若工具成功时退出码也不是 0（如 qpdf 有警告时返回 3），要找让它返回 0 的参数（qpdf 是--warning-exit-0），找不到就换工具；若工具会在标准输出打印百分比进度，可写progress_regex并用真实输出验证匹配。

第四步：写清单并交付

1. 按「清单格式」写 registry JSON，逐条对照「字段规则」自查；
2. 保存为{{REGISTRIES_DIR}}\<插件 id>.json（目录不存在就创建，文件用 UTF-8 编码）；
3. 告诉用户：去 Olib「插件」页点「刷新」→ 找到插件点「安装」→ 到「书架」右键对应文件使用；
4. 给用户一份测试报告：工具名、版本、license、下载地址、sha256、实际运行的命令和结果（退出码、产物大小）、已知限制；
5. 如需分享：把 JSON 放到任意 https 地址，对方在「插件」页点「添加插件源」填入该地址。

如果找不到满足条件的工具，直接说明原因和替代方案，不要写一份装上了也用不了的清单。

六、清单格式详解（schema_version 1）

一个文件就是一个「插件源」，可包含多个插件。完整格式示例：

{ "schema_version": 1, "plugins": [ { "id": "pdf-pagenum", "name": "PDF 页码工具", "description": "一句话说明插件能做什么，显示在插件页。", "capability": "pdf-tools", "publisher": "工具作者", "homepage": "https://github.com/author/tool", "license": "MIT", "inputs": ["pdf"], "outputs": ["pdf"], "targets": { "windows": { "download": { "sources": [ { "name": "GitHub", "url": "https://github.com/author/tool/releases/download/v1.2.0/tool-win64.zip" } ], "sha256": "<64 位小写十六进制>", "min_bytes": 1048576 }, "install": { "kind": "zip" }, "entry": "tool-win64/tool.exe" } }, "exec": { "actions": [ { "id": "add-page-numbers", "name": "添加页码", "description": "鼠标悬停时显示的说明。", "args": ["stamp", "--page-numbers", "{input}", "{output}"], "output_suffix": "-页码" } ] } } ] }

（以上工具和参数只是格式示意，实际以实测为准。）

插件顶层字段

源码层面，manifest.rs 的validate()是这些规则的最终裁判：id 字符集、entry 非空且不含..、下载源必须 https、必须有下载源（sources 或 resolver 至少其一）、第三方必须带合法 sha256（64 位十六进制）、必须声明 exec 或 service、exec 必须声明 args 或 actions、动作 id 不重复、动作 id 不得与 outputs 重名等。

targets.<平台>.download

下载引擎在 installer.rs：国内加速代理（https://down.npee.cn/?+ 原始 URL）优先，慢速判定阈值 300 KB/s（探速 12 秒）、卡死超时 30 秒、自动换源（最后一个源不再因慢而放弃），下载完成后校验 content-length 与expected_total是否一致。

targets.<平台>.install

install_zip（installer.rs）自带zip slip 防护：只接受entry.enclosed_name()认可的安全相对路径，任何逃逸出安装目录的条目都会被拒绝；Unix 下还保留解压文件的可执行位。

targets.<平台>.entry

解压后主可执行文件的相对路径（用/分隔）。很多压缩包自带一层顶层目录，要写完整（例如 qpdf 的qpdf-12.4.2-msvc64/bin/qpdf.exe）。不得包含..。Olib 以「entry 是否真实存在」判定安装成败（installer.rs），不信任安装器的退出码——某些安装器失败时退出码仍为 0。

exec：一次性命令行调用

args与actions至少要有一个。

动作（exec.actions[]）

动作是"只写 JSON 就能加功能"的扩展点。源码测试builtin_actions_are_wired_correctly（mod.rs）专门钉住了动作语义：Calibre 的「瘦身优化」必须指向ebook-polish.exe而非主 entry（这正是ActionSpec.entry覆盖存在的理由），且只吃 EPUB/AZW3、不能继承 calibre 那一长串转换输入格式。

七、Olib 如何调用插件：运行契约

等价于在命令行执行：

<安装目录>\<id>\<entry> <展开后的 args>

• 占位符只有两个：{input}是用户在书架上右键的那个文件的绝对路径，{output}是 Olib 生成的产物绝对路径（与输入同目录，按output_suffix/output_ext命名，重名时自动加序号）；
• 工作目录不固定。工具的配置文件、数据文件需能被它自行找到（例如 OpenCC 的-c s2t.json会在它自己的 share 目录里查找）；
• 不弹出控制台窗口（Windows 下用CREATE_NO_WINDOW）；标准输出用于解析进度，标准错误在失败时取末尾几行展示给用户；
• 成败判定：退出码为 0 且产物文件真的生成才算成功（runner.rs）。成功后产物出现在书架上，并带「已××」标记。

runner 的细节值得注意：

• unique_output_path生成不冲突的输出路径：同目录、原文件名 + 后缀 + 新扩展名，已存在则追加" (n)"（runner.rs）；
• 传给外部进程的路径会去掉 Windowscanonicalize产生的\\?\前缀（不少外部程序不认扩展长度路径），而落库记录用规范化路径——保证书架上的「已转换 / 已瘦身」标记能匹配上（runner.rs 与对应单测）；
• 加工记录是持久化的（写入 database.rs 的plugin_outputs表）：任务表是内存态、重启即失，但"这个文件被加工过"的标记必须留住。

动作产物的任务记录把动作 id 存进target_format字段（转换任务存的是目标格式），前端据此回查动作名来显示「已瘦身优化 / 瘦身优化生成」等标记——这就是清单校验中"动作 id 不能与输出格式重名"的深层原因（usePluginProcessing.ts）。

八、安全规则（不满足会导致整个插件源被拒绝加载）

1. 第三方插件必须提供sha256，Olib 安装前逐字节校验，不匹配就删除并拒绝安装；
2. 所有下载源必须是 https；
3. entry（含动作的entry）不得包含..；zip 解压时会拒绝任何逃逸出安装目录的条目（zip slip 防护）；
4. output_suffix不得含路径分隔符；output_ext只能是字母数字；
5. Olib不执行插件包里的任何脚本，只调用清单声明的entry；
6. 第三方插件不能使用resolver（动态获取最新版）：动态地址无法预知 sha256，也就无法校验。请锁定具体版本，发布新版时更新清单即可；
7. 第三方插件请只用exec。service（常驻 HTTP 服务）需要 Olib 内置对应的处理逻辑，第三方声明了也无法工作；
8. 插件 id 与内置插件冲突时内置优先，第三方不能顶替官方插件。

每条规则都能在 manifest.rs 的validate()/check_action()中找到对应实现，并有单元测试钉住（如third_party_without_sha256_is_rejected、third_party_resolver_is_rejected、entry_path_traversal_is_rejected、action_output_suffix_path_traversal_is_rejected、http_source_is_rejected等，见 manifest.rs tests）。

九、常驻服务型插件：service 契约（仅内置）

service型插件（如 Umi-OCR）不走 exec，而是声明一个常驻 HTTP 服务：应用负责拉起进程、轮询健康检查、就绪后把 GUI 收进托盘、应用退出时优雅关闭（service.rs）。ServiceSpec字段包括：

服务按需启动（第一次用到时才拉起），之后复用同一进程。测试builtin_registry_is_valid强调：OCR 引擎没有 exec、必须有 health 端点、必须声明 quit_args，否则应用退出时会泄漏孤儿进程。

同样仅内置可用的还有resolvers.rs的动态解析器（当前只有calibre-latest）：官方入口 302 后用 Range 请求只取 1 字节拿到重定向后的最终 URL，再从文件名解析版本号，拼出 GitHub release 直链（resolvers.rs）。因为动态 URL 无法预置 sha256，这个能力不对第三方开放。

十、常见问题排查

• 点「刷新」后插件页没有出现你的插件：清单没通过校验，整个文件会被跳过。逐条核对「安全规则」与「字段说明」，特别是 sha256 长度、https、id 字符、动作 id 与outputs重名、同格式动作缺output_suffix；
• 安装失败「校验和不匹配」：sha256 写错，或下载地址指向了会变化的文件；
• 安装失败「安装完成但未找到 …」：entry路径不对，通常是漏了压缩包的顶层目录；
• 右键菜单里没有动作：文件扩展名不在动作（或插件）的inputs里；扩展名要小写；
• 执行失败：看 Olib 显示的错误（来自 stderr 末尾）；用第五节的实测方法在「其他目录 + 中文路径」下复现。

十一、完整实战：内置 qpdf 插件是怎么做出来的

1. 需求「修复打不开的 PDF」→ GitHub 搜索pdf repair cli→ 选中qpdf/qpdf（Apache-2.0，持续维护）；
2. 查最新 release → 选qpdf-12.4.2-msvc64.zip（排除.exe安装包、32 位、arm64）；
3. 下载、复算 sha256；解压后主程序在qpdf-12.4.2-msvc64/bin/qpdf.exe；
4. 手写一个交叉引用表损坏的 PDF 测试：qpdf 坏.pdf 好.pdf能修好，但退出码为 3（有警告）→ 查--help找到--warning-exit-0→ 再测：退出码 0、产物可正常打开；
5. 产物与输入同为 PDF → 设置output_suffix: "-修复"。

{ "schema_version": 1, "plugins": [ { "id": "qpdf", "name": "PDF 修复（qpdf）", "description": "修复打不开、显示不全或报错的 PDF。", "capability": "pdf-tools", "publisher": "Jay Berkenbilt", "homepage": "https://qpdf.sourceforge.io", "license": "Apache-2.0", "inputs": ["pdf"], "outputs": ["pdf"], "targets": { "windows": { "download": { "sources": [ { "name": "GitHub", "url": "https://github.com/qpdf/qpdf/releases/download/v12.4.2/qpdf-12.4.2-msvc64.zip" } ], "sha256": "db87077e683630c1217e0e8f9a20a9749d952ab676e881c3689187763a5de25d", "min_bytes": 20971520 }, "install": { "kind": "zip" }, "entry": "qpdf-12.4.2-msvc64/bin/qpdf.exe" } }, "exec": { "actions": [ { "id": "repair", "name": "修复损坏的 PDF", "args": ["--warning-exit-0", "{input}", "{output}"], "output_suffix": "-修复" } ] } } ] }

（这是内置插件，所以 id 为qpdf的第三方清单会被忽略——你自己的插件请换一个 id。）测试qpdf_repair_treats_warnings_as_success（mod.rs）把这个"有警告但成功"的语义钉死在测试里，防止未来改动破坏它。

十二、对维护者的约定：改校验规则必须同步指南

guide.md里的校验规则是手写的——改了 manifest.rs 的校验或 runner.rs 的成败判定，必须同步 guide.md，否则 Agent 按指南写出的清单会被拒绝加载或装上了用不了。而 guide.md 的内置插件表由 guide.rs 从内置清单自动生成，新增内置插件无需改 guide.md（测试rendered_guide_has_no_placeholders_and_lists_builtins确保所有{{占位符}}都被填充且内置插件全部列出）。

小结

Olib 插件系统的设计可以用一句话概括：把"信任边界"画在清单解析处，把"可扩展性"寄托在声明式契约上。对插件作者而言，只需要一份通过校验的 JSON 清单；对应用而言，installer 与 runner 两个通用引擎服务所有插件，安全规则（sha256、https、路径防逃逸、不执行脚本）由 manifest 校验强制保证。理解了这些源码级细节之后，无论是手工编写第三方插件、借助 AI Agent 自动生成，还是为内置清单收录新工具，都能做到有的放矢、一次到位。

• 桌面应用