@qingflow-tech/qingflow-cli 1.1.50-beta.2 → 1.1.50-beta.4

package/skills/qingflow-cli/reference/examples/README.md

@@ -7,7 +7,7 @@ Use these files as copyable bases after reading the matching resource document.
 | Historical single-app schema probe | [schema/schema_single_app_form_standard.example.json](./schema/schema_single_app_form_standard.example.json) | Retired `--form-file` shape; use `builder app-form schema/get/validate/apply` for current declarations. |
 | Historical multi-app schema probe | [schema/schema_multi_app_form_relation_layout.example.json](./schema/schema_multi_app_form_relation_layout.example.json) | Retired `--apps-file` shape; current systems create independent AppForms and then bind confirmed app keys. |
 | Existing-app layout probe | [layout/layout_sections_full.example.json](./layout/layout_sections_full.example.json) | Historical layout-patch shape; current new and existing forms use the complete AppForm `spec.body`. |
-| Views | [views/views_upsert_table_minimal.example.json](./views/views_upsert_table_minimal.example.json), [views/views_batch_full.example.json](./views/views_batch_full.example.json) | `views[]` shape with filters, query panel, view-bound buttons, batch upsert/patch/remove. |
+| Views | [views/views_upsert_table_minimal.example.json](./views/views_upsert_table_minimal.example.json), [views/views_apply_v1alpha1.example.json](./views/views_apply_v1alpha1.example.json) | 单视图 JSON 对象，包含筛选、查询面板和视图绑定按钮；通过 `--app-key` 指定应用。 |
 | Charts | [charts/charts_upsert_dashboard_starter.example.json](./charts/charts_upsert_dashboard_starter.example.json) | Standalone chart apply; portal usually creates missing charts inline. |
 | Portal | [portal/portal_sections_standard_workbench.example.json](./portal/portal_sections_standard_workbench.example.json) | Standard workbench with inline QingBI charts and data views. |
 | Associated resources | [associated/associated_resources_semantic_full.example.json](./associated/associated_resources_semantic_full.example.json) | Current-record matching through `match_mappings`. |

package/skills/qingflow-cli/reference/examples/views/views_apply_v1alpha1.example.json

@@ -0,0 +1,14 @@
+{
+  "name": "项目台账视图",
+  "type": "table",
+  "columns": [100, 101, 102, 103],
+  "data_permission": {"type": "custom", "scope": "dept"},
+  "sort": [{"que_id": 100, "ascending": false}],
+  "display": {"row_height": "compact", "pin_navigate": true},
+  "query_conditions": {
+    "enabled": true,
+    "exact": false,
+    "hide_before_query": false,
+    "rows": [["项目名称", "负责人"], ["创建时间"]]
+  }
+}

package/skills/qingflow-cli/reference/examples/views/views_upsert_table_minimal.example.json

@@ -1,42 +1,36 @@
 {
-  "views": [
+  "name": "示例业务操作视图_CLI模板",
+  "type": "table",
+  "columns": [100, 101, 102, 103],
+  "filters": [
+    {"que_id": 100, "operator": "neq", "value": "已关闭"}
+  ],
+  "query_conditions": {
+    "enabled": true,
+    "exact": false,
+    "hide_before_query": false,
+    "rows": [["主记录编号", "主记录名称"], ["状态", "负责人"]]
+  },
+  "action_buttons": [
     {
-      "operation": "upsert",
-      "app_key": "APP_KEY",
-      "name": "示例业务操作视图_CLI模板",
-      "type": "table",
-      "columns": ["主记录编号", "主记录名称", "状态", "负责人"],
-      "filters": [
-        {"field_name": "状态", "operator": "neq", "value": "已关闭"}
+      "text": "行内创建子记录",
+      "action": "add_data",
+      "target_app_key": "TARGET_APP_KEY",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联主记录"}
       ],
-      "query_conditions": {
-        "enabled": true,
-        "exact": false,
-        "hide_before_query": false,
-        "rows": [["主记录编号", "主记录名称"], ["状态", "负责人"]]
-      },
-      "action_buttons": [
-        {
-          "text": "行内创建子记录",
-          "action": "add_data",
-          "target_app_key": "TARGET_APP_KEY",
-          "field_mappings": [
-            {"source_field": "数据ID", "target_field": "关联主记录"}
-          ],
-          "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
-          "placement": "list"
-        },
-        {
-          "text": "详情创建子记录",
-          "action": "add_data",
-          "target_app_key": "TARGET_APP_KEY",
-          "field_mappings": [
-            {"source_field": "数据ID", "target_field": "关联主记录"}
-          ],
-          "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
-          "placement": "detail"
-        }
-      ]
+      "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
+      "placement": "list"
+    },
+    {
+      "text": "详情创建子记录",
+      "action": "add_data",
+      "target_app_key": "TARGET_APP_KEY",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联主记录"}
+      ],
+      "default_values": {"目标状态字段": "REPLACE_WITH_TARGET_OPTION_LABEL"},
+      "placement": "detail"
     }
   ]
 }

package/src/qingflow_mcp/builder_facade/models.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import re
 from enum import Enum
-from typing import Any
+from typing import Any, Union
 
 from pydantic import AliasChoices, Field, model_validator
 
@@ -134,6 +134,8 @@ class PublicViewType(str, Enum):
     card = "card"
     board = "board"
     gantt = "gantt"
+    hierarchy = "hierarchy"
+    calendar = "calendar"
 
 
 class PublicButtonTriggerAction(str, Enum):
@@ -390,9 +392,38 @@ class FlowConditionRulePatch(StrictModel):
         return self
 
 
+
+
+def _coerce_que_id(value: Any) -> Any:
+    """字段引用归一:queId(后端字段唯一键)。接受 int / "123" / "field_123"(field_id 形态) → int;
+    其余形态原样返回交给 pydantic 报错(契约诚实:不支持显示名引用)。"""
+    if isinstance(value, bool) or isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        stripped = value.strip()
+        if stripped.isdigit():
+            return int(stripped)
+        if stripped.startswith("field_") and stripped[6:].isdigit():
+            return int(stripped[6:])
+    return value
+
 class ViewFilterRulePatch(StrictModel):
-    field_name: str = Field(validation_alias=AliasChoices("field_name", "fieldName", "field", "name"))
+    que_id: int = Field(validation_alias=AliasChoices("que_id", "queId", "field_id", "fieldId"))
     operator: ViewFilterOperator = Field(default=ViewFilterOperator.eq, validation_alias=AliasChoices("operator", "op"))
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_que_id(cls, value: Any) -> Any:
+        if isinstance(value, dict):
+            for alias in ("queId", "field_id", "fieldId"):
+                if alias in value and "que_id" not in value:
+                    value = {**{k: v for k, v in value.items() if k != alias}, "que_id": value[alias]}
+                    break
+            for alias in ("queId", "field_id", "fieldId"):
+                value.pop(alias, None) if alias != "que_id" else None
+        if isinstance(value, dict) and "que_id" in value:
+            return {**value, "que_id": _coerce_que_id(value["que_id"])}
+        return value
     values: list[Any] = Field(default_factory=list)
 
     @model_validator(mode="before")
@@ -405,11 +436,18 @@ class ViewFilterRulePatch(StrictModel):
         if self.operator in {ViewFilterOperator.is_empty, ViewFilterOperator.not_empty}:
             self.values = []
             return self
-        if not self.values:
+        if not self.values and self.operator != ViewFilterOperator.in_:
+            # in+空值合法:选项/成员类字段"ANY 判型未选任何值"的存量形态
+            # (后端 judgeType=EQUAL_ANY+空值,实测回写稳定保留)
             raise ValueError("view filter rule requires values")
         return self
 
 
+# 视图筛选双形态(与 visible_when/root_filter 的嵌组形态对齐):
+# 扁平 [rule, ...] = 单组 AND(向后兼容);嵌套 [[rule,...],[rule,...]] = 组间 OR、组内 AND
+ViewFilterGroupPatch = Union[ViewFilterRulePatch, list[ViewFilterRulePatch]]
+
+
 class FieldSelector(StrictModel):
     field_id: str | None = None
     que_id: int | None = None
@@ -544,16 +582,14 @@ class VisibilityPatch(StrictModel):
 
     @model_validator(mode="after")
     def validate_shape(self) -> "VisibilityPatch":
-        if self.mode == PublicVisibilityMode.specific and not self.selectors.has_any_selector():
-            raise ValueError("specific visibility requires selectors")
+        # mode=specific + 空 selectors 是合法形态(auth=2 但未配置成员),回写保真;
+        # 不强制要求 specific 必须有 selectors
         if self.mode != PublicVisibilityMode.specific and self.selectors.has_any_selector():
             raise ValueError("selectors are only allowed when mode=specific")
         if self.mode == PublicVisibilityMode.everyone and self.external_mode != PublicExternalVisibilityMode.workspace:
             raise ValueError("mode=everyone requires external_mode=workspace")
         if self.mode == PublicVisibilityMode.everyone and self.external_selectors.has_any_selector():
             raise ValueError("external_selectors are not allowed when mode=everyone")
-        if self.external_mode == PublicExternalVisibilityMode.specific and not self.external_selectors.has_any_selector():
-            raise ValueError("external_mode=specific requires external_selectors")
         if self.external_mode != PublicExternalVisibilityMode.specific and self.external_selectors.has_any_selector():
             raise ValueError("external_selectors are only allowed when external_mode=specific")
         return self
@@ -1137,6 +1173,149 @@ class ViewQueryConditionsPatch(StrictModel):
     rows: list[list[str | int]] = Field(default_factory=list, validation_alias=AliasChoices("rows", "fields", "queryCondition"))
 
 
+class ViewDataPermissionPatch(StrictModel):
+    """数据权限形状(公开语义)→ dataPermissionType + dataScope。"""
+
+    type: str = Field(default="custom", validation_alias=AliasChoices("type", "permission_type", "permissionType"))
+    scope: str = Field(default="all", validation_alias=AliasChoices("scope", "data_scope", "dataScope"))
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ViewDataPermissionPatch":
+        if self.type not in {"config", "custom"}:
+            raise ValueError("data_permission.type must be config or custom")
+        if self.scope not in {"all", "oneself", "dept", "subordinate", "custom"}:
+            raise ValueError("data_permission.scope must be one of all/oneself/dept/subordinate/custom")
+        return self
+
+
+class ViewSortRulePatch(StrictModel):
+    """排序规则(公开语义)→ viewgraphSorts + sortType=customSort。"""
+
+    que_id: int = Field(validation_alias=AliasChoices("que_id", "queId", "field_id", "fieldId"))
+    ascending: bool = Field(default=True, validation_alias=AliasChoices("ascending", "asc", "beingSortAscend"))
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_que_id(cls, value: Any) -> Any:
+        if isinstance(value, dict):
+            for alias in ("queId", "field_id", "fieldId"):
+                if alias in value and "que_id" not in value:
+                    value = {**{k: v for k, v in value.items() if k != alias}, "que_id": value[alias]}
+                    break
+            for alias in ("queId", "field_id", "fieldId"):
+                value.pop(alias, None) if alias != "que_id" else None
+        if isinstance(value, dict) and "que_id" in value:
+            return {**value, "que_id": _coerce_que_id(value["que_id"])}
+        return value
+
+
+class ViewCardConfigPatch(StrictModel):
+    """卡片视图特有配置 → titleQue/frontCoverQueId/clippingMode/... 。"""
+
+    title_que_id: int | None = Field(default=None, validation_alias=AliasChoices("title_que_id", "titleQueId"))
+    cover_que_id: int | None = Field(default=None, validation_alias=AliasChoices("cover_que_id", "coverQueId", "front_cover_que_id", "frontCoverQueId"))
+    clipping_mode: str | None = Field(default=None, validation_alias=AliasChoices("clipping_mode", "clippingMode"))
+    image_adaption: bool | None = Field(default=None, validation_alias=AliasChoices("image_adaption", "imageAdaption", "beingImageAdaption"))
+    show_field_title: bool | None = Field(default=None, validation_alias=AliasChoices("show_field_title", "showFieldTitle", "beingShowQueTitle"))
+    show_title: bool | None = Field(default=None, validation_alias=AliasChoices("show_title", "showTitle", "beingShowTitleQue"))
+    show_cover: bool | None = Field(default=None, validation_alias=AliasChoices("show_cover", "showCover", "beingShowCover"))
+    group_que_id: int | None = Field(default=None, validation_alias=AliasChoices("group_que_id", "groupQueId"))
+    group_color: bool | None = Field(default=None, validation_alias=AliasChoices("group_color", "groupColor", "beingGroupColor"))
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ViewCardConfigPatch":
+        if self.clipping_mode is not None and self.clipping_mode not in {"default", "fill"}:
+            raise ValueError("card.clipping_mode must be default or fill")
+        return self
+
+
+class ViewGanttGroupPatch(StrictModel):
+    que_id: int = Field(validation_alias=AliasChoices("que_id", "queId"))
+    ordinal: int | None = Field(default=None)
+
+
+class ViewGanttDependencyPatch(StrictModel):
+    predecessor_que_id: int = Field(validation_alias=AliasChoices("predecessor_que_id", "predecessorQueId"))
+    dependency_que_id: int = Field(validation_alias=AliasChoices("dependency_que_id", "dependencyQueId"))
+    start_start_option_id: int | None = Field(default=None, validation_alias=AliasChoices("start_start_option_id", "startStartOptionId"))
+    start_end_option_id: int | None = Field(default=None, validation_alias=AliasChoices("start_end_option_id", "startEndOptionId"))
+    end_start_option_id: int | None = Field(default=None, validation_alias=AliasChoices("end_start_option_id", "endStartOptionId"))
+    end_end_option_id: int | None = Field(default=None, validation_alias=AliasChoices("end_end_option_id", "endEndOptionId"))
+
+
+class ViewGanttConfigPatch(StrictModel):
+    """甘特视图特有配置 → viewgraphGanttConfigVO。"""
+
+    title_que_id: int | None = Field(default=None, validation_alias=AliasChoices("title_que_id", "titleQueId"))
+    start_que_id: int | None = Field(default=None, validation_alias=AliasChoices("start_que_id", "startQueId"))
+    end_que_id: int | None = Field(default=None, validation_alias=AliasChoices("end_que_id", "endQueId"))
+    default_time_dimension: str | None = Field(default=None, validation_alias=AliasChoices("default_time_dimension", "defaultTimeDimension"))
+    auto_calibration: bool | None = Field(default=None, validation_alias=AliasChoices("auto_calibration", "autoCalibration", "beingAutoCalibration"))
+    groups: list[ViewGanttGroupPatch] = Field(default_factory=list)
+    dependencies: list[ViewGanttDependencyPatch] = Field(default_factory=list, validation_alias=AliasChoices("dependencies", "dependency"))
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ViewGanttConfigPatch":
+        if self.default_time_dimension is not None and self.default_time_dimension not in {"day", "week", "month", "year"}:
+            raise ValueError("gantt.default_time_dimension must be day, week, month, or year")
+        if len(self.dependencies) > 1:
+            raise ValueError("gantt.dependencies supports at most one dependency relation in v1alpha1")
+        return self
+
+
+class ViewHierarchyConfigPatch(StrictModel):
+    """层级视图特有配置 → viewgraphHierarchyConfigVO。"""
+
+    title_que_id: int = Field(validation_alias=AliasChoices("title_que_id", "titleQueId"))
+    children_que_id: int = Field(validation_alias=AliasChoices("children_que_id", "childrenQueId"))
+    root_filter: list[list[ViewFilterRulePatch]] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("root_filter", "rootFilter", "root_node_filter", "rootNodeFilter"),
+    )
+
+
+class ViewCalendarConfigPatch(StrictModel):
+    """日历视图特有配置 → viewgraphCalendarConfigVO。"""
+
+    title_que_id: int = Field(validation_alias=AliasChoices("title_que_id", "titleQueId"))
+    date_que_id: int = Field(validation_alias=AliasChoices("date_que_id", "dateQueId"))
+    color_que_id: int | None = Field(default=None, validation_alias=AliasChoices("color_que_id", "colorQueId"))
+
+
+class ViewDisplayConfigPatch(StrictModel):
+    """展示杂项 → defaultRowHigh/beingPinNavigate/remark。"""
+
+    row_height: str | None = Field(default=None, validation_alias=AliasChoices("row_height", "rowHeight", "defaultRowHigh"))
+    pin_navigate: bool | None = Field(default=None, validation_alias=AliasChoices("pin_navigate", "pinNavigate", "beingPinNavigate"))
+    remark: str | None = Field(default=None)
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "ViewDisplayConfigPatch":
+        # 后端 defaultRowHigh 实际值域:compact/moderate/highest(high 为历史别名)
+        if self.row_height is not None and self.row_height not in {"compact", "moderate", "highest", "high"}:
+            raise ValueError("display.row_height must be compact, moderate, highest, or high")
+        return self
+
+
+class ViewRecordConfigPatch(StrictModel):
+    """记录可见性开关 → beingAuditRecordVisible 等。"""
+
+    audit_visible: bool | None = Field(default=None, validation_alias=AliasChoices("audit_visible", "auditVisible", "beingAuditRecordVisible"))
+    data_log_visible: bool | None = Field(default=None, validation_alias=AliasChoices("data_log_visible", "dataLogVisible", "beingDataLogVisible"))
+    qrobot_record_visible: bool | None = Field(default=None, validation_alias=AliasChoices("qrobot_record_visible", "qrobotRecordVisible", "beingQrobotRecordVisible"))
+    workflow_future_visible: bool | None = Field(default=None, validation_alias=AliasChoices("workflow_future_visible", "workflowFutureVisible", "beingWorkflowNodeFutureListVisible"))
+    comment: bool | None = Field(default=None, validation_alias=AliasChoices("comment", "beingCommentStatus"))
+
+
+class ViewShareConfigPatch(StrictModel):
+    """分享与安全 → beingNeedPass/viewgraphPass/beingForceLogin/beingPrintStatus。"""
+
+    need_pass: bool | None = Field(default=None, validation_alias=AliasChoices("need_pass", "needPass", "beingNeedPass"))
+    password: str | None = Field(default=None, validation_alias=AliasChoices("password", "pass", "viewgraphPass"))
+    force_login: bool | None = Field(default=None, validation_alias=AliasChoices("force_login", "forceLogin", "beingForceLogin"))
+    print_enabled: bool | None = Field(default=None, validation_alias=AliasChoices("print_enabled", "printEnabled", "beingPrintStatus"))
+
+
 class ViewAssociatedResourcesPatch(StrictModel):
     visible: bool = Field(default=True, validation_alias=AliasChoices("visible", "enabled", "asosChartVisible"))
     limit_type: str | None = Field(default=None, validation_alias=AliasChoices("limit_type", "limitType"))
@@ -1239,17 +1418,30 @@ class ViewActionButtonPatch(StrictModel):
 class ViewUpsertPatch(StrictModel):
     name: str
     view_key: str | None = Field(default=None, validation_alias=AliasChoices("view_key", "viewKey"))
+    pinned: bool | None = Field(default=None, validation_alias=AliasChoices("pinned", "fixed", "is_pinned", "isPinned"))
     type: PublicViewType
-    columns: list[str] = Field(default_factory=list)
-    group_by: str | None = None
-    filters: list[ViewFilterRulePatch] = Field(default_factory=list)
-    start_field: str | None = Field(default=None, validation_alias=AliasChoices("start_field", "startField"))
-    end_field: str | None = Field(default=None, validation_alias=AliasChoices("end_field", "endField"))
-    title_field: str | None = Field(default=None, validation_alias=AliasChoices("title_field", "titleField"))
+    columns: list[int] = Field(default_factory=list)
+    group_que_id: int | None = Field(default=None, validation_alias=AliasChoices("group_que_id", "groupQueId"))
+    filters: list["ViewFilterGroupPatch"] = Field(default_factory=list)
+    start_que_id: int | None = Field(default=None, validation_alias=AliasChoices("start_que_id", "startQueId"))
+    end_que_id: int | None = Field(default=None, validation_alias=AliasChoices("end_que_id", "endQueId"))
+    title_que_id: int | None = Field(default=None, validation_alias=AliasChoices("title_que_id", "titleQueId"))
     buttons: list["ViewButtonBindingPatch"] | None = None
     action_buttons: list[ViewActionButtonPatch] | None = Field(default=None, validation_alias=AliasChoices("action_buttons", "actionButtons"))
     action_buttons_mode: str = Field(default="merge", validation_alias=AliasChoices("action_buttons_mode", "actionButtonsMode", "button_mode", "buttonMode"))
     visibility: VisibilityPatch | None = None
+    data_permission: ViewDataPermissionPatch | None = Field(
+        default=None,
+        validation_alias=AliasChoices("data_permission", "dataPermission"),
+    )
+    sort: list[ViewSortRulePatch] | None = Field(default=None, validation_alias=AliasChoices("sort", "sort_rules", "sortRules"))
+    card: ViewCardConfigPatch | None = Field(default=None)
+    gantt: ViewGanttConfigPatch | None = Field(default=None)
+    hierarchy: ViewHierarchyConfigPatch | None = Field(default=None)
+    calendar: ViewCalendarConfigPatch | None = Field(default=None)
+    display: ViewDisplayConfigPatch | None = Field(default=None)
+    record: ViewRecordConfigPatch | None = Field(default=None)
+    share: ViewShareConfigPatch | None = Field(default=None)
     query_conditions: ViewQueryConditionsPatch | None = Field(default=None, validation_alias=AliasChoices("query_conditions", "queryConditions", "query_condition", "queryCondition"))
     associated_resources: ViewAssociatedResourcesPatch | None = Field(
         default=None,
@@ -1315,16 +1507,34 @@ class ViewUpsertPatch(StrictModel):
                 payload["type"] = "board"
             elif normalized == "ganttview":
                 payload["type"] = "gantt"
+            elif normalized == "hierarchyview":
+                payload["type"] = "hierarchy"
+            elif normalized == "calendarview":
+                payload["type"] = "calendar"
         return payload
 
     @model_validator(mode="after")
     def validate_shape(self) -> "ViewUpsertPatch":
         if self.type in {PublicViewType.table, PublicViewType.card} and not self.columns:
             raise ValueError("table/card views require columns")
-        if self.type == PublicViewType.board and not self.group_by:
-            raise ValueError("board view requires group_by")
-        if self.type == PublicViewType.gantt and not (self.start_field and self.end_field):
-            raise ValueError("gantt view requires start_field and end_field")
+        if self.type == PublicViewType.board and not self.group_que_id:
+            raise ValueError("board view requires group_que_id")
+        if self.type == PublicViewType.gantt and not (self.start_que_id and self.end_que_id):
+            raise ValueError("gantt view requires start_que_id and end_que_id")
+        if self.type == PublicViewType.hierarchy:
+            if self.hierarchy is None or not (self.hierarchy.title_que_id and self.hierarchy.children_que_id):
+                raise ValueError("hierarchy view requires hierarchy.title_que_id and children_que_id")
+        elif self.hierarchy is not None:
+            raise ValueError("hierarchy config is only allowed on hierarchy views")
+        if self.type == PublicViewType.calendar:
+            if self.calendar is None:
+                raise ValueError("calendar view requires calendar.title_que_id and date_que_id")
+        elif self.calendar is not None:
+            raise ValueError("calendar config is only allowed on calendar views")
+        if self.type != PublicViewType.card and self.card is not None:
+            raise ValueError("card config is only allowed on card views")
+        if self.type != PublicViewType.gantt and self.gantt is not None:
+            raise ValueError("gantt config is only allowed on gantt views")
         normalized_mode = str(self.action_buttons_mode or "merge").strip().lower()
         if normalized_mode not in {"merge", "replace"}:
             raise ValueError("action_buttons_mode must be merge or replace")

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