开发文档插件开发
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 | 读 / 写剪贴板 | 中 |
notify | Toast 通知 | 低 |
ai.chat | 调用 AI 模型(耗用户算力) | 中 |
image.generate / video.generate | AI 生图 / 生视频(耗用户算力) | 中 |
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:<域名> |
安装弹窗会展示访问的域名,平台不为其数据负责。 |
这篇文档有问题?匿名提交,不记录账号。