# Skill Action Manifest（匠厂宿主）

本文件说明 `assets/actions.json` 与 `scripts/main.py` CLI 的对应关系，供 Agent 编排与宿主 **Skill Action Runtime** 使用。

**边界：** 用户市场说明见根目录 [`README.md`](../README.md)；CLI 参数与错误码细节见 [`CLI.md`](CLI.md)。

## Action 是否必需

Action 是**可选能力**：

- 没有宿主直接操作需求的技能，**可以不提供** `actions.json`。
- 需要出现在**数据管理按钮**、**技能详情**、**定时任务**或 **Agent 直接调用**中的技能，**必须**提供 `assets/actions.json`。

## 文件位置

```text
{skill_root}/assets/actions.json
```

宿主扫描路径示例：

```text
~/.openclaw/skills/your-skill-slug/assets/actions.json
```

## 顶层结构

| 字段 | 必填 | 说明 |
|------|------|------|
| `schemaVersion` | 是 | 当前固定为 `1` |
| `skill` | 是 | 必须与 `SKILL.md` 的 `metadata.openclaw.slug` 一致 |
| `actions` | 是 | Action 数组，每项 `id` 唯一 |

模板最小示例见 [`assets/actions.json`](../assets/actions.json)；JSON Schema 见 [`assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json)。

## 执行模型

宿主将 action 转为 argv，再执行：

```text
python {skill_root}/scripts/main.py <command> <args...>
```

- `entrypoint.type` 当前只支持 `cli`
- `entrypoint.command` → CLI 子命令（须真实存在）
- `entrypoint.args` → 子命令参数（**必须为 JSON 数组**）
- `{{fieldName}}` → 来自 `inputSchema` 用户输入的简单模板替换

完整子命令定义见 [`scripts/cli/app.py`](../scripts/cli/app.py)。

### CLI 输出契约

技能 CLI 必须：

- 使用稳定的退出码
- 成功时输出可解析的结构化结果
- 失败时输出稳定错误信息
- 对可预期错误提供稳定错误码
- 对用户可处理的问题提供 `HINT`
- 不依赖 Agent 连续对话才能完成
- 不自行实现宿主任务中心
- 长时间任务允许异步执行，由宿主任务中心承载状态
- 不在 CLI 中硬编码宿主安装目录
- 不直接依赖某个具体 UI 页面

建议错误输出格式：

```text
ERROR:<CODE>: <message>
HINT: <next step>
```

## placements（入口位置）

| 值 | 含义 |
|----|------|
| `toolbar` | 数据管理第一排技能按钮 |
| `skill-detail` | 技能详情或技能市场详情页 |
| `agent` | Agent 可直接调用 |
| `cron` | 定时任务可直接调用 |

**预留能力（当前宿主可能尚未完整支持，模板示例请勿使用）：**

| 值 | 说明 |
|----|------|
| `row` | 行内操作（未来扩展） |
| `batch` | 批量操作（未来扩展） |

可以在 manifest 中作为未来扩展值定义，但不要让技能作者误以为 `row` / `batch` 已经完整可用。

## inputSchema 与参数表单

当前宿主稳定支持：

- `object` / `string` / `number` / `boolean`
- `enum` / `default` / `required` / `sensitive`
- 简单模板替换（`{{fieldName}}`）

示例：

```json
{
  "inputSchema": {
    "type": "object",
    "required": ["query"],
    "properties": {
      "query": {
        "type": "string",
        "title": "查询条件"
      },
      "limit": {
        "type": "number",
        "title": "返回数量",
        "default": 50
      }
    }
  }
}
```

约定：

- `boolean` 在宿主中渲染为开关
- `enum` 在宿主中渲染为选择框
- `required` 字段在提交前校验
- `sensitive` 字段不得出现在低信任入口
- 需要确认的副作用操作使用 `confirmation.message`
- 模板参数使用 `{{fieldName}}`，且必须在 `inputSchema.properties` 中声明
- `entrypoint.args` 项当前只允许 `string`、`number`、`boolean`；不允许对象或 `null`
- **不要**在当前模板中宣传 `nested object`、`oneOf`、复杂数组等尚未稳定支持的能力

## 风险与入口配置

- 查询、诊断、版本检查可以放到 `skill-detail` 或 `agent`
- 低风险、常用动作才考虑放 `toolbar`
- 会修改本地数据、访问外部系统、执行长时间任务的动作必须谨慎配置
- 有副作用的动作应添加 `confirmation.message`
- 高风险动作不应默认出现在 `toolbar`
- 含 `sensitive` 参数的 action 不应放入 `toolbar` 或 `cron`，除非有明确安全设计
- 不要为了「按钮多」而暴露所有 CLI 子命令
- 一个 CLI 命令可以拆成多个语义清晰的 action，但每个 action 必须有明确语义

## 模板示例 action 一览

| id | CLI | placements | 说明 |
|----|-----|------------|------|
| `health` | `health` | skill-detail, agent | 运行环境检查 |
| `version` | `version` | skill-detail | 版本 JSON |
| `config-path` | `config-path` | skill-detail | 配置路径 JSON |

复制为新技能后，请按业务需要增删 action；不需要宿主入口时可删除整个 `actions.json`。

## 与宿主 API（参考）

| 宿主 API | 用途 |
|----------|------|
| `GET /api/skill-actions/{skillSlug}` | 读取 manifest |
| `POST /api/skill-actions/run` | `{ skillSlug, actionId, input?, source? }` |
| `GET /api/skill-actions/jobs` | 任务中心 |

具体路径与字段以宿主实现为准；技能侧只需保证 manifest 与 CLI 契约稳定。