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

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -43,6 +43,7 @@ from ..builder_facade.models import (
     SchemaPlanRequest,
     VisibilityPatch,
     ViewFilterOperator,
+    ViewPartialPatch,
     ViewUpsertPatch,
     ViewsPreset,
     ViewsPlanRequest,
@@ -60,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"]
 
 
@@ -227,6 +236,7 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             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:
@@ -234,6 +244,7 @@ class AiBuilderTools(ToolBase):
                 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 [],
             )
@@ -243,6 +254,7 @@ class AiBuilderTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             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,
@@ -251,6 +263,7 @@ class AiBuilderTools(ToolBase):
                 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 [],
@@ -395,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(
@@ -402,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 [],
             )
 
@@ -410,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:
@@ -417,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 [],
             )
@@ -882,6 +899,7 @@ class AiBuilderTools(ToolBase):
         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:
@@ -889,6 +907,7 @@ class AiBuilderTools(ToolBase):
         raw_request = {
             "app_key": app_key,
             "upsert_buttons": upsert_buttons,
+            "patch_buttons": patch_buttons or [],
             "remove_buttons": remove_buttons,
             "view_configs": view_configs or [],
         }
@@ -936,11 +955,13 @@ class AiBuilderTools(ToolBase):
         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,
@@ -1272,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),
@@ -1853,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:
         """执行应用相关逻辑。"""
@@ -1861,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(
@@ -1872,6 +1895,7 @@ class AiBuilderTools(ToolBase):
                 publish=publish,
                 remove_views=remove_views,
                 upsert_views=upsert_views,
+                patch_views=patch_views or [],
             ),
         )
 
@@ -1882,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,
@@ -1933,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",
@@ -1947,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:
@@ -1955,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,
         )
@@ -1968,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:
@@ -1975,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 [],
                 }
@@ -2550,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:[...]}",
@@ -2696,6 +2770,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_keys": [
             "app_key",
             "upsert_buttons",
+            "patch_buttons",
             "remove_buttons",
             "view_configs",
             "upsert_buttons[].client_key",
@@ -2713,6 +2788,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",
@@ -2728,6 +2807,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         ],
         "aliases": {
             "upsertButtons": "upsert_buttons",
+            "patchButtons": "patch_buttons",
             "removeButtons": "remove_buttons",
             "viewConfigs": "view_configs",
             "clientKey": "client_key",
@@ -2767,15 +2847,19 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "execution_notes": [
             "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 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",
+            "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",
@@ -2792,6 +2876,12 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                     "trigger_link_url": "https://example.com",
                 }
             ],
+            "patch_buttons": [
+                {
+                    "button_text": "同步客户",
+                    "set": {"trigger_link_url": "https://example.com/new"},
+                }
+            ],
             "remove_buttons": [{"button_text": "旧按钮"}],
             "view_configs": [],
         },
@@ -2820,11 +2910,36 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 }
             ],
         },
+        "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_associated_resources_apply": {
         "allowed_keys": [
             "app_key",
             "upsert_resources",
+            "patch_resources",
             "remove_associated_item_ids",
             "reorder_associated_item_ids",
             "view_configs",
@@ -2835,7 +2950,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",
@@ -2844,6 +2967,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         ],
         "aliases": {
             "upsertResources": "upsert_resources",
+            "patchResources": "patch_resources",
             "resources": "upsert_resources",
             "removeAssociatedItemIds": "remove_associated_item_ids",
             "reorderAssociatedItemIds": "reorder_associated_item_ids",
@@ -2855,6 +2979,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "viewKey": "view_key",
             "viewgraphKey": "view_key",
             "reportSource": "report_source",
+            "matchMappings": "match_mappings",
             "matchRules": "match_rules",
             "associatedItemRefs": "associated_item_refs",
             "associatedItemIds": "associated_item_ids",
@@ -2866,10 +2991,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "execution_notes": [
             "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",
-            "client_key lets a view_config reference a resource created earlier in the same apply call through associated_item_refs",
+            "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",
         ],
@@ -2882,7 +3012,13 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                     "graph_type": "view",
                     "target_app_key": "TARGET_APP",
                     "view_key": "VIEW_KEY",
-                    "match_rules": [],
+                    "match_mappings": [{"target_field": "关联员工", "source_field": "数据ID"}],
+                }
+            ],
+            "patch_resources": [
+                {
+                    "associated_item_id": 123,
+                    "set": {"match_mappings": [{"target_field": "状态", "value": "待提交"}]},
                 }
             ],
             "remove_associated_item_ids": [],
@@ -3009,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",
@@ -3208,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",
         ],
@@ -3285,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",
         ],
@@ -3308,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", "upsert_views[].query_conditions"],
+        "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",
@@ -3322,6 +3462,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "queryConditions": "query_conditions",
             "query_condition": "query_conditions",
             "queryCondition": "query_conditions",
+            "patchViews": "patch_views",
             "startField": "start_field",
             "endField": "end_field",
             "titleField": "title_field",
@@ -3346,6 +3487,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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,
@@ -3357,6 +3499,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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": [
@@ -3393,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", "upsert_views[].query_conditions"],
+        "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",
@@ -3407,6 +3565,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "queryConditions": "query_conditions",
             "query_condition": "query_conditions",
             "queryCondition": "query_conditions",
+            "patchViews": "patch_views",
             "startField": "start_field",
             "endField": "end_field",
             "titleField": "title_field",
@@ -3435,6 +3594,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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,
@@ -3447,6 +3607,23 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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,
@@ -3604,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",
@@ -3620,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",
@@ -3631,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": [],
         },
@@ -3642,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",
         ],
@@ -3688,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",