把你的工作流，
放进 Finder 右键菜单。

01

开放，但不交出宿主权限。

RightMenu 插件是独立维护的 JavaScript 包。宿主负责验证、安装、授权和执行边界；插件只获得当前动作已声明且由用户授予的能力。

当前范围仅包括开放开发、本地导入和用户信任；不包含插件市场、社区索引或自动更新服务。

02

快速开始

安装 RightMenu 后，直接使用 App 内置的已签名命令行工具生成项目并运行 doctor。

内置 CLI 路径

/Applications/RightMenu.app/Contents/Helpers/rightmenu-pluginctl

生成一个可运行项目

init 不会覆盖已有目录。生成结果已经包含可运行插件、API v1.5 Schema 和匹配的 TypeScript 声明。

CLI="/Applications/RightMenu.app/Contents/Helpers/rightmenu-pluginctl"
"$CLI" init ./MyPlugin \
  --id dev.example.my-plugin \
  --name "My Plugin"
"$CLI" doctor ./MyPlugin

请在当前目录开发一个 RightMenu Plugin API v1.5 插件。

插件需求：[在这里描述插件功能]

要求：
- 先阅读 README.md、schema/rightmenu-plugin-manifest-v1.5.schema.json 和 types/rightmenu-plugin-api-v1.5.d.ts。
- 只修改当前插件项目，不修改 RightMenu 宿主源码。
- 输出必须兼容 JavaScriptCore；打包全部 import，不使用 Node.js require 或原生代码。
- 为每个 action 和 uiContribution 声明 requiredCapabilities，并保持 permissions 最小化。
- 修改载荷文件后，更新 manifest.json 中 files 的 byteCount 与 SHA-256。
- 完成后运行 "/Applications/RightMenu.app/Contents/Helpers/rightmenu-pluginctl" doctor .。
- 只有 doctor 退出状态为 0 且输出 validation.ok 才算完成。
- 未经明确要求，不生成私钥、不签名、不打包。

03

生成后的包结构

插件包以 .rightmenuplugin 结尾。manifest.json 描述入口、动作、权限和所有载荷文件；发布时只提交打包后的普通 JavaScript。

MyPlugin/
├── README.md
├── plugin/
│   └── my-plugin.rightmenuplugin/
│       ├── manifest.json
│       └── main.js
├── schema/
│   └── rightmenu-plugin-manifest-v1.5.schema.json
└── types/
    └── rightmenu-plugin-api-v1.5.d.ts

04

Manifest 与 API v1.5

每个 Finder 动作和 UI contribution 都必须声明 requiredCapabilities；不需要能力时明确写空数组。每项能力必须出现在 permissions 中，未被动作使用的宽泛权限会被拒绝。

{
  "apiVersion": "1.5",
  "permissions": [{
    "capability": "selection.read",
    "reason": "Reads metadata for selected Finder items."
  }],
  "actions": [
    { "id": "about", "title": "About", "requiredCapabilities": [] },
    { "id": "inspect", "title": "Inspect", "requiredCapabilities": ["selection.read"] }
  ],
  "uiContributions": []
}

globalThis.rightMenuPlugin = Object.freeze({
  run(actionID, input) {
    if (actionID !== "inspect") return { handled: false };
    return RightMenu.call("selection.read", {});
  }
});

JSON Schema 提供编辑器提示；文件安全、摘要、跨数组关系、兼容性与签名仍以 rightmenu-pluginctl doctor 为准。

05

开发与 doctor 校验

修改 JavaScript 后，更新 manifest 中每个变更文件的 byteCount 与 SHA-256，再运行 doctor。它最多输出 32 条有界诊断，并在存在错误时以非零状态退出。

1. 1

   编辑 JavaScriptCore 兼容的输出；打包所有 import，不要留下 Node.js require。

2. 2

   同步更新 files 中的字节数与 SHA-256；不要把 manifest.json 自身列入 files。

3. 3

   运行 doctor，直到 validation.ok，并处理 API、能力、签名或包结构诊断。

"$CLI" doctor ./MyPlugin
"$CLI" doctor ./MyPlugin/plugin/my-plugin.rightmenuplugin

06

本地导入与开发者模式

打开 RightMenu → 设置 → 插件。签名包使用“导入签名插件”；未签名目录必须显式启用开发者模式，再使用“导入未签名开发插件”。两类插件位于物理隔离的目录。

安装不等于授权。宿主在复制前后都会验证，最终移动成功后才完成安装；开发者模式关闭时，未签名插件不能运行。

07

动作级权限

API v1.5 按动作计算能力集合。缺少某项授权时，只隐藏依赖它的动作；其他已授权动作仍可用。用户随时可以撤销访问。

08

发布者签名与指纹

生产分发使用 Ed25519。首次导入未知自签名发布者时，用户必须核对完整 SHA-256 公钥指纹，再选择“信任并安装”。签名身份不会授予任何运行能力。

"$CLI" keygen ./publisher.private.json "Example Publisher"
"$CLI" sign \
  ./MyPlugin/plugin/my-plugin.rightmenuplugin \
  ./publisher.private.json
"$CLI" inspect-signature \
  ./MyPlugin/plugin/my-plugin.rightmenuplugin
"$CLI" pack \
  ./MyPlugin/plugin/my-plugin.rightmenuplugin \
  ./my-plugin.rightmenuplugin.zip

私钥文件必须保存在项目外，安全备份，绝不能提交或分发。私钥丢失后，现有安装无法接受同一发布者身份下的更新。

同一插件 ID 的更新必须使用与已安装版本完全相同的签名密钥；另一个已信任密钥也不能接管。当前版本不提供自动更新或密钥轮换。

09

常见诊断代码

自动化应读取稳定的 code 和进程退出状态，不要解析说明文字。

10

兼容性与运行约束

新项目使用 API v1.5，并要求 RightMenu 0.1.41 或更高版本。v1.5 向后兼容 v1.0–v1.4；旧包仍采用插件级全量权限行为。目标代码必须兼容 JavaScriptCore，并限制循环、递归、内存与输出。

Finder 动作仅面向 1–20 个本地普通文件的受支持选择；宿主会在调用前重新扫描并校验动作及其精确授权集合。