@qingflow-tech/qingflow-cli 1.1.51 → 1.1.54

package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/rich_text.json

@@ -0,0 +1,146 @@
+{
+  "$defs": {
+    "EmptyConfig": {
+      "additionalProperties": false,
+      "description": "该字段类型没有特殊配置。",
+      "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": {
+        "beingRequired": {
+          "description": "该字段是否必填;缺失时保留已有字段当前值。",
+          "type": "boolean"
+        },
+        "defaultType": {
+          "default": 1,
+          "description": "默认值类型,与 defaultValue 联动;1 表示静态值,2 表示关联/绑定值且 defaultValue 只能省略或为 null,3 表示公式值且提供 defaultValue 时必须为非空公式文本。省略 defaultType 但提供 defaultValue 时按 1 处理。",
+          "enum": [
+            1,
+            2,
+            3
+          ],
+          "type": "integer"
+        },
+        "defaultValue": {
+          "$ref": "#/$defs/ScalarDefaultValue",
+          "description": "普通字段的默认值;后端 queDefaultValue 为字符串,因此数字等字面量也必须以字符串传入。defaultType 为 1 时表示静态文本,为 3 时表示公式文本,为 2 时不携带字面量默认值。表格、地址、附件、引用等结构化默认值必须放在具体字段 config.defaultValues。显式 null 表示清除默认值。"
+        },
+        "name": {
+          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同父级允许同名(后端以 queId 为字段身份),配置引用建议携带 queId。",
+          "minLength": 1,
+          "type": "string"
+        },
+        "queId": {
+          "description": "已有字段的后端 ID;更新时用于精确定位并复用,新增字段通常省略。",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "questionDescription": {
+          "description": "字段说明;null 或空字符串表示清空。",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "questionType": {
+          "description": "字段类型;具体可用值由当前字段详情 Schema 的判别分支约束。",
+          "type": "string"
+        },
+        "width": {
+          "description": "字段在所在行的宽度百分比(1-100 整数);后端不校验总和与取值,存量数据存在 33/34 等三等分布值。",
+          "maximum": 100,
+          "minimum": 1,
+          "type": "integer"
+        }
+      },
+      "type": "object"
+    },
+    "ScalarDefaultValue": {
+      "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",
+        "string"
+      ]
+    }
+  },
+  "$id": "https://builder.qingflow.com/schemas/app-form-apply/v1alpha1/fields/rich_text.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    {
+      "$ref": "#/$defs/FieldCommon"
+    },
+    {
+      "properties": {
+        "config": {
+          "$ref": "#/$defs/EmptyConfig"
+        },
+        "questionType": {
+          "const": "rich_text"
+        }
+      },
+      "required": [
+        "questionType"
+      ]
+    }
+  ],
+  "title": "Qingflow AppForm v1alpha1 rich_text field",
+  "type": "object",
+  "unevaluatedProperties": false
+}

package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_choice.json

@@ -146,7 +146,7 @@
           "description": "普通字段的默认值;后端 queDefaultValue 为字符串,因此数字等字面量也必须以字符串传入。defaultType 为 1 时表示静态文本,为 3 时表示公式文本,为 2 时不携带字面量默认值。表格、地址、附件、引用等结构化默认值必须放在具体字段 config.defaultValues。显式 null 表示清除默认值。"
         },
         "name": {
-          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同一父级内唯一。",
+          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同父级允许同名(后端以 queId 为字段身份),配置引用建议携带 queId。",
           "minLength": 1,
           "type": "string"
         },
@@ -167,13 +167,9 @@
           "type": "string"
         },
         "width": {
-          "description": "字段在所在行的宽度百分比;只能选择 25、50、75 或 100。",
-          "enum": [
-            25,
-            50,
-            75,
-            100
-          ],
+          "description": "字段在所在行的宽度百分比(1-100 整数);后端不校验总和与取值,存量数据存在 33/34 等三等分布值。",
+          "maximum": 100,
+          "minimum": 1,
           "type": "integer"
         }
       },

package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/single_select.json

@@ -146,7 +146,7 @@
           "description": "普通字段的默认值;后端 queDefaultValue 为字符串,因此数字等字面量也必须以字符串传入。defaultType 为 1 时表示静态文本,为 3 时表示公式文本,为 2 时不携带字面量默认值。表格、地址、附件、引用等结构化默认值必须放在具体字段 config.defaultValues。显式 null 表示清除默认值。"
         },
         "name": {
-          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同一父级内唯一。",
+          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同父级允许同名(后端以 queId 为字段身份),配置引用建议携带 queId。",
           "minLength": 1,
           "type": "string"
         },
@@ -167,13 +167,9 @@
           "type": "string"
         },
         "width": {
-          "description": "字段在所在行的宽度百分比;只能选择 25、50、75 或 100。",
-          "enum": [
-            25,
-            50,
-            75,
-            100
-          ],
+          "description": "字段在所在行的宽度百分比(1-100 整数);后端不校验总和与取值,存量数据存在 33/34 等三等分布值。",
+          "maximum": 100,
+          "minimum": 1,
           "type": "integer"
         }
       },

package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/subtable.json

@@ -111,7 +111,7 @@
           ]
         },
         "fileSize": {
-          "minimum": 1,
+          "minimum": 0,
           "type": [
             "integer",
             "null"
@@ -131,7 +131,7 @@
           ]
         },
         "maxFileLimit": {
-          "minimum": 1,
+          "minimum": 0,
           "type": [
             "integer",
             "null"
@@ -229,7 +229,7 @@
     },
     "DataRelationCondition": {
       "additionalProperties": false,
-      "description": "一条数据关联过滤条件;sourceField 必须属于数据来源,operator 必须适用于该字段类型。固定值请使用 literal operand,不要直接声明后端 matchRules。",
+      "description": "一条数据关联过滤条件;sourceField 必须属于数据来源,operator 必须适用于该字段类型。固定值请使用 literal operand,不要直接声明后端 matchRules。sourceField 省略为存量读回形态(历史脏公式的源字段缺失,如 #queId_0$,写回时以 queId=0 透传),新建条件应提供 sourceField。",
       "properties": {
         "operand": {
           "$ref": "#/$defs/DataRelationOperand",
@@ -265,11 +265,10 @@
         },
         "sourceField": {
           "$ref": "#/$defs/FieldSelector",
-          "description": "被过滤的数据源字段。"
+          "description": "被过滤的数据源字段;存量读回形态可能缺失(后端反解析出的条件源字段 queId=0 且无名称)。"
         }
       },
       "required": [
-        "sourceField",
         "operator",
         "operand"
       ],
@@ -277,7 +276,7 @@
     },
     "DataRelationConfig": {
       "additionalProperties": false,
-      "description": "数据关联字段配置;从应用、Q-Linker 或代码块输出中读取数据。",
+      "description": "数据关联字段配置;从应用、Q-Linker 或代码块输出中读取数据。source 省略表示该字段当前无关联来源配置(存量表单读回形态:后端 GET 对 displayed 目标缺失的 relation 行不回传,FormSvcImpl#getQuestionRelationsBeans continue 分支;新建数据关联字段应提供 source)。",
       "properties": {
         "aggregation": {
           "description": "可选聚合方式;null 表示不聚合。",
@@ -312,12 +311,10 @@
         },
         "source": {
           "$ref": "#/$defs/DataRelationSource",
-          "description": "数据来源;按 kind 选择一种来源结构。"
+          "description": "数据来源;按 kind 选择一种来源结构。存量读回形态可能无 source(后端读面不回传关联配置),此时写回不重建该字段的关联。"
         }
       },
-      "required": [
-        "source"
-      ],
+      "required": [],
       "type": "object"
     },
     "DataRelationCustomButton": {
@@ -989,7 +986,7 @@
           "description": "普通字段的默认值;后端 queDefaultValue 为字符串,因此数字等字面量也必须以字符串传入。defaultType 为 1 时表示静态文本,为 3 时表示公式文本,为 2 时不携带字面量默认值。表格、地址、附件、引用等结构化默认值必须放在具体字段 config.defaultValues。显式 null 表示清除默认值。"
         },
         "name": {
-          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同一父级内唯一。",
+          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同父级允许同名(后端以 queId 为字段身份),配置引用建议携带 queId。",
           "minLength": 1,
           "type": "string"
         },
@@ -1010,13 +1007,9 @@
           "type": "string"
         },
         "width": {
-          "description": "字段在所在行的宽度百分比;只能选择 25、50、75 或 100。",
-          "enum": [
-            25,
-            50,
-            75,
-            100
-          ],
+          "description": "字段在所在行的宽度百分比(1-100 整数);后端不校验总和与取值,存量数据存在 33/34 等三等分布值。",
+          "maximum": 100,
+          "minimum": 1,
           "type": "integer"
         }
       },
@@ -1036,10 +1029,10 @@
           ]
         }
       ],
-      "description": "字段选择器;用于定位应用的数据标题、数据封面、自定义编号取值来源或其他配置引用的字段。至少提供 queId 或 name,两者同时提供时必须指向同一字段。",
+      "description": "字段选择器;用于定位应用的数据标题、数据封面、自定义编号取值来源或其他配置引用的字段。至少提供 queId 或 name,两者同时提供时必须指向同一字段。后端允许同父级同名字段,queId 是稳定身份;name 仅在唯一时可解析,命中多个同名时报 AMBIGUOUS_FIELD_SELECTOR,此时必须改用 queId。",
       "properties": {
         "name": {
-          "description": "字段名称;仅在当前作用域内唯一时可用于解析。",
+          "description": "字段名称;仅在当前作用域内唯一时可用于解析,同名命中多个字段时报 AMBIGUOUS_FIELD_SELECTOR,应改用 queId。",
           "minLength": 1,
           "type": "string"
         },
@@ -1401,7 +1394,7 @@
     },
     "RelationConfig": {
       "additionalProperties": false,
-      "description": "引用字段配置;引用其他应用中的数据。",
+      "description": "引用字段配置;引用其他应用中的数据。展示字段与权限以 displayFields 为准(后端 referQuestions 全量有序回写,queAuth 1=可编辑/2=隐藏/3=仅可见);displayField/visibleFields 为已废弃旧形态,apply 兼容接收一个版本窗口(displayField 同时视为双向绑定目标)。",
       "properties": {
         "beingDefaultFormulaAutoFillEnabled": {
           "description": "是否启用引用字段的默认值公式自动填充。",
@@ -1439,7 +1432,32 @@
         },
         "displayField": {
           "$ref": "#/$defs/FieldSelector",
-          "description": "引用值的主展示字段。"
+          "description": "已废弃:主展示字段;apply 兼容翻译为 twoWayBoundField + displayFields 首项,后续版本移除。"
+        },
+        "displayFields": {
+          "description": "有序展示字段全量列表(含隐藏字段),按 ordinal 保序回写为后端 referQuestions。可为空列表:空 = 双向绑定未配展示字段的合法存量形态(后端写链路对空 referQuestions 跳过插入、读面容忍空),round-trip 空↔空稳定;与已废弃 displayField/visibleFields 不可混用,条目 queId 不可重复。",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "auth": {
+                "default": "visible",
+                "description": "展示字段权限;editable=可编辑(1), hidden=隐藏(2), visible=仅可见(3);缺失按 visible。",
+                "enum": [
+                  "editable",
+                  "hidden",
+                  "visible"
+                ]
+              },
+              "field": {
+                "$ref": "#/$defs/FieldSelector"
+              }
+            },
+            "required": [
+              "field"
+            ],
+            "type": "object"
+          },
+          "type": "array"
         },
         "relationMode": {
           "default": "single",
@@ -1454,8 +1472,19 @@
           "minLength": 1,
           "type": "string"
         },
+        "twoWayBoundField": {
+          "description": "双向引用绑定的目标字段(后端 referQueId);null/省略 = 单向引用。get 读面在 referQueId 非空时必产出。",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "$ref": "#/$defs/FieldSelector"
+            }
+          ]
+        },
         "visibleFields": {
-          "description": "引用选择界面额外展示的字段。",
+          "description": "已废弃:额外展示字段;apply 兼容翻译为 displayFields 后续项,后续版本移除。",
           "items": {
             "$ref": "#/$defs/FieldSelector"
           },
@@ -1464,8 +1493,7 @@
         }
       },
       "required": [
-        "targetAppKey",
-        "displayField"
+        "targetAppKey"
       ],
       "type": "object"
     },
@@ -1584,7 +1612,10 @@
                   "$ref": "#/$defs/NumberConfig"
                 },
                 "questionType": {
-                  "const": "number"
+                  "enum": [
+                    "number",
+                    "amount"
+                  ]
                 }
               },
               "required": [
@@ -1597,7 +1628,10 @@
                   "$ref": "#/$defs/EmptyConfig"
                 },
                 "questionType": {
-                  "const": "date"
+                  "enum": [
+                    "date",
+                    "datetime"
+                  ]
                 }
               },
               "required": [

package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/text.json

@@ -78,7 +78,7 @@
           "description": "普通字段的默认值;后端 queDefaultValue 为字符串,因此数字等字面量也必须以字符串传入。defaultType 为 1 时表示静态文本,为 3 时表示公式文本,为 2 时不携带字面量默认值。表格、地址、附件、引用等结构化默认值必须放在具体字段 config.defaultValues。显式 null 表示清除默认值。"
         },
         "name": {
-          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同一父级内唯一。",
+          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同父级允许同名(后端以 queId 为字段身份),配置引用建议携带 queId。",
           "minLength": 1,
           "type": "string"
         },
@@ -99,13 +99,9 @@
           "type": "string"
         },
         "width": {
-          "description": "字段在所在行的宽度百分比;只能选择 25、50、75 或 100。",
-          "enum": [
-            25,
-            50,
-            75,
-            100
-          ],
+          "description": "字段在所在行的宽度百分比(1-100 整数);后端不校验总和与取值,存量数据存在 33/34 等三等分布值。",
+          "maximum": 100,
+          "minimum": 1,
           "type": "integer"
         }
       },

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

@@ -236,6 +236,28 @@
         "DATEDELTA(date, number, unit)"
       ]
     },
+    "DATEDIF": {
+      "category": "date",
+      "example": "DATEDIF(#queId_102$, #queId_101$)",
+      "meaning": "历史日期差函数名，仅存在于存量公式中（当前公式引擎未注册，日期差请使用 DAYS(end, start)）。为使存量声明的 validate/round-trip 通过而保留声明，不建议新公式使用。",
+      "parameters": [
+        {
+          "description": "结束日期或列表",
+          "name": "end"
+        },
+        {
+          "description": "开始日期或列表",
+          "name": "start"
+        }
+      ],
+      "returns": {
+        "description": "天数差文本列表",
+        "type": "list"
+      },
+      "signatures": [
+        "DATEDIF(end, start)"
+      ]
+    },
     "DATETOTIMESTAMP": {
       "category": "date",
       "example": "DATETOTIMESTAMP(#queId_101$)",
@@ -363,6 +385,19 @@
         "GETUSEREMAIL()"
       ]
     },
+    "GETUSERENAME": {
+      "category": "context",
+      "example": "GETUSERENAME()",
+      "meaning": "历史拼写（GETUSERNAME 的讹写），仅存在于存量公式中（当前公式引擎未注册，请使用 GETUSERNAME()）。为使存量声明的 validate/round-trip 通过而保留声明，不建议新公式使用。",
+      "parameters": [],
+      "returns": {
+        "description": "当前用户显示名称；无法取得时为空字符串",
+        "type": "string"
+      },
+      "signatures": [
+        "GETUSERENAME()"
+      ]
+    },
     "GETUSERNAME": {
       "category": "context",
       "example": "GETUSERNAME()",
@@ -1590,5 +1625,13 @@
       "需要拼接字段当前值时，将该字段的实际 queId 写成未加引号的 #queId_<字段ID>$；字段 name、字段标题和字段默认值都不能替代字段引用。",
       "新建应用的同一次 create 声明中尚未获得 queId 时，不得虚构 queId 或以字段 name 代替：先创建字段，app_form_get 回读实际 queId 后，再提交公式默认值更新。"
     ]
+  },
+  "x-qingflow-validation": {
+    "functionCallPolicy": "validate 会识别公式文本中引号外的 函数名( 调用；函数名必须在 x-qingflow-functions 中声明。未知函数会被拒绝，字符串字面量中的 NAME() 不视为函数调用。",
+    "scope": [
+      "defaultType=3 的 defaultValue",
+      "config.defaultValueFormula",
+      "data_relation config.filters.mode=advanced 的 config.filters.formula"
+    ]
   }
 }

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

@@ -136,10 +136,10 @@
           ]
         }
       ],
-      "description": "字段选择器;用于定位应用的数据标题、数据封面、自定义编号取值来源或其他配置引用的字段。至少提供 queId 或 name,两者同时提供时必须指向同一字段。",
+      "description": "字段选择器;用于定位应用的数据标题、数据封面、自定义编号取值来源或其他配置引用的字段。至少提供 queId 或 name,两者同时提供时必须指向同一字段。后端允许同父级同名字段,queId 是稳定身份;name 仅在唯一时可解析,命中多个同名时报 AMBIGUOUS_FIELD_SELECTOR,此时必须改用 queId。",
       "properties": {
         "name": {
-          "description": "字段名称;仅在当前作用域内唯一时可用于解析。",
+          "description": "字段名称;仅在当前作用域内唯一时可用于解析,同名命中多个字段时报 AMBIGUOUS_FIELD_SELECTOR,应改用 queId。",
           "minLength": 1,
           "type": "string"
         },
@@ -258,13 +258,9 @@
           "type": "array"
         },
         "width": {
-          "description": "字段在所在行的宽度百分比;只能选择 25、50、75 或 100。",
-          "enum": [
-            25,
-            50,
-            75,
-            100
-          ],
+          "description": "字段在所在行的宽度百分比(1-100 整数);后端不校验总和与取值,存量数据存在 33/34 等三等分布值。",
+          "maximum": 100,
+          "minimum": 1,
           "type": "integer"
         }
       },
@@ -334,11 +330,10 @@
           "description": "段落判别值。"
         },
         "rows": {
-          "description": "段落内的非空有序字段行。",
+          "description": "段落内的有序字段行;可为空数组(空 = 存量空段落形态,后端容忍,round-trip 空↔空稳定)。",
           "items": {
             "$ref": "#/$defs/FieldRow"
           },
-          "minItems": 1,
           "type": "array"
         },
         "sectionId": {
@@ -383,7 +378,6 @@
             ],
             "type": "object"
           },
-          "minItems": 1,
           "type": "array"
         },
         "sectionId": {
@@ -695,6 +689,7 @@
   "x-qingflow-supported-field-types": [
     "text",
     "long_text",
+    "rich_text",
     "number",
     "amount",
     "link",

package/src/qingflow_mcp/builder_facade/schemas/views/manifest.json

@@ -0,0 +1,42 @@
+{
+  "manifestDescription": "面向 app_views_apply 的版本化公开视图契约。summary 提供最小声明，complete 覆盖当前可写能力，details 提供按配置域读取的自包含专项 Schema。后端已知但尚不可写的能力以说明性元数据列出，不会被误报为公开能力。",
+  "latestVersion": "v1alpha1",
+  "versions": {
+    "v1alpha1": {
+      "versionDescription": "AI 和 CLI/MCP 使用的 canonical views DSL。字段名、更新语义和约束与 app_views_apply 对齐；schema 返回会内联专项 Schema 的依赖定义。",
+      "apiVersion": "builder.qingflow.com/v1alpha1",
+      "applyDto": "v1alpha1",
+      "contractSource": "app_views_apply",
+      "contractVersion": "v1alpha1",
+      "enabledByDefault": true,
+      "schemaKinds": [
+        "summary",
+        "complete",
+        "display",
+        "data-permission",
+        "operation-permission",
+        "query-condition",
+        "button-config"
+      ],
+      "schemaFiles": {
+        "summary": "v1alpha1/summary.json",
+        "complete": "v1alpha1/complete.json",
+        "display": "v1alpha1/details/display.json",
+        "data-permission": "v1alpha1/details/data-permission.json",
+        "operation-permission": "v1alpha1/details/operation-permission.json",
+        "query-condition": "v1alpha1/details/query-condition.json",
+        "button-config": "v1alpha1/details/button-config.json"
+      },
+      "viewTypes": [
+        "table",
+        "card",
+        "board",
+        "gantt",
+        "hierarchy",
+        "calendar"
+      ],
+      "backendKnownUnsupportedViewTypes": [],
+      "status": "active"
+    }
+  }
+}