@qingflow-tech/qingflow-cli 1.1.50 → 1.1.53

package/src/qingflow_mcp/server_app_builder.py

@@ -56,8 +56,8 @@ def build_builder_server() -> FastMCP:
             "For builder delete/remove apply results, separate delete execution from readback verification: after DELETE is sent, resources expose delete_executed, readback_status, and safe_to_retry_delete=false. If readback_status is unavailable or still_exists, do not blindly repeat the delete; confirm later with app_get/view_get/chart_get or the relevant apply readback. Views/buttons use single-item readback; associated resources use one app-level resource-pool readback because there is no confirmed single-item GET. "
             "For builder write/apply results, separate write execution from final readback verification: status=partial_success with write_executed=true and safe_to_retry=false means the write was sent or succeeded, while final readback, publish verification, or metadata confirmation is pending or permission-restricted. Report it as written but unverified; do not repeat the same write blindly. "
             "For app_form_apply, pin the version from app_form_schema, preserve the complete body and existing IDs from a draft get, and configure data display through app-level spec.dataTitleField/spec.dataCoverField selectors rather than booleans on fields; App Builder MCP validates the declaration inside app_form_apply, while the CLI route has a separate static validate command. dataTitleField must resolve to exactly one top-level field for a non-empty body, while dataCoverField is optional and must resolve to a top-level attachment field. A root appKey means update and may include packageId; no appKey means create and requires packageId plus spec.appName. AppForm does not accept spec.icon or spec.color; creation derives a stable default icon and color from spec.appName. "
-            "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows is a matrix of field names compiled to backend queryCondition queIds. New views default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless associated_resources is explicitly patched. View writes use ViewManagementAuth (beingViewManageStatus), falling back to DataManageAuth when advanced app permissions are not enabled. "
-            "For ordinary business buttons, declare them on the target view with app_views_apply.views[].action_buttons; app_views_apply writes the view first, then creates/binds the button. Use app_custom_buttons_apply only when the user explicitly asks to maintain existing standalone buttons outside view design, such as custom style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings config. Button body writes require EditAppAuth; view_configs placement writes require ViewManagementAuth, matching the backend viewConfig route. For addData buttons, prefer action_buttons.target_app_key + field_mappings/default_values on the view path; do not ask agents to write raw que_relation unless maintaining a legacy config. field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). To fill a target relation with the current record, map {'source_field': '数据ID', 'target_field': '目标引用字段'}; default_values is only for static constants. View button bindings merge by default; standalone view_configs are only for explicit maintenance. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
+            "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows accepts field names, field IDs, or queIds and compiles them to backend queryCondition queIds, with queIds preferred. New views default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless associated_resources is explicitly patched. View writes use ViewManagementAuth (beingViewManageStatus), falling back to DataManageAuth when advanced app permissions are not enabled. "
+            "For ordinary business buttons, declare them on a new or full view with app_views_apply.upsert_view.action_buttons; app_views_apply writes the view first, then creates/binds the button. For an existing view, use patch_views[].set.action_buttons. Use app_custom_buttons_apply only when the user explicitly asks to maintain existing standalone buttons outside view design, such as custom style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings config. Button body writes require EditAppAuth; view_configs placement writes require ViewManagementAuth, matching the backend viewConfig route. For addData buttons, prefer action_buttons.target_app_key + field_mappings/default_values on the view path; do not ask agents to write raw que_relation unless maintaining a legacy config. field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). To fill a target relation with the current record, map {'source_field': '数据ID', 'target_field': '目标引用字段'}; default_values is only for static constants. View button bindings merge by default; standalone view_configs are only for explicit maintenance. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
             "For BI reports, keep report-body development separate from Qingflow in-app display: use app_charts_apply to create, update, remove, or reorder app-source QingBI chart bodies/configs with dataSourceType=qingflow; chart dimension/metric/filter/query fields must come from app_get_fields.chart_fields, not record schema or form-only fields; dataset BI reports are not created or edited by app_charts_apply yet and should be created in QingBI first, then attached with app_associated_resources_apply using report_source=dataset. "
             "For associated views/reports, use app_associated_resources_apply. Use match_mappings for filtering associated resources: dynamic current-record conditions use source_field, static conditions use value. match_mappings also supports 数据ID(-17) and 编号(0). Do not ask agents to write raw match_rules unless preserving a legacy backend config. "
             "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, and view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key because the tool resolves those to the internal id. Before creating an associated resource, read app_get.associated_resources and reuse an existing matching target_app_key + view_key/chart_key through patch_resources; client_key only works inside one apply call and is not persisted. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
@@ -231,6 +231,32 @@ def build_builder_server() -> FastMCP:
     ) -> dict:
         return ai_builder.app_form_apply(profile=profile, spec=spec or {})
 
+    @server.tool()
+    def app_views_schema(
+        schema_version: str | None = None,
+        schema_kind: str | None = None,
+    ) -> dict:
+        """Get a complete views schema or a focused detail schema such as display or button-config."""
+        return ai_builder.app_views_schema(schema_version=schema_version, schema_kind=schema_kind)
+
+    @server.tool()
+    def app_views_get(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        schema_version: str | None = None,
+        schema_kind: str | None = None,
+    ) -> dict:
+        return ai_builder.app_views_get(
+            profile=profile, app_key=app_key, schema_version=schema_version, schema_kind=schema_kind
+        )
+
+    @server.tool()
+    def app_views_validate(
+        declaration: dict | None = None,
+        schema_version: str | None = None,
+    ) -> dict:
+        return ai_builder.app_views_validate(declaration=declaration or {}, schema_version=schema_version)
+
     @server.tool(description=ai_builder._high_risk_tool_description(operation="delete", target="app configuration"))
     def app_delete(
         profile: str = DEFAULT_PROFILE,
@@ -445,8 +471,8 @@ def build_builder_server() -> FastMCP:
         return ai_builder.app_get_charts(profile=profile, app_key=app_key, app_keys=app_keys)
 
     @server.tool()
-    def app_get_buttons(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
-        return ai_builder.app_get_buttons(profile=profile, app_key=app_key, app_keys=app_keys)
+    def app_get_buttons(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None, button_text: str | None = None) -> dict:
+        return ai_builder.app_get_buttons(profile=profile, app_key=app_key, app_keys=app_keys, button_text=button_text)
 
     @server.tool()
     def app_get_associated_resources(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
@@ -546,21 +572,19 @@ def build_builder_server() -> FastMCP:
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
         publish: bool = True,
-        upsert_views: list[dict] | None = None,
+        upsert_view: dict | None = None,
         patch_views: list[dict] | None = None,
         remove_views: list[str] | None = None,
-        apps: list[dict] | None = None,
-        views: list[dict] | None = None,
+        schema_version: str | None = None,
     ) -> dict:
         return ai_builder.app_views_apply(
             profile=profile,
             app_key=app_key,
             publish=publish,
-            upsert_views=upsert_views or [],
+            upsert_view=upsert_view,
             patch_views=patch_views or [],
             remove_views=remove_views or [],
-            apps=apps,
-            views=views,
+            schema_version=schema_version,
         )
 
     @server.tool()

package/src/qingflow_mcp/solution/compiler/view_compiler.py

@@ -12,6 +12,7 @@ VIEW_TYPE_MAP = {
     ViewType.board: "boardView",
     ViewType.gantt: "ganttView",
     ViewType.hierarchy: "hierarchyView",
+    ViewType.calendar: "calendarView",
 }
 
 
@@ -32,7 +33,7 @@ def compile_views(entity: EntitySpec) -> list[dict[str, Any]]:
                     "viewgraphQueIds": list(view.field_ids),
                     "viewgraphQuestions": [],
                     "ordinal": ordinal,
-                    "beingShowTitleQue": view.type in (ViewType.card, ViewType.board, ViewType.gantt, ViewType.hierarchy),
+                    "beingShowTitleQue": view.type in (ViewType.card, ViewType.board, ViewType.gantt, ViewType.hierarchy, ViewType.calendar),
                     "beingShowCover": False,
                     "viewgraphLimitType": 1,
                     "viewgraphLimit": view.filters,

package/src/qingflow_mcp/solution/executor.py

@@ -36,6 +36,7 @@ class SolutionExecutor:
         app_tools: AppTools,
         record_tools: RecordTools,
         view_tools: ViewTools,
+        view_writer: "ViewWriter | None" = None,
         chart_tools: QingbiReportTools,
         portal_tools: PortalTools,
         navigation_tools: NavigationTools,
@@ -47,6 +48,7 @@ class SolutionExecutor:
         self.app_tools = app_tools
         self.record_tools = record_tools
         self.view_tools = view_tools
+        self.view_writer = view_writer
         self.chart_tools = chart_tools
         self.portal_tools = portal_tools
         self.navigation_tools = navigation_tools
@@ -460,6 +462,20 @@ class SolutionExecutor:
             "Pass {app_key, spec} to solution_build_flow or use qingflow builder flow apply."
         )
 
+    def _create_view_via_writer(self, *, profile: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """视图创建唯一落点:共享 ViewWriter(POST /view/viewConfig)。
+
+        solution DSL 内部创建路径不再直接调用 ViewTools.view_create(该方法已删除);
+        未注入 writer 的旧调用方退化为直接经 ViewTools 同一会话执行同一端点。
+        """
+        if self.view_writer is not None:
+            return self.view_writer.create_view(profile=profile, payload=payload)
+        from ..tools.view_writer import ViewWriter as _FallbackViewWriter
+
+        return _FallbackViewWriter(self.view_tools.sessions, self.view_tools.backend).create_view(
+            profile=profile, payload=payload
+        )
+
     def _build_views(self, profile: str, entity: CompiledEntity, store: RunArtifactStore) -> None:
         app_key = self._get_app_key(store, entity.entity_id)
         field_meta = store.get_artifact("field_maps", entity.entity_id, {})
@@ -474,7 +490,7 @@ class SolutionExecutor:
                 schema=schema,
                 group_by_field_id=view_plan["group_by_field_id"],
             )
-            result = self.view_tools.view_create(profile=profile, payload=create_payload)
+            result = self._create_view_via_writer(profile=profile, payload=create_payload)
             view_result = result.get("result")
             view_key = ((view_result or {}) if isinstance(view_result, dict) else {}).get("viewgraphKey")
             if not view_key and isinstance(view_result, str):
@@ -895,13 +911,14 @@ class SolutionExecutor:
         data.setdefault("asosChartConfig", {"limitType": 1, "asosChartIdList": []})
         data.setdefault("viewgraphGanttConfigVO", None)
         data.setdefault("viewgraphHierarchyConfigVO", None)
+        data.setdefault("viewgraphCalendarConfigVO", None)
         data.setdefault("viewgraphLimitFormula", "")
         data.setdefault("buttonConfigDTOList", [])
         if not data.get("viewgraphQuestions"):
             data["viewgraphQuestions"] = _build_viewgraph_questions(schema, visible_que_ids)
         if not data.get("viewgraphSorts"):
             data["viewgraphSorts"] = [{"queId": 0, "beingSortAscend": True, "queType": 8}]
-        if data.get("viewgraphType") in {"cardView", "boardView", "ganttView", "hierarchyView"}:
+        if data.get("viewgraphType") in {"cardView", "boardView", "ganttView", "hierarchyView", "calendarView"}:
             data["titleQue"] = visible_que_ids[0] if visible_que_ids else None
         else:
             data.setdefault("titleQue", None)
@@ -2218,6 +2235,7 @@ def _portal_view_type(store: RunArtifactStore, entity_id: str, view_id: str) ->
         "board": "boardView",
         "gantt": "ganttView",
         "hierarchy": "hierarchyView",
+        "calendar": "calendarView",
     }
     for entity in store.data.get("normalized_solution_spec", {}).get("entities", []):
         if entity["entity_id"] != entity_id:
@@ -2324,36 +2342,106 @@ def _resolve_package_item_insert_index(tag_items: list[dict[str, Any]], ordinal:
     return max(0, min(len(tag_items), ordinal - 1))
 
 
-def _build_viewgraph_questions(schema: dict[str, Any], visible_que_ids: list[int]) -> list[dict[str, Any]]:
+def _flatten_viewgraph_questions(entries: list[Any] | None) -> dict[int, dict[str, Any]]:
+    """把读面的 viewgraphQuestions(含 subQues/innerQues 嵌套)按 queId 展平。"""
+    flat: dict[int, dict[str, Any]] = {}
+
+    def walk(entry: Any) -> None:
+        if not isinstance(entry, dict):
+            return
+        que_id = entry.get("queId")
+        if isinstance(que_id, int) and que_id not in flat:
+            flat[que_id] = entry
+        for key in ("subQues", "innerQues"):
+            for child in entry.get(key) or []:
+                if isinstance(child, list):
+                    for inner in child:
+                        walk(inner)
+                else:
+                    walk(child)
+
+    for entry in entries or []:
+        if isinstance(entry, list):
+            for inner in entry:
+                walk(inner)
+        else:
+            walk(entry)
+    return flat
+
+
+def _build_viewgraph_questions(
+    schema: dict[str, Any],
+    visible_que_ids: list[int],
+    *,
+    existing_by_que_id: dict[int, dict[str, Any]] | None = None,
+) -> list[dict[str, Any]]:
+    """重建业务列行；更新时原样保留已配置的系统列。
+
+    existing_by_que_id(读面展平行)存在时,以读面行为基底只更新可见性/序号——
+    保留列级权限(queAuth/beingAddRow/beingDeleteRow/beingEditRow/beingDownload 等),
+    否则重建会把这些标志归默认值,破坏既有列权限配置。
+    系统列读面占位对象不写回；existing_by_que_id=None 表示新建。
+    """
     visible_map = {que_id: index for index, que_id in enumerate(visible_que_ids, start=1)}
+    existing = existing_by_que_id or {}
     questions: list[dict[str, Any]] = []
     for base_question in schema.get("baseQues", []):
-        question = _build_viewgraph_question(base_question, visible_map, default_auth=3)
+        question = _build_viewgraph_question(base_question, visible_map, default_auth=3, existing=existing_by_que_id)
         if question is not None:
             questions.append(question)
     for line in schema.get("formQues", []):
         for question in line:
-            resolved = _build_viewgraph_question(question, visible_map, default_auth=1)
+            resolved = _build_viewgraph_question(question, visible_map, default_auth=1, existing=existing_by_que_id)
             if resolved is not None:
                 questions.append(resolved)
+    # 某些系统列只在视图读面出现，不属于表单 schema。
+    emitted_que_ids = _flatten_viewgraph_questions(questions)
+    for que_id, prior in existing.items():
+        if que_id <= 5 and que_id not in emitted_que_ids:
+            preserved = _build_viewgraph_question(prior, visible_map, default_auth=3, existing=existing)
+            if preserved is not None:
+                questions.append(preserved)
     return questions
 
 
-def _build_viewgraph_question(question: dict[str, Any], visible_map: dict[int, int], *, default_auth: int) -> dict[str, Any] | None:
+def _build_viewgraph_question(
+    question: dict[str, Any],
+    visible_map: dict[int, int],
+    *,
+    default_auth: int,
+    existing: dict[int, dict[str, Any]] | None = None,
+) -> dict[str, Any] | None:
     que_id = question.get("queId")
     if que_id is None:
         return None
+    if isinstance(que_id, int) and que_id <= 5 and existing is not None:
+        prior = existing.get(que_id)
+        # 后端会生成未落库的系统字段占位对象；只有落库配置才带这些列状态。
+        if prior is None or all(prior.get(key) is None for key in (
+            "beingListDisplay", "displayOrdinal", "beingAddRow", "beingEditRow", "beingDeleteRow",
+        )):
+            return None
+        return deepcopy(prior)
     sub_questions = [
         resolved
         for sub_question in question.get("subQuestions", []) or []
-        if (resolved := _build_viewgraph_question(sub_question, visible_map, default_auth=1)) is not None
+        if (resolved := _build_viewgraph_question(sub_question, visible_map, default_auth=1, existing=existing)) is not None
     ]
     inner_questions = [
         resolved
         for inner_row in question.get("innerQuestions", []) or []
         for inner_question in inner_row or []
-        if (resolved := _build_viewgraph_question(inner_question, visible_map, default_auth=1)) is not None
+        if (resolved := _build_viewgraph_question(inner_question, visible_map, default_auth=1, existing=existing)) is not None
     ]
+    prior = (existing or {}).get(que_id) if isinstance(que_id, int) else None
+    if prior is not None:
+        # 读面行为基底:保留全部列级标志,只更新可见性/序号;嵌套子项同样融合
+        merged = deepcopy(prior)
+        merged["beingListDisplay"] = que_id in visible_map
+        merged["displayOrdinal"] = visible_map.get(que_id, -1)
+        merged["subQues"] = sub_questions
+        merged["innerQues"] = inner_questions
+        return merged
     return {
         "queId": que_id,
         "queTitle": question.get("queTitle"),

package/src/qingflow_mcp/solution/spec_models.py

@@ -56,6 +56,7 @@ class ViewType(str, Enum):
     board = "board"
     gantt = "gantt"
     hierarchy = "hierarchy"
+    calendar = "calendar"
 
 
 class ChartType(str, Enum):