@josephyan/qingflow-app-user-mcp 1.1.26 → 1.1.28

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -7,7 +7,7 @@ import json
 import re
 from threading import Lock
 import time
-from typing import Any
+from typing import Any, cast
 
 from pydantic import ValidationError
 
@@ -92,6 +92,7 @@ BUILDER_APPLY_TOOL_NAMES = {
     "app_publish_verify",
 }
 VIEW_BATCH_MAX_WORKERS = 20
+SCHEMA_MULTI_APP_MAX_WORKERS = 10
 
 
 def _view_batch_operation(value: Any) -> str:
@@ -429,14 +430,15 @@ class AiBuilderTools(ToolBase):
             add_fields: list[JSONObject] | None = None,
             update_fields: list[JSONObject] | None = None,
             remove_fields: list[JSONObject] | None = None,
+            form: JSONObject | None = None,
             apps: list[JSONObject] | None = None,
         ) -> JSONObject:
             if apps:
-                if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
+                if app_key or app_name or app_title or add_fields or update_fields or remove_fields or form:
                     return _config_failure(
                         tool_name="app_schema_apply",
                         message="app_schema_apply multi-app mode accepts package_id/create_if_missing plus apps only.",
-                        fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
+                        fix_hint="Use `apps[].form` for batch mode, or use the single-app arguments including `form` without `apps`.",
                     )
                 if package_id is None:
                     return _config_failure(
@@ -486,6 +488,7 @@ class AiBuilderTools(ToolBase):
                 add_fields=add_fields or [],
                 update_fields=update_fields or [],
                 remove_fields=remove_fields or [],
+                form=form,
                 apps=[],
             )
 
@@ -1750,6 +1753,7 @@ class AiBuilderTools(ToolBase):
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
+        form: JSONObject | None = None,
         apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
@@ -1777,6 +1781,7 @@ class AiBuilderTools(ToolBase):
             add_fields=add_fields,
             update_fields=update_fields,
             remove_fields=remove_fields,
+            form=form,
         )
         result = self._retry_after_self_lock_release(
             profile=profile,
@@ -1795,6 +1800,7 @@ class AiBuilderTools(ToolBase):
                 add_fields=add_fields,
                 update_fields=update_fields,
                 remove_fields=remove_fields,
+                form=form,
             ),
         )
         return _attach_builder_apply_envelope("app_schema_apply", result)
@@ -1892,50 +1898,55 @@ class AiBuilderTools(ToolBase):
                 },
             )
 
-        client_key_to_app_key: dict[str, str] = {}
-        created_app_keys: list[str] = []
-        results: list[JSONObject] = []
-        any_write_executed = False
+        started = time.perf_counter()
+        final_by_index: list[JSONObject | None] = [None for _ in apps]
+        valid_indices: list[int] = []
         client_keys: set[str] = set()
-
         for index, raw_item in enumerate(apps):
             if not isinstance(raw_item, dict):
-                results.append(_multi_app_item_failure(index, raw_item, "INVALID_APP_ITEM", "apps[] items must be objects"))
+                final_by_index[index] = _multi_app_item_failure(index, raw_item, "INVALID_APP_ITEM", "apps[] items must be objects")
                 continue
-            item = deepcopy(raw_item)
-            client_key = str(item.get("client_key") or item.get("clientKey") or "").strip()
-            app_name = str(item.get("app_name") or item.get("appTitle") or item.get("app_title") or item.get("title") or "").strip()
-            app_key = str(item.get("app_key") or item.get("appKey") or "").strip()
+            client_key = str(raw_item.get("client_key") or raw_item.get("clientKey") or "").strip()
+            app_name = str(raw_item.get("app_name") or raw_item.get("appTitle") or raw_item.get("app_title") or raw_item.get("title") or "").strip()
+            app_key = str(raw_item.get("app_key") or raw_item.get("appKey") or "").strip()
             if client_key:
                 if client_key in client_keys:
-                    results.append(_multi_app_item_failure(index, item, "DUPLICATE_CLIENT_KEY", f"duplicate client_key '{client_key}'"))
+                    final_by_index[index] = _multi_app_item_failure(index, raw_item, "DUPLICATE_CLIENT_KEY", f"duplicate client_key '{client_key}'")
                     continue
                 client_keys.add(client_key)
             if not app_key and not app_name:
-                results.append(_multi_app_item_failure(index, item, "APP_SELECTOR_REQUIRED", "apps[] requires app_key or app_name"))
+                final_by_index[index] = _multi_app_item_failure(index, raw_item, "APP_SELECTOR_REQUIRED", "apps[] requires app_key or app_name")
                 continue
+            valid_indices.append(index)
 
-            initial_add_fields, deferred_add_fields = _split_multi_app_initial_add_fields(item, is_new_app=not bool(app_key))
-            item["_deferred_add_fields"] = deferred_add_fields
-            shell = self._app_schema_apply_once(
-                profile=profile,
-                app_key=app_key,
-                package_id=package_id if not app_key else None,
-                app_name=app_name,
-                app_title="",
-                icon=str(item.get("icon") or ""),
-                color=str(item.get("color") or ""),
-                visibility=item.get("visibility", visibility),
-                create_if_missing=create_if_missing and not app_key,
-                publish=publish and not deferred_add_fields,
-                add_fields=initial_add_fields,
-                update_fields=[],
-                remove_fields=[],
-            )
-            public_shell = _publicize_package_fields(shell)
+        def run_shell(index: int) -> JSONObject:
+            raw_item = cast(JSONObject, apps[index])
+            app_name = str(raw_item.get("app_name") or raw_item.get("appTitle") or raw_item.get("app_title") or raw_item.get("title") or "").strip()
+            app_key = str(raw_item.get("app_key") or raw_item.get("appKey") or "").strip()
+            client_key = str(raw_item.get("client_key") or raw_item.get("clientKey") or "").strip()
+            try:
+                shell = self._app_schema_apply_once(
+                    profile=profile,
+                    app_key=app_key,
+                    package_id=package_id if not app_key else None,
+                    app_name=app_name,
+                    app_title="",
+                    icon=str(raw_item.get("icon") or ""),
+                    color=str(raw_item.get("color") or ""),
+                    visibility=raw_item.get("visibility", visibility),
+                    create_if_missing=create_if_missing and not app_key,
+                    publish=False,
+                    add_fields=[],
+                    update_fields=[],
+                    remove_fields=[],
+                    form=None,
+                )
+                public_shell = _publicize_package_fields(shell)
+            except Exception as error:
+                public_shell = {"status": "failed", "error_code": "APP_SHELL_APPLY_FAILED", "message": str(error)}
             resolved_key = str(public_shell.get("app_key") or "").strip()
             if public_shell.get("status") not in {"success", "partial_success"} or not resolved_key:
-                results.append({
+                return {
                     "index": index,
                     "row_number": index + 1,
                     "client_key": client_key or None,
@@ -1945,16 +1956,9 @@ class AiBuilderTools(ToolBase):
                     "stage": "resolve_or_create_shell",
                     "error_code": public_shell.get("error_code") or "APP_SHELL_APPLY_FAILED",
                     "message": public_shell.get("message") or "app shell resolve/create failed",
-                    "safe_to_retry": not any_write_executed,
-                })
-                continue
-            if bool(public_shell.get("created")):
-                created_app_keys.append(resolved_key)
-            if _schema_apply_result_has_write(public_shell):
-                any_write_executed = True
-            if client_key:
-                client_key_to_app_key[client_key] = resolved_key
-            results.append({
+                    "safe_to_retry": True,
+                }
+            return {
                 "index": index,
                 "row_number": index + 1,
                 "client_key": client_key or None,
@@ -1965,60 +1969,54 @@ class AiBuilderTools(ToolBase):
                 "shell_result": public_shell,
                 "shell_field_diff": public_shell.get("field_diff") or {},
                 "shell_field_diff_details": public_shell.get("field_diff_details") or {},
-                "deferred_add_fields": deferred_add_fields,
-            })
+            }
 
-        final_items: list[JSONObject] = []
-        for index, raw_item in enumerate(apps):
-            existing = next((item for item in results if item.get("index") == index), None)
-            if not existing or existing.get("status") != "shell_ready":
-                if existing:
-                    final_items.append(existing)
+        shell_started = time.perf_counter()
+        shell_workers = min(SCHEMA_MULTI_APP_MAX_WORKERS, len(valid_indices)) if valid_indices else 0
+        if shell_workers:
+            with ThreadPoolExecutor(max_workers=shell_workers) as executor:
+                future_map = {executor.submit(run_shell, index): index for index in valid_indices}
+                for future in as_completed(future_map):
+                    index = future_map[future]
+                    try:
+                        final_by_index[index] = future.result()
+                    except Exception as error:
+                        final_by_index[index] = _multi_app_item_failure(index, apps[index], "APP_SHELL_APPLY_FAILED", str(error))
+        shell_wall_ms = int((time.perf_counter() - shell_started) * 1000)
+
+        client_key_to_app_key: dict[str, str] = {}
+        created_app_keys: list[str] = []
+        for item in final_by_index:
+            if not isinstance(item, dict) or item.get("status") != "shell_ready":
                 continue
-            item = deepcopy(raw_item)
+            if bool(item.get("created")) and str(item.get("app_key") or "").strip():
+                created_app_keys.append(str(item.get("app_key")))
+            client_key = str(item.get("client_key") or "").strip()
+            app_key = str(item.get("app_key") or "").strip()
+            if client_key and app_key:
+                client_key_to_app_key[client_key] = app_key
+
+        ready_indices = [
+            index
+            for index, item in enumerate(final_by_index)
+            if isinstance(item, dict) and item.get("status") == "shell_ready"
+        ]
+
+        def run_schema(index: int) -> JSONObject:
+            existing = cast(JSONObject, final_by_index[index])
+            raw_item = cast(JSONObject, apps[index])
             app_key = str(existing.get("app_key") or "").strip()
             try:
-                compiled_item = _compile_multi_app_schema_item_refs(item, client_key_to_app_key)
+                compiled_item = _compile_multi_app_schema_item_refs(deepcopy(raw_item), client_key_to_app_key)
             except ValueError as error:
-                final_items.append({
+                return {
                     **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
                     "status": "failed",
                     "stage": "compile_relation_refs",
                     "error_code": "TARGET_APP_REF_NOT_FOUND",
                     "message": str(error),
                     "safe_to_retry": False,
-                })
-                any_write_executed = True
-                continue
-
-            deferred_add_fields = (
-                _compiled_multi_app_deferred_add_fields(compiled_item, existing)
-                if bool(existing.get("created"))
-                else list(compiled_item.get("add_fields") or [])
-            )
-            update_fields = list(compiled_item.get("update_fields") or [])
-            remove_fields = list(compiled_item.get("remove_fields") or [])
-            if bool(existing.get("created")) and not deferred_add_fields and not update_fields and not remove_fields:
-                shell_result = existing.get("shell_result") if isinstance(existing.get("shell_result"), dict) else {}
-                item_status = shell_result.get("status") if shell_result.get("status") in {"success", "partial_success"} else "failed"
-                shell_field_diff = existing.get("shell_field_diff") if isinstance(existing.get("shell_field_diff"), dict) else {}
-                shell_field_diff_details = existing.get("shell_field_diff_details") if isinstance(existing.get("shell_field_diff_details"), dict) else {}
-                final_items.append({
-                    **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
-                    "status": item_status,
-                    "stage": "schema_apply",
-                    "field_diff": shell_field_diff,
-                    "field_diff_details": shell_field_diff_details,
-                    "shell_field_diff": shell_field_diff,
-                    "shell_field_diff_details": shell_field_diff_details,
-                    "published": bool(shell_result.get("published")),
-                    "verified": bool(shell_result.get("verified")),
-                    "error_code": shell_result.get("error_code"),
-                    "message": shell_result.get("message"),
-                    "safe_to_retry": False,
-                })
-                continue
-
+                }
             field_result = self._app_schema_apply_once(
                 profile=profile,
                 app_key=app_key,
@@ -2030,19 +2028,19 @@ class AiBuilderTools(ToolBase):
                 visibility=compiled_item.get("visibility"),
                 create_if_missing=False,
                 publish=publish,
-                add_fields=deferred_add_fields,
-                update_fields=update_fields,
-                remove_fields=remove_fields,
+                add_fields=list(compiled_item.get("add_fields") or []),
+                update_fields=list(compiled_item.get("update_fields") or []),
+                remove_fields=list(compiled_item.get("remove_fields") or []),
+                form=_multi_app_schema_form(compiled_item),
             )
             public_result = _publicize_package_fields(field_result)
-            if _schema_apply_result_has_write(public_result):
-                any_write_executed = True
             item_status = public_result.get("status") if public_result.get("status") in {"success", "partial_success"} else "failed"
             shell_field_diff = existing.get("shell_field_diff") if isinstance(existing.get("shell_field_diff"), dict) else {}
             shell_field_diff_details = existing.get("shell_field_diff_details") if isinstance(existing.get("shell_field_diff_details"), dict) else {}
             field_diff = _merge_schema_field_diffs(shell_field_diff, public_result.get("field_diff") or {})
             field_diff_details = _merge_schema_field_diffs(shell_field_diff_details, public_result.get("field_diff_details") or {})
-            final_items.append({
+            verification = public_result.get("verification") if isinstance(public_result.get("verification"), dict) else {}
+            return {
                 **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
                 "status": item_status,
                 "stage": "schema_apply",
@@ -2052,44 +2050,48 @@ class AiBuilderTools(ToolBase):
                 "shell_field_diff_details": shell_field_diff_details,
                 "published": bool(public_result.get("published")),
                 "verified": bool(public_result.get("verified")),
+                "form_layout_verified": verification.get("form_layout_verified"),
                 "error_code": public_result.get("error_code"),
                 "message": public_result.get("message"),
                 "safe_to_retry": False,
-            })
+                "schema_result": public_result,
+            }
 
-        # Inline layout: apply layout for each successful app that included a layout field.
-        for index, raw_item in enumerate(apps):
-            if not isinstance(raw_item, dict):
-                continue
-            layout_spec = raw_item.get("layout")
-            if not isinstance(layout_spec, dict) or not layout_spec:
-                continue
-            final_item = next((it for it in final_items if it.get("index") == index), None)
-            if not final_item or final_item.get("status") not in {"success", "partial_success"}:
-                continue
-            resolved_app_key = str(final_item.get("app_key") or "").strip()
-            if not resolved_app_key:
-                continue
-            layout_mode = str(layout_spec.get("mode") or "merge").strip() or "merge"
-            layout_sections = layout_spec.get("sections") or []
-            try:
-                layout_result = self.app_layout_apply(
-                    profile=profile,
-                    app_key=resolved_app_key,
-                    mode=layout_mode,
-                    publish=publish,
-                    sections=list(layout_sections),
-                )
-                layout_ok = layout_result.get("status") in {"success", "partial_success"}
-            except Exception as layout_error:
-                layout_ok = False
-                layout_result = {"status": "failed", "message": str(layout_error)}
-            if layout_ok:
-                final_item["layout_applied"] = True
-                final_item["layout_status"] = layout_result.get("status")
-            else:
-                final_item["layout_warning"] = layout_result.get("error_code") or "LAYOUT_APPLY_FAILED"
-                final_item["layout_message"] = layout_result.get("message")
+        schema_started = time.perf_counter()
+        schema_workers = min(SCHEMA_MULTI_APP_MAX_WORKERS, len(ready_indices)) if ready_indices else 0
+        if schema_workers:
+            with ThreadPoolExecutor(max_workers=schema_workers) as executor:
+                future_map = {executor.submit(run_schema, index): index for index in ready_indices}
+                for future in as_completed(future_map):
+                    index = future_map[future]
+                    try:
+                        final_by_index[index] = future.result()
+                    except Exception as error:
+                        existing = final_by_index[index] if isinstance(final_by_index[index], dict) else {}
+                        final_by_index[index] = {
+                            **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
+                            "status": "failed",
+                            "stage": "schema_apply",
+                            "error_code": "SCHEMA_APPLY_FAILED",
+                            "message": str(error),
+                            "safe_to_retry": False,
+                        }
+        schema_wall_ms = int((time.perf_counter() - schema_started) * 1000)
+
+        final_items = [item for item in final_by_index if isinstance(item, dict)]
+        any_write_executed = any(
+            isinstance(item, dict)
+            and (
+                _schema_apply_result_has_write(cast(JSONObject, item.get("shell_result") or {}))
+                or _schema_apply_result_has_write(cast(JSONObject, item.get("schema_result") or {}))
+                or bool(item.get("created"))
+            )
+            for item in final_items
+        )
+        if any_write_executed:
+            for item in final_items:
+                if isinstance(item, dict) and item.get("status") == "failed":
+                    item["safe_to_retry"] = False
 
         succeeded = sum(1 for item in final_items if item.get("status") in {"success", "partial_success"})
         failed = len(final_items) - succeeded
@@ -2107,6 +2109,18 @@ class AiBuilderTools(ToolBase):
             "publish_requested": publish,
             "apps": final_items,
             "normalized_args": normalized_args,
+            "parallelism": {
+                "shell_workers": shell_workers,
+                "schema_workers": schema_workers,
+            },
+            "duration_ms": {
+                "app_shell_parallel_wall": shell_wall_ms,
+                "relation_compile": 0,
+                "app_schema_parallel_wall": schema_wall_ms,
+                "native_inline_layout": schema_wall_ms if any(bool(item.get("form_layout_verified")) for item in final_items if isinstance(item, dict)) else 0,
+                "inline_layout_fallback": 0,
+                "total": int((time.perf_counter() - started) * 1000),
+            },
             "verification": {
                 "all_apps_succeeded": failed == 0,
                 "created_app_count": len(created_app_keys),
@@ -2133,9 +2147,25 @@ class AiBuilderTools(ToolBase):
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
+        form: JSONObject | None = None,
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
         effective_app_name = app_name or app_title
+        try:
+            form_layout_mode, form_layout_sections, form_layout_requested = _extract_schema_form_layout(form)
+            parsed_form_layout_sections = (
+                [LayoutSectionPatch.model_validate(item) for item in form_layout_sections]
+                if form_layout_requested
+                else None
+            )
+        except (TypeError, ValueError, ValidationError) as exc:
+            return _config_failure(
+                tool_name="app_schema_apply",
+                message="invalid form layout payload",
+                fix_hint='Use "form": {"sections": [{"title": "基础信息", "rows": [["字段A", "字段B"]]}]}.',
+                error_code="FORM_LAYOUT_INVALID",
+                details={"validation_detail": str(exc)},
+            )
         icon_failure = _validate_workspace_icon_for_builder(
             tool_name="app_schema_apply",
             icon=icon,
@@ -2192,6 +2222,7 @@ class AiBuilderTools(ToolBase):
                         "add_fields": plan_args.get("add_fields") or [{"name": "字段名称", "type": "text", "required": False}],
                         "update_fields": plan_args.get("update_fields") or [],
                         "remove_fields": plan_args.get("remove_fields") or [],
+                        **({"form": {"mode": form_layout_mode.value, "sections": form_layout_sections}} if form_layout_requested else {}),
                     },
                 },
             )
@@ -2208,6 +2239,8 @@ class AiBuilderTools(ToolBase):
             "update_fields": [patch.model_dump(mode="json") for patch in parsed_update],
             "remove_fields": [patch.model_dump(mode="json") for patch in parsed_remove],
         }
+        if form_layout_requested:
+            normalized_args["form"] = {"mode": form_layout_mode.value, "sections": form_layout_sections}
         result = _safe_tool_call(
             lambda: self._facade.app_schema_apply(
                 profile=profile,
@@ -2222,6 +2255,8 @@ class AiBuilderTools(ToolBase):
                 add_fields=parsed_add,
                 update_fields=parsed_update,
                 remove_fields=parsed_remove,
+                layout_mode=form_layout_mode,
+                layout_sections=parsed_form_layout_sections,
             ),
             error_code="SCHEMA_APPLY_FAILED",
             normalized_args=normalized_args,
@@ -2626,7 +2661,7 @@ class AiBuilderTools(ToolBase):
             "verified": verified,
             "write_executed": write_executed,
             "safe_to_retry": not write_executed,
-            "parallelism": {"view_workers": VIEW_BATCH_MAX_WORKERS, "same_app_parallel": True},
+            "parallelism": {"view_workers": workers, "same_app_parallel": True},
             "duration_ms": {
                 "normalize": normalized_ms,
                 "view_write_parallel_wall": write_ms,
@@ -3561,54 +3596,34 @@ def _compile_multi_app_schema_item_refs(item: JSONObject, client_key_to_app_key:
     return visit(compiled)
 
 
-def _split_multi_app_initial_add_fields(item: JSONObject, *, is_new_app: bool) -> tuple[list[JSONObject], list[JSONObject]]:
-    add_fields = _multi_app_list_value(item, "add_fields", "addFields")
-    if not is_new_app:
-        return [], add_fields
-    initial: list[JSONObject] = []
-    deferred: list[JSONObject] = []
-    for field in add_fields:
-        if _contains_multi_app_target_ref(field):
-            deferred.append(field)
-        else:
-            initial.append(field)
-    return initial, deferred
-
-
-def _compiled_multi_app_deferred_add_fields(compiled_item: JSONObject, existing_result: JSONObject) -> list[JSONObject]:
-    deferred = existing_result.get("deferred_add_fields")
-    if not isinstance(deferred, list):
-        return list(compiled_item.get("add_fields") or [])
-    deferred_names = {str(item.get("name") or item.get("title") or item.get("label") or "").strip() for item in deferred if isinstance(item, dict)}
-    if not deferred_names:
-        return []
-    return [
-        deepcopy(field)
-        for field in list(compiled_item.get("add_fields") or [])
-        if isinstance(field, dict)
-        and str(field.get("name") or field.get("title") or field.get("label") or "").strip() in deferred_names
-    ]
-
-
-def _multi_app_list_value(item: JSONObject, *keys: str) -> list[JSONObject]:
-    for key in keys:
-        value = item.get(key)
-        if isinstance(value, list):
-            return [deepcopy(entry) for entry in value if isinstance(entry, dict)]
-    return []
-
-
-def _contains_multi_app_target_ref(value: object) -> bool:
-    if isinstance(value, list):
-        return any(_contains_multi_app_target_ref(item) for item in value)
-    if not isinstance(value, dict):
-        return False
-    for key, entry in value.items():
-        if key in {"target_app_ref", "targetAppRef", "target_app_client_key", "targetAppClientKey"}:
-            return True
-        if _contains_multi_app_target_ref(entry):
-            return True
-    return False
+def _extract_schema_form_layout(form: object) -> tuple[LayoutApplyMode, list[JSONObject], bool]:
+    if form is None:
+        return LayoutApplyMode.merge, [], False
+    if not isinstance(form, dict):
+        raise TypeError("form must be an object")
+    raw_mode = str(form.get("mode") or "merge").strip().lower() or "merge"
+    if raw_mode == "overwrite":
+        raw_mode = "replace"
+    try:
+        mode = LayoutApplyMode(raw_mode)
+    except ValueError as exc:
+        raise ValueError("form.mode must be merge or replace") from exc
+    sections = form.get("sections")
+    if sections is None:
+        return mode, [], False
+    if not isinstance(sections, list):
+        raise TypeError("form.sections must be a JSON array")
+    return mode, [deepcopy(item) for item in sections if isinstance(item, dict)], True
+
+
+def _multi_app_schema_form(item: JSONObject) -> JSONObject | None:
+    form = item.get("form")
+    if isinstance(form, dict):
+        return deepcopy(form)
+    legacy_layout = item.get("layout")
+    if isinstance(legacy_layout, dict):
+        return deepcopy(legacy_layout)
+    return None
 
 
 def _merge_schema_field_diffs(*diffs: object) -> JSONObject:
@@ -3632,6 +3647,11 @@ def _schema_apply_result_has_write(result: JSONObject) -> bool:
     field_diff = result.get("field_diff")
     if isinstance(field_diff, dict):
         return any(bool(field_diff.get(key)) for key in ("added", "updated", "removed"))
+    details = result.get("details")
+    if isinstance(details, dict):
+        form_layout_diff = details.get("form_layout_diff")
+        if isinstance(form_layout_diff, dict) and bool(form_layout_diff.get("changed")):
+            return True
     return False
 
 
@@ -5340,6 +5360,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "add_fields",
             "update_fields",
             "remove_fields",
+            "form",
+            "form.mode",
+            "form.sections",
             "apps",
             "apps[].client_key",
             "apps[].app_key",
@@ -5350,6 +5373,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "apps[].add_fields",
             "apps[].update_fields",
             "apps[].remove_fields",
+            "apps[].form",
+            "apps[].form.mode",
+            "apps[].form.sections",
             "apps[].add_fields[].target_app_ref",
         ],
         "aliases": {
@@ -5360,6 +5386,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "apps[].appKey": "apps[].app_key",
             "apps[].appName": "apps[].app_name",
             "apps[].appTitle": "apps[].app_name",
+            "apps[].layout": "apps[].form",
             "field.targetAppRef": "field.target_app_ref",
             "field.targetAppClientKey": "field.target_app_ref",
             "field.title": "field.name",
@@ -5400,6 +5427,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "create mode: package_id + app_name + create_if_missing=true",
             "multi-app mode: pass package_id + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
             "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
+            "multi-app form layout belongs in apps[].form.sections and is written in the same schema save as fields and relation fields",
+            "multi-app shell and schema stages run in parallel with an internal max worker count of 10; response order still follows apps[] order",
             "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
             "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
             "create mode requires explicit icon + color; icon=template is blocked because it is too generic",
@@ -5408,8 +5437,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             *_VISIBILITY_EXECUTION_NOTES,
             "update_fields is the field-level partial update path; it reads current form schema and preserves untouched field config",
-            "multiple relation fields are backend-risky; read verification.relation_field_limit_verified and warnings before declaring the schema stable",
-            "backend 49614 is normalized to MULTIPLE_RELATION_FIELDS_UNSUPPORTED with a workaround message",
             "relation_mode=multiple maps to referenceConfig.optionalDataNum=0",
             "relation fields now require both display_field and visible_fields in MCP/CLI payloads",
             "if relation target metadata lookup is blocked by 40161/40002/40027, explicit display_field.name and visible_fields[].name let builder degrade verification and still continue schema write",
@@ -6204,7 +6231,23 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_charts_apply": {
-        "allowed_keys": ["app_key", "apps", "upsert_charts", "patch_charts", "remove_chart_ids", "reorder_chart_ids", "upsert_charts[].visibility", "patch_charts[].chart_id", "patch_charts[].name", "patch_charts[].set", "patch_charts[].unset"],
+        "allowed_keys": [
+            "app_key",
+            "apps",
+            "upsert_charts",
+            "patch_charts",
+            "remove_chart_ids",
+            "reorder_chart_ids",
+            "upsert_charts[].metric",
+            "upsert_charts[].metrics",
+            "upsert_charts[].group_by",
+            "upsert_charts[].where",
+            "upsert_charts[].visibility",
+            "patch_charts[].chart_id",
+            "patch_charts[].name",
+            "patch_charts[].set",
+            "patch_charts[].unset",
+        ],
         "aliases": {
             "patchCharts": "patch_charts",
             "chart.id": "chart.chart_id",
@@ -6212,6 +6255,11 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "chart.dimension_fields": "chart.dimension_field_ids",
             "chart.indicator_fields": "chart.indicator_field_ids",
             "chart.metric_field_ids": "chart.indicator_field_ids",
+            "chart.dimensions": "chart.group_by",
+            "chart.groupBy": "chart.group_by",
+            "chart.where": "chart.filters",
+            "chart.metric.operation": "chart.metric.op",
+            "chart.metric.aggregation": "chart.metric.op",
             "chart.filter.op": "chart.filter.operator",
         },
         "allowed_values": {
@@ -6232,6 +6280,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 "upsert_charts[].visibility compiles to QingBI base visibleAuth only",
                 "visibility-only updates keep the existing chart config and do not rewrite rawDataConfigDTO.authInfo",
                 "chart dimension/metric/filter/query fields are resolved from app_get_fields.chart_fields (QingBI datasource fields), not record schema or form-only fields",
+                "preferred chart metric DSL is SQL-like: metric='count(*)', metric='sum(金额)', metrics=['sum(金额)'], group_by=['状态'], where=[{field, op, value}]",
+                "legacy dimension_field_ids/indicator_field_ids/config.aggregate remain supported as advanced compatibility input, but should not be the first choice for agents",
+                "chart_get returns semantic group_by and metrics; raw QingBI config is diagnostic detail",
                 "system fields such as 申请人/申请时间/编号 are usable only when they appear in chart_fields; otherwise app_charts_apply returns CHART_FIELD_NOT_IN_QINGBI_SCHEMA",
                 "low-frequency chart types have local prevalidation: gauge requires 0 dimensions and 2 non-duplicated metrics; histogram requires at most 1 dimension and exactly 1 plain numeric metric",
                 "chart rule failures return chart_results[].diagnostics with rule_code, expected, actual, offending_fields, and next_action; backend 81002/81005 are translated when possible",
@@ -6243,7 +6294,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "upsert_charts": [{"name": "数据总量", "chart_type": "target", "indicator_field_ids": [], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "upsert_charts": [{"name": "数据总量", "chart_type": "target", "metric": "count(*)", "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "patch_charts": [{"chart_id": "CHART_ID", "set": {"name": "数据总量-新版"}}],
             "remove_chart_ids": [],
             "reorder_chart_ids": [],