开发文档插件开发

manifest 与权限

插件的全部声明都在 manifest.json:它是什么、界面在哪、有哪些命令、要哪些权限。

示例

JSON
{
  "schema": 2,
  "key": "json-tools",
  "name": "JSON 工坊",
  "version": "1.0.0",
  "minHost": "2.2.0",
  "description": "格式化、压缩和稳定排序 JSON。",
  "icon": "{}",
  "ui": { "entry": "ui/index.html", "mode": "iframe" },
  "permissions": ["clipboard.write", "notify"],
  "commands": [
    {
      "id": "transform",
      "title": "转换 JSON",
      "description": "校验 JSON,并按选择格式化、压缩或按键名排序。",
      "handler": "scripts/transform.mjs",
      "params": {
        "type": "object",
        "properties": {
          "text":   { "type": "string", "description": "待处理的 JSON 文本" },
          "action": { "type": "string", "enum": ["format", "minify", "sort"] }
        },
        "required": ["text"]
      }
    }
  ],
  "contributes": { "tool": { "category": "dev" } }
}

字段

字段 说明
schema 固定 2。
key 全局唯一,小写字母、数字、中划线,建后不能改。
name / description 市场里显示的名称和一句话说明。
version 语义化版本,每次上传要高于上一版。
minHost 最低桌面端版本,低于它的客户端不会安装这一版。使用 __kit__ SDK 时填 2.2.0。
icon / cover emoji 图标;cover 是包内封面图路径,不填自动生成。
ui 界面入口,mode 固定 iframe。纯命令插件可以不写。
permissions 权限数组,见下表,安装时逐条展示给用户。
commands[] 命令。带 handler 的命令会注册为 AI 工具,详见 命令脚本。
contributes.tool.category 分类:efficiency / media / dev / ai / fun。
contributes 其他 skills(给 AI 注入提示词)、island / panel(需对应 overlay 权限)、shortcuts(需 shortcuts 权限)。

权限

权限能力风险
clipboard.read / clipboard.write读 / 写剪贴板中
notifyToast 通知低
ai.chat调用 AI 模型(耗用户算力)中
image.generate / video.generateAI 生图 / 生视频(耗用户算力)中
web.search联网搜索(耗用户算力)中
storage.local本机 KV,每插件 5MB低
storage.cloud账号云端 KV中
user.profile昵称与头像(不含手机号和 token)中
fs.pick读写用户主动选择的文件中
fs.save弹出另存为对话框低
fs.workspace读写工作区文件高
shell.reveal在访达 / 资源管理器中显示文件低
shell.open用默认浏览器打开链接低
shell.openPath用系统默认方式打开本机文件或应用高
capture.screen截取当前屏幕中
media.camera / media.microphone摄像头 / 麦克风高
overlay.island / overlay.panel灵动岛 / 悬浮面板中
shortcuts注册全局快捷键中
system.stats读取 CPU、内存、电量、网速低
system.media控制音乐播放中
ocr识别图片文字(本机优先,不可用时交官方云端)低
process在用户电脑上运行程序高
net.fetch:<域名>访问指定域名,每个域名单独声明中
  • 界面 bridge 按权限拦截:已安装插件调用未声明的能力直接报错;草稿只告警,方便开发。
  • 摄像头、麦克风 未声明时宿主拒绝授权。
  • 命令脚本不受权限限制,它运行在完整的 Node 环境里。脚本用到网络、文件或子进程时,仍要如实声明 net.fetch:<域名>、process 等权限,供用户安装时确认、审核时核对。
  • 含高风险权限的插件上架时要写用途说明,审核员会核对代码。

数据存哪里

方式 权限 说明
本地 KV storage.local 每插件 5MB,重装不丢。
云端 KV storage.cloud 按用户和插件隔离,单条 64KB、总共 1MB、每分钟 60 次。插件上架后才能写,草稿期先用本地 KV。
自己的后端 net.fetch:<域名> 安装弹窗会展示访问的域名,平台不为其数据负责。