manifest.json 字段参考#

manifest.json 是插件包根目录中的清单文件。它同时用于插件身份识别、商店展示、入口加载、权限声明、搜索触发和版本更新记录。

上传时，服务端会读取并校验清单；校验失败会一次性返回全部问题。字段名区分大小写，必须使用下面的驼峰写法，例如 clipboardRules，不能写成 clipboard_rules。

完整示例#

下面示例包含当前支持的全部可声明字段：

{
  "code": "word_counter",
  "name": "字数统计",
  "version": "1.0.0",
  "description": "统计文本的字符数、词数和行数",
  "author": "Developer",
  "entry": "index.js",
  "runtime": "vue",
  "category": "效率办公",
  "icon": "🔢",
  "keywords": ["count", "word", "字数"],
  "tags": ["文本", "效率"],
  "permissions": ["clipboard:write"],
  "minApiLevel": 1,
  "requires": [],
  "optional": [],
  "features": [
    {
      "name": "字数统计",
      "description": "统计字符、词和行",
      "code": "count",
      "cmds": ["字数", "count", { "type": "over", "minLength": 1, "maxLength": 5000 }]
    }
  ],
  "clipboardRules": [
    {
      "name": "长文本",
      "pattern": "长度在 1 到 5000 个字符之间",
      "example": "一段需要统计的文本",
      "action": "打开字数统计",
      "matchType": "regex",
      "regex": "^[\\s\\S]{1,5000}$",
      "regexFlags": ""
    }
  ],
  "config": {
    "trimWhitespace": true,
    "defaultMode": "all"
  },
  "homepage": "https://github.com/example/word-counter",
  "screenshots": ["assets/screenshot.png"],
  "changelog": [
    { "version": "1.0.0", "date": "2026-08-28", "notes": "首个版本" }
  ]
}

必须提供的字段为 code、name、version、description 和 author。entry、runtime、category 虽然包含在模板中，但服务端分别默认为 index.js、vue、开发工具；建议始终显式填写，避免清单含义不清。其余字段可以省略；省略时按各字段说明中的默认值处理。

顶层字段#

entry 与构建目录#

entry 是上传产物中的路径，不是源码入口。标准 Vue + Vite 模板通常使用：

src/main.js  →  pnpm build  →  dist/index.js

因此清单一般写 "entry": "index.js"，上传或调试时选择包含 manifest.json 和 index.js 的 dist 目录。

icon 的三种写法#

字符或 emoji 图标：

{
  "icon": "🧩"
}

包内图片的相对路径（推荐，图片随插件包一起上传，不必自己找图床）：

{
  "icon": "icon.png"
}

http(s) 外链图片：

{
  "icon": "https://example.com/assets/icon.png"
}

包内相对路径的写法与 screenshots 一致：

• 路径相对包根目录，与 entry 同一套写法，子目录也可以写（如 assets/logo.svg）。
• 支持的扩展名：.png、.jpg、.jpeg、.webp、.gif、.svg、.ico。
• 建议使用正方形图片：客户端按 42×42 显示（详情页 60×60），采用 object-fit: cover，非正方形会被裁切。
• 上传后会自动转换为 /store-packages/<code>/<version>/... 形式的站内地址，客户端拿到的则是补全了域名的绝对地址。
• 声明了包内路径但文件没有打进包时，图标会退回默认的 ◆，不会显示为裂图。
• 每个版本带自己的图标，修改图标后重新打包并递增 version 即可。

外链图片必须能被客户端直接访问，否则商店卡片与启动器磁贴都会裂图——那是所有用户都要去加载的地址，请确保图床长期稳定。

字符图标不参与包内路径解析：它最多 8 个字符，也不带图片扩展名，因此不会与相对路径混淆。

features 功能点#

features 描述插件能做什么，并可声明主搜索框的触发指令。每个功能对象包含以下字段：

features[].cmds 指令类型#

字符串指令最多 30 个字符。over 的 minLength、maxLength 会转为正整数；不填或不是正数时使用运行时默认边界。主入口直接打开插件时，enterAction.type 为 open。

{
  "features": [
    {
      "name": "JSON 美化",
      "description": "缩进格式化 JSON",
      "code": "pretty",
      "cmds": [
        "json",
        "格式化",
        { "type": "regex", "match": "^[\\[{]", "flags": "" }
      ]
    },
    {
      "name": "图片处理",
      "description": "处理剪贴板图片",
      "code": "image",
      "cmds": [{ "type": "img" }]
    }
  ]
}

插件通过 api.getEnterAction() 或 api.onPluginEnter() 读取进入动作。动作中的 payload 是命中的文本，图片指令时通常是图片 data URL。

clipboardRules 剪贴板规则#

当用户通过全局快捷键唤出客户端时，宿主会检查剪贴板内容。命中规则后，内容会被填入搜索框并显示插件入口。剪贴板里是文件时走单独的「快捷识别」链路，见下文剪贴板文件与快捷识别。每条规则包含：

内置匹配类型如下：

正则应尽量短小、范围明确，避免灾难性回溯或匹配所有文本，防止抢占其他插件的剪贴板入口。

{
  "clipboardRules": [
    {
      "name": "颜色值",
      "pattern": "HEX、RGB 或 HSL 颜色",
      "example": "#2f81f7",
      "action": "打开取色面板",
      "matchType": "color"
    },
    {
      "name": "URL",
      "pattern": "完整 HTTP(S) 地址",
      "example": "https://toolzen.top",
      "action": "打开链接工具",
      "matchType": "url"
    }
  ]
}

剪贴板文件与快捷识别#

剪贴板里是文件时走的是另一条链路，不需要写正则：宿主直接读剪贴板里的文件路径列表，把声明了文件能力的插件列成启动器中的「快捷识别」结果。完整链路是：

1. 用户在系统文件管理器中复制文件或文件夹。
2. 用户按下 ToolZen 的呼出快捷键。
3. 宿主读取剪贴板中的绝对路径，把这些插件显示为「快捷识别」候选。
4. 用户点击候选卡片，或在剪贴板持有文件时按插件名打开插件。
5. 插件以 enterAction = { code, type: 'file', payload, files } 被打开：type 为 'file'，payload 是绝对路径用 \n 连接的结果，files 是同一批绝对路径的数组。

让插件进入这个候选列表有两种声明方式，任选其一：

{
  "clipboardRules": [
    {
      "name": "批量重命名",
      "pattern": "剪贴板中的文件或文件夹",
      "example": "D:\\photos\\IMG_0001.jpg",
      "action": "打开批量重命名",
      "matchType": "file"
    }
  ]
}

{
  "features": [
    {
      "name": "批量重命名",
      "description": "重命名剪贴板中的文件",
      "code": "rename",
      "cmds": [{ "type": "file" }]
    }
  ]
}

进入动作里有文件不等于拿到文件读写权限。要读取信息或改名，需在 permissions 中声明 file:read / file:write；要读取文件内容（api.file.read），还需额外声明 file:read-content。细节见文件与事件、类型与错误。

config 默认配置#

config 是静态默认值对象，不是任意 JSON 数据。键名由插件自行定义，最多 20 个；值只能是字符串、数字或布尔值，不能放数组、对象、null 或函数。

{
  "config": {
    "theme": "auto",
    "maxItems": 20,
    "showTips": true
  }
}

组件中通过 config prop 读取。用户在客户端修改后的配置会覆盖同名默认值；新增配置项或修改默认值后，应递增 version 并重新构建上传。

homepage 与 screenshots#

homepage 会在商店详情中显示为主页链接。它只能是 http(s) 地址。

screenshots 支持三种地址：

{
  "screenshots": [
    "assets/main.png",
    "/store-assets/word-counter/intro.webp",
    "https://example.com/screenshots/settings.png"
  ]
}

• 包内相对路径必须指向上传包中真实存在的图片文件。
• 上传后，包内路径会自动转换为 /store-packages/<code>/<version>/... 形式的站内地址。
• 图片扩展名须在插件包白名单内，例如 .png、.jpg、.jpeg、.webp、.gif、.svg、.ico。
• 每个地址最多 500 个字符，最多 6 张图。

changelog 更新记录#

每条记录包含以下字段：

记录应按新版本到旧版本排列，并在每次发布新版本时新增一条：

{
  "changelog": [
    { "version": "1.1.0", "date": "2026-08-28", "notes": "新增批量处理和快捷指令" },
    { "version": "1.0.0", "date": "2026-08-01", "notes": "首个版本" }
  ]
}

不是 manifest.json 的字段#

以下字段会出现在商店接口返回或客户端内部数据中，但不能写入插件清单来控制：

不要把这些字段当作插件配置写入 manifest.json；它们会被忽略、覆盖或由服务端拒绝。

发布前检查#

• manifest.json 位于构建后 dist 根目录。
• entry 指向 dist 内真实存在的 .js 或 .mjs 文件。
• code 没有复用其他插件，version 已递增。
• permissions 与实际调用的能力一致。
• features 和 clipboardRules 的正则可以编译，且匹配范围克制。
• screenshots 的包内路径真实存在，changelog 已补充本版本更新内容。
• 上传整个 dist 目录，不上传源码目录、node_modules 或旧的构建产物。

相关页面：动态指令、权限与能力矩阵、构建插件包、到开发者后台上传插件。