@josephyan/qingflow-app-builder-mcp 1.1.21 → 1.1.22

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from copy import deepcopy
 import json
 import time
@@ -15,7 +16,7 @@ from ..builder_facade.button_style_catalog import (
 )
 from ..public_surface import public_builder_contract_tool_names
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, backend_code_int
+from ..errors import QingflowApiError, backend_code_int, backend_code_value_int
 from ..json_types import JSONObject
 from ..builder_facade.models import (
     AssociatedResourcesApplyRequest,
@@ -142,6 +143,7 @@ BUILDER_APPLY_TOOL_NAMES = {
     "portal_delete",
     "app_publish_verify",
 }
+MULTI_APP_SCHEMA_APPLY_PARALLEL_LIMIT = 10
 
 
 class AiBuilderTools(ToolBase):
@@ -171,13 +173,28 @@ class AiBuilderTools(ToolBase):
         )
 
     def _apply_app_batch(self, *, tool_name: str, profile: str, apps: list[JSONObject], apply_one) -> JSONObject:
+        started_at = time.perf_counter()
+        batch_item_apply_ms = 0
+        child_total_ms = 0
+
+        def finish(payload: JSONObject) -> JSONObject:
+            _merge_duration_breakdown(
+                payload,
+                batch_item_apply_ms=batch_item_apply_ms,
+                child_total_ms=child_total_ms,
+                total_ms=_elapsed_ms(started_at),
+            )
+            return _attach_builder_apply_envelope(tool_name, payload)
+
         if not isinstance(apps, list) or not apps:
-            return _attach_builder_apply_envelope(tool_name, _config_failure(
-                tool_name=tool_name,
-                message=f"{tool_name} batch mode requires non-empty apps[].",
-                fix_hint="Pass apps as a JSON array; each item must include app_key plus that resource's normal payload.",
-                details={"expected_shape": {"apps": [{"app_key": "APP_KEY"}]}},
-            ))
+            return finish(
+                _config_failure(
+                    tool_name=tool_name,
+                    message=f"{tool_name} batch mode requires non-empty apps[].",
+                    fix_hint="Pass apps as a JSON array; each item must include app_key plus that resource's normal payload.",
+                    details={"expected_shape": {"apps": [{"app_key": "APP_KEY"}]}},
+                )
+            )
 
         app_results: list[JSONObject] = []
         errors: list[JSONObject] = []
@@ -206,8 +223,10 @@ class AiBuilderTools(ToolBase):
                 app_results.append(error)
                 continue
             try:
+                item_started_at = time.perf_counter()
                 result = apply_one(index, item, app_key)
             except (QingflowApiError, RuntimeError) as error:
+                batch_item_apply_ms += _elapsed_ms(item_started_at)
                 api_error = _coerce_api_error(error)
                 result = {
                     "status": "failed",
@@ -221,6 +240,13 @@ class AiBuilderTools(ToolBase):
                     "backend_code": api_error.backend_code,
                     "http_status": None if api_error.http_status == 404 else api_error.http_status,
                 }
+            else:
+                batch_item_apply_ms += _elapsed_ms(item_started_at)
+            if isinstance(result, dict):
+                child_breakdown = result.get("duration_breakdown_ms")
+                child_total = child_breakdown.get("total_ms") if isinstance(child_breakdown, dict) else None
+                if isinstance(child_total, (int, float)) and child_total >= 0:
+                    child_total_ms += int(child_total)
             status = str(result.get("status") or "success") if isinstance(result, dict) else "failed"
             wrapped: JSONObject = {
                 "index": index,
@@ -270,7 +296,7 @@ class AiBuilderTools(ToolBase):
             "write_succeeded": write_executed and failed == 0 and partial == 0,
             "safe_to_retry": not write_executed,
         }
-        return _attach_builder_apply_envelope(tool_name, payload)
+        return finish(payload)
 
     def _read_app_batch(self, *, tool_name: str, profile: str, app_keys: list[str], read_one) -> JSONObject:
         normalized_keys = [str(item).strip() for item in app_keys if str(item).strip()]
@@ -356,7 +382,6 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             package_id: int | None = None,
             package_name: str | None = None,
-            create_if_missing: bool | None = None,
             icon: str | JSONObject | None = None,
             color: str | None = None,
             icon_name: str | None = None,
@@ -370,7 +395,6 @@ class AiBuilderTools(ToolBase):
                 profile=profile,
                 package_id=package_id,
                 package_name=package_name,
-                create_if_missing=create_if_missing,
                 icon=icon,
                 color=color,
                 icon_name=icon_name,
@@ -599,7 +623,6 @@ class AiBuilderTools(ToolBase):
             icon_color: str | None = None,
             icon_config: JSONObject | None = None,
             visibility: JSONObject | None = None,
-            create_if_missing: bool | None = None,
             publish: bool = True,
             form: list[JSONObject] | None = None,
             add_fields: list[JSONObject] | None = None,
@@ -611,7 +634,7 @@ class AiBuilderTools(ToolBase):
                 if app_key or app_name or app_title or form or add_fields or update_fields or remove_fields:
                     return _config_failure(
                         tool_name="app_schema_apply",
-                        message="app_schema_apply multi-app mode accepts package_id plus apps only; create_if_missing is optional.",
+                        message="app_schema_apply multi-app mode accepts package_id plus apps only.",
                         fix_hint="Put per-app form in apps[].form when using batch mode.",
                     )
                 if package_id is None:
@@ -624,7 +647,6 @@ class AiBuilderTools(ToolBase):
                     profile=profile,
                     package_id=package_id,
                     visibility=visibility,
-                    create_if_missing=True if create_if_missing is None else bool(create_if_missing),
                     publish=publish,
                     apps=apps,
                     form=None,
@@ -636,20 +658,19 @@ class AiBuilderTools(ToolBase):
             has_app_name = bool((app_name or "").strip())
             has_app_title = bool((app_title or "").strip())
             has_package_id = package_id is not None
-            effective_create_if_missing = bool(create_if_missing)
             if has_app_key:
-                if effective_create_if_missing or has_package_id:
+                if has_package_id:
                     return _config_failure(
                         tool_name="app_schema_apply",
                         message="app_schema_apply edit mode accepts app_key and optional app_name rename only.",
-                        fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_id + app_name + create_if_missing=true`.",
+                        fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_id + app_name`.",
                     )
-            elif not (effective_create_if_missing and has_package_id and (has_app_name or has_app_title)):
+            elif not (has_package_id and (has_app_name or has_app_title)):
                 return _config_failure(
                     tool_name="app_schema_apply",
-                    message="app_schema_apply create mode requires package_id, app_name, and create_if_missing=true.",
-                    fix_hint="Use `app_key` for existing apps, or pass `package_id + app_name + create_if_missing=true` to create a new app.",
-                )
+                    message="app_schema_apply create mode requires package_id and app_name.",
+                        fix_hint="Use `app_key` for existing apps, or pass `package_id + app_name` to create a new app.",
+                    )
             return self.app_schema_apply(
                 profile=profile,
                 app_key=app_key,
@@ -662,7 +683,6 @@ class AiBuilderTools(ToolBase):
                 icon_color=icon_color,
                 icon_config=icon_config,
                 visibility=visibility,
-                create_if_missing=effective_create_if_missing,
                 publish=publish,
                 form=form or [],
                 add_fields=add_fields or [],
@@ -1009,7 +1029,6 @@ class AiBuilderTools(ToolBase):
         profile: str,
         package_id: int | None = None,
         package_name: str | None = None,
-        create_if_missing: bool | None = None,
         icon: str | JSONObject | None = None,
         color: str | None = None,
         icon_name: str | None = None,
@@ -1040,14 +1059,13 @@ class AiBuilderTools(ToolBase):
             tool_name="package_apply",
             icon=icon,
             color=color,
-            creating=package_id is None and bool(create_if_missing),
+            creating=package_id is None and bool(str(package_name or "").strip()),
         )
         if icon_failure is not None:
             return _attach_builder_apply_envelope("package_apply", icon_failure)
         normalized_args = {
             "package_id": package_id,
             **({"package_name": package_name} if str(package_name or "").strip() else {}),
-            "create_if_missing": bool(create_if_missing),
             **({"icon": icon} if icon else {}),
             **({"color": color} if color else {}),
             **({"visibility": visibility_patch.model_dump(mode="json")} if visibility_patch is not None else {}),
@@ -1059,7 +1077,6 @@ class AiBuilderTools(ToolBase):
                 profile=profile,
                 package_id=package_id,
                 package_name=package_name,
-                create_if_missing=create_if_missing,
                 icon=icon,
                 color=color,
                 visibility=visibility_patch,
@@ -1879,7 +1896,6 @@ class AiBuilderTools(ToolBase):
         icon: str = "",
         color: str = "",
         visibility: JSONObject | None = None,
-        create_if_missing: bool | None = None,
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
@@ -1894,7 +1910,6 @@ class AiBuilderTools(ToolBase):
             icon=icon,
             color=color,
             visibility=visibility,
-            create_if_missing=create_if_missing,
             add_fields=add_fields,
             update_fields=update_fields,
             remove_fields=remove_fields,
@@ -1910,7 +1925,6 @@ class AiBuilderTools(ToolBase):
                     "icon": icon,
                     "color": color,
                     "visibility": visibility,
-                    "create_if_missing": create_if_missing,
                     "add_fields": add_fields,
                     "update_fields": update_fields,
                     "remove_fields": remove_fields,
@@ -1931,7 +1945,6 @@ class AiBuilderTools(ToolBase):
                         "icon": icon,
                         "color": color,
                         "visibility": visibility,
-                        "create_if_missing": create_if_missing,
                         "add_fields": [{"name": "字段名称", "type": "text"}],
                         "update_fields": [],
                         "remove_fields": [],
@@ -2126,7 +2139,6 @@ class AiBuilderTools(ToolBase):
         icon_color: str | None = None,
         icon_config: JSONObject | None = None,
         visibility: JSONObject | None = None,
-        create_if_missing: bool | None = None,
         publish: bool = True,
         form: list[JSONObject] | None = None,
         add_fields: list[JSONObject],
@@ -2173,7 +2185,6 @@ class AiBuilderTools(ToolBase):
                 profile=profile,
                 package_id=package_id,
                 visibility=visibility,
-                create_if_missing=True if create_if_missing is None else bool(create_if_missing),
                 publish=publish,
                 apps=apps,
             )
@@ -2207,7 +2218,6 @@ class AiBuilderTools(ToolBase):
             icon=icon,
             color=color,
             visibility=visibility,
-            create_if_missing=bool(create_if_missing),
             publish=publish,
             add_fields=add_fields,
             update_fields=update_fields,
@@ -2226,7 +2236,6 @@ class AiBuilderTools(ToolBase):
                 icon=icon,
                 color=color,
                 visibility=visibility,
-                create_if_missing=create_if_missing,
                 publish=publish,
                 add_fields=add_fields,
                 update_fields=update_fields,
@@ -2242,52 +2251,114 @@ class AiBuilderTools(ToolBase):
         profile: str,
         package_id: int | None,
         visibility: JSONObject | None,
-        create_if_missing: bool,
         publish: bool,
         apps: list[JSONObject],
     ) -> JSONObject:
+        started_at = time.perf_counter()
+        validation_ms = 0
+        app_shell_apply_ms = 0
+        relation_compile_ms = 0
+        app_field_apply_ms = 0
+        inline_layout_fallback_ms = 0
+        child_schema_write_ms = 0
+        child_inline_layout_ms = 0
+        child_publish_ms = 0
+        child_readback_ms = 0
         normalized_args: JSONObject = {
             "package_id": package_id,
-            "create_if_missing": create_if_missing,
             "publish": publish,
             "apps": deepcopy(apps),
         }
         if visibility is not None:
             normalized_args["visibility"] = deepcopy(visibility)
+        parallelism: JSONObject = {"shell_workers": 0, "schema_workers": 0}
+
+        def merge_child_duration(child: JSONObject) -> None:
+            nonlocal child_schema_write_ms
+            nonlocal child_inline_layout_ms
+            nonlocal child_publish_ms
+            nonlocal child_readback_ms
+            breakdown = child.get("duration_breakdown_ms") if isinstance(child, dict) else None
+            if not isinstance(breakdown, dict):
+                return
+            for key, target in (
+                ("schema_write_ms", "child_schema_write_ms"),
+                ("inline_layout_ms", "child_inline_layout_ms"),
+                ("publish_ms", "child_publish_ms"),
+                ("readback_ms", "child_readback_ms"),
+            ):
+                value = breakdown.get(key)
+                if isinstance(value, (int, float)) and value >= 0:
+                    if target == "child_schema_write_ms":
+                        child_schema_write_ms += int(value)
+                    elif target == "child_inline_layout_ms":
+                        child_inline_layout_ms += int(value)
+                    elif target == "child_publish_ms":
+                        child_publish_ms += int(value)
+                    elif target == "child_readback_ms":
+                        child_readback_ms += int(value)
+
+        def finish(response: JSONObject) -> JSONObject:
+            _merge_duration_breakdown(
+                response,
+                multi_app_validation_ms=validation_ms,
+                app_shell_apply_ms=app_shell_apply_ms,
+                app_shell_parallel_wall_ms=app_shell_apply_ms,
+                relation_compile_ms=relation_compile_ms,
+                app_field_apply_ms=app_field_apply_ms,
+                app_schema_parallel_wall_ms=app_field_apply_ms,
+                native_inline_layout_ms=child_inline_layout_ms,
+                inline_layout_fallback_ms=inline_layout_fallback_ms,
+                child_schema_write_ms=child_schema_write_ms,
+                child_inline_layout_ms=child_inline_layout_ms,
+                child_publish_ms=child_publish_ms,
+                child_readback_ms=child_readback_ms,
+                total_ms=_elapsed_ms(started_at),
+            )
+            return response
+
+        validation_started_at = time.perf_counter()
         system_field_failure = _reserved_system_field_name_failure_for_apps(
             tool_name="app_schema_apply",
             profile=profile,
             package_id=package_id,
             visibility=visibility,
-            create_if_missing=create_if_missing,
             publish=publish,
             apps=apps,
         )
         if system_field_failure is not None:
-            return system_field_failure
+            validation_ms += _elapsed_ms(validation_started_at)
+            return finish(system_field_failure)
         if package_id is None:
-            return _config_failure(
-                tool_name="app_schema_apply",
-                message="app_schema_apply multi-app mode requires package_id.",
-                fix_hint="Pass package_id and apps[].app_name for new apps, or apps[].app_key for existing apps.",
+            validation_ms += _elapsed_ms(validation_started_at)
+            return finish(
+                _config_failure(
+                    tool_name="app_schema_apply",
+                    message="app_schema_apply multi-app mode requires package_id.",
+                    fix_hint="Pass package_id and apps[].app_name for new apps, or apps[].app_key for existing apps.",
+                )
             )
         if not apps:
-            return _config_failure(
-                tool_name="app_schema_apply",
-                error_code="APPS_FILE_EMPTY",
-                message="app_schema_apply multi-app mode requires non-empty apps.",
-                fix_hint="Pass apps as a non-empty list of app schema items.",
+            validation_ms += _elapsed_ms(validation_started_at)
+            return finish(
+                _config_failure(
+                    tool_name="app_schema_apply",
+                    error_code="APPS_FILE_EMPTY",
+                    message="app_schema_apply multi-app mode requires non-empty apps.",
+                    fix_hint="Pass apps as a non-empty list of app schema items.",
+                )
             )
         shape_failure = _schema_apps_shape_failure(tool_name="app_schema_apply", apps=apps)
         if shape_failure is not None:
-            return shape_failure
+            validation_ms += _elapsed_ms(validation_started_at)
+            return finish(shape_failure)
         static_validation_failure = _multi_app_static_validation_failure(
             tool_name="app_schema_apply",
             apps=apps,
-            create_if_missing=create_if_missing,
         )
         if static_validation_failure is not None:
-            return static_validation_failure
+            validation_ms += _elapsed_ms(validation_started_at)
+            return finish(static_validation_failure)
         icon_errors: list[JSONObject] = []
         seen_new_app_icons: dict[str, int] = {}
         for index, raw_item in enumerate(apps):
@@ -2338,32 +2409,111 @@ class AiBuilderTools(ToolBase):
                 else:
                     seen_new_app_icons[normalized_icon] = index
         if icon_errors:
-            return _config_failure(
-                tool_name="app_schema_apply",
-                error_code="WORKSPACE_ICON_BATCH_INVALID",
-                message="one or more apps have invalid workspace icon configuration",
-                fix_hint="Call `qingflow --json builder icon catalog`, choose a distinct non-template icon and color for each new app, then retry.",
-                details={"icon_errors": icon_errors},
-                allowed_values={
-                    "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
-                    "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
-                    "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
-                },
+            validation_ms += _elapsed_ms(validation_started_at)
+            return finish(
+                _config_failure(
+                    tool_name="app_schema_apply",
+                    error_code="WORKSPACE_ICON_BATCH_INVALID",
+                    message="one or more apps have invalid workspace icon configuration",
+                    fix_hint="Call `qingflow --json builder icon catalog`, choose a distinct non-template icon and color for each new app, then retry.",
+                    details={"icon_errors": icon_errors},
+                    allowed_values={
+                        "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
+                        "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
+                        "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
+                    },
+                )
             )
+        validation_ms += _elapsed_ms(validation_started_at)
 
         client_key_to_app_key: dict[str, str] = {}
         app_name_to_app_key: dict[str, str] = {}
         created_app_keys: list[str] = []
-        results: list[JSONObject] = []
+        results_by_index: list[JSONObject | None] = [None] * len(apps)
+        shell_jobs: list[JSONObject] = []
         any_write_executed = False
         any_write_may_have_succeeded = False
         pending_readback_app_keys: list[str] = []
         pending_readback_app_names: list[str] = []
         client_keys: set[str] = set()
+        client_key_indexes: dict[str, int] = {}
+        app_name_indexes: dict[str, int] = {}
+
+        def worker_count(count: int) -> int:
+            return min(MULTI_APP_SCHEMA_APPLY_PARALLEL_LIMIT, count) if count > 0 else 0
+
+        def mark_inline_layout_not_applied_in_schema(
+            result: JSONObject,
+            *,
+            app_key: str,
+            sections: list[JSONObject],
+        ) -> JSONObject:
+            marked = deepcopy(result)
+            inline_payload: JSONObject = {
+                "requested": True,
+                "section_count": len(sections),
+                "app_key": app_key or None,
+                "applied": False,
+                "applied_in_schema": False,
+                "error_code": "INLINE_FORM_LAYOUT_NOT_APPLIED_IN_SCHEMA",
+                "message": "schema save did not apply inline form layout; multi-app mode does not run app_layout_apply fallback",
+            }
+            marked["inline_form_layout"] = inline_payload
+            verification = marked.get("verification") if isinstance(marked.get("verification"), dict) else {}
+            verification = deepcopy(verification)
+            verification["inline_form_layout_verified"] = False
+            marked["verification"] = verification
+            if marked.get("status") in {"success", "partial_success"}:
+                marked["status"] = "partial_success"
+                marked["error_code"] = marked.get("error_code") or "INLINE_FORM_LAYOUT_NOT_APPLIED_IN_SCHEMA"
+                marked["message"] = "schema applied but inline form layout was not applied in schema save"
+            marked["safe_to_retry"] = False
+            return marked
+
+        def dependency_failure_for_item(index: int, item: JSONObject) -> JSONObject | None:
+            blocked: list[JSONObject] = []
+            for ref in _collect_multi_app_target_refs(item, path=f"apps[{index}]"):
+                ref_value = str(ref.get("value") or "").strip()
+                if not ref_value:
+                    continue
+                target_index: int | None = None
+                resolved = False
+                if ref.get("kind") == "target_app_ref":
+                    target_index = client_key_indexes.get(ref_value)
+                    resolved = ref_value in client_key_to_app_key
+                elif ref.get("kind") == "target_app":
+                    target_index = app_name_indexes.get(ref_value)
+                    resolved = ref_value in app_name_to_app_key
+                if target_index is None or resolved:
+                    continue
+                target_result = results_by_index[target_index] if 0 <= target_index < len(results_by_index) else None
+                blocked.append(
+                    {
+                        "kind": ref.get("kind"),
+                        "value": ref_value,
+                        "path": ref.get("path"),
+                        "target_index": target_index,
+                        "target_status": target_result.get("status") if isinstance(target_result, dict) else None,
+                        "target_error_code": target_result.get("error_code") if isinstance(target_result, dict) else None,
+                    }
+                )
+            if not blocked:
+                return None
+            raw_item = apps[index] if 0 <= index < len(apps) else item
+            failure = _multi_app_item_failure(
+                index,
+                raw_item,
+                "DEPENDENCY_APP_NOT_READY",
+                "one or more target apps failed or require readback, so this app schema was not written",
+            )
+            failure["stage"] = "dependency_check"
+            failure["safe_to_retry"] = False
+            failure["details"] = {"blocked_dependencies": blocked}
+            return failure
 
         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"))
+                results_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()
@@ -2371,33 +2521,104 @@ class AiBuilderTools(ToolBase):
             app_key = str(item.get("app_key") or 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}'"))
+                    results_by_index[index] = _multi_app_item_failure(index, item, "DUPLICATE_CLIENT_KEY", f"duplicate client_key '{client_key}'")
                     continue
                 client_keys.add(client_key)
+                client_key_indexes[client_key] = index
+            if app_name:
+                app_name_indexes[app_name] = index
             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"))
+                results_by_index[index] = _multi_app_item_failure(index, item, "APP_SELECTOR_REQUIRED", "apps[] requires app_key or app_name")
                 continue
-
-            initial_add_fields, deferred_add_fields = _split_multi_app_initial_add_fields(item, is_new_app=not bool(app_key))
-            inline_layout_sections = list(item.get("_inline_form_layout_sections") or [])
-            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=[],
-                inline_form_layout_sections=inline_layout_sections if not deferred_add_fields else None,
+            shell_jobs.append(
+                {
+                    "index": index,
+                    "item": item,
+                    "client_key": client_key,
+                    "app_name": app_name,
+                    "app_key": app_key,
+                }
             )
-            public_shell = _publicize_package_fields(shell)
+
+        shell_workers = worker_count(len(shell_jobs))
+        parallelism["shell_workers"] = shell_workers
+
+        def run_shell_job(job: JSONObject) -> JSONObject:
+            index = int(job["index"])
+            item = deepcopy(job["item"])
+            app_key = str(job.get("app_key") or "")
+            app_name = str(job.get("app_name") or "")
+            shell_started_at = time.perf_counter()
+            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(item.get("icon") or ""),
+                    color=str(item.get("color") or ""),
+                    visibility=item.get("visibility", visibility),
+                    publish=False,
+                    add_fields=[],
+                    update_fields=[],
+                    remove_fields=[],
+                    inline_form_layout_sections=None,
+                    allow_inline_layout_fallback=False,
+                )
+                return {
+                    "index": index,
+                    "job": job,
+                    "elapsed_ms": _elapsed_ms(shell_started_at),
+                    "public_shell": _publicize_package_fields(shell),
+                }
+            except Exception as error:  # pragma: no cover - defensive guard for unexpected worker failures
+                return {
+                    "index": index,
+                    "job": job,
+                    "elapsed_ms": _elapsed_ms(shell_started_at),
+                    "exception": repr(error),
+                }
+
+        shell_outputs: list[JSONObject] = []
+        shell_phase_started_at = time.perf_counter()
+        if shell_jobs:
+            with ThreadPoolExecutor(max_workers=shell_workers) as executor:
+                futures = [executor.submit(run_shell_job, job) for job in shell_jobs]
+                for future in as_completed(futures):
+                    shell_outputs.append(future.result())
+        app_shell_apply_ms += _elapsed_ms(shell_phase_started_at)
+
+        for output in sorted(shell_outputs, key=lambda item: int(item.get("index", 0))):
+            index = int(output["index"])
+            job = output.get("job") if isinstance(output.get("job"), dict) else {}
+            client_key = str(job.get("client_key") or "").strip()
+            app_name = str(job.get("app_name") or "").strip()
+            app_key = str(job.get("app_key") or "").strip()
+            item = deepcopy(job.get("item") if isinstance(job.get("item"), dict) else {})
+            exception = output.get("exception")
+            if exception:
+                results_by_index[index] = {
+                    "index": index,
+                    "row_number": index + 1,
+                    "client_key": client_key or None,
+                    "app_name": app_name or None,
+                    "app_key": app_key or None,
+                    "status": "pending_readback",
+                    "stage": "resolve_or_create_shell",
+                    "error_code": "APP_SHELL_APPLY_EXCEPTION",
+                    "message": str(exception),
+                    "write_executed": False,
+                    "write_may_have_succeeded": True,
+                    "safe_to_retry": False,
+                    "next_action": "readback_before_retry",
+                }
+                if app_name:
+                    pending_readback_app_names.append(app_name)
+                any_write_may_have_succeeded = True
+                continue
+            public_shell = output.get("public_shell") if isinstance(output.get("public_shell"), dict) else {}
+            merge_child_duration(public_shell)
             resolved_key = str(public_shell.get("app_key") or "").strip()
             shell_write_executed = _schema_apply_result_has_write(public_shell)
             shell_write_may_have_succeeded = _schema_apply_result_may_have_write(public_shell)
@@ -2417,7 +2638,7 @@ class AiBuilderTools(ToolBase):
                         pending_readback_app_keys.append(resolved_key)
                     if app_name:
                         pending_readback_app_names.append(app_name)
-                results.append({
+                results_by_index[index] = {
                     "index": index,
                     "row_number": index + 1,
                     "client_key": client_key or None,
@@ -2432,8 +2653,8 @@ class AiBuilderTools(ToolBase):
                     "safe_to_retry": False if pending_readback else (not shell_write_executed and not any_write_executed),
                     **({"next_action": "readback_before_retry"} if pending_readback else {}),
                     **({"verification": public_shell.get("verification")} if isinstance(public_shell.get("verification"), dict) else {}),
-                    **({"created": True} if pending_readback and create_if_missing and not app_key else {}),
-                })
+                    **({"created": True} if pending_readback and not app_key else {}),
+                }
                 continue
             if bool(public_shell.get("created")):
                 created_app_keys.append(resolved_key)
@@ -2446,7 +2667,7 @@ class AiBuilderTools(ToolBase):
             resolved_name = str(public_shell.get("app_name_after") or public_shell.get("app_name") or app_name or "").strip()
             if resolved_name:
                 app_name_to_app_key[resolved_name] = resolved_key
-            results.append({
+            results_by_index[index] = {
                 "index": index,
                 "row_number": index + 1,
                 "client_key": client_key or None,
@@ -2457,105 +2678,218 @@ 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] = []
+        final_items_by_index: list[JSONObject | None] = [None] * len(apps)
+        schema_jobs: list[JSONObject] = []
         for index, raw_item in enumerate(apps):
-            existing = next((item for item in results if item.get("index") == index), None)
+            existing = results_by_index[index] if 0 <= index < len(results_by_index) else None
             if not existing or existing.get("status") != "shell_ready":
                 if existing:
-                    final_items.append(existing)
+                    final_items_by_index[index] = existing
                 continue
             item = deepcopy(raw_item)
             app_key = str(existing.get("app_key") or "").strip()
+            dependency_failure = dependency_failure_for_item(index, item)
+            if dependency_failure is not None:
+                final_items_by_index[index] = dependency_failure
+                any_write_executed = True
+                continue
+            compile_started_at = time.perf_counter()
             try:
                 compiled_item = _compile_multi_app_schema_item_refs(item, client_key_to_app_key, app_name_to_app_key)
             except ValueError as error:
-                final_items.append({
+                relation_compile_ms += _elapsed_ms(compile_started_at)
+                final_items_by_index[index] = {
                     **{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 [])
-            )
+            relation_compile_ms += _elapsed_ms(compile_started_at)
+            schema_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 [])
-            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 {}
-                layout_sections = list(compiled_item.get("_inline_form_layout_sections") or [])
-                if layout_sections and not _inline_form_layout_was_handled(shell_result):
-                    shell_result = self._apply_inline_form_layout_after_schema(
+            layout_sections = list(compiled_item.get("_inline_form_layout_sections") or [])
+            field_phase_app_name = ""
+            field_phase_icon = ""
+            field_phase_color = ""
+            field_phase_visibility = None
+            relation_fields_for_retry = [
+                deepcopy(field)
+                for field in schema_add_fields
+                if isinstance(field, dict) and _multi_app_field_type(field) == PublicFieldType.relation.value
+            ]
+            schema_jobs.append(
+                {
+                    "index": index,
+                    "existing": existing,
+                    "app_key": app_key,
+                    "field_phase_app_name": field_phase_app_name,
+                    "field_phase_icon": field_phase_icon,
+                    "field_phase_color": field_phase_color,
+                    "field_phase_visibility": field_phase_visibility,
+                    "schema_add_fields": schema_add_fields,
+                    "update_fields": update_fields,
+                    "remove_fields": remove_fields,
+                    "layout_sections": layout_sections,
+                    "relation_fields_for_retry": relation_fields_for_retry,
+                }
+            )
+
+        schema_workers = worker_count(len(schema_jobs))
+        parallelism["schema_workers"] = schema_workers
+
+        def run_schema_job(job: JSONObject) -> JSONObject:
+            index = int(job["index"])
+            app_key = str(job.get("app_key") or "")
+            field_phase_app_name = str(job.get("field_phase_app_name") or "")
+            field_phase_icon = str(job.get("field_phase_icon") or "")
+            field_phase_color = str(job.get("field_phase_color") or "")
+            field_phase_visibility = job.get("field_phase_visibility")
+            schema_add_fields = list(job.get("schema_add_fields") or [])
+            update_fields = list(job.get("update_fields") or [])
+            remove_fields = list(job.get("remove_fields") or [])
+            layout_sections = list(job.get("layout_sections") or [])
+            relation_fields_for_retry = list(job.get("relation_fields_for_retry") or [])
+            field_started_at = time.perf_counter()
+            try:
+                field_result = self._app_schema_apply_once(
+                    profile=profile,
+                    app_key=app_key,
+                    package_id=None,
+                    app_name=field_phase_app_name,
+                    app_title="",
+                    icon=field_phase_icon,
+                    color=field_phase_color,
+                    visibility=field_phase_visibility,
+                    publish=publish,
+                    add_fields=schema_add_fields,
+                    update_fields=update_fields,
+                    remove_fields=remove_fields,
+                    inline_form_layout_sections=layout_sections,
+                    allow_inline_layout_fallback=False,
+                )
+                public_result = _publicize_package_fields(field_result)
+            except Exception as error:  # pragma: no cover - defensive guard for unexpected worker failures
+                return {
+                    "index": index,
+                    "job": job,
+                    "elapsed_ms": _elapsed_ms(field_started_at),
+                    "exception": repr(error),
+                }
+            if _multi_app_deferred_relation_retryable(public_result, relation_fields_for_retry):
+                first_error = {
+                    "error_code": public_result.get("error_code"),
+                    "message": public_result.get("message"),
+                    "backend_code": public_result.get("backend_code"),
+                    "http_status": public_result.get("http_status"),
+                    "details": deepcopy(public_result.get("details")) if isinstance(public_result.get("details"), dict) else None,
+                }
+                retry_attempts: list[JSONObject] = []
+                for retry_index, delay_seconds in enumerate((1.0, 5.0), start=1):
+                    retry_readback = self._stabilize_deferred_relation_metadata(
                         profile=profile,
-                        schema_result=shell_result,
-                        fallback_app_key=app_key,
+                        source_app_key=app_key,
+                        deferred_add_fields=relation_fields_for_retry,
+                        delay_seconds=delay_seconds,
+                    )
+                    retry_result = self._app_schema_apply_once(
+                        profile=profile,
+                        app_key=app_key,
+                        package_id=None,
+                        app_name=field_phase_app_name,
+                        app_title="",
+                        icon=field_phase_icon,
+                        color=field_phase_color,
+                        visibility=field_phase_visibility,
                         publish=publish,
-                        sections=layout_sections,
+                        add_fields=schema_add_fields,
+                        update_fields=update_fields,
+                        remove_fields=remove_fields,
+                        inline_form_layout_sections=layout_sections,
+                        allow_inline_layout_fallback=False,
                     )
-                    if _schema_apply_result_has_write(shell_result):
-                        any_write_executed = True
-                    if _schema_apply_result_may_have_write(shell_result):
-                        any_write_may_have_succeeded = True
-                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({
+                    public_retry_result = _publicize_package_fields(retry_result)
+                    retry_attempts.append(
+                        {
+                            "attempt": retry_index,
+                            "delay_seconds": delay_seconds,
+                            "status": public_retry_result.get("status"),
+                            "error_code": public_retry_result.get("error_code"),
+                            "backend_code": public_retry_result.get("backend_code"),
+                            "http_status": public_retry_result.get("http_status"),
+                            "readback": retry_readback,
+                        }
+                    )
+                    public_result = public_retry_result
+                    if not _multi_app_deferred_relation_retryable(public_result, relation_fields_for_retry):
+                        break
+                retry_details = public_result.get("details")
+                if not isinstance(retry_details, dict):
+                    retry_details = {}
+                    public_result["details"] = retry_details
+                retry_summary: JSONObject = {
+                    "attempted": True,
+                    "reason": "same_batch_relation_metadata_may_lag",
+                    "first_error": first_error,
+                    "attempts": retry_attempts,
+                }
+                if retry_attempts:
+                    retry_summary["readback"] = retry_attempts[-1].get("readback")
+                retry_details["deferred_relation_retry"] = retry_summary
+            if layout_sections and not _inline_form_layout_was_handled(public_result):
+                public_result = mark_inline_layout_not_applied_in_schema(
+                    public_result,
+                    app_key=app_key,
+                    sections=layout_sections,
+                )
+            return {
+                "index": index,
+                "job": job,
+                "elapsed_ms": _elapsed_ms(field_started_at),
+                "public_result": public_result,
+            }
+
+        schema_outputs: list[JSONObject] = []
+        schema_phase_started_at = time.perf_counter()
+        if schema_jobs:
+            with ThreadPoolExecutor(max_workers=schema_workers) as executor:
+                futures = [executor.submit(run_schema_job, job) for job in schema_jobs]
+                for future in as_completed(futures):
+                    schema_outputs.append(future.result())
+        app_field_apply_ms += _elapsed_ms(schema_phase_started_at)
+
+        for output in sorted(schema_outputs, key=lambda item: int(item.get("index", 0))):
+            index = int(output["index"])
+            job = output.get("job") if isinstance(output.get("job"), dict) else {}
+            existing = job.get("existing") if isinstance(job.get("existing"), dict) else {}
+            app_key = str(job.get("app_key") or "")
+            exception = output.get("exception")
+            if exception:
+                final_items_by_index[index] = {
                     **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
-                    "status": item_status,
+                    "status": "pending_readback",
                     "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"),
-                    "write_executed": _schema_apply_result_has_write(shell_result),
-                    "write_may_have_succeeded": _schema_apply_result_may_have_write(shell_result),
+                    "error_code": "SCHEMA_APPLY_EXCEPTION",
+                    "message": str(exception),
+                    "write_executed": False,
+                    "write_may_have_succeeded": True,
                     "safe_to_retry": False,
-                    **({"next_action": shell_result.get("next_action")} if shell_result.get("next_action") else {}),
-                    **({"verification": shell_result.get("verification")} if isinstance(shell_result.get("verification"), dict) else {}),
-                    **({"inline_form_layout": shell_result.get("inline_form_layout")} if isinstance(shell_result.get("inline_form_layout"), dict) else {}),
-                    **({"inline_form_layout_result": shell_result.get("inline_form_layout_result")} if isinstance(shell_result.get("inline_form_layout_result"), dict) else {}),
-                })
+                    "next_action": "readback_before_retry",
+                }
+                if app_key:
+                    pending_readback_app_keys.append(app_key)
+                if existing.get("app_name"):
+                    pending_readback_app_names.append(str(existing.get("app_name")))
+                any_write_may_have_succeeded = True
                 continue
-
-            field_result = self._app_schema_apply_once(
-                profile=profile,
-                app_key=app_key,
-                package_id=None,
-                app_name=str(compiled_item.get("app_name") or compiled_item.get("appTitle") or compiled_item.get("app_title") or ""),
-                app_title="",
-                icon=str(compiled_item.get("icon") or ""),
-                color=str(compiled_item.get("color") or ""),
-                visibility=compiled_item.get("visibility"),
-                create_if_missing=False,
-                publish=publish,
-                add_fields=deferred_add_fields,
-                update_fields=update_fields,
-                remove_fields=remove_fields,
-                inline_form_layout_sections=list(compiled_item.get("_inline_form_layout_sections") or []),
-            )
-            public_result = _publicize_package_fields(field_result)
-            layout_sections = list(compiled_item.get("_inline_form_layout_sections") or [])
-            if layout_sections and not _inline_form_layout_was_handled(public_result):
-                public_result = self._apply_inline_form_layout_after_schema(
-                    profile=profile,
-                    schema_result=public_result,
-                    fallback_app_key=app_key,
-                    publish=publish,
-                    sections=layout_sections,
-                )
+            public_result = output.get("public_result") if isinstance(output.get("public_result"), dict) else {}
+            merge_child_duration(public_result)
             if _schema_apply_result_has_write(public_result):
                 any_write_executed = True
             if _schema_apply_result_may_have_write(public_result):
@@ -2570,7 +2904,7 @@ class AiBuilderTools(ToolBase):
                     pending_readback_app_keys.append(app_key)
                 if existing.get("app_name"):
                     pending_readback_app_names.append(str(existing.get("app_name")))
-            final_items.append({
+            final_items_by_index[index] = {
                 **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
                 "status": item_status,
                 "stage": "schema_apply",
@@ -2585,12 +2919,17 @@ class AiBuilderTools(ToolBase):
                 "write_executed": _schema_apply_result_has_write(public_result),
                 "write_may_have_succeeded": _schema_apply_result_may_have_write(public_result),
                 "safe_to_retry": False,
+                **_multi_app_child_diagnostics(public_result),
                 **({"next_action": public_result.get("next_action")} if public_result.get("next_action") else {}),
                 **({"verification": public_result.get("verification")} if isinstance(public_result.get("verification"), dict) else {}),
                 **({"inline_form_layout": public_result.get("inline_form_layout")} if isinstance(public_result.get("inline_form_layout"), dict) else {}),
                 **({"inline_form_layout_result": public_result.get("inline_form_layout_result")} if isinstance(public_result.get("inline_form_layout_result"), dict) else {}),
-            })
+            }
 
+        final_items: list[JSONObject] = [
+            item if isinstance(item, dict) else _multi_app_item_failure(index, apps[index], "APP_ITEM_NOT_PROCESSED", "app item was not processed")
+            for index, item in enumerate(final_items_by_index)
+        ]
         pending_readback = sum(1 for item in final_items if item.get("status") == "pending_readback")
         succeeded = sum(1 for item in final_items if item.get("status") in {"success", "partial_success"})
         failed = sum(1 for item in final_items if item.get("status") == "failed")
@@ -2614,6 +2953,7 @@ class AiBuilderTools(ToolBase):
             "package_id": package_id,
             "publish_requested": publish,
             "apps": final_items,
+            "parallelism": parallelism,
             "normalized_args": normalized_args,
             "verification": {
                 "all_apps_succeeded": failed == 0,
@@ -2634,7 +2974,69 @@ class AiBuilderTools(ToolBase):
             response["next_action"] = "readback_before_retry"
             response["pending_readback_app_keys"] = list(dict.fromkeys(pending_readback_app_keys))
             response["pending_readback_app_names"] = list(dict.fromkeys(pending_readback_app_names))
-        return response
+        return finish(response)
+
+    def _stabilize_deferred_relation_metadata(
+        self,
+        *,
+        profile: str,
+        source_app_key: str,
+        deferred_add_fields: list[JSONObject],
+        delay_seconds: float,
+    ) -> list[JSONObject]:
+        edit_context_result = self._finish_deferred_relation_edit_context(profile=profile, app_key=source_app_key)
+        time.sleep(delay_seconds)
+        app_keys = [source_app_key]
+        for key in _multi_app_relation_target_app_keys(deferred_add_fields):
+            if key and key not in app_keys:
+                app_keys.append(key)
+        readback: list[JSONObject] = []
+        for app_key in app_keys:
+            try:
+                result = self._facade.app_read_fields(profile=profile, app_key=app_key)
+                readback.append(
+                    {
+                        "app_key": app_key,
+                        "status": result.get("status"),
+                        "field_count": len(result.get("fields") or []),
+                        **({"edit_context": edit_context_result} if app_key == source_app_key else {}),
+                    }
+                )
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                readback.append(
+                    {
+                        "app_key": app_key,
+                        "status": "failed",
+                        "transport_error": {
+                            "http_status": api_error.http_status,
+                            "backend_code": api_error.backend_code,
+                            "category": api_error.category,
+                            "request_id": api_error.request_id,
+                        },
+                    }
+                )
+        return readback
+
+    def _finish_deferred_relation_edit_context(self, *, profile: str, app_key: str) -> JSONObject:
+        try:
+            version_result = self._facade.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+            raw_version = version_result.get("editVersionNo") or version_result.get("versionNo") or 1
+            edit_version_no = int(raw_version)
+            self._facade.apps.app_edit_finished(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
+            return {"status": "success", "edit_version_no": edit_version_no}
+        except (QingflowApiError, RuntimeError, TypeError, ValueError) as error:
+            api_error = _coerce_api_error(error if isinstance(error, (QingflowApiError, RuntimeError)) else RuntimeError(str(error)))
+            return {
+                "status": "failed",
+                "message": api_error.message,
+                "transport_error": {
+                    "http_status": api_error.http_status,
+                    "backend_code": api_error.backend_code,
+                    "category": api_error.category,
+                    "request_id": api_error.request_id,
+                },
+            }
 
     def _app_schema_apply_once(
         self,
@@ -2647,16 +3049,17 @@ class AiBuilderTools(ToolBase):
         icon: str = "",
         color: str = "",
         visibility: JSONObject | None = None,
-        create_if_missing: bool = False,
         publish: bool = True,
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
         inline_form_layout_sections: list[JSONObject] | None = None,
+        allow_inline_layout_fallback: bool = True,
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
         started_at = time.perf_counter()
         effective_app_name = app_name or app_title
+        creating = not bool(str(app_key or "").strip()) and package_id is not None and bool(str(effective_app_name or "").strip())
         system_field_failure = _reserved_system_field_name_failure(
             tool_name="app_schema_apply",
             profile=profile,
@@ -2666,7 +3069,6 @@ class AiBuilderTools(ToolBase):
             icon=icon,
             color=color,
             visibility=visibility,
-            create_if_missing=create_if_missing,
             publish=publish,
             add_fields=add_fields,
             update_fields=update_fields,
@@ -2678,42 +3080,19 @@ class AiBuilderTools(ToolBase):
             tool_name="app_schema_apply",
             icon=icon,
             color=color,
-            creating=not bool(str(app_key or "").strip()) and bool(create_if_missing),
+            creating=creating,
         )
         if icon_failure is not None:
             return icon_failure
-        plan_result = self._rewrite_plan_result_for_apply(
-            result=self.app_schema_plan(
-                profile=profile,
-                app_key=app_key,
-                package_id=package_id,
-                app_name=effective_app_name,
-                icon=icon,
-                color=color,
-                visibility=visibility,
-                create_if_missing=create_if_missing,
-                add_fields=add_fields,
-                update_fields=update_fields,
-                remove_fields=remove_fields,
-            ),
-            profile=profile,
-            publish=publish,
-            plan_tool_name="app_schema_plan",
-            apply_tool_name="app_schema_apply",
-        )
-        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
-            return plan_result
-        plan_args = plan_result.get("normalized_args")
-        if not isinstance(plan_args, dict):
-            plan_args = {}
         try:
-            parsed_add = [FieldPatch.model_validate(item) for item in plan_args.get("add_fields") or []]
-            parsed_update = [FieldUpdatePatch.model_validate(item) for item in plan_args.get("update_fields") or []]
-            parsed_remove = [FieldRemovePatch.model_validate(item) for item in plan_args.get("remove_fields") or []]
+            parsed_add = [FieldPatch.model_validate(item) for item in add_fields or []]
+            parsed_update = [FieldUpdatePatch.model_validate(item) for item in update_fields or []]
+            parsed_remove = [FieldRemovePatch.model_validate(item) for item in remove_fields or []]
             parsed_inline_layout = [
                 LayoutSectionPatch.model_validate(item)
                 for item in (inline_form_layout_sections or [])
             ]
+            parsed_visibility = VisibilityPatch.model_validate(visibility) if visibility is not None else None
         except ValidationError as exc:
             return _validation_failure(
                 str(exc),
@@ -2723,28 +3102,26 @@ class AiBuilderTools(ToolBase):
                     "tool_name": "app_schema_apply",
                     "arguments": {
                         "profile": profile,
-                        "app_key": str(plan_args.get("app_key") or app_key),
-                        "package_id": plan_args.get("package_id", package_id),
-                        "app_name": str(plan_args.get("app_name") or effective_app_name),
-                        "icon": str(plan_args.get("icon") or icon),
-                        "color": str(plan_args.get("color") or color),
-                        "visibility": plan_args.get("visibility") or visibility,
-                        "create_if_missing": bool(plan_args.get("create_if_missing", create_if_missing)),
+                        "app_key": str(app_key or ""),
+                        "package_id": package_id,
+                        "app_name": effective_app_name,
+                        "icon": str(icon or ""),
+                        "color": str(color or ""),
+                        "visibility": visibility,
                         "publish": publish,
-                        "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 [],
+                        "add_fields": add_fields or [{"name": "字段名称", "type": "text", "required": False}],
+                        "update_fields": update_fields or [],
+                        "remove_fields": remove_fields or [],
                     },
                 },
             )
         normalized_args = {
-            "app_key": str(plan_args.get("app_key") or app_key),
-            "package_id": plan_args.get("package_id", package_id),
-            "app_name": str(plan_args.get("app_name") or effective_app_name),
-            "icon": str(plan_args.get("icon") or icon or ""),
-            "color": str(plan_args.get("color") or color or ""),
-            "visibility": plan_args.get("visibility") or visibility,
-            "create_if_missing": bool(plan_args.get("create_if_missing", create_if_missing)),
+            "app_key": str(app_key or ""),
+            "package_id": package_id,
+            "app_name": effective_app_name,
+            "icon": str(icon or ""),
+            "color": str(color or ""),
+            "visibility": parsed_visibility.model_dump(mode="json") if parsed_visibility is not None else None,
             "publish": publish,
             "add_fields": [patch.model_dump(mode="json") for patch in parsed_add],
             "update_fields": [patch.model_dump(mode="json") for patch in parsed_update],
@@ -2763,13 +3140,12 @@ class AiBuilderTools(ToolBase):
         result = _safe_tool_call(
             lambda: self._facade.app_schema_apply(
                 profile=profile,
-                app_key=str(plan_args.get("app_key") or app_key),
-                package_tag_id=plan_args.get("package_id", package_id),
-                app_name=str(plan_args.get("app_name") or effective_app_name),
-                icon=str(plan_args.get("icon") or icon or ""),
-                color=str(plan_args.get("color") or color or ""),
-                visibility=VisibilityPatch.model_validate(plan_args.get("visibility")) if plan_args.get("visibility") is not None else None,
-                create_if_missing=bool(plan_args.get("create_if_missing", create_if_missing)),
+                app_key=str(app_key or ""),
+                package_tag_id=package_id,
+                app_name=effective_app_name,
+                icon=str(icon or ""),
+                color=str(color or ""),
+                visibility=parsed_visibility,
                 publish=publish,
                 add_fields=parsed_add,
                 update_fields=parsed_update,
@@ -2781,12 +3157,12 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_schema_apply", "arguments": {"profile": profile, **normalized_args}},
         )
         public_result = _publicize_package_fields(result)
-        if inline_form_layout_sections and not _inline_form_layout_was_handled(public_result):
+        if inline_form_layout_sections and allow_inline_layout_fallback and not _inline_form_layout_was_handled(public_result):
             layout_started_at = time.perf_counter()
             public_result = self._apply_inline_form_layout_after_schema(
                 profile=profile,
                 schema_result=public_result,
-                fallback_app_key=str(plan_args.get("app_key") or app_key),
+                fallback_app_key=str(app_key or ""),
                 publish=publish,
                 sections=inline_form_layout_sections,
             )
@@ -2912,27 +3288,9 @@ class AiBuilderTools(ToolBase):
 
     def _app_layout_apply_once(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
         """执行内部辅助逻辑。"""
-        plan_result = self._rewrite_plan_result_for_apply(
-            result=self.app_layout_plan(
-                profile=profile,
-                app_key=app_key,
-                mode=mode,
-                sections=sections,
-                preset=None,
-            ),
-            profile=profile,
-            publish=publish,
-            plan_tool_name="app_layout_plan",
-            apply_tool_name="app_layout_apply",
-        )
-        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
-            return plan_result
-        plan_args = plan_result.get("normalized_args")
-        if not isinstance(plan_args, dict):
-            plan_args = {}
         try:
-            parsed_mode = LayoutApplyMode(str(plan_args.get("mode") or mode))
-            parsed_sections = [LayoutSectionPatch.model_validate(item) for item in plan_args.get("sections") or []]
+            parsed_mode = LayoutApplyMode(str(mode or "merge"))
+            parsed_sections = [LayoutSectionPatch.model_validate(item) for item in sections or []]
         except (ValueError, ValidationError) as exc:
             return _validation_failure(
                 str(exc),
@@ -2942,15 +3300,15 @@ class AiBuilderTools(ToolBase):
                     "tool_name": "app_layout_apply",
                     "arguments": {
                         "profile": profile,
-                        "app_key": str(plan_args.get("app_key") or app_key),
-                        "mode": str(plan_args.get("mode") or "merge"),
+                        "app_key": app_key,
+                        "mode": str(mode or "merge"),
                         "publish": publish,
-                        "sections": plan_args.get("sections") or [{"title": "基础信息", "rows": [["字段A", "字段B"]]}],
+                        "sections": sections or [{"title": "基础信息", "rows": [["字段A", "字段B"]]}],
                     },
                 },
             )
         normalized_args = {
-            "app_key": str(plan_args.get("app_key") or app_key),
+            "app_key": app_key,
             "mode": parsed_mode.value,
             "publish": publish,
             "sections": [section.model_dump(mode="json", exclude_none=True) for section in parsed_sections],
@@ -2958,7 +3316,7 @@ class AiBuilderTools(ToolBase):
         return _safe_tool_call(
             lambda: self._facade.app_layout_apply(
                 profile=profile,
-                app_key=str(plan_args.get("app_key") or app_key),
+                app_key=app_key,
                 mode=parsed_mode,
                 publish=publish,
                 sections=parsed_sections,
@@ -3061,32 +3419,13 @@ class AiBuilderTools(ToolBase):
         transitions: list[JSONObject],
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
-        plan_result = self._rewrite_plan_result_for_apply(
-            result=self.app_flow_plan(
-                profile=profile,
-                app_key=app_key,
-                mode=mode,
-                nodes=nodes,
-                transitions=transitions,
-                preset=None,
-            ),
-            profile=profile,
-            publish=publish,
-            plan_tool_name="app_flow_plan",
-            apply_tool_name="app_flow_apply",
-        )
-        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
-            return plan_result
-        plan_args = plan_result.get("normalized_args")
-        if not isinstance(plan_args, dict):
-            plan_args = {}
         try:
             request = FlowPlanRequest.model_validate(
                 {
-                    "app_key": plan_args.get("app_key") or app_key,
-                    "mode": plan_args.get("mode") or mode,
-                    "nodes": plan_args.get("nodes") or [],
-                    "transitions": plan_args.get("transitions") or [],
+                    "app_key": app_key,
+                    "mode": mode,
+                    "nodes": nodes or [],
+                    "transitions": transitions or [],
                     "preset": None,
                 }
             )
@@ -3099,11 +3438,11 @@ class AiBuilderTools(ToolBase):
                     "tool_name": "app_flow_apply",
                     "arguments": {
                         "profile": profile,
-                        "app_key": str(plan_args.get("app_key") or app_key),
-                        "mode": str(plan_args.get("mode") or "replace"),
+                        "app_key": app_key,
+                        "mode": str(mode or "replace"),
                         "publish": publish,
-                        "nodes": plan_args.get("nodes") or [{"id": "start", "type": "start", "name": "发起"}],
-                        "transitions": plan_args.get("transitions") or [],
+                        "nodes": nodes or [{"id": "start", "type": "start", "name": "发起"}],
+                        "transitions": transitions or [],
                     },
                 },
             )
@@ -3200,69 +3539,9 @@ class AiBuilderTools(ToolBase):
         )
         if reserved_failure is not None:
             return reserved_failure
-        if patch_views or _view_payload_has_action_buttons(upsert_views=upsert_views, patch_views=patch_views):
-            try:
-                parsed_views = [ViewUpsertPatch.model_validate(item) for item in (upsert_views or [])]
-                parsed_patch_views = [ViewPartialPatch.model_validate(item) for item in patch_views]
-            except ValidationError as exc:
-                return _visibility_validation_failure(
-                    str(exc),
-                    tool_name="app_views_apply",
-                    exc=exc,
-                    suggested_next_call={
-                        "tool_name": "app_views_apply",
-                        "arguments": {
-                            "profile": profile,
-                            "app_key": app_key,
-                            "publish": publish,
-                            "upsert_views": upsert_views or [],
-                            "patch_views": [
-                                {"view_key": "VIEW_KEY", "set": {"query_conditions": {"enabled": True, "rows": [["字段A"]]}}},
-                            ],
-                            "remove_views": remove_views or [],
-                        },
-                    },
-                )
-            normalized_args = {
-                "app_key": app_key,
-                "publish": publish,
-                "upsert_views": [public_view_upsert_payload(view) for view in parsed_views],
-                "patch_views": [public_view_partial_payload(patch) for patch in parsed_patch_views],
-                "remove_views": list(remove_views or []),
-            }
-            return _safe_tool_call(
-                lambda: self._facade.app_views_apply(
-                    profile=profile,
-                    app_key=app_key,
-                    publish=publish,
-                    upsert_views=parsed_views,
-                    patch_views=parsed_patch_views,
-                    remove_views=list(remove_views or []),
-                ),
-                error_code="VIEWS_APPLY_FAILED",
-                normalized_args=normalized_args,
-                suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **normalized_args}},
-            )
-        plan_result = self._rewrite_plan_result_for_apply(
-            result=self.app_views_plan(
-                profile=profile,
-                app_key=app_key,
-                upsert_views=upsert_views,
-                remove_views=remove_views,
-                preset=None,
-            ),
-            profile=profile,
-            publish=publish,
-            plan_tool_name="app_views_plan",
-            apply_tool_name="app_views_apply",
-        )
-        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
-            return plan_result
-        plan_args = plan_result.get("normalized_args")
-        if not isinstance(plan_args, dict):
-            plan_args = {}
         try:
-            parsed_views = [ViewUpsertPatch.model_validate(item) for item in plan_args.get("upsert_views") or []]
+            parsed_views = [ViewUpsertPatch.model_validate(item) for item in (upsert_views or [])]
+            parsed_patch_views = [ViewPartialPatch.model_validate(item) for item in (patch_views or [])]
         except ValidationError as exc:
             return _visibility_validation_failure(
                 str(exc),
@@ -3272,28 +3551,29 @@ class AiBuilderTools(ToolBase):
                     "tool_name": "app_views_apply",
                     "arguments": {
                         "profile": profile,
-                        "app_key": str(plan_args.get("app_key") or app_key),
+                        "app_key": app_key,
                         "publish": publish,
-                        "upsert_views": plan_args.get("upsert_views") or [{"name": "业务台账视图", "type": "table", "columns": ["字段A"]}],
-                        "remove_views": plan_args.get("remove_views") or [],
+                        "upsert_views": upsert_views or [{"name": "业务台账视图", "type": "table", "columns": ["字段A"]}],
+                        "patch_views": patch_views or [],
+                        "remove_views": remove_views or [],
                     },
                 },
             )
         normalized_args = {
-            "app_key": str(plan_args.get("app_key") or app_key),
+            "app_key": app_key,
             "publish": publish,
             "upsert_views": [public_view_upsert_payload(view) for view in parsed_views],
-            "patch_views": [],
-            "remove_views": list(plan_args.get("remove_views") or remove_views),
+            "patch_views": [public_view_partial_payload(patch) for patch in parsed_patch_views],
+            "remove_views": list(remove_views or []),
         }
         return _safe_tool_call(
             lambda: self._facade.app_views_apply(
                 profile=profile,
-                app_key=str(plan_args.get("app_key") or app_key),
+                app_key=app_key,
                 publish=publish,
                 upsert_views=parsed_views,
-                patch_views=[],
-                remove_views=list(plan_args.get("remove_views") or remove_views),
+                patch_views=parsed_patch_views,
+                remove_views=list(remove_views or []),
             ),
             error_code="VIEWS_APPLY_FAILED",
             normalized_args=normalized_args,
@@ -4049,7 +4329,6 @@ def _multi_app_static_validation_failure(
     *,
     tool_name: str,
     apps: list[JSONObject],
-    create_if_missing: bool,
 ) -> JSONObject | None:
     issues: list[JSONObject] = []
     client_key_indexes: dict[str, int] = {}
@@ -4112,17 +4391,6 @@ def _multi_app_static_validation_failure(
                 }
             )
             continue
-        if new_app_item and not create_if_missing:
-            issues.append(
-                {
-                    "index": index,
-                    "row_number": index + 1,
-                    "path": f"apps[{index}]",
-                    "error_code": "CREATE_IF_MISSING_REQUIRED",
-                    "message": "apps[] item with app_name but no app_key cannot run when create_if_missing=false",
-                    "fix_hint": "Omit create_if_missing in multi-app mode, set it to true, or pass app_key for every existing app item.",
-                }
-            )
 
         add_fields = _multi_app_list_value(item, "add_fields", "addFields")
         if new_app_item:
@@ -4324,6 +4592,86 @@ def _compiled_multi_app_deferred_add_fields(compiled_item: JSONObject, existing_
     ]
 
 
+def _multi_app_child_diagnostics(result: JSONObject) -> JSONObject:
+    diagnostics: JSONObject = {}
+    for key in (
+        "backend_code",
+        "http_status",
+        "request_id",
+        "details",
+        "suggested_next_call",
+        "warnings",
+        "publish_result",
+        "duration_breakdown_ms",
+    ):
+        value = result.get(key)
+        if value is None:
+            continue
+        if isinstance(value, (dict, list)) and not value:
+            continue
+        diagnostics[key] = deepcopy(value)
+    return diagnostics
+
+
+def _multi_app_field_type(field: JSONObject) -> str:
+    raw_type = str(field.get("type") or field.get("field_type") or field.get("fieldType") or "").strip()
+    if raw_type:
+        normalized = FIELD_TYPE_ALIASES.get(raw_type.lower())
+        return normalized.value if normalized is not None else raw_type
+    raw_type_id = field.get("type_id") or field.get("typeId") or field.get("field_type_id") or field.get("fieldTypeId")
+    try:
+        normalized_by_id = FIELD_TYPE_ID_ALIASES.get(int(raw_type_id))
+    except (TypeError, ValueError):
+        normalized_by_id = None
+    return normalized_by_id.value if normalized_by_id is not None else ""
+
+
+def _multi_app_deferred_relation_retryable(result: JSONObject, deferred_add_fields: list[JSONObject]) -> bool:
+    if not deferred_add_fields:
+        return False
+    if not any(_multi_app_field_type(field) == PublicFieldType.relation.value for field in deferred_add_fields if isinstance(field, dict)):
+        return False
+    if result.get("status") in {"success", "partial_success"}:
+        return False
+    if result.get("error_code") != "SCHEMA_APPLY_FAILED":
+        return False
+    if _schema_apply_result_has_write(result):
+        return False
+    return backend_code_value_int(_result_backend_code(result)) == 400
+
+
+def _result_backend_code(result: JSONObject) -> Any:
+    if result.get("backend_code") is not None:
+        return result.get("backend_code")
+    details = result.get("details")
+    if isinstance(details, dict):
+        transport = details.get("transport_error")
+        if isinstance(transport, dict):
+            return transport.get("backend_code")
+    return None
+
+
+def _multi_app_relation_target_app_keys(fields: list[JSONObject]) -> list[str]:
+    app_keys: list[str] = []
+
+    def visit(value: Any) -> None:
+        if isinstance(value, list):
+            for item in value:
+                visit(item)
+            return
+        if not isinstance(value, dict):
+            return
+        target_app_key = str(value.get("target_app_key") or value.get("targetAppKey") or "").strip()
+        if target_app_key and target_app_key not in app_keys:
+            app_keys.append(target_app_key)
+        for child in value.values():
+            if isinstance(child, (dict, list)):
+                visit(child)
+
+    visit(fields)
+    return app_keys
+
+
 def _multi_app_list_value(item: JSONObject, *keys: str) -> list[JSONObject]:
     for key in keys:
         value = item.get(key)
@@ -4501,7 +4849,6 @@ def _reserved_system_field_name_failure(
     icon: str | None = None,
     color: str | None = None,
     visibility: JSONObject | None = None,
-    create_if_missing: bool = False,
     publish: bool | None = None,
     add_fields: list[JSONObject] | None = None,
     update_fields: list[JSONObject] | None = None,
@@ -4521,7 +4868,6 @@ def _reserved_system_field_name_failure(
             "icon": icon or "",
             "color": color or "",
             "visibility": visibility,
-            "create_if_missing": create_if_missing,
             "add_fields": suggested_add_fields,
             "update_fields": update_fields or [],
             "remove_fields": remove_fields or [],
@@ -4550,7 +4896,6 @@ def _reserved_system_field_name_failure_for_apps(
     profile: str,
     package_id: int | None,
     visibility: JSONObject | None,
-    create_if_missing: bool,
     publish: bool,
     apps: list[JSONObject],
 ) -> JSONObject | None:
@@ -4566,7 +4911,6 @@ def _reserved_system_field_name_failure_for_apps(
             icon=str(item.get("icon") or ""),
             color=str(item.get("color") or ""),
             visibility=item.get("visibility") if isinstance(item.get("visibility"), dict) else visibility,
-            create_if_missing=create_if_missing,
             publish=publish,
             add_fields=list(item.get("add_fields") or item.get("addFields") or []),
             update_fields=list(item.get("update_fields") or item.get("updateFields") or []),
@@ -4584,7 +4928,6 @@ def _reserved_system_field_name_failure_for_apps(
                     "profile": profile,
                     "package_id": package_id,
                     "visibility": visibility,
-                    "create_if_missing": create_if_missing,
                     "publish": publish,
                     "apps": fixed_apps,
                 }
@@ -4759,12 +5102,13 @@ def _safe_tool_call(
     normalized_args: JSONObject,
     suggested_next_call: JSONObject | None,
 ) -> JSONObject:
+    started_at = time.perf_counter()
     try:
-        return call()
+        result = call()
     except (QingflowApiError, RuntimeError) as error:
         api_error = _coerce_api_error(error)
         public_http_status = None if api_error.http_status == 404 else api_error.http_status
-        return {
+        result = {
             "status": "failed",
             "error_code": error_code,
             "recoverable": True,
@@ -4786,6 +5130,9 @@ def _safe_tool_call(
             "noop": False,
             "verification": {},
         }
+    if isinstance(result, dict):
+        _merge_duration_breakdown(result, tool_call_ms=_elapsed_ms(started_at))
+    return result
 
 
 def _publicize_package_fields(value):
@@ -4865,6 +5212,8 @@ def _builder_apply_json_paths() -> JSONObject:
         "warnings": "$.warnings",
         "verification": "$.verification",
         "details": "$.details",
+        "duration_breakdown_ms": "$.duration_breakdown_ms",
+        "total_ms": "$.duration_breakdown_ms.total_ms",
         "write_executed": "$.write_executed",
         "write_may_have_succeeded": "$.write_may_have_succeeded",
         "safe_to_retry": "$.safe_to_retry",
@@ -5875,7 +6224,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_keys": [
             "package_id",
             "package_name",
-            "create_if_missing",
             "icon",
             "color",
             "icon_name",
@@ -5888,7 +6236,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "aliases": {
             "packageId": "package_id",
             "packageName": "package_name",
-            "createIfMissing": "create_if_missing",
             "iconName": "icon",
             "iconColor": "color",
             "icon_config.name": "icon",
@@ -5905,6 +6252,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "execution_notes": [
             "create or update package metadata, visibility, grouping, and ordering in one call",
+            "create mode: package_name without package_id creates a package",
             "creating a package requires explicit icon + color; icon=template is blocked because it is too generic",
             "agent-facing primary icon shape is icon + color; icon_name/icon_color, icon_config, and icon={name,color} are compatibility aliases that normalize to icon/color",
             "updating a package preserves existing icon/color when omitted; explicit icon/color values are still validated",
@@ -5913,6 +6261,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "package_id maps internally to backend tagId; do not use tag_id in public calls",
             "items is a full package layout tree; omitting existing app/portal items is blocked unless allow_detach=true",
             "item shapes: {type:'app', app_key}, {type:'portal', dash_key}, or {type:'group', group_id?, name, items:[...]}",
+            "allow_detach=true with flat app/portal items and no groups is treated as an explicit full replacement and skips current layout read plus final package readback",
             "layout apply calls backend package ordering (MoveGroupAuth), so it requires package edit_app permission even when items=[] only clears/deletes existing groups",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
@@ -5932,7 +6281,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "create_example": {
             "profile": "default",
             "package_name": "项目管理",
-            "create_if_missing": True,
             "icon": "briefcase",
             "color": "azure",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
@@ -6151,6 +6499,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "remove_buttons supports button_id or exact unique button_text",
             "after a remove_buttons DELETE is sent, the tool verifies deletion by single button_id readback; removed[] returns delete_executed, readback_status, and safe_to_retry_delete=false",
             "if a removed button returns readback_status=unavailable or still_exists, treat the result as readback pending and do not blindly repeat the delete",
+            "pure create/update with returned button ids and no view_configs/remove skips the final custom-button inventory read; response details.final_readback_skipped=true",
             "all operations share one edit context and publish after at least one write succeeds; there is no draft-only mode for this tool",
             "background_color and text_color cannot both be white",
         ],
@@ -6296,6 +6645,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "client_key only lets a view_config reference a resource created earlier in the same apply call through associated_item_refs; it is not persisted and cannot deduplicate later apply calls",
             "remove_associated_item_ids sends DELETE and verifies deletion with one associated-resource pool readback because the backend has no confirmed single-item GET; removed[] returns delete_executed, readback_status, and safe_to_retry_delete=false",
             "if an associated resource delete returns readback_status=unavailable or still_exists, treat the result as readback pending and do not blindly repeat the delete",
+            "pure create/update with returned associated_item_id values and no view_configs/remove/reorder skips the final associated-resource pool read; response details.final_readback_skipped=true",
             "this tool publishes after at least one write succeeds; there is no draft-only mode",
             "visible=false hides the associated-resource area without clearing previous selected ids; visible=true with limit_type=all shows the whole app-level pool",
         ],
@@ -6330,7 +6680,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_schema_plan": {
-        "allowed_keys": ["app_key", "package_id", "app_name", "icon", "color", "visibility", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
+        "allowed_keys": ["app_key", "package_id", "app_name", "icon", "color", "visibility", "add_fields", "update_fields", "remove_fields"],
         "aliases": {
             "app_title": "app_name",
             "title": "app_name",
@@ -6385,7 +6735,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "icon": "briefcase",
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
-            "create_if_missing": True,
             "add_fields": [{"name": "项目名称", "type": "text", "data_title": True}],
             "update_fields": [],
             "remove_fields": [],
@@ -6419,7 +6768,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "icon_color",
             "icon_config",
             "visibility",
-            "create_if_missing",
             "publish",
             "form",
             "add_fields",
@@ -6502,13 +6850,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "use exactly one resource mode",
             "edit mode: app_key, optional app_name to rename the existing app",
-            "create mode: package_id + app_name + create_if_missing=true",
+            "create mode: package_id + app_name",
+            "create mode submits a create request directly after basic package add_app permission check; it does not scan app_name duplicates or reuse an existing app by name",
             "create mode follows backend CreateAppBean: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
-            "multi-app mode: pass package_id + apps[]; create_if_missing defaults to true for app_name items and may be set false only when every item uses app_key",
+            "multi-app mode: pass package_id + apps[]; items with app_name and no app_key are created, items with app_key update existing apps",
             "CLI --apps-file primary shape is {package_id, apps:[...]}; raw app arrays and singleton wrapper arrays are compatibility paths, not recommended examples",
             "create app schemas with form: form[].section names form sections; form[].rows[][] contains field objects; builder splits form into field creation plus form layout apply",
             "single-app CLI primary shape is --form-file; multi-app primary shape is apps[].form inside --apps-file",
-            "multi-app mode preflights static errors before writing: duplicate client_key/app_name, missing data title on new apps, explicit create_if_missing=false with app_name items, and unresolved target_app_ref/target_app",
+            "multi-app mode validates static payload errors before writing: duplicate client_key/app_name, missing data title on new apps, and unresolved target_app_ref/target_app",
             "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 relation fields may also use target_app with another apps[].app_name; prefer target_app_ref/client_key when names may collide",
             "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
@@ -6549,7 +6898,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "icon": "briefcase",
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
-            "create_if_missing": True,
             "publish": True,
             "form": [
                 {