# 协议总览

Plugin API v1 定义飞块与插件之间的交互。清单提供静态声明，后台 SDK 连接插件代码与宿主，页面 SDK 连接超级块界面与后台。

开发插件时，从[入门教程](../../guides/quickstart.md)开始。本章说明飞块处理这些接口时的顺序，适合确认调用行为或实现兼容工具。

## 一个动作如何执行

飞块加载 `manifest.json`，验证动作 ID、参数 Schema 和执行设置，随后启动插件后台。后台调用 `definePlugin()` 注册处理函数，飞块核对注册内容后把插件标记为运行中。

用户执行动作时，飞块先检查参数，再调用后台的 `actions[actionId](args, context)`。处理函数返回后，如果清单声明了 `outputSchema`，飞块检查返回值；校验通过的值成为流程步骤结果。任一步骤失败，这次调用以错误结束。

## 超级块如何更新

超级块页面显示一个已放置的实例。后台发布状态后，飞块把对应快照交给页面，页面 SDK 调用 `onState()` 监听器。

页面需要主动获取数据时，使用 `requestData()`；页面提交按钮点击等操作时，使用 `invokeAction()`。宿主根据已放置的块确定实例身份，再调用对应后台函数。

## 数据类型

跨进程数据使用 JSON 类型：字符串、有限数值、布尔值、数组和普通对象。函数、`Date`、`Map` 等 JavaScript 对象需要先转换为 JSON 数据。例如，时间可以使用 ISO 字符串，`Map` 可以转成普通对象。

清单的 Schema 支持六种类型，详见 [Schema 参考](../../reference/schema.md)。各通道的大小和时间设置见[运行限制](../../reference/limits.md)。