# 为 Folra 编写独立插件 先读 [PluginKit 协议](README.md)和 [JSDoc 类型](types.js)。结构参考 [清单](manifest.schema.json)、[快照](snapshot.schema.json)、[结果](result.schema.json)和[用例](cases.schema.json)的 JSON Schema。v1 可参考[选区去重](../../examples/plugins/selection-dedupe/README.md)或[文稿目录](../../examples/plugins/toc/README.md)。v2 可参考[选区文本工具](../../examples/plugins/text-tools-v2/README.md)或[带选项的目录](../../examples/plugins/toc-options-v2/README.md)。v3 可参考[当前文稿的工作区链接检查](../../examples/plugins/workspace-links/README.md)。v4 可参考[工作区工具](../../examples/plugins/workspace-tool/README.md)。 在用户选择的目录创建作者工程,交付 `manifest.json`、`command.js`、`tests/cases.json` 和打包后的 `.folraplug`。用支持目标 API 的完整签名 Folra 运行下面的命令。将 App 路径、插件 ID 和作用域换成实际值。这里用 v2 选区命令举例。 ```sh folra="/Applications/Folra.app/Contents/MacOS/Folra" "$folra" plugin scaffold ./MyCommand --api 2 --id org.example.my-command --name 'My command' --scope selection # 编辑 ./MyCommand 中的清单、脚本和用例 "$folra" plugin validate ./MyCommand --json "$folra" plugin test ./MyCommand --json "$folra" plugin pack ./MyCommand ./MyCommand.folraplug --json ``` 把输出目录的路径交给用户。用户在 Folra 中选择「插件 → 管理插件… → 安装插件…」,选取 `.folraplug` 目录,确认后从「插件」菜单运行。 1. 每包一个同步全局 function run(snapshot)。v1 用 1/1 清单和四键快照,v2 用 2/2 清单、原生表单和带 params 的五键快照。v3 用 3/3 清单,必需 `scope: "document"`、`ui` 和 `permissions: ["workspace.read"]`,快照增加 workspace。v4 用 4/4 清单、document scope、原生表单和实际使用的权限,快照带 `responses`、可选的 `workspace` 和 `event`。入口为全局函数,宿主不加载模块或安装 hook。 2. ui 仅为 schema:1 与静态 fields,支持 text/dropdown/toggle。text 必需 maxLength,按 UTF-16 计数;default 必须合法。字段 id 和 dropdown value 遵循同一 ASCII id 规则,分别唯一。不能添加 onChange、异步回调或参数磁盘保存。 3. params 必须写全且匹配字段类型、选项、UTF-16 长度和 64 KiB JSON 预算。宿主负责执行前拒绝缺省、未知、错误类型等表单数据;脚本不补默认值,也不编造 malformed input 的作者错误结果。手动表单命令在提交后运行,v4 可以请求宿主并在收到响应后再运行。 4. selection 只收到非空选区片段,坐标从 0 开始。document 收到当前全文。v3 经用户同意后还收到工作区文件相对路径和当前文稿的链接解析结果。v3 测试用合成 workspace 数据,脚本只依赖输入,不调用网络、文件、进程、Date、random、计时器或 Promise,不跨实例保存状态。 5. 用 JS length/slice 的半开 UTF-16 坐标,保护 surrogate pair 与 CRLF。edits 依旧输入 start 严格升序、无重叠且不同起点。无变化返回 noop,不支持的输入返回 unsupported-input。v2 到 v4 的 text 结果始终保留 text,包括原样和空输出。 6. text 复制是纯文本,插入在原 selection.end,替换覆盖授权 scope。全文操作明确显示“替换整篇文稿 / Replace Document”。v2 到 v4 的文稿编辑先预览再由用户应用。预览复用本次结果。 7. 保留范围外字符、Unicode 拼写、CRLF/LF 和末尾换行。支持有限 Markdown 子集就拒绝未覆盖结构,不解析重写全篇。目录仅生成普通 Markdown,返回精确局部 edits。 8. JSON 测试必需 input、expectedResult,可选 expectedText/name。text 的 expectedText 是返回值,edits 是变更后范围,其余结果用原文。覆盖 defaults、不同 params、noop(适用)、emoji、组合字符、CRLF、有无末尾换行、fence 和支持边界。空 selection 与缺省 params 由宿主测试拒绝,不伪造脚本调用。 9. Schema 只检查结构,不能代替跨字段、manifest 对照、范围和预算约束,也不能证明安全或终止。使用支持目标 API 的完整签名 App 执行 CLI;test 必须用同一受限运行时,缺失时报 runner-unavailable,禁止 Node、vm 或子 shell 替代执行。 10. pack 只带 manifest.json 与 command.js。作者工程保留 README、SDK、AGENTS 和 tests。安装需由用户确认,发布状态以实际可安装的 Folra 版本为准。 ## v4 用法 - 只声明实际使用的权限。网络域名放在 `networkHosts`,自动化事件放在 `triggers`,编辑器贡献放在 `contributions`。 - 每轮返回一个 `request`,在下轮的 `responses` 用请求 ID 查响应。脚本实例每轮重建。不要重复请求已响应的 ID。每次调用最多八轮宿主请求。 - 用 `workspaceWrites` 提交批量创建或替换,由用户预览并确认。压缩或裁剪后的 `asset` 用响应 ID 写入附件。`view` 返回原生工具区块,按钮事件按同一权限流程运行。 - 自动化需要用户在插件管理为工作区启用,执行时只做本地只读查询与报告。脚本渲染的 `render.block` 只收到代码块源码,只能返回限长文本、noop 或 error。 - CLI 用合成的 `responses` 和 `event` 验证每轮,不产生真实文件、网络或界面副作用。渲染用例省略 `workspace`,`responses` 为空。用签名 App 实测请求授权、写入预览及所有界面入口。