# Folra PluginKit 作者契约 独立插件由 JSON 清单和 JavaScript 命令组成,可以在自己的 Mac 上打包和安装。开发命令与应用内命令使用同一个沙盒 XPC 运行器,每次创建受限 QuickJS 实例。请使用支持目标 API 和本地插件安装的 Folra。通过 Agent 开发时,可以把 [AGENTS.md](AGENTS.md) 发给它。 ## 创建一个插件 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)。插件包包含两个固定文件名。 ```text MyCommand.folraplug/ manifest.json command.js ``` `.folraplug` 是普通目录,不是 ZIP、二进制文件或可执行应用。作者目录可以包含 README、AGENTS、测试和类型说明;它们不会进入安装 payload 或被执行。pack 不遍历这些文件,也不读取它们指向的其他目录。 ```json {"format":1,"api":1,"id":"org.example.my-command","version":"1.0.0","name":"My command","scope":"selection"} ``` manifest 严格拒绝缺失和未知字段。v1 恰有上面六个字段,`format/api` 成对为数值整数 `1/1`,禁止 `ui`。v2 恰有这六个字段加必需的 `ui`,版本成对为 `2/2`。v3 和 v4 还要求 `permissions`,分别用 `3/3`、`4/4`。拒绝混搭、缺项、未知字段及 `ui:null`,布尔值不是数字。id 为小写 ASCII 反向域名,至少两段,每段以字母开头,字母、数字与单个内部分隔连字符组成,每段最多 63 字节,总长最多 253 字节。版本恰有三个无前导零的十进制分量,最长 80 字节;不接受 prerelease 或 build。显示名最多 80 个 Unicode scalar,宿主去掉控制字符后必须仍有非空白字符。入口由包格式固定为同步 `run(snapshot)`。 `command.js` 声明单个同步全局入口: ```js /** @param {Snapshot} snapshot @returns {CommandResult} */ function run(snapshot) { if (snapshot.text.indexOf("foo") < 0) return {kind: "noop"}; return {kind: "edits", edits: [{ start: 0, end: snapshot.text.length, text: snapshot.text.replace(/foo/g, "bar") }]}; } ``` `types.js` 提供 JSDoc 类型,不要 import 它。每次调用使用新运行实例,不依赖全局状态、Date、random、Intl、计时器、Promise、async jobs、网络、文件、进程或原生对象。模块、外部入口与依赖不受支持。包校验只检查协议和文件结构。受限运行时负责执行和隔离。 ## 静态原生表单 v2 到 v4 在 manifest 中声明静态表单,由宿主绘制。下例为 v2。 ```json { "format": 2, "api": 2, "id": "org.example.text-tools-v2", "version": "1.0.0", "name": "Plain text tools", "scope": "selection", "ui": {"schema": 1, "fields": [ {"kind":"text", "id":"prefix", "label":"Prefix", "default":"", "maxLength":64}, {"kind":"dropdown", "id":"order", "label":"Order", "default":"keep", "options":[ {"value":"keep", "label":"Keep first occurrence"}, {"value":"ascending", "label":"Ascending"}, {"value":"descending", "label":"Descending"} ]}, {"kind":"toggle", "id":"unique", "label":"Remove duplicates", "default":true} ]} } ``` `ui` 恰有 `schema` 和 `fields`,schema 为整数 1,fields 最多 16 项,可为空。每项必需 `kind/id/label/default`,字段 id 不重复,遵循 ASCII `^[a-z][a-z0-9_]{0,31}$`。label 为 1–80 个 Unicode scalar。三种字段严格各有自己的键: | kind | 额外必需字段 | default 与提交值 | | --- | --- | --- | | text | `maxLength`,整数 1–4096 | string,长度不超过 maxLength 个 UTF-16 code units | | dropdown | `options`,1–32 项 `{value,label}` | string,必须等于某个 option.value | | toggle | 无 | boolean | option.value 与字段 id 使用同一 ASCII 规则,同一 dropdown 的 value 不重复;option.label 同样为 1–80 个 Unicode scalar。text 的 maxLength 必填,default 必须合法。`"😀".length` 是 2,不能按一个可见字符计入 maxLength。JSON Schema 的字符串 maxLength 按字符计数,不能代替此 UTF-16 检查或跨字段的 default 校验。 宿主只在本次调用内持有默认值和表单值,不把参数保存到磁盘。打开面板、编辑字段、选择选项和切换开关都不执行脚本。表单命令在用户提交后开始。v2 和 v3 调用一次 `run(snapshot)`,v4 可在收到宿主响应后再次调用。返回、复制、预览和应用结果不重新执行。 v2 快照恰有 `api/scope/text/selection/params` 五个键,例如: ```json {"api":2,"scope":"selection","text":"a\na","selection":{"start":0,"end":3},"params":{"prefix":"","order":"keep","unique":true}} ``` params 必需且为完整对象,键集合必须与 manifest.ui.fields 的 id 集合相等;每值仅可为 string 或 boolean,类型、dropdown 选项和 text 的 UTF-16 长度均须匹配。即使使用所有默认值,CLI case 仍须写全 params;空 fields 也要传 `{}`。不接受 params 缺省、null、部分字段、额外键、数字或隐式转换。宿主在执行前对照 manifest 验证,拒绝后不调用脚本。脚本不得用缺省回退掩盖宿主错误。 ## v3 只读工作区 v3 命令在文件夹工作区的文稿中运行。清单固定 `scope: "document"`,必须声明 `permissions: ["workspace.read"]`。可以使用空表单。 ```json { "format": 3, "api": 3, "id": "org.example.workspace-links", "version": "1.0.0", "name": "Check Workspace Links", "scope": "document", "ui": {"schema": 1, "fields": []}, "permissions": ["workspace.read"] } ``` 安装时显示权限范围。每次运行时用户在表单确认本次工作区访问,宿主随后收集只读快照并调用脚本。`workspace` 是 v3 快照必需的第六个键。 ```json { "api": 3, "scope": "document", "text": "[[Plan]]\n![cover](cover.jpg)", "selection": {"start": 0, "end": 0}, "params": {}, "workspace": { "document": "notes/today.md", "files": [ {"path": "notes/Plan.md", "kind": "document"}, {"path": "notes/today.md", "kind": "document"} ], "links": [ {"target": "Plan", "kind": "wiki", "status": "resolved", "path": "notes/Plan.md"}, {"target": "cover.jpg", "kind": "image", "status": "missing"} ] } } ``` | 字段 | 内容 | | --- | --- | | `document` | 当前文稿在工作区内的相对路径。`files` 包含这篇文稿。 | | `files` | 工作区内可索引的普通文件。`kind` 为 `document` 或 `attachment`。隐藏项、包及符号链接不进入索引。 | | `links` | 当前原文中识别的链接,`kind` 为 `markdown`、`wiki` 或 `image`。`target` 来自当前文稿。 | `status` 为 `resolved`、`missing`、`outsideWorkspace` 或 `unsupported`。仅 `resolved` 带 `path`,其值是 `files` 中已有的工作区相对路径。`missing` 表示当前索引内找不到目标。`outsideWorkspace` 表示引用超出已授权的工作区。`unsupported` 涵盖快照无法检查的引用,例如网络 URL。链接状态检查文件目标,标题锚点和文件内容由其他功能处理。 插件只能读这一次快照。文件条目提供相对路径与分类,文稿正文只来自发起命令的当前文稿。v3 可以像 v2 一样提出当前文稿的编辑,仍由用户预览确认。工作区权限只允许查询。索引超限或读取失败时,宿主报告错误,避免用部分索引生成误报。 ## v4 宿主能力 清单使用 `format: 4`、`api: 4`、`scope: "document"` 和原生 `ui`。在 `permissions` 中列出至少一项实际使用的权限,每项只出现一次。Folra 按清单显示权限,并按发起窗口或工作区限定范围。 | 权限 | 可用数据或操作 | | --- | --- | | `workspace.read` | 提供 v3 工作区索引及当前文稿的引用解析 | | `document.read` | 请求指定工作区相对路径的 Markdown 正文 | | `document.write` | 提交工作区 Markdown 批量创建与替换方案 | | `attachment.read` | 请求工作区图片的字节,或在本机压缩、裁剪、识别图片文字 | | `attachment.write` | 提交工作区图片的批量创建与替换方案 | | `network.request` | 经逐次确认向 `networkHosts` 中的 HTTPS 主机发送请求 | | `automation.run` | 用户为插件和工作区启用后,接收 `triggers` 中的事件并输出报告 | | `view.present` | 显示原生侧栏或独立工具窗口 | | `editor.extend` | 通过 `contributions` 声明快捷键、补全、行内样式和代码块渲染 | 声明工作区、文稿、附件或自动化权限时,从文件夹工作区的文稿发起命令。v4 快照始终包含 `responses`,首次执行时为 `[]`。声明 `workspace.read` 的命令还收到 `workspace`。自动化、工具按钮与脚本渲染通过 `event` 传递触发原因。 ### 请求数据 从同步 `run(snapshot)` 返回 `{kind:"request",request:{id,kind,...}}`。Folra 校验权限和数据,在宿主执行请求,然后用新的脚本实例重跑 `run`,在 `snapshot.responses` 追加响应。用请求 ID 查找已经收到的结果,每次新请求用不同 ID。一个命令最多执行八次宿主请求。 ```js function run(snapshot) { const note = snapshot.responses.find(item => item.id === "read-plan"); if (!note) { return {kind:"request", request:{id:"read-plan", kind:"document.read", path:"Plan.md"}}; } return {kind:"text", text:note.value}; } ``` | `request.kind` | 附加字段 | 响应 | | --- | --- | --- | | `document.read` | `path` | `{id,kind:"text",value}`,磁盘上的 UTF-8 正文,单次最多 512 KiB。发起命令的文稿原文已在 `snapshot.text` | | `attachment.read` | `path` | `{id,kind:"base64",value}`,最多 384 KiB 原始数据 | | `attachment.compress` | `path`、`quality`,0 到 1 | `{id,kind:"asset",value:"image/jpeg"}` | | `attachment.crop` | `path`、`x`、`y`、`width`、`height`,整数像素。以校正方向后的图像左上角为原点 | `{id,kind:"asset",value:"image/png"}` | | `attachment.ocr` | `path` | 文本响应,最多 64 KiB | | `network.request` | `url`、`method`,可选 `body` 和 `headers` | `{id,kind:"http",status,value}`,状态码及 UTF-8 响应正文 | 路径使用工作区相对路径和 `/`,父目录须存在。宿主拒绝绝对路径、隐藏项、包、符号链接和硬链接。附件读写及图片处理接受可解码的单帧 PNG、JPEG、GIF、TIFF、HEIC、HEIF、WebP 和 BMP。扩展名须与实际格式匹配,匹配忽略大小写。替换已有文件时,Folra 也检查原文件的实际格式。图片处理输入最多 16 MiB、16 Mi 像素,直接读取或内联写入原始字节最多 384 KiB。原样复制保留图片自身的元数据。压缩及裁剪结果由宿主持有,`asset` 只传 MIME 类型,可用对应请求 ID 提交保存。请求 ID 使用小写 ASCII 字母起头,后接小写字母、数字、下划线或连字符,总长 64 字符以内。 同次运行的宿主响应会累积在快照里。响应、当前正文、参数和工作区索引一起编码为 JSON,合计最多 1 MiB,转义字符也计入。单篇文稿满足 512 KiB 限额时,仍可能因为快照剩余空间不足而读不到。Folra 会提示触及了单篇或累计限额。 HTTPS 请求使用清单中 1 到 8 个明确的域名。允许 GET 或 POST,GET 不带请求体。POST 请求体为 UTF-8 字符串,最多 64 KiB。可传 `Accept` 和 `Content-Type`,合计最多 8 KiB,使用单行 ASCII 值。授权面板显示目标主机、方法、完整 URL、请求头和完整正文及其字节数。脚本不能设置 `Authorization`。正文里的控制字符用 Unicode 转义显示。点击发送后,Folra 使用已审阅的请求。响应最多 128 KiB。重定向、Cookie 和系统保存的网络凭据不可用。完整快照和结果仍各受 1 MiB 上限约束。 ### 提交工作区写入 返回 `{kind:"workspaceWrites",writes:[...]}`,包含 1 到 16 条不同路径。Markdown 条目为 `{kind:"document",path,text}`,正文最多 512 KiB。附件条目有两种写法。 - `{kind:"attachment",path,base64}` 直接提供数据,解码后最多 384 KiB。 - `{kind:"attachment",path,response:"request-id"}` 引用本次调用的 `asset` 响应,由 Folra 保存生成的 JPEG 或 PNG。 每项附件最多 16 MiB,批次的新旧数据总量最多 32 MiB。Folra 对有变动的文件显示旧内容与新内容或附件大小,用户确认后才创建或替换。若全部内容与磁盘一致,Folra 直接提示无需更改。目标已经在 Folra 打开、文件在预览后改变,或路径超出许可时,宿主拒绝本次提交。 ### 工具窗口和编辑器扩展 批量写入确认会逐文件列出文稿差异,图片并排显示现有和建议的缩略图、原图尺寸及字节数。工作区无法读取时结束本次运行。审阅后文件变动需要重新运行并确认。 使用 `view.present` 返回 `{kind:"view",view:{title,placement,sections}}`。位置为 `"sidebar"` 或 `"window"`,省略时使用窗口。每个工具最多 16 个区块,区块类型为文本 `{kind:"text",text}`、表格 `{kind:"table",columns,rows}` 或按钮 `{kind:"action",id,label}`。表格最多 8 列和 64 行。点击按钮后重新发起插件命令,快照增加 `event:{kind:"view.action",action:id}`。工具按钮复用打开工具时确认的表单值。每次点击仍重新取得当前文稿快照,命令的权限、写入预览和网络确认照常生效。 如果快捷键与 Folra 内建命令冲突,内建命令优先。多个启用插件声明同一快捷键时,按插件 ID 排序,由排在最前的插件使用。管理窗口会提示冲突,其他插件仍可从菜单手动运行。 声明 `editor.extend` 时,清单须提供非空的 `contributions`。Folra 用下列声明绘制或操作编辑器。 - `shortcut` 使用 `{key:"k",modifiers:["command","option"]}`,键为小写字母或数字,修饰键须包含 command 以及 option 或 control。 - `completions` 每条包含 `trigger`、`insert`、`label`。在编辑器中输入完整的分号触发词,再按 Tab 插入文本,例如 `;plan`。 - `blocks` 每条包含 `language`、`renderer`。语言以 `folra-` 开头,渲染器为 `text`、`table`、`barChart` 或 `script`。表格用 Tab 分列,首行为表头。条形图每行用 Tab 分隔标签和非负数值。 - `inline` 每条包含 `name`、`style`。用 `%%name:内容%%` 写行内标记。样式为 `accent`、`badge`、`muted` 或 `command`。点击 `command` 标记发起插件命令。 清单每包最多 16 个补全、8 种代码块语言和 8 种行内名称。普通渲染和补全由 Folra 直接处理。`script` 代码块在后台调用同一个 `run`,此时 `snapshot.event` 为 `{kind:"render.block",action:语言名}`,`snapshot.text` 只包含代码块内容。插件命令占用运行环境时,代码块先显示源码,待运行环境空闲后继续渲染。可返回最多 4 KiB 的 `text`、`noop` 或 `error`。渲染调用没有工作区或其他宿主操作权限。 ### 自动化 在清单的 `triggers` 声明 `document.open`、`document.change`、`workspace.change` 或 `timer`。用户从「插件 > 只读工作区自动化」为当前工作区开启该插件。启用期间,宿主为当前活动的工作区文稿发送事件,定时器间隔约 60 秒。自动运行使用表单默认值,可按已声明权限查询本地数据。返回 `text` 可在插件管理的「自动化结果」里查看。写入、网络请求和弹出工具界面在手动运行时可用。授权随应用会话结束而清除。 连续输入或工作区文件变动会按事件类型合并,停稳后再运行。Folra 自动保存文稿和写入隐藏的插件临时文件不会额外触发 `workspace.change`。手动命令可优先运行,尚未完成的自动化可在命令结束后重新调度。 ## 快照与结果 v1 输入固定为 `{api:1, scope, text, selection:{start,end}}` 四个键,禁止 params。v2 增加 `params`。v3 还带 `workspace`。v4 以 `responses`、可选的 `workspace` 和 `event` 扩展 v2 的形状。scope 限定快照原文及通过 `edits` 修改的范围。 - `selection` 只收到所选片段,selection 恒为 `[0,text.length)`。空选区在宿主被拒绝,不调用脚本,不自动扩大为全文。部分行就是所选片段。 - `document` 收到全文,selection 为原选区,可为空 caret。全文变更的原文预览、确认和事务提交属于宿主。 v1 输出为下面三种对象。v2 到 v4 还支持 `{kind:"text",text:"..."}`。v4 增加 `request`、`workspaceWrites` 和 `view`。所有对象都拒绝缺失和未知字段。 ```js ({kind: "noop"}) ({kind: "error", code: "unsupported-input", message: "Select plain text lines."}) ({kind: "edits", edits: [{start: 0, end: 3, text: "new"}]}) ``` `kind:"text"` 是纯文本输出,空字符串、与输入相同的字符串也保留为 text,不自动转换成 edits 或 noop。v1 返回 text 会被拒绝。宿主以只读纯文本显示,用户可明确选择复制、插入或替换;复制只写纯文本,不改变文稿。不是 HTML、Markdown 渲染或可执行 UI。 - 插入在本次原始快照的 `selection.end`,不是后来移动的光标。selection scope 对应原选区的结尾,document scope 对应原全文选区的结尾。 - 替换覆盖整个授权 scope `[0,text.length)`。selection scope 替换捕获的整个选区;document scope 明确显示“替换整篇文稿 / Replace Document”,即使原始选区非空也覆盖整篇。 - v2 到 v4 的文稿编辑,包括脚本返回的精确 edits、纯文本插入、纯文本替换,都先预览,再由用户 Apply。空文本插入和相同文本替换不增加撤销。空文本替换可能删除整个授权范围,仍须预览及 Apply。 - 用户修改或切换文稿、关闭原窗口、外部重载,或插件被替换、禁用、卸载时,原请求会失效。应用前再次检查原文稿事务和包身份,不能向新文稿或新选区重定向结果。 作者错误码只有 `unsupported-input`;message 最多 256 个 Unicode scalar,去控制字符后按纯文本显示。作者错误不改变正文。异常、超时、权限、取消、失效等属于宿主错误,不能通过作者错误码伪造。 所有范围都是旧 snapshot 的半开 UTF-16 code units。JS `length`、`slice`、`indexOf` 使用这个单位,不能使用 UTF-8 长度或 `Array.from` 的字符数。`A😀e\u0301\r\nB` 长度 8,emoji 在 `[1,3)`,CRLF 在 `[5,7)`;边界 2 与 6 非法。组合字符之间的边界合法。 edits 必须按 start 严格递增,不能重叠、同起点多插入或插入前一替换内部;相邻范围允许。每条的 `0 <= start <= end <= text.length`,必须为整数。空数组非法,改用 noop。最多 256 条,宿主一次性检查全部再应用;任一非法则整体拒绝。edits 的最终文本与输入 UTF-8 字节相同会归为 noop,不增加撤销。不要 trim、Unicode normalize 或转换全篇行尾,除非这正是命令明确承诺的转换。 | 内容 | 固定上限 | | --- | --- | | manifest.json | 16 KiB | | command.js | 256 KiB,非空 UTF-8,不含 NUL | | snapshot.text / 完整输入 JSON | 各 1 MiB UTF-8 | | 完整结果 JSON / replacement 总量 / 最终 scope 文本 | 各 1 MiB UTF-8 | | params 对象的 JSON | 64 KiB UTF-8,计入完整输入 JSON 预算 | | text 原始输出 / 完整结果 JSON | 各 1 MiB UTF-8 | | 工作区文件数 / 访问的文件系统条目数 | 4096 / 32768 | | 当前文稿链接数 / 每条路径或目标 | 512 / 4096 UTF-8 字节 | | 表单字段 / dropdown options | 最多 16 / 每项 1–32 | | text maxLength | 1–4096 UTF-16 code units,default 与提交值同限 | | 编辑条数 | 256 | | tests 文件 / case 数 | 4 MiB / 256 | | JSON 嵌套 | 64 层 | JSON 转义会增加字节数,因此正文不到 1 MiB 也可能超过 JSON 预算。宿主拒绝非法 UTF-8、未配对 surrogate、重复 JSON 键、非有限数和布尔坐标。四份 JSON Schema 描述结构。manifest 和 snapshot 通过 `oneOf` 区分四个版本,cases 将输入版本与结果形状关联。跨字段、文件路径归属、UTF-16 范围及字节预算由宿主验证。 ## 开发命令 从支持目标 API 的完整签名 Folra App 内调用可执行文件。下面使用 `/Applications` 的安装路径。使用其他构建时,换成该副本的路径。CLI 只读取命令指定的作者工程和用例。 ```sh "/Applications/Folra.app/Contents/MacOS/Folra" plugin scaffold ./MyCommand --id org.example.my-command --name 'My command' --scope selection "/Applications/Folra.app/Contents/MacOS/Folra" plugin validate ./MyCommand --json "/Applications/Folra.app/Contents/MacOS/Folra" plugin test ./MyCommand --cases ./MyCommand/tests/cases.json --json "/Applications/Folra.app/Contents/MacOS/Folra" plugin pack ./MyCommand ./MyCommand.folraplug --json ``` scaffold 省略 `--api` 或传 `--api 1` 生成 v1 模板。`--api 2` 生成静态原生表单、text 输出及含完整 params 的 cases,两种 scope 均支持。`--api 3` 默认为 document,生成空表单、工作区文件计数脚本和合成工作区用例。`--api 4` 默认为 document,声明 `workspace.read` 和 `document.read`,并生成读取示例与合成响应测试。 ```sh "/Applications/Folra.app/Contents/MacOS/Folra" plugin scaffold ./MyForm --api 2 --id org.example.my-form --name 'My form' --scope selection "/Applications/Folra.app/Contents/MacOS/Folra" plugin test ./examples/plugins/text-tools-v2 --json "/Applications/Folra.app/Contents/MacOS/Folra" plugin test ./examples/plugins/toc-options-v2 --json "/Applications/Folra.app/Contents/MacOS/Folra" plugin scaffold ./MyWorkspaceCommand --api 3 --id org.example.my-workspace-command "/Applications/Folra.app/Contents/MacOS/Folra" plugin test ./examples/plugins/workspace-links --json "/Applications/Folra.app/Contents/MacOS/Folra" plugin scaffold ./MyWorkspaceTool --api 4 --id org.example.my-workspace-tool "/Applications/Folra.app/Contents/MacOS/Folra" plugin test ./examples/plugins/workspace-tool --json ``` v1 和 v2 的 scope 默认为 selection。v1 的 selection 生成行去重示例,document 生成 Markdown 目录示例。模板附带测试、AGENTS、README 和 types.js。目标目录必须不存在,父目录必须已存在。`--id` 默认 `org.example.my-command`,`--name` 默认 `My text command`。validate 只读包。pack 复制已验证的两个原始文件到新的 `.folraplug` 目录。用 `test` 显式运行脚本测试。 test 默认读取 `tests/cases.json`。它直接使用与已安装插件相同的受限 runtime,每 case 新实例;运行器不可用时返回 `runner-unavailable`;宿主与嵌入的 worker 都需要正常的 Developer ID 签名,临时 ad-hoc 重签或拆出可执行文件不能代替完整 App。禁止回退到 Node、vm 或子 shell 执行插件。测试格式为非空 JSON 数组,input 与 expectedResult 必需,name 和 expectedText 可选: ```json [ { "name": "unchanged", "input": {"api":1,"scope":"selection","text":"one\ntwo","selection":{"start":0,"end":7}}, "expectedResult": {"kind":"noop"}, "expectedText": "one\ntwo" } ] ``` test 先将每个 input 与包 manifest 对照。v3 和 v4 用例手写合成的 `workspace`。v4 每条用例只执行一轮脚本。分别测初始 `request` 以及带合成 `responses` 或 `event` 的后续结果。CLI 只比较结果对象,工作区 IO、HTTPS 请求、自动化调度及界面绘制均由 App 处理。宿主在脚本执行前拒绝缺失或非法的参数和快照字段。此类输入由宿主协议测试覆盖。 expectedResult 也经过完整校验,原样编辑归为 noop 后比较结果,另按字节比较最终文本。text 的 expectedText 是返回的纯文本,edits 是编辑后的 scope 文本,其余结果使用原输入。expectedText 如提供必须与 expectedResult 一致。case 使用合成数据。 stdout 是单个 JSON 对象,始终包含 `ok` 和 `diagnostics` 数组,成功包操作附带 `digest`,test 附带 `cases` 数量。diagnostic 含 `code`、`path`、`message`,case 执行错误的 path 是 `/0` 等数组位置。退出码 0 成功,2 为参数、包、协议或断言错误,3 为 IO 或 runtime 失败。错误不打印文稿、结果正文或任意异常描述。 ## 包身份与本地生命周期 payload 只接受两个固定名字的非可执行、单硬链接普通文件。根目录和 payload 条目不接受软链接;通过目录 fd、openat/O_NOFOLLOW、fstat 及有界读取捕获字节,不先检查路径再重开。README、tests、作者 AGENTS 等不会随包安装。原生二进制、外部模块入口和可执行安装脚本不是包格式的一部分。 contentHash 为 SHA-256。按 manifest.json、载荷文件顺序,各拼接 UTF-8 文件名、NUL、8-byte big-endian 原始字节长度、原始字节。mtime、权限、扩展属性不参与;摘要只表示内容身份,不表示作者签名或信任。pack 保留 JSON/JS 的原始字节,包括行尾,不带作者文件和执行位。 PluginStore 必须由宿主传入明确的私有 root,测试用临时目录,没有默认用户路径。安装在自生 UUID 目录中暂存验证,原子替换 registry.json 是提交点;失败不改变原注册。重复 id 一律报 duplicate-id,由 UI 确认后显式 replacing。安装不执行脚本。新安装启用,重复同内容也需要明确替换;替换成功生成新 generation。启停状态变化也生成新 generation,重复设置同一状态不变。卸载先移除注册再清理旧 payload;崩溃留下的未注册目录不会被加载,不会遍历作者目录清理文件。 启动与执行前重验身份;损坏、未知 API、摘要变化或冲突记录被隔离到 issues,不出现在 list;其他插件继续可用。整个注册表损坏或版本未知时 list 为空,issues 说明问题,拒绝写入,保留原文件以便恢复。包替换、禁用、卸载、文稿版本和请求失效由宿主在提交前共同检查;文本相等不能代替版本检查。`ValidatedPluginResult.apply(to:)` 是纯文本运算,不能代替宿主的文稿身份、一次性 claim、原子事务或撤销边界。 ## 安装与运行 在 Folra 选择「插件 → 管理插件… → 安装插件…」,选取自己打包或解压得到的 `.folraplug`。确认前可查看插件名称、版本和访问范围。管理窗口可启停和卸载插件,重启后保留状态。v1 在用户选择菜单命令时运行。v2 到 v4 手动运行时先打开表单,提交后运行。声明工作区权限的命令从文件夹工作区内的文稿发起,每次手动运行时确认访问。 v1 保持原来的应用规则:选区内累计修改不超过 2048 个 UTF-16 单位、插入不超过 40 个换行的小改动直接应用;全文或更大改动先展示原文差异。成功批次为一步撤销,失败、取消、过期和 noop 不改变文稿。修改包含无法安全映射的转换 Wiki 链接时会被拒绝。 v2 到 v4 的文稿编辑经过差异预览,由用户应用。 每次运行受 2 秒解释器 deadline、512 KiB 栈、32 MiB allocator-accounted heap 预算约束。heap 不是进程 RSS;宿主另监测 128 MiB RSS 和 3 秒执行时间,必要时终止其拥有的运行器。启动另有 15 秒上限。Date、Math.random、Intl、Promise、异步任务、计时器和原生 IO 桥均不可用,不依赖引擎外部状态。