@mearl/native-host 2.21.0 → 2.22.1

package/README.md

@@ -154,7 +154,7 @@ try {
 
 `capabilities` 返回 Provider 实际支持的 mode、permissions、结构化输出、流式和取消能力。当前 Codex 只提供显式 `{ provider: 'codex', mode: 'agent', permissions: 'read-only' }`，每次使用临时 app-server 会话，禁用已配置的 MCP、Apps、搜索、插件和相关扩展功能，沙箱禁止写入和网络；人工请求直接失败。它仍有只读 Agent 的本机读取能力，不能承诺完全不调用工具，因此 `mode: 'generate'` 明确拒绝，绝不降级。交互侧边栏保持独立会话生命周期。
 
-请求最多 256 KiB；`outputSchema` 最多 64 KiB，通过 [Codex app-server](https://developers.openai.com/codex/app-server/) 的 `turn/start` 传递。宿主只接受成功 turn 的原始最终消息，并独立解析 JSON、校验 schema，再生成成功任务；Provider 的 willRetry 错误不提前结束执行，终态错误保留具体原因及稳定错误码。`model.delta` 是可缺失的诊断进度，不能拼接成最终结果。最终文本上限 32 MiB，结构化返回 `{ text, output?, provider, mode, model? }`，模型额外业务约束仍由插件校验。
+请求最多 256 KiB；`outputSchema` 最多 64 KiB，通过 [Codex app-server](https://developers.openai.com/codex/app-server/) 的 `turn/start` 传递。宿主只接受成功 turn 的原始最终消息，并解析 JSON，再生成成功任务；outputSchema 的约束交给模型 Provider，插件负责验证最终数据结构和业务约束；Provider 的 willRetry 错误不提前结束执行，终态错误保留具体原因及稳定错误码。`model.delta` 是可缺失的诊断进度，不能拼接成最终结果。最终文本上限 32 MiB，结构化返回 `{ text, output?, provider, mode, model? }`，模型额外业务约束仍由插件校验。
 
 SDK 使用 `PluginModelClient.capabilities/list/start/run`。工具箱使用 `host.model.capabilities/list/start` 和 `waitTask`。`PluginModelClient.run` 的 signal 会取消执行并等待清理，语义与仅停止观察的任务 `wait` 不同。
 
@@ -181,7 +181,7 @@ export default app => {
 };
 ```
 
-`context.checkpoint(data, expectedSequence)` 仅在 service 路由、未绑定页面实例的活动受管理公开命令中可用；子任务可记录检查点，显式恢复仍只接受合格根任务。负载最多 64 KiB，宿主按声明 schema 校验，分配递增检查点序号。数据、版本、宿主计算的 canonical schemaHash、任务快照和 checkpoint 事件写入同一个原子任务记录；并发过期写入明确冲突。检查点不是外部操作的完成证明，与插件 state 事务也不共享提交。外部提交与检查点之间的故障窗口由恢复入口查询操作状态或使用稳定幂等键处理。
+`context.checkpoint(data, expectedSequence)` 仅在 service 路由、未绑定页面实例的活动受管理公开命令中可用；子任务可记录检查点，显式恢复仍只接受合格根任务。负载最多 64 KiB，宿主检查 JSON 和 CAS 序号，分配递增检查点序号；schema 是格式描述与版本身份，插件负责验证检查点数据。数据、版本、宿主计算的 canonical schemaHash、任务快照和 checkpoint 事件写入同一个原子任务记录；并发过期写入明确冲突。检查点不是外部操作的完成证明，与插件 state 事务也不共享提交。外部提交与检查点之间的故障窗口由恢复入口查询操作状态或使用稳定幂等键处理。
 
 SDK 使用 `PluginTaskClient.checkpoint(taskId)` / `resume(taskId, { environment?, revision? })`。resume 只接受失败、取消或中断的根命令，创建新的 taskId 和执行代次，记录 `resumedFrom`，原任务保持终态；相同来源任务只有一个直接后继，重复请求返回已有 attempt，配置不同则冲突。继续恢复失败的新 attempt 时，对新 taskId 调用 resume。
 
@@ -203,7 +203,7 @@ export default app => {
 };
 ```
 
-migrateFrom 最多 16 个不同的旧版本（均低于目标版本），历史 schema 必须与检查点写入时记录的宿主 hash 及保留代码声明一致。即使源码没变，依赖环境等动态声明发生格式漂移也拒绝恢复。迁移和恢复进程调用隐藏 handler 前再次比较目标声明签名，普通 checkpoint 写入也校验执行端声明；Python 每次 run 的 ready ACK 前核对完整加载元数据。迁移返回新检查点的数据，宿主校验 JSON、64 KiB 限制和目标 schema，再将新数据及来源元信息原子写入唯一后继任务；旧任务和检查点不变。没有迁移声明、格式不匹配、转换失败或清理未确认均不接纳新任务。
+migrateFrom 最多 16 个不同的旧版本（均低于目标版本），历史 schema 必须与检查点写入时记录的宿主 hash 及保留代码声明一致。即使源码没变，依赖环境等动态声明发生格式漂移也拒绝恢复。迁移和恢复进程调用隐藏 handler 前再次比较目标声明签名，普通 checkpoint 写入也校验执行端声明；Python 每次 run 的 ready ACK 前核对完整加载元数据。迁移返回新检查点的数据，宿主校验 JSON、64 KiB 限制和目标声明身份，再将新数据及来源元信息原子写入唯一后继任务；旧任务和检查点不变。没有迁移声明、格式不匹配、转换失败或清理未确认均不接纳新任务。
 
 同一源任务的并发恢复按 revision 选择与环境指纹合并，不同意图冲突；已提交后继的重试先核验请求指纹，不重复转换。迁移在独立受管理进程执行，10 秒期限，与声明解析共享最多 8 个进程预算，无等待队列，服务关闭会取消并等待清理。转换和原执行树均确认停止，且安装和双端代码快照再次核验后才接纳新任务。迁移没有宿主 API、模型、state、页面或嵌套插件调用权限；JS/Python 仍是可信本机代码，具备直接文件和网络访问能力，不构成 OS 沙箱。迁移必须是可重复的纯 JSON 转换：提交前崩溃可能再次执行，不承诺转换恰好执行一次。
 
@@ -254,7 +254,7 @@ export default app => {
 
 页面函数的 `host.emit(name, payload)` 返回接收确认；处理结果通过实例事件查询。`context.page.send/get` 始终绑定当前实例，运行时任务的普通页面动作和复合页面入口被拒绝。每次出队、宿主调用和提交结果都重新检查文档。运行时传输保留控制会话归属、暂停与释放检查，并行处理消息和回调；消息顺序由实例与事件策略负责，等待业务消息不会阻塞同文档的校验或取消。页面 `receive(message, { signal, requestId })` 提供每条消息的协作取消信号；任务取消传播到该文档对应请求，插件异步等待后应检查 signal。取消不强制终止页面 JS，已提交的外部操作仍需核对。后台默认每 10 秒并发续租，每实例校验超时 8 秒，浏览器租约 30 秒；续租只更新内存，独立定时器每 5 秒批量保存轻量租约，完整运行时代码与待确认事件只在对应状态变化时持久化。失效时取消排队和运行任务并释放页面资源。
 
-事件负载最多 32 KiB，页面待确认队列 64 条；后台每事件默认待处理 32 条（最多 64），每实例活动事件最多 128，有限并发最多 8。历史最多 256 条及 384 KiB，游标缺口明确返回。Native Messaging 的请求与结果各按 192 KiB 分块并校验 SHA-256，单条页面业务消息/结果最多 24 MiB；浏览器与工具箱回复资源各有 32 MiB 总预算及 30 秒过期。
+事件 schema 保留为格式描述，后台处理器负责验证负载；宿主检查事件绑定、文档归属、大小和调度约束。事件负载最多 32 KiB，页面待确认队列 64 条；后台每事件默认待处理 32 条（最多 64），每实例活动事件最多 128，有限并发最多 8。历史最多 256 条及 384 KiB，游标缺口明确返回。Native Messaging 的请求与结果各按 192 KiB 分块并校验 SHA-256，单条页面业务消息/结果最多 24 MiB；浏览器与工具箱回复资源各有 32 MiB 总预算及 30 秒过期。
 
 SDK 使用 `PluginPageClient`。工具箱调用 `host.page.*`，或 `window.mearl.subscribe('page', { instanceId, cursor? }, listener)` 观察后台事件；`events` 接受 `cursor` 与 `waitMs`（0–25000），无新事件时可等待变化；工具箱订阅先读取快照，随后使用长轮询，退订只结束观察。内部 `page_runtime` 是文档适配协议，业务插件使用 `app.page()`。设计稿叠加已迁移，保存事件无需 Popup 转发。
 
@@ -266,13 +266,13 @@ SDK 使用 `PluginPageClient`。工具箱调用 `host.page.*`，或 `window.mear
 
 ### 状态和激活
 
-插件导出 `stateStorage = { version: 1, collections: { ... } }`，每个集合声明 `scope`（installation/host/browser-session/instance）、`storage`（persistent/cache/memory）、`schemaVersion`、JSON Schema 和可选 `maxEntries/maxBytes/ttlMs`。浏览器会话与实例只接受 cache/memory；memory 只允许这两种作用域，并且只驻留插件执行宿主内存，按需分配，全宿主合计上限 128 MiB / 512 个集合命名空间，宿主重启清空；实例结束释放对应内存。浏览器会话在文档刷新时保留，新的浏览器会话使用独立空间。所有页面作用域都由真实活动页面解析，不能用业务字段伪造。实例结束清理专属缓存；其他缓存默认 TTL 一天，最多七天，读取、定时维护和配额检查会回收过期值。持久配置、缓存、任务记录和二进制资产分别管理。
+schema 是格式元数据，宿主不执行 JSON Schema 关键字校验；状态写入、事件负载、检查点及迁移数据由插件验证。插件导出 `stateStorage = { version: 1, collections: { ... } }`，每个集合声明 `scope`（installation/host/browser-session/instance）、`storage`（persistent/cache/memory）、`schemaVersion`、JSON Schema 和可选 `maxEntries/maxBytes/ttlMs`。浏览器会话与实例只接受 cache/memory；memory 只允许这两种作用域，并且只驻留插件执行宿主内存，按需分配，全宿主合计上限 128 MiB / 512 个集合命名空间，宿主重启清空；实例结束释放对应内存。浏览器会话在文档刷新时保留，新的浏览器会话使用独立空间。所有页面作用域都由真实活动页面解析，不能用业务字段伪造。实例结束清理专属缓存；其他缓存默认 TTL 一天，最多七天，读取、定时维护和配额检查会回收过期值。持久配置、缓存、任务记录和二进制资产分别管理。
 
 同一命名空间已有状态时，memory 与磁盘存储之间切换须使用新的集合名或作用域；不支持跨存储介质迁移。
 
 `get/list/transact` 在用户级任务服务串行处理，集合的值、CAS 版本、schema 版本、TTL 与最近 64 次幂等回执一起写入单个原子记录。每个 put/delete 必须携带读取获得的 opaque `expectedVersion`；集合版本单调递增，删除和过期不会重用版本。多键事务最多 128 项、512 KiB，单值最多 256 KiB，默认每集合 1024 项/8 MiB，磁盘状态每插件总量 64 MiB；memory 按前述全宿主上限管理。list 返回有界分页，调用方带 `expectedRevision` 检测翻页期间的变动。
 
-变更 schema 或存储类型需要提升 `schemaVersion`。迁移事务明确带 `migrateFromVersion` 与 `expectedRevision`，全部保留值通过新 schema 后才原子提交；旧 revision 禁止回写新 schema。同步 handler 也校验加载时的声明签名，避免代码更新期间误写。更换安装不会继承旧安装命名空间。
+变更 schema 或存储类型需要提升 `schemaVersion`。迁移事务明确带 `migrateFromVersion` 与 `expectedRevision`，插件负责验证和转换全部保留值，宿主核验版本及事务约束后原子提交；旧 revision 禁止回写新 schema。同步 handler 也校验加载时的声明签名，避免代码更新期间误写。更换安装不会继承旧安装命名空间。
 
 命令使用 `app.state(collection, operation, input)`，或通过自动绑定当前页面实例的 `context.state(...)` 调用。SDK `PluginStateClient` 与工具箱 `host.state.*` 使用同一服务。设计稿叠加的素材和设置使用 browser-session memory，素材通过有界分块读写。用户显式导出的图片不属于缓存。