插件开发指南

Ting Reader 插件开发的关键是：在 plugin.yml 声明 capability 和 permissions，在插件代码里通过 HostGateway 调用系统能力，再按运行时差异完成桥接和打包。

插件如何调用系统能力

插件不能直接读数据库、拼媒体路径或绕过用户权限。需要读取书籍、章节、进度、媒体地址、库文件、缓存或创建任务时，统一调用 HostGateway。HostGateway 会根据 manifest 权限和当前用户上下文做校验。

Capability：注册插件能力，决定系统什么时候调用插件。
HostGateway：插件访问宿主系统，决定插件怎么安全读取或操作系统数据。

JavaScript 后台方法使用 Ting.host.invoke(method, params)。
web_container UI 使用 postMessage 发送 method: "host.invoke"，客户端再转发到 /api/v1/plugin-host/invoke。
WASM 使用 ting_env.host_invoke，再通过 host_response_size 和 host_read_body 读取 JSON 结果。
Native 动态库通过 plugin_set_host_api 接收 Host API，再调用 host_invoke(method, params_json, result_json)。

Manifest：声明能力和权限

capabilities 决定插件暴露什么入口，permissions 决定插件能调用哪些系统能力。HostGateway 调用缺少对应权限时会被拒绝。

admin_only: true 是插件级 manifest 字段，默认值为 false。开启后，插件只对管理员可见、可安装和可调用；普通用户不会在插件列表、能力发现或客户端 UI 入口中看到它，也不能直接调用它的 capability 或受保护路由。

id: assistant-tools
name: Assistant Tools
version: 1.0.0
min_core_version: 1.4.8
runtime: javascript
entry_point: plugin.js
author: Your Name
description:
  zh: 提供客户端入口、工具和后台任务
  en: Provides client entries, tools, and background tasks
# Optional: set true for plugins that should be visible and callable only by admins.
admin_only: false

capabilities:
  - id: assistant.panel
    kind: ui_extension
    invoke: openAssistant
    slot: global.floating_action
    title: { zh: AI 助手, en: AI Assistant }
    render:
      mode: web_container
      entry: ui/index.html

  - id: metadata.search
    kind: metadata_provider
    invoke: searchMetadata
    auto_scrape: true
    search_fields:
      - key: title
        label: { zh: 书名, en: Title }
        required: true
        default_from: book.title
    result_fields:
      - key: title
        label: { zh: 标题, en: Title }
      - key: cover_url
        label: { zh: 封面, en: Cover }

  - id: books.tools
    kind: tool_provider
    invoke: invokeTool
    tools:
      - name: books.search
        description: Search books the current user can access

permissions:
  - type: network_access
    value: api.example.com
  - type: books_read
  - type: progress_read
  - type: cache_read
  - type: cache_write

Capability 与 HostGateway 速览

Capability 写在 capabilities 中，声明插件提供什么能力、由谁调用、调用哪个运行时函数、是否显示客户端 UI。
HostGateway 是插件访问宿主数据的唯一安全入口，例如读取书籍、章节、进度、媒体地址、库文件、缓存、播放列表或用户设置。
运行时文件不决定插件类型，capabilities[].kind 才决定插件能做什么。
所有 HostGateway 调用都需要在 permissions 中声明对应权限；缺权限、缺用户上下文或越权访问都会被拒绝。

详细 kind、slot、render mode、HTTP route、任务、事件和 UI 图标写法，请看“插件能力声明”页面。HostGateway 方法参数、响应格式、Web 容器桥接、WASM/Native 错误码和权限表，请看“HostGateway 能力调用详解”页面。

插件配置

需要 API key、接口地址、模型名、开关、枚举选项或数值参数时，在 plugin.yml 里声明 config_schema。配置表单、敏感字段加密、默认值、运行时读取方式和常见坑请看“插件配置 config_schema”页面。

选择运行时

JavaScript 运行时

适合快速实现 API 接入、元数据处理、工具、插件商店源和轻量 UI 后端逻辑。

WASM 运行时

适合跨平台 Rust 逻辑、内容处理和计算型任务。

Native 运行时

适合格式处理、流式解密、系统库调用和平台二进制工具供应。

trpack 下载与打包

trpack 是 Ting Reader 插件开发和打包 CLI，用来初始化插件项目、校验 plugin.yml、构建 .tr 插件包、生成签名密钥、检查包内容，以及解包调试。

下载后建议重命名为 trpack 或 trpack.exe，并放到 PATH 中。Linux 和 macOS 需要先执行 chmod +x trpack。

命令	用途
init	按模板创建插件项目，模板包括 `metadata`、`format`、`ui`、`route`、`content`、`tool`。
validate	校验插件目录和 `plugin.yml/plugin.yaml`，提前发现 capability、入口文件、资源路径等问题。
build / pack	把插件目录打成 `.tr` 包，可通过 `--include` 添加额外文件，通过 `--json` 输出机器可读摘要。
keygen	生成 Ed25519 发布密钥，保持同一插件后续升级的发布者身份稳定。
sign	给已有 `.tr` 包重新签名，适合 CI 产物或补签发布包。
inspect	查看 `.tr` 包元数据、文件表和签名摘要，支持 `--json`。
verify	校验 `.tr` 包结构、manifest、文件表和签名状态。
unpack	解包到目录，便于调试包内文件和 manifest。
is-tr	快速判断一个文件是否是 `.tr` 插件包。

trpack init my-plugin --template ui --id my-plugin --name "My Plugin"
trpack validate my-plugin
trpack build my-plugin --output dist/my-plugin.tr --json
trpack inspect dist/my-plugin.tr --json
trpack unpack dist/my-plugin.tr --output unpacked
trpack is-tr dist/my-plugin.tr

插件包使用 .tr 格式发布。发布前至少执行 validate、build 和 verify，确认 manifest、文件表、签名信息、依赖插件和最低服务端版本都正确。

trpack validate my-plugin
trpack build my-plugin --output dist/my-plugin.tr
trpack verify dist/my-plugin.tr

公开发布插件时建议使用稳定签名密钥，不要把私钥提交到仓库。已有包需要补签时可以用 trpack sign。当前安装路径只接受有效 .tr 包：未签名包会被拒绝，未受信但签名有效的包需要用户确认后才能安装。

trpack keygen --key-id my-plugin-release --output keys/private.json --public-output keys/public.json
trpack build . --output dist/my-plugin.tr --sign-key keys/private.json
trpack sign dist/my-plugin.tr --key keys/private.json --output dist/my-plugin.signed.tr
trpack verify dist/my-plugin.signed.tr

不要把源码目录直接复制到服务端插件安装目录作为发布方式。安装 .tr 时宿主会写入 .trpack/package.json 和 .trpack/signature.json；启动发现插件时会重新校验这些元数据、文件大小和 sha256。直接改安装目录里的文件可能导致签名校验失败或启动时被跳过。

运行时	打包关注点
JavaScript	通常包含 `plugin.yml`、入口脚本、可选 `ui/` 静态资源和本地模块。
WASM	先编译 `.wasm`，再把 `plugin.yml` 和 `.wasm` 放入插件目录打包。
Native	按平台分别编译 `.dll/.so/.dylib`，使用匹配平台的 trpack 构建对应 `.tr` 包。

← 上一篇Webhook 教程下一篇 →插件能力声明