ShuyoNote 插件 API（一）：用 20 行写出第一个插件

这是「插件 API」系列的第一篇。看完这一篇你能写出一个能跑、能装、能上手的插件； 能力清单、事件、零代码与主题、日志与沙箱在后面几篇。

1. 最小插件（20 行）

插件是磁盘上的一个目录，放在应用数据目录的 plugins/<插件 id>/ 下（也可用「插件管理 → 从文件夹安装」）：

plugins/my-plugin/
├── manifest.json
└── main.js

manifest.json：

{
  "id": "my-plugin",
  "name": "我的插件",
  "version": "0.1.0",
  "description": "一句话说明",
  "apiVersion": "1.0.0",
  "main": "main.js",
  "permissions": [
    { "id": "read:pages", "reason": "为了在提示里显示本空间页面数" }
  ]
}

main.js：

register({
  id: "my-plugin.hello",
  title: "打个招呼",
  description: "显示本空间页面数",
  closeOnRun: false,
  run: function () {
    api.log("开始执行");
    api.notify("本空间共 " + api.pages.count() + " 个页面");
    return "完成";
  },
});

要点：

• id 必须等于目录名；可用字符：字母、数字、_、.、-（推荐只用小写字母、数字与 -）；
• main 只能是同级文件名（main.js 或 ./main.js）；
• 每次执行都会重新 eval 插件代码并新建一个沙箱 —— 不要在顶层做耗时工作；
• 返回的字符串会显示在命令面板底部；closeOnRun: true 执行后关闭面板。

写完之后怎么跑起来、怎么排错：见 §9 开发循环。

2. manifest 字段

• id：✅ ｜ 插件 id，必须等于目录名；单段，可用 A-Za-z0-9_.-（推荐 [a-z0-9-]）
• name：✅ ｜ 显示名
• version：建议 ｜ 插件自身版本
• description：建议 ｜ 一句话说明
• apiVersion：✅ ｜ 本插件针对的 API 版本（当前 1.0.0）；主版本不被支持时会被拒载
• main：入口文件，默认 main.js
• permissions：✅ ｜ 见下节；不写 = 默认零能力（v1 之前的老插件会得到基线授权并收到警告）

3. 权限

权限必须在 manifest 里逐条声明，安装/启用时会把「权限 + 理由」展示给用户； 运行时由宿主逐次调用校验——没声明的权限，调用会失败（不是被隐藏）。

"permissions": [
  { "id": "read:page.current", "reason": "为当前页生成摘要" }
]

• read:page.current：读取当前页正文：读取当前打开页面的 content_json ｜ low
• read:pages：读取本空间页面统计：读取本空间的页面数量等汇总信息（不含正文） ｜ low
• write:page.current：向当前页写入纯文本：往当前页面插入一段纯文本（不接受 HTML/Markdown，不可删改既有内容） ｜ low
• read:tags：读取本空间标签：读取本空间的标签清单（名称与关联页面数） ｜ low
• read:backlinks：读取反链：读取哪些页面引用了某个页面 ｜ low
• read:files：读取附件元数据：读取页面的附件元数据（名称/类型/大小），不含文件字节 ｜ low
• kv:own：存储自己的数据：在插件自己的命名空间里读写键值（与其他插件、与笔记数据互不可见） ｜ low
• write:pages：新建页面 / 追加内容：新建页面或向页面追加内容；写入前会先给你看草稿并等你确认（不直接落库） ｜ medium
• read:properties：读取属性定义：读取本空间的属性定义（名称/类型/id），供插件找到要写的属性 ｜ low
• write:properties：设置页面属性：给页面设置属性值；写入前会先给你看草稿并等你确认 ｜ medium
• write:tags：给页面加标签：给页面加标签；写入前会先给你看草稿并等你确认 ｜ medium
• export:files：把内容保存成文件：存到哪、存不存都由你在系统保存对话框里定（插件只能给一个建议文件名，给不了路径）。导出的文件是明文，不随空间的加密一起保护 ｜ medium