actions

contributes.actions 决定用户在动作选择器里能看到什么。后台用相同的 ID 注册处理函数，接入过程见开发动作。

#示例

{
  "apiVersion": 1,
  "id": "example.text-toolkit",
  "name": "文本处理工具",
  "version": "1.0.0",
  "description": "文本处理工具教学示例",
  "hostPlatforms": [
    "windows",
    "macos",
    "linux"
  ],
  "main": "index.js",
  "permissions": [],
  "contributes": {
    "actions": [
      {
        "id": "split",
        "title": "整理文本",
        "description": "按分隔符拆分，去除空白项，最多返回前 100 项",
        "argsSchema": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string",
              "title": "文本",
              "format": "multiline",
              "maxLength": 2000,
              "titleKey": "actions.split.argsSchema.properties.text.title"
            },
            "separator": {
              "type": "string",
              "title": "分隔符",
              "default": ",",
              "maxLength": 8,
              "titleKey": "actions.split.argsSchema.properties.separator.title"
            }
          },
          "required": [
            "text"
          ],
          "additionalProperties": false
        },
        "outputSchema": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 100
            },
            "count": {
              "type": "integer"
            }
          },
          "required": [
            "items",
            "count"
          ],
          "additionalProperties": false
        },
        "titleKey": "actions.split.title",
        "descriptionKey": "actions.split.description"
      }
    ]
  },
  "i18n": {
    "defaultLocale": "zh-CN",
    "resources": {
      "zh-CN": "locales/zh-CN.json",
      "en-US": "locales/en-US.json"
    }
  },
  "nameKey": "plugin.name",
  "descriptionKey": "plugin.description"
}

#Action

清单位置：manifest.contributes.actions[]。

#Action.id

string · 必填

动作 ID，在本插件内唯一，最多 128 个字符。后台使用 actions[id] 注册。

#Action.title

string · 必填

用户看到的动作名称，最多 128 个字符。

#Action.description

string · 可选

解释动作做什么，以及使用前需要哪些条件，最多 240 个字符。

#Action.hostPlatforms

string[] · 可选

动作支持的桌面宿主系统。必须是顶层 Manifest.hostPlatforms 的非空、不重复子集；省略时继承插件列表。宿主隐藏不支持的动作及引用这些动作的预设，并在按钮和流程调用入口拒绝执行。已有配置保持原引用，不自动删除。此字段不授予任何系统能力权限。

#Action.icon

string · 可选

动作的图标库 ID 或包内 SVG 路径，见插件图标与资源。

#Action.category

string · 可选

引用 categories 中的分类 ID。

#Action.argsSchema

Schema · 可选

输入参数的描述，根 type 为 object。省略时只接收空参数对象。

顶层字符串参数可声明 dynamicOptions: true，通过后台 actionOptions 返回搜索候选项，见动态候选项。

#Action.outputSchema

Schema · 可选

返回值的描述。可使用任何支持的 Schema 类型；流程据此提供结果字段提示。

#Action.execution

ActionExecution · 可选

所有宿主入口调用这个动作时的等待时间和资源调度设置。

#ActionExecution

清单位置：manifest.contributes.actions[].execution 或 manifest.contributes.widgets[].instanceActions[].execution。

#ActionExecution.timeoutMs

integer · 可选

宿主等待动作响应的时间，范围为 100–300000 毫秒。省略时使用宿主请求时间，默认 10000 毫秒。

#ActionExecution.concurrency

"serial" | "parallel" · 可选

默认为 serial，同插件的动作使用串行队列。选择 parallel 时，动作可以重叠执行，并且不能再设置 resource 或 hostResource。

#ActionExecution.resource

string · 可选

插件内的队列名称，最多 80 个字符。操作同一资源的动作使用相同名称；省略时使用 default 队列。

#ActionExecution.hostResource

"desktop" | "audio" · 可选

多个插件共享的宿主资源队列。desktop 用于桌面操作，audio 用于音量操作，需要同时声明对应能力权限。它与 resource 二选一。

#Category

清单位置：manifest.contributes.categories[]。动作和按钮预设共用此目录，分别填写自己的 category，两者可属于不同分类。

{
  "categories": [
    { "id": "volume", "title": "音量控制", "icon": "host:outline/VolumeHigh", "group": "audio" }
  ],
  "actions": [
    { "id": "increase", "title": "增大音量", "category": "volume" }
  ]
}

分类身份由插件 ID 和分类 ID 共同确定。分类标题只用于展示和搜索；跨插件同名分类不会自动合并。

#Category.id

string · 必填

分类 ID，使用小写字母开头，可包含小写字母、数字和 -，最多 64 个字符。

#Category.title

string · 必填

选择器显示的分类名称，最多 80 个字符。

#Category.icon

string · 可选

分类的图标库 ID 或包内 SVG 路径，见插件图标与资源。

按钮、流程和小组件实例动作使用同一个宿主执行器。排队取消不会发送动作；已发送动作不承诺强制取消。响应超时会报告失败，但资源一直保留到迟到响应或插件退出；永不响应的插件需要停止或重启。

#显式开放数值控制

#Action.valueControl

{ parameter: string, state?: { sourceId: string, path?: string[], availabilityPath?: string[] } } · 可选

声明此动作是可供数值控件使用的设置接口。parameter 指向 argsSchema 中一个顶层 number/integer 参数，不允许枚举或未定义参数。只有显式声明的动作才出现在控件目标列表，普通动作继续按原方式使用。应声明“设置到某个数值”的动作，不要将增减步进、请求超时等辅助参数标记为控制目标。

state 是可选的默认当前值来源，属于同一个插件；sourceId 必须对应已声明、全局可见且允许 widgets 读取的全局状态，path 指向其中的数值字段，省略表示根值。宿主自动填入此反馈，但用户可更换或清除。参数范围由既有 Schema 提供，无需重复声明。 state.availabilityPath 可选，指向同一来源中 schema 已声明的布尔字段；只有该字段严格为 true 时反馈数值才有效。省略时不检查业务对象中的任何可用性字段。

{
  "valueControl": {
    "parameter": "level",
    "state": { "sourceId": "widget:volume-slider", "path": ["level"], "availabilityPath": ["available"] }
  }
}

控制目标必须满足当前的显式声明；提供方没有明确声明时，控件停用并提示重新选择。宿主在显示、提交和排队分派时都检查声明，页面无法绕过该限制。

#Category.group

string · 可选

显式加入宿主的公共功能分组：

省略时归入“其他”；填写不在表中的 ID 会被清单校验拒绝。该字段只影响查找和展示，不改变动作调用、权限或已保存引用。

预设、动作选择器和流程编辑器的插件动作目录默认“按功能”：不同插件显式选择同一公共分组时集中显示，条目保留插件来源和本地分类。“按插件”视图保留插件与本地分类层级。搜索同时覆盖公共分组、插件、本地分类和条目名称。宿主的“动作流程”入口独立于插件公共分组。

#categoryGroup

分类的公共功能组使用 contributes.categories[].group 声明。类别 ID 仍属于插件内部命名空间；公共功能组负责动作列表的展示聚合。