@qingflow-tech/qingflow-app-user-mcp 1.0.40 → 1.0.42

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -22,6 +22,7 @@ from ..builder_facade.models import (
     ChartApplyRequest,
     CustomButtonsApplyRequest,
     CustomButtonPatch,
+    FIELD_TYPE_ALIASES,
     FIELD_TYPE_ID_ALIASES,
     FieldPatch,
     FieldRemovePatch,
@@ -1824,6 +1825,13 @@ class AiBuilderTools(ToolBase):
         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):
@@ -1892,6 +1900,9 @@ class AiBuilderTools(ToolBase):
         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):
@@ -1931,25 +1942,47 @@ 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",
                     "write_executed": shell_write_executed,
-                    "safe_to_retry": not shell_write_executed and not any_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 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()
@@ -2016,7 +2049,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
 
@@ -2038,11 +2075,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,
@@ -2055,21 +2099,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 {}),
             })
 
+        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,
@@ -2077,12 +2133,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,
@@ -2612,12 +2679,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")
@@ -3053,6 +3120,262 @@ def _normalize_schema_apps_argument(*, tool_name: str, package_id: int | None, a
     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)},
+                        }
+                    )
+
+        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],
@@ -3167,6 +3490,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,
     *,
@@ -3641,8 +3973,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
 
 
@@ -3929,7 +4267,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))
@@ -5132,6 +5470,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),
@@ -5146,6 +5485,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",
@@ -5153,6 +5493,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",
@@ -5164,6 +5505,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",
@@ -5782,6 +6124,7 @@ _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",
         ],
         "minimal_example": {
@@ -5877,7 +6220,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_charts_apply": {
-        "allowed_keys": ["app_key", "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",
@@ -5885,6 +6243,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": {
@@ -5905,6 +6268,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 "upsert_charts[].visibility compiles to QingBI base visibleAuth only",
                 "visibility-only updates keep the existing chart config and do not rewrite rawDataConfigDTO.authInfo",
                 "chart dimension/metric/filter/query fields are resolved from app_get_fields.chart_fields (QingBI datasource fields), not record schema or form-only fields",
+                "preferred chart metric DSL is SQL-like: metric='count(*)', metric='sum(金额)', metrics=['sum(金额)'], group_by=['状态'], where=[{field, op, value}]",
+                "legacy dimension_field_ids/indicator_field_ids/config.aggregate remain supported as advanced compatibility input, but should not be the first choice for agents",
+                "chart_get returns semantic group_by and metrics; raw QingBI config is diagnostic detail",
                 "system fields such as 申请人/申请时间/编号 are usable only when they appear in chart_fields; otherwise app_charts_apply returns CHART_FIELD_NOT_IN_QINGBI_SCHEMA",
                 "low-frequency chart types have local prevalidation: gauge requires 0 dimensions and 2 non-duplicated metrics; histogram requires at most 1 dimension and exactly 1 plain numeric metric",
                 "chart rule failures return chart_results[].diagnostics with rule_code, expected, actual, offending_fields, and next_action; backend 81002/81005 are translated when possible",
@@ -5915,7 +6281,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "upsert_charts": [{"name": "数据总量", "chart_type": "target", "indicator_field_ids": [], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "upsert_charts": [{"name": "数据总量", "chart_type": "target", "metric": "count(*)", "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "patch_charts": [{"chart_id": "CHART_ID", "set": {"name": "数据总量-新版"}}],
             "remove_chart_ids": [],
             "reorder_chart_ids": [],
@@ -5962,9 +6328,11 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "viewRef": "view_ref",
             "dashStyleConfigBO": "dash_style_config",
         },
-        "section_allowed_keys": ["title", "source_type", "position", "dash_style_config", "config", "chart_ref", "view_ref", "text", "url"],
+        "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",
@@ -5996,6 +6364,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",