Manifest 参考

结构

字段	类型	必填	说明
`id`	string	是	反向域名，唯一标识
`name`	string	是	显示名称，支持本地化
`description`	string	否	简短介绍
`version`	string	是	语义化版本
`sdkapi`	number	推荐	SDK API 版本，格式 YYMMDD（如 260626）
`category`	string	条件必填	分类 ID（与 Nexus 同步，如 `utilities`、`productivity`），用于 UI 分组（`sdkapi >= 260114` 必填）
`main`	string	是	先导脚本入口，通常为 `index.js`
`entry`	string	旧字段	旧版 init 入口；新插件不要继续使用
`preload`	string	否	渲染层预加载脚本
`dev.enable`	boolean	否	开发模式热重载
`permissions`	object	否	权限声明，见下方详情
`permissionReasons`	object	否	权限用途说明
`features[].acceptedInputTypes`	string	否	`text`、`image`、`files`、`html`
`features`	object	否	CoreBox 指令、Widget、Workflow 节点
`semanticAliases`	object	否	语义别名声明，识别标记为 `App Semantic Alias Catalog / 应用语义别名目录`（建议 `sdkapi >= 260626`）

SDK API 版本 (sdkapi)

sdkapi 字段用于声明插件兼容的 SDK API 版本。格式为 YYMMDD（年月日）。

当前版本: 260626 (2026-06-26)
支持列表: 251212、260114、260121、260215、260225、260228、260428、260615、260626
未声明、非法、未列入支持列表或低于 251212: 运行时直接以 SDKAPI_BLOCKED 阻断
251212 ~ 260113: 启用完整权限校验
等于或高于 260114: 在 251212 基础上，要求声明 category（用于 UI 分组）
等于或高于 260215: 可使用插件 SQLite SDK（usePluginSqlite）
等于或高于 260228: 启用插件 capability auth 基线
260428: 受支持 marker，不新增额外运行时门槛
260615: 受支持 marker，不新增额外运行时门槛
260626: 当前推荐 marker，开放 SemanticAliasSDK 与 semanticAliases 声明，不新增 SQLite schema 或额外运行时门槛

自 260114 起：建议补充 category 以参与 UI 分组展示；当 sdkapi >= 260114 且缺失 category 时，插件将被拒绝启动并在列表中标记问题。

建议新插件始终声明最新的 sdkapi 版本以获得完整的权限保护。

语义别名声明 (semanticAliases)

识别标记：App Semantic Alias Catalog / 应用语义别名目录。

semanticAliases 用于声明插件、Feature 或 Provider 的可发现语义词，例如短别名、类别词、中文/英文同义词和常见缩写。它是 manifest metadata，首版用于让开发者用统一结构维护别名；真实运行时接入仍应通过现有 features[].keywords、searchTokens 或 Search Provider 写入路径，不会自动新增未安装应用或外链结果。

{
  "sdkapi": 260626,
  "semanticAliases": [
    {
      "id": "todo.create",
      "target": "todo.new",
      "label": "Create Todo",
      "aliases": ["todo", "task"],
      "categories": ["office", "办公"],
      "synonyms": ["待办", "任务"]
    }
  ]
}

权限声明 (permissions)

权限系统控制插件对敏感 API 的访问。详见 Permission API 文档。

声明格式

"permissions": {
  "required": ["clipboard.read", "network.internet"],
  "optional": ["storage.shared"]
},
"permissionReasons": {
  "clipboard.read": "读取剪贴板中的待翻译文本",
  "network.internet": "连接翻译服务 API"
}

可用权限

权限 ID	风险	说明
`fs.read`	中	读取文件
`fs.write`	高	写入文件
`fs.execute`	高	执行文件
`clipboard.read`	中	读取剪贴板
`clipboard.write`	低	写入剪贴板（自动授予）
`network.local`	低	本地网络
`network.internet`	中	互联网访问
`network.download`	中	下载文件
`system.shell`	高	执行命令
`system.notification`	低	系统通知
`system.tray`	中	托盘交互
`intelligence.basic`	低	基础智能能力
`intelligence.admin`	高	管理级智能能力
`intelligence.agents`	高	智能体
`storage.plugin`	低	插件存储（自动授予）
`storage.shared`	中	共享存储
`storage.sqlite`	中	插件 SQLite 数据库访问
`window.create`	低	创建窗口（自动授予）
`window.capture`	高	屏幕截图

示例

{
  "id": "com.tuff.todo",
  "name": {
    "default": "待办",
    "en": "Todo"
  },
  "description": "快速记录与同步待办",
  "version": "1.3.0",
  "sdkapi": 260626,
  "category": "utilities",
  "main": "index.js",
  "features": [
    {
      "id": "todo.new",
      "name": "快速创建待办",
      "desc": "从输入文本创建本地待办",
      "keywords": ["todo", "task", "待办", "任务"],
      "push": true,
      "acceptedInputTypes": ["text", "files"],
      "commands": [
        { "type": "over", "value": ["todo", "task"] }
      ]
    }
  ],
  "semanticAliases": [
    {
      "id": "todo.create",
      "target": "todo.new",
      "aliases": ["todo", "task"],
      "categories": ["office", "办公"],
      "synonyms": ["待办", "任务"]
    }
  ],
  "permissions": {
    "required": ["clipboard.read", "storage.sqlite"],
    "optional": ["storage.shared"]
  },
  "permissionReasons": {
    "clipboard.read": "读取剪贴板中的待办内容",
    "storage.sqlite": "将待办数据存储到本地 SQLite"
  }
}

校验

id 为必填，使用至少三段的全小写反向域名标识。
name 使用全小写 slug，version 使用严格 SemVer。
sdkapi 必须是受支持 marker；达到文档门槛后必须声明 category。
Prelude 插件使用 main: "index.js"；纯 UI 插件可以省略 main。
permissions 使用 { required: string[], optional: string[] }，每个 id 必须存在于权限注册表。
打包态必须关闭 dev.enable/dev.source、清空 dev address，并用 _files 绑定所有普通文件。
Nexus 在上传前拒绝危险归档路径/类型、重复或大小写冲突条目、身份/版本不一致和超限包。

常见错误

情况	解决办法
Prelude 插件未填写 main	指定 `index.js` 并确保文件存在；纯 UI 插件无需 Prelude 入口
继续使用 `entry` / `init(ctx)`	按插件开发任务流迁移到先导脚本模型
权限过多被拒	仅声明实际需要的权限，首版尽量最小化
features 关键词冲突	使用命名空间（如 `todo.` 前缀）避免重复