ReadAware

建立插件

从一个实用的动作开始。在新增功能的过程中，持续让兼容性、权限与运行时行为保持可见。

取得模板与类型

公开插件仓库包含模板、声明、登录与包检查。若涉及尚未发布的 API，请与目前源码接口约定比对，并使用相符的开发版构建。最新发布的应用可能比这份文件还旧。

仓库脚本使用 Bun。将 template/ 复制到 plugins/<your-plugin-id>/，并让目录名称与清单 ID 保持一致。

最精简的指令

这个示例在启用期间注册一个指令，并且只有在用户执行它时才产生界面效果。

json
{
  "id": "hello-reader",
  "name": "Hello Reader",
  "version": "0.1.0",
  "schemaVersion": 1,
  "main": "main.js",
  "requires": {
    "contributions": { "commands": "^1.1.0" },
    "services": { "ui": "^1.17.0" }
  }
}
typescript
export default {
  activate(ctx) {
    ctx.contributions.commands.register({
      id: "hello",
      title: "Say hello",
      run: () => ctx.services.ui.showToast("Hello, reader!"),
    });
  },
};

将入口模块编译为独立的 main.js。上述清单刻意要求目前文件记载的版本；请在检查并测试那些接口约定之后，才使用较旧的版本范围。

加入最小且实用的权限

使用 Explorer 寻找方法，并复制其起始的清单片段。片段会声明一项能力；请补齐该操作所需的授权。

  • 读取书库数据需要 library:read；变更数据则需要 library:write。
  • 设置使用精确的 settingsAccess 路径与操作。
  • 任意 HTTP 需要 service:network 以及允许的 networkAccess.origins。
  • 位于无需权限的界面服务中的阅读相关方法，仍可能需要 reading:read 或 reading:write。
  • 书籍授权是透过宿主同意而选定，并透过 ctx.grants.book 暴露；清单无法自行取得另一本书的访问权。

检查 ctx.capabilities，并处理缺少的选用命名空间。将 ReadAware 持有的数据保留在其领域中；插件存储空间仅用于你自己的纪录、设置与检查点。

处理观察与取消

不再需要时，请释放句柄（handle）。对于支持的调用，请传入 AbortSignal 并等待实际结果。取消并不会还原已发生的写入或远端副作用。

自动反应使用 ctx.withEvent(delivery) 来处理后续工作，包括在 await 之后。接口约定要求时，请为因果订阅提供稳定的 ruleId。用户发起的动作使用原始启用上下文。这能让宿主侦测回圈，而不会把独立的动作混为一谈。

在本机构建与安装

遵循 checkout 的包脚本。在公开插件仓库中，一般检查如下：

bash
bun run build
bun run typecheck
bun test
bun run validate

开启 ReadAware → 设置 → 插件 → 安装插件，选取构建后的文件夹，并查看同意摘要。在桌面应用中实际使用该功能。重新构建并重新安装以确认更新。

为私有数据设置版本

schemaVersion 与包版本相互独立。当存储的 KV 或文件结构改变时，请透过 migrate(storageCtx, change) 提供支持的升级与降级转换。

迁移只会取得存储专属的权限。除了成功案例，也请测试失败的转换：先前的包与已提交的数据必须保持可用。一般代码更新请避免加入不必要的结构变更。

测试你的功能所用的边界

检查其实际的 Worker/Tauri 行为、权限与书籍范围拒绝、取消、禁用／重新启用，以及失败复原。若是界面插件，请涵盖键盘导航、长文字与狭窄窗口。若是变更数据的插件，请涵盖并行编辑，以及在需要持久化的情况下重新启动。

调度只会在应用开启时执行；持久性工作仅支持宿主的类型化计划。两者都不是一般的背景程序或任意代码工作的执行器。API 参考说明了这些限制。

发布

一旦构建后的包能搭配其声明的最低接口约定正常运作，请遵循发布的说明。