#插件开发

SciLaxy 插件把不可变能力声明连接到用户显式选择的 Desktop 或 Runner。服务器是控制面；可执行代码、操作凭据、provider 进程、工具调用以及插件访问的本地文件始终留在该设备。

本节面向扩展目录、开发本地 provider、维护运行时或排查连接问题的开发者，描述当前真实实现。

#心智模型

一个可用插件不是一张表或一个二进制文件，而是六类授权的交集：

flowchart LR
  Catalog[Plugin release] --> Install[用户安装]
  Install --> Connection[Provider connection]
  Install --> Permission[权限策略]
  Connection --> Device[指定 Desktop / Runner]
  Device --> Runtime[本地 runtime 或 provider]
  Permission --> Call[已授权调用]
  Runtime --> Call

服务器只保存足以决定和审计一次调用的证据，不会收到飞书 App Secret、GitHub Token、本地可执行路径或 provider 进程副本。

当前模型是账户级授权。旧迁移或历史文档可能出现 plugin_session_snapshot、plugin_session_capability、agent_plugin_binding；迁移 00093 已经删除它们。Runtime Session 和外部效果现在直接冻结自己实际使用的授权。

#能力类型

一个 release 可以声明下列闭合能力类型：

每项能力都有稳定 key、严格配置 JSON、配置摘要、声明权限和确定顺序。未知字段或未声明能力类型会被拒绝，不会被静默忽略。

#内置插件

当前内置目录包含：

service/pkg/core/plugin/builtin/catalog.json 是内置目录的唯一产品事实源。部署 origin、发布渠道、签名 key 和环境 secret 不属于插件可执行代码。

#生命周期

从目录到可调用插件的正常路径是：

1. 安装一个不可变 release。安装不会自动登录 provider。
2. 选择设备，该设备必须完成登记并持有有效租约。
3. 配置连接。device-local profile 通过签名设备动作和隔离的 Desktop 凭据窗口完成。
4. 批准权限，覆盖 release 声明的能力。
5. 启用安装。Worker 会在提交状态前重新计算 readiness。
6. 调用工具、Channel 或 runtime。请求冻结当前修订并只为一个设备 generation 签名。
7. 审计和对账外部副作用，不盲目重放结果不明的写操作。

安装生命周期命令是异步的。API 先预留幂等 plugin_installation_operation，投递 plugin:lifecycle:execute，Worker 再把 operation 从 pending 推进到 running 和终态。

#理解启用操作

“启用”是最后的 readiness gate，不是配置向导。一个 disabled installation 仍可能缺少 connection、权限策略、设备租约、runtime 或可信 release。

任一条件缺失时，Worker 返回 requirements_unmet。health projection 会携带可操作 blocker，例如：

• connection_required
• permission_required
• device_offline
• runtime_incompatible
• release_revoked
• policy_changed

对于新安装的飞书插件，开发者仅仅持有 App ID 和 App Secret 还不够。必须先在指定 Desktop 创建命名 profile，完成安全凭据输入使 connection 进入 ready，批准请求权限，然后才能启用。

当前 UI 可能在这些步骤尚未完成时仍允许提交“启用”。此时异步拒绝属于后端预期行为；缺少前置引导是产品交互问题，并不表示租约、签名或凭据校验失败。

#继续阅读

• 数据模型 解释当前全部 23 张插件表。
• 运行时与安全 说明服务端/设备边界、信任链、凭据存储、外部效果、Channel 和 webhook relay。
• 开发与排障 提供路由、本地启动、readiness 错误、SQL 诊断和扩展清单。