SDK 清单 Schema

2026-11-15

本篇是 biglazycat 清单的字段级参考;创建工程的完整流程见「插件开发流程」。

清单字段(package.json 的 biglazycat)

清单是 package.json 里的 biglazycat 对象,未知字段一律拒绝。顶层字段:

字段 类型 必填 说明
apiVersion 1 是 SDK 接口主版本,当前固定为 1,与宿主不符报 API_MISMATCH
minimumApiRevision 整数 否 要求的最低 API 修订;宿主低于该修订时拒绝安装
displayName string 是 显示名,1–200 字符
description string 否 插件描述
main string 否 后台入口相对路径;不得以 / 开头、不得含 ..、\ 与 :;纯页面插件可省略
mainView string 否 主页面 view id,须匹配 ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$
settingsView string 否 设置页 view id
platforms string[] 是 目标平台,取值 windows/amd64、windows/arm64、darwin/amd64、darwin/arm64、linux/amd64、linux/arm64,1–256 项
activation string[] 否 自动激活事件,取值 startup、workspace.opened、document.committed
dependencies object[] 否 运行期插件服务依赖,每项含 plugin、service、version、optional,0–256 项
contributes object 是 能力贡献点,见下表

宿主在清单 Schema 之外还校验平台、engines 引擎版本、路径存在性、引用有效性与重复 ID。

contributes 贡献点

键 字段(加粗为必填) 说明
commands id、title、description、contexts、aiCallable、externalEffect、visibility、inputSchema 命令。contexts 取值 workspace、editor.document、editor.selection、resource,声明命令适用的上下文;aiCallable 为 true 才对外部 AI 开放;externalEffect 标记有外部副作用;visibility: "internal"(修订 2)把命令从命令面板、快捷键与工具栏入口隐藏,仅页面可调用,aiCallable 不受影响;inputSchema 是受限 JSON Schema,支持 type、description、properties、required、additionalProperties、items、enum、minimum、maximum、minLength、maxLength、minItems、maxItems
views id、title、entry、defaultLocation、route、multiple、commandPalette 页面。entry 指向构建产物中的 HTML 文件;defaultLocation 取值 tab、panel、window;multiple 允许同时开多个实例;commandPalette: false(修订 2)避免页面与打开命令在命令面板重复出现;route 以 / 开头
menus location、command 菜单项。location 取值 editor.selection、editor.document、resource、toolbar;command 引用已声明命令 id
services id、version、methods 对其他插件提供的服务;methods 为 1–256 个方法名
providers id、contract、version、service 导出提供者;contract 当前仅 export.text,version 固定 1,service 指向已声明服务
editors id、title、extensions、view 自定义文件编辑器;extensions 形如 .catnote,1–256 项;view 指向已声明页面
schedules id、command、intervalSeconds、catchUp 定时任务;intervalSeconds 取 10–31536000 秒;catchUp 取值 skip、once

服务依赖声明

dependencies 与 npm dependencies 无关,声明运行期要调用的其他插件服务:

"dependencies": [
  { "plugin": "@scope/text-tools", "service": "text", "version": "^1.0.0", "optional": true }
]

必需依赖缺失、版本不符或依赖环在启用/启动时被拒绝;可选依赖不会自动启动不兼容版本,调用方需自行处理不可用错误。