dify-plugin-daemon/docs/runtime/sri_cn.md

Dify Plugin Daemon - Serverless Runtime Interface (SRI)

Serverless Runtime Interface (SRI) 是一组用于将插件封装为 Serverless 组件，并由 Dify Plugin Daemon 在外部平台（如 AWS Lambda）上远程启动和运行的 HTTP 接口规范。

该接口允许 daemon 通过标准协议与远程运行环境通信，实现插件部署、运行、实例查询等功能。

⚠️ 注意：当前接口处于 Alpha 阶段，不保证稳定性与向后兼容性。 企业版中提供生产级 SRI 实现, 如需请联系 business@dify.ai。

---

🔧 基础配置

daemon 通过如下环境变量进行配置：

变量名	含义
DIFY_PLUGIN_SERVERLESS_CONNECTOR_URL	指定远程运行环境的 Base URL，例如 https://example.com
DIFY_PLUGIN_SERVERLESS_CONNECTOR_API_KEY	用于访问 SRI 的鉴权 token，将被加入请求 Header 中的 Authorization 字段

---

📡 接口说明

GET /ping

用于 daemon 启动时的连通性检查。

请求

GET /ping
Authorization: <API_KEY>

响应

• 200 OK，响应体为纯文本字符串 "pong"

---

GET /v1/runner/instances

返回支持运行的插件实例信息。

请求参数

• filename（必填）：上传的插件包文件名，格式为：

  vendor@plugin@version@hash.difypkg
  

响应

{
  "items": [
    {
      "ID": "string",
      "Name": "string",
      "Endpoint": "string",
      "ResourceName": "string"
    }
  ]
}

---

POST /v1/launch

以流式事件的方式启动插件，供 daemon 实时解析启动状态。

本接口使用 multipart/form-data 提交，同时以 Server-Sent Events（SSE） 返回插件运行状态流。

请求字段

字段名	类型	描述
context	file	.difypkg 格式的插件包
verified	boolean	插件是否已通过 daemon 验证（由 manifest 判断）

SSE 响应格式

{
  "Stage": "healthz|start|build|run|end",
  "State": "running|success|failed",
  "Obj": "string",
  "Message": "string"
}

阶段说明

Stage	含义	行为说明
healthz	健康检查	初始化运行时资源，准备插件容器
start	启动准备阶段	准备环境
build	构建阶段	构建插件依赖，打包镜像
run	运行阶段	插件运行中，如成功将返回关键信息
end	启动完成	插件运行结果确认，可能为 success 或 failed

当接收到以下格式的 Stage=run 且 State=success 消息时，daemon 将提取其中信息并建立插件实例：

endpoint=http://...,name=...,id=...

错误处理

• 任意阶段返回 State = failed 即视为启动失败
• daemon 应中断流程并抛出异常，输出 Message 内容作为错误信息

---

🔁 通信时序图（ASCII）

daemon                              Serverless Runtime Interface
   |-------------------------------------->|
   |           GET /ping                  |
   |<--------------------------------------|
   |         200 OK "pong"                |
   |-------------------------------------->|
   |    GET /v1/runner/instances          |
   |            filename                  |
   |<--------------------------------------|
   |             {items}                  |
   |-------------------------------------->|
   |        POST /v1/launch               |
   | context, verified multipart payload |
   |<--------------------------------------|
   |   Building plugin... (SSE)           |
   |<--------------------------------------|
   |   Launching plugin... (SSE)          |
   |<--------------------------------------|
   |   Function: [Name] (SSE)             |
   |<--------------------------------------|
   |   FunctionUrl: [Endpoint] (SSE)      |
   |<--------------------------------------|
   |   Done: Plugin launched (SSE)        |

---

📦 插件文件名规范

插件文件扩展名必须为 .difypkg，命名格式如下：

<vendor>@<plugin_name>@<version>@<sha256_hash>.difypkg

示例：

langgenius@tavily@0.0.5@7f277f7a63e36b1b3e9ed53e55daab0b281599d14902664bade86215f5374f06.difypkg

---

📬 联系我们

如需接入商业支持版本，或希望深入了解插件打包与部署规范，请联系：

📧 business@dify.ai

---

📘 OpenAPI 规范（YAML）

openapi: 3.0.3
info:
  title: Dify Plugin Daemon - Serverless Runtime Interface (SRI)
  version: alpha
  description: HTTP API specification for the Dify Plugin Daemon's Serverless Runtime
    Interface (SRI).
paths:
  /ping:
    get:
      summary: Health check endpoint
      description: Used by the daemon to verify connectivity with the SRI.
      responses:
        '200':
          description: Returns 'pong' if the service is alive
          content:
            text/plain:
              schema:
                type: string
                example: pong
      security:
      - apiKeyAuth: []
  /v1/runner/instances:
    get:
      summary: List available plugin instances
      parameters:
      - name: filename
        in: query
        required: true
        schema:
          type: string
        description: Full plugin package filename (e.g., vendor@plugin@version@hash.difypkg)
      responses:
        '200':
          description: List of available plugin instances
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        ID:
                          type: string
                        Name:
                          type: string
                        Endpoint:
                          type: string
                        ResourceName:
                          type: string
      security:
      - apiKeyAuth: []
  /v1/launch:
    post:
      summary: Launch a plugin via SSE
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                context:
                  type: string
                  format: binary
                  description: Plugin package file (.difypkg)
                verified:
                  type: boolean
                  description: Whether the plugin is verified
              required:
              - context
      responses:
        '200':
          description: Server-Sent Events stream with plugin launch stages
          content:
            text/event-stream:
              schema:
                type: object
                properties:
                  Stage:
                    type: string
                    enum:
                    - healthz
                    - start
                    - build
                    - run
                    - end
                  State:
                    type: string
                    enum:
                    - running
                    - success
                    - failed
                  Obj:
                    type: string
                  Message:
                    type: string
      security:
      - apiKeyAuth: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization