feat: standardize skill data management and actions
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
161
references/ACTIONS.md
Normal file
161
references/ACTIONS.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 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 契约稳定。
|
||||
Reference in New Issue
Block a user