分发、安装与使用插件
安全分发 Raydo 插件包，并从安装走到真实 Capability 执行。
开发完成的插件以 dist/plugin.raydo.zip 分发。SDK 和脚手架发布在 npm；具体插件归档不需要作为 npm 包发布。
分发方式
开发者可以通过以下方式提供归档：
- GitHub Release；
- 产品或公司下载页；
- 企业内部 Artifact 仓库；
- 受控预览期间的直接文件传输。
分发时应同时提供预期发布者、版本、manifestDigest 和 packageDigest。使用 HTTPS 或经过认证的企业通道，不要把源码目录冒充成已经审阅的归档。
社区发布激活状态
Raydo Hub 已具备受限的社区插件契约，但公开自助提交仍保持关闭，直到发布条款、滥用与安全联系人、法律复审和运营阻止工具被一起激活。社区上架只代表发布者签名证明，不是 Raydo 的安全或质量认证。
通过 Raydo Hub 社区插件发布
社区流程把公开发现与扩展包托管严格分开：
把精确的
plugin.raydo.zip 托管在发布者控制的 HTTPS 基础设施上。Raydo Hub 不上传、不代理、也不保存扩展包字节。在 Hub 登记 Ed25519 发布者密钥。私钥始终留在 Hub 之外；怀疑泄露时应立即轮换或撤销。Hub 会返回该账户的精确发布者 ID。
在执行
npm run verify 和 npm run pack 前，把脚手架中的 developer 发布者占位值替换为这个精确 Hub 发布者 ID。包 manifest、install envelope、签名描述符与通过认证的 Hub 账户必须声明同一个发布者。创建封闭的
raydo.hub.plugin-release-descriptor.v1 描述符，绑定发布者与密钥、插件 ID 与版本、不可变归档 URL、字节大小、manifestDigest、packageDigest、兼容平台、Capability、Connector、权限和 effect。签名 canonical 描述符，并且只提交描述符。Hub 会验证发布者命名空间所有权、活跃密钥、签名、不可变身份、公开 URL 规则、受限投影和治理就绪状态。
通过的版本以 社区 · 发布者证明 和 由发布者托管 展示。举报、撤回、阻止和发布者暂停可以让它退出公开发现，但 Hub 仍不会接管扩展包。
用户在 Raydo Desktop 选择审核并安装。Desktop 只访问精确的 Hub 描述符端点，验证签名与描述符摘要，禁止重定向并直接从发布者下载，再验证字节大小、包摘要和 manifest 摘要，最终以 disabled 的
needs-review 状态安装。上架不会自动复审、授权、配置连接、启用或执行插件；浏览器模式仍然只读。在公开提交功能正式激活前，发布者可以先准备同一描述符，并继续通过上面的直接渠道分发精确归档。
安装到 Raydo Desktop
浏览器模式默认只读。安装、审阅、连接配置、Grant 和启用需要在 Raydo Desktop 中完成。
从可信来源下载精确的
plugin.raydo.zip。在 Raydo Desktop 打开 Plugins / Plugin Center，选择从本地文件安装。
选择归档；Raydo 会验证包结构、manifest、Schema、权限、可移植性、私密材料边界和 digest。
确认安装结果为
needs-review。这个状态下插件不能贡献或执行 Capability。审阅发布者、权限、effect、连接要求、Capability Schema、
manifestDigest 和 packageDigest。批准经过审阅的包；批准只会让插件进入 disabled 状态，不会自动配置连接或启用执行。
配置授权并启用
对于需要外部连接的插件：
打开 App Connections，配置所需 Provider 账号或服务。
选择插件允许使用的精确资源，例如 workspace、database、folder 或 conversation。
只为所需资源和 effect 授予经过审阅的 Capability。
回到 Plugins，启用经过审阅的插件。
纯本地插件可能不需要 App Connections，但仍然必须经过安装、审阅和启用。
生命周期状态
| 状态 | 含义 | 能否执行 |
|---|---|---|
needs-review | 归档验证通过，但还没有人工审阅授权。 | 不能 |
| 审阅后 disabled | 发布者、权限、effect 和 digest 已审阅，但插件保持停用。 | 不能 |
| enabled and ready | 审阅仍有效，所需连接、资源、Grant 和路由均存活。 | 可以 |
| enabled but not ready | 插件已启用，但连接、资源、Grant 或精确路由缺失或已漂移。 | 不能 |
| frozen update | 安装字节已变化，新身份尚未审阅。 | 不能 |
用户如何使用插件
启用后的插件向 Raydo 贡献 Capability，而不是创建一套独立应用运行时。根据插件声明的 surface，用户可以：
- 在 Capability Library 中发现能力；
- 把 Capability 分配给 Organization Role；
- 把精确 projection 加入 Workflow；
- 从受支持的 Chat 或任务路径触发；
- 在 Raydo 中检查归一化结果、provenance、Artifact 和交付结果。
执行仍然经过 Raydo 的 route、approval、Connection Grant、execution ledger、redaction、audit、Artifact 和 delivery owners。
撤销与更新
- 撤销 Grant 或连接会在新的外部 effect 前移除 readiness；
- 禁用或卸载插件会移除 contribution eligibility；
- manifest 或包内容变化会使旧审阅授权失效；
- 变化后的归档必须作为新的精确身份重新安装和审阅；
- 已保存 Workflow 不得静默切换到不同版本、digest、路由或资源。
故障检查
| 现象 | 检查项 |
|---|---|
| 安装被拒绝 | 确认文件是原始 .raydo.zip，再比较两个预期 digest。 |
一直停留在 needs-review | 在 Raydo Desktop 完成审阅；安装本身不会产生授权。 |
| 插件已启用但不可用 | 检查 App Connections、所选资源、Grant scope 和 route readiness。 |
| Workflow 提示插件 projection 已过期 | 重新打开 Workflow，并明确选择新审阅的 projection。 |
| 写操作被阻止 | 确认 Capability 声明写 effect，并满足审批和幂等要求。 |
需要生成新归档时，返回开发与打包 Raydo 插件。