# actions

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

## 示例



```json
{
  "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 路径，见[插件图标与资源](./icons.md)。

### `Action.category`

`string` · 可选

引用 `categories` 中的分类 ID。

### `Action.argsSchema`

`Schema` · 可选

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

顶层字符串参数可声明 `dynamicOptions: true`，通过后台 `actionOptions` 返回搜索候选项，见[动态候选项](../guides/actions.md#动态候选项)。

### `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`，两者可属于不同分类。

```json
{
  "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 路径，见[插件图标与资源](./icons.md)。

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

## 显式开放数值控制

### `Action.valueControl`

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

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

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

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

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

### `Category.group`

`string` · 可选

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

| ID | 名称 |
| --- | --- |
| `system` | 系统 |
| `display` | 显示 |
| `audio` | 音频 |
| `media` | 多媒体 |
| `network` | 网络 |
| `tools` | 工具 |
| `other` | 其他 |

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

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

## categoryGroup

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