Manifest and Operation reference

extension.json drives installation validation and runtime authorization. Declarations must match build outputs, handlers and callers.

API REFERENCE

Browse contracts, signatures, fields and examples. Unspecified defaults are not inferred.

On this page

01Identity and entry points

Use the scaffold manifest as the baseline. Fields below are grouped by role; extension.schema.json and CLI validation define exact constraints.

Field / API	Contract
specVersion / engines.api	Current manifest uses 1.0-draft / 1.
publisher / name / version	Identity is publisher.name; version identifies the extension package.
displayName / description	May use %key% from extension.nls.json.
main	Packaged Node entry, e.g. dist/extension.cjs.
icon / skills	Packaged PNG or theme object; array of Skill directories.
contributes.home	title, webRoot and entry describe the home page.
permissions	Declares capability and scope; not an automatic grant.
authentication.resources	Declares business resources for host-managed authentication.

02Complete Operation declaration

This hello-operation declaration belongs in the manifest operations array. id identifies the callable operation; handler is the backend registration name. They are different fields.

extension.json · one operations entry

{
  "id": "samples.hello-operation.count",
  "handler": "count",
  "title": "统计文本",
  "description": "统计文本",
  "exposeTo": [
    "page",
    "agent"
  ],
  "effect": "read",
  "projectScoped": false,
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string",
        "maxLength": 2000
      }
    },
    "required": [
      "text"
    ],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "characters": {
        "type": "integer"
      },
      "words": {
        "type": "integer"
      },
      "lines": {
        "type": "integer"
      }
    },
    "required": [
      "characters",
      "words",
      "lines"
    ],
    "additionalProperties": false
  },
  "requiredPermissions": []
}

03Operation field contract

Inputs and outputs are validated on each invocation. A write effect cannot be replaced with UI text or a custom confirmation.

Field / API	Contract
id / handler	id prefix matches extension identity; handler matches registration.
title / description	Describe real effects and required input for users and the Agent.
exposeTo	Allowed callers: page and/or agent.
effect	read or write; the host confirms writes.
projectScoped	Whether an invocation binds to a project.
inputSchema / outputSchema	JSON object contracts; specify required and additionalProperties.
requiredPermissions	Declared capabilities required by this operation.
timeoutMs	Optional timeout; use 120000 for interactive sign-in.

Open the complete runnable sample

SDK / CLI 0.1.0-alpha.9 · Contract baseline Compatibility and preview notes · Sample source