243 lines
9.3 KiB
Markdown
243 lines
9.3 KiB
Markdown
# Skill Action Manifest（匠厂宿主）
|
||
|
||
本文件说明 `assets/actions.json` 与 `scripts/main.py` CLI 的对应关系，供 Agent 编排与宿主 **Skill Action Runtime** 使用。
|
||
|
||
**权威运行时契约（sync/async、任务中心、编排范式）见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。**
|
||
|
||
**边界：** 用户市场说明见根目录 [`README.md`](../README.md)；CLI 参数与错误码细节见 [`CLI.md`](CLI.md)。
|
||
|
||
## 模板严格规范 vs 宿主向后兼容
|
||
|
||
| 角色 | 定位 |
|
||
|------|------|
|
||
| **skill-template** | 新技能推荐的**严格规范**：必填字段、明确类型、`additionalProperties: false` |
|
||
| **宿主运行时** | **向后兼容**的历史 manifest 解析器：可能接受部分缺省字段（如 `description`、`placements`、`entrypoint.args`、input property `type`） |
|
||
|
||
**新技能不应依赖宿主缺省行为。** 复制模板后按 [`assets/schemas/skill-actions.schema.json`](../assets/schemas/skill-actions.schema.json) 与本文完整填写 manifest。
|
||
|
||
JSON Schema 使用 `additionalProperties: false` 表达模板严格边界；这与宿主共享类型中的可选字段并不矛盾——宿主为兼容旧技能可能更宽松，模板为防漂移要求更严。
|
||
|
||
## Action 是否必需
|
||
|
||
Action 是**可选能力**：
|
||
|
||
- 没有宿主直接操作需求的技能，**可以不提供** `actions.json`。
|
||
- 需要出现在**数据管理按钮**、**技能详情**、**定时任务**或 **Agent 直接调用**中的技能，**必须**提供 `assets/actions.json`。
|
||
- **含浏览器 RPA / 长耗时任务**的技能：**必须**提供至少一条 `executionProfile: "async"` 且 `placements` 含 `agent` 的 action（见 `POLICY-SKILL-ACTION-001`）。
|
||
|
||
## 文件位置
|
||
|
||
```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)。
|
||
|
||
## Phase 1 当前稳定支持（新技能应只使用这些）
|
||
|
||
| 层级 | 稳定字段 / 能力 |
|
||
|------|----------------|
|
||
| 顶层 | `schemaVersion`、`skill`、`actions` |
|
||
| action | `id`、`label`、`description`、`placements`、`entrypoint`；可选 `inputSchema`、`confirmation`、**`executionProfile`** |
|
||
| entrypoint | `type = cli`、`command`、`args`（**必填** JSON 数组，项为 `string` / `number` / `boolean`） |
|
||
| placements | `toolbar`、`skill-detail`、`agent`、`cron` |
|
||
| inputSchema | 根 `type: object`；properties 使用 `string` / `number` / `boolean`；支持 `enum`、`default`、`required`、`sensitive` |
|
||
| confirmation | `{ "message": "..." }` |
|
||
| **executionProfile** | `"sync"` \| `"async"`（**模板要求显式写出**） |
|
||
|
||
## 预留能力（当前不可当作已实现能力）
|
||
|
||
以下在宿主共享类型或 Schema 枚举中可能出现，但 **Phase 1 Runtime 尚未完整支持**，**新模板示例不得使用**：
|
||
|
||
| 类别 | 预留项 | 说明 |
|
||
|------|--------|------|
|
||
| placements | `row`、`batch` | 行内 / 批量入口，未来扩展 |
|
||
| action 字段 | `bind`、`concurrency`、`locks` | 绑定、并发与锁控制，宿主后续实现 |
|
||
| inputSchema | `array`、nested `object`、`oneOf` 等 | 复杂表单与联合类型，不属于当前推荐模板范围 |
|
||
|
||
可以在文档或 Schema 枚举中保留这些值供未来对齐，但不要让技能作者误以为它们已经可执行。
|
||
|
||
## 执行模型
|
||
|
||
宿主将 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)。
|
||
|
||
### `executionProfile`（sync / async）
|
||
|
||
| 值 | 宿主行为 | 任务中心 |
|
||
|----|----------|----------|
|
||
| `sync` | 内联等待 CLI（默认约 30s） | 不进 |
|
||
| `async` | 后台 Job，立即返回 `jobId` | **进入** |
|
||
| 省略 | 宿主默认按 **async** | 进入 |
|
||
|
||
- **RPA / 浏览器 / 长耗时** → 必须 `"async"`，并建议加 `confirmation`。
|
||
- **数据管理 toolbar** → 只挂 **async** action。
|
||
- 完整规则见 [`../development/SKILL_ACTION_RUNTIME.md`](../development/SKILL_ACTION_RUNTIME.md)。
|
||
|
||
### CLI 输出契约
|
||
|
||
技能 CLI 必须：
|
||
|
||
- 使用稳定的退出码
|
||
- 成功时输出可解析的结构化结果
|
||
- 失败时输出稳定错误信息
|
||
- 对可预期错误提供稳定错误码
|
||
- 对用户可处理的问题提供 `HINT`
|
||
- 不依赖 Agent 连续对话才能完成
|
||
- 不自行实现宿主任务中心
|
||
- 长时间任务允许异步执行，由宿主任务中心承载状态
|
||
- 不在 CLI 中硬编码宿主安装目录
|
||
- 不直接依赖某个具体 UI 页面
|
||
|
||
建议错误输出格式：
|
||
|
||
```text
|
||
ERROR:<CODE>: <message>
|
||
HINT: <next step>
|
||
```
|
||
|
||
## placements（入口位置）
|
||
|
||
| 值 | 含义 |
|
||
|----|------|
|
||
| `toolbar` | 数据管理第一排技能按钮（**仅 async**） |
|
||
| `skill-detail` | 技能详情或技能市场详情页 |
|
||
| `agent` | Agent 可直接调用（`run_skill_action`） |
|
||
| `cron` | 定时任务可直接调用 |
|
||
|
||
**预留能力（当前宿主可能尚未完整支持，模板示例请勿使用）：**
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `row` | 行内操作（未来扩展） |
|
||
| `batch` | 批量操作（未来扩展） |
|
||
|
||
### Action 类型 × placements 矩阵
|
||
|
||
| Action 类型 | executionProfile | 典型 placements | confirmation |
|
||
|-------------|------------------|-----------------|--------------|
|
||
| health / version / config-path | sync | skill-detail, agent | 无 |
|
||
| 统计 / 只读查询 | sync | skill-detail, agent | 无 |
|
||
| 导入 / 重置 | sync | skill-detail, agent | 可选 |
|
||
| 单条副作用 RPA | async | agent, skill-detail | **必须** |
|
||
| 批量顺序 pick RPA | async | **toolbar**, cron, agent | **必须** |
|
||
|
||
## 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
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
批量 pick 参数约定（有队列表时）：
|
||
|
||
```json
|
||
{
|
||
"pickCount": {
|
||
"type": "number",
|
||
"title": "处理数量",
|
||
"description": "从队列选取 pending 记录条数",
|
||
"default": 1,
|
||
"minimum": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
约定：
|
||
|
||
- `boolean` 在宿主中渲染为开关
|
||
- `enum` 在宿主中渲染为选择框
|
||
- `required` 字段在提交前校验
|
||
- `sensitive` 字段不得出现在低信任入口
|
||
- 需要确认的副作用操作使用 `confirmation.message`
|
||
- 模板参数使用 `{{fieldName}}`，且必须在 `inputSchema.properties` 中声明
|
||
- `entrypoint.args` 项当前只允许 `string`、`number`、`boolean`；不允许对象或 `null`
|
||
- **不要**在当前模板中宣传 `nested object`、`oneOf`、复杂数组等尚未稳定支持的能力
|
||
|
||
## 风险与入口配置
|
||
|
||
- 查询、诊断、版本检查可以放到 `skill-detail` 或 `agent`
|
||
- 低风险、常用动作才考虑放 `toolbar`（且须为 async）
|
||
- 会修改本地数据、访问外部系统、执行长时间任务的动作必须谨慎配置
|
||
- 有副作用的动作应添加 `confirmation.message`
|
||
- 高风险动作不应默认出现在 `toolbar`
|
||
- 含 `sensitive` 参数的 action 不应放入 `toolbar` 或 `cron`，除非有明确安全设计
|
||
- 不要为了「按钮多」而暴露所有 CLI 子命令
|
||
- 一个 CLI 命令可以拆成多个语义清晰的 action，但每个 action 必须有明确语义
|
||
- **Agent 必须用 `run_skill_action`，禁止 `exec` 直跑长任务 CLI**（见 `SKILL_ACTION_RUNTIME.md`）
|
||
|
||
## 模板示例 action 一览
|
||
|
||
| id | CLI | executionProfile | placements | 说明 |
|
||
|----|-----|------------------|------------|------|
|
||
| `health` | `health` | sync | skill-detail, agent | 运行环境检查 |
|
||
| `version` | `version` | sync | skill-detail | 版本 JSON |
|
||
| `config-path` | `config-path` | sync | skill-detail | 配置路径 JSON |
|
||
|
||
业务技能复制后，按需增加例如：
|
||
|
||
| 模式 | id 示例 | executionProfile | placements |
|
||
|------|---------|------------------|------------|
|
||
| 单条 RPA | `your-run` | async | agent, skill-detail |
|
||
| 队列 pick | `your-run-pick` | async | toolbar, cron, agent |
|
||
| 统计 | `your-stats` | sync | skill-detail, agent |
|
||
|
||
不需要宿主入口时可删除整个 `actions.json`（无 RPA 长任务时）。
|
||
|
||
## 与宿主 API（参考）
|
||
|
||
| 宿主 API | 用途 |
|
||
|----------|------|
|
||
| `GET /api/skill-actions/{skillSlug}` | 读取 manifest |
|
||
| `POST /api/skill-actions/run` | `{ skillSlug, actionId, input?, source? }` |
|
||
| `GET /api/skill-actions/jobs` | 任务中心 |
|
||
|
||
具体路径与字段以宿主实现为准；技能侧只需保证 manifest 与 CLI 契约稳定。
|