开发与打包 Raydo 插件

从空目录创建独立插件，验证契约并生成确定性的 Raydo 安装包。

本页带开发者从空目录生成可安装的 dist/plugin.raydo.zip。

当前公开版本

Developer Preview 使用 create-raydo-plugin@0.1.2 和 @raydoai/plugin-sdk@0.2.0。请从 next 标签进入官方预览通道，不要把它解释为 GA。

两个 npm 包分别做什么

包	职责
`create-raydo-plugin`	创建独立 TypeScript 项目、固定命令、Capability fixture 和默认 App Connection 模板。
`@raydoai/plugin-sdk`	定义 plugin manifest、contribution、Capability、Schema、权限、fixture、验证、测试和确定性打包。

普通开发者从脚手架开始即可。生成的项目已经声明 SDK 依赖，不需要先手工安装 SDK。

五步上手

npm create raydo-plugin@next my-raydo-plugin -- --plugin-id acme.documents --display-name "Acme Documents" --connector-id notion
cd my-raydo-plugin
npm install
npm run verify
npm run pack

创建命令是非交互的。它不会自动安装依赖、发送遥测、连接 Raydo，也不会写入 Raydo 应用状态。

生成的工程

默认工程包含：

文件	用途
`plugin.ts`	类型化 plugin manifest、App Connection contribution 和 Capability 契约。
`contract-fixture.ts`	每个声明 Capability 的确定性 fixture 输出。
`package.json`	固定的构建、验证、测试、总验证和打包命令。
`tsconfig.json`	独立 NodeNext TypeScript 构建配置。
`README.md`	当前插件工程的开发步骤与所有权边界。
`.gitignore`	排除构建、依赖和归档产物。
`LICENSE`	生成工程的 MIT License。

默认模板是只读能力。只有插件确实需要写操作时，才在创建命令中加入 --write。写模板会保留审批和幂等要求，不要为了让 fixture 通过而关闭它们。

开发循环

修改 plugin.ts，并保证每个声明的 Capability 都在 contract-fixture.ts 中有对应场景。

只使用经过审阅的 JSON Schema 子集；未知关键字、重复 required、过深嵌套和无界值会验证失败。

修改 manifest、Schema、权限或打包输入时运行 npm run validate。

运行 npm test，执行所有声明 Capability 的 fixture。

生成分发包前运行 npm run verify。

运行 npm run pack，把输出的 manifest 和 package digest 与归档一起保存。

命令说明

命令	结果
`npm run validate`	构建插件，并检查 manifest、Capability、权限、Schema、可移植性、大小和私密材料边界。
`npm test`	构建插件并运行声明的契约 fixture。
`npm run verify`	依次执行验证和契约测试。
`npm run pack`	生成 `dist/plugin.raydo.zip` 并打印精确 digest；不会把插件发布到 npm 或 Raydo Hub。

包身份与审阅

npm run pack 输出两个身份：

manifestDigest 绑定经过审阅的 manifest 与 contribution 契约；
packageDigest 绑定归档的精确字节内容。

审阅后不要修改归档。manifest 或包内容发生任何变化都会产生新身份，必须在 Raydo 中重新审阅。

安全边界

不得把 API key、access token、Cookie、私钥、原始 Provider body 或生产凭据放进源码、fixture、README 示例或归档；
精确声明所需权限和外部 effect；
插件可以请求连接支持的 Capability，但不拥有用户凭据或 Grant；
插件输出必须有界并匹配经过审阅的 output Schema；
写 Capability 继续接受 Raydo 的审批和幂等约束。

下一步查看分发、安装与使用插件。