492 lines
21 KiB
JSON
492 lines
21 KiB
JSON
{
|
||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||
"$id": "https://openclaw.local/skill-template/skill-actions.schema.json",
|
||
"title": "SkillActionManifest",
|
||
"description": "匠厂 skill-template 对新技能的严格 Action manifest 规范（schemaVersion 1）。additionalProperties=false 表示模板推荐契约；宿主运行时可能为兼容历史 manifest 接受部分缺省字段，但新技能不应依赖缺省行为。含可选 hostEffects/steps（匠厂宿主 ≥2.8.5）与可选 hoverHint（数据管理工具栏悬停，需宿主已支持该字段）。",
|
||
"type": "object",
|
||
"required": ["schemaVersion", "skill", "actions"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"schemaVersion": {
|
||
"type": "integer",
|
||
"const": 1
|
||
},
|
||
"skill": {
|
||
"type": "string",
|
||
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
|
||
"description": "与 SKILL.md metadata.openclaw.slug 一致"
|
||
},
|
||
"actions": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"items": { "$ref": "#/$defs/action" },
|
||
"description": "Action 列表。同一 placement（toolbar/row/batch）下，宿主按本数组中匹配项的相对顺序展示。toolbar/batch：表顶栏全部直接展示（无「更多操作」溢出）。row：行级入口，宿主可呈现为操作列、行右键和/或行内「⋯」（同一批 Action、同一顺序）；不在本字段配置排序、截断或菜单树。调整顺序即调整数组先后。无独立 sortOrder 字段。宿主内置刷新/导出/查看等不参与本顺序。表顶栏宽时左右横排，窄时左右分栏且栏内竖排。"
|
||
},
|
||
"policy": {
|
||
"$ref": "#/$defs/policyDeclaration",
|
||
"description": "可选。启用 Data Policy（L1/L2）。缺省或不 enabled = L0，宿主不拉 Snapshot。详见 references/POLICY.md。"
|
||
},
|
||
"cellPresentation": {
|
||
"$ref": "#/$defs/cellPresentationDeclaration",
|
||
"description": "可选。启用数据管理单元格呈现（P1）。缺省或不 enabled = P0，宿主不读标色。详见 references/CELL_PRESENTATION.md。"
|
||
}
|
||
},
|
||
"$defs": {
|
||
"cellPresentationDeclaration": {
|
||
"type": "object",
|
||
"required": ["enabled"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"enabled": {
|
||
"type": "boolean",
|
||
"description": "仅 true 启用；false 等同 P0。"
|
||
}
|
||
}
|
||
},
|
||
"policyDeclaration": {
|
||
"type": "object",
|
||
"required": ["enabled"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"enabled": {
|
||
"type": "boolean",
|
||
"description": "仅 true 启用；false 等同 L0。"
|
||
},
|
||
"entrypoint": {
|
||
"$ref": "#/$defs/entrypoint",
|
||
"description": "enabled=true 时必填。推荐 command=policy，args 可含 {{table}}/{{skill}}/{{userId}}。"
|
||
},
|
||
"appliesTo": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string",
|
||
"enum": ["data-management"]
|
||
},
|
||
"description": "缺省 [\"data-management\"]。本期宿主只实现 data-management。"
|
||
}
|
||
},
|
||
"allOf": [
|
||
{
|
||
"if": {
|
||
"properties": { "enabled": { "const": true } },
|
||
"required": ["enabled"]
|
||
},
|
||
"then": {
|
||
"required": ["entrypoint"]
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"placement": {
|
||
"type": "string",
|
||
"enum": ["toolbar", "row", "batch", "cron", "agent", "skill-detail"],
|
||
"description": "稳定支持 toolbar/row/batch/cron/agent/skill-detail（对齐匠厂宿主）。row=行级入口（操作列/行右键/⋯ 等由宿主呈现，无独立 row-context-menu placement）。placements 与 executionProfile 正交，不做条件限制。"
|
||
},
|
||
"mutationKind": {
|
||
"type": "string",
|
||
"enum": ["create", "update", "delete", "import"],
|
||
"description": "可选。接管数据管理默认按钮：create=新增、update=编辑、delete=删除、import=导入。须配合非空 bind.tables；无配置时宿主仍直写 SQLite。import 时 UI 仍用宿主「导入数据」面板，确认后调用本 Action 写库。"
|
||
},
|
||
"scalarArg": {
|
||
"type": ["string", "number", "boolean"]
|
||
},
|
||
"inputProperty": {
|
||
"type": "object",
|
||
"required": ["type"],
|
||
"additionalProperties": true,
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": ["string", "number", "boolean", "object"],
|
||
"description": "模板 Phase 1 仅推荐 string/number/boolean；根 inputSchema.type=object 的 properties 使用基础标量类型"
|
||
},
|
||
"title": { "type": "string" },
|
||
"description": { "type": "string" },
|
||
"default": {},
|
||
"enum": {
|
||
"type": "array",
|
||
"minItems": 1
|
||
},
|
||
"sensitive": { "type": "boolean" },
|
||
"readOnly": {
|
||
"type": "boolean",
|
||
"description": "只读。有「已选择」且字段来自 inputMapping（或约定 id 字段）时，宿主 form 默认不渲染该控件，预设值仍提交；无摘要时只读展示。勿用 visibleWhen 代替（visibleWhen 隐藏不提交）。"
|
||
},
|
||
"revealInForm": {
|
||
"type": "boolean",
|
||
"description": "可选逃生阀。true 时即使弹层有「已选择」摘要，也仍渲染该 readOnly 字段。不改变提交 payload。省略=映射只读字段在有摘要时默认折叠。"
|
||
},
|
||
"column": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-z][a-z0-9_]*$",
|
||
"description": "可选。绑定业务表物理列名；Action 弹窗（toolbar/batch）与 replaces create/update 抽屉均可复用该列的中文名与 lookup 下拉"
|
||
},
|
||
"display_type": {
|
||
"type": "string",
|
||
"enum": ["textarea", "date", "datetime_unix_seconds", "url", "email", "lookup", "directory", "file"],
|
||
"description": "可选。表单控件提示；与 format 二选一即可。lookup=关联下拉（须配 lookup 对象或绑到已有 lookup 列）。file/directory=本地路径选择（可选 pathRoot 指定起始目录，见 ACTIONS.md）。须与 CRUD display_type 语义对齐。"
|
||
},
|
||
"format": {
|
||
"type": "string",
|
||
"enum": ["textarea", "date", "datetime_unix_seconds", "url", "email", "lookup", "directory", "file"],
|
||
"description": "可选。display_type 别名，语义相同。"
|
||
},
|
||
"pathRoot": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "可选。仅对 display_type/format 为 file 或 directory 有意义：原生选文件/目录对话框的起始文件夹，相对当前技能数据根（如 input/库存数据）。省略则宿主默认打开 {skill_data}/input。禁止绝对路径、盘符与 ..。Agent/CLI 忽略。见 references/ACTIONS.md「本地路径选择与 pathRoot」。"
|
||
},
|
||
"lookup": {
|
||
"$ref": "#/$defs/lookupConfig",
|
||
"description": "可选。内联同库表关联 Lookup（与列 options_json lookup 对象同构）。用于当前表没有对应列时；推荐同时设 display_type=lookup。见 ACTIONS.md「跨表引用：Lookup」。"
|
||
},
|
||
"visibleWhen": {
|
||
"description": "可选。表单字段条件显隐。宿主在数据管理/定时任务参数表单中：规则不满足则隐藏该字段、提交时省略、且不校验 required。支持 {field,equals} / {field,in:[...]}，或单键简写 {collectMode:\"按关键词采集\"} / {collectMode:[\"a\",\"b\"]}。Agent/CLI 无 UI 时同样按当前 input 求值后剥离隐藏字段。",
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"required": ["field", "equals"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"field": { "type": "string", "minLength": 1 },
|
||
"equals": { "type": ["string", "number", "boolean"] }
|
||
}
|
||
},
|
||
{
|
||
"type": "object",
|
||
"required": ["field", "in"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"field": { "type": "string", "minLength": 1 },
|
||
"in": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"items": { "type": ["string", "number", "boolean"] }
|
||
}
|
||
}
|
||
},
|
||
{
|
||
"type": "object",
|
||
"minProperties": 1,
|
||
"maxProperties": 1,
|
||
"additionalProperties": {
|
||
"oneOf": [
|
||
{ "type": ["string", "number", "boolean"] },
|
||
{
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"items": { "type": ["string", "number", "boolean"] }
|
||
}
|
||
]
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"lookupConfig": {
|
||
"type": "object",
|
||
"required": ["ref_table", "value_column", "label_column"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"ref_table": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
|
||
"description": "同库被引用表名"
|
||
},
|
||
"value_column": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
|
||
"description": "提交值列（编号 / 外键）"
|
||
},
|
||
"label_column": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
|
||
"description": "主文案列"
|
||
},
|
||
"extra_column": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
|
||
"description": "可选。第三展示列；有值时宿主拼成「value · label（extra）」"
|
||
},
|
||
"filter_column": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
|
||
"description": "可选。等值过滤列"
|
||
},
|
||
"filter_value": {
|
||
"type": ["string", "number", "boolean", "null"],
|
||
"description": "可选。与 filter_column 配对的等值"
|
||
},
|
||
"multiple": {
|
||
"type": "boolean",
|
||
"description": "可选。true=多选 Lookup（存/提交 TEXT 逗号分隔 id）；省略或 false=单选（默认）。与 CRUD options_json lookup 同构。"
|
||
}
|
||
},
|
||
"description": "同库 FK 式 Lookup。展示：value · label；有 extra 时 value · label（extra）。multiple 时多选。宿主亦接受 camelCase 键名。"
|
||
},
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"required": ["type", "properties"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"type": { "const": "object" },
|
||
"required": {
|
||
"type": "array",
|
||
"items": { "type": "string" }
|
||
},
|
||
"properties": {
|
||
"type": "object",
|
||
"additionalProperties": { "$ref": "#/$defs/inputProperty" }
|
||
}
|
||
}
|
||
},
|
||
"entrypoint": {
|
||
"type": "object",
|
||
"required": ["type", "command", "args"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"type": { "const": "cli" },
|
||
"command": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"args": {
|
||
"type": "array",
|
||
"items": { "$ref": "#/$defs/scalarArg" },
|
||
"description": "仅允许 string/number/boolean 标量数组"
|
||
}
|
||
}
|
||
},
|
||
"confirmation": {
|
||
"type": "object",
|
||
"required": ["message"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"message": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
}
|
||
}
|
||
},
|
||
"bind": {
|
||
"type": "object",
|
||
"required": ["tables"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"tables": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"uniqueItems": true,
|
||
"items": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-z][a-z0-9_]*$",
|
||
"description": "英文 snake_case 业务表名；须真实存在于技能 SQLite / _jiangchang_tables"
|
||
},
|
||
"description": "数据管理表级绑定：决定 toolbar/row/batch Action 出现在哪些表。宿主兼容旧技能时，缺失 bind 可视为全表展示；新技能 toolbar Action 必须显式声明。"
|
||
},
|
||
"inputMapping": {
|
||
"type": "object",
|
||
"additionalProperties": { "type": "string", "minLength": 1 },
|
||
"description": "可选。将 $row.$pk / $row.col / $selection.ids 等映射到 inputSchema 字段名，供 row/batch 预填。"
|
||
},
|
||
"columnMapping": {
|
||
"type": "object",
|
||
"additionalProperties": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-z][a-z0-9_]*$"
|
||
},
|
||
"description": "可选。将 inputSchema 属性名映射到业务表物理列名，供 Action 弹窗与 replaces create/update 抽屉复用列 displayName / lookup options。"
|
||
},
|
||
"labelColumn": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-z][a-z0-9_]*$",
|
||
"description": "可选。数据管理 Action 确认/表单弹层「已选择」摘要用的可读标签列（#id + 标签）。仅影响展示，不改变提交 payload。省略时宿主按常见列名启发（title/name 等），再不行只显示编号。"
|
||
}
|
||
},
|
||
"description": "表级绑定；toolbar 必填。可选 inputMapping / columnMapping / labelColumn。concurrency/locks 勿写入。"
|
||
},
|
||
"hostEffectId": {
|
||
"type": "string",
|
||
"enum": ["reloadTable", "refreshCatalog", "clearSelection"],
|
||
"description": "数据管理 UI 副作用（匠厂宿主 ≥2.8.5）。reloadTable=刷新当前表（含 Data Policy）；refreshCatalog=刷新技能目录；clearSelection=清空多选。"
|
||
},
|
||
"hostEffects": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"onSuccess": {
|
||
"type": "array",
|
||
"items": { "$ref": "#/$defs/hostEffectId" },
|
||
"uniqueItems": true,
|
||
"description": "sync 退出 0，或 async 任务已被任务中心接收时触发（不是 Job 跑完）。"
|
||
},
|
||
"onFailure": {
|
||
"type": "array",
|
||
"items": { "$ref": "#/$defs/hostEffectId" },
|
||
"uniqueItems": true,
|
||
"description": "sync 失败，或 async 启动被拒时触发。"
|
||
}
|
||
},
|
||
"description": "可选。UI 副作用简写；省略则宿主不额外改 UI。与 placements/executionProfile/interaction 正交；cron/agent 忽略。新技能有编排需求时优先用 steps。"
|
||
},
|
||
"actionStep": {
|
||
"type": "object",
|
||
"required": ["when", "do"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"when": {
|
||
"type": "string",
|
||
"enum": ["before", "afterSuccess", "afterFailure"],
|
||
"description": "before=CLI 前；afterSuccess/afterFailure 时机同 hostEffects.onSuccess/onFailure。"
|
||
},
|
||
"do": {
|
||
"type": "string",
|
||
"enum": ["deleteByFk", "deleteRows", "reloadTable", "refreshCatalog", "clearSelection"],
|
||
"description": "闭环操作或 UI 效果。deleteByFk/deleteRows 须配合 table（及 fk）。"
|
||
},
|
||
"table": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-z][a-z0-9_]*$",
|
||
"description": "deleteByFk / deleteRows 目标表（snake_case）。"
|
||
},
|
||
"fk": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"pattern": "^[a-z][a-z0-9_]*$",
|
||
"description": "deleteByFk 时子表外键列名。"
|
||
}
|
||
},
|
||
"allOf": [
|
||
{
|
||
"if": {
|
||
"properties": { "do": { "const": "deleteByFk" } },
|
||
"required": ["do"]
|
||
},
|
||
"then": { "required": ["table", "fk"] }
|
||
},
|
||
{
|
||
"if": {
|
||
"properties": { "do": { "const": "deleteRows" } },
|
||
"required": ["do"]
|
||
},
|
||
"then": { "required": ["table"] }
|
||
}
|
||
]
|
||
},
|
||
"action": {
|
||
"type": "object",
|
||
"required": ["id", "label", "description", "placements", "entrypoint", "executionProfile"],
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
|
||
"minLength": 1
|
||
},
|
||
"label": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"description": {
|
||
"type": "string",
|
||
"minLength": 1
|
||
},
|
||
"hoverHint": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "可选。数据管理工具栏悬停文案。与 description / confirmation.message 独立；省略则不显示悬停，不回退。需宿主已支持该字段。当前实现为顶栏技能按钮，不含宿主内置删除/刷新/新增/导入/导出。"
|
||
},
|
||
"placements": {
|
||
"type": "array",
|
||
"minItems": 0,
|
||
"items": { "$ref": "#/$defs/placement" },
|
||
"description": "决定 Action 出现在哪里；与 executionProfile 正交。仅 replaces 接管默认 CRUD 时可为空数组。数据管理 toolbar/row/batch 的顺序由顶层 actions 数组相对顺序决定。表顶栏 toolbar/batch 全部直接展示（无溢出菜单）；row 为行级入口（操作列/行右键/⋯），不在本字段配置排序、截断或菜单树。"
|
||
},
|
||
"replaces": { "$ref": "#/$defs/mutationKind" },
|
||
"entrypoint": { "$ref": "#/$defs/entrypoint" },
|
||
"inputSchema": { "$ref": "#/$defs/inputSchema" },
|
||
"confirmation": { "$ref": "#/$defs/confirmation" },
|
||
"executionProfile": {
|
||
"type": "string",
|
||
"enum": ["sync", "async"],
|
||
"description": "sync=调用方等待结构化结果（不建 Job）；async=宿主建后台 Job 并进任务中心。必须显式写出；长耗时建议 async，但不限制 placements。"
|
||
},
|
||
"interaction": {
|
||
"type": "string",
|
||
"enum": ["auto", "direct", "confirm", "form"],
|
||
"description": "数据管理等可点击入口的交互方式（与 executionProfile 正交）。direct=一点即跑；confirm=轻量确认（文案用 confirmation.message）；form=参数表单；auto/省略=宿主按 inputSchema+confirmation 推断。cron 触发与 agent 忽略本字段。"
|
||
},
|
||
"interactionByPlacement": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"toolbar": { "type": "string", "enum": ["direct", "confirm", "form"] },
|
||
"row": { "type": "string", "enum": ["direct", "confirm", "form"] },
|
||
"batch": { "type": "string", "enum": ["direct", "confirm", "form"] },
|
||
"cron": { "type": "string", "enum": ["direct", "confirm", "form"] },
|
||
"agent": { "type": "string", "enum": ["direct", "confirm", "form"] },
|
||
"skill-detail": { "type": "string", "enum": ["direct", "confirm", "form"] },
|
||
"create": { "type": "string", "enum": ["direct", "confirm", "form"] },
|
||
"update": { "type": "string", "enum": ["direct", "confirm", "form"] },
|
||
"delete": { "type": "string", "enum": ["direct", "confirm", "form"] },
|
||
"import": { "type": "string", "enum": ["direct", "confirm", "form"] }
|
||
},
|
||
"description": "按 placement / replaces 覆盖 interaction（只能写 concrete 模式，不能写 auto）。"
|
||
},
|
||
"bind": { "$ref": "#/$defs/bind" },
|
||
"hostEffects": { "$ref": "#/$defs/hostEffects" },
|
||
"steps": {
|
||
"type": "array",
|
||
"maxItems": 8,
|
||
"items": { "$ref": "#/$defs/actionStep" },
|
||
"description": "可选。有序宿主编排（before / afterSuccess / afterFailure）；单次最多 8 步。与 hostEffects 可并存（同效果可能各跑一次）。新技能优先用 steps。省略则无额外步骤。需匠厂宿主 ≥2.8.5。"
|
||
},
|
||
"authz": {
|
||
"type": "object",
|
||
"additionalProperties": false,
|
||
"properties": {
|
||
"capability": {
|
||
"type": "string",
|
||
"minLength": 1,
|
||
"description": "可选文档/静态提示用能力名；宿主不得仅凭此显隐按钮，运行时以 policy Snapshot 为准。"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"if": {
|
||
"properties": {
|
||
"placements": {
|
||
"contains": { "const": "toolbar" }
|
||
}
|
||
},
|
||
"required": ["placements"]
|
||
},
|
||
"then": {
|
||
"required": ["bind"]
|
||
},
|
||
"allOf": [
|
||
{
|
||
"if": {
|
||
"required": ["replaces"]
|
||
},
|
||
"then": {
|
||
"required": ["bind"]
|
||
}
|
||
}
|
||
],
|
||
"description": "concurrency/locks 为未稳定预留字段，勿写入新技能 manifest。placements 含 toolbar 或声明 replaces 时必须声明 bind.tables。无 replaces 时 placements 建议非空（模板测试强制）。"
|
||
}
|
||
}
|
||
}
|