插件配置 - manifest.json

一、配置文件概述

manifest.json 是插件的核心配置文件，位于插件根目录，定义了插件的基本信息、前端配置、后端配置等。

二、完整配置示例

{
  "id": "asr",
  "title": "AI语音识别",
  "version": "1.0.0",
  "description": "识别视频和音频的语音内容",
  "author": "小蜗工具",
  "icon": "frontend/public/logo.png",
  "dev_mode": false,
  "frontend": {
    "entry": "frontend/dist/index.html",
    "width": 1280,
    "height": 900,
    "resizable": true,
    "maximizable": true,
    "decorations": false
  },
  "backend": {
    "type": "python",
    "runtime": "",
    "use_local_runtime": true,
    "fallback_runtime": true,
    "entry": "backend/main.py",
    "args": [],
    "env": {
      "PYTHONIOENCODING": "utf-8"
    },
    "pip": {
      "numpy": "1.23.5",
      "pydub": null
    }
  },
  "dev": {
    "frontend": {
      "entry": "http://localhost:5173"
    },
    "backend": {
      "runtime": "D:\\python\\python.exe",
      "use_local_runtime": false,
      "entry": "backend/main.py",
      "args": ["--dev"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  },
  "extmodels": {
    "check_files": [
      "python310\\python.exe",
      "__users__\\.cache\\huggingface\\hub\\models--xxx\\model.pt",
      "__models__\\whisper\\model.bin"
    ],
    "download_url": "https://example.com/download"
  }
}

三、基础字段

字段	类型	必需	说明
id	string	是	插件唯一标识，用于目录名和窗口标签
title	string	是	插件显示名称
version	string	是	版本号（建议使用语义化版本）
description	string	否	插件描述
author	string	否	作者信息
icon	string	否	图标路径（相对于插件目录）
dev_mode	boolean	否	开发模式开关，默认 false

四、frontend 前端配置

字段	类型	必需	说明
entry	string	是	入口文件路径（相对于插件目录）
width	number	否	窗口宽度，默认 1200
height	number	否	窗口高度，默认 800
resizable	boolean	否	是否可调整大小，默认 true
maximizable	boolean	否	是否允许最大化，默认 true
decorations	boolean	否	是否显示系统窗口边框，默认 false

说明：

• decorations: false 时使用小蜗自定义标题栏
• entry 生产模式通常为 frontend/dist/index.html

五、backend 后端配置

字段	类型	必需	说明
type	string	是	后端类型：python / node / exe
entry	string	是	入口文件路径（相对于插件目录）
runtime	string	否	运行时路径（绝对或相对路径）
use_local_runtime	boolean	否	是否使用插件目录内的运行时（仅python）
fallback_runtime	boolean	否	本地运行时找不到时是否回退到系统运行时（仅python）
args	string[]	否	启动参数
env	object	否	环境变量
pip	object	否	pip 依赖配置（仅 python 类型有效，不要配置大型包 例如：torch）

5.1 运行时查找优先级

Python 运行时：

1. use_local_runtime: true → 在插件目录查找 python.exe
2. 找不到且 fallback_runtime: true → 继续下一步
3. runtime 配置 → 使用指定路径
4. 小蜗内置 Python → 使用应用配置的 Python
5. 系统 python → 回退到系统环境变量

5.2 pip 依赖配置，不要配置大型包 例如：torch

"pip": {
  "numpy": "1.23.5",
  "pydub": null,
  "requests": null
}

• null 表示不限制版本
• 字符串值表示指定版本
• 插件启动时自动检查并安装缺失依赖
• 如果该插件依赖 torch 这种大型包或者额外需要其他模型文件，千万不要配置torch，太大下载不稳定。建议做成一个独立的python环境和模型包一起打包成 7z 压缩包。
• 参考下面 第八节 extmodels扩展模型包配置

六、dev 开发模式配置

当 dev_mode: true 时，使用 dev 配置覆盖 frontend 和 backend：

"dev": {
  "frontend": {
    "entry": "http://localhost:5173"
  },
  "backend": {
    "runtime": "D:\\python\\python.exe",
    "use_local_runtime": false,
    "entry": "backend/main.py",
    "args": ["--dev"]
  }
}

开发模式优势：

• 前端连接本地开发服务器，支持热重载
• 后端可传入调试参数
• 可指定开发环境专用的 Python 路径

七、最小配置示例

7.1 纯前端插件（无后端）

{
  "id": "my-tool",
  "title": "我的工具",
  "version": "1.0.0",
  "frontend": {
    "entry": "frontend/dist/index.html"
  }
}

7.2 带 Python 后端的插件

{
  "id": "my-tool",
  "title": "我的工具",
  "version": "1.0.0",
  "frontend": {
    "entry": "frontend/dist/index.html"
  },
  "backend": {
    "type": "python",
    "use_local_runtime": true,
    "fallback_runtime": true,
    "entry": "backend/main.py",
    "env": {
      "PYTHONIOENCODING": "utf-8"
    }
  }
}

八、extmodels扩展模型包配置

extmodels 用于配置插件依赖的外部模型包或大型资源文件。

8.1 配置示例

"extmodels": {
  "check_files": [
    "python310\\python.exe",
    "__users__\\.cache\\huggingface\\hub\\models--xxx\\model.pt"
  ],
  "download_url": "https://example.com/download"
}

8.2 字段说明

字段	类型	说明
check_files	string[]	需要检测的文件路径列表
download_url	string	模型包下载页面地址

8.3 路径占位符

check_files 支持以下占位符：

占位符	说明
__users__	用户目录（如 C:\Users\xxx）
__models__	公共模型目录（extlibs/models），多个插件可共享的模型存放位置
无占位符	相对于插件后端目录

前端触发检查：

配置好 extmodels 后，需要在前端调用 callBackend 时传入 check_extmodel: true 参数来触发检查。通常在需要使用模型的请求中添加：

// 示例：在获取配置时检查模型是否已安装
const config = await PluginSDK.callBackend("function", {
  check_extmodel: true,
})

当 check_extmodel: true 时，系统会在执行后端方法前自动检查 check_files 中的文件是否存在。如果缺失，会自动弹出下载引导窗口并返回错误提示，后端方法不会被执行。

建议在插件初始化或首次使用模型的请求中添加此参数，无需在每个请求中都携带。