# 插件 SDK

`.xfeplugin` 是 ZIP，根目录必须包含 plugin.json、入口程序集及依赖。SDK 使用 .NET 10；公共接口在 XFEWorkflow.Abstractions 中。

```json
{
  "schemaVersion": 1,
  "sdkMajorVersion": 1,
  "sdkMinimumVersion": "1.0.0",
  "sdkMaximumVersionExclusive": "2.0.0",
  "id": "sample.echo",
  "name": "示例回声",
  "version": "1.0.0",
  "assembly": "XFEWorkflow.Plugins.Sample.dll",
  "entryType": "XFEWorkflow.Plugins.Sample.EchoPlugin",
  "supportedRids": [],
  "dependencies": [],
  "capabilities": []
}
```

实际清单的 capabilities 需要声明 ID、pluginId、名称、输入输出端口，以及执行出口。能力 ID 必须以插件 ID 加点开头。输入端口的 type、label、required、defaultValue、secret、choices 生成属性表单。IsTrigger 为 true 时注册为触发器，无输入的触发器显示说明而非原始参数编辑框。SDK 范围必须包含当前宿主版本 1.7.1，原有 1.0.0～2.0.0 的插件仍兼容。SDK 1.4 支持专用类型、端口说明、触发事件字段映射和兼容别名；1.5 支持企微接收全部新消息的宿主协议；1.6 增加可通过能力 ID 调用的基础纯数据节点及结构化循环控制；1.7 增加页面插件，1.7.1 为页面提供账号显示信息及密钥与设置合并保存。详见[基础节点](basic-nodes.md)、[端口与类型转换](typed-ports.md)及下方页面接口。

SDK 1.1 新增 `ScreenRegion` 物理像素区域模型和 `PortDefinition.EditorHint`。`screen-region`、`screen-point`、`file-open`、`file-save` 分别生成区域框选、坐标拾取、图像选择和 PNG 保存控件，支持 JSON 与数据绑定。使用这些新增 API 的插件应声明 `sdkMinimumVersion: "1.1.0"`。区域与点仍以 JSON 对象跨插件传递。

SDK 1.2 新增 `IWorkflowContext.ExecuteGraphAsync`，用于运行图形生成的可编辑 C#；执行仍通过统一引擎，保留节点日志、变量、结构化子图、超时和取消。使用新增接口的插件应声明 `sdkMinimumVersion: "1.2.0"`。接口提供默认实现，旧版插件上下文实现不需要补充新方法。

插件触发能力会显示在节点库的“触发器”分类，保留插件来源名称。清单的 inputs 用于属性区的监听参数；画布端口为 `next`、`event` 和 `inputs`。事件由插件的 emit 回调发送，只有对应节点的分支会执行，插件实现无需直接调用其他工作流。

触发器的监听参数在 Runner 中解析 `$secret`、`$input` 与 `$var` 绑定，再应用默认值并校验必填项和类型。`$input` 读取工作流默认输入；此时尚无节点输出。标记 `secret` 的表单字段填写“设置 → 凭据”中的名称，保存为 `{"$secret":"名称"}`。监听异常回传调度状态与日志；停止时宿主也释放实现了 `IAsyncDisposable` / `IDisposable` 的触发器实例。

依赖使用 `id`、`minimumVersion`、`maximumVersionExclusive`；版本遵循 SemVer。supportedRids 为空表示不限制，Windows 专用插件应声明 win-x64 / win-x86 / win-arm64。

## 实现

入口实现 IWorkflowPlugin，在 Register 中调用 RegisterAction 或 RegisterTrigger，工厂创建动作实例。动作接收 JSON 输入、IWorkflowContext 和 CancellationToken，异步返回 JsonObject。触发器通过 emit 提交输入数据，并在取消时释放监听资源。

使用 context.InvokeAsync 调用另一插件的稳定能力 ID，使用 context.GetSecretAsync 读取凭据引用。浏览器等运行资源以句柄传递。跨插件只引用 SDK，通过清单声明版本依赖，不直接引用实现 DLL。

输入默认值只应用于未提供的参数；显式 null 保持为空，必填参数为空则报错。“屏幕与识别”1.1.0 的找图节点增加 `minimumSimilarity`（0.01～1，默认 0.9），`templatePath` 同时接受本地路径和内嵌 PNG data URI。`minimumSimilarity: null` 使用旧版逐通道 `tolerance` 规则，方便已有工作流升级后保持原行为。

完整示例在 `samples/XFEWorkflow.Plugins.Sample`：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools/Pack-Sample.ps1
```

将生成的 `.xfeplugin` 在“插件中心”导入，即可在节点库看到“回声”。升级时提高版本号后重新导入，已有版本内容不覆盖；工作流仍使用锁定的旧版本，需在工作流设置中显式更新锁定版本。

在线发布在独立的“Space → 上传插件”中进行，登录后选择 `.xfeplugin`。在“我的发布”查看审核状态，管理员审核上架后其他用户可下载，依赖会自动获取。本地插件中心保留版本管理与导出。Space 也支持上传完整工作流，工作流声明的插件版本锁定会随包携带，详见 [Space 发布流程](space.md)。

每个插件版本拥有独立加载上下文，SDK 共享。卸载运行中的版本会先禁用、等待运行结束再删除。安装校验包大小、展开总量、入口文件、兼容范围、重复路径、链接与路径越界；服务端仅存储检查包，不执行 DLL。

## 官方能力

| 插件 | 能力 |
|---|---|
| xfe.http | request |
| xfe.file | read / write / list |
| xfe.ai | chat，Chat Completions 兼容服务 |
| xfe.wecom | send，群机器人 text / markdown |
| xfe.browser | open / navigate / wait / click / input / extract / script / screenshot / download / close |
| xfe.desktop | pick / activate / read / fill / click / text / keys / sequence |
| xfe.vision | selectRegion / capture / ocr / findText / waitText / clickText / findImage / waitImage / clickImage / pixel / waitColor / click / move / drag / scroll / clipboardRead / clipboardWrite |
| xfe.timer | 定时事件触发器 |

参数、输出和默认值的完整定义在官方插件 Manifests 与桌面插件 plugin.json 中。

## 页面插件（SDK 1.7）

插件可以同时提供动作、触发器和页面，也可以只提供页面。清单新增 `pages`，并声明 `sdkMinimumVersion: "1.7.0"`。已有不含 pages 的插件保持兼容。页面 ID 与能力一样必须属于插件命名空间，且不能重复。

~~~json
{
  "pages": [{
    "id": "sample.tools.dashboard",
    "pluginId": "sample.tools",
    "name": "工具面板",
    "iconGlyph": "\uE774",
    "assembly": "Sample.Tools.WinUI.dll",
    "entryType": "Sample.Tools.WinUI.Dashboard"
  }]
}
~~~

主插件的 `IWorkflowPlugin.Register` 调用 `registry.RegisterPage(descriptor)`。SDK 的页面元数据不引用 WinUI，因此 Runner 和独立 Space 服务端都能读取清单，检查包内程序集而不加载界面。

原生视图程序集引用 `XFEWorkflow.Desktop.Sdk`，目标框架 `net10.0-windows10.0.22621.0`，启用 UseWinUI，实现：

~~~csharp
public interface IWorkflowPage : IAsyncDisposable
{
    FrameworkElement View { get; }
    ValueTask InitializeAsync(IPluginPageContext context, CancellationToken cancellationToken);
}
~~~

宿主在 UI 线程创建视图、调用 InitializeAsync；模型请求、进程、CPU 工作应异步安排到后台。IPluginPageContext 提供插件目录、独立数据目录、AutoConfig 设置、凭据引用和加密保存、WinUIHelper 的 WebView 初始化、可拖动分隔条、XFE 日志与敏感值过滤。宿主页面卡片样式为 `ManagementCardStyle`，使用主题资源，支持深浅主题切换。

SDK 1.7.1 增加 `User`、`GetUserAsync(ct)` 和 `UserChanged`。`PluginPageUser` 只包含账号 ID、显示名称和经过宿主读取的头像 data URI；不会提供登录 session。头像请求限制格式、体积与超时，不向头像地址附带账号凭据。页面应在 UI 线程更新视图，并在 DisposeAsync 取消订阅。需要这些接口的插件将 `sdkMinimumVersion` 设为 `1.7.1`。

`SaveSettingsWithCredentialAsync(settings, reference, secret, ct)` 让桌面宿主将加密密钥与插件设置写入同一个 AutoConfig 快照；`settings.credential` 必须等于对应引用。已有分开的保存接口仍可用。官方 Agent 浏览器 1.0.1 使用此接口避免新密钥已保存、引用却未更新的不一致状态。

启用插件后自动增加导航项；首次打开才加载页面程序集。主插件与页面共用该版本的加载上下文，SDK、WinUI 与 WebView2 宿主程序集共享。页面及依赖持有版本租约；切换导航保留实例，禁用、升级后切换版本、卸载或退出时调用 DisposeAsync。若 Windows 仍占用 DLL，则保持待移除状态，下次启动继续清理。DisposeAsync 必须取消任务并释放 WebView2、进程和事件。

页面程序集与资源一起打入原来的 .xfeplugin，不需要另一种包。可像其他插件一样上传 Space、声明依赖并自动安装。完整参考实现为 `XFEWorkflow.Plugins.AgentBrowser` 和 `XFEWorkflow.Plugins.AgentBrowser.WinUI`；[DeepSeek Agent 浏览器说明](agent-browser.md)。离线 Markdown 库已随仓库保存；更新时运行 `tools/Update-AgentChatAssets.ps1`，使用固定版本和锁文件。

Agent 浏览器 **1.2.0** 还在包内包含 `Skill/`（browser-debugger 及锁定的 Playwright 依赖）和 `Runtime/`（对应架构的 Node、许可证和来源哈希）。`tools/Copy-AgentRuntime.ps1` 在构建时完成校验与打包，客户端安装和每轮对话不运行环境检测、不读取外部技能目录，也不要求安装 Node/npm。该版本最低 SDK 仍为 **1.7.1**。