@qingflow-tech/qingflow-app-user-mcp 1.0.39 → 1.0.41

package/src/qingflow_mcp/cli/commands/builder.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 import argparse
+from copy import deepcopy
 
 from ..context import CliContext
-from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
 from ..json_io import load_json_value
+from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -479,6 +480,7 @@ def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
 def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
     apps_payload = _load_apps_file_arg(args.apps_file)
     apps = apps_payload["apps"]
+    apps_warnings = apps_payload.get("warnings") or []
     package_id = args.package_id
     if package_id is None and apps_payload.get("package_id") is not None:
         package_id = int(apps_payload["package_id"])
@@ -487,6 +489,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             raise_config_error(
                 "schema apply multi-app mode requires a non-empty --apps-file.",
                 fix_hint="Pass a JSON array, or a JSON object like {\"package_id\":1001,\"apps\":[...]} with at least one app item.",
+                error_code="APPS_FILE_EMPTY",
             )
         if args.app_key or args.app_name or args.app_title or args.add_fields_file or args.update_fields_file or args.remove_fields_file:
             raise_config_error(
@@ -498,7 +501,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
                 "schema apply multi-app mode requires --package-id.",
                 fix_hint="Pass `--package-id`, or put `package_id` at the top level of --apps-file. `package_name` alone does not create the package here; run `builder package apply` first.",
             )
-        return context.builder.app_schema_apply(
+        result = context.builder.app_schema_apply(
             profile=args.profile,
             package_id=package_id,
             visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
@@ -509,6 +512,11 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             update_fields=[],
             remove_fields=[],
         )
+        if apps_warnings and isinstance(result, dict):
+            result_warnings = list(result.get("warnings") or [])
+            result_warnings.extend(deepcopy(apps_warnings))
+            result["warnings"] = result_warnings
+        return result
     has_app_key = bool((args.app_key or "").strip())
     has_app_name = bool((args.app_name or "").strip())
     has_app_title = bool((args.app_title or "").strip())
@@ -545,8 +553,56 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
 def _load_apps_file_arg(path: str | None) -> dict[str, object]:
     if not path:
         return {"apps": []}
+    expected_shape = {
+        "package_id": 1001,
+        "apps": [
+            {
+                "client_key": "employee",
+                "app_name": "员工花名册",
+                "icon": "business-personalcard",
+                "color": "emerald",
+                "add_fields": [],
+            }
+        ],
+    }
+    expected_shape_details = {
+        "expected_shape": expected_shape,
+        "expected_shape_json": (
+            '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
+            '"icon":"business-personalcard","color":"emerald","add_fields":[]}]}'
+        ),
+    }
     payload = load_json_value(path, option_name="--apps-file")
     if isinstance(payload, list):
+        if len(payload) == 1 and isinstance(payload[0], dict) and "apps" in payload[0]:
+            wrapper = payload[0]
+            apps = wrapper.get("apps")
+            if not isinstance(apps, list):
+                raise_config_error(
+                    "--apps-file wrapper object requires an apps array.",
+                    fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw apps array like [{\"app_name\":\"...\",\"icon\":\"...\",\"color\":\"...\",\"add_fields\":[...]}].",
+                    error_code="APPS_FILE_SHAPE_INVALID",
+                    details=expected_shape_details,
+                )
+            result: dict[str, object] = {
+                "apps": apps,
+                "warnings": [
+                    {
+                        "code": "APPS_FILE_WRAPPER_ARRAY_UNWRAPPED",
+                        "message": "--apps-file was a singleton wrapper array; normalized it to {package_id, apps}.",
+                    }
+                ],
+            }
+            if wrapper.get("package_id") is not None:
+                result["package_id"] = wrapper.get("package_id")
+            return result
+        if any(isinstance(item, dict) and "apps" in item for item in payload):
+            raise_config_error(
+                "--apps-file root array items must be app items, not package wrapper objects.",
+                fix_hint="Use one object {\"package_id\":1001,\"apps\":[...]} or a raw app array [{\"app_name\":\"...\",\"icon\":\"...\",\"color\":\"...\",\"add_fields\":[...]}]. Do not wrap multiple {package_id, apps} objects in an array.",
+                error_code="APPS_FILE_SHAPE_INVALID",
+                details=expected_shape_details,
+            )
         return {"apps": payload}
     if isinstance(payload, dict):
         apps = payload.get("apps")
@@ -554,6 +610,8 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
             raise_config_error(
                 "--apps-file JSON object requires an apps array.",
                 fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw JSON array.",
+                error_code="APPS_FILE_SHAPE_INVALID",
+                details=expected_shape_details,
             )
         result: dict[str, object] = {"apps": apps}
         if payload.get("package_id") is not None:
@@ -562,6 +620,8 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
     raise_config_error(
         "--apps-file must be a JSON array or an object containing apps.",
         fix_hint="Use [{...}] or {\"package_id\":1001,\"apps\":[...]}",
+        error_code="APPS_FILE_SHAPE_INVALID",
+        details=expected_shape_details,
     )
 
 

package/src/qingflow_mcp/cli/commands/common.py

@@ -48,14 +48,23 @@ def read_secret_arg(value: str | None, *, stdin_enabled: bool, label: str) -> st
     raise QingflowApiError.config_error(f"{label} is required")
 
 
-def raise_config_error(message: str, *, fix_hint: str) -> None:
+def raise_config_error(
+    message: str,
+    *,
+    fix_hint: str | None = None,
+    error_code: str = "CONFIG_ERROR",
+    details: dict[str, Any] | None = None,
+) -> None:
+    error_details: dict[str, Any] = {"fix_hint": fix_hint or message}
+    if details:
+        error_details.update(details)
     raise RuntimeError(
         json.dumps(
             {
                 "category": "config",
                 "message": message,
-                "error_code": "CONFIG_ERROR",
-                "details": {"fix_hint": fix_hint},
+                "error_code": error_code,
+                "details": error_details,
             },
             ensure_ascii=False,
         )

package/src/qingflow_mcp/cli/formatters.py

@@ -36,6 +36,7 @@ def _is_executed_nonfatal_result(result: dict[str, Any]) -> bool:
     status = str(result.get("status") or "").lower()
     executed = bool(
         result.get("write_executed")
+        or result.get("write_may_have_succeeded")
         or result.get("delete_executed")
         or result.get("action_executed")
         or result.get("export_executed")

package/src/qingflow_mcp/cli/main.py

@@ -423,6 +423,7 @@ def _is_executed_nonfatal_result(result: dict[str, Any]) -> bool:
     status = str(result.get("status") or "").lower()
     executed = bool(
         result.get("write_executed")
+        or result.get("write_may_have_succeeded")
         or result.get("delete_executed")
         or result.get("action_executed")
         or result.get("export_executed")
@@ -441,6 +442,7 @@ def _has_readback_unavailable_verification(result: dict[str, Any]) -> bool:
             "readback_pending",
             "metadata_unverified",
             "views_read_unavailable",
+            "readback_before_retry",
         )
     )
 

package/src/qingflow_mcp/response_trim.py

@@ -169,6 +169,7 @@ def _is_executed_nonfatal_payload(payload: dict[str, Any]) -> bool:
     status = str(payload.get("status") or "").lower()
     executed = bool(
         payload.get("write_executed")
+        or payload.get("write_may_have_succeeded")
         or payload.get("delete_executed")
         or payload.get("action_executed")
         or payload.get("export_executed")