Operit Plugin Development

Skill manifest: skill.manifest.json. The manifest declares this SKILL.md as the sole always-loaded startup prompt and maps plugin tasks to the on-demand documents under docs/.

Use this document as the entry point for local Operit plugin development rules. It summarizes the official plugin tutorial at https://operit.app/#/guide/plugin and directs each task to the required detailed specification.

Development Guides

• Script Packages: JavaScript and TypeScript script-package discovery, metadata, exports, completion, typing, tsconfig, and verification.
• ToolPkg Structure: manifest, compiled paths, subpackages, resources, and package verification.
• ToolPkg Hooks And UI: main, Compose DSL UI, lifecycle hooks, message/XML/input plugins, and prompt hooks.
• Build And Debug: compilation, runtime execution, ToolPkg installation, logs, and diagnostic paths.
• Coverage Matrix: official tutorial topics, supported plugin forms, and local documentation coverage.

Source Of Truth

When implementing or changing a plugin, inspect the installed development package before relying on a remembered API shape:

• docs/SCRIPT_DEV_GUIDE.md: script package conventions.
• docs/TOOLPKG_FORMAT_GUIDE.md: ToolPkg manifest and package layout.
• examples/quick_start.ts: minimal script package pattern.
• examples/types/index.d.ts: global host API entry point.
• examples/types/core.d.ts: complete(...), exports, and core declarations.
• examples/types/tool-types.d.ts: tool-name and return-type mappings.
• examples/types/results.d.ts: result structures for file, network, UI, workflow, and chat APIs.

The installed type declarations are authoritative for Tools, toolCall(...), ToolPkg, Compose DSL, and all host API parameters and return values.

Choose The Package Form

Select the smallest package form that satisfies the feature:

Start with a script package for a single tool. Use ToolPkg only when the package needs package-level composition, resources, UI, or registrations.

Script Package Contract

A script package is discovered and invoked through three aligned elements:

1. METADATA declares the package and its tools.
2. The implementation defines a function for each declared tool.
3. exports.<toolName> = <toolName> exposes that implementation to the host.

METADATA.tools[].name, the function name, and the export name must be identical. Keep parameter names, types, required flags, and localized descriptions synchronized with the implementation.

Use complete(...) to deliver the final host result. A JavaScript return value alone is not the script package result contract.

/*
METADATA
{
  "name": "example_package",
  "category": "Utility",
  "tools": [
    {
      "name": "example_tool",
      "description": {
        "zh": "示例工具",
        "en": "Example tool"
      },
      "parameters": [
        {
          "name": "value",
          "description": {
            "zh": "输入值",
            "en": "Input value"
          },
          "type": "string",
          "required": true
        }
      ]
    }
  ]
}
*/

async function example_tool(params) {
  try {
    const value = String(params.value || "");
    complete({ success: true, data: { value } });
  } catch (error) {
    complete({
      success: false,
      message: String(error && error.message ? error.message : error),
    });
  }
}

exports.example_tool = example_tool;

Script Package Conventions

• Declare every callable tool in METADATA; implementation functions are not exposed automatically.
• Validate required parameters before using them and report validation failures with complete({ success: false, message }).
• Wrap asynchronous tool work in try/catch and return one structured terminal result.
• Use success consistently. Include a stable data, message, or domain-specific result field as appropriate.
• Prefer host capabilities declared in examples/types over browser-only assumptions or undocumented APIs.
• Keep tool functions focused. Split independent tool capabilities into separate exports rather than a single multipurpose entry point.

TypeScript Conventions

For TypeScript scripts, reference the installed host declarations so that the editor and compiler can resolve global APIs:

/// <reference path="./types/index.d.ts" />

Adjust the relative path to the local type directory used by the project. Compile TypeScript before runtime testing. Keep tsconfig.json output paths aligned with the script or ToolPkg paths consumed at runtime.

Use the declared parameter and result types whenever they are available. Do not hand-write incompatible substitutes for host result objects or tool-call shapes.

ToolPkg Contract

A ToolPkg separates package description, registration, tools, UI, and resources:

my_toolpkg/
|-- manifest.json
|-- dist/
|   |-- main.js
|   `-- packages/
|       `-- example_tools.js
|-- ui/
|   `-- example_panel/
|       `-- index.ui.js
`-- resources/
    `-- example/
        `-- asset.zip

manifest.json

The manifest describes package structure. Core fields are:

• schema_version: manifest format version; current examples use 1.
• toolpkg_id: stable, unique package identifier. Do not change it casually after distribution.
• version: package version; use semantic versioning.
• main: compiled main-entry path.
• subpackages: tool package list, including each id, entry, and default-enabled state.
• resources: packaged resource list for ToolPkg.readResource(...).
• display_name and description: user-facing localized text when applicable.

Keep every manifest path synchronized with compiler output and committed package files. The manifest describes structure only; it does not contain executable hook logic.

main And Subpackages

• main.ts or main.js is the registration entry point for UI and hooks such as ToolPkg.registerAppLifecycleHook(...), message-processing plugins, XML-render plugins, and input-menu plugins.
• Each subpackages[].entry module provides the actual callable tool functions.
• ui/ contains Compose DSL UI modules.
• resources/ contains assets distributed with the package.

Do not place a subpackage's public tool implementation in main merely because the package has a main entry. Keep registration and tool behavior separated.

Implementation Workflow

1. Identify whether the requested feature is a script package, a TypeScript project, or a ToolPkg.
2. Read the nearest matching example and relevant declarations before coding.
3. Define or update metadata, manifest fields, function signatures, exports, and output paths together.
4. Implement only the requested behavior with explicit parameter validation and structured completion results.
5. Compile TypeScript when the project contains TypeScript source.
6. Verify that declared tools, exports, generated files, manifest paths, and registrations agree.
7. Test the smallest affected surface and inspect the relevant runtime logs when device debugging is in scope.

Build And Debug

The source repository provides distinct paths for ordinary script packages and ToolPkg packages:

• Compile TypeScript: npx tsc or npx tsc -p <path-to-tsconfig.json>.
• Validate a normal JavaScript script function: tools/execute_js.bat <script.js> <exported_function> <json-arguments>.
• Install and debug a ToolPkg: tools/debug_toolpkg.bat <toolpkg-directory>.

tools/execute_js.bat targets a specific exported script function. tools/debug_toolpkg.bat validates the manifest, packages the directory or .toolpkg, installs it for debugging, and captures package-registration logs.

Useful log tags:

• Script packages: ScriptExecutionReceiver, JsEngine.
• ToolPkg packages: ToolPkg, PackageManager, ToolPkgDebugInstallReceiver.

For application-internal AI collaboration, follow the locally installed SandboxPackage_DEV materials and do not assume that full-source-repository or ADB commands are part of the default workflow.

Pre-Delivery Checklist

• The selected package form is no more complex than the feature requires.
• All host API calls match the installed declaration files.
• Every METADATA tool name matches its function and exports entry.
• Every tool returns a structured complete(...) result on success and failure.
• TypeScript compilation succeeds when TypeScript sources changed.
• ToolPkg manifest.json IDs, versions, entries, resources, and compiled output paths are valid.
• Hook and UI registrations are in main, while callable tools remain in subpackages.
• Debug output and relevant logs have been checked for the changed execution path.

Reference

Official tutorial: https://operit.app/#/guide/plugin

Last refreshed from the tutorial: 2026-07-29 13:34:02 Asia/Shanghai.