# FlyonDeck 插件开发文档

> 与 /docs 用户界面使用同一份文档构建产物。正文为中文，代码示例已展开，可直接读取，无需执行 JavaScript 或登录。

Plugin API v1 · SDK 0.1.0 · Host 0.0.1 · 核对日期 2026-11-04

## 读取入口

- [全文合集](/llms-full.txt)：全部章节的完整 Markdown，适合一次性检索。
- [机器可读目录](/docs-agent/index.json)：章节路径、简介、版本及 SHA-256；按需选择章节。
- [用户界面](/docs)：与下面的 Markdown 文档对应。

按篇 Markdown 保留原文和相对链接；相对链接以该篇 Markdown 的 URL 为基准。示例下载、Schema 与公共 SDK 源码链接仍由本站 /docs-assets 提供。

## 入门

- [飞块插件开发](/docs-agent/overview/introduction.md)：为按钮添加动作，或用 HTML 和 JavaScript 创建超级块。
- [使用插件开发工具包](/docs-agent/guides/toolkit.md)：安装 flyon，创建、构建和打包插件，通过开发者模式直接调用动作、预览 widget 场景并查看日志。
- [创建第一个插件](/docs-agent/guides/quickstart.md)：创建一个接收名字、返回问候文本的动作，并在飞块中运行它。
- [项目结构](/docs-agent/guides/project.md)：安排后台入口、页面资源和依赖，并在 TypeScript 项目中生成可运行文件。

## 开发指南

- [开发动作](/docs-agent/guides/actions.md)：把业务函数变成按钮和流程可执行的动作。
- [发布状态](/docs-agent/guides/states.md)：让按钮、流程和超级块读取插件当前的值。
- [提供按钮预设](/docs-agent/guides/presets.md)：为常用动作提供默认名称、图标和状态外观。
- [创建超级块](/docs-agent/guides/widgets.md)：使用 HTML 页面显示数据，并为每个放置位置提供交互和配置。
- [超级块响应式布局最佳实践](/docs-agent/guides/responsive-widgets.md)：以实际内容区计算比例和空间预算，按信息优先级切换布局，并验证文字、进度与操作区域不会重叠。
- [请求数据与调用服务](/docs-agent/guides/data-services.md)：从超级块请求一次数据，或在后台调用另一插件的功能。
- [调试插件](/docs-agent/troubleshooting/diagnostics.md)：根据插件启动、动作执行或页面显示的问题定位原因。

## 参考文档

- [参考文档](/docs-agent/reference/index.md)：按清单对象或 SDK 命名空间查找接口。
- [运行限制](/docs-agent/reference/limits.md)：查询数据大小、请求时间和并发数量。

## 清单参考

- [manifest.json](/docs-agent/reference/manifest.md)：描述插件信息、权限和提供的功能。
- [字段索引](/docs-agent/reference/fields.md)：从字段路径查找它所属的清单对象和属性定义。
- [Schema](/docs-agent/reference/schema.md)：定义动作参数、返回值和状态的数据类型。
- [actions](/docs-agent/reference/actions.md)：在清单中声明动作、参数、结果和流程执行策略。
- [stateSources](/docs-agent/reference/states.md)：声明插件可以发布的状态，以及哪些位置可以读取它。
- [widgets](/docs-agent/reference/widgets.md)：声明超级块页面、尺寸、状态订阅和实例操作。
- [WidgetSettings](/docs-agent/reference/settings.md)：为超级块的每个实例提供配置字段。
- [buttonPresets](/docs-agent/reference/presets.md)：提供按钮的默认外观，以及不同状态下的动作。
- [dataProviders](/docs-agent/reference/data-providers.md)：为已放置的超级块处理一次数据请求。
- [events](/docs-agent/reference/events-manifest.md)：声明后台发给飞块的一次性事件。
- [services 与 uses](/docs-agent/reference/services.md)：声明本插件提供的服务，以及需要调用的外部服务。
- [参数编辑器](/docs-agent/reference/editors.md)：通过 Schema 选择文件、应用、网址等参数的输入方式。
- [插件图标与资源](/docs-agent/reference/icons.md)：直接引用图标库 ID 或插件包内 SVG，为动作、预设与分类提供图标。
- [权限](/docs-agent/reference/permissions.md)：声明后台需要飞块代理执行的操作。
- [数据接口](/docs-agent/reference/channels.md)：选择一次性数据、事件或插件服务的清单声明。

## 参考

- [插件全局设置](/docs-agent/reference/plugin-settings.md)：插件级共享配置、私密字段与后台变更通知。
- [国际化](/docs-agent/reference/i18n.md)：宿主语言、插件展示资源与页面 SDK 翻译。

## 后台 API

- [definePlugin](/docs-agent/reference/node-sdk.md)：注册插件的动作、生命周期和其他处理函数。
- [context.system](/docs-agent/reference/system.md)：执行系统打开、输入、音量和截图操作。
- [context.native](/docs-agent/reference/native.md)：运行随插件一起发布的可执行文件。
- [context.network](/docs-agent/reference/network.md)：通过飞块请求 HTTPS JSON 数据。
- [context.deck](/docs-agent/reference/deck.md)：让执行动作的设备切换屏幕。
- [context.states](/docs-agent/reference/states-api.md)：向清单中声明的状态来源发布当前值。
- [context.widgets](/docs-agent/reference/widgets-api.md)：查询已放置的超级块实例及其配置。
- [context.events](/docs-agent/reference/events.md)：向飞块发送一次事件。
- [context.plugins](/docs-agent/reference/plugins.md)：调用另一插件声明的服务方法。
- [host：宿主能力](/docs-agent/reference/host.md)：查询宿主接口版本，与权限和运行时可用性分开判断。
- [storage：插件数据目录](/docs-agent/reference/storage.md)：使用宿主分配的数据与缓存目录，插件负责格式和迁移。

## 页面 API

- [FlyonDeckWidget](/docs-agent/reference/page-sdk.md)：在超级块主页面中接收状态、请求数据和提交操作。
- [FlyonDeckWidgetConfig](/docs-agent/reference/config-page.md)：在超级块配置页面中读取和修改公开配置。
- [FlyonDeckPluginConfig](/docs-agent/reference/plugin-config-page.md)：自定义插件全局设置 HTML 页面和公开草稿 SDK。

## 协议

- [协议总览](/docs-agent/protocol/v1/overview.md)：了解清单、后台和页面如何共同完成一次调用。
- [插件包](/docs-agent/protocol/v1/package.md)：定义 flyext 的文件结构、入口和资源路径。
- [运行与生命周期](/docs-agent/protocol/v1/runtime.md)：说明后台的启动、就绪、停止和异常退出。
- [动作调用](/docs-agent/protocol/v1/actions.md)：说明动作参数、执行顺序和步骤结果的处理。
- [状态发布与读取](/docs-agent/protocol/v1/states.md)：说明状态身份、作用域、快照和清理行为。
- [一次性数据请求](/docs-agent/protocol/v1/data-channels.md)：说明超级块从发起请求到收到结果的过程。
- [页面与实例交互](/docs-agent/protocol/v1/page-bridge.md)：说明页面上下文、状态交付、实例操作和配置更新。
- [插件服务与事件](/docs-agent/protocol/v1/services-events.md)：说明服务版本匹配、调用方身份和事件交付。
- [运行环境与权限](/docs-agent/protocol/v1/security.md)：说明后台、宿主能力和页面分别运行在哪里。

## 示例

- [示例插件](/docs-agent/guides/examples.md)：下载完整项目，运行并修改代码。

## 发布

- [打包与安装](/docs-agent/publishing/package.md)：把插件目录打包成 .flyext，供用户安装。
- [发布插件](/docs-agent/publishing/marketplace.md)：管理开发者命名空间，上传安装包并提交版本审核。
- [API 密钥与开放 API](/docs-agent/publishing/open-api.md)：生成 API 密钥，让 Agent 或 CI 上传版本、更新说明并提交审核。
- [更新与迁移](/docs-agent/migrations/compatibility.md)：用插件配置版本和逐版本处理器迁移宿主管理的数据，统一提交并在失败时保留原配置。

## 维护附录

- [版本说明](/docs-agent/overview/versions.md)：区分协议版本、插件发布版本和服务版本。
- [校验器实现差异](/docs-agent/migrations/validation-differences.md)：记录桌面端与商店清单校验器的差异。
- [进程通信](/docs-agent/protocol/v1/ipc.md)：记录宿主与后台 SDK 的消息格式和处理顺序。