skill-template/references/ACTIONS.md

Skill Action Manifest（匠厂宿主）

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

权威运行时契约（sync/async、任务中心、单内核编排）见 ../development/SKILL_ACTION_RUNTIME.md。

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

模板严格规范 vs 宿主向后兼容

角色	定位
skill-template	新技能推荐的严格规范：必填字段、明确类型、additionalProperties: false
宿主运行时	向后兼容的历史 manifest 解析器：可能接受部分缺省字段（如 description、placements、entrypoint.args、缺失的 bind.tables）

新技能不应依赖宿主缺省行为。 复制模板后按 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）。

文件位置

{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。

五职责正交（必读）

字段 / 层	只决定什么	不决定什么
placements	Action 出现在哪里（toolbar / cron / agent / skill-detail …）	不决定 sync/async
bind.tables	数据管理里出现在哪些业务表	不决定业务实现
executionProfile	宿主是同步等待还是异步 Job	不限制可展示入口
entrypoint	实际执行哪个 CLI 命令与参数	不写业务逻辑
domain service	真正完成什么业务	不感知 toolbar / cron / agent 来源

一个业务能力通常只定义一个 Action，用 placements 同时挂到多个入口。不要拆成 sync-records-toolbar / sync-records-cron 等副本，除非语义确实不同；即便拆分，也必须调用同一个领域业务内核。

Phase 1 当前稳定支持（新技能应只使用这些）

层级	稳定字段 / 能力
顶层	schemaVersion、skill、actions
action	id、label、description、placements、entrypoint、executionProfile（必填）；可选 inputSchema、confirmation、bind
entrypoint	type = cli、command、args（必填 JSON 数组，项为 string / number / boolean）
placements	toolbar、skill-detail、agent、cron
bind	{ "tables": ["business_table"] }（见下节）
inputSchema	根 type: object；properties 使用 string / number / boolean；支持 enum、default、required、sensitive
confirmation	{ "message": "..." }
executionProfile	"sync" | "async"（必须显式写出，禁止依赖缺省）

bind.tables（表级绑定）

{
  "bind": {
    "tables": ["business_table"]
  }
}

规则：

• bind 为 object，additionalProperties: false；当前只允许 tables。
• tables 非空数组、元素唯一、英文 snake_case、不得为空字符串。
• placements 含 toolbar 时必须显式声明非空 bind.tables（模板 Schema if/then + 自动测试强制）。
• 表名须真实存在于技能 SQLite 与 _jiangchang_tables。
• 希望出现在多张表时，显式列出所有表；不要依赖「无 bind 则全表展示」——那是宿主对旧技能的兼容，不是新技能标准。
• 本阶段不扩展 selection / inputMapping / columns / row binding / concurrency / locks。

默认模板 actions.json 仅含 health / version / config-path，不放在 toolbar，故无需 bind 示例污染默认 manifest。业务示例：

{
  "id": "sync-records",
  "label": "同步记录",
  "description": "从外部来源同步到技能本地数据库，不生成导出文件。",
  "placements": ["toolbar", "cron", "agent", "skill-detail"],
  "executionProfile": "async",
  "bind": { "tables": ["business_records"] },
  "entrypoint": { "type": "cli", "command": "sync-records", "args": [] }
}

预留能力（当前不可当作已实现能力）

类别	预留项	说明
placements	row、batch	行内 / 批量入口，未来扩展；新技能示例不得使用
action 字段	concurrency、locks	并发与锁控制，未稳定开放
inputSchema	array、nested object、oneOf 等	复杂表单，不属于当前推荐范围

bind 不是保留字段；已作为 Phase 1 表级绑定正式能力。

执行模型

宿主将 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。

executionProfile（仅 sync / async）

模板与新技能只允许这两种值；禁止发明 auto / background / deferred 等第三种模式。

值	宿主行为	任务中心
sync	调用方等待结束，直接返回结构化结果或结构化错误；不创建后台 Job	不进
async	宿主创建后台 Job，立即返回 jobId；用 emit / checkpoint / finish 报告进度与终态	进入

合法组合（全部允许）：sync|async × toolbar|cron|agent|skill-detail。

经验建议（不是 placement 硬限制）：耗时不可预测、需要暂停/停止/进度展示的任务，建议用 async。

直接执行 CLI 时，终端自然等待进程结束；宿主通过 Action 调用同一 CLI 时，再按 executionProfile 决定同步等待还是建 Job。技能不得自行实现第二套任务中心或后台队列。

CLI 输出契约

技能 CLI 必须：

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

建议错误输出格式：

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

placements（入口位置）

值	含义
toolbar	数据管理第一排技能按钮（须配合 bind.tables）
skill-detail	技能详情或技能市场详情页
agent	Agent 可直接调用（run_skill_action）
cron	定时任务可直接调用

预留（模板示例请勿使用）： row、batch。

Action 类型 × placements（常见示例，不是限制）

下表只表示常见用法示例。实际 placements 以 manifest 配置为准；sync / async 不影响展示入口。

Action 类型	常见 executionProfile	常见 placements	confirmation
health / version / config-path	sync	skill-detail, agent	无
统计 / 只读查询	sync	skill-detail, agent	无
数据同步（外源 → 本地库）	sync 或 async	toolbar + cron + agent + skill-detail（按需）	可选
导入 / 重置	sync 或 async	skill-detail, agent	可选
单条副作用 RPA	async（建议）	agent, skill-detail	建议
批量顺序 pick RPA	async（建议）	toolbar, cron, agent	建议

同步数据 vs 导出当前表 vs 特殊业务报告

不要混用「导出」一词：

能力	语义	谁负责
同步数据（sync / refresh / collect）	外部来源 → 技能本地数据库	技能 Action / domain service
导出当前数据表	技能本地数据库 → CSV/Excel 等	数据管理页宿主统一导出
生成特殊业务报告	多表合并、特殊排版或附加计算	仅当系统导出无法满足时，才提供独立 export-* Action

同步型 Action 默认：读外部数据、写技能自己的库、不生成 CSV/Excel/JSON 文件、不重复实现宿主表导出。兼容旧 export 命令若需要刷新数据，必须调用同一个 sync 业务内核。通用同步语义见 SCHEMA.md 与 ../development/SKILL_ACTION_RUNTIME.md。

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

批量 pick 参数约定（有队列表时）：

{
  "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（须 bind.tables；executionProfile 按耗时自选）
• 会修改本地数据、访问外部系统、执行长时间任务的动作必须谨慎配置
• 有副作用的动作应添加 confirmation.message
• 高风险动作不应默认出现在 toolbar
• 含 sensitive 参数的 action 不应放入 toolbar 或 cron，除非有明确安全设计
• 不要为了「按钮多」而暴露所有 CLI 子命令
• 一个 CLI 命令可以拆成多个语义清晰的 action，但每个 action 必须有明确语义，并复用同一业务内核
• Agent 必须用 run_skill_action，禁止 exec 直跑长任务 CLI（见 SKILL_ACTION_RUNTIME.md）
• 禁止按 source=toolbar/cron/agent/skill-detail 在业务代码中分叉业务行为

模板示例 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	bind
数据同步	sync-records	async 或 sync	toolbar, cron, agent, skill-detail	必填 tables
单条 RPA	your-run	async（建议）	agent, skill-detail	按需
队列 pick	your-run-pick	async（建议）	toolbar, cron, agent	有 toolbar 则必填
统计	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 契约稳定。