PI-Desktop Plugin Manifest Structure: Complete JSON Schema and Validation Guide

PI-Desktop uses a rigorously versioned JSON schema—formalized in docs/spec/07-plugins/02-plugin-manifest-schema.md and enforced at load time by the validateManifest function in packages/plugin-sdk/src/index.ts—to strictly define every plugin's metadata, UI assets, contributions, and security policies.

The plugin manifest structure in PI-Desktop serves as the single source of truth for the host application to discover, validate, and execute third-party extensions. Defined primarily through TypeScript interfaces in packages/plugin-sdk/src/types.ts and validated against a frozen specification, the manifest ensures that plugins declare their capabilities explicitly before execution. This declarative approach enables static analysis, secure sandboxing, and predictable lifecycle management across the PI-Desktop ecosystem.

Mandatory Root Fields

Every PI-Desktop plugin manifest must begin with four required fields that establish identity and compatibility.

• schemaVersion: Must be the integer 1. This ensures the host interprets the manifest using the correct validation rules.
• id: A unique reverse-domain identifier matching the pattern ^[a-z0-9]+(\.[a-z0-9_-]+)+$ (e.g., demo.hello or com.example.plugin).
• name: Human-readable plugin name displayed in the UI.
• version: Semantic version string (e.g., 1.2.3) used for dependency resolution and update checks.

The TypeScript type PluginManifestV1 in packages/plugin-sdk/src/types.ts defines these root properties, ensuring compile-time safety for developers and runtime validation for the host.

Optional Configuration Sections

Beyond the mandatory metadata, the plugin manifest structure supports extensive optional blocks that define UI behavior, feature contributions, and resource access.

UI Configuration (PluginUiConfig)

The ui object declares panel dimensions and entry points:

• panel: Relative path to the HTML renderer entry (e.g., renderer/index.html).
• width and height: Default panel dimensions in pixels.
• title: Localized string map (e.g., { "en": "Sample", "zh-CN": "示例" }).

Contribution Points (PluginContributes)

The contributes field uses the PluginContributes type to register extensions:

• commands: Palette commands with id and title.
• views: Sidebar or panel views with icon, entry, and order.
• agentTools, skills, services, themes, mcpServers, busTopics, settings, and sessionSources: Specialized integration points for the PI-Desktop agent system and event bus.

Security Policies

PI-Desktop implements a capability-based security model where permissions must be explicitly declared:

• permissions: Array of PluginPermission enum values (e.g., ui.panel, fs.read, net.fetch).
• fs: File-system policy using PluginFsPolicy/PluginFsRule to define read, write, and delete scopes relative to workspace or global roots. Rules must use relative globs; the own modifier is restricted to delete operations.
• net: Network egress policy listing allowed domains under domains. Entries must be bare hostnames with optional *. wildcards (e.g., api.example.com, *.cdn.org).

Manifest Validation Pipeline

At load time, PI-Desktop invokes validateManifest (located at line 803 in packages/plugin-sdk/src/index.ts) to enforce schema compliance. According to the source code, this routine performs the following checks:

1. Schema Version Verification: Confirms schemaVersion equals 1.
2. Identity Validation: Ensures id conforms to the reverse-domain regex and version follows semantic versioning.
3. Path Sanitization: Rejects absolute paths or paths containing .. sequences in any file reference.
4. Permission Consistency: Validates that declared contributions have matching permissions (e.g., a views contribution requires ui.view permission).
5. Policy Syntax: Verifies fs rules contain only relative globs and net.domains entries lack protocol prefixes or path components.

If validation fails, the manifest is rejected and the plugin is not loaded, preventing insecure or malformed code from executing in the PI-Desktop environment.

Complete Manifest Examples

Minimal Valid Manifest

The simplest valid PI-Desktop plugin defines only the required fields and a single command contribution:

{
  "schemaVersion": 1,
  "id": "demo.hello",
  "name": "Hello",
  "version": "0.1.0",
  "main": "main.js",
  "ui": { "panel": "renderer/index.html" },
  "contributes": {
    "commands": [
      { "id": "hello.open", "title": "Open Hello Panel" }
    ]
  },
  "permissions": ["ui.panel"]
}

Manifest with Localization and Views

This example demonstrates localized UI strings and a view contribution:

{
  "schemaVersion": 1,
  "id": "demo.sample",
  "name": "Sample Plugin",
  "version": "1.2.3",
  "main": "main.js",
  "ui": {
    "panel": "renderer/panel.html",
    "width": 400,
    "height": 300,
    "title": { "en": "Sample", "zh-CN": "示例" }
  },
  "contributes": {
    "views": [
      {
        "id": "sampleView",
        "title": { "en": "Sample View", "zh-CN": "示例视图" },
        "icon": "sparkles",
        "entry": "views/sample.html",
        "order": 5
      }
    ]
  },
  "permissions": ["ui.panel", "ui.view"]
}

Manifest with Security Policies

This advanced example configures restricted file-system and network access:

{
  "schemaVersion": 1,
  "id": "demo.security",
  "name": "Secure Plugin",
  "version": "0.0.1",
  "main": "main.js",
  "permissions": ["fs.read", "net.fetch"],
  "fs": {
    "read": { "root": "workspace", "scope": ["docs/**", "*.md"] }
  },
  "net": {
    "domains": ["api.example.com", "*.example.org"]
  }
}

Reference Implementation Files

The PI-Desktop repository contains several critical files that define and implement the plugin manifest structure:

• docs/spec/07-plugins/02-plugin-manifest-schema.md: The authoritative specification document describing the JSON schema, TypeScript types, and validation rules.
• packages/plugin-sdk/src/index.ts: Contains the validateManifest function (line 803) used for runtime schema enforcement.
• packages/plugin-sdk/src/types.ts: Central TypeScript definitions for PluginManifest, PluginPermission, PluginFsPolicy, and related interfaces.
• examples/plugins/hello/manifest.json: Real-world example demonstrating UI configuration, commands, agent tools, skills, themes, and permissions.
• packages/plugin-devkit/src/templates.ts: Devkit helper that generates valid manifest.json files when scaffolding new plugins.

Summary

• PI-Desktop's plugin manifest structure requires a schemaVersion of 1 along with mandatory fields id, name, and version formatted according to strict patterns defined in packages/plugin-sdk/src/types.ts.
• The validateManifest function at line 803 of packages/plugin-sdk/src/index.ts enforces schema compliance, path sanitization, and permission consistency at load time.
• Optional sections include ui for panel configuration, contributes for feature registration (commands, views, agent tools), and security policies for fs and net access.
• All file paths must be relative; absolute paths and .. traversal sequences are explicitly rejected during validation.
• The complete specification is documented in docs/spec/07-plugins/02-plugin-manifest-schema.md.

Frequently Asked Questions

What is the minimum required schema for a PI-Desktop plugin manifest?

Every manifest must include schemaVersion (set to 1), a unique id matching the reverse-domain pattern ^[a-z0-9]+(\.[a-z0-9_-]+)+$, a name, and a version. As implemented in packages/plugin-sdk/src/index.ts, the validateManifest function rejects any manifest missing these fields or using an unsupported schema version.

How does PI-Desktop validate plugin permissions against contributions?

The validation routine checks that every contribution type declared in the contributes object has a corresponding entry in the permissions array. For example, if you declare a views contribution, the manifest must include the ui.view permission. This enforcement occurs in packages/plugin-sdk/src/index.ts to ensure plugins cannot access host capabilities without explicit authorization.

Can a PI-Desktop plugin access the file system or network by default?

No. Access to fs.* and net.fetch capabilities is deny-by-default. Developers must explicitly request these permissions and define restrictive policies: fs rules must specify relative glob patterns under a workspace or global root, while net.domains must list specific bare hostnames. Absolute paths and protocol-prefixed URLs are rejected during validation.

Where is the plugin manifest schema formally documented?

The canonical specification resides in docs/spec/07-plugins/02-plugin-manifest-schema.md within the PI-Desktop repository. This document defines the JSON structure, TypeScript interfaces, and validation rules. Developers can also reference examples/plugins/hello/manifest.json for a comprehensive real-world implementation and use packages/plugin-devkit/src/templates.ts to generate compliant manifests during plugin scaffolding.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}