扩展清单与 Operation 参考

extension.json 是安装校验和运行授权的入口。声明必须与构建产物、处理函数和调用界面一致。

API 参考

按章节查看契约、签名、字段与示例；未注明的默认值不作推断。

本页内容

01身份与入口

参考默认脚手架清单。以下字段按职责归类，具体组合与约束以 extension.schema.json 和 CLI 校验为准。

字段 / API	说明
specVersion / engines.api	当前清单使用 1.0-draft / 1。
publisher / name / version	扩展身份为 publisher.name；version 为扩展包版本。
displayName / description	可用 %key% 引用 extension.nls.json。
main	包内 Node 后端入口，例如 dist/extension.cjs。
icon / skills	包内 PNG 或主题对象；Skill 目录数组。
contributes.home	title、webRoot、entry 指向独立主页。
permissions	声明 capability 与 scope；不是自动授权。
authentication.resources	声明宿主管理认证的业务资源。

02完整 Operation 声明

下列操作来自 hello-operation，放入清单 operations 数组。id 是调用标识；handler 是后端 register 使用的名称；两者不是同一字段。

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 字段契约

每次调用都校验输入和输出；写入 effect 不能靠文案或 UI 代替。

字段 / API	说明
id / handler	id 前缀匹配扩展身份；handler 匹配注册名。
title / description	面向用户与 Agent，描述真实效果与所需输入。
exposeTo	page、agent 的允许调用方列表。
effect	read 或 write；写操作由宿主确认。
projectScoped	是否绑定项目上下文。
inputSchema / outputSchema	JSON 对象契约；明确 required 与 additionalProperties。
requiredPermissions	本操作需要的已声明能力。
timeoutMs	可选超时配置；交互登录使用 120000。

打开完整可运行案例

SDK / CLI 0.1.0-alpha.9 · 接口基线兼容性与预览说明 · 案例源码