@josephyan/qingflow-cli 1.1.4 → 1.1.5

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -15,17 +15,22 @@ 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
+from ..errors import QingflowApiError, backend_code_int
 from ..json_types import JSONObject
 from ..builder_facade.models import (
     AssociatedResourcesApplyRequest,
     ChartApplyRequest,
     CustomButtonsApplyRequest,
     CustomButtonPatch,
+    FIELD_TYPE_ALIASES,
     FIELD_TYPE_ID_ALIASES,
     FieldPatch,
     FieldRemovePatch,
     FieldUpdatePatch,
+    FlowPreset,
+    FlowNodePatch,
+    FlowPlanRequest,
+    FlowTransitionPatch,
     LayoutApplyMode,
     LayoutPlanRequest,
     LayoutPreset,
@@ -65,6 +70,7 @@ from .qingbi_report_tools import QingbiReportTools
 from .role_tools import RoleTools
 from .solution_tools import SolutionTools
 from .view_tools import ViewTools
+from .workflow_tools import WorkflowTools
 
 
 def _normalize_builder_view_key(value: str) -> str:
@@ -74,6 +80,32 @@ def _normalize_builder_view_key(value: str) -> str:
     return raw
 
 
+def _payload_get(payload: JSONObject, *keys: str, default: Any = None) -> Any:
+    for key in keys:
+        if key in payload:
+            return payload.get(key)
+    return default
+
+
+def _payload_list(payload: JSONObject, *keys: str, default: list | None = None) -> list:
+    value = _payload_get(payload, *keys, default=default if default is not None else [])
+    return value if isinstance(value, list) else []
+
+
+def _payload_bool(payload: JSONObject, *keys: str, default: bool = True) -> bool:
+    value = _payload_get(payload, *keys, default=default)
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"1", "true", "yes", "y", "on"}:
+            return True
+        if normalized in {"0", "false", "no", "n", "off"}:
+            return False
+    return bool(value)
+
+
+PUBLIC_STABLE_FLOW_NODE_TYPES = ["start", "approve", "fill", "copy", "webhook", "end"]
 BUILDER_APPLY_SCHEMA_VERSION = "builder.apply.v1"
 BUILDER_APPLY_TOOL_NAMES = {
     "package_apply",
@@ -85,6 +117,7 @@ BUILDER_APPLY_TOOL_NAMES = {
     "app_associated_resources_apply",
     "app_charts_apply",
     "portal_apply",
+    "portal_delete",
     "app_publish_verify",
 }
 
@@ -107,6 +140,7 @@ class AiBuilderTools(ToolBase):
             buttons=CustomButtonTools(sessions, backend),
             packages=PackageTools(sessions, backend),
             views=ViewTools(sessions, backend),
+            workflows=WorkflowTools(sessions, backend),
             portals=PortalTools(sessions, backend),
             charts=QingbiReportTools(sessions, backend),
             roles=RoleTools(sessions, backend),
@@ -114,6 +148,165 @@ class AiBuilderTools(ToolBase):
             solutions=SolutionTools(sessions, backend),
         )
 
+    def _apply_app_batch(self, *, tool_name: str, profile: str, apps: list[JSONObject], apply_one) -> JSONObject:
+        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"}]}},
+            ))
+
+        app_results: list[JSONObject] = []
+        errors: list[JSONObject] = []
+        for index, item in enumerate(apps):
+            if not isinstance(item, dict):
+                error = {
+                    "index": index,
+                    "status": "failed",
+                    "error_code": "APPS_FILE_ITEM_INVALID",
+                    "message": "apps[] item must be an object",
+                    "reason_path": f"apps[{index}]",
+                }
+                errors.append(error)
+                app_results.append(error)
+                continue
+            app_key = str(item.get("app_key") or item.get("appKey") or "").strip()
+            if not app_key:
+                error = {
+                    "index": index,
+                    "status": "failed",
+                    "error_code": "APPS_FILE_APP_KEY_REQUIRED",
+                    "message": "apps[] item requires app_key",
+                    "reason_path": f"apps[{index}].app_key",
+                }
+                errors.append(error)
+                app_results.append(error)
+                continue
+            try:
+                result = apply_one(index, item, app_key)
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                result = {
+                    "status": "failed",
+                    "error_code": f"{tool_name.upper()}_BATCH_ITEM_FAILED",
+                    "recoverable": True,
+                    "message": _public_error_message(f"{tool_name.upper()}_BATCH_ITEM_FAILED", api_error),
+                    "app_key": app_key,
+                    "normalized_args": {"app_key": app_key},
+                    "details": {"transport_error": _transport_error_payload(api_error)},
+                    "request_id": api_error.request_id,
+                    "backend_code": api_error.backend_code,
+                    "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                }
+            status = str(result.get("status") or "success") if isinstance(result, dict) else "failed"
+            wrapped: JSONObject = {
+                "index": index,
+                "app_key": app_key,
+                "status": status,
+                "result": result if isinstance(result, dict) else {"status": "failed", "message": str(result)},
+            }
+            if status == "failed":
+                error = {
+                    "index": index,
+                    "app_key": app_key,
+                    "status": status,
+                    "error_code": wrapped["result"].get("error_code"),
+                    "message": wrapped["result"].get("message"),
+                }
+                errors.append(error)
+                wrapped["error"] = error
+            app_results.append(wrapped)
+
+        succeeded = sum(1 for item in app_results if str(item.get("status") or "") in {"success", "partial_success"})
+        failed = len(app_results) - succeeded
+        status = "success" if failed == 0 else "failed" if succeeded == 0 else "partial_success"
+        write_executed = any(
+            isinstance(item.get("result"), dict) and bool(item["result"].get("write_executed"))
+            for item in app_results
+        )
+        payload: JSONObject = {
+            "status": status,
+            "error_code": None if status == "success" else f"{tool_name.upper()}_BATCH_PARTIAL" if succeeded else f"{tool_name.upper()}_BATCH_FAILED",
+            "recoverable": failed > 0,
+            "message": (
+                f"applied {tool_name} to {succeeded}/{len(app_results)} apps"
+                if status != "success"
+                else f"applied {tool_name} to {succeeded} apps"
+            ),
+            "normalized_args": {"apps": apps},
+            "apps": app_results,
+            "errors": errors,
+            "verification": {
+                "batch_verified": failed == 0,
+                "succeeded": succeeded,
+                "failed": failed,
+            },
+            "write_executed": write_executed,
+            "write_succeeded": write_executed and failed == 0,
+            "safe_to_retry": not write_executed,
+        }
+        return _attach_builder_apply_envelope(tool_name, 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()]
+        if not normalized_keys:
+            return _config_failure(
+                tool_name=tool_name,
+                message=f"{tool_name} batch mode requires non-empty app_keys[].",
+                fix_hint="Pass app_keys as a non-empty list of app keys.",
+                details={"expected_shape": {"app_keys": ["APP_A", "APP_B"]}},
+            )
+        apps: list[JSONObject] = []
+        errors: list[JSONObject] = []
+        for index, app_key in enumerate(normalized_keys):
+            try:
+                result = read_one(app_key)
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = _coerce_api_error(error)
+                result = {
+                    "status": "failed",
+                    "error_code": f"{tool_name.upper()}_BATCH_ITEM_FAILED",
+                    "recoverable": True,
+                    "message": _public_error_message(f"{tool_name.upper()}_BATCH_ITEM_FAILED", api_error),
+                    "app_key": app_key,
+                    "details": {"transport_error": _transport_error_payload(api_error)},
+                    "request_id": api_error.request_id,
+                    "backend_code": api_error.backend_code,
+                    "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                }
+            status = str(result.get("status") or "success") if isinstance(result, dict) else "failed"
+            app_item: JSONObject = {
+                "index": index,
+                "app_key": app_key,
+                "status": status,
+                "data": result,
+            }
+            if status == "failed":
+                error = {
+                    "index": index,
+                    "app_key": app_key,
+                    "status": "failed",
+                    "error_code": result.get("error_code") if isinstance(result, dict) else None,
+                    "message": result.get("message") if isinstance(result, dict) else str(result),
+                }
+                app_item["error"] = error
+                errors.append(error)
+            apps.append(app_item)
+        succeeded = sum(1 for item in apps if str(item.get("status") or "") in {"success", "partial_success"})
+        failed = len(apps) - succeeded
+        return {
+            "status": "success" if failed == 0 else "failed" if succeeded == 0 else "partial_success",
+            "error_code": None if failed == 0 else f"{tool_name.upper()}_BATCH_PARTIAL" if succeeded else f"{tool_name.upper()}_BATCH_FAILED",
+            "recoverable": failed > 0,
+            "message": f"read {tool_name} for {succeeded}/{len(apps)} apps" if failed else f"read {tool_name} for {succeeded} apps",
+            "normalized_args": {"app_keys": normalized_keys},
+            "app_keys": normalized_keys,
+            "apps": apps,
+            "errors": errors,
+            "verification": {"batch_verified": failed == 0, "succeeded": succeeded, "failed": failed},
+        }
+
     def register(self, mcp) -> None:
         """注册当前工具到 MCP 服务。"""
         @mcp.tool()
@@ -138,8 +331,11 @@ class AiBuilderTools(ToolBase):
             package_id: int | None = None,
             package_name: str | None = None,
             create_if_missing: bool = False,
-            icon: str | None = None,
+            icon: str | JSONObject | None = None,
             color: str | None = None,
+            icon_name: str | None = None,
+            icon_color: str | None = None,
+            icon_config: JSONObject | None = None,
             visibility: JSONObject | None = None,
             items: list[dict] | None = None,
             allow_detach: bool = False,
@@ -151,6 +347,9 @@ class AiBuilderTools(ToolBase):
                 create_if_missing=create_if_missing,
                 icon=icon,
                 color=color,
+                icon_name=icon_name,
+                icon_color=icon_color,
+                icon_config=icon_config,
                 visibility=visibility,
                 items=items or None,
                 allow_detach=allow_detach,
@@ -299,15 +498,11 @@ class AiBuilderTools(ToolBase):
 
         @mcp.tool()
         def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
-            if app_keys:
-                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get, data_key="summary", tool_name="app_get")
-            return self.app_get(profile=profile, app_key=app_key)
+            return self.app_get(profile=profile, app_key=app_key, app_keys=app_keys)
 
         @mcp.tool()
         def app_get_fields(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
-            if app_keys:
-                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_fields, data_key="fields", tool_name="app_get_fields")
-            return self.app_get_fields(profile=profile, app_key=app_key)
+            return self.app_get_fields(profile=profile, app_key=app_key, app_keys=app_keys)
 
         @mcp.tool()
         def app_repair_code_blocks(
@@ -320,39 +515,27 @@ class AiBuilderTools(ToolBase):
 
         @mcp.tool()
         def app_get_layout(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
-            if app_keys:
-                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_layout, data_key="sections", tool_name="app_get_layout")
-            return self.app_get_layout(profile=profile, app_key=app_key)
+            return self.app_get_layout(profile=profile, app_key=app_key, app_keys=app_keys)
 
         @mcp.tool()
         def app_get_views(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
-            if app_keys:
-                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_views, data_key="views", tool_name="app_get_views")
-            return self.app_get_views(profile=profile, app_key=app_key)
+            return self.app_get_views(profile=profile, app_key=app_key, app_keys=app_keys)
 
         @mcp.tool()
         def app_get_flow(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
-            if app_keys:
-                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_flow, data_key="spec", tool_name="app_get_flow")
-            return self.app_get_flow(profile=profile, app_key=app_key)
+            return self.app_get_flow(profile=profile, app_key=app_key, app_keys=app_keys)
 
         @mcp.tool()
         def app_get_charts(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
-            if app_keys:
-                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_charts, data_key="charts", tool_name="app_get_charts")
-            return self.app_get_charts(profile=profile, app_key=app_key)
+            return self.app_get_charts(profile=profile, app_key=app_key, app_keys=app_keys)
 
         @mcp.tool()
         def app_get_buttons(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
-            if app_keys:
-                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_buttons, data_key="buttons", tool_name="app_get_buttons")
-            return self._facade.app_get_buttons(profile=profile, app_key=app_key)
+            return self.app_get_buttons(profile=profile, app_key=app_key, app_keys=app_keys)
 
         @mcp.tool()
         def app_get_associated_resources(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
-            if app_keys:
-                return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_associated_resources, data_key="associated_resources", tool_name="app_get_associated_resources")
-            return self._facade.app_get_associated_resources(profile=profile, app_key=app_key)
+            return self.app_get_associated_resources(profile=profile, app_key=app_key, app_keys=app_keys)
 
         @mcp.tool()
         def portal_list(profile: str = DEFAULT_PROFILE) -> JSONObject:
@@ -384,8 +567,11 @@ class AiBuilderTools(ToolBase):
             package_id: int | None = None,
             app_name: str = "",
             app_title: str = "",
-            icon: str = "",
+            icon: str | JSONObject = "",
             color: str = "",
+            icon_name: str | None = None,
+            icon_color: str | None = None,
+            icon_config: JSONObject | None = None,
             visibility: JSONObject | None = None,
             create_if_missing: bool = False,
             publish: bool = True,
@@ -394,7 +580,7 @@ class AiBuilderTools(ToolBase):
             remove_fields: list[JSONObject] | None = None,
             apps: list[JSONObject] | None = None,
         ) -> JSONObject:
-            if apps:
+            if apps is not None:
                 if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
                     return _config_failure(
                         tool_name="app_schema_apply",
@@ -443,6 +629,9 @@ class AiBuilderTools(ToolBase):
                 app_title=app_title,
                 icon=icon,
                 color=color,
+                icon_name=icon_name,
+                icon_color=icon_color,
+                icon_config=icon_config,
                 visibility=visibility,
                 create_if_missing=create_if_missing,
                 publish=publish,
@@ -469,7 +658,7 @@ class AiBuilderTools(ToolBase):
             app_key: str = "",
             version_id: str = "",
         ) -> JSONObject:
-            return self.app_get_flow(profile=profile, app_key=app_key, version_id=version_id or None)
+            return self.app_flow_get(profile=profile, app_key=app_key, version_id=version_id or None)
 
         @mcp.tool()
         def app_flow_get_schema(profile: str = DEFAULT_PROFILE, schema_version: str = "") -> JSONObject:
@@ -479,7 +668,10 @@ class AiBuilderTools(ToolBase):
         def app_flow_apply(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
+            mode: str = "replace",
             publish: bool = True,
+            nodes: list[JSONObject] | None = None,
+            transitions: list[JSONObject] | None = None,
             spec: JSONObject | None = None,
             idempotency_key: str = "",
             schema_version: str = "",
@@ -488,8 +680,11 @@ class AiBuilderTools(ToolBase):
             return self.app_flow_apply(
                 profile=profile,
                 app_key=app_key,
+                mode=mode,
                 publish=publish,
-                spec=spec or {},
+                nodes=nodes or [],
+                transitions=transitions or [],
+                spec=spec,
                 idempotency_key=idempotency_key or None,
                 schema_version=schema_version or None,
                 patch_nodes=patch_nodes,
@@ -595,6 +790,13 @@ class AiBuilderTools(ToolBase):
                 patch_sections=patch_sections,
             )
 
+        @mcp.tool(description=self._high_risk_tool_description(operation="delete", target="portal"))
+        def portal_delete(
+            profile: str = DEFAULT_PROFILE,
+            dash_key: str = "",
+        ) -> JSONObject:
+            return self.portal_delete(profile=profile, dash_key=dash_key)
+
         @mcp.tool()
         def app_publish_verify(
             profile: str = DEFAULT_PROFILE,
@@ -602,17 +804,10 @@ class AiBuilderTools(ToolBase):
             app_keys: list[str] | None = None,
             expected_package_id: int | None = None,
         ) -> JSONObject:
-            if app_keys:
-                return self._facade._batch_read_app_keys(
-                    profile=profile,
-                    app_keys=app_keys,
-                    single_reader=lambda profile, app_key: self.app_publish_verify(profile=profile, app_key=app_key, expected_package_id=expected_package_id),
-                    data_key="verification",
-                    tool_name="app_publish_verify",
-                )
             return self.app_publish_verify(
                 profile=profile,
                 app_key=app_key,
+                app_keys=app_keys,
                 expected_package_id=expected_package_id,
             )
 
@@ -661,15 +856,16 @@ class AiBuilderTools(ToolBase):
                 "allowed_values": {"tool_name": public_tool_names},
                 "details": {"reason_path": "tool_name"},
                 "suggested_next_call": None,
-            "request_id": None,
-            "backend_code": None,
-            "http_status": None,
-            "noop": False,
-            "warnings": [],
-            "verification": {},
-            "verified": False,
-        }
+                "request_id": None,
+                "backend_code": None,
+                "http_status": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {},
+                "verified": False,
+            }
         contract = _builder_contract_with_apply_output(lookup_name, contract)
+        contract_summary = _builder_tool_contract_summary(lookup_name, contract)
         return {
             "status": "success",
             "error_code": None,
@@ -688,6 +884,8 @@ class AiBuilderTools(ToolBase):
             "verification": {},
             "verified": True,
             "tool_name": requested,
+            "summary": contract_summary,
+            "json_paths": contract_summary["json_paths"],
             "contract": contract,
         }
 
@@ -710,6 +908,12 @@ class AiBuilderTools(ToolBase):
             "color_count": len(catalog["icon_colors"]),
             "warnings": [],
             "verification": {"source": "backend AiBuildConstant ICON_NAMES/ICON_COLORS"},
+            "json_paths": {
+                "icon_names": "$.icon_names",
+                "icon_colors": "$.icon_colors",
+                "generic_icon_names": "$.generic_icon_names",
+                "common_examples": "$.common_examples",
+            },
         }
 
     @tool_cn_name("分组创建")
@@ -776,13 +980,23 @@ class AiBuilderTools(ToolBase):
         package_id: int | None = None,
         package_name: str | None = None,
         create_if_missing: bool = False,
-        icon: str | None = None,
+        icon: str | JSONObject | None = None,
         color: str | None = None,
+        icon_name: str | None = None,
+        icon_color: str | None = None,
+        icon_config: JSONObject | None = None,
         visibility: JSONObject | None = None,
         items: list[dict] | None = None,
         allow_detach: bool = False,
     ) -> JSONObject:
         """执行分组与包相关逻辑。"""
+        icon, color = _normalize_builder_icon_args(
+            icon=icon,
+            color=color,
+            icon_name=icon_name,
+            icon_color=icon_color,
+            icon_config=icon_config,
+        )
         visibility_patch = None
         if visibility is not None:
             try:
@@ -905,16 +1119,23 @@ class AiBuilderTools(ToolBase):
         contain_disable: bool = False,
     ) -> JSONObject:
         """执行工具方法逻辑。"""
+        normalized_query = str(query or "").strip()
         normalized_args = {
-            "query": query,
+            "query": normalized_query,
             "page_num": page_num,
             "page_size": page_size,
             "contain_disable": contain_disable,
         }
+        if not normalized_query:
+            return _config_failure(
+                tool_name="member_search",
+                message="query is required for member_search; builder member lookup is a contact-directory path, not a record candidate fallback.",
+                fix_hint="For record member/department field ambiguity, use record member-candidates / department-candidates instead.",
+            )
         return _safe_tool_call(
             lambda: self._facade.member_search(
                 profile=profile,
-                query=query,
+                query=normalized_query,
                 page_num=page_num,
                 page_size=page_size,
                 contain_disable=contain_disable,
@@ -927,9 +1148,16 @@ class AiBuilderTools(ToolBase):
     @tool_cn_name("角色检索")
     def role_search(self, *, profile: str, keyword: str, page_num: int = 1, page_size: int = 20) -> JSONObject:
         """执行角色相关逻辑。"""
-        normalized_args = {"keyword": keyword, "page_num": page_num, "page_size": page_size}
+        normalized_keyword = str(keyword or "").strip()
+        normalized_args = {"keyword": normalized_keyword, "page_num": page_num, "page_size": page_size}
+        if not normalized_keyword:
+            return _config_failure(
+                tool_name="role_search",
+                message="keyword is required for role_search; builder role lookup is a contact-management path, not a record candidate fallback.",
+                fix_hint="For record member/department field ambiguity, use record member-candidates / department-candidates instead.",
+            )
         return _safe_tool_call(
-            lambda: self._facade.role_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size),
+            lambda: self._facade.role_search(profile=profile, keyword=normalized_keyword, page_num=page_num, page_size=page_size),
             error_code="ROLE_SEARCH_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, **normalized_args}},
@@ -1058,19 +1286,20 @@ class AiBuilderTools(ToolBase):
         apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用按钮 apply 逻辑。"""
-        if apps:
-            return self._facade._batch_write_apps(
+        if apps is not None:
+            return self._apply_app_batch(
+                tool_name="app_custom_buttons_apply",
                 profile=profile,
                 apps=apps,
-                single_writer=lambda profile, app_key, **kw: self.app_custom_buttons_apply(
+                apply_one=lambda _index, item, item_app_key: self.app_custom_buttons_apply(
                     profile=profile,
-                    app_key=app_key,
-                    upsert_buttons=kw.get("upsert_buttons", []),
-                    patch_buttons=kw.get("patch_buttons", []),
-                    remove_buttons=kw.get("remove_buttons", []),
-                    view_configs=kw.get("view_configs", []),
+                    app_key=item_app_key,
+                    upsert_buttons=_payload_list(item, "upsert_buttons", "upsertButtons", "buttons", default=upsert_buttons or []),
+                    patch_buttons=_payload_list(item, "patch_buttons", "patchButtons", default=patch_buttons or []),
+                    remove_buttons=_payload_list(item, "remove_buttons", "removeButtons", default=remove_buttons or []),
+                    view_configs=_payload_list(item, "view_configs", "viewConfigs", default=view_configs or []),
+                    apps=None,
                 ),
-                tool_name="app_custom_buttons_apply",
             )
         raw_request = {
             "app_key": app_key,
@@ -1127,20 +1356,31 @@ class AiBuilderTools(ToolBase):
         apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用关联资源 apply 逻辑。"""
-        if apps:
-            return self._facade._batch_write_apps(
+        if apps is not None:
+            return self._apply_app_batch(
+                tool_name="app_associated_resources_apply",
                 profile=profile,
                 apps=apps,
-                single_writer=lambda profile, app_key, **kw: self.app_associated_resources_apply(
+                apply_one=lambda _index, item, item_app_key: self.app_associated_resources_apply(
                     profile=profile,
-                    app_key=app_key,
-                    upsert_resources=kw.get("upsert_resources", []),
-                    patch_resources=kw.get("patch_resources", []),
-                    remove_associated_item_ids=kw.get("remove_associated_item_ids", []),
-                    reorder_associated_item_ids=kw.get("reorder_associated_item_ids", []),
-                    view_configs=kw.get("view_configs", []),
+                    app_key=item_app_key,
+                    upsert_resources=_payload_list(item, "upsert_resources", "upsertResources", "resources", default=upsert_resources or []),
+                    patch_resources=_payload_list(item, "patch_resources", "patchResources", default=patch_resources or []),
+                    remove_associated_item_ids=_payload_list(
+                        item,
+                        "remove_associated_item_ids",
+                        "removeAssociatedItemIds",
+                        default=remove_associated_item_ids or [],
+                    ),
+                    reorder_associated_item_ids=_payload_list(
+                        item,
+                        "reorder_associated_item_ids",
+                        "reorderAssociatedItemIds",
+                        default=reorder_associated_item_ids or [],
+                    ),
+                    view_configs=_payload_list(item, "view_configs", "viewConfigs", default=view_configs or []),
+                    apps=None,
                 ),
-                tool_name="app_associated_resources_apply",
             )
         raw_request = {
             "app_key": app_key,
@@ -1304,11 +1544,14 @@ class AiBuilderTools(ToolBase):
         ))
 
     @tool_cn_name("应用详情查询")
-    def app_get(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+    def app_get(self, *, profile: str, app_key: str, app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
-        if app_keys:
-            return _publicize_package_fields(
-                self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get, data_key="summary", tool_name="app_get")
+        if app_keys is not None:
+            return self._read_app_batch(
+                tool_name="app_get",
+                profile=profile,
+                app_keys=app_keys,
+                read_one=lambda item_app_key: self.app_get(profile=profile, app_key=item_app_key, app_keys=None),
             )
         normalized_args = {"app_key": app_key}
         return _publicize_package_fields(_safe_tool_call(
@@ -1330,10 +1573,15 @@ class AiBuilderTools(ToolBase):
         )
 
     @tool_cn_name("应用字段详情查询")
-    def app_get_fields(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+    def app_get_fields(self, *, profile: str, app_key: str, app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
-        if app_keys:
-            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_fields, data_key="fields", tool_name="app_get_fields")
+        if app_keys is not None:
+            return self._read_app_batch(
+                tool_name="app_get_fields",
+                profile=profile,
+                app_keys=app_keys,
+                read_one=lambda item_app_key: self.app_get_fields(profile=profile, app_key=item_app_key, app_keys=None),
+            )
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_fields(profile=profile, app_key=app_key),
@@ -1372,10 +1620,15 @@ class AiBuilderTools(ToolBase):
         )
 
     @tool_cn_name("应用布局详情查询")
-    def app_get_layout(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+    def app_get_layout(self, *, profile: str, app_key: str, app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
-        if app_keys:
-            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_layout, data_key="sections", tool_name="app_get_layout")
+        if app_keys is not None:
+            return self._read_app_batch(
+                tool_name="app_get_layout",
+                profile=profile,
+                app_keys=app_keys,
+                read_one=lambda item_app_key: self.app_get_layout(profile=profile, app_key=item_app_key, app_keys=None),
+            )
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_layout(profile=profile, app_key=app_key),
@@ -1396,10 +1649,15 @@ class AiBuilderTools(ToolBase):
         )
 
     @tool_cn_name("应用视图详情查询")
-    def app_get_views(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+    def app_get_views(self, *, profile: str, app_key: str, app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
-        if app_keys:
-            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_views, data_key="views", tool_name="app_get_views")
+        if app_keys is not None:
+            return self._read_app_batch(
+                tool_name="app_get_views",
+                profile=profile,
+                app_keys=app_keys,
+                read_one=lambda item_app_key: self.app_get_views(profile=profile, app_key=item_app_key, app_keys=None),
+            )
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_views(profile=profile, app_key=app_key),
@@ -1408,27 +1666,53 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
-    @tool_cn_name("Workflow Spec Schema")
-    def app_flow_get_schema(self, *, profile: str, schema_version: str | None = None) -> JSONObject:
-        normalized_args = {"schema_version": schema_version}
+    @tool_cn_name("应用流程摘要读取")
+    def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
+        """执行应用相关逻辑。"""
+        normalized_args = {"app_key": app_key}
         return _safe_tool_call(
-            lambda: self._facade.flow_get_schema(profile=profile, schema_version=schema_version),
-            error_code="FLOW_SPEC_SCHEMA_FAILED",
+            lambda: self._facade.app_read_flow_summary(profile=profile, app_key=app_key),
+            error_code="FLOW_READ_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile, **normalized_args}},
+            suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
-    @tool_cn_name("Workflow Spec 读取")
-    def app_get_flow(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None, version_id: str | None = None) -> JSONObject:
+    @tool_cn_name("应用流程详情查询")
+    def app_get_flow(self, *, profile: str, app_key: str, app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
-        if app_keys:
-            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_flow, data_key="spec", tool_name="app_get_flow")
+        if app_keys is not None:
+            return self._read_app_batch(
+                tool_name="app_get_flow",
+                profile=profile,
+                app_keys=app_keys,
+                read_one=lambda item_app_key: self.app_get_flow(profile=profile, app_key=item_app_key, app_keys=None),
+            )
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.app_get_flow(profile=profile, app_key=app_key),
+            error_code="APP_GET_FLOW_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    @tool_cn_name("应用流程规格查询")
+    def app_flow_get(self, *, profile: str, app_key: str, version_id: str | None = None) -> JSONObject:
         normalized_args = {"app_key": app_key, "version_id": version_id}
         return _safe_tool_call(
             lambda: self._facade.flow_get(profile=profile, app_key=app_key, version_id=version_id),
-            error_code="APP_GET_FLOW_FAILED",
+            error_code="APP_FLOW_GET_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
+            suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("应用流程规格 Schema 查询")
+    def app_flow_get_schema(self, *, profile: str, schema_version: str | None = None) -> JSONObject:
+        normalized_args = {"schema_version": schema_version}
+        return _safe_tool_call(
+            lambda: self._facade.flow_get_schema(profile=profile, schema_version=schema_version),
+            error_code="APP_FLOW_SCHEMA_GET_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile, **normalized_args}},
         )
 
     @tool_cn_name("应用图表摘要读取")
@@ -1443,10 +1727,15 @@ class AiBuilderTools(ToolBase):
         )
 
     @tool_cn_name("应用图表详情查询")
-    def app_get_charts(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
+    def app_get_charts(self, *, profile: str, app_key: str, app_keys: list[str] | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
-        if app_keys:
-            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_charts, data_key="charts", tool_name="app_get_charts")
+        if app_keys is not None:
+            return self._read_app_batch(
+                tool_name="app_get_charts",
+                profile=profile,
+                app_keys=app_keys,
+                read_one=lambda item_app_key: self.app_get_charts(profile=profile, app_key=item_app_key, app_keys=None),
+            )
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_charts(profile=profile, app_key=app_key),
@@ -1457,9 +1746,13 @@ class AiBuilderTools(ToolBase):
 
     @tool_cn_name("自定义按钮读取")
     def app_get_buttons(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
-        """执行按钮相关逻辑。"""
-        if app_keys:
-            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_buttons, data_key="buttons", tool_name="app_get_buttons")
+        if app_keys is not None:
+            return self._read_app_batch(
+                tool_name="app_get_buttons",
+                profile=profile,
+                app_keys=app_keys,
+                read_one=lambda item_app_key: self.app_get_buttons(profile=profile, app_key=item_app_key, app_keys=None),
+            )
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_buttons(profile=profile, app_key=app_key),
@@ -1470,9 +1763,13 @@ class AiBuilderTools(ToolBase):
 
     @tool_cn_name("关联资源读取")
     def app_get_associated_resources(self, *, profile: str, app_key: str = "", app_keys: list[str] | None = None) -> JSONObject:
-        """执行关联资源相关逻辑。"""
-        if app_keys:
-            return self._facade._batch_read_app_keys(profile=profile, app_keys=app_keys, single_reader=self._facade.app_get_associated_resources, data_key="associated_resources", tool_name="app_get_associated_resources")
+        if app_keys is not None:
+            return self._read_app_batch(
+                tool_name="app_get_associated_resources",
+                profile=profile,
+                app_keys=app_keys,
+                read_one=lambda item_app_key: self.app_get_associated_resources(profile=profile, app_key=item_app_key, app_keys=None),
+            )
         normalized_args = {"app_key": app_key}
         return _safe_tool_call(
             lambda: self._facade.app_get_associated_resources(profile=profile, app_key=app_key),
@@ -1558,6 +1855,22 @@ class AiBuilderTools(ToolBase):
         remove_fields: list[JSONObject],
     ) -> JSONObject:
         """执行应用相关逻辑。"""
+        system_field_failure = _reserved_system_field_name_failure(
+            tool_name="app_schema_plan",
+            profile=profile,
+            app_key=app_key,
+            package_id=package_id,
+            app_name=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,
+        )
+        if system_field_failure is not None:
+            return system_field_failure
         try:
             request = SchemaPlanRequest.model_validate(
                 {
@@ -1651,6 +1964,52 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **normalized_request}},
         )
 
+    @tool_cn_name("应用流程规划")
+    def app_flow_plan(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        mode: str = "replace",
+        nodes: list[JSONObject] | None = None,
+        transitions: list[JSONObject] | None = None,
+        preset: str | None = None,
+    ) -> JSONObject:
+        """执行应用相关逻辑。"""
+        try:
+            request = FlowPlanRequest.model_validate(
+                {
+                    "app_key": app_key,
+                    "mode": mode,
+                    "nodes": nodes or [],
+                    "transitions": transitions or [],
+                    "preset": preset,
+                }
+            )
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_flow_plan",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_flow_plan",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key,
+                        "mode": "replace",
+                        "preset": "basic_approval",
+                        "nodes": [],
+                        "transitions": [],
+                    },
+                },
+            )
+        return _safe_tool_call(
+            lambda: self._facade.app_flow_plan(profile=profile, request=request),
+            error_code="FLOW_PLAN_FAILED",
+            normalized_args=request.model_dump(mode="json"),
+            suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+        )
+
     @tool_cn_name("应用视图规划")
     def app_views_plan(
         self,
@@ -1662,6 +2021,15 @@ class AiBuilderTools(ToolBase):
         preset: str | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
+        reserved_failure = _reserved_system_view_name_failure(
+            tool_name="app_views_plan",
+            profile=profile,
+            app_key=app_key,
+            upsert_views=upsert_views,
+            remove_views=remove_views,
+        )
+        if reserved_failure is not None:
+            return reserved_failure
         try:
             request = ViewsPlanRequest.model_validate(
                 {
@@ -1703,8 +2071,11 @@ class AiBuilderTools(ToolBase):
         package_id: int | None = None,
         app_name: str = "",
         app_title: str = "",
-        icon: str = "",
+        icon: str | JSONObject = "",
         color: str = "",
+        icon_name: str | None = None,
+        icon_color: str | None = None,
+        icon_config: JSONObject | None = None,
         visibility: JSONObject | None = None,
         create_if_missing: bool = False,
         publish: bool = True,
@@ -1714,7 +2085,25 @@ class AiBuilderTools(ToolBase):
         apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
-        if apps:
+        icon, color = _normalize_builder_icon_args(
+            icon=icon,
+            color=color,
+            icon_name=icon_name,
+            icon_color=icon_color,
+            icon_config=icon_config,
+        )
+        if apps is not None:
+            normalized_apps_payload = _normalize_schema_apps_argument(
+                tool_name="app_schema_apply",
+                package_id=package_id,
+                apps=apps,
+            )
+            failure = normalized_apps_payload.get("failure")
+            if isinstance(failure, dict):
+                return _attach_builder_apply_envelope("app_schema_apply", failure)
+            package_id = normalized_apps_payload.get("package_id")  # type: ignore[assignment]
+            apps = normalized_apps_payload.get("apps")  # type: ignore[assignment]
+            input_warnings = list(normalized_apps_payload.get("warnings") or [])
             result = self._app_schema_apply_multi(
                 profile=profile,
                 package_id=package_id,
@@ -1723,6 +2112,10 @@ class AiBuilderTools(ToolBase):
                 publish=publish,
                 apps=apps,
             )
+            if input_warnings:
+                result_warnings = list(result.get("warnings") or [])
+                result_warnings.extend(deepcopy(input_warnings))
+                result["warnings"] = result_warnings
             return _attach_builder_apply_envelope("app_schema_apply", result)
         result = self._app_schema_apply_once(
             profile=profile,
@@ -1778,6 +2171,17 @@ class AiBuilderTools(ToolBase):
         }
         if visibility is not None:
             normalized_args["visibility"] = deepcopy(visibility)
+        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
         if package_id is None:
             return _config_failure(
                 tool_name="app_schema_apply",
@@ -1787,9 +2191,20 @@ class AiBuilderTools(ToolBase):
         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.",
             )
+        shape_failure = _schema_apps_shape_failure(tool_name="app_schema_apply", apps=apps)
+        if shape_failure is not None:
+            return 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
         icon_errors: list[JSONObject] = []
         seen_new_app_icons: dict[str, int] = {}
         for index, raw_item in enumerate(apps):
@@ -1854,9 +2269,13 @@ class AiBuilderTools(ToolBase):
             )
 
         client_key_to_app_key: dict[str, str] = {}
+        app_name_to_app_key: dict[str, str] = {}
         created_app_keys: list[str] = []
         results: 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()
 
         for index, raw_item in enumerate(apps):
@@ -1895,31 +2314,58 @@ class AiBuilderTools(ToolBase):
             )
             public_shell = _publicize_package_fields(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)
+            if shell_write_executed:
+                any_write_executed = True
+            if shell_write_may_have_succeeded:
+                any_write_may_have_succeeded = True
             if public_shell.get("status") not in {"success", "partial_success"} or not resolved_key:
+                pending_readback = bool(shell_write_may_have_succeeded or shell_write_executed) and (
+                    str(public_shell.get("next_action") or "") == "readback_before_retry"
+                    or bool((public_shell.get("verification") if isinstance(public_shell.get("verification"), dict) else {}).get("readback_before_retry"))
+                    or not resolved_key
+                )
+                item_status = "pending_readback" if pending_readback else "failed"
+                if pending_readback:
+                    if resolved_key:
+                        pending_readback_app_keys.append(resolved_key)
+                    if app_name:
+                        pending_readback_app_names.append(app_name)
                 results.append({
                     "index": index,
                     "row_number": index + 1,
                     "client_key": client_key or None,
                     "app_name": app_name or None,
                     "app_key": resolved_key or app_key or None,
-                    "status": "failed",
+                    "status": item_status,
                     "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,
+                    "write_executed": shell_write_executed,
+                    "write_may_have_succeeded": bool(shell_write_may_have_succeeded or shell_write_executed),
+                    "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 {}),
                 })
                 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 shell_write_may_have_succeeded and str(public_shell.get("next_action") or "") == "readback_before_retry":
+                pending_readback_app_keys.append(resolved_key)
+                if app_name:
+                    pending_readback_app_names.append(app_name)
             if client_key:
                 client_key_to_app_key[client_key] = resolved_key
+            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({
                 "index": index,
                 "row_number": index + 1,
                 "client_key": client_key or None,
-                "app_name": str(public_shell.get("app_name_after") or public_shell.get("app_name") or app_name or "").strip() or None,
+                "app_name": resolved_name or None,
                 "app_key": resolved_key,
                 "status": "shell_ready",
                 "created": bool(public_shell.get("created")),
@@ -1939,7 +2385,7 @@ class AiBuilderTools(ToolBase):
             item = deepcopy(raw_item)
             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(item, client_key_to_app_key, app_name_to_app_key)
             except ValueError as error:
                 final_items.append({
                     **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
@@ -1976,7 +2422,11 @@ class AiBuilderTools(ToolBase):
                     "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),
                     "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 {}),
                 })
                 continue
 
@@ -1998,11 +2448,18 @@ class AiBuilderTools(ToolBase):
             public_result = _publicize_package_fields(field_result)
             if _schema_apply_result_has_write(public_result):
                 any_write_executed = True
+            if _schema_apply_result_may_have_write(public_result):
+                any_write_may_have_succeeded = 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 {})
+            if _schema_apply_result_may_have_write(public_result) and str(public_result.get("next_action") or "") == "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")))
             final_items.append({
                 **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
                 "status": item_status,
@@ -2015,55 +2472,33 @@ class AiBuilderTools(ToolBase):
                 "verified": bool(public_result.get("verified")),
                 "error_code": public_result.get("error_code"),
                 "message": public_result.get("message"),
+                "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,
+                **({"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 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")
-
+        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 = len(final_items) - succeeded
-        overall_status = "success" if failed == 0 else ("partial_success" if succeeded > 0 or any_write_executed else "failed")
-        return {
+        failed = sum(1 for item in final_items if item.get("status") == "failed")
+        partial = sum(1 for item in final_items if item.get("status") == "partial_success")
+        overall_status = (
+            "success"
+            if failed == 0 and pending_readback == 0 and partial == 0
+            else ("partial_success" if succeeded > 0 or pending_readback > 0 or any_write_executed or any_write_may_have_succeeded else "failed")
+        )
+        uncertain_write = any_write_may_have_succeeded or pending_readback > 0
+        response: JSONObject = {
             "status": overall_status,
             "mode": "multi_app",
             "total": len(apps),
             "succeeded": succeeded,
             "failed": failed,
+            "pending_readback": pending_readback,
             "created_app_keys": created_app_keys,
             "write_executed": any_write_executed,
-            "safe_to_retry": not any_write_executed,
+            "safe_to_retry": not (any_write_executed or uncertain_write),
             "package_id": package_id,
             "publish_requested": publish,
             "apps": final_items,
@@ -2071,12 +2506,23 @@ class AiBuilderTools(ToolBase):
             "verification": {
                 "all_apps_succeeded": failed == 0,
                 "created_app_count": len(created_app_keys),
+                "pending_readback_count": pending_readback,
             },
             "request_id": None,
             "error_code": None if overall_status != "failed" else "MULTI_APP_SCHEMA_APPLY_FAILED",
             "recoverable": overall_status != "success",
-            "message": "multi-app schema apply completed" if overall_status != "failed" else "multi-app schema apply failed",
+            "message": (
+                "multi-app schema apply needs readback before retry"
+                if pending_readback > 0
+                else ("multi-app schema apply completed" if overall_status != "failed" else "multi-app schema apply failed")
+            ),
         }
+        if uncertain_write:
+            response["write_may_have_succeeded"] = True
+            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
 
     def _app_schema_apply_once(
         self,
@@ -2097,6 +2543,23 @@ class AiBuilderTools(ToolBase):
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
         effective_app_name = app_name or app_title
+        system_field_failure = _reserved_system_field_name_failure(
+            tool_name="app_schema_apply",
+            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,
+            publish=publish,
+            add_fields=add_fields,
+            update_fields=update_fields,
+            remove_fields=remove_fields,
+        )
+        if system_field_failure is not None:
+            return system_field_failure
         icon_failure = _validate_workspace_icon_for_builder(
             tool_name="app_schema_apply",
             icon=icon,
@@ -2191,20 +2654,30 @@ class AiBuilderTools(ToolBase):
         return _publicize_package_fields(result)
 
     @tool_cn_name("应用布局应用")
-    def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject], apps: list[JSONObject] | None = None) -> JSONObject:
+    def app_layout_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        mode: str = "merge",
+        publish: bool = True,
+        sections: list[JSONObject],
+        apps: list[JSONObject] | None = None,
+    ) -> JSONObject:
         """执行应用相关逻辑。"""
-        if apps:
-            return self._facade._batch_write_apps(
+        if apps is not None:
+            return self._apply_app_batch(
+                tool_name="app_layout_apply",
                 profile=profile,
                 apps=apps,
-                single_writer=lambda profile, app_key, **kw: self.app_layout_apply(
+                apply_one=lambda _index, item, item_app_key: self.app_layout_apply(
                     profile=profile,
-                    app_key=app_key,
-                    mode=kw.get("mode", mode),
-                    publish=kw.get("publish", publish),
-                    sections=kw.get("sections", []),
+                    app_key=item_app_key,
+                    mode=str(_payload_get(item, "mode", default=mode) or mode),
+                    publish=_payload_bool(item, "publish", default=publish),
+                    sections=_payload_list(item, "sections", default=sections or []),
+                    apps=None,
                 ),
-                tool_name="app_layout_apply",
             )
         result = self._app_layout_apply_once(
             profile=profile,
@@ -2290,15 +2763,25 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        spec: JSONObject,
+        mode: str = "replace",
         publish: bool = True,
+        nodes: list[JSONObject] | None = None,
+        transitions: list[JSONObject] | None = None,
+        spec: JSONObject | None = None,
         idempotency_key: str | None = None,
         schema_version: str | None = None,
         patch_nodes: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
-        if patch_nodes:
-            result = _safe_tool_call(
+        if patch_nodes is not None:
+            normalized_args = {
+                "app_key": app_key,
+                "publish": publish,
+                "patch_nodes": patch_nodes,
+                "idempotency_key": idempotency_key,
+                "schema_version": schema_version,
+            }
+            return _attach_builder_apply_envelope("app_flow_apply", _safe_tool_call(
                 lambda: self._facade.flow_patch_nodes(
                     profile=profile,
                     app_key=app_key,
@@ -2307,50 +2790,132 @@ class AiBuilderTools(ToolBase):
                     idempotency_key=idempotency_key,
                     schema_version=schema_version,
                 ),
-                error_code="FLOW_APPLY_FAILED",
-                normalized_args={"app_key": app_key, "patch_nodes": patch_nodes, "publish": publish},
-                suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, "app_key": app_key, "patch_nodes": patch_nodes}},
+                error_code="FLOW_PATCH_FAILED",
+                normalized_args=normalized_args,
+                suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
+            ))
+        if spec is not None:
+            normalized_args = {
+                "app_key": app_key,
+                "publish": publish,
+                "spec": spec,
+                "idempotency_key": idempotency_key,
+                "schema_version": schema_version,
+            }
+            return _attach_builder_apply_envelope("app_flow_apply", _safe_tool_call(
+                lambda: self._facade.flow_apply(
+                    profile=profile,
+                    app_key=app_key,
+                    spec=spec,
+                    publish=publish,
+                    idempotency_key=idempotency_key,
+                    schema_version=schema_version,
+                ),
+                error_code="FLOW_SPEC_APPLY_FAILED",
+                normalized_args=normalized_args,
+                suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
+            ))
+        effective_nodes = nodes or []
+        effective_transitions = transitions or []
+        result = self._app_flow_apply_once(
+            profile=profile,
+            app_key=app_key,
+            mode=mode,
+            publish=publish,
+            nodes=effective_nodes,
+            transitions=effective_transitions,
+        )
+        result = self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._app_flow_apply_once(
+                profile=profile,
+                app_key=app_key,
+                mode=mode,
+                publish=publish,
+                nodes=effective_nodes,
+                transitions=effective_transitions,
+            ),
+        )
+        return _attach_builder_apply_envelope("app_flow_apply", result)
+
+    def _app_flow_apply_once(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        mode: str = "replace",
+        publish: bool = True,
+        nodes: list[JSONObject],
+        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 [],
+                    "preset": None,
+                }
             )
-            return _attach_builder_apply_envelope("app_flow_apply", result)
-        if not isinstance(spec, dict) or not spec:
-            return _config_failure(
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
                 tool_name="app_flow_apply",
-                message="app_flow_apply requires a non-empty WorkflowSpecDTO `spec` object.",
-                fix_hint="Call app_flow_get_schema, then app_flow_get for GET-first baseline, patch spec, and apply.",
+                exc=exc,
+                suggested_next_call={
+                    "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"),
+                        "publish": publish,
+                        "nodes": plan_args.get("nodes") or [{"id": "start", "type": "start", "name": "发起"}],
+                        "transitions": plan_args.get("transitions") or [],
+                    },
+                },
             )
         normalized_args = {
-            "app_key": app_key,
+            "app_key": request.app_key,
+            "mode": request.mode,
             "publish": publish,
-            "spec": spec,
-            "idempotency_key": idempotency_key,
-            "schema_version": schema_version,
+            "nodes": [node.model_dump(mode="json") for node in request.nodes],
+            "transitions": [transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
         }
-        result = _safe_tool_call(
-            lambda: self._facade.flow_apply(
+        return _safe_tool_call(
+            lambda: self._facade.app_flow_apply(
                 profile=profile,
-                app_key=app_key,
-                spec=spec,
+                app_key=request.app_key,
+                mode=request.mode,
                 publish=publish,
-                idempotency_key=idempotency_key,
-                schema_version=schema_version,
+                nodes=[node.model_dump(mode="json") for node in request.nodes],
+                transitions=[transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
             ),
             error_code="FLOW_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
         )
-        result = self._retry_after_self_lock_release(
-            profile=profile,
-            result=result,
-            retry_call=lambda: self._facade.flow_apply(
-                profile=profile,
-                app_key=app_key,
-                spec=spec,
-                publish=publish,
-                idempotency_key=idempotency_key,
-                schema_version=schema_version,
-            ),
-        )
-        return _attach_builder_apply_envelope("app_flow_apply", result)
 
     @tool_cn_name("应用视图应用")
     def app_views_apply(
@@ -2365,19 +2930,20 @@ class AiBuilderTools(ToolBase):
         apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
-        if apps:
-            return self._facade._batch_write_apps(
+        if apps is not None:
+            return self._apply_app_batch(
+                tool_name="app_views_apply",
                 profile=profile,
                 apps=apps,
-                single_writer=lambda profile, app_key, **kw: self.app_views_apply(
+                apply_one=lambda _index, item, item_app_key: self.app_views_apply(
                     profile=profile,
-                    app_key=app_key,
-                    publish=kw.get("publish", publish),
-                    upsert_views=kw.get("upsert_views", []),
-                    patch_views=kw.get("patch_views", []),
-                    remove_views=kw.get("remove_views", []),
+                    app_key=item_app_key,
+                    publish=_payload_bool(item, "publish", default=publish),
+                    upsert_views=_payload_list(item, "upsert_views", "upsertViews", "views", default=upsert_views or []),
+                    patch_views=_payload_list(item, "patch_views", "patchViews", default=patch_views or []),
+                    remove_views=_payload_list(item, "remove_views", "removeViews", default=remove_views or []),
+                    apps=None,
                 ),
-                tool_name="app_views_apply",
             )
         result = self._app_views_apply_once(
             profile=profile,
@@ -2412,6 +2978,17 @@ class AiBuilderTools(ToolBase):
         remove_views: list[str],
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
+        reserved_failure = _reserved_system_view_name_failure(
+            tool_name="app_views_apply",
+            profile=profile,
+            app_key=app_key,
+            publish=publish,
+            upsert_views=upsert_views,
+            patch_views=patch_views,
+            remove_views=remove_views,
+        )
+        if reserved_failure is not None:
+            return reserved_failure
         if patch_views:
             try:
                 parsed_views = [ViewUpsertPatch.model_validate(item) for item in (upsert_views or [])]
@@ -2486,7 +3063,7 @@ class AiBuilderTools(ToolBase):
                         "profile": profile,
                         "app_key": str(plan_args.get("app_key") or app_key),
                         "publish": publish,
-                        "upsert_views": plan_args.get("upsert_views") or [{"name": "全部数据", "type": "table", "columns": ["字段A"]}],
+                        "upsert_views": plan_args.get("upsert_views") or [{"name": "业务台账视图", "type": "table", "columns": ["字段A"]}],
                         "remove_views": plan_args.get("remove_views") or [],
                     },
                 },
@@ -2545,19 +3122,20 @@ class AiBuilderTools(ToolBase):
         apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
-        if apps:
-            return self._facade._batch_write_apps(
+        if apps is not None:
+            return self._apply_app_batch(
+                tool_name="app_charts_apply",
                 profile=profile,
                 apps=apps,
-                single_writer=lambda profile, app_key, **kw: self.app_charts_apply(
+                apply_one=lambda _index, item, item_app_key: self.app_charts_apply(
                     profile=profile,
-                    app_key=app_key,
-                    upsert_charts=kw.get("upsert_charts", []),
-                    patch_charts=kw.get("patch_charts", []),
-                    remove_chart_ids=kw.get("remove_chart_ids", []),
-                    reorder_chart_ids=kw.get("reorder_chart_ids", []),
+                    app_key=item_app_key,
+                    upsert_charts=_payload_list(item, "upsert_charts", "upsertCharts", "charts", default=upsert_charts or []),
+                    patch_charts=_payload_list(item, "patch_charts", "patchCharts", default=patch_charts or []),
+                    remove_chart_ids=_payload_list(item, "remove_chart_ids", "removeChartIds", default=remove_chart_ids or []),
+                    reorder_chart_ids=_payload_list(item, "reorder_chart_ids", "reorderChartIds", default=reorder_chart_ids or []),
+                    apps=None,
                 ),
-                tool_name="app_charts_apply",
             )
         try:
             request = ChartApplyRequest.model_validate(
@@ -2577,12 +3155,12 @@ class AiBuilderTools(ToolBase):
                 suggested_next_call={
                     "tool_name": "app_charts_apply",
                     "arguments": {
-                        "profile": profile,
-                        "app_key": app_key,
-                        "upsert_charts": [{"name": "销售总量", "chart_type": "target", "indicator_field_ids": []}],
-                        "remove_chart_ids": [],
-                        "reorder_chart_ids": [],
-                    },
+	                        "profile": profile,
+	                        "app_key": app_key,
+	                        "upsert_charts": [{"name": "销售总量", "chart_type": "target", "metric": "count(*)"}],
+	                        "remove_chart_ids": [],
+	                        "reorder_chart_ids": [],
+	                    },
                 },
             ))
         normalized_args = request.model_dump(mode="json")
@@ -2617,25 +3195,23 @@ class AiBuilderTools(ToolBase):
         patch_sections: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行门户相关逻辑。"""
-        if patch_sections:
-            if not dash_key:
-                return _attach_builder_apply_envelope("portal_apply", _config_failure(
-                    tool_name="portal_apply",
-                    message="patch_sections requires dash_key to identify the portal",
-                    fix_hint="Provide dash_key from portal_list or portal_get",
-                ))
-            result = _safe_tool_call(
+        if patch_sections is not None:
+            normalized_args = {
+                "dash_key": dash_key,
+                "publish": publish,
+                "patch_sections": patch_sections,
+            }
+            return _attach_builder_apply_envelope("portal_apply", _publicize_package_fields(_safe_tool_call(
                 lambda: self._facade.portal_patch_sections(
                     profile=profile,
                     dash_key=dash_key,
                     patch_sections=patch_sections,
                     publish=publish,
                 ),
-                error_code="PORTAL_APPLY_FAILED",
-                normalized_args={"dash_key": dash_key, "patch_sections": patch_sections, "publish": publish},
-                suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, "dash_key": dash_key, "patch_sections": patch_sections}},
-            )
-            return _attach_builder_apply_envelope("portal_apply", result)
+                error_code="PORTAL_PATCH_FAILED",
+                normalized_args=normalized_args,
+                suggested_next_call={"tool_name": "portal_get", "arguments": {"profile": profile, "dash_key": dash_key}},
+            )))
         request_payload: dict[str, Any] = dict(payload) if isinstance(payload, dict) else {}
         if dash_key:
             request_payload["dash_key"] = dash_key
@@ -2712,23 +3288,39 @@ class AiBuilderTools(ToolBase):
         ))
         return _attach_builder_apply_envelope("portal_apply", result)
 
+    @tool_cn_name("门户删除")
+    def portal_delete(self, *, profile: str, dash_key: str) -> JSONObject:
+        """执行门户删除逻辑。"""
+        normalized_args = {"dash_key": dash_key}
+        result = _publicize_package_fields(_safe_tool_call(
+            lambda: self._facade.portal_delete(profile=profile, dash_key=dash_key),
+            error_code="PORTAL_DELETE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "portal_delete", "arguments": {"profile": profile, **normalized_args}},
+        ))
+        return _attach_builder_apply_envelope("portal_delete", result)
+
     @tool_cn_name("应用发布校验")
     def app_publish_verify(
         self,
         *,
         profile: str,
-        app_key: str = "",
+        app_key: str,
         app_keys: list[str] | None = None,
         expected_package_id: int | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
-        if app_keys:
-            return self._facade._batch_read_app_keys(
-                profile=profile,
-                app_keys=app_keys,
-                single_reader=lambda profile, app_key: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_id),
-                data_key="verification",
+        if app_keys is not None:
+            return self._apply_app_batch(
                 tool_name="app_publish_verify",
+                profile=profile,
+                apps=[{"app_key": item, "expected_package_id": expected_package_id} for item in app_keys],
+                apply_one=lambda _index, item, item_app_key: self.app_publish_verify(
+                    profile=profile,
+                    app_key=item_app_key,
+                    app_keys=None,
+                    expected_package_id=item.get("expected_package_id") or item.get("expectedPackageId") or expected_package_id,
+                ),
             )
         normalized_args = {"app_key": app_key, "expected_package_id": expected_package_id}
         result = _publicize_package_fields(_safe_tool_call(
@@ -2862,33 +3454,442 @@ class AiBuilderTools(ToolBase):
                     "tool_name": apply_tool_name,
                     "arguments": {"profile": profile, **normalized_args, "publish": publish},
                 }
-        return rewritten
+        return rewritten
+
+
+def _multi_app_item_failure(index: int, item: object, error_code: str, message: str) -> JSONObject:
+    app_name = None
+    client_key = None
+    app_key = None
+    if isinstance(item, dict):
+        app_name = str(item.get("app_name") or item.get("appTitle") or item.get("app_title") or item.get("title") or "").strip() or None
+        client_key = str(item.get("client_key") or item.get("clientKey") or "").strip() or None
+        app_key = str(item.get("app_key") or item.get("appKey") or "").strip() or None
+    return {
+        "index": index,
+        "row_number": index + 1,
+        "client_key": client_key,
+        "app_name": app_name,
+        "app_key": app_key,
+        "status": "failed",
+        "stage": "validate_item",
+        "error_code": error_code,
+        "message": message,
+        "safe_to_retry": True,
+    }
+
+
+def _normalize_builder_icon_args(
+    *,
+    icon: str | JSONObject | None,
+    color: str | None,
+    icon_name: str | None = None,
+    icon_color: str | None = None,
+    icon_config: JSONObject | None = None,
+) -> tuple[str | None, str | None]:
+    payloads: list[JSONObject] = []
+    if isinstance(icon_config, dict):
+        payloads.append(icon_config)
+    if isinstance(icon, dict):
+        payloads.append(icon)
+
+    normalized_icon = None if isinstance(icon, dict) else icon
+    normalized_color = color
+    for payload in payloads:
+        normalized_icon = normalized_icon or payload.get("icon") or payload.get("icon_name") or payload.get("iconName") or payload.get("name")
+        normalized_color = normalized_color or payload.get("color") or payload.get("icon_color") or payload.get("iconColor")
+    normalized_icon = normalized_icon or icon_name
+    normalized_color = normalized_color or icon_color
+    return (
+        str(normalized_icon).strip() if normalized_icon is not None else None,
+        str(normalized_color).strip() if normalized_color is not None else None,
+    )
+
+
+def _normalize_schema_app_item(item: JSONObject) -> JSONObject:
+    normalized = deepcopy(item)
+    icon, color = _normalize_builder_icon_args(
+        icon=normalized.get("icon"),
+        color=normalized.get("color"),
+        icon_name=normalized.get("icon_name") or normalized.get("iconName"),
+        icon_color=normalized.get("icon_color") or normalized.get("iconColor"),
+        icon_config=normalized.get("icon_config") or normalized.get("iconConfig"),
+    )
+    if icon:
+        normalized["icon"] = icon
+    if color:
+        normalized["color"] = color
+    for key in ("icon_name", "iconName", "icon_color", "iconColor", "icon_config", "iconConfig"):
+        normalized.pop(key, None)
+    return normalized
+
+
+def _schema_apps_expected_shape() -> JSONObject:
+    return {
+        "package_id": 1001,
+        "apps": [
+            {
+                "client_key": "employee",
+                "app_name": "员工花名册",
+                "icon": "business-personalcard",
+                "color": "emerald",
+                "add_fields": [{"name": "员工名称", "type": "text", "as_data_title": True}],
+            }
+        ],
+    }
+
+
+def _schema_apps_expected_shape_json() -> str:
+    return (
+        '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
+        '"icon":"business-personalcard","color":"emerald","add_fields":[{"name":"员工名称","type":"text","as_data_title":true}]}]}'
+    )
+
+
+def _is_schema_apps_wrapper_item(item: object) -> bool:
+    return isinstance(item, dict) and "apps" in item
+
+
+def _schema_apps_shape_failure(*, tool_name: str, apps: list[JSONObject]) -> JSONObject | None:
+    for index, item in enumerate(apps):
+        if _is_schema_apps_wrapper_item(item):
+            return _config_failure(
+                tool_name=tool_name,
+                error_code="APPS_FILE_SHAPE_INVALID",
+                message="apps[] items must be app schema items, not package wrapper objects.",
+                fix_hint=(
+                    "For MCP pass package_id separately and apps=[{app_name, icon, color, add_fields}]. "
+                    'For CLI use --apps-file with {"package_id":1001,"apps":[...]}. '
+                    "Do not pass multiple {package_id, apps} wrapper objects inside apps[]."
+                ),
+                details={
+                    "index": index,
+                    "row_number": index + 1,
+                    "expected_shape": _schema_apps_expected_shape(),
+                    "expected_shape_json": _schema_apps_expected_shape_json(),
+                },
+            )
+    return None
+
+
+def _normalize_schema_apps_argument(*, tool_name: str, package_id: int | None, apps: list[JSONObject]) -> JSONObject:
+    normalized_package_id = package_id
+    normalized_apps: list[JSONObject] = apps
+    warnings: list[JSONObject] = []
+
+    if len(apps) == 1 and _is_schema_apps_wrapper_item(apps[0]):
+        wrapper = apps[0]
+        wrapper_apps = wrapper.get("apps")
+        if not isinstance(wrapper_apps, list):
+            return {
+                "failure": _config_failure(
+                    tool_name=tool_name,
+                    error_code="APPS_FILE_SHAPE_INVALID",
+                    message="apps singleton wrapper requires an apps array.",
+                    fix_hint='Use {"package_id":1001,"apps":[...]} in CLI, or pass MCP package_id=1001 and apps=[...].',
+                    details={
+                        "expected_shape": _schema_apps_expected_shape(),
+                        "expected_shape_json": _schema_apps_expected_shape_json(),
+                    },
+                )
+            }
+        if normalized_package_id is None and wrapper.get("package_id") is not None:
+            try:
+                normalized_package_id = int(wrapper.get("package_id"))
+            except (TypeError, ValueError):
+                return {
+                    "failure": _config_failure(
+                        tool_name=tool_name,
+                        error_code="APPS_FILE_SHAPE_INVALID",
+                        message="apps singleton wrapper package_id must be an integer.",
+                        fix_hint="Pass package_id as a number at the top level.",
+                        details={
+                            "expected_shape": _schema_apps_expected_shape(),
+                            "expected_shape_json": _schema_apps_expected_shape_json(),
+                        },
+                    )
+                }
+        normalized_apps = wrapper_apps
+        warnings.append(
+            {
+                "code": "APPS_FILE_WRAPPER_ARRAY_UNWRAPPED",
+                "message": "apps was a singleton wrapper array; normalized it to package_id + apps.",
+            }
+        )
+    else:
+        failure = _schema_apps_shape_failure(tool_name=tool_name, apps=apps)
+        if failure is not None:
+            return {"failure": failure}
+
+    normalized_items: list[JSONObject] = []
+    for item in normalized_apps:
+        normalized_items.append(_normalize_schema_app_item(item) if isinstance(item, dict) else item)
+    return {"package_id": normalized_package_id, "apps": normalized_items, "warnings": warnings}
+
+
+def _multi_app_item_app_name(item: JSONObject) -> str:
+    return str(item.get("app_name") or item.get("appName") or item.get("appTitle") or item.get("app_title") or item.get("title") or "").strip()
+
+
+def _multi_app_item_app_key(item: JSONObject) -> str:
+    return str(item.get("app_key") or item.get("appKey") or "").strip()
+
+
+def _multi_app_item_client_key(item: JSONObject) -> str:
+    return str(item.get("client_key") or item.get("clientKey") or "").strip()
+
+
+def _field_name_for_static_validation(field: JSONObject) -> str:
+    return str(field.get("name") or field.get("title") or field.get("label") or "").strip()
+
+
+def _field_type_for_static_validation(field: JSONObject) -> str:
+    return str(field.get("type") or field.get("type_id") or field.get("typeId") or "").strip()
+
+
+def _is_data_title_field(field: JSONObject) -> bool:
+    return bool(field.get("as_data_title") or field.get("asDataTitle"))
+
+
+def _collect_multi_app_target_refs(value: object, *, path: str) -> list[JSONObject]:
+    refs: list[JSONObject] = []
+    if isinstance(value, list):
+        for index, entry in enumerate(value):
+            refs.extend(_collect_multi_app_target_refs(entry, path=f"{path}[{index}]"))
+        return refs
+    if not isinstance(value, dict):
+        return refs
+    for key, entry in value.items():
+        current_path = f"{path}.{key}"
+        if key in {"target_app_ref", "targetAppRef", "target_app_client_key", "targetAppClientKey"}:
+            refs.append({"kind": "target_app_ref", "value": str(entry or "").strip(), "path": current_path})
+            continue
+        if key in {"target_app", "targetApp"}:
+            refs.append({"kind": "target_app", "value": str(entry or "").strip(), "path": current_path})
+            continue
+        refs.extend(_collect_multi_app_target_refs(entry, path=current_path))
+    return refs
+
+
+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] = {}
+    app_name_indexes: dict[str, list[int]] = {}
+
+    for index, item in enumerate(apps):
+        if not isinstance(item, dict):
+            continue
+        app_name = _multi_app_item_app_name(item)
+        client_key = _multi_app_item_client_key(item)
+        if client_key:
+            first_index = client_key_indexes.get(client_key)
+            if first_index is not None:
+                issues.append(
+                    {
+                        "index": index,
+                        "row_number": index + 1,
+                        "path": f"apps[{index}].client_key",
+                        "error_code": "DUPLICATE_CLIENT_KEY",
+                        "message": f"duplicate client_key '{client_key}' also appears at apps[{first_index}]",
+                        "fix_hint": "Use a unique stable client_key for each app item, then reference relations through target_app_ref.",
+                        "details": {"client_key": client_key, "first_index": first_index, "duplicate_index": index},
+                    }
+                )
+            else:
+                client_key_indexes[client_key] = index
+        if app_name:
+            app_name_indexes.setdefault(app_name, []).append(index)
+
+    for app_name, indexes in sorted(app_name_indexes.items()):
+        if len(indexes) <= 1:
+            continue
+        issues.append(
+            {
+                "index": indexes[1],
+                "row_number": indexes[1] + 1,
+                "path": f"apps[{indexes[1]}].app_name",
+                "error_code": "DUPLICATE_APP_NAME",
+                "message": f"duplicate app_name '{app_name}' appears at apps{indexes}",
+                "fix_hint": "Use unique app_name values in one multi-app payload, or use app_key for existing apps.",
+                "details": {"app_name": app_name, "indexes": indexes},
+            }
+        )
+
+    for index, item in enumerate(apps):
+        if not isinstance(item, dict):
+            continue
+        app_key = _multi_app_item_app_key(item)
+        app_name = _multi_app_item_app_name(item)
+        new_app_item = not bool(app_key)
+        if not app_key and not app_name:
+            issues.append(
+                {
+                    "index": index,
+                    "row_number": index + 1,
+                    "path": f"apps[{index}]",
+                    "error_code": "APP_SELECTOR_REQUIRED",
+                    "message": "apps[] item requires app_key or app_name",
+                    "fix_hint": "For new apps pass app_name; for existing apps pass app_key.",
+                }
+            )
+            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": "new multi-app items require create_if_missing=true",
+                    "fix_hint": "Set create_if_missing=true, or pass app_key for an existing app.",
+                }
+            )
 
+        add_fields = _multi_app_list_value(item, "add_fields", "addFields")
+        if new_app_item:
+            title_fields: list[tuple[int, JSONObject]] = [
+                (field_index, field)
+                for field_index, field in enumerate(add_fields)
+                if isinstance(field, dict) and _is_data_title_field(field)
+            ]
+            if not title_fields:
+                issues.append(
+                    {
+                        "index": index,
+                        "row_number": index + 1,
+                        "path": f"apps[{index}].add_fields",
+                        "error_code": "MISSING_DATA_TITLE_FIELD",
+                        "message": "new apps must define exactly one top-level data title field",
+                        "fix_hint": "Mark one readable top-level field with as_data_title=true, for example {'name':'客户名称','type':'text','as_data_title':true}.",
+                        "details": {"suggested_field_names": [_field_name_for_static_validation(field) for field in add_fields[:8] if isinstance(field, dict)]},
+                    }
+                )
+            elif len(title_fields) > 1:
+                issues.append(
+                    {
+                        "index": index,
+                        "row_number": index + 1,
+                        "path": f"apps[{index}].add_fields",
+                        "error_code": "MULTIPLE_DATA_TITLE_FIELDS",
+                        "message": "new apps can mark only one top-level field as data title",
+                        "fix_hint": "Keep as_data_title=true on exactly one top-level field.",
+                        "details": {
+                            "fields": [
+                                {
+                                    "field_index": field_index,
+                                    "name": _field_name_for_static_validation(field),
+                                    "type": _field_type_for_static_validation(field),
+                                }
+                                for field_index, field in title_fields
+                            ]
+                        },
+                    }
+                )
+            else:
+                field_index, title_field = title_fields[0]
+                if _field_type_for_static_validation(title_field) in {"subtable", "table"}:
+                    issues.append(
+                        {
+                            "index": index,
+                            "row_number": index + 1,
+                            "path": f"apps[{index}].add_fields[{field_index}]",
+                            "error_code": "INVALID_DATA_TITLE_FIELD",
+                            "message": "data title must be a top-level non-subtable field",
+                            "fix_hint": "Move as_data_title=true to a normal top-level text/number/date-like field.",
+                            "details": {
+                                "field_name": _field_name_for_static_validation(title_field),
+                                "field_type": _field_type_for_static_validation(title_field),
+                            },
+                        }
+                    )
+                if _contains_multi_app_target_ref(title_field):
+                    issues.append(
+                        {
+                            "index": index,
+                            "row_number": index + 1,
+                            "path": f"apps[{index}].add_fields[{field_index}]",
+                            "error_code": "DATA_TITLE_FIELD_DEFERRED_BY_TARGET_REF",
+                            "message": "data title cannot be a relation field that depends on target_app_ref/target_app in the same multi-app call",
+                            "fix_hint": "Use a normal title field such as 客户名称/项目名称 as data title; keep relation fields as non-title fields.",
+                            "details": {"field_name": _field_name_for_static_validation(title_field)},
+                        }
+                    )
 
-def _multi_app_item_failure(index: int, item: object, error_code: str, message: str) -> JSONObject:
-    app_name = None
-    client_key = None
-    app_key = None
-    if isinstance(item, dict):
-        app_name = str(item.get("app_name") or item.get("appTitle") or item.get("app_title") or item.get("title") or "").strip() or None
-        client_key = str(item.get("client_key") or item.get("clientKey") or "").strip() or None
-        app_key = str(item.get("app_key") or item.get("appKey") or "").strip() or None
-    return {
-        "index": index,
-        "row_number": index + 1,
-        "client_key": client_key,
-        "app_name": app_name,
-        "app_key": app_key,
-        "status": "failed",
-        "stage": "validate_item",
-        "error_code": error_code,
-        "message": message,
-        "safe_to_retry": True,
-    }
+        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:
+                issues.append(
+                    {
+                        "index": index,
+                        "row_number": index + 1,
+                        "path": ref.get("path"),
+                        "error_code": "TARGET_APP_REFERENCE_EMPTY",
+                        "message": "target app reference cannot be empty",
+                        "fix_hint": "Use target_app_ref with another apps[].client_key, or target_app with a unique apps[].app_name.",
+                    }
+                )
+            elif ref.get("kind") == "target_app_ref" and ref_value not in client_key_indexes:
+                issues.append(
+                    {
+                        "index": index,
+                        "row_number": index + 1,
+                        "path": ref.get("path"),
+                        "error_code": "TARGET_APP_REF_UNRESOLVED",
+                        "message": f"target_app_ref '{ref_value}' does not match any apps[].client_key in this payload",
+                        "fix_hint": "Set target_app_ref to one of apps[].client_key, or use target_app_key for an already-known existing app.",
+                        "details": {"target_app_ref": ref_value, "available_client_keys": sorted(client_key_indexes.keys())},
+                    }
+                )
+            elif ref.get("kind") == "target_app":
+                matching_indexes = app_name_indexes.get(ref_value, [])
+                if not matching_indexes:
+                    issues.append(
+                        {
+                            "index": index,
+                            "row_number": index + 1,
+                            "path": ref.get("path"),
+                            "error_code": "TARGET_APP_NAME_UNRESOLVED",
+                            "message": f"target_app '{ref_value}' does not match any apps[].app_name in this payload",
+                            "fix_hint": "Prefer target_app_ref with a stable apps[].client_key, or make target_app match an app_name exactly.",
+                            "details": {"target_app": ref_value, "available_app_names": sorted(app_name_indexes.keys())},
+                        }
+                    )
+                elif len(matching_indexes) > 1:
+                    issues.append(
+                        {
+                            "index": index,
+                            "row_number": index + 1,
+                            "path": ref.get("path"),
+                            "error_code": "TARGET_APP_NAME_AMBIGUOUS",
+                            "message": f"target_app '{ref_value}' matches multiple apps[].app_name values",
+                            "fix_hint": "Use target_app_ref with a unique apps[].client_key instead of target_app.",
+                            "details": {"target_app": ref_value, "matching_indexes": matching_indexes},
+                        }
+                    )
+
+    if not issues:
+        return None
+    return _config_failure(
+        tool_name=tool_name,
+        error_code="MULTI_APP_STATIC_VALIDATION_FAILED",
+        message="multi-app schema payload has static errors; fix apps[] before writing.",
+        fix_hint="Before creating app shells, ensure each new app has exactly one data title, unique client_key/app_name, and relation refs match apps[].client_key or app_name.",
+        details={"issues": issues, "expected_shape": _schema_apps_expected_shape()},
+    )
 
 
-def _compile_multi_app_schema_item_refs(item: JSONObject, client_key_to_app_key: dict[str, str]) -> JSONObject:
+def _compile_multi_app_schema_item_refs(
+    item: JSONObject,
+    client_key_to_app_key: dict[str, str],
+    app_name_to_app_key: dict[str, str] | None = None,
+) -> JSONObject:
     compiled = deepcopy(item)
+    app_name_to_app_key = app_name_to_app_key or {}
 
     def visit(value):
         if isinstance(value, list):
@@ -2908,6 +3909,13 @@ def _compile_multi_app_schema_item_refs(item: JSONObject, client_key_to_app_key:
             if not target_app_key:
                 raise ValueError(f"target_app_ref '{ref_key}' did not match any apps[].client_key")
             payload["target_app_key"] = target_app_key
+        target_app = payload.pop("target_app", None) or payload.pop("targetApp", None)
+        if target_app is not None and not str(payload.get("target_app_key") or "").strip():
+            target_name = str(target_app or "").strip()
+            target_app_key = app_name_to_app_key.get(target_name)
+            if not target_app_key:
+                raise ValueError(f"target_app '{target_name}' did not match any apps[].app_name in the same call")
+            payload["target_app_key"] = target_app_key
         return payload
 
     return visit(compiled)
@@ -2956,7 +3964,7 @@ def _contains_multi_app_target_ref(value: object) -> bool:
     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"}:
+        if key in {"target_app_ref", "targetAppRef", "target_app_client_key", "targetAppClientKey", "target_app", "targetApp"}:
             return True
         if _contains_multi_app_target_ref(entry):
             return True
@@ -2979,6 +3987,8 @@ def _merge_schema_field_diffs(*diffs: object) -> JSONObject:
 
 
 def _schema_apply_result_has_write(result: JSONObject) -> bool:
+    if "write_executed" in result:
+        return bool(result.get("write_executed"))
     if bool(result.get("created")) or bool(result.get("published")) or bool(result.get("app_base_updated")):
         return True
     field_diff = result.get("field_diff")
@@ -2987,6 +3997,15 @@ def _schema_apply_result_has_write(result: JSONObject) -> bool:
     return False
 
 
+def _schema_apply_result_may_have_write(result: JSONObject) -> bool:
+    verification = result.get("verification") if isinstance(result.get("verification"), dict) else {}
+    return bool(
+        result.get("write_may_have_succeeded")
+        or str(result.get("next_action") or "") == "readback_before_retry"
+        or verification.get("readback_before_retry")
+    )
+
+
 def _validation_failure(
     detail: str,
     *,
@@ -3067,6 +4086,197 @@ def _visibility_validation_failure(
     return result
 
 
+_RESERVED_SYSTEM_FIELD_NAMES = {
+    "数据ID",
+    "编号",
+    "申请人",
+    "申请时间",
+    "创建人",
+    "创建时间",
+    "提交人",
+    "提交时间",
+    "更新时间",
+    "更新人",
+    "当前流程状态",
+    "当前处理人",
+    "当前处理节点",
+    "流程标题",
+}
+
+
+def _field_patch_name(item: object) -> str:
+    if not isinstance(item, dict):
+        return ""
+    value = item.get("name")
+    if value is None:
+        value = item.get("title")
+    if value is None:
+        value = item.get("field_name")
+    if value is None:
+        value = item.get("fieldName")
+    return str(value or "").strip()
+
+
+def _reserved_system_field_name_failure(
+    *,
+    tool_name: str,
+    profile: str,
+    app_key: str = "",
+    package_id: int | None = None,
+    app_name: str = "",
+    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,
+    remove_fields: list[JSONObject] | None = None,
+    app_index: int | None = None,
+) -> JSONObject | None:
+    for index, item in enumerate(add_fields or []):
+        name = _field_patch_name(item)
+        if name not in _RESERVED_SYSTEM_FIELD_NAMES:
+            continue
+        suggested_add_fields = [field for field in (add_fields or []) if _field_patch_name(field) not in _RESERVED_SYSTEM_FIELD_NAMES]
+        arguments: JSONObject = {
+            "profile": profile,
+            "app_key": app_key,
+            "package_id": package_id,
+            "app_name": app_name,
+            "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 [],
+        }
+        if publish is not None:
+            arguments["publish"] = publish
+        return _config_failure(
+            tool_name=tool_name,
+            error_code="RESERVED_SYSTEM_FIELD_NAME",
+            message=f"add_fields[{index}].name uses built-in system field name '{name}'",
+            fix_hint="Do not create form fields named 数据ID, 编号, 申请人, 申请时间, 创建人, 创建时间, 提交人, 提交时间, 更新时间, 更新人, 当前流程状态, 当前处理人, 当前处理节点, or 流程标题. These fields are provided by Qingflow. Remove them from add_fields; only reference them where the tool explicitly supports system fields, such as button source_field 数据ID.",
+            details={
+                "reserved_field_names": sorted(_RESERVED_SYSTEM_FIELD_NAMES),
+                "blocked_index": index,
+                "blocked_name": name,
+                "app_index": app_index,
+            },
+            suggested_next_call={"tool_name": tool_name, "arguments": arguments},
+        )
+    return None
+
+
+def _reserved_system_field_name_failure_for_apps(
+    *,
+    tool_name: str,
+    profile: str,
+    package_id: int | None,
+    visibility: JSONObject | None,
+    create_if_missing: bool,
+    publish: bool,
+    apps: list[JSONObject],
+) -> JSONObject | None:
+    for index, item in enumerate(apps or []):
+        if not isinstance(item, dict):
+            continue
+        failure = _reserved_system_field_name_failure(
+            tool_name=tool_name,
+            profile=profile,
+            app_key=str(item.get("app_key") or item.get("appKey") or ""),
+            package_id=package_id,
+            app_name=str(item.get("app_name") or item.get("appName") or ""),
+            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 []),
+            remove_fields=list(item.get("remove_fields") or item.get("removeFields") or []),
+            app_index=index,
+        )
+        if failure is not None:
+            suggested = deepcopy(failure.get("suggested_next_call") or {})
+            arguments = suggested.get("arguments")
+            if isinstance(arguments, dict):
+                fixed_apps = deepcopy(apps)
+                if isinstance(fixed_apps[index], dict):
+                    fixed_apps[index]["add_fields"] = arguments.get("add_fields") or []
+                arguments = {
+                    "profile": profile,
+                    "package_id": package_id,
+                    "visibility": visibility,
+                    "create_if_missing": create_if_missing,
+                    "publish": publish,
+                    "apps": fixed_apps,
+                }
+                failure["suggested_next_call"] = {"tool_name": tool_name, "arguments": arguments}
+            return failure
+    return None
+
+
+_RESERVED_SYSTEM_VIEW_NAMES = {
+    "全部数据",
+    "我的数据",
+    "我发起的",
+    "待办",
+    "已办",
+    "抄送",
+}
+
+
+def _reserved_system_view_name_failure(
+    *,
+    tool_name: str,
+    profile: str,
+    app_key: str,
+    publish: bool | None = None,
+    upsert_views: list[JSONObject] | None = None,
+    patch_views: list[JSONObject] | None = None,
+    remove_views: list[str] | None = None,
+) -> JSONObject | None:
+    for index, item in enumerate(upsert_views or []):
+        if not isinstance(item, dict):
+            continue
+        name = str(item.get("name") or "").strip()
+        view_key = str(item.get("view_key") or item.get("viewKey") or "").strip()
+        if name in _RESERVED_SYSTEM_VIEW_NAMES and not view_key:
+            suggested: JSONObject = {
+                "tool_name": tool_name,
+                "arguments": {
+                    "profile": profile,
+                    "app_key": app_key,
+                    "upsert_views": [
+                        {
+                            **item,
+                            "name": "业务台账视图",
+                        }
+                    ],
+                    "patch_views": patch_views or [],
+                    "remove_views": remove_views or [],
+                },
+            }
+            if publish is not None:
+                suggested["arguments"]["publish"] = publish
+            return _config_failure(
+                tool_name=tool_name,
+                error_code="RESERVED_SYSTEM_VIEW_NAME",
+                message=f"upsert_views[{index}].name uses built-in system view name '{name}' without view_key",
+                fix_hint="Do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送. Use a business-specific view name for new views; to modify a built-in view, pass its existing raw view_key or use patch_views.",
+                details={
+                    "reserved_view_names": sorted(_RESERVED_SYSTEM_VIEW_NAMES),
+                    "blocked_index": index,
+                    "blocked_name": name,
+                },
+                suggested_next_call=suggested,
+            )
+    return None
+
+
 def _config_failure(
     *,
     tool_name: str,
@@ -3075,6 +4285,7 @@ def _config_failure(
     error_code: str = "CONFIG_ERROR",
     details: JSONObject | None = None,
     allowed_values: JSONObject | None = None,
+    suggested_next_call: JSONObject | None = None,
 ) -> JSONObject:
     contract = _BUILDER_TOOL_CONTRACTS.get(tool_name or "")
     public_allowed_values = deepcopy(contract.get("allowed_values", {})) if isinstance(contract, dict) else {}
@@ -3095,7 +4306,7 @@ def _config_failure(
         "missing_fields": [],
         "allowed_values": public_allowed_values,
         "details": public_details,
-        "suggested_next_call": None,
+        "suggested_next_call": suggested_next_call,
         "request_id": None,
         "backend_code": None,
         "http_status": None,
@@ -3223,11 +4434,58 @@ def _builder_contract_with_apply_output(tool_name: str, contract: JSONObject) ->
         "schema_version": BUILDER_APPLY_SCHEMA_VERSION,
         "preferred_ui_fields": ["operation", "summary", "resources"],
         "resource_fields": ["resource_type", "operation", "status", "id", "key", "name", "ids", "parent", "icon_config", "error_code", "message"],
+        "json_paths": _builder_apply_json_paths(),
         "legacy_fields_preserved": True,
     }
     return public
 
 
+def _builder_tool_contract_summary(tool_name: str, contract: JSONObject) -> JSONObject:
+    allowed_values = contract.get("allowed_values") if isinstance(contract, dict) else {}
+    allowed_values_keys = sorted(str(key) for key in allowed_values) if isinstance(allowed_values, dict) else []
+    return {
+        "tool_name": tool_name,
+        "contract_path": "$.contract",
+        "allowed_keys_path": "$.contract.allowed_keys",
+        "allowed_values_path": "$.contract.allowed_values",
+        "allowed_values_key_style": "flat_dotted_keys",
+        "minimal_example_path": "$.contract.minimal_example",
+        "execution_notes_path": "$.contract.execution_notes",
+        "top_level_allowed_values_usage": "empty on successful contract lookup; use $.contract.allowed_values instead",
+        "allowed_values_keys_sample": allowed_values_keys[:12],
+        "json_paths": {
+            "contract": "$.contract",
+            "allowed_keys": "$.contract.allowed_keys",
+            "allowed_values": "$.contract.allowed_values",
+            "minimal_example": "$.contract.minimal_example",
+            "execution_notes": "$.contract.execution_notes",
+            "aliases": "$.contract.aliases",
+        },
+    }
+
+
+def _builder_apply_json_paths() -> JSONObject:
+    return {
+        "status": "$.status",
+        "schema_version": "$.schema_version",
+        "operation": "$.operation",
+        "summary": "$.summary",
+        "resources": "$.resources",
+        "warnings": "$.warnings",
+        "verification": "$.verification",
+        "details": "$.details",
+        "write_executed": "$.write_executed",
+        "write_may_have_succeeded": "$.write_may_have_succeeded",
+        "safe_to_retry": "$.safe_to_retry",
+        "next_action": "$.next_action",
+        "summary_write_executed": "$.summary.write_executed",
+        "summary_safe_to_retry": "$.summary.safe_to_retry",
+        "resource_keys": "$.resources[].key",
+        "resource_ids": "$.resources[].id",
+        "resource_statuses": "$.resources[].status",
+    }
+
+
 def _attach_builder_apply_envelope(tool_name: str, payload: JSONObject) -> JSONObject:
     if not isinstance(payload, dict):
         return payload
@@ -3236,6 +4494,7 @@ def _attach_builder_apply_envelope(tool_name: str, payload: JSONObject) -> JSONO
     payload["operation"] = tool_name
     payload["resources"] = resources
     payload["summary"] = _builder_apply_summary(payload, resources)
+    payload["json_paths"] = _builder_apply_json_paths()
     return payload
 
 
@@ -3269,8 +4528,14 @@ def _builder_apply_summary(payload: JSONObject, resources: list[JSONObject]) ->
     }
     if "write_executed" in payload:
         summary["write_executed"] = bool(payload.get("write_executed"))
+    if "write_may_have_succeeded" in payload:
+        summary["write_may_have_succeeded"] = bool(payload.get("write_may_have_succeeded"))
     if "safe_to_retry" in payload:
         summary["safe_to_retry"] = bool(payload.get("safe_to_retry"))
+    if payload.get("next_action"):
+        summary["next_action"] = payload.get("next_action")
+    if payload.get("pending_readback") is not None:
+        summary["pending_readback"] = payload.get("pending_readback")
     return summary
 
 
@@ -3291,6 +4556,8 @@ def _builder_apply_resources(tool_name: str, payload: JSONObject) -> list[JSONOb
         resources = _builder_package_resources(payload)
     elif tool_name == "app_schema_apply":
         resources = _builder_schema_resources(payload)
+    elif isinstance(payload.get("apps"), list) and _builder_apply_tool_is_app_scoped(tool_name):
+        resources = _builder_batch_app_resources(tool_name, payload)
     elif tool_name == "app_layout_apply":
         resources = [_builder_app_resource(payload, operation="layout_updated")]
     elif tool_name == "app_flow_apply":
@@ -3301,6 +4568,8 @@ def _builder_apply_resources(tool_name: str, payload: JSONObject) -> list[JSONOb
         resources = _builder_chart_resources(payload)
     elif tool_name == "portal_apply":
         resources = _builder_portal_resources(payload)
+    elif tool_name == "portal_delete":
+        resources = _builder_portal_resources(payload, operation_override="removed")
     elif tool_name == "app_custom_buttons_apply":
         resources = _builder_button_resources(payload)
     elif tool_name == "app_associated_resources_apply":
@@ -3316,6 +4585,38 @@ def _builder_apply_resources(tool_name: str, payload: JSONObject) -> list[JSONOb
     return resources
 
 
+def _builder_batch_app_resources(tool_name: str, payload: JSONObject) -> list[JSONObject]:
+    resources: list[JSONObject] = []
+    operation_by_tool = {
+        "app_schema_apply": "updated",
+        "app_layout_apply": "layout_updated",
+        "app_flow_apply": "workflow_updated",
+        "app_views_apply": "updated",
+        "app_custom_buttons_apply": "updated",
+        "app_associated_resources_apply": "updated",
+        "app_charts_apply": "updated",
+        "app_publish_verify": "verified",
+    }
+    operation = operation_by_tool.get(tool_name, "updated")
+    for item in payload.get("apps") or []:
+        if not isinstance(item, dict):
+            continue
+        result = item.get("result") if isinstance(item.get("result"), dict) else {}
+        nested_resources = result.get("resources") if isinstance(result, dict) else None
+        if isinstance(nested_resources, list) and nested_resources:
+            resources.extend(resource for resource in nested_resources if isinstance(resource, dict))
+            continue
+        app_payload: JSONObject = {
+            **(result if isinstance(result, dict) else {}),
+            "app_key": item.get("app_key") or (result.get("app_key") if isinstance(result, dict) else None),
+            "status": item.get("status") or (result.get("status") if isinstance(result, dict) else None),
+            "error_code": item.get("error_code") or (result.get("error_code") if isinstance(result, dict) else None),
+            "message": item.get("message") or (result.get("message") if isinstance(result, dict) else None),
+        }
+        resources.append(_builder_app_resource(app_payload, operation=operation))
+    return resources
+
+
 def _builder_apply_tool_is_app_scoped(tool_name: str) -> bool:
     return tool_name in {
         "app_schema_apply",
@@ -3496,7 +4797,15 @@ def _builder_package_resources(payload: JSONObject) -> list[JSONObject]:
     package_id = payload.get("package_id") or payload.get("id")
     package_name = payload.get("package_name") or payload.get("name")
     status = _builder_status(payload, "success")
-    operation = "failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated")
+    operation = (
+        "failed"
+        if status == "failed"
+        else "removed"
+        if bool(payload.get("deleted")) or bool(payload.get("delete_executed"))
+        else "created"
+        if bool(payload.get("created"))
+        else "updated"
+    )
     normalized_args = payload.get("normalized_args") if isinstance(payload.get("normalized_args"), dict) else {}
     icon_config = (
         _builder_container_icon_config(payload, raw_keys=("icon", "tagIcon", "tag_icon"))
@@ -3547,7 +4856,7 @@ def _builder_schema_resources(payload: JSONObject) -> list[JSONObject]:
                     parent=package_parent,
                     icon_config=icon_config,
                     error_code=item.get("error_code"),
-                    message=item.get("message") if status == "failed" else None,
+                    message=item.get("message") if status in {"failed", "pending_readback"} else None,
                 )
             )
             resources.extend(_builder_field_resources(item.get("field_diff_details") or item.get("field_diff"), parent=parent))
@@ -3748,7 +5057,7 @@ def _builder_chart_resources(payload: JSONObject) -> list[JSONObject]:
     return resources
 
 
-def _builder_portal_resources(payload: JSONObject) -> list[JSONObject]:
+def _builder_portal_resources(payload: JSONObject, *, operation_override: str | None = None) -> list[JSONObject]:
     status = _builder_status(payload, "success")
     draft_result = payload.get("draft_result") if isinstance(payload.get("draft_result"), dict) else {}
     live_result = payload.get("live_result") if isinstance(payload.get("live_result"), dict) else {}
@@ -3779,7 +5088,7 @@ def _builder_portal_resources(payload: JSONObject) -> list[JSONObject]:
         first_tag = draft_result.get("tags")[0]
         if isinstance(first_tag, dict):
             package_id = first_tag.get("tagId") or first_tag.get("tag_id") or first_tag.get("id")
-    operation = "failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated")
+    operation = operation_override or ("failed" if status == "failed" else ("created" if bool(payload.get("created")) else "updated"))
     parent = None
     if package_id:
         parent = _builder_parent("package", id_value=package_id, key=package_id)
@@ -3968,7 +5277,7 @@ def _coerce_api_error(error: Exception) -> QingflowApiError:
 
 
 def _public_error_message(error_code: str, error: QingflowApiError) -> str:
-    if error.backend_code == 40074 or error_code == "APP_EDIT_LOCKED":
+    if backend_code_int(error) == 40074 or error_code == "APP_EDIT_LOCKED":
         return "app is currently locked by another active editor session"
     if error.http_status != 404:
         return error.message
@@ -4143,13 +5452,29 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "package_apply": {
-        "allowed_keys": ["package_id", "package_name", "create_if_missing", "icon", "color", "visibility", "items", "allow_detach"],
+        "allowed_keys": [
+            "package_id",
+            "package_name",
+            "create_if_missing",
+            "icon",
+            "color",
+            "icon_name",
+            "icon_color",
+            "icon_config",
+            "visibility",
+            "items",
+            "allow_detach",
+        ],
         "aliases": {
             "packageId": "package_id",
             "packageName": "package_name",
             "createIfMissing": "create_if_missing",
             "iconName": "icon",
             "iconColor": "color",
+            "icon_config.name": "icon",
+            "icon_config.icon_name": "icon",
+            "icon_config.color": "color",
+            "icon_config.icon_color": "color",
             "allowDetach": "allow_detach",
         },
         "allowed_values": {
@@ -4161,12 +5486,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "create or update package metadata, visibility, grouping, and ordering in one call",
             "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",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             "metadata keys omitted on update are preserved",
             "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:[...]}",
+            "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,
         ],
         "minimal_example": {
@@ -4309,7 +5636,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
     "app_custom_buttons_apply": {
         "allowed_keys": [
             "app_key",
-            "apps",
             "upsert_buttons",
             "patch_buttons",
             "remove_buttons",
@@ -4394,6 +5720,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id maps to current record id (-17), 编号/record_number maps to visible record number (0)",
             "to fill a target relation field with the current source record, map source_field='数据ID' to the target relation field; default_values is for static constants, not dynamic current-record values",
             "do not write raw que_relation unless maintaining a legacy config; field_mappings/default_values and que_relation are mutually exclusive",
+            "permission split follows backend routes: upsert_buttons/patch_buttons/remove_buttons require EditAppAuth; view_configs also requires ViewManagementAuth (beingViewManageStatus), which falls back to DataManageAuth when advanced app permissions are not enabled",
             "view_configs binds custom buttons into views in the same apply call; button_ref may be a same-call client_key, a button_id, or an exact unique existing button_text",
             "view_configs[].view_key is the raw builder view key from app_get.views[].view_key; do not pass record-data view_id values like custom:VIEW_KEY",
             "view_configs[].buttons is required in merge mode; omitting buttons is blocked to avoid no-op writes and accidental publish",
@@ -4406,7 +5733,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "if a removed button returns readback_status=unavailable or still_exists, treat the result as readback pending and do not blindly repeat the delete",
             "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",
-            "accepts apps[] for multi-app batch; each item is {app_key, upsert_buttons?, patch_buttons?, remove_buttons?, view_configs?}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -4482,7 +5808,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
     "app_associated_resources_apply": {
         "allowed_keys": [
             "app_key",
-            "apps",
             "upsert_resources",
             "patch_resources",
             "remove_associated_item_ids",
@@ -4539,6 +5864,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "this tool manages Qingflow in-app associated report/view display; it does not create or edit QingBI report bodies/configs",
             "create or edit app-source BI report bodies first with app_charts_apply, then attach the resulting chart_id here with graph_type=chart; dataset BI reports can only be attached when they already exist",
             "this is the default associated report/view path; it manages both the app-level associated resource pool and per-view display config",
+            "permission split follows backend routes: upsert_resources/patch_resources/remove/reorder require EditAppAuth; view_configs require ViewManagementAuth (beingViewManageStatus), which falls back to DataManageAuth when advanced app permissions are not enabled",
             "use patch_resources for partial parameter replacement on existing associated resources; the tool reads the current resource including backend-required raw fields, merges patch_resources[].set/unset, then submits the backend full-save payload internally",
             "associated_item_id is form_asos_chart.id from app_get.associated_resources[].associated_item_id; view_configs/remove/reorder may also pass an existing associated resource's chart_id/chart_key/view_key and the tool resolves it to the internal id",
             "before creating an associated resource, read app_get.associated_resources and reuse an existing item with patch_resources when target_app_key + view_key/chart_key already matches; repeated upsert_resources without associated_item_id can create duplicate associated items",
@@ -4552,7 +5878,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",
             "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",
-            "accepts apps[] for multi-app batch; each item is {app_key, upsert_resources?, patch_resources?, remove_associated_item_ids?, reorder_associated_item_ids?, view_configs?}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -4583,22 +5908,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 }
             ],
         },
-        "batch_example": {
-            "profile": "default",
-            "apps": [
-                {
-                    "app_key": "APP_1",
-                    "upsert_resources": [
-                        {"client_key": "orders_view", "graph_type": "view", "target_app_key": "ORDER_APP", "view_key": "ORDER_VIEW"}
-                    ],
-                    "view_configs": [{"view_key": "MAIN_VIEW", "limit_type": "select", "associated_item_refs": ["orders_view"]}],
-                },
-                {
-                    "app_key": "APP_2",
-                    "view_configs": [{"view_key": "MAIN_VIEW", "visible": True, "limit_type": "all"}],
-                },
-            ],
-        },
     },
     "app_schema_plan": {
         "allowed_keys": ["app_key", "package_id", "app_name", "icon", "color", "visibility", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
@@ -4642,6 +5951,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "create mode may set visibility for the new app; edit mode may update visibility on an existing app",
             "create mode should include explicit non-template icon + color; apply mode enforces this before writing",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
+            "do not add form fields named 数据ID, 编号, 申请人, 申请时间, 创建人, 创建时间, 提交人, 提交时间, 更新时间, 更新人, 当前流程状态, 当前处理人, 当前处理节点, or 流程标题; these are Qingflow built-in system fields, not fields to create",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
@@ -4678,8 +5988,12 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "app_key",
             "package_id",
             "app_name",
+            "app_title",
             "icon",
             "color",
+            "icon_name",
+            "icon_color",
+            "icon_config",
             "visibility",
             "create_if_missing",
             "publish",
@@ -4692,11 +6006,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "apps[].app_name",
             "apps[].icon",
             "apps[].color",
+            "apps[].icon_name",
+            "apps[].icon_color",
+            "apps[].icon_config",
             "apps[].visibility",
             "apps[].add_fields",
             "apps[].update_fields",
             "apps[].remove_fields",
             "apps[].add_fields[].target_app_ref",
+            "apps[].add_fields[].target_app",
         ],
         "aliases": {
             "app_title": "app_name",
@@ -4706,8 +6024,16 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "apps[].appKey": "apps[].app_key",
             "apps[].appName": "apps[].app_name",
             "apps[].appTitle": "apps[].app_name",
+            "apps[].iconName": "apps[].icon",
+            "apps[].iconColor": "apps[].color",
+            "apps[].icon_config.name": "apps[].icon",
+            "apps[].icon_config.color": "apps[].color",
             "field.targetAppRef": "field.target_app_ref",
             "field.targetAppClientKey": "field.target_app_ref",
+            "field.targetApp": "field.target_app",
+            "field.options[].label": "field.options[]",
+            "field.options[].value": "field.options[]",
+            "field.options[].optValue": "field.options[]",
             "field.title": "field.name",
             "field.label": "field.name",
             "field.fields": "field.subfields",
@@ -4733,6 +6059,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "allowed_values": {
             "field.type": [member.value for member in PublicFieldType],
+            "field.type_aliases": {alias: field_type.value for alias, field_type in sorted(FIELD_TYPE_ALIASES.items())},
             "field.relation_mode": [member.value for member in PublicRelationMode],
             "field.department_scope.mode": ["all", "custom"],
             "field.code_block_binding.outputs.target_field.type": list(INTEGRATION_OUTPUT_TARGET_FIELD_TYPES),
@@ -4744,14 +6071,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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 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 + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
+            "CLI --apps-file primary shape is {package_id, apps:[...]}; raw app arrays and singleton wrapper arrays are compatibility paths, not recommended examples",
+            "multi-app mode preflights static errors before writing: duplicate client_key/app_name, missing data title on new apps, create_if_missing omissions, 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",
             "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",
+            "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",
             "multi-app create mode requires each new app item to include a distinct non-template icon and a valid color",
+            "agent-friendly field type aliases are normalized before writing: multiline/multiline_text/textarea -> long_text; select/single_choice/dropdown -> single_select; multi_choice/multiple_choice/checkbox -> multi_select",
+            "single_select and multi_select options accept strings or objects such as {label,value}; builder normalizes them to option labels before writing",
             "edit mode preserves existing icon/color when omitted; explicit icon/color values are still validated",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
+            "do not add form fields named 数据ID, 编号, 申请人, 申请时间, 创建人, 创建时间, 提交人, 提交时间, 更新时间, 更新人, 当前流程状态, 当前处理人, 当前处理节点, or 流程标题; these are Qingflow built-in system fields, not fields to create",
             *_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",
@@ -4759,6 +6094,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",
+            "relation write readback returns details.relation_readback_matrix; mismatches include details.relation_repair_plan with a minimal update_fields relation patch and data_impact",
             "update_fields[].set.subfield_updates is the safe patch path for editing existing subtable child fields without rebuilding the entire subtable",
             "subfield_updates only supports safe child overlays: name, required, description, and nested subfield_updates",
             "set.subfields remains the full replace/rebuild path for a subtable and is higher risk when hidden relation/reference children exist",
@@ -4974,7 +6310,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "preset_example": {"profile": "default", "app_key": "APP_KEY", "mode": "merge", "preset": "balanced", "sections": []},
     },
     "app_layout_apply": {
-        "allowed_keys": ["app_key", "mode", "publish", "sections", "apps"],
+        "allowed_keys": ["app_key", "mode", "publish", "sections"],
         "aliases": {"overwrite": "replace", "sectionId": "section_id"},
         "section_allowed_keys": ["type", "paragraph_id", "section_id", "title", "rows"],
         "section_aliases": {
@@ -4991,7 +6327,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "mode=replace is full layout replacement and should be used only when intentionally rewriting all sections",
             "layout verification is split into layout_verified and layout_summary_verified",
             "LAYOUT_SUMMARY_UNVERIFIED means raw form readback is stronger than the compact summary",
-            "accepts apps[] for multi-app batch; each item is {app_key, mode?, sections, publish?}; top-level publish is used as default for items that omit publish",
         ],
         "minimal_section_example": {"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["字段A", "字段B", "字段C", "字段D"]]},
         "minimal_example": {
@@ -5001,73 +6336,95 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "publish": True,
             "sections": [{"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["项目名称", "项目负责人", "项目阶段", "优先级"]]}],
         },
-        "batch_example": {
-            "profile": "default",
-            "publish": True,
-            "apps": [
-                {"app_key": "APP_KEY_1", "mode": "merge", "sections": [{"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["字段A", "字段B"]]}]},
-                {"app_key": "APP_KEY_2", "mode": "merge", "sections": [{"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["字段C", "字段D"]]}]},
-            ],
-        },
     },
-    "app_flow_get_schema": {
-        "allowed_keys": ["schema_version"],
-        "aliases": {"schemaVersion": "schema_version"},
-        "allowed_values": {},
-        "execution_notes": [
-            "returns WorkflowSpec JSON Schema from /workflow/spec/schema",
-            "call this before authoring a new spec or validating spec shape",
-            "worksheet-level approval deduplication toggles (legacy global settings) are not yet part of WorkflowSpec",
-        ],
-        "minimal_example": {
-            "profile": "default",
-            "schema_version": "vnext-2026-06",
+    "app_flow_plan": {
+        "allowed_keys": ["app_key", "mode", "nodes", "transitions", "preset"],
+        "aliases": {
+            "overwrite": "replace",
+            "base_preset": "preset",
+            "default_approval": "basic_approval",
+            "node.role_names": "node.assignees.role_names",
+            "node.role_ids": "node.assignees.role_ids",
+            "node.member_names": "node.assignees.member_names",
+            "node.member_emails": "node.assignees.member_emails",
+            "node.member_uids": "node.assignees.member_uids",
+            "node.editable_fields": "node.permissions.editable_fields",
+            "default_approval": "basic_approval",
         },
-    },
-    "app_flow_get": {
-        "allowed_keys": ["app_key", "version_id"],
-        "aliases": {"versionId": "version_id"},
-        "allowed_values": {},
+        "allowed_values": {
+            "mode": ["replace"],
+            "preset": [member.value for member in FlowPreset],
+            "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
+        },
+        "dependency_hints": [
+            "approval-style workflows require an explicit business status select field before app_flow_apply, such as 状态 / 处理状态 / 审批状态 / 工单状态",
+            "approve/fill/copy nodes require at least one assignee",
+        ],
         "execution_notes": [
-            "returns current WorkflowSpecDTO for one app via GET /workflow/spec",
-            "use GET-first before patching and app_flow_apply",
+            "public flow building is intentionally limited to linear workflows",
+            "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
+            "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
+            "mode": "replace",
+            "preset": "basic_approval",
+            "nodes": [
+                {
+                    "id": "approve_1",
+                    "type": "approve",
+                    "name": "部门审批",
+                    "assignees": {"role_names": ["项目经理"]},
+                    "permissions": {"editable_fields": ["状态", "审批意见"]},
+                }
+            ],
+            "transitions": [],
         },
     },
     "app_flow_apply": {
-        "allowed_keys": ["app_key", "publish", "spec", "idempotency_key", "schema_version", "patch_nodes"],
+        "allowed_keys": ["app_key", "mode", "publish", "nodes", "transitions"],
         "aliases": {
-            "schemaVersion": "schema_version",
-            "idempotencyKey": "idempotency_key",
+            "overwrite": "replace",
+            "node.role_names": "node.assignees.role_names",
+            "node.role_ids": "node.assignees.role_ids",
+            "node.member_names": "node.assignees.member_names",
+            "node.member_emails": "node.assignees.member_emails",
+            "node.member_uids": "node.assignees.member_uids",
+            "node.editable_fields": "node.permissions.editable_fields",
+        },
+        "allowed_values": {
+            "mode": ["replace"],
+            "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
         },
-        "allowed_values": {},
         "dependency_hints": [
-            "when using spec: must be a complete WorkflowSpecDTO object (replace-only apply); when using patch_nodes[]: spec is not required",
-            "use patch_nodes[] instead of spec when updating only specific nodes; patch_nodes reads current flow, merges set/unset, then writes back — spec is not needed when patch_nodes is supplied",
+            "approval-style workflows require an explicit business status select field before app_flow_apply, such as 状态 / 处理状态 / 审批状态 / 工单状态",
+            "approve/fill/copy nodes require at least one assignee",
         ],
         "execution_notes": [
-            "posts to /workflow/spec:apply with appKey, idempotencyKey, schemaVersion, and spec",
-            "verification uses appliedSpec, diffSummary, and semanticLint from the apply response",
-            "publish=false keeps changes in draft when supported by the backend",
-            "patch_nodes[] items are {id, set, unset}; id must match an existing node id from app_get_flow.spec.nodes; FLOW_NODE_NOT_FOUND is returned if id is missing",
+            "public flow building is intentionally limited to linear workflows",
+            "app_flow_apply is replace-only; do not treat node snippets as partial patches",
+            "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
+            "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
+            "workflow verification only covers linear node structure in the public tool surface",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
+            "mode": "replace",
             "publish": True,
-            "spec": {
-                "nodes": [{"id": "n1", "type": "APPLICANT", "name": "发起"}],
-                "transitions": [],
-            },
-        },
-        "patch_nodes_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-            "publish": True,
-            "patch_nodes": [{"id": "approve_1", "set": {"name": "总监审批", "assignees": {"role_names": ["总监"]}}}],
+            "nodes": [
+                {"id": "start", "type": "start", "name": "发起"},
+                {
+                    "id": "approve_1",
+                    "type": "approve",
+                    "name": "部门审批",
+                    "assignees": {"role_names": ["项目经理"]},
+                    "permissions": {"editable_fields": ["状态", "审批意见"]},
+                },
+                {"id": "end", "type": "end", "name": "结束"},
+            ],
+            "transitions": [{"from": "start", "to": "approve_1"}, {"from": "approve_1", "to": "end"}],
         },
     },
     "app_views_plan": {
@@ -5125,12 +6482,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
+            "creating a new view follows backend createViewgraphConfig and requires both ViewManagementAuth and DataManageAuth; updating/deleting existing views only requires ViewManagementAuth",
             "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
-            "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
+            "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
+            "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
             "use patch_views for partial parameter replacement on existing views; the tool reads current config, merges patch_views[].set/unset, then submits the backend full-save payload internally",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
+            "do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送; these are built-in system/default views. Use business-specific names for new views, and pass the existing raw view_key or patch_views when changing a built-in view",
             "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_views explicitly changes associated_resources",
             "associated report/view resource pool and per-view selected resources are configured through app_associated_resources_apply; app_views_apply only keeps legacy associated_resources input compatible",
             "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
@@ -5139,7 +6499,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "upsert_views": [{"name": "项目台账视图", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_views": [],
         },
         "query_conditions_example": {
@@ -5177,6 +6537,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             ],
             "remove_views": [],
         },
+        "query_conditions_field_rules": {
+            "supported_field_types": ["text", "long_text", "number", "amount", "date", "datetime", "single_select", "multi_select", "phone", "email", "boolean", "member", "department"],
+            "unsupported_field_types": ["relation", "attachment", "subtable", "address", "code_block", "q_linker"],
+            "use_instead": {
+                "fixed_filter": "filters",
+                "current_record_related_report_or_view": "app_associated_resources_apply.match_mappings",
+            },
+        },
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -5197,7 +6565,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
     "app_views_apply": {
         "allowed_keys": [
             "app_key",
-            "apps",
             "publish",
             "upsert_views",
             "patch_views",
@@ -5250,27 +6617,29 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "execution_notes": [
             "apply may return partial_success when some views land and others fail",
+            "creating a new view follows backend createViewgraphConfig and requires both ViewManagementAuth and DataManageAuth; updating/deleting existing views only requires ViewManagementAuth",
             "when duplicate view names exist, supply view_key to target the exact view",
             "read back app_get after any failed or partial view apply",
             "view existence verification and saved-filter verification are separate; treat filters as unverified until verification.view_filters_verified is true",
             "buttons omitted preserves existing button config; buttons=[] clears all buttons; buttons=[...] replaces the full button config",
             "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
-            "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
+            "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
+            "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
             "use patch_views for partial parameter replacement on existing views; the public update mode is patch even though the backend save is still a full view payload",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
+            "do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送; these are built-in system/default views. Use business-specific names for new views, and pass the existing raw view_key or patch_views when changing a built-in view",
             "new views created by app_views_apply default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless patch_views/upsert_views explicitly changes associated_resources",
             "associated report/view resource pool and per-view selected resources are configured through app_associated_resources_apply; app_views_apply keeps legacy associated_resources input compatible but it is no longer the recommended public contract",
             "for multi-value operators such as in, pass values as a list; value may also be used as an alias when it already contains a list",
-            "accepts apps[] for multi-app batch; each item is {app_key, upsert_views?, patch_views?, remove_views?, publish?}; top-level publish is used as default for items that omit publish",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
             "publish": True,
-            "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "upsert_views": [{"name": "项目台账视图", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_views": [],
         },
         "query_conditions_example": {
@@ -5310,6 +6679,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             ],
             "remove_views": [],
         },
+        "query_conditions_field_rules": {
+            "supported_field_types": ["text", "long_text", "number", "amount", "date", "datetime", "single_select", "multi_select", "phone", "email", "boolean", "member", "department"],
+            "unsupported_field_types": ["relation", "attachment", "subtable", "address", "code_block", "q_linker"],
+            "use_instead": {
+                "fixed_filter": "filters",
+                "current_record_related_report_or_view": "app_associated_resources_apply.match_mappings",
+            },
+        },
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -5329,19 +6706,18 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get": {
-        "allowed_keys": ["app_key", "app_keys"],
+        "allowed_keys": ["app_key"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
             "returns builder-side app map: base summary, editability, field/view/chart/button counts, compact views, compact charts, custom_buttons, and app-level associated_resources",
             "use this as the default builder discovery read before view_get/chart_get/apply detail work",
             "editability is route-aware builder capability summary, not end-user data visibility",
-            "can_edit_app_base covers app base-info writes such as app_name, icon, and visibility",
-            "can_edit_form covers form/schema routes only and does not imply app base-info writes",
+            "can_edit_app_base covers app base-info writes such as app_name, icon, and visibility; it follows backend EditAppAuth and does not require package edit_tag",
+            "can_edit_form covers form/schema routes and also follows backend EditAppAuth",
             "returns normalized app visibility when backend auth is readable",
             "custom_buttons[].button_id is the id required by app_custom_buttons_apply view_configs[].buttons[].button_ref",
             "associated_resources[].associated_item_id is the internal id; app_associated_resources_apply.view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key",
-            "accepts app_keys[] for batch summary read; batch returns {status, apps[], errors[]} where each apps[] item preserves the single app_get summary fields",
         ],
         "minimal_example": {
             "profile": "default",
@@ -5349,7 +6725,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get_fields": {
-        "allowed_keys": ["app_key", "app_keys"],
+        "allowed_keys": ["app_key"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
@@ -5357,8 +6733,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "use this before app_schema_apply when you need exact field definitions",
             "also returns chart_fields from QingBI datasource fields; app_charts_apply field selectors should use chart_fields because record/schema-visible fields and QingBI fields are not the same schema",
             "chart_fields[].field_id supports field_<queId> selectors, while chart_fields[].bi_field_id is the raw QingBI fieldId accepted by report configs",
+            "chart_fields[].chart_apply_examples contains copyable semantic app_charts_apply snippets such as count_by_field, filtered_count, and numeric sum_metric",
             "subtable fields include nested subfields using the same compact field shape",
-            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item has {app_key, fields}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -5366,13 +6742,12 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get_layout": {
-        "allowed_keys": ["app_key", "app_keys"],
+        "allowed_keys": ["app_key"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
             "returns compact current layout configuration for one app",
             "use this before app_layout_apply when you need paragraph and row structure",
-            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item has {app_key, sections}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -5380,7 +6755,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get_views": {
-        "allowed_keys": ["app_key", "app_keys"],
+        "allowed_keys": ["app_key"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
@@ -5388,7 +6763,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "compatibility/specialized inventory tool; default builder discovery should start with app_get",
             "use this before app_views_apply only when you need an exact current view inventory beyond app_get",
             "view items include visibility_summary when backend view auth is readable",
-            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item has {app_key, views}",
         ],
         "minimal_example": {
             "profile": "default",
@@ -5396,13 +6770,12 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get_flow": {
-        "allowed_keys": ["app_key", "app_keys"],
+        "allowed_keys": ["app_key"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
-            "returns WorkflowSpecDTO for one app (alias of app_flow_get)",
-            "use app_flow_get_schema then app_flow_get before app_flow_apply",
-            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item has {app_key, spec}",
+            "returns workflow configuration summary for one app",
+            "use this before app_flow_apply when you need the current node structure",
         ],
         "minimal_example": {
             "profile": "default",
@@ -5410,7 +6783,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_get_charts": {
-        "allowed_keys": ["app_key", "app_keys"],
+        "allowed_keys": ["app_key"],
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
@@ -5419,37 +6792,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "use this before app_charts_apply when you need exact current chart_id values beyond the app_get summary",
             "chart summaries do not include full qingbi config payloads",
             "chart items include visibility_summary when QingBI base info is readable",
-            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item has {app_key, charts}",
-        ],
-        "minimal_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-        },
-    },
-    "app_get_buttons": {
-        "allowed_keys": ["app_key", "app_keys"],
-        "aliases": {},
-        "allowed_values": {},
-        "execution_notes": [
-            "returns custom button list (draft state) for one app",
-            "also returns view_configs read from view bindings, so app_custom_buttons_apply view_configs can be patched from the same read result",
-            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item preserves the single-read fields such as {app_key, buttons, view_configs, warnings, verification}",
-            "use before app_custom_buttons_apply when you need current button_id values",
-        ],
-        "minimal_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-        },
-    },
-    "app_get_associated_resources": {
-        "allowed_keys": ["app_key", "app_keys"],
-        "aliases": {},
-        "allowed_values": {},
-        "execution_notes": [
-            "returns associated resource pool (draft state) for one app",
-            "also returns view_configs read from view bindings, so app_associated_resources_apply view_configs can be patched from the same read result",
-            "accepts app_keys[] for batch read; batch returns {status, apps[], errors[]} where each apps[] item preserves the single-read fields such as {app_key, associated_resources, view_configs, warnings, verification}",
-            "use before app_associated_resources_apply when you need current associated_item_id values",
         ],
         "minimal_example": {
             "profile": "default",
@@ -5464,6 +6806,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "returns builder-configurable portal list items only",
             "use this as the builder portal discovery path before portal_get",
             "results are compact list items, not raw dash payloads",
+            "large workspaces may return an unfiltered discovery list with portal_permissions_verified=false instead of probing every portal detail",
         ],
         "minimal_example": {
             "profile": "default",
@@ -5486,7 +6829,22 @@ _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",
+            "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",
@@ -5494,6 +6852,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": {
@@ -5514,18 +6877,20 @@ _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",
                 "remove_chart_ids deletes by chart_id and verifies each deleted chart with single chart_id readback; pure delete does not read the full chart list",
                 "if delete readback is unavailable or still finds the chart, chart_results[] returns delete_executed=true, readback_status, and safe_to_retry_delete=false; do not blindly repeat delete",
-                "accepts apps[] for multi-app batch; each item is {app_key, upsert_charts?, patch_charts?, remove_chart_ids?, reorder_chart_ids?}",
                 *_VISIBILITY_EXECUTION_NOTES,
             ],
         "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": [],
@@ -5563,7 +6928,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "portal_apply": {
-        "allowed_keys": ["dash_key", "dash_name", "name", "package_id", "publish", "sections", "patch_sections", "pages", "payload", "layout_preset", "visibility", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
+        "allowed_keys": ["dash_key", "dash_name", "name", "package_id", "publish", "sections", "pages", "payload", "layout_preset", "visibility", "auth", "icon", "color", "hide_copyright", "dash_global_config", "config"],
         "aliases": {
             "packageId": "package_id",
             "name": "dash_name",
@@ -5575,13 +6940,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "section_allowed_keys": ["title", "source_type", "role", "position", "dash_style_config", "config", "chart_ref", "view_ref", "text", "url"],
         "section_aliases": {
             "sourceType": "source_type",
+            "zone": "role",
+            "sectionRole": "role",
             "chartRef": "chart_ref",
             "viewRef": "view_ref",
             "dashStyleConfigBO": "dash_style_config",
         },
         "allowed_values": {
             "section.source_type": ["chart", "view", "grid", "filter", "text", "link"],
-            "section.role": ["metric"],
             "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),
@@ -5591,23 +6957,25 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "use exactly one resource mode",
             "update mode: dash_key",
             "create mode: package_id + dash_name",
+            "create mode follows backend DashCtrl.createDash: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
             "create mode requires explicit icon + color; icon=template is blocked because it is too generic",
             "edit mode preserves existing icon/color when omitted; explicit icon/color values are still validated",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             "portal_apply uses replace semantics for sections",
             "when editing an existing portal, sections may be omitted to update only base info such as visibility, icon, or package",
-            "use patch_sections[] for section-level patch updates without replacing all sections; each item needs one selector (chart_ref with chart_id/chart_key/chart_name, view_ref with view_key/view_name, or order as 0-based index) plus set/unset",
-            "when sections[] is supplied without patch_sections[], it uses replace semantics for all sections",
-            "remove a section by omitting it from the sections list (replace mode) or by unset in patch_sections (patch mode)",
+            "portal section-level patch is not exposed; supplying sections means full sections replacement",
+            "remove a section by omitting it from the new sections list",
             "package_id is required when creating a new portal",
             "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
-            "chart_ref resolves by chart_id/chart_key first, then exact unique chart_name",
+            "chart_ref resolves by chart_id first, then exact unique chart_name",
             "view_ref resolves by view_key first, then exact unique view_name",
             "pc layout uses a 24-column grid; mobile layout uses a 6-column grid",
-            "set section.role=metric only for target/indicator chart cards; metric cards use pc.rows >= 5 and pc.cols >= 6, while ordinary BI charts use pc.rows >= 7 and pc.cols >= 8",
             "if unsure about layout, omit position or use layout_preset=auto/dashboard_2col/dashboard_3col",
             "two-column pc layout should use x=0/12 with cols=12; three-column pc layout should use x=0/8/16 with cols=8",
             "x=0/6 with cols=6 only occupies the left half of the pc portal and triggers PORTAL_LAYOUT_HALF_WIDTH",
+            "grid sections must include config.items; an empty grid triggers PORTAL_GRID_ITEMS_EMPTY because the frontend only shows an empty entry container",
+            "metric portal sections may set role=metric; role=metric requires a target/indicator chart and otherwise triggers PORTAL_METRIC_SECTION_CHART_TYPE_MISMATCH",
+            "standard workbench count diagnostics warn when metric cards are not 4-6, BI charts are not 2-3, or business views are not 1-2",
             "position.pc/mobile is the canonical portal layout shape",
             "compat payload accepts name -> dash_name and single pages[0].components -> sections",
             "visibility is the canonical public auth shape; auth is kept only as a deprecated compatibility alias",
@@ -5661,14 +7029,19 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 "mobile": {"x": 0, "y": 0, "cols": 6, "rows": 8},
             },
         },
-        "patch_sections_example": {
+    },
+    "portal_delete": {
+        "allowed_keys": ["dash_key"],
+        "aliases": {"dashKey": "dash_key"},
+        "allowed_values": {},
+        "execution_notes": [
+            "deletes one portal by dash_key",
+            "delete results separate DELETE execution from readback verification",
+            "if delete_executed=true and readback_status=unavailable or still_exists, do not blindly repeat delete; confirm later with portal_get or portal_list",
+        ],
+        "minimal_example": {
             "profile": "default",
             "dash_key": "DASH_KEY",
-            "publish": True,
-            "patch_sections": [
-                {"chart_ref": {"chart_id": "CHART_ID"}, "set": {"title": "销售总览-新版"}},
-                {"order": 2, "set": {"title": "任务列表-新版"}},
-            ],
         },
     },
     "app_publish_verify": {
@@ -5708,6 +7081,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
 _PRIVATE_BUILDER_TOOL_CONTRACTS = {
     "app_schema_plan",
     "app_layout_plan",
+    "app_flow_plan",
     "app_views_plan",
 }