# 进程通信

这一页用于维护飞块宿主和 SDK。插件开发时使用 `definePlugin()` 与 `context`；SDK 会构造和处理下面的消息。

## 消息对象

后台使用 Node.js 进程 IPC 传递消息，日志仍走 stdout 和 stderr。

| 字段 | 类型 | 用途 |
| --- | --- | --- |
| `apiVersion` | `number` | 当前为 `1` |
| `id` | `string` | 消息 ID |
| `type` | `string` | 消息类型，见下表 |
| `action` | `string` | 命令、事件或能力名称 |
| `data` | `unknown` | 与该名称对应的 JSON 数据 |
| `requestId` | `string`，可选 | 关联请求和响应 |
| `timestamp` | `number` | 发送时间 |

宿主从已绑定的后台进程识别插件，消息中的业务数据只提供这次调用所需的参数。

## 消息类型

| `type` | 方向 | 用途 |
| --- | --- | --- |
| `command` | 宿主 → 后台 | 执行动作或其他处理函数 |
| `response` | 后台 → 宿主 | 返回命令结果 |
| `error` | 后台 → 宿主 | 返回命令错误 |
| `event` | 后台 → 宿主 | `ready`、`startup_error` 等生命周期事件 |
| `capability_request` | 后台 → 宿主 | 请求 SDK 宿主能力 |
| `capability_response` | 宿主 → 后台 | 返回宿主能力结果，失败时包含 `error` |

## 命令名称

| `action` | 处理入口 |
| --- | --- |
| `invoke_action` | `actions[actionId]` |
| `invoke_service` | `services[serviceId][method]` |
| `query_widget_options` | `widgetOptions[widgetId][field]` |
| `request_data_provider` | `dataProviders[providerId]` |
| `invoke_widget_action` | `widgetActions[widgetId][actionId]` |
| `ping` | 返回 `alive` |
| `stop` | 调用 `onStop()` |

SDK 用 `requestId` 匹配完成结果。请求结束或超时后，等待项被移除，之后到达的响应不再完成同一次请求。宿主每 30 秒检查后台响应，连续三次失败后结束进程。

## 就绪事件

`ready.data` 包含实际注册的动作、服务方法、动态选项、数据提供者和实例操作。宿主核对这些信息与清单声明后，进入运行状态。启动失败则通过 `startup_error` 传递错误消息。