Files

chendelian 35c20fc0f2 feat: standardize skill data management and actions

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-11 11:23:14 +08:00

5.1 KiB

Raw Blame History

Skill Action Manifest（匠厂宿主）

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

边界： 用户市场说明见根目录 README.md；CLI 参数与错误码细节见 CLI.md。

Action 是否必需

Action 是可选能力：

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

文件位置

{skill_root}/assets/actions.json

宿主扫描路径示例：

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

顶层结构

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

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

执行模型

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

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

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

完整子命令定义见 scripts/cli/app.py。

CLI 输出契约

技能 CLI 必须：

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

建议错误输出格式：

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}}）

示例：

{
  "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 契约稳定。

5.1 KiB Raw Blame History Unescape Escape