NOTEGEN.插件系统
使用和管理 NoteGen 插件，为编辑器与笔记工作流增加可控的扩展能力。
插件可以在不改变 Markdown 文件格式的前提下，为 NoteGen 增加命令、菜单、状态栏信息、设置项和笔记工作流。
桌面端入口位于“设置 → 插件”，包含“已安装”“发现”“更新”，开发者模式开启后另有“开发者”标签。权限在每个已安装插件的设置详情内。插件安装与运行目前只在桌面端开放，移动端暂不运行插件。
桌面端写作统计保留内置兜底；官方统计插件显示状态栏内容时隐藏兜底，避免重复显示。移动端保留原生字符统计，可在“设置 → 编辑器 → 写作统计”开关，不需要安装插件。
更新日期：2026-09-10。四个 SDK 包已发布 npm，官方插件签名市场已上线；社区投稿尚未开放。接口说明以当前开发分支为准，未发布的新增能力需使用对应源码版本。远程安装还要求 NoteGen 支持插件系统并内置正式根公钥。
插件、Skills 与 MCP 的区别
| 类型 | 作用范围 | 典型用途 |
|---|---|---|
| NoteGen 插件 | 扩展 NoteGen 本地界面和笔记工作流 | 自定义命令、菜单与写作辅助 |
| Skills | 告诉 AI Agent 如何完成一类任务 | 按固定结构整理会议记录 |
| MCP | 让 AI Agent 调用外部工具或数据 | 连接第三方服务 |
安装 NoteGen 插件不会创建 Skill，也不会授予模型、Agent 或 MCP 权限。
当前支持的插件类型
官方插件
官方插件由 NoteGen 团队维护源码，并由市场根索引中登记的 NoteGen 发布者签名。它们与社区插件使用相同的沙箱、权限审核、安装、更新、回滚和卸载流程，不拥有宿主内部特权。
官方插件可以独立于 NoteGen 应用发布新版本。市场中的“官方”标记来自受信任的签名索引，不应通过插件名称、作者文字或 ID 前缀自行判断。
社区插件
社区插件将通过签名市场索引安装。市场包经过摘要校验和发布者签名验证，但插件仍可能读取你明确授权的内容或创建文件。安装前应检查发布者、源码、许可证、更新记录、平台和权限摘要。
当前官方与社区市场插件都只支持桌面端。市场尚未开放时，NoteGen 不会绕过信任检查安装远程包。
找到需要的入口
打开“设置 → 插件”：
| 入口 | 用途 |
|---|---|
| 已安装 | 搜索本机插件、刷新本机状态、启用或禁用插件 |
| 发现 | 浏览市场、刷新签名目录、审核并安装插件 |
| 更新 | 只列出有兼容新版本的市场插件；没有记录不代表没有安装插件 |
| 开发者 | 开发者模式开启后显示；导入本地构建目录、查看日志、导出诊断 |
在“已安装”点击插件右侧“设置”展开详情。详情提供启用范围、使用说明正文、设置和权限；更新、回滚和卸载操作直接显示在详情最下方，不必再展开一层。“权限”不是独立的顶部标签。
安装并开始使用
- 在“发现”搜索插件，点击“安装”。
- 查看版本、发布者、公钥标识、许可证、源码链接、包摘要和权限摘要，再确认安装。
- NoteGen 获取新鲜的签名索引，验证下载包的摘要、完整性清单和发布者签名。
- 安装完成后转到“已安装”，启用插件并确认授权。安装本身不等于启用或授权。
- 展开插件详情阅读使用说明。按说明从命令面板、菜单、状态栏、侧栏或编辑器标签使用功能。
插件命令面板快捷键是 macOS 的 Command + Shift + P，Windows/Linux 的 Ctrl + Shift + P。具体功能取决于插件声明的入口；使用说明下方不再提供通用“立即使用”按钮。
市场不可用或无法取得新鲜签名索引时，安装和更新会停止。陈旧缓存只能浏览，不能用于安装。若提示“程序已安装但设置保存失败”，先刷新本机列表，再启用并审核，不要立即重复安装。
选择启用范围
| 范围 | 行为 |
|---|---|
| 禁用 | 停止运行，保留程序与数据 |
| 当前工作区 | 只在当前工作区运行 |
| 所有工作区 | 在已有有效启用记录、完成所需审核的工作区运行 |
“所有工作区”不会替未来的新工作区授权。首次进入新工作区仍需启用和审核。没有声明权限的插件也需要当前工作区的有效启用记录。
确认权限
授权弹窗中，每张权限卡片包含名称、说明、必需/可选标记，以及该权限的目录、路径或网络范围。
- 首次审核时声明的权限默认选中；必需权限不可取消，可选权限可以取消。
- 左下角“全选”可选中或取消所有可选权限，必需权限始终保留；部分选中时显示中间状态。
- 再次打开保留此前的选择；已有授权记录的插件新增可选权限时，不自动选中该项。
- 没有保存路径的
workspace-folder权限默认选择“整个工作区”，可以改成更小的目录；已有范围继续保留。 - 文件级权限仍需指定文件；网络权限仍需填写允许的 HTTPS origin，不会默认开放整个网络。
- 默认勾选只是表单初始值，点击“授权并启用”后才提交。取消弹窗不会新增授权。
“整个工作区”在路径输入中表示为 .。路径相对当前工作区，不接受绝对路径或 ..。展开“高级：指定新目录或多个路径”可用逗号分隔多个范围。某些插件将一组必需权限绑定到同一个目录设置，弹窗会集中显示一次目录选择。
审核过程中切换工作区或更换插件包会使弹窗失效。关闭后重新打开，确认当前工作区和版本再提交。
权限能力
插件只能使用 manifest 中声明、且你在当前工作区授予的能力。当前公开权限包括：
| 权限 | 能力 |
|---|---|
editor.read | 读取当前活动 Markdown 编辑器或选区 |
editor.write | 在 revision 校验通过后修改当前活动 Markdown 编辑器 |
notes.read | 读取授权的工作区 Markdown 文件 |
notes.list | 列举授权目录中的 Markdown 文件 |
notes.create | 在授权目录中创建 Markdown 文件 |
notes.open | 打开授权目录中的 Markdown 文件 |
notes.write | 修改授权的 Markdown 文件 |
notes.delete | 删除授权的 Markdown 文件 |
notes.move | 在授权的源路径和目标路径之间移动 Markdown 文件 |
network.fetch | 请求你明确授权的 HTTPS origin |
network.fetch 不是通用联网权限。插件只能访问 manifest 声明且你逐项授权的 HTTPS origin，不能自行扩大到其他域名。插件也没有 Shell、数据库、Tauri、DOM 或任意文件系统访问权限。
查看和撤销
到“已安装 → 插件设置 → 权限”，查看各工作区的已授权、已拒绝、未审核、已变化状态及路径。只能在当前工作区调整授权。撤销可选权限立即拒绝新调用；撤销必需权限同时禁用插件。已进入宿主原子提交阶段的写入可能完成，撤销授权不会撤销已经完成的文件修改。
修改设置
开关、选择项立即保存；单行文本与数字在 Enter 或失焦后保存；多行文本在失焦后保存。输入中文时用于确认候选词的 Enter 不会提交设置。
设备/工作区表示本机配置作用域，不表示跨设备同步。修改目录设置不会自动扩大现有授权；出现权限拒绝时，重新审核目录范围。授权弹窗中的共享目录绑定是显式确认流程，会同步对应目录设置。
新版本已发布但没有更新提示
- 到“已安装”查看实际版本和来源标签。“开发版本”来自本地导入，不参与市场更新；“插件市场”来源才能更新到兼容的新版本。
- 到“发现”点击“刷新”，再返回“更新”。当前客户端可能复用未过期索引，只打开更新页不会主动获取新索引。
- 若仍没有更新，核对已安装版本与市场版本，以及新版本要求的 NoteGen 最低版本、API 范围和支持平台。
“发现”中的版本是市场版本，“已安装”按钮只表示同 ID 已存在，不表示已经装上该版本。从开发版改用市场版，需要先卸载开发版，再从“发现”安装；卸载确认时留意数据保留选项。
测试 0.1.0 → 0.1.1 这类升级流程，应在新版本发布前先通过市场安装旧版本。直接安装最新版不能验证这次升级。
更新、回滚与撤销版本
市场更新需要用户确认，不会自动安装。到“更新”查看兼容新版本，也可在插件详情底部操作。来源相同且未扩权时可迁移有效启用记录和授权；新增或扩大的权限需要复核。发布者 ID 不能自行更换，换钥必须经过根签名目录登记；换钥后的新包需要重新审核。
新市场版本首次成功激活前显示“等待激活确认”，这个状态跨重启保留。首次激活失败会退回上一版本；候选版确认或回滚前不能继续安装其他版本。详情底部“回滚”仅在存在上一版本时显示。
回滚会切回上一包及它对应的 storage.device/workspace 数据副本；不会回滚贡献设置、Markdown 修改或远端服务操作。旧版数据不会自动合并新版运行期间产生的写入。
市场可通过签名索引的 revoked 标记撤销具体版本。宿主取得该标记后停止运行该版本，阻止再次加载、安装或回滚到它，并显示原因。移除索引条目不是撤销；离线设备不会即时获知新标记。
本地开发插件
开发者模式下导入已构建的 .notegen/package 绝对路径。启用后自动监听构建产物，没有“重载”按钮或“自动重载”开关；关闭设置页面后继续监听，重启宿主后恢复。关闭开发者模式或禁用插件会停止/暂停监听。
作者在插件项目中运行 notegen-plugin dev，源码变化后生成新产物，NoteGen 校验并导入新的不可变快照。运行时和界面会重建，表单草稿不跨重载保留；扩权仍需审核。详细步骤见开发第一个插件。
失败和诊断
插件详情显示运行状态、失败代码和次数。成功激活会清除之前的失败记录；未清除的运行时失败累计三次后，插件隔离并禁用。可清除失败记录后重新启用、更新、回滚或卸载。
开发者日志包含宿主消息及作者通过 ctx.log.info/warning/error 写入的内容，不自动收集 console。可以按插件筛选并导出诊断 JSON；日志不持久化，退出应用前导出。诊断包含版本、运行状态和日志，分享前检查作者写入的正文是否含私人内容。
卸载
到“已安装 → 插件设置”，在详情最下方点击“卸载”：
- 卸载并保留数据：删除程序、禁用所有工作区并清除授权，保留贡献设置与 KV。
- 卸载并删除数据：还会删除该插件的设备设置、工作区设置与 KV。
两者都不会删除插件创建的 Markdown，也不会撤销已完成的操作。清理部分数据失败时，插件已停止且授权已撤销，但会提示仍有残留。不要删除包含其他插件数据的共享存储文件来消除提示。
同步、备份和恢复
插件包、权限和启用状态不会随工作区同步到其他设备。Markdown 文件按普通工作区规则同步。
管理备份通过独立的 plugin-user-data.json 保存插件 KV。恢复归档工作区时重新绑定其 KV 工作区 ID；不会恢复插件程序、发布者信任、旧权限或启用凭据。重新安装并授权后才能使用恢复的数据。贡献设置保留目标设备已有状态，其他工作区数据不会自动绑定到当前目录。
本机 plugins/*.json.bak 是损坏恢复副本，不是跨设备备份。遇到存储损坏，应退出应用、保留完整插件数据目录并联系维护者，不要直接删除状态文件。新版存储格式不保证能被旧宿主读取。
数据保存位置
| 数据 | 保存位置与行为 |
|---|---|
| 插件程序 | NoteGen 应用数据目录；不进入 Markdown 工作区 |
| 启用范围、授权、贡献设置 | 应用数据目录下的 plugins/host-state.json；当前不跨设备同步 |
storage.device 与 storage.workspace | 应用数据目录下的 plugins/storage.json；后者只是按工作区 ID 分区，也不跨设备同步 |
| 插件创建或修改的 Markdown | 普通工作区文件，按你现有的工作区同步与备份规则处理 |
因此，在另一台设备上同步到同一工作区，不会自动安装、启用或授权社区插件。卸载插件也不会删除它曾创建的 Markdown 文件。
插件状态由宿主原生层串行写入，采用同目录临时文件原子替换，并维护有效的 .json.bak 恢复副本。成功保存前，两份文件都会更新到已提交状态，避免恢复时重新带回已撤销的授权或已删除的数据。读取时会尝试从有效备份恢复损坏的文件；两份都无法读取时会报告错误，不会静默重置授权或数据。旧版根目录中的 plugins.json 和 plugin-data.json 只作为首次迁移来源，迁移后不再承接新设置或 KV 写入。
常见问题
| 现象 | 处理 |
|---|---|
| 已安装但没有功能入口 | 检查当前工作区是否启用、权限是否待审核，再读插件使用说明 |
| 看不到开发者标签 | 在“设置 → 通用 → 高级”打开开发者模式 |
| 更新页为空，找不到卸载 | 到已安装插件详情最下方；更新页只显示可更新插件 |
| 修改源码后没变化 | 确认 notegen-plugin dev 正在运行、导入的是 .notegen/package、开发者模式和插件均已启用 |
| 自动重载报错后不再尝试 | 修复并生成不同的新产物，或重启宿主；同一失败产物不无限重试 |
| 权限已选中仍报错 | 文件级权限需要具体文件，网络权限需要明确 origin；检查当前工作区及路径 |
| 同步到新设备后插件没运行 | 在新设备重新安装、启用并授权；同步笔记不代表同步插件信任 |
安全边界
官方、社区与本地开发插件都运行在独立 Worker 中的 QuickJS 隔离环境，通过受控消息桥请求宿主能力。NoteGen 会在每次调用时检查插件身份、权限和路径范围，并限制内存、执行时间、消息大小、调用频率和本地存储额度。
这套机制用于缩小风险面，不代表插件经过功能或隐私背书。只安装你信任的发布者，并只授予完成任务所需的最小路径范围。
开发者阅读路线
先完成开发第一个插件，再查阅 开发工具概览与 命令行工具。通过 插件配置声明能力，结合 接口与类型参考、功能调用与权限和扩展应用界面实现功能。分发前阅读插件运行机制、插件测试、打包与验证与发布到插件市场。