# 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 写入路径，不会自动新增未安装应用或外链结果。

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

## 权限声明 (permissions)

权限系统控制插件对敏感 API 的访问。详见 [Permission API 文档](/docs/dev/api/permission)。

**声明格式**

:::TuffCodeBlock{lang="json"}
---
code: |
  "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` | 高 | 屏幕截图 |

## 示例
:::TuffCodeBlock{lang="json"}
---
code: |
  {
    "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)` | 按 [插件开发任务流](../getting-started/plugin-workflow.zh.mdc) 迁移到先导脚本模型 |
| 权限过多被拒 | 仅声明实际需要的权限，首版尽量最小化 |
| features 关键词冲突 | 使用命名空间（如 `todo.` 前缀）避免重复 |