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

package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/q_linker.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"
         },
@@ -121,10 +121,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"
         },

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

@@ -258,7 +258,7 @@
           "description": "普通字段的默认值;后端 queDefaultValue 为字符串,因此数字等字面量也必须以字符串传入。defaultType 为 1 时表示静态文本,为 3 时表示公式文本,为 2 时不携带字面量默认值。表格、地址、附件、引用等结构化默认值必须放在具体字段 config.defaultValues。显式 null 表示清除默认值。"
         },
         "name": {
-          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同一父级内唯一。",
+          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同父级允许同名(后端以 queId 为字段身份),配置引用建议携带 queId。",
           "minLength": 1,
           "type": "string"
         },
@@ -301,10 +301,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"
         },

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

@@ -83,7 +83,7 @@
           "description": "普通字段的默认值;后端 queDefaultValue 为字符串,因此数字等字面量也必须以字符串传入。defaultType 为 1 时表示静态文本,为 3 时表示公式文本,为 2 时不携带字面量默认值。表格、地址、附件、引用等结构化默认值必须放在具体字段 config.defaultValues。显式 null 表示清除默认值。"
         },
         "name": {
-          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同一父级内唯一。",
+          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同父级允许同名(后端以 queId 为字段身份),配置引用建议携带 queId。",
           "minLength": 1,
           "type": "string"
         },

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

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

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

@@ -986,7 +986,7 @@
           "description": "普通字段的默认值;后端 queDefaultValue 为字符串,因此数字等字面量也必须以字符串传入。defaultType 为 1 时表示静态文本,为 3 时表示公式文本,为 2 时不携带字面量默认值。表格、地址、附件、引用等结构化默认值必须放在具体字段 config.defaultValues。显式 null 表示清除默认值。"
         },
         "name": {
-          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同一父级内唯一。",
+          "description": "字段展示名称;新增字段必填,已有字段可在携带 queId 时省略;同父级允许同名(后端以 queId 为字段身份),配置引用建议携带 queId。",
           "minLength": 1,
           "type": "string"
         },
@@ -1029,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"
         },

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

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()",

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

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

@@ -32,11 +32,10 @@
         "card",
         "board",
         "gantt",
-        "hierarchy"
-      ],
-      "backendKnownUnsupportedViewTypes": [
+        "hierarchy",
         "calendar"
       ],
+      "backendKnownUnsupportedViewTypes": [],
       "status": "active"
     }
   }

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://qingflow.com/schemas/builder/views/v1alpha1/complete.json",
   "title": "Qingflow Builder Views Declaration · complete (v1alpha1)",
-  "viewCompleteDescription": "视图完整声明(完整版 spec):summary 的严格超集,覆盖 app_views_apply 当前支持的公开语义——数据权限/可见性授权/筛选/排序/查询条件/按钮配置/关联资源/类型特有配置(card/gantt/hierarchy)/展示与记录开关/分享安全。展示、排序、筛选和类型专属字段使用整数 queId;查询条件 rows 兼容字段名或 ID。打印模板明细、附件权限、列级权限、高级筛选公式和 calendar 尚未进入公开写入契约。schema 校验在别名归一之后执行,只约束规范名。各配置域的专项 Schema(含清空/替换语义)通过 app_views_schema 换 schema_kind 获取(见 x-qingflow-related-schemas)。",
+  "viewCompleteDescription": "视图完整声明(完整版 spec):summary 的严格超集,覆盖 app_views_apply 当前支持的公开语义——数据权限/可见性授权/筛选/排序/查询条件/按钮配置/关联资源/类型特有配置(card/gantt/hierarchy/calendar)/展示与记录开关/分享安全。展示、排序、筛选和类型专属字段使用整数 queId;查询条件 rows 兼容字段名或 ID。打印模板明细、附件权限、列级权限和高级筛选公式尚未进入公开写入契约。schema 校验在别名归一之后执行,只约束规范名。各配置域的专项 Schema(含清空/替换语义)通过 app_views_schema 换 schema_kind 获取(见 x-qingflow-related-schemas)。",
   "$defs": {
     "ViewDeclaration": {
       "type": "object",
@@ -26,6 +26,7 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 200,
+          "viewNameDescription": "视图名称;未提供 view_key 时按 name 唯一匹配决定更新或创建,重名报 AMBIGUOUS_VIEW。",
           "x-backend": "viewgraphName"
         },
         "type": {
@@ -35,10 +36,11 @@
             "card",
             "board",
             "gantt",
-            "hierarchy"
+            "hierarchy",
+            "calendar"
           ],
-          "viewTypeDescription": "完整版在四公开类型之上增加 hierarchy(层级视图;summary 档不含,dataset-v0 有 2 例)。",
-          "x-backend": "viewgraphType(tableView/cardView/boardView/ganttView/hierarchyView)"
+          "viewTypeDescription": "支持表格、卡片、看板、甘特、层级和日历视图。",
+          "x-backend": "viewgraphType(tableView/cardView/boardView/ganttView/hierarchyView/calendarView)"
         },
         "columns": {
           "type": "array",
@@ -134,6 +136,11 @@
           "hierarchyDescription": "层级视图特有配置(hierarchy 类型适用,必填)。",
           "x-backend": "viewgraphHierarchyConfigVO(titleQueId/childrenQueId/rootNodeFilter)"
         },
+        "calendar": {
+          "$ref": "#/$defs/CalendarConfig",
+          "calendarDescription": "日历视图特有配置(calendar 类型适用,必填)。",
+          "x-backend": "viewgraphCalendarConfigVO(titleQueId/dateQueId/colorQueId)"
+        },
         "display": {
           "$ref": "#/$defs/DisplayConfig",
           "displayDescription": "展示杂项:行高/固定导航/备注。",
@@ -291,6 +298,13 @@
               "hierarchy"
             ]
           }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "calendar" } },
+            "required": ["type"]
+          },
+          "then": { "required": ["calendar"] }
         }
       ]
     },
@@ -497,10 +511,12 @@
         "ascending": {
           "type": "boolean",
           "default": true,
+          "ascendingDescription": "是否升序;默认 true。",
           "x-backend": "beingSortAscend"
         },
         "que_id": {
           "type": "integer",
+          "queIdDescription": "排序字段 queId。别名 fieldName/field/name。",
           "x-backend": "ViewgraphSortQuestion.queId"
         }
       }
@@ -512,11 +528,13 @@
         "enabled": {
           "type": "boolean",
           "default": true,
+          "enabledDescription": "是否开启查询面板。",
           "x-backend": "queryConditionStatus"
         },
         "exact": {
           "type": "boolean",
           "default": false,
+          "exactDescription": "是否精确匹配;true=多条件同时满足,false=任一满足。",
           "x-backend": "queryConditionExact"
         },
         "hide_before_query": {
@@ -709,7 +727,7 @@
         },
         "button_id": {
           "type": "integer",
-          "buttonIdDescription": "按钮 id。别名 buttonId/id。",
+          "buttonIdDescription": "按钮 id(创建前先 app_get_buttons 传 button_text 查重,唯一命中直接复用本 id;未命中才用 app_custom_buttons_apply 创建)。别名 buttonId/id。",
           "x-backend": "button_config.id / custom_button_id"
         },
         "button_text": {
@@ -813,31 +831,37 @@
             "default",
             "fill"
           ],
+          "clippingModeDescription": "封面裁剪模式:default=默认,fill=填充。",
           "x-backend": "clippingMode(default 实测)"
         },
         "image_adaption": {
           "type": "boolean",
           "default": false,
+          "imageAdaptionDescription": "封面图是否自适应尺寸。",
           "x-backend": "beingImageAdaption"
         },
         "show_field_title": {
           "type": "boolean",
           "default": true,
+          "showFieldTitleDescription": "是否显示字段标题。",
           "x-backend": "beingShowQueTitle"
         },
         "show_title": {
           "type": "boolean",
           "default": true,
+          "showTitleDescription": "是否显示卡片标题。",
           "x-backend": "beingShowTitleQue"
         },
         "show_cover": {
           "type": "boolean",
           "default": false,
+          "showCoverDescription": "是否显示封面图。",
           "x-backend": "beingShowCover"
         },
         "group_color": {
           "type": "boolean",
           "default": false,
+          "groupColorDescription": "分组是否显示颜色标识。",
           "x-backend": "beingGroupColor"
         },
         "group_que_id": {
@@ -870,6 +894,7 @@
             "year"
           ],
           "default": "month",
+          "defaultTimeDimensionDescription": "默认时间维度:day/week/month/year。",
           "x-backend": "defaultTimeDimension(month×8/week×4 实测)"
         },
         "auto_calibration": {
@@ -880,16 +905,18 @@
         },
         "groups": {
           "type": "array",
+          "groupsDescription": "甘特分组字段列表,按 ordinal 排序。",
           "items": {
             "type": "object",
             "additionalProperties": false,
             "properties": {
               "ordinal": {
-                "type": "integer"
+                "type": "integer",
+                "ordinalDescription": "分组展示顺序。"
               },
               "que_id": {
                 "type": "integer",
-                "minLength": 1
+                "queIdDescription": "分组字段 queId。"
               }
             }
           },
@@ -898,6 +925,7 @@
         "dependencies": {
           "type": "array",
           "maxItems": 1,
+          "dependenciesDescription": "任务依赖关系;后端为单对象,v1alpha1 限 1 条。",
           "items": {
             "$ref": "#/$defs/GanttDependency"
           },
@@ -905,14 +933,17 @@
         },
         "start_que_id": {
           "type": "integer",
+          "startQueIdDescription": "甘特开始时间字段 queId;与顶层 start_que_id 等价,取其一。",
           "x-backend": "startTimeQueId"
         },
         "end_que_id": {
           "type": "integer",
+          "endQueIdDescription": "甘特结束时间字段 queId;与顶层 end_que_id 等价,取其一。",
           "x-backend": "endTimeQueId"
         },
         "title_que_id": {
           "type": "integer",
+          "titleQueIdDescription": "甘特标题字段 queId;与顶层 title_que_id 等价。",
           "x-backend": "titleQueId"
         }
       }
@@ -927,28 +958,32 @@
       "properties": {
         "start_start_option_id": {
           "type": "integer",
+          "startStartOptionIdDescription": "开始→开始依赖的偏移选项 id(可选)。",
           "x-backend": "startStartOptionId"
         },
         "start_end_option_id": {
           "type": "integer",
+          "startEndOptionIdDescription": "开始→结束依赖的偏移选项 id(可选)。",
           "x-backend": "startEndOptionId"
         },
         "end_start_option_id": {
           "type": "integer",
+          "endStartOptionIdDescription": "结束→开始依赖的偏移选项 id(可选)。",
           "x-backend": "endStartOptionId"
         },
         "end_end_option_id": {
           "type": "integer",
+          "endEndOptionIdDescription": "结束→结束依赖的偏移选项 id(可选)。",
           "x-backend": "endEndOptionId"
         },
         "dependency_que_id": {
           "type": "integer",
-          "minLength": 1,
+          "dependencyQueIdDescription": "被依赖(后续)任务的关联字段 queId。",
           "x-backend": "dependencyQueId"
         },
         "predecessor_que_id": {
           "type": "integer",
-          "minLength": 1,
+          "predecessorQueIdDescription": "前置任务的关联字段 queId。",
           "x-backend": "predecessorTaskQueId"
         }
       }
@@ -974,14 +1009,26 @@
         },
         "title_que_id": {
           "type": "integer",
+          "titleQueIdDescription": "层级标题字段 queId。",
           "x-backend": "viewgraph_hierarchy_config.titleQueId"
         },
         "children_que_id": {
           "type": "integer",
+          "childrenQueIdDescription": "子节点关联字段 queId(引用/关联字段)。",
           "x-backend": "childrenQueId"
         }
       }
     },
+    "CalendarConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title_que_id", "date_que_id"],
+      "properties": {
+        "title_que_id": { "type": "integer", "calendarTitleQueIdDescription": "日历事项标题字段 queId。", "x-backend": "titleQueId" },
+        "date_que_id": { "type": "integer", "calendarDateQueIdDescription": "日历日期字段 queId；可使用表单日期字段或系统字段申请时间(2)/更新时间(3)。", "x-backend": "dateQueId" },
+        "color_que_id": { "type": "integer", "calendarColorQueIdDescription": "可选的日历颜色字段 queId。", "x-backend": "colorQueId" }
+      }
+    },
     "DisplayConfig": {
       "type": "object",
       "additionalProperties": false,
@@ -994,15 +1041,18 @@
             "highest",
             "high"
           ],
+          "rowHeightDescription": "表格行高:compact=紧凑,moderate=适中,high=高,highest=最高。",
           "x-backend": "defaultRowHigh(compact×705 实测)"
         },
         "pin_navigate": {
           "type": "boolean",
           "default": false,
+          "pinNavigateDescription": "是否固定视图内导航;与顶层 pinned(视图列表固定)无关。",
           "x-backend": "beingPinNavigate"
         },
         "remark": {
           "type": "string",
+          "remarkDescription": "视图备注。",
           "x-backend": "remark"
         }
       }
@@ -1014,26 +1064,31 @@
         "audit_visible": {
           "type": "boolean",
           "default": true,
+          "auditVisibleDescription": "是否显示操作记录。",
           "x-backend": "beingAuditRecordVisible"
         },
         "data_log_visible": {
           "type": "boolean",
           "default": true,
+          "dataLogVisibleDescription": "是否显示数据日志(字段变更历史)。",
           "x-backend": "beingDataLogVisible"
         },
         "qrobot_record_visible": {
           "type": "boolean",
           "default": false,
+          "qrobotRecordVisibleDescription": "是否显示机器人记录。",
           "x-backend": "beingQrobotRecordVisible"
         },
         "workflow_future_visible": {
           "type": "boolean",
           "default": true,
+          "workflowFutureVisibleDescription": "是否显示流程未来节点。",
           "x-backend": "beingWorkflowNodeFutureListVisible"
         },
         "comment": {
           "type": "boolean",
           "default": false,
+          "commentDescription": "是否开启留言。",
           "x-backend": "beingCommentStatus"
         }
       }
@@ -1045,6 +1100,7 @@
         "need_pass": {
           "type": "boolean",
           "default": false,
+          "needPassDescription": "分享是否需要访问密码;true 时用 password 提供密码。",
           "x-backend": "beingNeedPass"
         },
         "password": {
@@ -1055,6 +1111,7 @@
         "force_login": {
           "type": "boolean",
           "default": false,
+          "forceLoginDescription": "分享是否强制登录后查看。",
           "x-backend": "beingForceLogin"
         },
         "print_enabled": {
@@ -1071,7 +1128,7 @@
     {
       "kind": "display",
       "displayDescription": "展示字段、排序、关联资源和各公开视图类型的专属配置。",
-      "fields": ["columns", "sort", "card", "gantt", "hierarchy", "associated_resources", "display", "group_que_id", "title_que_id", "start_que_id", "end_que_id"]
+      "fields": ["columns", "sort", "card", "gantt", "hierarchy", "calendar", "associated_resources", "display", "group_que_id", "title_que_id", "start_que_id", "end_que_id"]
     },
     {
       "kind": "data-permission",
@@ -1102,7 +1159,7 @@
     "kinds": {
       "summary": "最小创建声明:类型/名称/展示字段 + 数据权限形状。",
       "complete": "完整声明:全部公开可写字段,含各配置域与类型专属配置。",
-      "display": "展示字段、排序、卡片/甘特/层级配置、分组字段和关联资源。",
+      "display": "展示字段、排序、卡片/甘特/层级/日历配置、分组字段和关联资源。",
       "data-permission": "数据权限模式、数据范围和固定筛选条件。",
       "operation-permission": "成员可见范围、记录日志、留言、打印和分享策略。",
       "query-condition": "用户查询面板的开关、匹配模式和字段布局。",
@@ -1121,11 +1178,6 @@
     "backend_warning": "底层 ViewgraphInfo 更新接口对部分省略字段会执行 false、true、空数组或空字符串初始化，因此不得把直接后端请求中的省略统一理解为保留。"
   },
   "x-qingflow-backend-known-unsupported": {
-    "calendar": {
-      "backend": "viewgraphType=calendarView + viewgraphCalendarConfigVO",
-      "status": "not-writable",
-      "reason": "当前 app_views_apply 编译器没有 calendar 分支。"
-    },
     "column_permissions": {
       "backend": "viewgraphQuestions/ViewgraphQuestion",
       "status": "not-writable",

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/button-config.json

@@ -6,9 +6,9 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "action_buttons": { "type": "array", "items": { "$ref": "../complete.json#/$defs/ActionButton" }, "maxItems": 60 },
-    "action_buttons_mode": { "type": "string", "enum": ["merge", "replace"], "default": "merge" },
-    "buttons": { "type": "array", "items": { "$ref": "../complete.json#/$defs/ButtonBinding" }, "maxItems": 60 },
+    "action_buttons": { "type": "array", "items": { "$ref": "../complete.json#/$defs/ActionButton" }, "maxItems": 60, "actionButtonsDescription": "系统动作按钮(add_data/link/qRobot/wings);省略保留现有,空数组清空。" },
+    "action_buttons_mode": { "type": "string", "enum": ["merge", "replace"], "default": "merge", "actionButtonsModeDescription": "merge=与现有按钮合并(默认),replace=按声明全量替换。" },
+    "buttons": { "type": "array", "items": { "$ref": "../complete.json#/$defs/ButtonBinding" }, "maxItems": 60, "buttonsDescription": "已有自定义按钮的视图绑定(按 button_id 引用,维护位置/主次/显隐)。" },
     "query_conditions": { "$ref": "../complete.json#/$defs/QueryConditions", "queryConditionsDescription": "搜索按钮配置依赖的查询面板。" }
   },
   "x-qingflow-related-schemas": {
@@ -42,9 +42,9 @@
     "buttons": "引用应用中已存在的自定义按钮，只维护视图绑定、位置、主次和显隐条件。"
   },
   "x-qingflow-custom-button-workflow": {
-    "query": "先使用 app_get 获取应用中已有自定义按钮及 button_id。",
-    "createOrUpdate": "需要维护按钮主体、样式、跨视图复用或 qRobot/wings 细节时使用 app_custom_buttons_apply。",
-    "viewBinding": "普通业务动作优先声明 action_buttons；已有自定义按钮使用 buttons 绑定。"
+    "query": "创建前先用 app_get_buttons 传 button_text 按文案精确查重(CLI: builder button get --app-key APP --button-text 文案);唯一命中直接复用其 button_id,同名多条用 button_id 精确指定。",
+    "createOrUpdate": "未命中再用 app_custom_buttons_apply 创建;它自身也按 button_text 去重(无 button_id 时唯一同名匹配转为更新),不要重复创建同名按钮。需要维护按钮主体、样式、跨视图复用或 qRobot/wings 细节时同样使用 app_custom_buttons_apply。",
+    "viewBinding": "普通业务动作优先声明 action_buttons;已有自定义按钮使用 buttons 绑定(button_id 来自查询结果)。"
   },
   "examples": [
     { "action_buttons": [{ "text": "新增", "action": "add_data", "placement": "header", "primary": true }], "action_buttons_mode": "merge" },

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/data-permission.json

@@ -6,7 +6,7 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "data_permission": { "$ref": "../complete.json#/$defs/DataPermission" },
+    "data_permission": { "$ref": "../complete.json#/$defs/DataPermission", "dataPermissionDescription": "数据权限生效类型(config/custom)与数据范围(scope)。" },
     "filters": {
       "type": "array",
       "items": { "anyOf": [

package/src/qingflow_mcp/builder_facade/schemas/views/v1alpha1/details/display.json

@@ -2,20 +2,21 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://qingflow.com/schemas/builder/views/v1alpha1/details/display.json",
   "title": "Qingflow Views display configuration",
-  "displayDescription": "视图展示配置片段(schema_kind=display),字段直接并入完整视图声明。所有字段引用均为实际整数 queId；calendar 等当前 apply 不支持的类型不在公开 schema 中。",
+  "displayDescription": "视图展示配置片段(schema_kind=display),字段直接并入完整视图声明。所有字段引用均为实际整数 queId。",
   "type": "object",
   "additionalProperties": false,
   "properties": {
     "pinned": { "type": "boolean", "pinnedDescription": "是否固定在应用的视图列表顶部。true=固定，false=取消固定；省略时保持当前状态。它与 display.pin_navigate 无关。", "x-backend": "POST /app/{appKey}/view/ordinal (FIXED_VIEW_LIST|VIEW_LIST)" },
     "columns": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "columnsDescription": "表格或卡片展示字段，按数组顺序显示。" },
     "sort": { "type": "array", "items": { "$ref": "../complete.json#/$defs/SortRule" }, "sortDescription": "多级排序。空数组恢复默认排序。" },
-    "card": { "$ref": "../complete.json#/$defs/CardConfig" },
-    "gantt": { "$ref": "../complete.json#/$defs/GanttConfig" },
-    "hierarchy": { "$ref": "../complete.json#/$defs/HierarchyConfig" },
-    "associated_resources": { "$ref": "../complete.json#/$defs/AssociatedResources" },
-    "display": { "$ref": "../complete.json#/$defs/DisplayConfig" },
+    "card": { "$ref": "../complete.json#/$defs/CardConfig", "cardDescription": "卡片视图配置(封面/标题/字段标题/分组)。" },
+    "gantt": { "$ref": "../complete.json#/$defs/GanttConfig", "ganttDescription": "甘特视图配置(时间维度/分组/依赖)。" },
+    "hierarchy": { "$ref": "../complete.json#/$defs/HierarchyConfig", "hierarchyDescription": "层级视图配置(必填 title_que_id/children_que_id,可选 root_filter)。" },
+    "calendar": { "$ref": "../complete.json#/$defs/CalendarConfig", "calendarDescription": "日历视图配置(必填 title_que_id/date_que_id)。" },
+    "associated_resources": { "$ref": "../complete.json#/$defs/AssociatedResources", "associatedResourcesDescription": "关联报表/图表资源展示配置;应用级资源池用 app_associated_resources_apply 维护。" },
+    "display": { "$ref": "../complete.json#/$defs/DisplayConfig", "displayMiscDescription": "展示杂项(行高/视图内导航固定/备注)。" },
     "group_que_id": { "type": "integer", "groupQueIdDescription": "看板分组字段 queId。" },
-    "title_que_id": { "type": "integer", "titleQueIdDescription": "卡片、甘特或层级标题字段 queId。" },
+    "title_que_id": { "type": "integer", "titleQueIdDescription": "卡片、甘特、层级或日历标题字段 queId。" },
     "start_que_id": { "type": "integer", "startQueIdDescription": "甘特开始时间字段 queId。" },
     "end_que_id": { "type": "integer", "endQueIdDescription": "甘特结束时间字段 queId。" }
   },
@@ -27,7 +28,7 @@
     "kinds": {
       "summary": "最小创建声明:类型/名称/展示字段 + 数据权限形状。",
       "complete": "完整声明:全部公开可写字段,含各配置域与类型专属配置。",
-      "display": "展示字段、排序、卡片/甘特/层级配置、分组字段和关联资源。",
+      "display": "展示字段、排序、卡片/甘特/层级/日历配置、分组字段和关联资源。",
       "data-permission": "数据权限模式、数据范围和固定筛选条件。",
       "operation-permission": "成员可见范围、记录日志、留言、打印和分享策略。",
       "query-condition": "用户查询面板的开关、匹配模式和字段布局。",
@@ -56,16 +57,17 @@
     "card": "columns 至少包含一个业务字段；标题和封面等使用 card。",
     "board": "必须提供 group_que_id。",
     "gantt": "必须提供 start_que_id 和 end_que_id，或在 gantt 中提供等价字段。",
-    "hierarchy": "必须提供 hierarchy.title_que_id 和 hierarchy.children_que_id。"
+    "hierarchy": "必须提供 hierarchy.title_que_id 和 hierarchy.children_que_id。",
+    "calendar": "必须提供 calendar.title_que_id 和 calendar.date_que_id。date_que_id 可为表单日期字段或系统字段 2(申请时间)/3(更新时间)。"
   },
   "x-qingflow-unsupported": {
-    "calendar": "app_views_apply 当前不支持 calendar；后端对应 calendarView + viewgraphCalendarConfigVO。",
     "column_permissions": "列级可编辑、隐藏、下载等 ViewgraphQuestion 配置尚未进入公开 DSL。"
   },
   "examples": [
     { "columns": [101, 102], "sort": [{ "que_id": 101, "ascending": true }] },
     { "group_que_id": 103, "title_que_id": 101, "card": { "show_title": true, "group_color": true } },
     { "gantt": { "title_que_id": 101, "start_que_id": 104, "end_que_id": 105, "default_time_dimension": "month", "auto_calibration": false } },
-    { "hierarchy": { "title_que_id": 101, "children_que_id": 106, "root_filter": [] } }
+    { "hierarchy": { "title_que_id": 101, "children_que_id": 106, "root_filter": [] } },
+    { "calendar": { "title_que_id": 101, "date_que_id": 104, "color_que_id": 103 } }
   ]
 }