@qingflow-tech/qingflow-app-builder-mcp 1.0.5 → 1.0.7

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,
@@ -220,33 +223,38 @@ 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,
+            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 [],
+                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,
+            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 [],
+                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:
@@ -867,6 +875,115 @@ 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],
+        remove_buttons: list[JSONObject],
+        view_configs: list[JSONObject] | None = None,
+    ) -> JSONObject:
+        """执行应用按钮 apply 逻辑。"""
+        raw_request = {
+            "app_key": app_key,
+            "upsert_buttons": upsert_buttons,
+            "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],
+    ) -> JSONObject:
+        """执行应用关联资源 apply 逻辑。"""
+        raw_request = {
+            "app_key": app_key,
+            "upsert_resources": upsert_resources,
+            "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 +1026,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": "客户"}],
+                            },
                         },
                     },
                 },
@@ -2572,115 +2692,209 @@ _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",
+            "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",
+            "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",
+            "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",
+            "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",
+            "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[].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 is accepted as an experimental row/list placement, but some backend deployments reject it; if that happens, the tool returns LIST_BUTTON_BACKEND_UNSUPPORTED and still applies header/detail placements when they were part of the same view config",
+            "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",
+                }
+            ],
+            "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}],
+                }
+            ],
         },
     },
-    "app_custom_button_update": {
-        "allowed_keys": ["app_key", "button_id", "payload"],
+    "app_associated_resources_apply": {
+        "allowed_keys": [
+            "app_key",
+            "upsert_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_rules",
+            "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",
+            "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",
+            "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",
+            "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",
+            "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",
+            "client_key lets a view_config reference a resource created earlier in the same apply call through associated_item_refs",
+            "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_rules": [],
+                }
+            ],
+            "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 +2923,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 +2944,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 +2991,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],
@@ -2806,6 +3024,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 +3036,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": [],
         },
@@ -3085,7 +3308,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", "remove_views", "preset", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility", "upsert_views[].query_conditions"],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -3096,6 +3319,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "kanban": "board",
             "filter_rules": "filters",
             "filterRules": "filters",
+            "queryConditions": "query_conditions",
+            "query_condition": "query_conditions",
+            "queryCondition": "query_conditions",
             "startField": "start_field",
             "endField": "end_field",
             "titleField": "title_field",
@@ -3118,6 +3344,9 @@ _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",
+            "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 +3356,25 @@ _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",
+            "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 +3393,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", "remove_views", "upsert_views[].view_key", "upsert_views[].buttons", "upsert_views[].visibility", "upsert_views[].query_conditions"],
         "aliases": {
             "fields": "columns",
             "column_names": "columns",
@@ -3156,6 +3404,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "kanban": "board",
             "filter_rules": "filters",
             "filterRules": "filters",
+            "queryConditions": "query_conditions",
+            "query_condition": "query_conditions",
+            "queryCondition": "query_conditions",
             "startField": "start_field",
             "endField": "end_field",
             "titleField": "title_field",
@@ -3178,10 +3429,13 @@ _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",
+            "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 +3446,26 @@ _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,
+            "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 +3489,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 +3536,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 +3564,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",
         ],