把你的工作流程，
放進 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 個本機一般檔案的受支援選取；宿主會在呼叫前重新掃描並校驗動作及其精確授權集合。