@qingflow-tech/qingflow-app-builder-mcp 1.0.6 → 1.0.8

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -17,7 +17,9 @@ from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError
 from ..json_types import JSONObject
 from ..builder_facade.models import (
+    AssociatedResourcesApplyRequest,
     ChartApplyRequest,
+    CustomButtonsApplyRequest,
     CustomButtonPatch,
     FIELD_TYPE_ID_ALIASES,
     FieldPatch,
@@ -32,6 +34,7 @@ from ..builder_facade.models import (
     LayoutPreset,
     LayoutSectionPatch,
     PortalApplyRequest,
+    PublicButtonPlacement,
     PublicButtonTriggerAction,
     PublicFieldType,
     PublicRelationMode,
@@ -40,6 +43,7 @@ from ..builder_facade.models import (
     SchemaPlanRequest,
     VisibilityPatch,
     ViewFilterOperator,
+    ViewPartialPatch,
     ViewUpsertPatch,
     ViewsPreset,
     ViewsPlanRequest,
@@ -57,6 +61,14 @@ from .solution_tools import SolutionTools
 from .view_tools import ViewTools
 from .workflow_tools import WorkflowTools
 
+
+def _normalize_builder_view_key(value: str) -> str:
+    raw = str(value or "").strip()
+    if raw.startswith("custom:"):
+        return raw.split(":", 1)[1].strip()
+    return raw
+
+
 PUBLIC_STABLE_FLOW_NODE_TYPES = ["start", "approve", "fill", "copy", "webhook", "end"]
 
 
@@ -220,33 +232,42 @@ class AiBuilderTools(ToolBase):
             return self.button_style_catalog_get(profile=profile)
 
         @mcp.tool()
-        def app_custom_button_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
-            return self.app_custom_button_list(profile=profile, app_key=app_key)
-
-        @mcp.tool()
-        def app_custom_button_get(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> JSONObject:
-            return self.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id)
-
-        @mcp.tool()
-        def app_custom_button_create(
+        def app_custom_buttons_apply(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            payload: JSONObject | None = None,
+            upsert_buttons: list[JSONObject] | None = None,
+            patch_buttons: list[JSONObject] | None = None,
+            remove_buttons: list[JSONObject] | None = None,
+            view_configs: list[JSONObject] | None = None,
         ) -> JSONObject:
-            return self.app_custom_button_create(profile=profile, app_key=app_key, payload=payload or {})
+            return self.app_custom_buttons_apply(
+                profile=profile,
+                app_key=app_key,
+                upsert_buttons=upsert_buttons or [],
+                patch_buttons=patch_buttons or [],
+                remove_buttons=remove_buttons or [],
+                view_configs=view_configs or [],
+            )
 
         @mcp.tool()
-        def app_custom_button_update(
+        def app_associated_resources_apply(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            button_id: int = 0,
-            payload: JSONObject | None = None,
+            upsert_resources: list[JSONObject] | None = None,
+            patch_resources: list[JSONObject] | None = None,
+            remove_associated_item_ids: list[int] | None = None,
+            reorder_associated_item_ids: list[int] | None = None,
+            view_configs: list[JSONObject] | None = None,
         ) -> JSONObject:
-            return self.app_custom_button_update(profile=profile, app_key=app_key, button_id=button_id, payload=payload or {})
-
-        @mcp.tool()
-        def app_custom_button_delete(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> JSONObject:
-            return self.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+            return self.app_associated_resources_apply(
+                profile=profile,
+                app_key=app_key,
+                upsert_resources=upsert_resources or [],
+                patch_resources=patch_resources or [],
+                remove_associated_item_ids=remove_associated_item_ids or [],
+                reorder_associated_item_ids=reorder_associated_item_ids or [],
+                view_configs=view_configs or [],
+            )
 
         @mcp.tool()
         def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
@@ -387,6 +408,7 @@ class AiBuilderTools(ToolBase):
             app_key: str = "",
             publish: bool = True,
             upsert_views: list[JSONObject] | None = None,
+            patch_views: list[JSONObject] | None = None,
             remove_views: list[str] | None = None,
         ) -> JSONObject:
             return self.app_views_apply(
@@ -394,6 +416,7 @@ class AiBuilderTools(ToolBase):
                 app_key=app_key,
                 publish=publish,
                 upsert_views=upsert_views or [],
+                patch_views=patch_views or [],
                 remove_views=remove_views or [],
             )
 
@@ -402,6 +425,7 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             upsert_charts: list[JSONObject] | None = None,
+            patch_charts: list[JSONObject] | None = None,
             remove_chart_ids: list[str] | None = None,
             reorder_chart_ids: list[str] | None = None,
         ) -> JSONObject:
@@ -409,6 +433,7 @@ class AiBuilderTools(ToolBase):
                 profile=profile,
                 app_key=app_key,
                 upsert_charts=upsert_charts or [],
+                patch_charts=patch_charts or [],
                 remove_chart_ids=remove_chart_ids or [],
                 reorder_chart_ids=reorder_chart_ids or [],
             )
@@ -867,6 +892,119 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "button_style_catalog_get", "arguments": {"profile": profile}},
         )
 
+    @tool_cn_name("应用按钮声明式应用")
+    def app_custom_buttons_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        upsert_buttons: list[JSONObject],
+        patch_buttons: list[JSONObject] | None = None,
+        remove_buttons: list[JSONObject],
+        view_configs: list[JSONObject] | None = None,
+    ) -> JSONObject:
+        """执行应用按钮 apply 逻辑。"""
+        raw_request = {
+            "app_key": app_key,
+            "upsert_buttons": upsert_buttons,
+            "patch_buttons": patch_buttons or [],
+            "remove_buttons": remove_buttons,
+            "view_configs": view_configs or [],
+        }
+        try:
+            request = CustomButtonsApplyRequest.model_validate(raw_request)
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_custom_buttons_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_custom_buttons_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key or "APP_KEY",
+                        "upsert_buttons": [
+                            {
+                                "button_text": "同步客户",
+                                "style_preset": "primary_blue",
+                                "button_icon": "ex-switch",
+                                "trigger_action": "link",
+                                "trigger_link_url": "https://example.com",
+                            }
+                        ],
+                        "remove_buttons": [],
+                        "view_configs": [],
+                    },
+                },
+            )
+        normalized_args = request.model_dump(mode="json")
+        return _safe_tool_call(
+            lambda: self._facade.app_custom_buttons_apply(profile=profile, request=request),
+            error_code="CUSTOM_BUTTONS_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_custom_buttons_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
+
+    @tool_cn_name("应用关联资源声明式应用")
+    def app_associated_resources_apply(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        upsert_resources: list[JSONObject],
+        remove_associated_item_ids: list[int],
+        reorder_associated_item_ids: list[int],
+        view_configs: list[JSONObject],
+        patch_resources: list[JSONObject] | None = None,
+    ) -> JSONObject:
+        """执行应用关联资源 apply 逻辑。"""
+        raw_request = {
+            "app_key": app_key,
+            "upsert_resources": upsert_resources,
+            "patch_resources": patch_resources or [],
+            "remove_associated_item_ids": remove_associated_item_ids,
+            "reorder_associated_item_ids": reorder_associated_item_ids,
+            "view_configs": view_configs,
+        }
+        try:
+            request = AssociatedResourcesApplyRequest.model_validate(raw_request)
+        except ValidationError as exc:
+            return _validation_failure(
+                str(exc),
+                tool_name="app_associated_resources_apply",
+                exc=exc,
+                suggested_next_call={
+                    "tool_name": "app_associated_resources_apply",
+                    "arguments": {
+                        "profile": profile,
+                        "app_key": app_key or "APP_KEY",
+                        "upsert_resources": [
+                            {
+                                "client_key": "customer_view",
+                                "graph_type": "view",
+                                "target_app_key": "TARGET_APP",
+                                "view_key": "VIEW_KEY",
+                            }
+                        ],
+                        "view_configs": [
+                            {
+                                "view_key": "MAIN_VIEW",
+                                "visible": True,
+                                "limit_type": "select",
+                                "associated_item_refs": ["customer_view"],
+                            }
+                        ],
+                    },
+                },
+            )
+        normalized_args = request.model_dump(mode="json", exclude_none=True)
+        return _safe_tool_call(
+            lambda: self._facade.app_associated_resources_apply(profile=profile, request=request),
+            error_code="ASSOCIATED_RESOURCES_APPLY_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_associated_resources_apply", "arguments": {"profile": profile, **normalized_args}},
+        )
+
     @tool_cn_name("应用按钮列表")
     def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
         """执行应用相关逻辑。"""
@@ -909,7 +1047,10 @@ class AiBuilderTools(ToolBase):
                             "style_preset": "primary_blue",
                             "button_icon": "ex-plus-circle",
                             "trigger_action": "addData",
-                            "trigger_add_data_config": {"related_app_key": "TARGET_APP_KEY", "que_relation": []},
+                            "trigger_add_data_config": {
+                                "target_app_key": "TARGET_APP_KEY",
+                                "field_mappings": [{"source_field": "客户名称", "target_field": "客户"}],
+                            },
                         },
                     },
                 },
@@ -1152,7 +1293,7 @@ class AiBuilderTools(ToolBase):
     @tool_cn_name("视图详情查询")
     def view_get(self, *, profile: str, view_key: str = "", viewgraph_key: str = "") -> JSONObject:
         """执行视图相关逻辑。"""
-        resolved_view_key = str(view_key or viewgraph_key or "").strip()
+        resolved_view_key = _normalize_builder_view_key(str(view_key or viewgraph_key or "").strip())
         normalized_args = {"view_key": resolved_view_key}
         return _safe_tool_call(
             lambda: self._facade.view_get(profile=profile, view_key=resolved_view_key),
@@ -1733,6 +1874,7 @@ class AiBuilderTools(ToolBase):
         app_key: str,
         publish: bool = True,
         upsert_views: list[JSONObject],
+        patch_views: list[JSONObject] | None = None,
         remove_views: list[str],
     ) -> JSONObject:
         """执行应用相关逻辑。"""
@@ -1741,6 +1883,7 @@ class AiBuilderTools(ToolBase):
             app_key=app_key,
             publish=publish,
             upsert_views=upsert_views,
+            patch_views=patch_views or [],
             remove_views=remove_views,
         )
         return self._retry_after_self_lock_release(
@@ -1752,6 +1895,7 @@ class AiBuilderTools(ToolBase):
                 publish=publish,
                 remove_views=remove_views,
                 upsert_views=upsert_views,
+                patch_views=patch_views or [],
             ),
         )
 
@@ -1762,9 +1906,53 @@ class AiBuilderTools(ToolBase):
         app_key: str,
         publish: bool = True,
         upsert_views: list[JSONObject],
+        patch_views: list[JSONObject],
         remove_views: list[str],
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
+        if patch_views:
+            try:
+                parsed_views = [ViewUpsertPatch.model_validate(item) for item in (upsert_views or [])]
+                parsed_patch_views = [ViewPartialPatch.model_validate(item) for item in patch_views]
+            except ValidationError as exc:
+                return _visibility_validation_failure(
+                    str(exc),
+                    tool_name="app_views_apply",
+                    exc=exc,
+                    suggested_next_call={
+                        "tool_name": "app_views_apply",
+                        "arguments": {
+                            "profile": profile,
+                            "app_key": app_key,
+                            "publish": publish,
+                            "upsert_views": upsert_views or [],
+                            "patch_views": [
+                                {"view_key": "VIEW_KEY", "set": {"query_conditions": {"enabled": True, "rows": [["字段A"]]}}},
+                            ],
+                            "remove_views": remove_views or [],
+                        },
+                    },
+                )
+            normalized_args = {
+                "app_key": app_key,
+                "publish": publish,
+                "upsert_views": [view.model_dump(mode="json") for view in parsed_views],
+                "patch_views": [patch.model_dump(mode="json") for patch in parsed_patch_views],
+                "remove_views": list(remove_views or []),
+            }
+            return _safe_tool_call(
+                lambda: self._facade.app_views_apply(
+                    profile=profile,
+                    app_key=app_key,
+                    publish=publish,
+                    upsert_views=parsed_views,
+                    patch_views=parsed_patch_views,
+                    remove_views=list(remove_views or []),
+                ),
+                error_code="VIEWS_APPLY_FAILED",
+                normalized_args=normalized_args,
+                suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **normalized_args}},
+            )
         plan_result = self._rewrite_plan_result_for_apply(
             result=self.app_views_plan(
                 profile=profile,
@@ -1813,6 +2001,7 @@ class AiBuilderTools(ToolBase):
                 app_key=str(plan_args.get("app_key") or app_key),
                 publish=publish,
                 upsert_views=parsed_views,
+                patch_views=[],
                 remove_views=list(plan_args.get("remove_views") or remove_views),
             ),
             error_code="VIEWS_APPLY_FAILED",
@@ -1827,6 +2016,7 @@ class AiBuilderTools(ToolBase):
         profile: str,
         app_key: str,
         upsert_charts: list[JSONObject],
+        patch_charts: list[JSONObject] | None = None,
         remove_chart_ids: list[str],
         reorder_chart_ids: list[str],
     ) -> JSONObject:
@@ -1835,6 +2025,7 @@ class AiBuilderTools(ToolBase):
             profile=profile,
             app_key=app_key,
             upsert_charts=upsert_charts,
+            patch_charts=patch_charts or [],
             remove_chart_ids=remove_chart_ids,
             reorder_chart_ids=reorder_chart_ids,
         )
@@ -1848,6 +2039,7 @@ class AiBuilderTools(ToolBase):
         upsert_charts: list[JSONObject],
         remove_chart_ids: list[str],
         reorder_chart_ids: list[str],
+        patch_charts: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
         try:
@@ -1855,6 +2047,7 @@ class AiBuilderTools(ToolBase):
                 {
                     "app_key": app_key,
                     "upsert_charts": upsert_charts or [],
+                    "patch_charts": patch_charts or [],
                     "remove_chart_ids": remove_chart_ids or [],
                     "reorder_chart_ids": reorder_chart_ids or [],
                 }
@@ -2430,6 +2623,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_values": deepcopy(_VISIBILITY_ALLOWED_VALUES),
         "execution_notes": [
             "create or update package metadata, visibility, grouping, and ordering in one call",
+            "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:[...]}",
@@ -2572,115 +2766,271 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
         },
     },
-    "app_custom_button_list": {
-        "allowed_keys": ["app_key"],
-        "aliases": {},
-        "allowed_values": {},
-        "minimal_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-        },
-    },
-    "app_custom_button_get": {
-        "allowed_keys": ["app_key", "button_id"],
-        "aliases": {"buttonId": "button_id"},
-        "allowed_values": {},
-        "minimal_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-            "button_id": 1001,
-        },
-    },
-    "app_custom_button_create": {
-        "allowed_keys": ["app_key", "payload"],
+    "app_custom_buttons_apply": {
+        "allowed_keys": [
+            "app_key",
+            "upsert_buttons",
+            "patch_buttons",
+            "remove_buttons",
+            "view_configs",
+            "upsert_buttons[].client_key",
+            "upsert_buttons[].button_id",
+            "upsert_buttons[].button_text",
+            "upsert_buttons[].style_preset",
+            "upsert_buttons[].background_color",
+            "upsert_buttons[].text_color",
+            "upsert_buttons[].button_icon",
+            "upsert_buttons[].trigger_action",
+            "upsert_buttons[].trigger_link_url",
+            "upsert_buttons[].trigger_add_data_config",
+            "upsert_buttons[].trigger_add_data_config.target_app_key",
+            "upsert_buttons[].trigger_add_data_config.field_mappings",
+            "upsert_buttons[].trigger_add_data_config.field_mappings[].source_field",
+            "upsert_buttons[].trigger_add_data_config.field_mappings[].target_field",
+            "upsert_buttons[].trigger_add_data_config.default_values",
+            "patch_buttons[].button_id",
+            "patch_buttons[].button_text",
+            "patch_buttons[].set",
+            "patch_buttons[].unset",
+            "view_configs[].view_key",
+            "view_configs[].mode",
+            "view_configs[].buttons",
+            "view_configs[].buttons[].button_ref",
+            "view_configs[].buttons[].placement",
+            "view_configs[].buttons[].primary",
+            "view_configs[].buttons[].button_limit",
+            "view_configs[].buttons[].button_formula",
+            "view_configs[].buttons[].button_formula_type",
+            "view_configs[].buttons[].print_tpls",
+            "remove_buttons[].button_id",
+            "remove_buttons[].button_text",
+        ],
         "aliases": {
-            "payload.buttonText": "payload.button_text",
-            "payload.stylePreset": "payload.style_preset",
-            "payload.backgroundColor": "payload.background_color",
-            "payload.textColor": "payload.text_color",
-            "payload.buttonIcon": "payload.button_icon",
-            "payload.triggerAction": "payload.trigger_action",
-            "payload.triggerLinkUrl": "payload.trigger_link_url",
-            "payload.triggerAddDataConfig": "payload.trigger_add_data_config",
-            "payload.externalQrobotConfig": "payload.external_qrobot_config",
-            "payload.customButtonExternalQRobotRelationVO": "payload.external_qrobot_config",
-            "payload.triggerWingsConfig": "payload.trigger_wings_config",
+            "upsertButtons": "upsert_buttons",
+            "patchButtons": "patch_buttons",
+            "removeButtons": "remove_buttons",
+            "viewConfigs": "view_configs",
+            "clientKey": "client_key",
+            "buttonId": "button_id",
+            "buttonText": "button_text",
+            "stylePreset": "style_preset",
+            "backgroundColor": "background_color",
+            "textColor": "text_color",
+            "buttonIcon": "button_icon",
+            "triggerAction": "trigger_action",
+            "triggerLinkUrl": "trigger_link_url",
+            "triggerAddDataConfig": "trigger_add_data_config",
+            "targetAppKey": "trigger_add_data_config.target_app_key",
+            "fieldMappings": "trigger_add_data_config.field_mappings",
+            "defaultValues": "trigger_add_data_config.default_values",
+            "mode": "view_configs[].mode",
+            "applyMode": "view_configs[].mode",
+            "buttonRef": "view_configs[].buttons[].button_ref",
+            "beingMain": "view_configs[].buttons[].primary",
+            "buttonLimit": "view_configs[].buttons[].button_limit",
+            "visibleWhen": "view_configs[].buttons[].button_limit",
+            "buttonFormula": "view_configs[].buttons[].button_formula",
+            "buttonFormulaType": "view_configs[].buttons[].button_formula_type",
+            "printTpls": "view_configs[].buttons[].print_tpls",
+            "externalQrobotConfig": "external_qrobot_config",
+            "customButtonExternalQRobotRelationVO": "external_qrobot_config",
+            "triggerWingsConfig": "trigger_wings_config",
         },
         "allowed_values": {
-            "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
-            "payload.style_preset": [item["key"] for item in BUTTON_STYLE_PRESETS],
-            "payload.button_icon": list(BUTTON_ICONS),
-            "payload.background_color": list(BUTTON_BACKGROUND_COLORS),
-            "payload.text_color": list(BUTTON_TEXT_COLORS),
+            "upsert_buttons[].trigger_action": [member.value for member in PublicButtonTriggerAction],
+            "upsert_buttons[].style_preset": [item["key"] for item in BUTTON_STYLE_PRESETS],
+            "upsert_buttons[].button_icon": list(BUTTON_ICONS),
+            "upsert_buttons[].background_color": list(BUTTON_BACKGROUND_COLORS),
+            "upsert_buttons[].text_color": list(BUTTON_TEXT_COLORS),
+            "view_configs[].mode": ["merge", "replace"],
+            "view_configs[].buttons[].placement": [member.value for member in PublicButtonPlacement],
         },
         "execution_notes": [
-            "custom button writes now auto-publish the current app draft as a fixed closing step",
+            "this is the default custom-button write path; old list/get/create/update/delete tools are hidden from the public agent surface",
+            "use patch_buttons for partial parameter replacement on existing buttons; the tool reads current button detail, merges patch_buttons[].set/unset, then submits the backend full-save payload internally",
+            "button_id targets an existing button; without button_id, button_text is used as an exact unique upsert key, otherwise a new button is created",
+            "for addData buttons, use trigger_add_data_config.target_app_key plus field_mappings/default_values; field_mappings compiles to backend queRelation",
+            "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",
+            "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",
+            "view_configs[].mode defaults to merge; use mode=replace or an explicit empty buttons list to replace/clear a view's custom button bindings",
+            "advanced view button binding supports button_limit, button_formula, button_formula_type, and print_tpls when visibility or print-template behavior is required",
+            "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",
+            "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",
-            "payload accepts either style_preset + optional button_icon, or explicit button_icon/background_color/text_color from button_style_catalog_get",
-            "for addData buttons, put field mappings in payload.trigger_add_data_config.que_relation",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "payload": {
-                "button_text": "新增记录",
-                "style_preset": "primary_blue",
-                "button_icon": "ex-plus-circle",
-                "trigger_action": "link",
-                "trigger_link_url": "https://example.com",
-            },
+            "upsert_buttons": [
+                {
+                    "button_text": "同步客户",
+                    "style_preset": "primary_blue",
+                    "button_icon": "ex-switch",
+                    "trigger_action": "link",
+                    "trigger_link_url": "https://example.com",
+                }
+            ],
+            "patch_buttons": [
+                {
+                    "button_text": "同步客户",
+                    "set": {"trigger_link_url": "https://example.com/new"},
+                }
+            ],
+            "remove_buttons": [{"button_text": "旧按钮"}],
+            "view_configs": [],
+        },
+        "add_data_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_buttons": [
+                {
+                    "client_key": "add_order",
+                    "button_text": "新增订单",
+                    "style_preset": "neutral_outline",
+                    "button_icon": "ex-plus-circle",
+                    "trigger_action": "addData",
+                    "trigger_add_data_config": {
+                        "target_app_key": "TARGET_APP",
+                        "field_mappings": [{"source_field": "客户名称", "target_field": "客户"}],
+                        "default_values": {"状态": "待提交"},
+                    },
+                }
+            ],
+            "remove_buttons": [],
+            "view_configs": [
+                {
+                    "view_key": "VIEW_KEY",
+                    "buttons": [{"button_ref": "add_order", "placement": "detail", "primary": True}],
+                }
+            ],
+        },
+        "relation_current_record_example": {
+            "profile": "default",
+            "app_key": "EMPLOYEE_APP",
+            "upsert_buttons": [
+                {
+                    "client_key": "add_worklog",
+                    "button_text": "快捷添加工时",
+                    "style_preset": "neutral_outline",
+                    "button_icon": "ex-plus-circle",
+                    "trigger_action": "addData",
+                    "trigger_add_data_config": {
+                        "target_app_key": "WORKLOG_APP",
+                        "field_mappings": [{"source_field": "数据ID", "target_field": "关联员工"}],
+                        "default_values": {"状态": "待提交"},
+                    },
+                }
+            ],
+            "view_configs": [
+                {
+                    "view_key": "RAW_VIEW_KEY",
+                    "buttons": [{"button_ref": "add_worklog", "placement": "detail", "primary": True}],
+                }
+            ],
         },
     },
-    "app_custom_button_update": {
-        "allowed_keys": ["app_key", "button_id", "payload"],
+    "app_associated_resources_apply": {
+        "allowed_keys": [
+            "app_key",
+            "upsert_resources",
+            "patch_resources",
+            "remove_associated_item_ids",
+            "reorder_associated_item_ids",
+            "view_configs",
+            "upsert_resources[].client_key",
+            "upsert_resources[].associated_item_id",
+            "upsert_resources[].graph_type",
+            "upsert_resources[].target_app_key",
+            "upsert_resources[].view_key",
+            "upsert_resources[].chart_key",
+            "upsert_resources[].report_source",
+            "upsert_resources[].match_mappings",
+            "upsert_resources[].match_mappings[].target_field",
+            "upsert_resources[].match_mappings[].source_field",
+            "upsert_resources[].match_mappings[].value",
+            "upsert_resources[].match_mappings[].operator",
+            "upsert_resources[].match_rules",
+            "patch_resources[].associated_item_id",
+            "patch_resources[].set",
+            "patch_resources[].unset",
+            "view_configs[].view_key",
+            "view_configs[].visible",
+            "view_configs[].limit_type",
+            "view_configs[].associated_item_ids",
+            "view_configs[].associated_item_refs",
+        ],
         "aliases": {
-            "buttonId": "button_id",
-            "payload.buttonText": "payload.button_text",
-            "payload.stylePreset": "payload.style_preset",
-            "payload.backgroundColor": "payload.background_color",
-            "payload.textColor": "payload.text_color",
-            "payload.buttonIcon": "payload.button_icon",
-            "payload.triggerAction": "payload.trigger_action",
-            "payload.triggerLinkUrl": "payload.trigger_link_url",
-            "payload.triggerAddDataConfig": "payload.trigger_add_data_config",
-            "payload.externalQrobotConfig": "payload.external_qrobot_config",
-            "payload.customButtonExternalQRobotRelationVO": "payload.external_qrobot_config",
-            "payload.triggerWingsConfig": "payload.trigger_wings_config",
+            "upsertResources": "upsert_resources",
+            "patchResources": "patch_resources",
+            "resources": "upsert_resources",
+            "removeAssociatedItemIds": "remove_associated_item_ids",
+            "reorderAssociatedItemIds": "reorder_associated_item_ids",
+            "viewConfigs": "view_configs",
+            "associatedItemId": "associated_item_id",
+            "graphType": "graph_type",
+            "targetAppKey": "target_app_key",
+            "chartKey": "chart_key",
+            "viewKey": "view_key",
+            "viewgraphKey": "view_key",
+            "reportSource": "report_source",
+            "matchMappings": "match_mappings",
+            "matchRules": "match_rules",
+            "associatedItemRefs": "associated_item_refs",
+            "associatedItemIds": "associated_item_ids",
         },
         "allowed_values": {
-            "payload.trigger_action": [member.value for member in PublicButtonTriggerAction],
-            "payload.style_preset": [item["key"] for item in BUTTON_STYLE_PRESETS],
-            "payload.button_icon": list(BUTTON_ICONS),
-            "payload.background_color": list(BUTTON_BACKGROUND_COLORS),
-            "payload.text_color": list(BUTTON_TEXT_COLORS),
+            "upsert_resources[].graph_type": ["chart", "view"],
+            "upsert_resources[].report_source": ["app", "dataset"],
+            "view_configs[].limit_type": ["all", "select"],
         },
         "execution_notes": [
-            "custom button writes now auto-publish the current app draft as a fixed closing step",
-            "background_color and text_color cannot both be white",
-            "payload accepts either style_preset + optional button_icon, or explicit button_icon/background_color/text_color from button_style_catalog_get",
-            "for addData buttons, put field mappings in payload.trigger_add_data_config.que_relation",
+            "this is the default associated report/view path; it manages both the app-level associated resource pool and per-view display config",
+            "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; it is not chart_id, chart_key, or view_key",
+            "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",
+            "graph_type=view uses view_key and internally compiles to the Qingflow view source; graph_type=chart uses chart_key and defaults to report_source=app",
+            "report_source=app maps to BI_QINGFLOW; report_source=dataset maps to BI_DATASET; do not pass raw backend sourceType",
+            "use match_mappings for associated view/report filtering; dynamic conditions use source_field and static conditions use value",
+            "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",
+            "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",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "button_id": 1001,
-            "payload": {
-                "button_text": "查看详情",
-                "style_preset": "neutral_outline",
-                "button_icon": "ex-edit",
-                "trigger_action": "link",
-                "trigger_link_url": "https://example.com/detail",
-            },
-        },
-    },
-    "app_custom_button_delete": {
-        "allowed_keys": ["app_key", "button_id"],
-        "aliases": {"buttonId": "button_id"},
-        "allowed_values": {},
-        "minimal_example": {
-            "profile": "default",
-            "app_key": "APP_KEY",
-            "button_id": 1001,
+            "upsert_resources": [
+                {
+                    "client_key": "customer_view",
+                    "graph_type": "view",
+                    "target_app_key": "TARGET_APP",
+                    "view_key": "VIEW_KEY",
+                    "match_mappings": [{"target_field": "关联员工", "source_field": "数据ID"}],
+                }
+            ],
+            "patch_resources": [
+                {
+                    "associated_item_id": 123,
+                    "set": {"match_mappings": [{"target_field": "状态", "value": "待提交"}]},
+                }
+            ],
+            "remove_associated_item_ids": [],
+            "reorder_associated_item_ids": [],
+            "view_configs": [
+                {
+                    "view_key": "MAIN_VIEW",
+                    "visible": True,
+                    "limit_type": "select",
+                    "associated_item_refs": ["customer_view"],
+                }
+            ],
         },
     },
     "app_schema_plan": {
@@ -2709,6 +3059,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.customBtnTextStatus": "field.custom_button_text_enabled",
             "field.customBtnText": "field.custom_button_text",
             "field.subfieldUpdates": "field.subfield_updates",
+            "field.asDataTitle": "field.as_data_title",
+            "field.asDataCover": "field.as_data_cover",
         },
         "allowed_values": {
             "field.type": [member.value for member in PublicFieldType],
@@ -2728,7 +3080,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
-            "add_fields": [{"name": "项目名称", "type": "text"}],
+            "add_fields": [{"name": "项目名称", "type": "text", "as_data_title": True}],
             "update_fields": [],
             "remove_fields": [],
         },
@@ -2775,6 +3127,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field.customBtnTextStatus": "field.custom_button_text_enabled",
             "field.customBtnText": "field.custom_button_text",
             "field.subfieldUpdates": "field.subfield_updates",
+            "field.asDataTitle": "field.as_data_title",
+            "field.asDataCover": "field.as_data_cover",
         },
         "allowed_values": {
             "field.type": [member.value for member in PublicFieldType],
@@ -2791,6 +3145,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "create mode: package_id + app_name + create_if_missing=true",
             "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
             *_VISIBILITY_EXECUTION_NOTES,
+            "update_fields is the field-level partial update path; it reads current form schema and preserves untouched field config",
             "multiple relation fields are backend-risky; read verification.relation_field_limit_verified and warnings before declaring the schema stable",
             "backend 49614 is normalized to MULTIPLE_RELATION_FIELDS_UNSUPPORTED with a workaround message",
             "relation_mode=multiple maps to referenceConfig.optionalDataNum=0",
@@ -2806,6 +3161,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "code block outputs must be emitted through qf_output assignment; use qf_output = {...} or assign qf_output after building the result object, never const/let qf_output =",
             "builder automatically normalizes const/let qf_output assignments on write and rejects output-bound code blocks that still do not contain a valid qf_output assignment",
             "code_block_binding and q_linker_binding target fields are limited to text, long_text, number, amount, date, datetime, single_select, multi_select, and boolean",
+            "data title is required: mark exactly one top-level field with as_data_title=true; use a readable name/number/date-like field",
+            "data cover is optional: mark at most one top-level attachment field with as_data_cover=true",
         ],
         "minimal_example": {
             "profile": "default",
@@ -2816,7 +3173,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
             "publish": True,
-            "add_fields": [{"name": "项目名称", "type": "text"}],
+            "add_fields": [
+                {"name": "项目名称", "type": "text", "as_data_title": True},
+                {"name": "项目封面", "type": "attachment", "as_data_cover": True},
+            ],
             "update_fields": [],
             "remove_fields": [],
         },
@@ -2985,6 +3345,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "allowed_values": {"mode": [member.value for member in LayoutApplyMode]},
         "execution_notes": [
+            "mode=merge is the layout partial update path: mentioned sections are merged and unmentioned fields are preserved",
+            "mode=replace is full layout replacement and should be used only when intentionally rewriting all sections",
             "layout verification is split into layout_verified and layout_summary_verified",
             "LAYOUT_SUMMARY_UNVERIFIED means raw form readback is stronger than the compact summary",
         ],
@@ -3062,6 +3424,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         ],
         "execution_notes": [
             "public flow building is intentionally limited to linear workflows",
+            "app_flow_apply is replace-only; do not treat node snippets as partial patches",
             "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
             "workflow verification only covers linear node structure in the public tool surface",
         ],
@@ -3085,7 +3448,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_plan": {
-        "allowed_keys": ["app_key", "upsert_views", "remove_views", "preset", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility"],
+        "allowed_keys": ["app_key", "upsert_views", "patch_views", "remove_views", "preset", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility", "upsert_views[].query_conditions", "patch_views[].view_key", "patch_views[].name", "patch_views[].set", "patch_views[].unset"],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -3096,6 +3459,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "kanban": "board",
             "filter_rules": "filters",
             "filterRules": "filters",
+            "queryConditions": "query_conditions",
+            "query_condition": "query_conditions",
+            "queryCondition": "query_conditions",
+            "patchViews": "patch_views",
             "startField": "start_field",
             "endField": "end_field",
             "titleField": "title_field",
@@ -3118,6 +3485,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "execution_notes": [
             "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",
+            "view associated report/view display is now configured through app_associated_resources_apply, not app_views_apply",
             "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",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
@@ -3127,6 +3498,41 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_views": [],
         },
+        "query_conditions_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "patch_views": [
+                {
+                    "view_key": "VIEW_KEY",
+                    "set": {
+                        "query_conditions": {
+                            "enabled": True,
+                            "rows": [["客户名称", "负责人"], ["创建时间"]],
+                        }
+                    },
+                }
+            ],
+            "remove_views": [],
+        },
+        "full_upsert_query_conditions_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_views": [
+                {
+                    "name": "客户查询视图",
+                    "type": "table",
+                    "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
+                    "filters": [{"field_name": "客户状态", "operator": "eq", "value": "有效"}],
+                    "query_conditions": {
+                        "enabled": True,
+                        "exact": False,
+                        "hide_before_query": False,
+                        "rows": [["客户名称", "负责人"], ["创建时间"]],
+                    },
+                }
+            ],
+            "remove_views": [],
+        },
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -3145,7 +3551,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_views_apply": {
-        "allowed_keys": ["app_key", "publish", "upsert_views", "remove_views", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility"],
+        "allowed_keys": ["app_key", "publish", "upsert_views", "patch_views", "remove_views", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility", "upsert_views[].query_conditions", "patch_views[].view_key", "patch_views[].name", "patch_views[].set", "patch_views[].unset"],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -3156,6 +3562,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "kanban": "board",
             "filter_rules": "filters",
             "filterRules": "filters",
+            "queryConditions": "query_conditions",
+            "query_condition": "query_conditions",
+            "queryCondition": "query_conditions",
+            "patchViews": "patch_views",
             "startField": "start_field",
             "endField": "end_field",
             "titleField": "title_field",
@@ -3178,10 +3588,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "apply may return partial_success when some views land and others fail",
             "when duplicate view names exist, supply view_key to target the exact view",
-            "read back app_get_views after any failed or partial view apply",
+            "read back app_get after any failed or partial view apply",
             "view existence verification and saved-filter verification are separate; treat filters as unverified until verification.view_filters_verified is true",
             "buttons omitted preserves existing button config; buttons=[] clears all buttons; buttons=[...] replaces the full button config",
             "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
+            "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
+            "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
+            "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",
+            "view associated report/view display is now 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",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
@@ -3192,6 +3606,43 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "upsert_views": [{"name": "全部数据", "type": "table", "columns": ["项目名称"], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
             "remove_views": [],
         },
+        "query_conditions_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "patch_views": [
+                {
+                    "view_key": "VIEW_KEY",
+                    "set": {
+                        "query_conditions": {
+                            "enabled": True,
+                            "rows": [["客户名称", "负责人"], ["创建时间"]],
+                        }
+                    },
+                }
+            ],
+            "remove_views": [],
+        },
+        "full_upsert_query_conditions_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "upsert_views": [
+                {
+                    "name": "客户查询视图",
+                    "type": "table",
+                    "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
+                    "filters": [{"field_name": "客户状态", "operator": "eq", "value": "有效"}],
+                    "query_conditions": {
+                        "enabled": True,
+                        "exact": False,
+                        "hide_before_query": False,
+                        "rows": [["客户名称", "负责人"], ["创建时间"]],
+                    },
+                }
+            ],
+            "remove_views": [],
+        },
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -3215,12 +3666,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
-            "returns builder-side app configuration summary and editability",
-            "use this as the default builder discovery read before fields/layout/views/flow/charts detail reads",
+            "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",
             "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 id required by app_associated_resources_apply.view_configs.associated_item_ids; do not pass chart_id there",
         ],
         "minimal_example": {
             "profile": "default",
@@ -3260,7 +3713,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_values": {},
         "execution_notes": [
             "returns compact current view inventory for one app",
-            "use this before app_views_apply when you need exact current view keys",
+            "compatibility/specialized inventory tool; default builder discovery should start with app_get",
+            "use this before app_views_apply only when you need an exact current view inventory beyond app_get",
             "view items include visibility_summary when backend view auth is readable",
         ],
         "minimal_example": {
@@ -3287,7 +3741,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_values": {},
         "execution_notes": [
             "returns a compact current chart inventory for one app",
-            "use this before app_charts_apply when you need exact current chart_id values",
+            "compatibility/specialized inventory tool; default builder discovery should start with app_get",
+            "use this before app_charts_apply when you need exact current chart_id values beyond the app_get summary",
             "chart summaries do not include full qingbi config payloads",
             "chart items include visibility_summary when QingBI base info is readable",
         ],
@@ -3326,8 +3781,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_charts_apply": {
-        "allowed_keys": ["app_key", "upsert_charts", "remove_chart_ids", "reorder_chart_ids", "upsert_charts[].visibility"],
+        "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"],
         "aliases": {
+            "patchCharts": "patch_charts",
             "chart.id": "chart.chart_id",
             "chart.type": "chart.chart_type",
             "chart.dimension_fields": "chart.dimension_field_ids",
@@ -3342,6 +3798,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
             "execution_notes": [
                 "app_charts_apply is immediate-live and does not publish",
+                "use patch_charts for partial parameter replacement on existing charts; the tool reads current chart base/config, merges patch_charts[].set/unset, then submits full QingBI base/config payloads internally",
                 "chart matching precedence is chart_id first, then exact unique chart name",
                 "when chart names are not unique, supply chart_id instead of guessing by name",
                 "successful create results must return a real backend chart_id",
@@ -3353,6 +3810,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "app_key": "APP_KEY",
             "upsert_charts": [{"name": "数据总量", "chart_type": "target", "indicator_field_ids": [], "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE)}],
+            "patch_charts": [{"chart_id": "CHART_ID", "set": {"name": "数据总量-新版"}}],
             "remove_chart_ids": [],
             "reorder_chart_ids": [],
         },
@@ -3364,6 +3822,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "returns one builder-side view definition detail",
             "does not return record data; use user-side view_get or record_list for runtime rows",
+            "view_key is a raw builder view key; if a record-data custom:VIEW_KEY value is passed, the tool normalizes it to VIEW_KEY",
             "use this after builder portal_get when a component references a view_ref.view_key",
             "returns normalized view visibility when backend auth is readable",
         ],
@@ -3410,6 +3869,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 "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",