Docs/Manifest Reference

Manifest Reference

Universal Developer

Manifest Reference

Schema

FieldTypeRequiredDescription
idstring✓Reverse-domain unique ID
namestring or map✓Display name, supports locales
descriptionstringShort summary
versionstring✓SemVer
sdkapinumberRecommendedSDK API version, format YYMMDD (e.g., 260626)
categorystringConditionalCategory id synced with Nexus (e.g., utilities, productivity) (required when sdkapi >= 260114)
mainstring✓Prelude script entry, usually index.js
entrystringLegacyLegacy init entry; do not use for new plugins
preloadstringRenderer preload file
dev.enablebooleanEnable hot reload
permissionsobjectPermission declarations, see below
permissionReasonsobjectReasons for permissions
features[].acceptedInputTypesstringtext, image, files, html
featuresobjectCoreBox commands, widgets, workflow nodes
semanticAliasesobjectSemantic alias declarations with marker App Semantic Alias Catalog / 应用语义别名目录 (recommended with sdkapi >= 260626)

SDK API Version (sdkapi)

The sdkapi field declares the SDK API version the plugin is compatible with. Format is YYMMDD (year-month-day).

  • Current version: 260626 (2026-06-26)
  • Supported list: 251212, 260114, 260121, 260215, 260225, 260228, 260428, 260615, 260626
  • Not declared, invalid, unsupported, or below 251212: Blocked by runtime with SDKAPI_BLOCKED
  • 251212 ~ 260113: Full permission enforcement enabled
  • Equal to or above 260114: Requires category for UI grouping (in addition to 251212 baseline)
  • Equal to or above 260215: Can use plugin SQLite SDK (usePluginSqlite)
  • Equal to or above 260228: Plugin capability auth baseline is enabled
  • 260428: Supported marker; no additional runtime gate is introduced
  • 260615: Supported marker; no additional runtime gate is introduced
  • 260626: Current recommended marker; exposes SemanticAliasSDK and semanticAliases declarations without adding a SQLite schema change or extra runtime gate

New plugins should always declare the latest sdkapi version for complete permission protection.

Semantic Aliases (semanticAliases)

Recognition marker: App Semantic Alias Catalog / 应用语义别名目录.

semanticAliases declares discoverability terms for a plugin, feature, or provider: short aliases, category terms, Chinese/English synonyms, and common abbreviations. It is manifest metadata in V1 so developers can keep aliases in one structure; runtime integration should still write through existing features[].keywords, searchTokens, or Search Provider paths. It does not automatically add uninstalled apps or external website results.

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

Permissions

The permission system controls plugin access to sensitive APIs. See Permission API docs for details.

Declaration Format

EXAMPLE.JSON
"permissions": {
  "required": ["clipboard.read", "network.internet"],
  "optional": ["storage.shared"]
},
"permissionReasons": {
  "clipboard.read": "Read text from clipboard for translation",
  "network.internet": "Connect to translation API"
}

Available Permissions

Permission IDRiskDescription
fs.readMediumRead files
fs.writeHighWrite files
fs.executeHighExecute files
clipboard.readMediumRead clipboard
clipboard.writeLowWrite clipboard
network.localLowLocal network
network.internetMediumInternet access
network.downloadMediumDownload files
system.shellHighExecute commands
system.notificationLowSystem notifications
system.trayMediumSystem tray
intelligence.basicLowBasic intelligence
intelligence.contextMediumContext sessions with history and memories
intelligence.adminHighAdmin intelligence
intelligence.agentsHighIntelligence agents
storage.pluginLowPlugin storage (auto-granted)
storage.sharedMediumShared storage
storage.sqliteMediumPlugin SQLite database access
window.createLowCreate windows (auto-granted)
window.captureHighScreen capture
account.readMediumRead the account's profile, plan and usage
search.root-resultsHighPush or update CoreBox root results

Example

EXAMPLE.JSON
{
  "id": "com.tuff.todo",
  "name": {
    "default": "Todo",
    "zh-CN": "Text"
  },
  "description": "Capture and sync todos",
  "version": "1.3.0",
  "sdkapi": 260626,
  "category": "utilities",
  "main": "index.js",
  "features": [
    {
      "id": "todo.new",
      "name": "Create Todo",
      "desc": "Create a local todo from input text",
      "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": "Read todo content from clipboard",
    "storage.sqlite": "Store todo data in local SQLite"
  }
}

Validation Checklist

  • id is required and uses a lowercase reverse-domain identifier with at least three safe segments.
  • name is a lowercase slug and version is strict SemVer.
  • sdkapi must be a supported marker; category is required at the documented SDK threshold.
  • Prelude plugins use main: "index.js"; UI-only plugins may omit main.
  • permissions uses { required: string[], optional: string[] } and every id must exist in the permission registry.
  • Packaged builds disable dev.enable/dev.source, clear the dev address, and bind every regular file through _files.
  • Nexus rejects unsafe archive paths/types, duplicate or case-colliding entries, identity/version mismatches, and package limits before upload.

Frequent Issues

IssueFix
Missing main on a Prelude pluginSet main to index.js and ensure the file exists; UI-only plugins do not need a Prelude entry.
Still using entry / init(ctx)Migrate to the Prelude model through Plugin Development Workflow.
Excessive permissionsRequest only what you truly need, especially for v1.
Keyword collisionsNamespace features like todo.* to avoid conflicts.