# SparkDesk Plugin 开发指南

# 整体流程

SparkDesk Plugin 从开发至用户侧使用的流程如下：

1. 开发者需要准备一个插件描述文件 spark-plugin-manifest.json，描述文件的内容和格式必须符合下面章节中的规范和要求
2. 开发者生成一个OpenAPI规范的接口文档 spark-plugin-apis.yaml，这个文档的内容结构必须严格符合OpenAPI标准
3. 在SparkDesk开发者中心创建插件，填写必要信息，并上传 spark-plugin-manifest.json 和 spark-plugin-apis.yaml 文件
4. 信息提交和文件校验通过后，星火会创建一个可预览和调试的插件
5. 等待片刻即可在调试页面进行调试，验证插件触发是否正常，验证插件接口调用是否正常
6. 开发者在调试并验证成功后可以提交插件上架申请，申请提交后会将插件相关信息递交给星火官方审核
7. 待审核通过后，您的插件便会上架星火SparkDesk的插件市场
8. 拥有插件使用权限的用户会在插件市场中找到开发者上架的插件，点击安装后用户账户即可在对话中勾选使用插件
9. 如果插件需要用户侧OAuth授权，会在用户安装时进行用户侧鉴权流程
10. 用户在使用SparkDesk上进行对话问答时，可在页面上启用插件功能并勾选本轮聊天中可以使用的插件
11. 当用户的提问被星火认知大模型判定为可以由插件处理时，开发者提供的相应接口将被调用
12. 最后，插件接口提供的信息将由星火认知大模型分析后以自然语言答案的形式返回给用户

# 插件描述文件

每个插件都需要一个名为 spark-plugin-manifest.json 的插件描述文件，此文件需在创建插件页面上上传。当你通过SparkDesk开发者中心创建插件时，需要使用 spark-plugin-manifest.json 文件来描述和定义你的插件。这份描述文件中的部分信息会协助星火认知大模型在用户对话过程中正确地触发和调用插件，另一部分信息则将在插件商店中展示你的插件。如果插件接口的调用需要授权，还需要在文件中填写额外的授权信息字段。

# 描述文件字段解释

当auth.type=service_http时：

当auth.type=oauth时：

# 描述文件Demo

无鉴权的插件描述文件Demo:

{
  "schema_version": "v1",
  "name_for_human": "AI法律助手",
  "name_for_model": "法律知识检索与问答",
  "description_for_human": "随身的人工智能法律知识助手，帮您解决生活中的法律问题，助力构建法治社会。",
  "description_for_model": "法律知识检索与问答插件；检索法律知识库并回答用户的法律问题；可以检索包括刑法、民法典、社会法、经济法、行政法等众多法律内的法律条文，并根据用户提问回答问题。",
  "auth": {
    "type": "none"
  },
  "logo_url": "https://YOUR_DOMAIN/logo.png",
  "contact_email": "support@YOUR_DOMAIN",
  "legal_info_url": "https://YOUR_DOMAIN/legal"
}

服务侧鉴权的插件描述文件Demo:

{
  "schema_version": "v1",
  "name_for_human": "AI法律助手",
  "name_for_model": "法律知识检索与问答",
  "description_for_human": "随身的人工智能法律知识助手，帮您解决生活中的法律问题，助力构建法治社会。",
  "description_for_model": "法律知识检索与问答插件；检索法律知识库并回答用户的法律问题；可以检索包括刑法、民法典、社会法、经济法、行政法等众多法律内的法律条文，并根据用户提问回答问题。",
  "auth": {
    "type": "service_http",
    "authorization_type": "bearer",
    "verification_token": "7addeb9de979e5e6214sc3da7643ca"
  },
  "logo_url": "https://YOUR_DOMAIN/logo.png",
  "contact_email": "support@YOUR_DOMAIN",
  "legal_info_url": "https://YOUR_DOMAIN/legal"
}

用户侧鉴权的插件描述文件Demo:

{
  "schema_version": "v1",
  "name_for_human": "AI法律助手",
  "name_for_model": "法律知识检索与问答",
  "description_for_human": "随身的人工智能法律知识助手，帮您解决生活中的法律问题，助力构建法治社会。",
  "description_for_model": "法律知识检索与问答插件；检索法律知识库并回答用户的法律问题；可以检索包括刑法、民法典、社会法、经济法、行政法等众多法律内的法律条文，并根据用户提问回答问题。",
  "auth": {
    "type": "oauth",
    "client_url": "https://YOUR_DOMAIN/oauth/v2/authorize",
    "authorization_url": "https://YOUR_DOMAIN/api/oauth.v2.access",
    "scope": "search:read",
    "authorization_content_type": "application/x-www-form-urlencoded",
    "client_id": "e979e5",
    "client_secret": "214sc3-ddeb9de979e5e6214sc3d"
  },
  "logo_url": "https://YOUR_DOMAIN/logo.png",
  "contact_email": "support@YOUR_DOMAIN",
  "legal_info_url": "https://YOUR_DOMAIN/legal"
}

# OpenAPI规范的接口文档

下一步是建立OpenAPI规范文档来描述开发者提供的API集合。除了OpenAPI规范和清单文件中定义的内容外，星火认知大模型并不了解开发者的API。如果开发者的Web应用包含大量的API，并非所有接口都需要向星火Desk公开。因此，我们建议你将OpenAPI规范文档限制在SparkDesk Plugin所需的最小API集合内。并且，我们推荐单个插件功能所需的接口数量保持在1-3个范围，这样星火认知大模型可以以最优的判断和最好的决策路径进行API的调用。

插件接口的描述文件应完全依照OpenAPI规范来编写。参考文档：OpenAPI规范（中文版） (opens new window)

Web项目自动生成OpenAPI规范文档可使用下面的Lib/Framework：

• Java SpringBoot Application - springdoc-openapi (opens new window)
• Python Flask Application - flask-siwadoc (opens new window)
• Python Django Application - django-rest-swagger (opens new window)
• Go gin/echo/buffalo etc. Application - swaggo (opens new window)
• C# ASP.NET Application - swashbuckle (opens new window)

# 接口规范文档Demo

openapi: 3.0.1
info:
  title: 法律知识检索与问答
  description: 法律知识检索与问答插件；检索法律知识库并回答用户的法律问题；可以检索包括刑法、民法典、社会法、经济法、行政法等众多法律内的法律条文，并根据用户提问回答问题。
  version: 'v1'
servers:
  - url: http://localhost:6666
paths:
  /search:
    get:
      operationId: getAnswer
      summary: 获得法律条文及解释
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getAnswerResponse'
components:
  schemas:
    getAnswerResponse:
      type: object
      properties:
        provisions:
          type: array
          items:
            type: string
          description: 法律条文及解释的列表

# 额外要求与注意事项

1. 如果在OpenAPI文档中存在多个服务器URL，目前的版本会默认选择列表中的第一个URL。也就是说，如果存在如下所示的服务器列表，星火Desk插件系统将只会调用 http://host1:6666 这个路径。

servers:
- url: http://host1:6666
- url: http://host2:6666
- url: http://host3:6666

2. 插件接口文档中的info字段内的title和description字段的值需要与插件描述文件 (opens new window)中的 name_for_model 和 description_for_model 保持一致。

{
  ...,
  "name_for_model": "法律知识检索与问答", 
  "description_for_model": "法律知识检索与问答插件；检索法律知识库并回答用户的法律问题；可以检索包括刑法、民法典、社会法、经济法、行政法等众多法律内的法律条文，并根据用户提问回答问题。",
  ...
}

info:
  title: 法律知识检索与问答
  description: 法律知识检索与问答插件；检索法律知识库并回答用户的法律问题；可以检索包括刑法、民法典、社会法、经济法、行政法等众多法律内的法律条文，并根据用户提问回答问题。

# 插件鉴权

# 无鉴权

当插件开发者在SparkDesk开发者中心注册插件并选择No Auth选项时，意味着插件提供的API在其调用流程中将不涉及任何形式的鉴权。因此，星火Desk的用户在安装这些插件时，无需经历任何特殊的登录或授权流程。在用户聊天过程中，如果插件调用被触发，星火Desk的服务器将直接请求插件API，以获取所需结果。

# 服务侧鉴权

开发者在创建插件时，通常需要利用某种鉴权方式来保护他们的API端点。目前，星火Desk插件系统只支持通过HTTP Bearer认证 (opens new window)实现服务侧鉴权。

在SparkDesk开发者中心注册插件并选择 服务侧鉴权 选项的开发者，需要填写表单中的token字段。当用户在聊天中触发插件调用时，星火Desk的后端服务会在向您的API发送请求时，会在HTTP Header中添加Bearer Token：

Authorization: Bearer <token>

这样，通过鉴权机制，可以确保插件提供方API的安全性，防止非法访问。

# 用户侧鉴权

如果插件的某些功能依赖于星火用户在插件提供商的服务或网站上注册并拥有账户，那么必须实现插件的用户侧鉴权。此用户侧鉴权过程在用户从商店安装插件时发生，并且在OAuth AccessToken失效时，会再次触发用户侧鉴权流程。

星火Desk插件采用OAuth2.0授权码模式进行用户侧鉴权。相关的时序图如下所示：

注1: 图中的插件授权服务器和插件API服务器可以是同一台服务器或同一个域名下的不同接口，图中是在逻辑上将两者区分开。

注2: 图中流程涉及的具体参数名或url地址会在后面的更新版本中给出