表单 YAML 参考

逐项查阅模板、字段、提交动作和输入绑定。校验以 SDK 内的 form.schema.json 与 CLI 语义检查为准。

API 参考

按章节查看契约、签名、字段与示例；未注明的默认值不作推断。

本页内容

01模板顶层

fields 与 steps 必须二选一。未知字段被拒绝；不要加入 $schema、脚本或本地化键。使用编辑器配置关联 schema。

字段	类型	必填	默认值	说明
version	1	是	未注明	必填，固定 1。
id	string	是	未注明	必填，^[a-z][a-z0-9-]{0,79}$。
title / description	string	title 必填	未注明	title 1–120 字符；description 最多 2000。
fields	Field[]	条件必填	未注明	单步模式，1–100 个字段。
steps	Step[]	条件必填	未注明	多步模式，1–20 步；每步 id、title、fields 必填，next 可选。
submit	object	是	未注明	必填；kind: chat 或 kind: operation。

字段必须提供 name、type、label。名称应在其作用域内唯一，并与绑定保持一致。不同类型的组合约束还会由 CLI 校验。

当前支持静态声明式字段，不支持附件、密码输入、远程动态选项或条件脚本。金额应按模板的精度处理，避免把业务金额直接当浮点数累计。

字段 / API	说明
text / textarea	minLength、maxLength 范围 0–20000。
number	minimum、maximum；integer 控制整数。
money	currency 为 3 位大写代码；scale 0–4；金额边界使用十进制字符串，例 '0.01'。
date	日期输入。
select	1–100 个静态 options，每项 label/value 为 1–120 字符。
checkbox	确认勾选；required 用于要求确认。

operation 绑定到同扩展已声明的操作，输入和恢复目标需要通过语义校验；写入依然需要宿主确认。

字段 / API	说明
chat	kind、label 必填；不提供 operation/input。
operation	kind、label、operation、input 必填；recovery 可选。
input	最多 100 个属性，每项是 {from: path} 或 {value: literal}。
recovery.operation	同扩展的 page read 操作，用 submissionId 查询。

安装支持 YAML schema 的编辑器扩展后，将以下内容放进 .vscode/settings.json。静态 schema 不能代替 CLI 的绑定校验或宿主运行时权限检查。

.vscode/settings.json

{
  "yaml.schemas": {
    "./node_modules/@ambleloft/extension-sdk/form.schema.json": [
      "skills/**/*.yaml"
    ]
  }
}

SDK / CLI 0.1.0-alpha.9 · 接口基线兼容性与预览说明 · 案例源码