@qingflow-tech/qingflow-cli 1.1.43-beta.3 → 1.1.43-beta.5

package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/complete.json

@@ -58,9 +58,6 @@
           "type": "string"
         }
       },
-      "required": [
-        "name"
-      ],
       "type": "object"
     },
     "AnswerValue": {
@@ -131,8 +128,15 @@
     },
     "AppFormSpec": {
       "additionalProperties": false,
-      "description": "表单基础配置与字段布局目标态;除 body 外,缺失属性表示保留当前值。",
+      "description": "表单基础配置与字段布局目标态;除 body 外,缺失属性表示保留当前值。应用内所有 q_linker 和 code_block 字段的 outputs[].targetField 必须全局唯一,同一实际字段只能被一个输出映射写入。多个生产方需要回写时,请选择不同目标字段或合并为一个生产方。",
       "properties": {
+        "appDescription": {
+          "description": "应用描述;null 或空字符串表示清空。",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "appName": {
           "description": "应用名称;缺失时保留当前名称。",
           "minLength": 1,
@@ -147,46 +151,33 @@
         },
         "body": {
           "$ref": "#/$defs/Body",
-          "description": "业务字段与布局的完整目标态;缺失字段或段落表示删除。"
+          "description": "业务字段与布局的完整目标态;缺失字段或段落表示删除。应用内所有 Q-Linker 和代码块的 outputs[].targetField 不得重复选择同一实际字段。"
         },
-        "color": {
-          "description": "新应用图标颜色;仅创建分支允许,必须来自 workspace icon color catalog。",
-          "minLength": 1,
-          "type": "string"
-        },
-        "description": {
-          "description": "应用描述;null 或空字符串表示清空。",
-          "type": [
-            "string",
-            "null"
+        "dataCoverField": {
+          "description": "数据封面字段选择器;指定每条数据的封面附件来源。仅允许选择顶层 attachment 字段;null 表示清除数据封面。",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/FieldSelector"
+            }
           ]
         },
-        "icon": {
-          "description": "新应用图标;仅创建分支允许,必须来自 workspace icon catalog 且不得为 template。",
-          "minLength": 1,
-          "type": "string"
-        },
-        "serialNumber": {
-          "$ref": "#/$defs/SerialNumber",
-          "description": "应用编号规则;支持默认编号或自定义组件编号。"
-        },
-        "style": {
-          "description": "应用样式;对象内缺失属性保留当前值,null 表示清除全部自定义样式。",
+        "dataTitleField": {
+          "description": "数据标题字段选择器;指定每条数据的主显示标题来源。创建非空 body 时必填,更新时省略表示保留当前选择;显式提供时必须唯一定位一个顶层字段,仅 body 为空时允许 null。",
           "oneOf": [
             {
-              "$ref": "#/$defs/Style"
+              "type": "null"
             },
             {
-              "type": "null"
+              "$ref": "#/$defs/FieldSelector"
             }
           ]
         },
-        "theme": {
-          "description": "应用主题 ID;null 表示清除自定义主题。",
-          "type": [
-            "integer",
-            "null"
-          ]
+        "serialNumber": {
+          "$ref": "#/$defs/SerialNumber",
+          "description": "应用编号规则;支持默认编号或自定义组件编号。"
         }
       },
       "required": [
@@ -384,7 +375,28 @@
     },
     "CodeBlockBinding": {
       "additionalProperties": false,
-      "description": "代码块的输入、代码和输出映射。",
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "outputs": {
+                "minItems": 1
+              }
+            },
+            "required": [
+              "outputs"
+            ]
+          },
+          "then": {
+            "properties": {
+              "code": {
+                "pattern": "(^|[^A-Za-z0-9_$])qf_output\\s*=(?!=)"
+              }
+            }
+          }
+        }
+      ],
+      "description": "代码块的输入、代码和输出映射;配置 outputs 时,代码必须显式给 qf_output 赋值,仅 return 对象不会产生可回写结果。每个输出目标还必须满足应用级唯一性规则,不能与任何代码块或 Q-Linker 的其他输出指向同一实际字段。多个生产方需要回写时,请选择不同目标字段或合并为一个生产方。",
       "properties": {
         "autoTrigger": {
           "description": "是否在输入变化时自动执行代码块。",
@@ -394,7 +406,7 @@
           ]
         },
         "code": {
-          "description": "代码块源码;MCP/CLI 仅保存,不执行。",
+          "description": "业务代码源码;MCP/CLI 仅保存,不执行。inputs 声明的 var 会由 Builder 自动注入。配置 outputs 时必须显式赋值 qf_output,例如 qf_output = { score: input.score };,仅 return 对象或比较 qf_output 不会回写。",
           "minLength": 1,
           "type": "string"
         },
@@ -420,14 +432,14 @@
           ]
         },
         "inputs": {
-          "description": "当前表单字段到代码变量的映射。",
+          "description": "当前表单字段到代码变量的映射。Builder 会在保存时自动生成读取 qf_field 的代码前缀;业务 code 直接使用 var,不要手写 qf_field.{字段名$$ID$$}。",
           "items": {
             "$ref": "#/$defs/CodeBlockInputBinding"
           },
           "type": "array"
         },
         "outputs": {
-          "description": "代码输出路径到目标字段的映射。",
+          "description": "代码输出路径到目标字段的映射;每个 path 必须从代码显式赋值的 qf_output 中读取,且所有 targetField 在整个应用的代码块和 Q-Linker 输出中必须全局唯一。",
           "items": {
             "$ref": "#/$defs/CodeBlockOutputBinding"
           },
@@ -454,14 +466,14 @@
     },
     "CodeBlockInputBinding": {
       "additionalProperties": false,
-      "description": "一个表单字段到代码变量的映射。",
+      "description": "一个表单字段到代码变量的映射;Builder 自动生成后端字段读取前缀。",
       "properties": {
         "field": {
           "$ref": "#/$defs/FieldSelector",
           "description": "输入来源字段。"
         },
         "var": {
-          "description": "代码中的变量名;null 表示沿用后端默认变量名。",
+          "description": "业务 code 中直接使用的 JavaScript 变量名;null 表示由 Builder 生成合法且唯一的变量名。",
           "type": [
             "string",
             "null"
@@ -475,7 +487,7 @@
     },
     "CodeBlockOutputBinding": {
       "additionalProperties": false,
-      "description": "一个代码输出值到表单字段的映射。",
+      "description": "一个代码输出值到表单字段的映射;同一实际目标字段在整个应用中只能被一个代码块或 Q-Linker 输出映射写入。",
       "properties": {
         "alias": {
           "description": "输出别名;用于后续数据关联引用。",
@@ -483,7 +495,7 @@
           "type": "string"
         },
         "aliasId": {
-          "description": "后端生成的输出别名 ID;新增输出时可省略,get 返回后必须保留。",
+          "description": "后端生成的输出别名 ID;新增输出时省略,Builder 在首次写入后按 alias 与 path 自动回填再保存关系。更新已有输出时必须保留 get 返回值,不得自行编造或置空。",
           "minimum": 1,
           "type": "integer"
         },
@@ -494,7 +506,7 @@
         },
         "targetField": {
           "$ref": "#/$defs/FieldSelector",
-          "description": "接收结果的当前表单字段。"
+          "description": "接收结果的当前表单字段;该字段在整个应用的全部代码块和 Q-Linker outputs 中只能作为 targetField 出现一次,不得被多个输出关系重复写入。"
         }
       },
       "required": [
@@ -506,7 +518,7 @@
     },
     "DataRelationCondition": {
       "additionalProperties": false,
-      "description": "一条数据关联过滤条件。",
+      "description": "一条数据关联过滤条件;sourceField 必须属于数据来源,operator 必须适用于该字段类型。固定值请使用 literal operand,不要直接声明后端 matchRules。",
       "properties": {
         "operand": {
           "$ref": "#/$defs/DataRelationOperand",
@@ -632,7 +644,7 @@
       ]
     },
     "DataRelationFilters": {
-      "description": "simple 模式的外层组为 OR、组内条件为 AND;advanced 模式使用完整公式。",
+      "description": "simple 模式的外层组为 OR、组内条件为 AND;advanced 模式使用完整公式。simple 条件只声明业务值,builder 会生成后端保存所需的 judgeValues 和 judgeValueDetails,不要在声明中直接填写这两个后端属性。",
       "oneOf": [
         {
           "additionalProperties": false,
@@ -688,9 +700,9 @@
               "const": "literal"
             },
             "values": {
-              "description": "字面量值列表。",
+              "description": "固定比较值列表;值必须使用字符串。选择类来源字段填写已有选项的展示文本,builder 会在 apply 时解析为后端 optId;解析不到会在写入前报错。is_empty/is_not_empty 必须传空数组,其他运算符至少传一项。",
               "items": {
-                "$ref": "#/$defs/JsonValue"
+                "type": "string"
               },
               "type": "array"
             }
@@ -1189,15 +1201,71 @@
       "type": "object"
     },
     "FieldCommon": {
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "defaultType": {
+                "const": 2
+              }
+            },
+            "required": [
+              "defaultType"
+            ]
+          },
+          "then": {
+            "properties": {
+              "defaultValue": {
+                "type": "null"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "defaultType": {
+                "const": 3
+              }
+            },
+            "required": [
+              "defaultType"
+            ]
+          },
+          "then": {
+            "properties": {
+              "defaultValue": {
+                "minLength": 1,
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            }
+          }
+        }
+      ],
+      "anyOf": [
+        {
+          "required": [
+            "queId"
+          ]
+        },
+        {
+          "required": [
+            "name"
+          ]
+        }
+      ],
       "description": "顶层业务字段的公共属性;字段类型由 TopField 的判别分支定义。",
       "properties": {
-        "dataTitle": {
-          "description": "是否作为数据标题;整个 body 最多且必须按规则存在一个。",
+        "beingRequired": {
+          "description": "该字段是否必填;缺失时保留已有字段当前值。",
           "type": "boolean"
         },
         "defaultType": {
           "default": 1,
-          "description": "默认值类型;1 表示静态值,2 表示关联/绑定值,3 表示公式值。",
+          "description": "默认值类型,与 defaultValue 联动;1 表示静态值,2 表示关联/绑定值且 defaultValue 只能省略或为 null,3 表示公式值且提供 defaultValue 时必须为非空公式文本。省略 defaultType 但提供 defaultValue 时按 1 处理。",
           "enum": [
             1,
             2,
@@ -1207,39 +1275,40 @@
         },
         "defaultValue": {
           "$ref": "#/$defs/ScalarDefaultValue",
-          "description": "普通字段的标量默认值;表格、地址、附件、引用等结构化默认值必须放在具体字段 config.defaultValues。显式 null 表示清除默认值。"
-        },
-        "description": {
-          "description": "字段说明;null 或空字符串表示清空。",
-          "type": [
-            "string",
-            "null"
-          ]
+          "description": "普通字段的默认值;后端 queDefaultValue 为字符串,因此数字等字面量也必须以字符串传入。defaultType 为 1 时表示静态文本,为 3 时表示公式文本,为 2 时不携带字面量默认值。表格、地址、附件、引用等结构化默认值必须放在具体字段 config.defaultValues。显式 null 表示清除默认值。"
         },
         "name": {
-          "description": "字段展示名称;同一父级内唯一,不单独作为字段身份。",
+          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同一父级内唯一。",
           "minLength": 1,
           "type": "string"
         },
         "queId": {
-          "description": "已有字段的后端 ID;get 返回,新增字段省略。",
+          "description": "已有字段的后端 ID;更新时用于精确定位并复用,新增字段通常省略。",
           "minimum": 1,
           "type": "integer"
         },
-        "required": {
-          "description": "是否必填;缺失时保留已有字段当前值。",
-          "type": "boolean"
+        "questionDescription": {
+          "description": "字段说明;null 或空字符串表示清空。",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "questionType": {
+          "description": "字段类型;具体可用值由当前字段详情 Schema 的判别分支约束。",
+          "type": "string"
         },
         "width": {
-          "description": "字段在所在行的宽度百分比;同一行要么全部提供且合计 100,要么全部省略。",
-          "maximum": 100,
-          "minimum": 1,
+          "description": "字段在所在行的宽度百分比;只能选择 25、50、75 或 100。",
+          "enum": [
+            25,
+            50,
+            75,
+            100
+          ],
           "type": "integer"
         }
       },
-      "required": [
-        "name"
-      ],
       "type": "object"
     },
     "FieldRow": {
@@ -1275,7 +1344,7 @@
           ]
         }
       ],
-      "description": "跨字段引用选择器;至少提供 queId 或 name,两者同时提供时必须指向同一字段。",
+      "description": "字段选择器;用于定位应用的数据标题、数据封面、自定义编号取值来源或其他配置引用的字段。至少提供 queId 或 name,两者同时提供时必须指向同一字段。",
       "properties": {
         "name": {
           "description": "字段名称;仅在当前作用域内唯一时可用于解析。",
@@ -1290,6 +1359,11 @@
       },
       "type": "object"
     },
+    "FormulaExpression": {
+      "description": "轻流公式表达式的解码文本;字段引用形如 #queId_<queId>$,由后端 Formula 引擎解析。",
+      "minLength": 1,
+      "type": "string"
+    },
     "JsonValue": {
       "description": "数据关联字面量支持的任意 JSON 值。",
       "oneOf": [
@@ -1640,17 +1714,17 @@
     },
     "QLinkerBinding": {
       "additionalProperties": false,
-      "description": "Q-Linker 的输入映射、请求配置和输出映射。",
+      "description": "Q-Linker 的输入映射、请求配置和输出映射;每个输出目标还必须满足应用级唯一性规则,不能与任何 Q-Linker 或代码块的其他输出指向同一实际字段。多个生产方需要回写时,请选择不同目标字段或合并为一个生产方。",
       "properties": {
         "inputs": {
-          "description": "将当前表单字段映射到请求参数的规则。",
+          "description": "将当前表单字段映射到请求参数的规则。query_param、header、url_encoded 会直接生成对应位置的动态参数;json_path 用于替换 request.url、request.jsonValue 或 request.xmlValue 中的 {{key}} 占位符。",
           "items": {
             "$ref": "#/$defs/QLinkerInputBinding"
           },
           "type": "array"
         },
         "outputs": {
-          "description": "将响应路径映射到目标字段的规则;至少一个。",
+          "description": "将响应路径映射到目标字段的规则;至少一个。所有 targetField 在整个应用的 Q-Linker 和代码块输出中必须全局唯一。",
           "items": {
             "$ref": "#/$defs/QLinkerOutputBinding"
           },
@@ -1683,19 +1757,19 @@
     },
     "QLinkerInputBinding": {
       "additionalProperties": false,
-      "description": "一个表单字段到请求参数的映射。",
+      "description": "一个表单字段到请求参数的映射。需要把字段值嵌入 URL、JSON 或 XML 字符串时,source 必须为 json_path,key 必须等于所选字段名,并在对应请求字符串中写 {{key}};其他 source 不会替换 {{key}}。",
       "properties": {
         "field": {
           "$ref": "#/$defs/FieldSelector",
           "description": "输入来源字段。"
         },
         "key": {
-          "description": "请求中的参数名。",
+          "description": "请求参数名。source 为 json_path 时必须等于 field 选中的字段名,并与请求字符串中的 {{key}} 完全一致。",
           "minLength": 1,
           "type": "string"
         },
         "source": {
-          "description": "参数写入请求的位置。",
+          "description": "字段值的写入位置。query_param、header、url_encoded 分别生成动态查询参数、请求头、表单项;json_path 替换 URL、JSON 或 XML 中的 {{key}}。不要用前三种 source 提供字符串占位符。",
           "enum": [
             "query_param",
             "header",
@@ -1735,7 +1809,7 @@
     },
     "QLinkerOutputBinding": {
       "additionalProperties": false,
-      "description": "一个响应值到表单目标字段的映射。",
+      "description": "一个响应值到表单目标字段的映射;同一实际目标字段在整个应用中只能被一个 Q-Linker 或代码块输出映射写入。",
       "properties": {
         "alias": {
           "description": "输出别名;用于后续数据关联引用。",
@@ -1743,7 +1817,7 @@
           "type": "string"
         },
         "aliasId": {
-          "description": "后端生成的输出别名 ID;新增输出时可省略,get 返回后必须保留。",
+          "description": "后端生成的输出别名 ID;新增输出时省略,Builder 在首次写入后按 alias 与 path 自动回填再保存关系。更新已有输出时必须保留 get 返回值,不得自行编造或置空。",
           "minimum": 1,
           "type": "integer"
         },
@@ -1754,7 +1828,7 @@
         },
         "targetField": {
           "$ref": "#/$defs/FieldSelector",
-          "description": "接收结果的当前表单字段。"
+          "description": "接收结果的当前表单字段;该字段在整个应用的全部 Q-Linker 和代码块 outputs 中只能作为 targetField 出现一次,不得被多个输出关系重复写入。"
         }
       },
       "required": [
@@ -1820,7 +1894,7 @@
           ]
         },
         "jsonValue": {
-          "description": "bodyType 为 json 时的 JSON 请求体字符串。",
+          "description": "bodyType 为 json 时的 JSON 请求体字符串。动态字段值写成 {{key}},且 inputs 必须存在同名 source=json_path 映射;query_param、header、url_encoded 不会替换这里的占位符。",
           "type": [
             "string",
             "null"
@@ -1851,7 +1925,7 @@
           ]
         },
         "url": {
-          "description": "请求 URL。",
+          "description": "请求 URL;动态嵌入字段值时使用 {{key}},并在 inputs 中提供同名 source=json_path 映射。",
           "minLength": 1,
           "type": "string"
         },
@@ -1863,7 +1937,7 @@
           "type": "array"
         },
         "xmlValue": {
-          "description": "bodyType 为 xml 时的 XML 请求体字符串。",
+          "description": "bodyType 为 xml 时的 XML 请求体字符串。动态字段值写成 {{key}},且 inputs 必须存在同名 source=json_path 映射。",
           "type": [
             "string",
             "null"
@@ -1904,11 +1978,23 @@
       "description": "引用字段配置;引用其他应用中的数据。",
       "properties": {
         "beingDefaultFormulaAutoFillEnabled": {
+          "description": "是否启用引用字段的默认值公式自动填充。",
           "type": [
             "boolean",
             "null"
           ]
         },
+        "defaultValueFormula": {
+          "description": "引用字段默认值自动填充使用的公式;仅在 beingDefaultFormulaAutoFillEnabled 为 true 时执行,null 表示清除。",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/FormulaExpression"
+            }
+          ]
+        },
         "defaultValueMatchRules": {
           "type": [
             "array",
@@ -1999,11 +2085,9 @@
       "type": "object"
     },
     "ScalarDefaultValue": {
-      "description": "不包含对象或数组的普通字段默认值。",
+      "description": "后端 queDefaultValue 支持的普通字段默认值;非空值必须是字符串,显式 null 表示清除默认值。数字和布尔值应先转换为字符串,对象和数组必须使用字段专用默认值配置。defaultType 为 3 时,通过 AppForm Schema 查询能力传入当前 schema_version 并设置 schema_kind=formula 获取公式语法、字段引用、运算符和全部函数说明;CLI 使用 builder app-form schema --schema-kind formula。需要配置结构化默认值时,传入当前 schema_version,并将字段的 questionType 作为 field_type 获取字段详细 Schema。",
       "type": [
         "null",
-        "boolean",
-        "number",
         "string"
       ]
     },
@@ -2186,7 +2270,7 @@
             },
             "field": {
               "$ref": "#/$defs/FieldSelector",
-              "description": "取值来源字段。"
+              "description": "自定义编号中参与拼接的取值来源字段。"
             },
             "id": {
               "minimum": 1,
@@ -2257,57 +2341,6 @@
         }
       ]
     },
-    "Style": {
-      "additionalProperties": false,
-      "description": "表单背景和头部视觉样式;颜色使用 CSS 颜色字符串。",
-      "properties": {
-        "bgColor": {
-          "description": "表单背景色;null 表示清除。",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "bgImage": {
-          "description": "表单背景图片 URL;null 表示清除。",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "fontColor": {
-          "description": "表单头部字体颜色;null 表示清除。",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "headerColor": {
-          "description": "表单头部背景色;null 表示清除。",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "headerImage": {
-          "description": "表单头图 URL;null 表示清除。",
-          "type": [
-            "string",
-            "null"
-          ]
-        },
-        "opacity": {
-          "description": "背景透明度,取值 0 到 1;null 表示清除。",
-          "maximum": 1,
-          "minimum": 0,
-          "type": [
-            "number",
-            "null"
-          ]
-        }
-      },
-      "type": "object"
-    },
     "SubField": {
       "allOf": [
         {
@@ -2320,7 +2353,7 @@
                 "config": {
                   "$ref": "#/$defs/TextConfig"
                 },
-                "type": {
+                "questionType": {
                   "enum": [
                     "text",
                     "long_text",
@@ -2330,7 +2363,7 @@
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2338,12 +2371,12 @@
                 "config": {
                   "$ref": "#/$defs/PhoneConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "phone"
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2351,12 +2384,12 @@
                 "config": {
                   "$ref": "#/$defs/NumberConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "number"
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2364,12 +2397,12 @@
                 "config": {
                   "$ref": "#/$defs/EmptyConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "date"
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2377,12 +2410,12 @@
                 "config": {
                   "$ref": "#/$defs/AttachmentConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "attachment"
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2390,12 +2423,12 @@
                 "config": {
                   "$ref": "#/$defs/MemberConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "member"
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2403,7 +2436,7 @@
                 "config": {
                   "$ref": "#/$defs/ChoiceConfig"
                 },
-                "type": {
+                "questionType": {
                   "enum": [
                     "single_choice",
                     "single_select",
@@ -2412,7 +2445,7 @@
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "config"
               ]
             },
@@ -2421,12 +2454,12 @@
                 "config": {
                   "$ref": "#/$defs/DepartmentConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "department"
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "config"
               ]
             },
@@ -2435,12 +2468,12 @@
                 "config": {
                   "$ref": "#/$defs/RelationConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "relation"
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "config"
               ]
             },
@@ -2449,12 +2482,12 @@
                 "config": {
                   "$ref": "#/$defs/DataRelationConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "data_relation"
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "config"
               ]
             }
@@ -2466,11 +2499,71 @@
       "unevaluatedProperties": false
     },
     "SubFieldCommon": {
-      "description": "表格子字段的公共属性;不允许 dataTitle、dataCover 或 width。",
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "defaultType": {
+                "const": 2
+              }
+            },
+            "required": [
+              "defaultType"
+            ]
+          },
+          "then": {
+            "properties": {
+              "defaultValue": {
+                "type": "null"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "defaultType": {
+                "const": 3
+              }
+            },
+            "required": [
+              "defaultType"
+            ]
+          },
+          "then": {
+            "properties": {
+              "defaultValue": {
+                "minLength": 1,
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            }
+          }
+        }
+      ],
+      "anyOf": [
+        {
+          "required": [
+            "queId"
+          ]
+        },
+        {
+          "required": [
+            "name"
+          ]
+        }
+      ],
+      "description": "表格子字段的公共属性;不允许 width,也不能被应用级数据标题或数据封面选择器选中。",
       "properties": {
+        "beingRequired": {
+          "description": "该子字段是否必填;缺失时保留当前值。",
+          "type": "boolean"
+        },
         "defaultType": {
           "default": 1,
-          "description": "默认值类型;1 表示静态值,2 表示关联/绑定值,3 表示公式值。",
+          "description": "默认值类型,与 defaultValue 联动;1 表示静态值,2 表示关联/绑定值且 defaultValue 只能省略或为 null,3 表示公式值且提供 defaultValue 时必须为非空公式文本。省略 defaultType 但提供 defaultValue 时按 1 处理。",
           "enum": [
             1,
             2,
@@ -2479,41 +2572,31 @@
           "type": "integer"
         },
         "defaultValue": {
-          "description": "表单填写时的默认值;显式 null 表示清除默认值。",
-          "type": [
-            "null",
-            "boolean",
-            "number",
-            "string",
-            "array",
-            "object"
-          ]
-        },
-        "description": {
-          "description": "子字段说明;null 或空字符串表示清空。",
-          "type": [
-            "string",
-            "null"
-          ]
+          "$ref": "#/$defs/ScalarDefaultValue",
+          "description": "表单填写时的默认值;后端 queDefaultValue 为字符串,因此数字等字面量也必须以字符串传入。defaultType 为 1 时表示静态文本,为 3 时表示公式文本,为 2 时不携带字面量默认值。显式 null 表示清除默认值。"
         },
         "name": {
-          "description": "子字段展示名称;在所属表格内唯一。",
+          "description": "子字段展示名称;新增子字段必填,已有子字段可在携带 queId 时省略。",
           "minLength": 1,
           "type": "string"
         },
         "queId": {
-          "description": "已有子字段的后端 ID;新增时省略。",
+          "description": "已有子字段的后端 ID;更新时用于精确定位并复用,新增子字段通常省略。",
           "minimum": 1,
           "type": "integer"
         },
-        "required": {
-          "description": "是否必填;缺失时保留当前值。",
-          "type": "boolean"
+        "questionDescription": {
+          "description": "子字段说明;null 或空字符串表示清空。",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "questionType": {
+          "description": "子字段类型;具体可用值由当前字段详情 Schema 的判别分支约束。",
+          "type": "string"
         }
       },
-      "required": [
-        "name"
-      ],
       "type": "object"
     },
     "SubtableConfig": {
@@ -2616,7 +2699,7 @@
                 "config": {
                   "$ref": "#/$defs/EmptyConfig"
                 },
-                "type": {
+                "questionType": {
                   "enum": [
                     "date",
                     "datetime"
@@ -2624,7 +2707,7 @@
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2632,7 +2715,7 @@
                 "config": {
                   "$ref": "#/$defs/TextConfig"
                 },
-                "type": {
+                "questionType": {
                   "enum": [
                     "text",
                     "long_text",
@@ -2642,7 +2725,7 @@
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2650,12 +2733,12 @@
                 "config": {
                   "$ref": "#/$defs/PhoneConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "phone"
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2663,7 +2746,7 @@
                 "config": {
                   "$ref": "#/$defs/NumberConfig"
                 },
-                "type": {
+                "questionType": {
                   "enum": [
                     "number",
                     "amount"
@@ -2671,7 +2754,7 @@
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2679,12 +2762,12 @@
                 "config": {
                   "$ref": "#/$defs/MemberConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "member"
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2692,12 +2775,12 @@
                 "config": {
                   "$ref": "#/$defs/AddressConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "address"
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2705,15 +2788,12 @@
                 "config": {
                   "$ref": "#/$defs/AttachmentConfig"
                 },
-                "dataCover": {
-                  "type": "boolean"
-                },
-                "type": {
+                "questionType": {
                   "const": "attachment"
                 }
               },
               "required": [
-                "type"
+                "questionType"
               ]
             },
             {
@@ -2721,7 +2801,7 @@
                 "config": {
                   "$ref": "#/$defs/ChoiceConfig"
                 },
-                "type": {
+                "questionType": {
                   "enum": [
                     "single_choice",
                     "single_select",
@@ -2730,7 +2810,7 @@
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "config"
               ]
             },
@@ -2739,12 +2819,12 @@
                 "config": {
                   "$ref": "#/$defs/DepartmentConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "department"
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "config"
               ]
             },
@@ -2753,12 +2833,12 @@
                 "config": {
                   "$ref": "#/$defs/RelationConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "relation"
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "config"
               ]
             },
@@ -2767,12 +2847,12 @@
                 "config": {
                   "$ref": "#/$defs/QLinkerConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "q_linker"
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "config"
               ]
             },
@@ -2781,12 +2861,12 @@
                 "config": {
                   "$ref": "#/$defs/CodeBlockConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "code_block"
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "config"
               ]
             },
@@ -2795,12 +2875,12 @@
                 "config": {
                   "$ref": "#/$defs/DataRelationConfig"
                 },
-                "type": {
+                "questionType": {
                   "const": "data_relation"
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "config"
               ]
             },
@@ -2809,26 +2889,26 @@
                 "config": {
                   "$ref": "#/$defs/SubtableConfig"
                 },
+                "questionType": {
+                  "const": "subtable"
+                },
                 "subfields": {
                   "items": {
                     "$ref": "#/$defs/SubField"
                   },
                   "minItems": 1,
                   "type": "array"
-                },
-                "type": {
-                  "const": "subtable"
                 }
               },
               "required": [
-                "type",
+                "questionType",
                 "subfields"
               ]
             }
           ]
         }
       ],
-      "description": "顶层业务字段;type 决定 config 或 subfields 的结构。",
+      "description": "顶层业务字段;questionType 决定 config 或 subfields 的结构。",
       "type": "object",
       "unevaluatedProperties": false
     }
@@ -2837,24 +2917,6 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "oneOf": [
     {
-      "properties": {
-        "spec": {
-          "not": {
-            "anyOf": [
-              {
-                "required": [
-                  "icon"
-                ]
-              },
-              {
-                "required": [
-                  "color"
-                ]
-              }
-            ]
-          }
-        }
-      },
       "required": [
         "appKey"
       ]
@@ -2868,9 +2930,7 @@
       "properties": {
         "spec": {
           "required": [
-            "appName",
-            "icon",
-            "color"
+            "appName"
           ]
         }
       },
@@ -2882,7 +2942,7 @@
   "properties": {
     "apiVersion": {
       "const": "builder.qingflow.com/v1alpha1",
-      "description": "AppForm 契约版本;一期固定为 v1alpha1。"
+      "description": "AppForm 契约版本;当前固定为 v1alpha1。"
     },
     "appKey": {
       "description": "更新已有应用的唯一标识;存在非空值即进入更新模式。",