# AI 生成技能

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```


提交技能草稿并接收服务端发送的润色事件；结果事件包含可保存的技能内容。

```text
POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/skills/polish/stream
```

## 调用前准备

准备个人访问令牌、工作区 ID 和待润色的技能草稿。响应类型为 `text/event-stream`。

## 请求体

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 调用示例

```bash
curl -N -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/skills/polish/stream" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "摘要",
    "description": "生成内容摘要",
    "instruction": "总结输入内容"
  }'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 技能名称。 |
| `instruction` | string | 是 | 待润色的技能指令。 |
| `description` | string | 是 | 技能说明。 |
| `instruction_spec` | object | 否 | 结构化技能指令。 |
| `instruction_spec.body` | string | 否 | 指令正文。 |
| `instruction_spec.variables_schema` | object | 否 | 指令变量的 JSON Schema。 |
| `input_requirements` | string | 否 | 输入要求。 |
| `output_format` | string | 否 | 输出格式。 |
| `category` | string | 否 | 技能分类。 |
| `tags` | string（字符串数组） | 否 | 技能标签。 |
| `phase` | string | 否 | 技能阶段。 |
| `pipeline` | string（字符串数组） | 否 | 流水线步骤。 |
| `pipeline_ref` | string | 否 | 流水线引用。 |
| `source_type` | string | 否 | 技能源类型。 |
| `source_ref` | string | 否 | 技能源引用。 |
| `routing_summary` | object | 否 | 路由摘要。 |
| `requirements` | object | 否 | 技能依赖要求。 |
| `parameters_schema` | object | 否 | 输入参数的 JSON Schema。 |
| `output_contract` | object | 否 | 输出契约。 |
| `labels` | object | 否 | 字符串标签。 |
| `annotations` | object | 否 | 字符串注解。 |
| `metadata` | object | 否 | 扩展元数据。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```text
event: started
data: {"request_id":"req_01","prompt_version":"skill_polish_v1"}

event: delta
data: {"request_id":"req_01","content":"请总结输入内容"}

event: ping
data: {"request_id":"req_01","timestamp":"2026-08-21T07:00:00Z"}

event: result
data: {"request_id":"req_01","result":{"name":"摘要","description":"摘要技能","instruction":"请总结输入内容","tags":[]}}

event: error
data: {"request_id":"req_01","error":{"code":"INVALID_DRAFT","message":"The skill draft is invalid.","retryable":false}}

event: done
data: {"request_id":"req_01"}
```

:::::
:::::{tab-item} 字段说明

成功时返回事件流。每个事件都由 `event:` 行、单行 JSON 的 `data:` 行和一个空行组成。`result` 事件包含已校验的技能草稿，`done` 表示流结束。



响应字段如下。

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `SSE 事件名` | string | `event:` 行中的事件类型，可为 `started`、`delta`、`ping`、`result`、`error` 或 `done`。 |
| `request_id` | string | 本次润色请求 ID。 |

:::

:::{tab-item} 开始事件

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `prompt_version` | string | `started` 事件中的提示词版本。 |

:::

:::{tab-item} 增量与心跳

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `content` | string | `delta` 事件中的增量文本。 |
| `timestamp` | string | `ping` 事件中的 RFC 3339 时间。 |

:::

:::{tab-item} 生成结果

下面表格展开响应示例中的 `result` 数据；每一行是该对象或数组项的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result` | object | `result` 事件中的已校验技能草稿。 |
| `name` | string | 技能名称。 |
| `description` | string | 技能说明。 |
| `instruction` | string | 润色后的技能指令。 |
| `instruction_spec` | object | 结构化技能指令；未设置时不返回。 |
| `input_requirements` | string | 输入要求；未设置时不返回。 |
| `output_format` | string | 输出格式；未设置时不返回。 |
| `category` | string | 技能分类；未设置时不返回。 |
| `tags` | string（字符串数组） | 技能标签。 |
| `phase` | string | 技能阶段；未设置时不返回。 |
| `pipeline` | string（字符串数组） | 流水线步骤；未设置时不返回。 |
| `pipeline_ref` | string | 流水线引用；未设置时不返回。 |
| `source_type` | string | 技能源类型；未设置时不返回。 |
| `source_ref` | string | 技能源引用；未设置时不返回。 |
| `routing_summary` | object | 路由摘要；未设置时不返回。 |
| `requirements` | object | 技能依赖要求；未设置时不返回。 |
| `parameters_schema` | object | 输入参数的 JSON Schema；未设置时不返回。 |
| `output_contract` | object | 输出契约；未设置时不返回。 |
| `labels` | object | 字符串标签；未设置时不返回。 |
| `annotations` | object | 字符串注解；未设置时不返回。 |
| `metadata` | object | 扩展元数据；未设置时不返回。 |
| `pending_confirmations` | string（字符串数组） | 仍需确认的事项；没有时不返回。 |
| `warnings` | string（字符串数组） | 润色警告；没有时不返回。 |

:::

:::{tab-item} 错误事件

下面表格展开响应示例中的 `error` 数据；每一行是该对象或数组项的一个字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error` | object | `error` 事件中的公开错误信息。 |
| `code` | string | 流内错误代码。 |
| `message` | string | 流内错误说明。 |
| `retryable` | boolean | 是否可以重试。 |

:::
::::

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```text
event: error
data: {"request_id":"req_01","error":{"code":"INVALID_DRAFT","message":"The skill draft is invalid.","retryable":false}}

event: done
data: {"request_id":"req_01"}
```

```json
{
  "code": 2,
  "message": "invalid argument"
}
```

:::::
:::::{tab-item} 字段说明

流已经开始后，处理错误通过 SSE `error` 事件返回，随后发送 `done`：



流建立前的请求错误使用普通 JSON 响应：



### 常见 HTTP 错误

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `400` | `2` | **常见原因：**JSON 无效，或技能草稿未通过建立事件流前的校验。**建议操作：**检查请求体和必填字段。 |
| `503` | `15` | **常见原因：**技能润色服务未配置。**建议操作：**稍后重试。 |

:::
::::

:::::
::::::
:::::::