@qingflow-tech/qingflow-app-builder-mcp 1.0.10 → 1.0.12

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from copy import deepcopy
 import json
 import time
+from typing import Any
 
 from pydantic import ValidationError
 
@@ -14,7 +15,7 @@ from ..builder_facade.button_style_catalog import (
 )
 from ..public_surface import public_builder_contract_tool_names
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError
+from ..errors import QingflowApiError, backend_code_int
 from ..json_types import JSONObject
 from ..builder_facade.models import (
     AssociatedResourcesApplyRequest,
@@ -49,6 +50,15 @@ from ..builder_facade.models import (
     ViewsPlanRequest,
 )
 from ..builder_facade.service import AiBuilderFacade, INTEGRATION_OUTPUT_TARGET_FIELD_TYPES
+from ..solution.compiler.icon_utils import (
+    GENERIC_WORKSPACE_ICON_NAMES,
+    WORKSPACE_ICON_COLORS,
+    WORKSPACE_ICON_NAMES,
+    normalize_workspace_icon_name,
+    validate_workspace_icon_choice,
+    workspace_icon_catalog_payload,
+    workspace_icon_config,
+)
 from .app_tools import AppTools
 from .base import ToolBase, tool_cn_name
 from .custom_button_tools import CustomButtonTools
@@ -117,6 +127,14 @@ class AiBuilderTools(ToolBase):
         def builder_tool_contract(tool_name: str = "") -> JSONObject:
             return self.builder_tool_contract(tool_name=tool_name)
 
+        @mcp.tool()
+        def workspace_icon_catalog_get(profile: str = DEFAULT_PROFILE) -> JSONObject:
+            return self.workspace_icon_catalog_get(profile=profile)
+
+        @mcp.tool()
+        def package_list(profile: str = DEFAULT_PROFILE, trial_status: str = "all", query: str = "") -> JSONObject:
+            return self.package_list(profile=profile, trial_status=trial_status, query=query)
+
         @mcp.tool()
         def package_get(profile: str = DEFAULT_PROFILE, package_id: int = 0) -> JSONObject:
             return self.package_get(profile=profile, package_id=package_id)
@@ -482,9 +500,12 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             dash_key: str = "",
             dash_name: str = "",
+            name: str = "",
             package_id: int | None = None,
             publish: bool = True,
             sections: list[JSONObject] | None = None,
+            pages: list[JSONObject] | None = None,
+            layout_preset: str = "",
             visibility: JSONObject | None = None,
             auth: JSONObject | None = None,
             icon: str | None = None,
@@ -492,10 +513,14 @@ class AiBuilderTools(ToolBase):
             hide_copyright: bool | None = None,
             dash_global_config: JSONObject | None = None,
             config: JSONObject | None = None,
+            payload: JSONObject | None = None,
         ) -> JSONObject:
+            payload = payload if isinstance(payload, dict) else {}
             has_dash_key = bool((dash_key or "").strip())
-            has_dash_name = bool((dash_name or "").strip())
-            has_package_id = package_id is not None
+            effective_dash_name = (dash_name or name or str(payload.get("dash_name") or payload.get("dashName") or payload.get("name") or "")).strip()
+            has_dash_name = bool(effective_dash_name)
+            effective_package_id = package_id if package_id is not None else payload.get("package_id") or payload.get("packageId") or payload.get("package_tag_id")
+            has_package_id = effective_package_id is not None
             if has_dash_key and has_package_id:
                 return _config_failure(
                     tool_name="portal_apply",
@@ -512,9 +537,12 @@ class AiBuilderTools(ToolBase):
                 profile=profile,
                 dash_key=dash_key,
                 dash_name=dash_name,
+                name=name,
                 package_id=package_id,
                 publish=publish,
                 sections=sections or [],
+                pages=pages or [],
+                layout_preset=layout_preset,
                 visibility=visibility,
                 auth=auth,
                 icon=icon,
@@ -522,6 +550,7 @@ class AiBuilderTools(ToolBase):
                 hide_copyright=hide_copyright,
                 dash_global_config=dash_global_config,
                 config=config or {},
+                payload=payload,
             )
 
         @mcp.tool()
@@ -537,14 +566,14 @@ class AiBuilderTools(ToolBase):
             )
 
     @tool_cn_name("分组列表查询")
-    def package_list(self, *, profile: str, trial_status: str = "all") -> JSONObject:
+    def package_list(self, *, profile: str, trial_status: str = "all", query: str = "") -> JSONObject:
         """执行分组与包相关逻辑。"""
-        normalized_args = {"trial_status": trial_status}
+        normalized_args = {"trial_status": trial_status, "query": query}
         return _safe_tool_call(
-            lambda: self._facade.package_list(profile=profile, trial_status=trial_status),
+            lambda: self._facade.package_list(profile=profile, trial_status=trial_status, query=query),
             error_code="PACKAGE_LIST_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "package_list", "arguments": {"profile": profile, "trial_status": trial_status}},
+            suggested_next_call={"tool_name": "package_list", "arguments": {"profile": profile, "trial_status": trial_status, "query": query}},
         )
 
     @tool_cn_name("分组解析")
@@ -611,6 +640,27 @@ class AiBuilderTools(ToolBase):
             "contract": contract,
         }
 
+    @tool_cn_name("工作区图标目录")
+    def workspace_icon_catalog_get(self, *, profile: str = DEFAULT_PROFILE) -> JSONObject:
+        """读取应用、应用包、门户可用的工作区图标候选。"""
+        catalog = workspace_icon_catalog_payload()
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "loaded workspace icon catalog",
+            "profile": profile,
+            "icon_names": catalog["icon_names"],
+            "icon_colors": catalog["icon_colors"],
+            "generic_icon_names": catalog["generic_icon_names"],
+            "common_examples": catalog["common_examples"],
+            "notes": catalog["notes"],
+            "count": len(catalog["icon_names"]),
+            "color_count": len(catalog["icon_colors"]),
+            "warnings": [],
+            "verification": {"source": "backend AiBuildConstant ICON_NAMES/ICON_COLORS"},
+        }
+
     @tool_cn_name("分组创建")
     def package_create(
         self,
@@ -691,6 +741,14 @@ class AiBuilderTools(ToolBase):
                     "package_apply",
                     _visibility_validation_failure(str(exc), tool_name="package_apply", exc=exc),
                 )
+        icon_failure = _validate_workspace_icon_for_builder(
+            tool_name="package_apply",
+            icon=icon,
+            color=color,
+            creating=package_id is None and bool(create_if_missing),
+        )
+        if icon_failure is not None:
+            return _attach_builder_apply_envelope("package_apply", icon_failure)
         normalized_args = {
             "package_id": package_id,
             **({"package_name": package_name} if str(package_name or "").strip() else {}),
@@ -796,16 +854,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,
@@ -818,9 +883,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}},
@@ -1657,6 +1729,68 @@ class AiBuilderTools(ToolBase):
                 message="app_schema_apply multi-app mode requires non-empty apps.",
                 fix_hint="Pass apps as a non-empty list of app schema items.",
             )
+        icon_errors: list[JSONObject] = []
+        seen_new_app_icons: dict[str, int] = {}
+        for index, raw_item in enumerate(apps):
+            if not isinstance(raw_item, dict):
+                continue
+            app_key = str(raw_item.get("app_key") or raw_item.get("appKey") or "").strip()
+            creating_item = not app_key
+            icon_failure = _validate_workspace_icon_for_builder(
+                tool_name="app_schema_apply",
+                icon=str(raw_item.get("icon") or ""),
+                color=str(raw_item.get("color") or ""),
+                creating=creating_item,
+            )
+            if icon_failure is not None:
+                icon_errors.append(
+                    {
+                        "index": index,
+                        "row_number": index + 1,
+                        "error_code": icon_failure.get("error_code"),
+                        "message": icon_failure.get("message"),
+                        "details": icon_failure.get("details"),
+                    }
+                )
+                continue
+            _ok, _error_code, _message, icon_details = validate_workspace_icon_choice(
+                icon=str(raw_item.get("icon") or ""),
+                color=str(raw_item.get("color") or ""),
+                require_explicit=creating_item,
+                disallow_generic=creating_item,
+            )
+            normalized_icon = str(icon_details.get("normalized_icon") or "").strip()
+            if creating_item and normalized_icon:
+                if normalized_icon in seen_new_app_icons:
+                    icon_errors.append(
+                        {
+                            "index": index,
+                            "row_number": index + 1,
+                            "error_code": "DUPLICATE_WORKSPACE_ICON_IN_BATCH",
+                            "message": f"apps[{index}] reuses icon '{normalized_icon}' from apps[{seen_new_app_icons[normalized_icon]}]",
+                            "details": {
+                                "icon": normalized_icon,
+                                "first_index": seen_new_app_icons[normalized_icon],
+                                "duplicate_index": index,
+                                "icon_catalog_command": "qingflow --json builder icon catalog",
+                            },
+                        }
+                    )
+                else:
+                    seen_new_app_icons[normalized_icon] = index
+        if icon_errors:
+            return _config_failure(
+                tool_name="app_schema_apply",
+                error_code="WORKSPACE_ICON_BATCH_INVALID",
+                message="one or more apps have invalid workspace icon configuration",
+                fix_hint="Call `qingflow --json builder icon catalog`, choose a distinct non-template icon and color for each new app, then retry.",
+                details={"icon_errors": icon_errors},
+                allowed_values={
+                    "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
+                    "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
+                    "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
+                },
+            )
 
         client_key_to_app_key: dict[str, str] = {}
         created_app_keys: list[str] = []
@@ -1700,6 +1834,9 @@ 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)
+            if shell_write_executed:
+                any_write_executed = True
             if public_shell.get("status") not in {"success", "partial_success"} or not resolved_key:
                 results.append({
                     "index": index,
@@ -1711,13 +1848,12 @@ class AiBuilderTools(ToolBase):
                     "stage": "resolve_or_create_shell",
                     "error_code": public_shell.get("error_code") or "APP_SHELL_APPLY_FAILED",
                     "message": public_shell.get("message") or "app shell resolve/create failed",
-                    "safe_to_retry": not any_write_executed,
+                    "write_executed": shell_write_executed,
+                    "safe_to_retry": not shell_write_executed and not any_write_executed,
                 })
                 continue
             if bool(public_shell.get("created")):
                 created_app_keys.append(resolved_key)
-            if _schema_apply_result_has_write(public_shell):
-                any_write_executed = True
             if client_key:
                 client_key_to_app_key[client_key] = resolved_key
             results.append({
@@ -1868,6 +2004,14 @@ class AiBuilderTools(ToolBase):
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
         effective_app_name = app_name or app_title
+        icon_failure = _validate_workspace_icon_for_builder(
+            tool_name="app_schema_apply",
+            icon=icon,
+            color=color,
+            creating=not bool(str(app_key or "").strip()) and bool(create_if_missing),
+        )
+        if icon_failure is not None:
+            return icon_failure
         plan_result = self._rewrite_plan_result_for_apply(
             result=self.app_schema_plan(
                 profile=profile,
@@ -2364,9 +2508,12 @@ class AiBuilderTools(ToolBase):
         profile: str,
         dash_key: str = "",
         dash_name: str = "",
+        name: str = "",
         package_id: int | None = None,
         publish: bool = True,
         sections: list[JSONObject] | None = None,
+        pages: list[JSONObject] | None = None,
+        layout_preset: str = "",
         visibility: JSONObject | None = None,
         auth: JSONObject | None = None,
         icon: str | None = None,
@@ -2374,25 +2521,44 @@ class AiBuilderTools(ToolBase):
         hide_copyright: bool | None = None,
         dash_global_config: JSONObject | None = None,
         config: JSONObject | None = None,
+        payload: JSONObject | None = None,
     ) -> JSONObject:
         """执行门户相关逻辑。"""
+        request_payload: dict[str, Any] = dict(payload) if isinstance(payload, dict) else {}
+        if dash_key:
+            request_payload["dash_key"] = dash_key
+        if dash_name:
+            request_payload["dash_name"] = dash_name
+        elif name:
+            request_payload["name"] = name
+        if package_id is not None:
+            request_payload["package_id"] = package_id
+        if "publish" not in request_payload or publish is False:
+            request_payload["publish"] = publish
+        if sections:
+            request_payload["sections"] = sections
+        if pages:
+            request_payload["pages"] = pages
+        if layout_preset:
+            request_payload["layout_preset"] = layout_preset
+        if visibility is not None:
+            request_payload["visibility"] = visibility
+        if auth is not None:
+            request_payload["auth"] = auth
+        if icon is not None:
+            request_payload["icon"] = icon
+        if color is not None:
+            request_payload["color"] = color
+        if hide_copyright is not None:
+            request_payload["hide_copyright"] = hide_copyright
+        if dash_global_config is not None:
+            request_payload["dash_global_config"] = dash_global_config
+        if config:
+            merged_config = dict(request_payload.get("config") or {}) if isinstance(request_payload.get("config"), dict) else {}
+            merged_config.update(config)
+            request_payload["config"] = merged_config
         try:
-            request = PortalApplyRequest.model_validate(
-                {
-                    "dash_key": dash_key or None,
-                    "dash_name": dash_name or None,
-                    "package_tag_id": package_id,
-                    "publish": publish,
-                    "sections": sections or [],
-                    "visibility": visibility,
-                    "auth": auth,
-                    "icon": icon,
-                    "color": color,
-                    "hide_copyright": hide_copyright,
-                    "dash_global_config": dash_global_config,
-                    "config": config or {},
-                }
-            )
+            request = PortalApplyRequest.model_validate(request_payload)
         except ValidationError as exc:
             return _attach_builder_apply_envelope("portal_apply", _visibility_validation_failure(
                 str(exc),
@@ -2405,6 +2571,7 @@ class AiBuilderTools(ToolBase):
                         "dash_name": dash_name or "业务门户",
                         "package_id": package_id or 1001,
                         "publish": True,
+                        "layout_preset": "dashboard_2col",
                         "sections": [
                             {
                                 "title": "经营概览",
@@ -2417,6 +2584,14 @@ class AiBuilderTools(ToolBase):
             ))
         normalized_args = request.model_dump(mode="json")
         normalized_args["package_id"] = normalized_args.pop("package_tag_id", package_id)
+        icon_failure = _validate_workspace_icon_for_builder(
+            tool_name="portal_apply",
+            icon=str(request.icon or ""),
+            color=str(request.color or ""),
+            creating=not bool(str(request.dash_key or "").strip()),
+        )
+        if icon_failure is not None:
+            return _attach_builder_apply_envelope("portal_apply", icon_failure)
         result = _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.portal_apply(profile=profile, request=request),
             error_code="PORTAL_APPLY_FAILED",
@@ -2683,6 +2858,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")
@@ -2771,20 +2948,34 @@ def _visibility_validation_failure(
     return result
 
 
-def _config_failure(*, tool_name: str, message: str, fix_hint: str) -> JSONObject:
+def _config_failure(
+    *,
+    tool_name: str,
+    message: str,
+    fix_hint: str,
+    error_code: str = "CONFIG_ERROR",
+    details: JSONObject | None = None,
+    allowed_values: 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 {}
+    if allowed_values:
+        public_allowed_values.update(deepcopy(allowed_values))
+    public_details: JSONObject = {
+        "fix_hint": fix_hint,
+        "allowed_keys": deepcopy(contract.get("allowed_keys", [])) if isinstance(contract, dict) else [],
+    }
+    if details:
+        public_details.update(deepcopy(details))
     return {
         "status": "failed",
-        "error_code": "CONFIG_ERROR",
+        "error_code": error_code,
         "recoverable": True,
         "message": message,
         "normalized_args": {},
         "missing_fields": [],
-        "allowed_values": deepcopy(contract.get("allowed_values", {})) if isinstance(contract, dict) else {},
-        "details": {
-            "fix_hint": fix_hint,
-            "allowed_keys": deepcopy(contract.get("allowed_keys", [])) if isinstance(contract, dict) else [],
-        },
+        "allowed_values": public_allowed_values,
+        "details": public_details,
         "suggested_next_call": None,
         "request_id": None,
         "backend_code": None,
@@ -2794,6 +2985,52 @@ def _config_failure(*, tool_name: str, message: str, fix_hint: str) -> JSONObjec
     }
 
 
+def _workspace_icon_config_failure(
+    *,
+    tool_name: str,
+    error_code: str,
+    message: str,
+    details: JSONObject,
+) -> JSONObject:
+    return _config_failure(
+        tool_name=tool_name,
+        error_code=error_code,
+        message=message,
+        fix_hint="Call `qingflow --json builder icon catalog`, choose an explicit non-template icon and color, then retry.",
+        details=details,
+        allowed_values={
+            "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
+            "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
+            "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
+        },
+    )
+
+
+def _validate_workspace_icon_for_builder(
+    *,
+    tool_name: str,
+    icon: str | None,
+    color: str | None,
+    creating: bool,
+) -> JSONObject | None:
+    if not creating and not (str(icon or "").strip() or str(color or "").strip()):
+        return None
+    ok, error_code, message, details = validate_workspace_icon_choice(
+        icon=icon,
+        color=color,
+        require_explicit=creating,
+        disallow_generic=creating,
+    )
+    if ok:
+        return None
+    return _workspace_icon_config_failure(
+        tool_name=tool_name,
+        error_code=error_code or "WORKSPACE_ICON_INVALID",
+        message=message or "invalid workspace icon configuration",
+        details=details,
+    )
+
+
 def _safe_tool_call(
     call,
     *,
@@ -2842,6 +3079,7 @@ def _publicize_package_fields(value):
         "tag_ids_after": "package_ids_after",
         "tag_name": "package_name",
         "tag_icon": "icon",
+        "iconConfig": "icon_config",
         "package_tag_id": "package_id",
         "package_tag_ids": "package_ids",
         "expected_package_tag_id": "expected_package_id",
@@ -2865,7 +3103,7 @@ def _builder_contract_with_apply_output(tool_name: str, contract: JSONObject) ->
     public["output_contract"] = {
         "schema_version": BUILDER_APPLY_SCHEMA_VERSION,
         "preferred_ui_fields": ["operation", "summary", "resources"],
-        "resource_fields": ["resource_type", "operation", "status", "id", "key", "name", "ids", "parent", "error_code", "message"],
+        "resource_fields": ["resource_type", "operation", "status", "id", "key", "name", "ids", "parent", "icon_config", "error_code", "message"],
         "legacy_fields_preserved": True,
     }
     return public
@@ -3013,6 +3251,41 @@ def _builder_app_parent(payload: JSONObject) -> JSONObject | None:
     return _builder_parent("app", key=app_key, name=app_name)
 
 
+def _builder_icon_config(raw_icon: object = None, *, icon: object = None, color: object = None) -> JSONObject | None:
+    raw = str(raw_icon).strip() if raw_icon not in (None, "") else ""
+    explicit_icon = str(icon).strip() if icon not in (None, "") else ""
+    explicit_color = str(color).strip() if color not in (None, "") else ""
+    if raw:
+        if raw.startswith("{") and raw.endswith("}"):
+            config = workspace_icon_config(raw)
+        else:
+            config = {
+                "icon_name": normalize_workspace_icon_name(raw),
+                "icon_color": explicit_color or None,
+                "icon_text": None,
+                "raw": raw,
+            }
+        if any(config.get(key) for key in ("icon_name", "icon_color", "icon_text", "raw")):
+            return config
+    if explicit_icon or explicit_color:
+        return {
+            "icon_name": normalize_workspace_icon_name(explicit_icon) if explicit_icon else None,
+            "icon_color": explicit_color or None,
+            "icon_text": None,
+            "raw": None,
+        }
+    return None
+
+
+def _builder_container_icon_config(container: object, *, raw_keys: tuple[str, ...], icon_keys: tuple[str, ...] = ("icon",), color_keys: tuple[str, ...] = ("color",)) -> JSONObject | None:
+    if not isinstance(container, dict):
+        return None
+    raw_icon = next((container.get(key) for key in raw_keys if container.get(key) not in (None, "")), None)
+    icon = next((container.get(key) for key in icon_keys if container.get(key) not in (None, "")), None)
+    color = next((container.get(key) for key in color_keys if container.get(key) not in (None, "")), None)
+    return _builder_icon_config(raw_icon, icon=icon, color=color)
+
+
 def _builder_resource(
     *,
     resource_type: str,
@@ -3023,10 +3296,11 @@ def _builder_resource(
     name: object = None,
     ids: JSONObject | None = None,
     parent: JSONObject | None = None,
+    icon_config: JSONObject | None = None,
     error_code: object = None,
     message: object = None,
 ) -> JSONObject:
-    return {
+    resource = {
         "resource_type": resource_type,
         "operation": operation,
         "status": status,
@@ -3038,6 +3312,9 @@ def _builder_resource(
         "error_code": str(error_code) if error_code not in (None, "") else None,
         "message": str(message) if message not in (None, "") else None,
     }
+    if icon_config:
+        resource["icon_config"] = icon_config
+    return resource
 
 
 def _builder_app_resource(payload: JSONObject, *, operation: str) -> JSONObject:
@@ -3046,6 +3323,11 @@ def _builder_app_resource(payload: JSONObject, *, operation: str) -> JSONObject:
         operation = "failed"
     app_key = _builder_payload_app_key(payload)
     app_name = _builder_payload_app_name(payload)
+    normalized_args = payload.get("normalized_args") if isinstance(payload.get("normalized_args"), dict) else {}
+    icon_config = (
+        _builder_container_icon_config(payload, raw_keys=("app_icon", "appIcon"))
+        or _builder_container_icon_config(normalized_args, raw_keys=("app_icon", "appIcon", "icon"))
+    )
     return _builder_resource(
         resource_type="app",
         operation=operation,
@@ -3053,6 +3335,7 @@ def _builder_app_resource(payload: JSONObject, *, operation: str) -> JSONObject:
         key=app_key,
         name=app_name,
         ids={"app_key": app_key} if app_key not in (None, "") else {},
+        icon_config=icon_config,
         error_code=payload.get("error_code"),
         message=payload.get("message") if status == "failed" else None,
     )
@@ -3095,6 +3378,11 @@ def _builder_package_resources(payload: JSONObject) -> list[JSONObject]:
     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")
+    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"))
+        or _builder_container_icon_config(normalized_args, raw_keys=("icon", "tagIcon", "tag_icon"))
+    )
     return [
         _builder_resource(
             resource_type="package",
@@ -3104,6 +3392,7 @@ def _builder_package_resources(payload: JSONObject) -> list[JSONObject]:
             key=str(package_id) if package_id not in (None, "") else None,
             name=package_name,
             ids={"package_id": package_id} if package_id not in (None, "") else {},
+            icon_config=icon_config,
             error_code=payload.get("error_code"),
             message=payload.get("message") if status == "failed" else None,
         )
@@ -3121,6 +3410,10 @@ def _builder_schema_resources(payload: JSONObject) -> list[JSONObject]:
             status = _builder_status(item, "success")
             operation = "failed" if status == "failed" else ("created" if bool(item.get("created")) else "updated")
             parent = _builder_parent("app", key=item.get("app_key"), name=item.get("app_name"))
+            icon_config = (
+                _builder_container_icon_config(item, raw_keys=("app_icon", "appIcon", "icon"))
+                or _builder_container_icon_config(item.get("shell_result"), raw_keys=("app_icon", "appIcon", "icon"))
+            )
             resources.append(
                 _builder_resource(
                     resource_type="app",
@@ -3133,6 +3426,7 @@ def _builder_schema_resources(payload: JSONObject) -> list[JSONObject]:
                         **({"package_id": package_id} if package_id not in (None, "") else {}),
                     },
                     parent=package_parent,
+                    icon_config=icon_config,
                     error_code=item.get("error_code"),
                     message=item.get("message") if status == "failed" else None,
                 )
@@ -3145,6 +3439,11 @@ def _builder_schema_resources(payload: JSONObject) -> list[JSONObject]:
     app_key = payload.get("app_key")
     app_name = payload.get("app_name_after") or payload.get("app_name")
     parent = _builder_parent("app", key=app_key, name=app_name)
+    normalized_args = payload.get("normalized_args") if isinstance(payload.get("normalized_args"), dict) else {}
+    icon_config = (
+        _builder_container_icon_config(payload, raw_keys=("app_icon", "appIcon", "icon"))
+        or _builder_container_icon_config(normalized_args, raw_keys=("icon", "app_icon", "appIcon"))
+    )
     resources = [
         _builder_resource(
             resource_type="app",
@@ -3153,6 +3452,7 @@ def _builder_schema_resources(payload: JSONObject) -> list[JSONObject]:
             key=app_key,
             name=app_name,
             ids={"app_key": app_key} if app_key else {},
+            icon_config=icon_config,
             error_code=payload.get("error_code"),
             message=payload.get("message") if status == "failed" else None,
         )
@@ -3254,6 +3554,7 @@ def _builder_view_verification_by_name(payload: JSONObject) -> dict[str, JSONObj
 
 
 def _builder_view_identity(item: object, verification_by_name: dict[str, JSONObject]) -> tuple[str | None, str | None, str, object, object]:
+    verification: JSONObject | None = None
     if isinstance(item, dict):
         name = item.get("name") or item.get("view_name") or item.get("viewName")
         view_key = item.get("view_key") or item.get("viewKey")
@@ -3274,6 +3575,16 @@ def _builder_view_identity(item: object, verification_by_name: dict[str, JSONObj
                 matching = verification.get("matching_view_keys")
                 if isinstance(matching, list) and matching:
                     view_key = matching[0]
+    if name and verification is None:
+        verification = verification_by_name.get(str(name))
+    if isinstance(verification, dict):
+        verification_status = str(verification.get("status") or "").strip()
+        if verification_status in {"removed", "readback_pending"}:
+            status = "readback_pending"
+            if verification_status == "removed":
+                status = "removed"
+        error_code = error_code or verification.get("error_code")
+        message = message or verification.get("message")
     return (
         str(name) if name not in (None, "") else None,
         str(view_key) if view_key not in (None, "") else None,
@@ -3290,16 +3601,17 @@ def _builder_chart_resources(payload: JSONObject) -> list[JSONObject]:
         if not isinstance(item, dict):
             continue
         status = str(item.get("status") or "success")
-        operation = _builder_operation(status, fallback="updated")
+        operation = _builder_operation(item.get("operation") or status, fallback="updated")
         if status == "failed":
             operation = "failed"
+        resource_status = "failed" if status == "failed" else ("readback_pending" if status == "readback_pending" else "success")
         chart_id = item.get("chart_id") or item.get("chartId")
         chart_key = item.get("chart_key") or item.get("chartKey")
         resources.append(
             _builder_resource(
                 resource_type="chart",
                 operation=operation,
-                status="failed" if status == "failed" else "success",
+                status=resource_status,
                 id_value=chart_id,
                 key=chart_key or chart_id,
                 name=item.get("name") or item.get("chart_name") or item.get("chartName"),
@@ -3311,7 +3623,7 @@ def _builder_chart_resources(payload: JSONObject) -> list[JSONObject]:
                 },
                 parent=parent,
                 error_code=item.get("error_code"),
-                message=item.get("message") if status == "failed" else None,
+                message=item.get("message") if status in {"failed", "readback_pending"} else None,
             )
         )
     return resources
@@ -3352,6 +3664,12 @@ def _builder_portal_resources(payload: JSONObject) -> list[JSONObject]:
     parent = None
     if package_id:
         parent = _builder_parent("package", id_value=package_id, key=package_id)
+    icon_config = (
+        _builder_container_icon_config(payload, raw_keys=("dash_icon", "dashIcon", "icon"))
+        or _builder_container_icon_config(draft_result, raw_keys=("dashIcon", "dash_icon", "icon"))
+        or _builder_container_icon_config(live_result, raw_keys=("dashIcon", "dash_icon", "icon"))
+        or _builder_container_icon_config(normalized_args, raw_keys=("icon", "dash_icon", "dashIcon"))
+    )
     return [
         _builder_resource(
             resource_type="portal",
@@ -3364,6 +3682,7 @@ def _builder_portal_resources(payload: JSONObject) -> list[JSONObject]:
                 **({"package_id": package_id} if package_id else {}),
             },
             parent=parent,
+            icon_config=icon_config,
             error_code=payload.get("error_code"),
             message=payload.get("message") if status == "failed" else None,
         )
@@ -3393,7 +3712,7 @@ def _builder_button_resources(payload: JSONObject) -> list[JSONObject]:
                     },
                     parent=parent,
                     error_code=item.get("error_code"),
-                    message=item.get("message") if status == "failed" else None,
+                    message=item.get("message") if status in {"failed", "readback_pending"} else None,
                 )
             )
     for item in payload.get("view_configs") or []:
@@ -3413,7 +3732,7 @@ def _builder_button_resources(payload: JSONObject) -> list[JSONObject]:
                     },
                     parent=parent,
                     error_code=item.get("error_code"),
-                    message=item.get("message") if status == "failed" else None,
+                    message=item.get("message") if status in {"failed", "readback_pending"} else None,
                 )
             )
     return resources
@@ -3457,7 +3776,7 @@ def _builder_associated_resource_resources(payload: JSONObject) -> list[JSONObje
                     },
                     parent=parent,
                     error_code=item.get("error_code"),
-                    message=item.get("message") if status == "failed" else None,
+                    message=item.get("message") if status in {"failed", "readback_pending"} else None,
                 )
             )
     for item in payload.get("view_configs") or []:
@@ -3530,7 +3849,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
@@ -3656,6 +3975,40 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "tool_name": "chart_get",
         },
     },
+    "workspace_icon_catalog_get": {
+        "allowed_keys": [],
+        "aliases": {},
+        "allowed_values": {
+            "icon": list(WORKSPACE_ICON_NAMES),
+            "color": list(WORKSPACE_ICON_COLORS),
+            "generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
+        },
+        "execution_notes": [
+            "read this before creating app packages, apps, or portals when choosing supported workspace icons",
+            "the CLI validates icon/color candidates but does not infer business defaults from resource names",
+            "new app/package/portal creation requires explicit non-template icon + color",
+        ],
+        "minimal_example": {
+            "profile": "default",
+        },
+    },
+    "package_list": {
+        "allowed_keys": ["trial_status", "query"],
+        "aliases": {"trialStatus": "trial_status", "keyword": "query"},
+        "allowed_values": {"trial_status": ["all"]},
+        "execution_notes": [
+            "lists app packages visible to the current builder profile by calling backend GET /tag?trialStatus=...",
+            "query is applied locally to package_id/tag_id/package_name/tag_name after /tag returns",
+            "does not fall back to app list because app list cannot represent empty packages, duplicate package names, or package-level permissions",
+            "returns package_id/package_name plus compatible tag_id/tag_name; use package_get for package detail before editing",
+            "permission failures are returned as PACKAGE_LIST_FAILED with backend transport details",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "trial_status": "all",
+            "query": "产品研发",
+        },
+    },
     "package_get": {
         "allowed_keys": ["package_id"],
         "aliases": {"packageId": "package_id"},
@@ -3680,13 +4033,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "iconColor": "color",
             "allowDetach": "allow_detach",
         },
-        "allowed_values": deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        "allowed_values": {
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
+            "workspace_icon.icon_names": list(WORKSPACE_ICON_NAMES),
+            "workspace_icon.icon_colors": list(WORKSPACE_ICON_COLORS),
+            "workspace_icon.generic_icon_names": list(GENERIC_WORKSPACE_ICON_NAMES),
+        },
         "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",
+            "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": {
@@ -3706,7 +4068,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "package_name": "项目管理",
             "create_if_missing": True,
-            "icon": "files-folder",
+            "icon": "briefcase",
             "color": "azure",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
         },
@@ -3819,7 +4181,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "execution_notes": [
             "use this read-only tool before button writes when an agent needs a supported icon or color choice",
-            "current frontend only supports template icons and template colors from this catalog",
+            "current frontend only supports button icons and button colors from this catalog",
             "text/icon color is unified through text_color; there is no separate icon_color",
         ],
         "minimal_example": {
@@ -3913,6 +4275,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",
@@ -3921,6 +4284,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "default placements are header and detail; header maps to frontend top buttons",
             "placement=list configures backend INSIDE row/list buttons; header maps to TOP and detail maps to DETAIL",
             "remove_buttons supports button_id or exact unique button_text",
+            "after a remove_buttons DELETE is sent, the tool verifies deletion by single button_id readback; removed[] returns delete_executed, readback_status, and safe_to_retry_delete=false",
+            "if a removed button returns readback_status=unavailable or still_exists, treat the result as readback pending and do not blindly repeat the delete",
             "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",
         ],
@@ -4054,6 +4419,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",
@@ -4063,6 +4429,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "match_mappings.source_field accepts source schema fields plus system fields 数据ID(-17) and 编号(0); match_mappings compiles to backend matchRules",
             "do not write raw match_rules unless preserving a legacy backend config; match_mappings and match_rules are mutually exclusive",
             "client_key only lets a view_config reference a resource created earlier in the same apply call through associated_item_refs; it is not persisted and cannot deduplicate later apply calls",
+            "remove_associated_item_ids sends DELETE and verifies deletion with one associated-resource pool readback because the backend has no confirmed single-item GET; removed[] returns delete_executed, readback_status, and safe_to_retry_delete=false",
+            "if an associated resource delete returns readback_status=unavailable or still_exists, treat the result as readback pending and do not blindly repeat the delete",
             "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",
         ],
@@ -4129,17 +4497,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.type": [member.value for member in PublicFieldType],
             "field.relation_mode": [member.value for member in PublicRelationMode],
             "field_type_ids": sorted(FIELD_TYPE_ID_ALIASES.keys()),
+            "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),
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
             "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",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
             "profile": "default",
             "app_name": "研发项目管理",
             "package_id": 1001,
-            "icon": "template",
+            "icon": "briefcase",
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
@@ -4235,10 +4608,15 @@ _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",
             "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 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",
+            "multi-app create mode requires each new app item to include a distinct non-template icon and a valid color",
+            "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",
             *_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",
@@ -4263,7 +4641,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "app_name": "研发项目管理",
             "package_id": 1001,
-            "icon": "template",
+            "icon": "briefcase",
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
@@ -4284,6 +4662,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 {
                     "client_key": "employee",
                     "app_name": "员工花名册",
+                    "icon": "business-personalcard",
+                    "color": "emerald",
                     "add_fields": [
                         {"name": "员工名称", "type": "text", "as_data_title": True},
                         {"name": "员工照片", "type": "attachment", "as_data_cover": True},
@@ -4292,6 +4672,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 {
                     "client_key": "worklog",
                     "app_name": "工时表",
+                    "icon": "clock",
+                    "color": "blue",
                     "add_fields": [
                         {"name": "工时标题", "type": "text", "as_data_title": True},
                         {
@@ -4627,10 +5009,13 @@ _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",
             "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",
             "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",
@@ -4749,6 +5134,7 @@ _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",
@@ -4757,6 +5143,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",
             "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",
             "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",
@@ -4832,8 +5220,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",
@@ -4850,6 +5238,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "returns compact current field configuration for one app",
             "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",
             "subtable fields include nested subfields using the same compact field shape",
         ],
         "minimal_example": {
@@ -4971,6 +5361,12 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 "successful create results must return a real backend chart_id",
                 "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",
+                "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",
                 *_VISIBILITY_EXECUTION_NOTES,
             ],
         "minimal_example": {
@@ -5014,9 +5410,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "portal_apply": {
-        "allowed_keys": ["dash_key", "dash_name", "package_id", "publish", "sections", "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",
             "sourceType": "source_type",
             "chartRef": "chart_ref",
             "viewRef": "view_ref",
@@ -5029,20 +5426,35 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "viewRef": "view_ref",
             "dashStyleConfigBO": "dash_style_config",
         },
-        "allowed_values": {"section.source_type": ["chart", "view", "grid", "filter", "text", "link"], **deepcopy(_VISIBILITY_ALLOWED_VALUES)},
-            "execution_notes": [
-                "use exactly one resource mode",
-                "update mode: dash_key",
-                "create mode: package_id + dash_name",
-                "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",
-                "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",
+        "allowed_values": {
+            "section.source_type": ["chart", "view", "grid", "filter", "text", "link"],
+            "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),
+            **deepcopy(_VISIBILITY_ALLOWED_VALUES),
+        },
+        "execution_notes": [
+            "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",
+            "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 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",
+            "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",
             "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",
             "passing visibility and auth together is rejected as VISIBILITY_CONFLICT",
             *_VISIBILITY_EXECUTION_NOTES,
@@ -5051,7 +5463,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "dash_name": "经营门户",
             "package_id": 1001,
+            "icon": "view-grid",
+            "color": "blue",
             "publish": True,
+            "layout_preset": "dashboard_2col",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "sections": [
                 {
@@ -5065,6 +5480,23 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 }
             ],
         },
+        "compat_payload_example": {
+            "name": "经营门户",
+            "package_id": 1001,
+            "layout_preset": "dashboard_2col",
+            "pages": [
+                {
+                    "title": "经营总览",
+                    "components": [
+                        {
+                            "title": "销售趋势",
+                            "source_type": "chart",
+                            "chart_ref": {"app_key": "APP_KEY", "chart_id": "CHART_ID"},
+                        }
+                    ],
+                }
+            ],
+        },
         "minimal_section_example": {
             "title": "订单概览",
             "source_type": "view",