@qingflow-tech/qingflow-cli 1.1.50 → 1.1.53

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -115,6 +115,15 @@ def _elapsed_ms(started_at: float) -> int:
     return max(0, int((time.perf_counter() - started_at) * 1000))
 
 
+def _transport_error_payload(error: QingflowApiError) -> JSONObject:
+    return {
+        "http_status": error.http_status,
+        "backend_code": error.backend_code,
+        "category": error.category,
+        "request_id": error.request_id,
+    }
+
+
 def _merge_duration_breakdown(payload: JSONObject, **items: int | None) -> None:
     breakdown = payload.get("duration_breakdown_ms")
     if not isinstance(breakdown, dict):
@@ -151,7 +160,6 @@ BUILDER_APPLY_TOOL_NAMES = {
     "app_publish_verify",
 }
 MULTI_APP_SCHEMA_APPLY_PARALLEL_LIMIT = 10
-VIEW_APPLY_PARALLEL_LIMIT = 20
 PORTAL_INLINE_CHART_MAX_WORKERS = 10
 
 
@@ -434,6 +442,30 @@ class AiBuilderTools(ToolBase):
         ) -> JSONObject:
             return self.app_form_apply(profile=profile, spec=spec or {})
 
+        @mcp.tool()
+        def app_views_schema(
+            schema_version: str | None = None,
+            schema_kind: str | None = None,
+        ) -> JSONObject:
+            """Get a complete views schema or a focused detail schema such as display or button-config."""
+            return self.app_views_schema(schema_version=schema_version, schema_kind=schema_kind)
+
+        @mcp.tool()
+        def app_views_get(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            schema_version: str | None = None,
+            schema_kind: str | None = None,
+        ) -> JSONObject:
+            return self.app_views_get(profile=profile, app_key=app_key, schema_version=schema_version, schema_kind=schema_kind)
+
+        @mcp.tool()
+        def app_views_validate(
+            declaration: JSONObject | None = None,
+            schema_version: str | None = None,
+        ) -> JSONObject:
+            return self.app_views_validate(declaration=declaration or {}, schema_version=schema_version)
+
         @mcp.tool(description=self._high_risk_tool_description(operation="delete", target="app configuration"))
         def app_delete(
             profile: str = DEFAULT_PROFILE,
@@ -763,19 +795,17 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             publish: bool = True,
-            upsert_views: list[JSONObject] | None = None,
+            upsert_view: JSONObject | None = None,
             patch_views: list[JSONObject] | None = None,
             remove_views: list[str] | None = None,
-            apps: list[JSONObject] | None = None,
         ) -> JSONObject:
             return self.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,
             )
 
         @mcp.tool()
@@ -1979,20 +2009,22 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_charts", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
-    def app_get_buttons(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+    def app_get_buttons(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None, button_text: str | None = None) -> JSONObject:
         if app_keys is not None:
             return self._read_app_batch(
                 tool_name="app_get_buttons",
                 profile=profile,
                 app_keys=app_keys,
-                read_one=lambda item_app_key: self.app_get_buttons(profile=profile, app_key=item_app_key, app_keys=None),
+                read_one=lambda item_app_key: self.app_get_buttons(profile=profile, app_key=item_app_key, app_keys=None, button_text=button_text),
             )
-        normalized_args = {"app_key": app_key}
+        normalized_args: JSONObject = {"app_key": app_key}
+        if str(button_text or "").strip():
+            normalized_args["button_text"] = str(button_text or "").strip()
         return _safe_tool_call(
-            lambda: self._facade.app_get_buttons(profile=profile, app_key=app_key),
+            lambda: self._facade.app_get_buttons(profile=profile, app_key=app_key, button_text=button_text),
             error_code="APP_GET_BUTTONS_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_get_buttons", "arguments": {"profile": profile, "app_key": app_key}},
+            suggested_next_call={"tool_name": "app_get_buttons", "arguments": {"profile": profile, **normalized_args}},
         )
 
     def app_get_associated_resources(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
@@ -2251,17 +2283,34 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str,
+        upsert_view: JSONObject | None = None,
         upsert_views: list[JSONObject] | None = None,
         patch_views: list[JSONObject] | None = None,
         remove_views: list[str] | None = None,
         preset: str | None = None,
     ) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Plan one new or fully updated view, plus optional existing-view changes."""
+        if upsert_view is not None and upsert_views:
+            return _config_failure(
+                tool_name="app_views_plan",
+                message="pass either upsert_view or upsert_views, not both.",
+                fix_hint="Use upsert_view for one new or full view declaration.",
+                details={"provided": ["upsert_view", "upsert_views"]},
+            )
+        normalized_upsert_views = [upsert_view] if upsert_view is not None else list(upsert_views or [])
+        if len(normalized_upsert_views) > 1:
+            return _config_failure(
+                tool_name="app_views_plan",
+                message="app_views_plan supports planning one new or fully updated view per call.",
+                fix_hint="Call app_views_plan once for each view, using upsert_view.",
+                details={"max_upsert_views": 1, "received_upsert_views": len(normalized_upsert_views)},
+                error_code="VIEW_BATCH_CREATE_UNSUPPORTED",
+            )
         reserved_failure = _reserved_system_view_name_failure(
             tool_name="app_views_plan",
             profile=profile,
             app_key=app_key,
-            upsert_views=upsert_views,
+            upsert_views=normalized_upsert_views,
             remove_views=remove_views,
         )
         if reserved_failure is not None:
@@ -2270,7 +2319,7 @@ class AiBuilderTools(ToolBase):
             request = ViewsPlanRequest.model_validate(
                 {
                     "app_key": app_key,
-                    "upsert_views": upsert_views or [],
+                    "upsert_views": normalized_upsert_views,
                     "patch_views": patch_views or [],
                     "remove_views": remove_views or [],
                     "preset": preset,
@@ -2287,7 +2336,7 @@ class AiBuilderTools(ToolBase):
                         "profile": profile,
                         "app_key": app_key,
                         "preset": "default_table",
-                        "upsert_views": [],
+                        "upsert_view": None,
                         "patch_views": [],
                         "remove_views": [],
                     },
@@ -2298,7 +2347,7 @@ class AiBuilderTools(ToolBase):
             error_code="VIEWS_PLAN_FAILED",
             normalized_args={
                 "app_key": request.app_key,
-                "upsert_views": [public_view_upsert_payload(view) for view in request.upsert_views],
+                "upsert_view": public_view_upsert_payload(request.upsert_views[0]) if request.upsert_views else None,
                 "patch_views": [public_view_partial_payload(patch) for patch in request.patch_views],
                 "remove_views": list(request.remove_views),
                 "preset": request.preset.value if request.preset is not None else None,
@@ -2308,7 +2357,7 @@ class AiBuilderTools(ToolBase):
                 "arguments": {
                     "profile": profile,
                     "app_key": request.app_key,
-                    "upsert_views": [public_view_upsert_payload(view) for view in request.upsert_views],
+                    "upsert_view": public_view_upsert_payload(request.upsert_views[0]) if request.upsert_views else None,
                     "patch_views": [public_view_partial_payload(patch) for patch in request.patch_views],
                     "remove_views": list(request.remove_views),
                     "preset": request.preset.value if request.preset is not None else None,
@@ -3931,41 +3980,47 @@ class AiBuilderTools(ToolBase):
         profile: str,
         app_key: str,
         publish: bool = True,
-        upsert_views: list[JSONObject],
+        upsert_view: JSONObject | None = None,
         patch_views: list[JSONObject] | None = None,
-        remove_views: list[str],
-        apps: list[JSONObject] | None = None,
-        views: list[JSONObject] | None = None,
+        remove_views: list[str] | None = None,
+        schema_version: str | None = None,
+        upsert_views: list[JSONObject] | None = None,
     ) -> JSONObject:
-        """执行应用相关逻辑。"""
-        if views is not None:
-            return self._app_views_apply_view_batch(
-                profile=profile,
-                publish=publish,
-                views=views,
+        """Apply one new or full view declaration for one application.
+
+        ``upsert_views`` remains an internal compatibility alias while callers
+        migrate to ``upsert_view``. It accepts at most one item.
+        """
+        if upsert_view is not None and upsert_views:
+            return _attach_builder_apply_envelope(
+                "app_views_apply",
+                _config_failure(
+                    tool_name="app_views_apply",
+                    message="pass either upsert_view or upsert_views, not both.",
+                    fix_hint="Use upsert_view for one new or full view declaration.",
+                    details={"provided": ["upsert_view", "upsert_views"]},
+                ),
             )
-        if apps is not None:
-            return self._apply_app_batch(
-                tool_name="app_views_apply",
-                profile=profile,
-                apps=apps,
-                apply_one=lambda _index, item, item_app_key: self.app_views_apply(
-                    profile=profile,
-                    app_key=item_app_key,
-                    publish=_payload_bool(item, "publish", default=publish),
-                    upsert_views=_payload_list(item, "upsert_views", "upsertViews", "views", default=upsert_views or []),
-                    patch_views=_payload_list(item, "patch_views", "patchViews", default=patch_views or []),
-                    remove_views=_payload_list(item, "remove_views", "removeViews", default=remove_views or []),
-                    apps=None,
+        normalized_upsert_views = [upsert_view] if upsert_view is not None else list(upsert_views or [])
+        if len(normalized_upsert_views) > 1:
+            return _attach_builder_apply_envelope(
+                "app_views_apply",
+                _config_failure(
+                    tool_name="app_views_apply",
+                    message="app_views_apply supports creating or fully updating one view per call.",
+                    fix_hint="Call app_views_apply once for each view, using upsert_view.",
+                    details={"max_upsert_views": 1, "received_upsert_views": len(normalized_upsert_views)},
+                    error_code="VIEW_BATCH_CREATE_UNSUPPORTED",
                 ),
             )
         result = self._app_views_apply_once(
             profile=profile,
             app_key=app_key,
             publish=publish,
-            upsert_views=upsert_views,
+            upsert_views=normalized_upsert_views,
             patch_views=patch_views or [],
-            remove_views=remove_views,
+            remove_views=remove_views or [],
+            schema_version=schema_version,
         )
         result = self._retry_after_self_lock_release(
             profile=profile,
@@ -3974,255 +4029,14 @@ class AiBuilderTools(ToolBase):
                 profile=profile,
                 app_key=app_key,
                 publish=publish,
-                remove_views=remove_views,
-                upsert_views=upsert_views,
+                remove_views=remove_views or [],
+                upsert_views=normalized_upsert_views,
                 patch_views=patch_views or [],
+                schema_version=schema_version,
             ),
         )
         return self._attach_apply_envelope(profile, "app_views_apply", result)
 
-    def _app_views_apply_view_batch(
-        self,
-        *,
-        profile: str,
-        publish: bool,
-        views: list[JSONObject],
-    ) -> JSONObject:
-        started_at = time.perf_counter()
-        if not isinstance(views, list) or not views:
-            return self._attach_apply_envelope(profile,
-                "app_views_apply",
-                _config_failure(
-                    tool_name="app_views_apply",
-                    message="app_views_apply views[] batch mode requires a non-empty views array.",
-                    fix_hint="Pass views as a JSON array; each item must include app_key and operation.",
-                    details={"expected_shape": {"views": [{"operation": "upsert", "app_key": "APP_KEY", "name": "业务视图", "type": "table", "columns": ["字段A"]}]}},
-                ),
-            )
-
-        def _infer_operation(item: JSONObject) -> str:
-            raw = str(item.get("operation") or item.get("op") or "").strip().lower()
-            aliases = {
-                "create": "upsert",
-                "update": "upsert",
-                "replace": "upsert",
-                "delete": "remove",
-                "remove": "remove",
-                "patch": "patch",
-                "upsert": "upsert",
-            }
-            if raw:
-                return aliases.get(raw, raw)
-            if "set" in item or "unset" in item or "update" in item or "values" in item:
-                return "patch"
-            if "view_key" in item or "viewKey" in item:
-                return "patch" if ("name" in item or "type" in item or "columns" in item or "fields" in item) else "remove"
-            return "upsert"
-
-        def _view_job_payload(item: JSONObject) -> JSONObject:
-            return {
-                key: deepcopy(value)
-                for key, value in item.items()
-                if key
-                not in {
-                    "operation",
-                    "op",
-                    "app_key",
-                    "appKey",
-                    "publish",
-                }
-            }
-
-        def _view_selector(payload: JSONObject) -> str:
-            return str(payload.get("view_key") or payload.get("viewKey") or payload.get("viewgraphKey") or payload.get("viewGraphKey") or payload.get("name") or "").strip()
-
-        normalized_jobs: list[JSONObject] = []
-        job_results: list[JSONObject | None] = [None for _ in views]
-        errors: list[JSONObject] = []
-        seen_patch_remove: dict[tuple[str, str], int] = {}
-        seen_upsert_names: dict[tuple[str, str], int] = {}
-
-        def _add_validation_error(index: int, error_code: str, message: str, *, app_key: str = "", operation: str = "", reason_path: str = "") -> None:
-            error = {
-                "index": index,
-                "app_key": app_key,
-                "operation": operation,
-                "status": "failed",
-                "error_code": error_code,
-                "message": message,
-                **({"reason_path": reason_path} if reason_path else {}),
-            }
-            errors.append(error)
-            job_results[index] = error
-
-        for index, item in enumerate(views):
-            if not isinstance(item, dict):
-                _add_validation_error(index, "VIEWS_FILE_ITEM_INVALID", "views[] item must be an object", reason_path=f"views[{index}]")
-                continue
-            app_key = str(item.get("app_key") or item.get("appKey") or "").strip()
-            operation = _infer_operation(item)
-            payload = _view_job_payload(item)
-            if not app_key:
-                _add_validation_error(index, "VIEWS_FILE_APP_KEY_REQUIRED", "views[] item requires app_key", operation=operation, reason_path=f"views[{index}].app_key")
-                continue
-            if operation not in {"upsert", "patch", "remove"}:
-                _add_validation_error(index, "VIEWS_FILE_OPERATION_INVALID", "views[].operation must be upsert, patch, or remove", app_key=app_key, operation=operation, reason_path=f"views[{index}].operation")
-                continue
-            selector = _view_selector(payload)
-            if operation in {"patch", "remove"} and not selector:
-                _add_validation_error(index, "VIEWS_FILE_VIEW_SELECTOR_REQUIRED", f"{operation} view job requires view_key or name", app_key=app_key, operation=operation, reason_path=f"views[{index}].view_key")
-                continue
-            if operation in {"patch", "remove"} and selector:
-                conflict_key = (app_key, selector)
-                first_index = seen_patch_remove.get(conflict_key)
-                if first_index is not None:
-                    _add_validation_error(index, "DUPLICATE_VIEW_JOB_CONFLICT", f"views[{index}] conflicts with views[{first_index}] for the same app/view selector", app_key=app_key, operation=operation, reason_path=f"views[{index}]")
-                    continue
-                seen_patch_remove[conflict_key] = index
-            if operation == "upsert":
-                name = str(payload.get("name") or "").strip()
-                if name:
-                    conflict_key = (app_key, name)
-                    first_index = seen_upsert_names.get(conflict_key)
-                    if first_index is not None:
-                        _add_validation_error(index, "DUPLICATE_VIEW_NAME_IN_BATCH", f"views[{index}] duplicates upsert view name from views[{first_index}] in the same app", app_key=app_key, operation=operation, reason_path=f"views[{index}].name")
-                        continue
-                    seen_upsert_names[conflict_key] = index
-            normalized_jobs.append(
-                {
-                    "index": index,
-                    "app_key": app_key,
-                    "operation": operation,
-                    "publish": _payload_bool(item, "publish", default=publish),
-                    "payload": payload,
-                }
-            )
-
-        def _extract_view_identity(result: JSONObject, fallback_payload: JSONObject, fallback_operation: str) -> tuple[str | None, str | None, str]:
-            diff = result.get("views_diff") if isinstance(result.get("views_diff"), dict) else {}
-            for key, operation_name in (("created", "created"), ("updated", "updated"), ("removed", "removed"), ("failed", "failed")):
-                entries = diff.get(key)
-                if isinstance(entries, list) and entries:
-                    entry = entries[0]
-                    if isinstance(entry, dict):
-                        return (
-                            str(entry.get("name") or entry.get("view_name") or entry.get("viewName") or fallback_payload.get("name") or "").strip() or None,
-                            str(entry.get("view_key") or entry.get("viewKey") or fallback_payload.get("view_key") or fallback_payload.get("viewKey") or "").strip() or None,
-                            operation_name,
-                        )
-                    if entry not in (None, ""):
-                        return (str(entry), None, operation_name)
-            fallback_name = str(fallback_payload.get("name") or "").strip() or None
-            fallback_view_key = str(fallback_payload.get("view_key") or fallback_payload.get("viewKey") or "").strip() or None
-            return fallback_name, fallback_view_key, "removed" if fallback_operation == "remove" else "updated"
-
-        def _run_view_job(job: JSONObject) -> JSONObject:
-            payload = deepcopy(job["payload"])
-            operation = str(job["operation"])
-            app_key = str(job["app_key"])
-            job_publish = bool(job.get("publish"))
-            if operation == "upsert":
-                call_kwargs = {"upsert_views": [payload], "patch_views": [], "remove_views": []}
-            elif operation == "patch":
-                call_kwargs = {"upsert_views": [], "patch_views": [payload], "remove_views": []}
-            else:
-                call_kwargs = {"upsert_views": [], "patch_views": [], "remove_views": [_view_selector(payload)]}
-            result = self._app_views_apply_once(
-                profile=profile,
-                app_key=app_key,
-                publish=job_publish,
-                **call_kwargs,
-            )
-            result = self._retry_after_self_lock_release(
-                profile=profile,
-                result=result,
-                retry_call=lambda: self._app_views_apply_once(
-                    profile=profile,
-                    app_key=app_key,
-                    publish=job_publish,
-                    **call_kwargs,
-                ),
-            )
-            status = str(result.get("status") or "success") if isinstance(result, dict) else "failed"
-            name, view_key, actual_operation = _extract_view_identity(result if isinstance(result, dict) else {}, payload, operation)
-            item: JSONObject = {
-                "index": job["index"],
-                "app_key": app_key,
-                "operation": actual_operation if status != "failed" else operation,
-                "requested_operation": operation,
-                "status": status,
-                **({"name": name} if name else {}),
-                **({"view_key": view_key} if view_key else {}),
-                "result": result if isinstance(result, dict) else {"status": "failed", "message": str(result)},
-            }
-            if status == "failed":
-                item["error_code"] = item["result"].get("error_code")
-                item["message"] = item["result"].get("message")
-            return item
-
-        view_write_started_at = time.perf_counter()
-        view_workers = min(VIEW_APPLY_PARALLEL_LIMIT, len(normalized_jobs)) if normalized_jobs else 0
-        if normalized_jobs:
-            with ThreadPoolExecutor(max_workers=view_workers) as executor:
-                future_map = {executor.submit(_run_view_job, job): job for job in normalized_jobs}
-                for future in as_completed(future_map):
-                    job = future_map[future]
-                    try:
-                        item_result = future.result()
-                    except (QingflowApiError, RuntimeError) as error:
-                        api_error = _coerce_api_error(error)
-                        item_result = {
-                            "index": job["index"],
-                            "app_key": job["app_key"],
-                            "operation": job["operation"],
-                            "requested_operation": job["operation"],
-                            "status": "failed",
-                            "error_code": "VIEW_BATCH_JOB_FAILED",
-                            "message": _public_error_message("VIEW_BATCH_JOB_FAILED", api_error),
-                            "details": {"transport_error": _transport_error_payload(api_error)},
-                            "request_id": api_error.request_id,
-                            "backend_code": api_error.backend_code,
-                            "http_status": None if api_error.http_status == 404 else api_error.http_status,
-                        }
-                    job_results[int(job["index"])] = item_result
-        view_write_parallel_wall_ms = _elapsed_ms(view_write_started_at)
-
-        final_views = [item if isinstance(item, dict) else {"index": index, "status": "failed", "error_code": "VIEW_BATCH_JOB_MISSING", "message": "view batch job did not produce a result"} for index, item in enumerate(job_results)]
-        errors.extend(item for item in final_views if str(item.get("status") or "") == "failed" and item not in errors)
-        partial = sum(1 for item in final_views if str(item.get("status") or "") == "partial_success")
-        succeeded = sum(1 for item in final_views if str(item.get("status") or "") in {"success", "partial_success"})
-        failed = len(final_views) - succeeded
-        status = "failed" if succeeded == 0 else "partial_success" if failed > 0 or partial > 0 else "success"
-        write_executed = any(
-            isinstance(item.get("result"), dict) and bool(item["result"].get("write_executed"))
-            for item in final_views
-        )
-        payload: JSONObject = {
-            "status": status,
-            "error_code": None if status == "success" else "APP_VIEWS_APPLY_BATCH_PARTIAL" if succeeded else "APP_VIEWS_APPLY_BATCH_FAILED",
-            "recoverable": failed > 0 or partial > 0,
-            "message": f"applied app_views_apply to {succeeded}/{len(final_views)} views" if status != "success" else f"applied app_views_apply to {succeeded} views",
-            "normalized_args": {"views": views},
-            "views": final_views,
-            "errors": errors,
-            "parallelism": {"view_workers": view_workers, "same_app_parallel": True},
-            "verification": {
-                "batch_verified": failed == 0 and partial == 0,
-                "succeeded": succeeded,
-                "partial": partial,
-                "failed": failed,
-            },
-            "write_executed": write_executed,
-            "write_succeeded": write_executed and failed == 0 and partial == 0,
-            "safe_to_retry": not write_executed,
-        }
-        _merge_duration_breakdown(
-            payload,
-            view_write_parallel_wall_ms=view_write_parallel_wall_ms,
-            total_ms=_elapsed_ms(started_at),
-        )
-        return self._attach_apply_envelope(profile, "app_views_apply", payload)
-
     def _app_views_apply_once(
         self,
         *,
@@ -4232,6 +4046,7 @@ class AiBuilderTools(ToolBase):
         upsert_views: list[JSONObject],
         patch_views: list[JSONObject],
         remove_views: list[str],
+        schema_version: str | None = None,
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
         reserved_failure = _reserved_system_view_name_failure(
@@ -4259,7 +4074,7 @@ class AiBuilderTools(ToolBase):
                         "profile": profile,
                         "app_key": app_key,
                         "publish": publish,
-                        "upsert_views": upsert_views or [{"name": "业务台账视图", "type": "table", "columns": ["字段A"]}],
+                        "upsert_view": (upsert_views[0] if upsert_views else {"name": "业务台账视图", "type": "table", "columns": ["字段A"]}),
                         "patch_views": patch_views or [],
                         "remove_views": remove_views or [],
                     },
@@ -4268,9 +4083,10 @@ class AiBuilderTools(ToolBase):
         normalized_args = {
             "app_key": app_key,
             "publish": publish,
-            "upsert_views": [public_view_upsert_payload(view) for view in parsed_views],
+            "upsert_view": public_view_upsert_payload(parsed_views[0]) if parsed_views else None,
             "patch_views": [public_view_partial_payload(patch) for patch in parsed_patch_views],
             "remove_views": list(remove_views or []),
+            "schema_version": schema_version,
         }
         return _safe_tool_call(
             lambda: self._facade.app_views_apply(
@@ -4280,12 +4096,44 @@ class AiBuilderTools(ToolBase):
                 upsert_views=parsed_views,
                 patch_views=parsed_patch_views,
                 remove_views=list(remove_views or []),
+                schema_version=schema_version,
             ),
             error_code="VIEWS_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    def app_views_schema(
+        self,
+        *,
+        schema_version: str | None = None,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
+        """Return a versioned views schema (summary/complete or a focused detail kind)."""
+        return self._facade.app_views_schema(schema_version=schema_version, schema_kind=schema_kind)
+
+    def app_views_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        schema_version: str | None = None,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
+        """Read canonical views declarations (summary projection or complete reverse-compilation)."""
+        return self._facade.app_views_get(
+            profile=profile, app_key=app_key, schema_version=schema_version, schema_kind=schema_kind or "summary"
+        )
+
+    def app_views_validate(
+        self,
+        *,
+        declaration: JSONObject,
+        schema_version: str | None = None,
+    ) -> JSONObject:
+        """Offline-validate a views declaration without touching the backend."""
+        return self._facade.app_views_validate(declaration=declaration or {}, schema_version=schema_version)
+
     def chart_apply(
         self,
         *,
@@ -5668,12 +5516,10 @@ def _reserved_system_view_name_failure(
                 "arguments": {
                     "profile": profile,
                     "app_key": app_key,
-                    "upsert_views": [
-                        {
-                            **item,
-                            "name": "业务台账视图",
-                        }
-                    ],
+                    "upsert_view": {
+                        **item,
+                        "name": "业务台账视图",
+                    },
                     "patch_views": patch_views or [],
                     "remove_views": remove_views or [],
                 },
@@ -5683,7 +5529,7 @@ def _reserved_system_view_name_failure(
             return _config_failure(
                 tool_name=tool_name,
                 error_code="RESERVED_SYSTEM_VIEW_NAME",
-                message=f"upsert_views[{index}].name uses built-in system view name '{name}' without view_key",
+                message=f"upsert_view.name uses built-in system view name '{name}' without view_key",
                 fix_hint="Do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送. Use a business-specific view name for new views; to modify a built-in view, pass its existing raw view_key or use patch_views.",
                 details={
                     "reserved_view_names": sorted(_RESERVED_SYSTEM_VIEW_NAMES),
@@ -8147,20 +7993,20 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
     "app_views_plan": {
         "allowed_keys": [
             "app_key",
-            "upsert_views",
+            "upsert_view",
             "patch_views",
             "remove_views",
             "preset",
-            "upsert_views[].view_key",
-            "upsert_views[].name",
-            "upsert_views[].type",
-            "upsert_views[].columns",
-            "upsert_views[].filters",
-            "upsert_views[].buttons",
-            "upsert_views[].action_buttons",
-            "upsert_views[].action_buttons_mode",
-            "upsert_views[].visibility",
-            "upsert_views[].query_conditions",
+            "upsert_view.view_key",
+            "upsert_view.name",
+            "upsert_view.type",
+            "upsert_view.columns",
+            "upsert_view.filters",
+            "upsert_view.buttons",
+            "upsert_view.action_buttons",
+            "upsert_view.action_buttons_mode",
+            "upsert_view.visibility",
+            "upsert_view.query_conditions",
             "patch_views[].view_key",
             "patch_views[].name",
             "patch_views[].set",
@@ -8181,6 +8027,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "queryConditions": "query_conditions",
             "query_condition": "query_conditions",
             "queryCondition": "query_conditions",
+            "upsertView": "upsert_view",
             "patchViews": "patch_views",
             "startField": "start_field",
             "endField": "end_field",
@@ -8215,18 +8062,19 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "execution_notes": [
             "creating a new view follows backend createViewgraphConfig and requires both ViewManagementAuth and DataManageAuth; updating/deleting existing views only requires ViewManagementAuth",
-            "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
+            "upsert_view accepts one new or full view declaration; plan additional views in separate calls",
+            "upsert_view.visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
-            "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
+            "upsert_view.query_conditions.rows is a layout matrix of query-panel supported field names, field IDs, or queIds; queIds are preferred and all forms are compiled to backend queryCondition queIds",
             "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
             "use patch_views for partial parameter replacement on existing views; the tool reads current config, merges patch_views[].set/unset, then submits the backend full-save payload internally",
             "business buttons should be declared with action_buttons on the target view; app_views_apply writes the view first, then compiles action_buttons through the custom button writer and binds them to the resulting view_key",
             "action_buttons_mode defaults to merge; replace rewrites this view's custom button bindings, and replace plus action_buttons=[] clears this view's custom button bindings without deleting button bodies",
-            "legacy upsert_views[].buttons is a compatibility path for raw full replacement of existing view button config; do not use it as the normal agent path",
+            "legacy upsert_view.buttons is a compatibility path for raw full replacement of existing view button config; do not use it as the normal agent path",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
             "do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送; these are built-in system/default views. Use business-specific names for new views, and pass the existing raw view_key or patch_views when changing a built-in view",
-            "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_views explicitly changes associated_resources",
+            "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_view explicitly changes associated_resources",
             "associated report/view resource pool and per-view selected resources are configured through app_associated_resources_apply; app_views_apply only keeps legacy associated_resources input compatible",
             "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
             *_VISIBILITY_EXECUTION_NOTES,
@@ -8234,7 +8082,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "upsert_views": [{"name": "项目台账视图", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "upsert_view": {"name": "项目台账视图", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)},
             "remove_views": [],
         },
         "query_conditions_example": {
@@ -8256,41 +8104,37 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "action_buttons_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "upsert_views": [
-                {
-                    "name": "生产工单执行视图",
-                    "type": "table",
-                    "columns": ["工单编号", "产品", "状态", "负责人"],
-                    "action_buttons": [
-                        {
-                            "text": "开始生产",
-                            "action": "link",
-                            "url": "https://example.com/start",
-                            "placement": "list",
-                            "visible_when": [{"field_name": "状态", "operator": "eq", "value": "待排产"}],
-                        }
-                    ],
-                }
-            ],
+            "upsert_view": {
+                "name": "生产工单执行视图",
+                "type": "table",
+                "columns": ["工单编号", "产品", "状态", "负责人"],
+                "action_buttons": [
+                    {
+                        "text": "开始生产",
+                        "action": "link",
+                        "url": "https://example.com/start",
+                        "placement": "list",
+                        "visible_when": [{"field_name": "状态", "operator": "eq", "value": "待排产"}],
+                    }
+                ],
+            },
             "remove_views": [],
         },
         "full_upsert_query_conditions_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "upsert_views": [
-                {
-                    "name": "客户查询视图",
-                    "type": "table",
-                    "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
-                    "filters": [{"field_name": "客户状态", "operator": "eq", "value": "有效"}],
-                    "query_conditions": {
-                        "enabled": True,
-                        "exact": False,
-                        "hide_before_query": False,
-                        "rows": [["客户名称", "负责人"], ["创建时间"]],
-                    },
-                }
-            ],
+            "upsert_view": {
+                "name": "客户查询视图",
+                "type": "table",
+                "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
+                "filters": [{"field_name": "客户状态", "operator": "eq", "value": "有效"}],
+                "query_conditions": {
+                    "enabled": True,
+                    "exact": False,
+                    "hide_before_query": False,
+                    "rows": [["客户名称", "负责人"], ["创建时间"]],
+                },
+            },
             "remove_views": [],
         },
         "query_conditions_field_rules": {
@@ -8304,48 +8148,35 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "upsert_views": [
-                {
-                    "name": "项目甘特图",
-                    "type": "gantt",
-                    "columns": ["项目名称", "开始日期", "结束日期"],
-                    "start_field": "开始日期",
-                    "end_field": "结束日期",
-                    "title_field": "项目名称",
-                    "filters": [{"field_name": "状态", "operator": "eq", "value": "进行中"}],
-                }
-            ],
+            "upsert_view": {
+                "name": "项目甘特图",
+                "type": "gantt",
+                "columns": ["项目名称", "开始日期", "结束日期"],
+                "start_field": "开始日期",
+                "end_field": "结束日期",
+                "title_field": "项目名称",
+                "filters": [{"field_name": "状态", "operator": "eq", "value": "进行中"}],
+            },
             "remove_views": [],
         },
     },
     "app_views_apply": {
         "allowed_keys": [
-            "views",
-            "views[].operation",
-            "views[].app_key",
-            "views[].view_key",
-            "views[].name",
-            "views[].type",
-            "views[].columns",
-            "views[].filters",
-            "views[].action_buttons",
-            "views[].set",
-            "views[].unset",
             "app_key",
             "publish",
-            "upsert_views",
+            "upsert_view",
             "patch_views",
             "remove_views",
-            "upsert_views[].view_key",
-            "upsert_views[].name",
-            "upsert_views[].type",
-            "upsert_views[].columns",
-            "upsert_views[].filters",
-            "upsert_views[].buttons",
-            "upsert_views[].action_buttons",
-            "upsert_views[].action_buttons_mode",
-            "upsert_views[].visibility",
-            "upsert_views[].query_conditions",
+            "upsert_view.view_key",
+            "upsert_view.name",
+            "upsert_view.type",
+            "upsert_view.columns",
+            "upsert_view.filters",
+            "upsert_view.buttons",
+            "upsert_view.action_buttons",
+            "upsert_view.action_buttons_mode",
+            "upsert_view.visibility",
+            "upsert_view.query_conditions",
             "patch_views[].view_key",
             "patch_views[].name",
             "patch_views[].set",
@@ -8366,10 +8197,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "queryConditions": "query_conditions",
             "query_condition": "query_conditions",
             "queryCondition": "query_conditions",
-            "views[].op": "views[].operation",
-            "views[].fields": "views[].columns",
-            "views[].viewKey": "views[].view_key",
-            "views[].actionButtons": "views[].action_buttons",
+            "upsertView": "upsert_view",
             "patchViews": "patch_views",
             "startField": "start_field",
             "endField": "end_field",
@@ -8392,7 +8220,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "action_buttons[].defaultValues": "action_buttons[].default_values",
         },
         "allowed_values": {
-            "views[].operation": ["upsert", "patch", "remove"],
             "view.type": [member.value for member in PublicViewType],
             "view.filter.operator": [member.value for member in ViewFilterOperator],
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
@@ -8403,9 +8230,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
-            "preferred batch input is views[]; each item has app_key and operation=upsert/patch/remove, and the same batch may mix same-app and cross-app views",
-            f"views[] jobs run concurrently with an internal limit of {VIEW_APPLY_PARALLEL_LIMIT}; results are returned in input order",
-            "apply may return partial_success when some views land and others fail",
+            "upsert_view accepts one new or full view declaration for the app_key in this call; submit additional views in separate calls",
             "creating a new view follows backend createViewgraphConfig and requires both ViewManagementAuth and DataManageAuth; updating/deleting existing views only requires ViewManagementAuth",
             "when duplicate view names exist, supply view_key to target the exact view",
             "read back app_get after any failed or partial view apply",
@@ -8414,24 +8239,25 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "business buttons should be declared with action_buttons on the target view; app_views_apply writes the view first, then compiles action_buttons through the custom button writer and binds them to the resulting view_key",
             "patch_views[].set.action_buttons can add buttons to an existing view without rewriting columns/filters; action_buttons_mode defaults to merge, replace rewrites this view's custom button bindings, and replace plus action_buttons=[] clears bindings without deleting button bodies",
             "publish=false with action_buttons is blocked as VIEW_ACTION_BUTTONS_REQUIRE_PUBLISH because the underlying custom button writer may publish after successful button writes",
-            "legacy upsert_views[].buttons is a compatibility path for raw full replacement of existing view button config; do not use it as the normal agent path",
-            "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
+            "upsert_view.buttons is a compatibility path for raw full replacement of existing view button config; do not use it as the normal agent path",
+            "upsert_view.visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
-            "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
+            "upsert_view.query_conditions.rows is a layout matrix of query-panel supported field names, field IDs, or queIds; queIds are preferred and all forms are compiled to backend queryCondition queIds",
             "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
             "use patch_views for partial parameter replacement on existing views; the public update mode is patch even though the backend save is still a full view payload",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
             "do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送; these are built-in system/default views. Use business-specific names for new views, and pass the existing raw view_key or patch_views when changing a built-in view",
-            "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_views explicitly changes associated_resources",
+            "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_view explicitly changes associated_resources",
             "associated report/view resource pool and per-view selected resources are configured through app_associated_resources_apply; app_views_apply keeps legacy associated_resources input compatible but it is no longer the recommended public contract",
             "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
             "profile": "default",
+            "app_key": "APP_KEY",
             "publish": True,
-            "views": [{"operation": "upsert", "app_key": "APP_KEY", "name": "项目台账视图", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "upsert_view": {"name": "项目台账视图", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)},
         },
         "query_conditions_example": {
             "profile": "default",
@@ -8454,8 +8280,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "app_key": "APP_KEY",
             "publish": True,
-            "upsert_views": [
-                {
+            "upsert_view": {
                     "name": "生产工单执行视图",
                     "type": "table",
                     "columns": ["工单编号", "产品", "状态", "负责人"],
@@ -8468,8 +8293,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                             "visible_when": [{"field_name": "状态", "operator": "eq", "value": "待排产"}],
                         }
                     ],
-                }
-            ],
+                },
             "remove_views": [],
         },
         "action_buttons_patch_example": {
@@ -8499,8 +8323,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "app_key": "APP_KEY",
             "publish": True,
-            "upsert_views": [
-                {
+            "upsert_view": {
                     "name": "客户查询视图",
                     "type": "table",
                     "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
@@ -8511,8 +8334,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                         "hide_before_query": False,
                         "rows": [["客户名称", "负责人"], ["创建时间"]],
                     },
-                }
-            ],
+                },
             "remove_views": [],
         },
         "query_conditions_field_rules": {
@@ -8527,8 +8349,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "app_key": "APP_KEY",
             "publish": True,
-            "upsert_views": [
-                {
+            "upsert_view": {
                     "name": "项目甘特图",
                     "type": "gantt",
                     "columns": ["项目名称", "开始日期", "结束日期"],
@@ -8536,8 +8357,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                     "end_field": "结束日期",
                     "title_field": "项目名称",
                     "filters": [{"field_name": "状态", "operator": "eq", "value": "进行中"}],
-                }
-            ],
+                },
             "remove_views": [],
         },
     },