@josephyan/qingflow-app-builder-mcp 1.1.16 → 1.1.18

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -49,6 +49,8 @@ from ..builder_facade.models import (
     ViewUpsertPatch,
     ViewsPreset,
     ViewsPlanRequest,
+    public_view_partial_payload,
+    public_view_upsert_payload,
 )
 from ..builder_facade.service import AiBuilderFacade, INTEGRATION_OUTPUT_TARGET_FIELD_TYPES
 from ..solution.compiler.icon_utils import (
@@ -575,17 +577,18 @@ class AiBuilderTools(ToolBase):
             visibility: JSONObject | None = None,
             create_if_missing: bool | None = None,
             publish: bool = True,
+            form: list[JSONObject] | None = None,
             add_fields: list[JSONObject] | None = None,
             update_fields: list[JSONObject] | None = None,
             remove_fields: list[JSONObject] | None = None,
             apps: list[JSONObject] | None = None,
         ) -> JSONObject:
             if apps is not None:
-                if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
+                if app_key or app_name or app_title or form or add_fields or update_fields or remove_fields:
                     return _config_failure(
                         tool_name="app_schema_apply",
                         message="app_schema_apply multi-app mode accepts package_id plus apps only; create_if_missing is optional.",
-                        fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
+                        fix_hint="Put per-app form in apps[].form when using batch mode.",
                     )
                 if package_id is None:
                     return _config_failure(
@@ -600,6 +603,7 @@ class AiBuilderTools(ToolBase):
                     create_if_missing=True if create_if_missing is None else bool(create_if_missing),
                     publish=publish,
                     apps=apps,
+                    form=None,
                     add_fields=[],
                     update_fields=[],
                     remove_fields=[],
@@ -636,10 +640,11 @@ class AiBuilderTools(ToolBase):
                 visibility=visibility,
                 create_if_missing=effective_create_if_missing,
                 publish=publish,
+                form=form or [],
                 add_fields=add_fields or [],
                 update_fields=update_fields or [],
                 remove_fields=remove_fields or [],
-                apps=[],
+                apps=None,
             )
 
         @mcp.tool()
@@ -2018,6 +2023,7 @@ class AiBuilderTools(ToolBase):
         profile: str,
         app_key: str,
         upsert_views: list[JSONObject] | None = None,
+        patch_views: list[JSONObject] | None = None,
         remove_views: list[str] | None = None,
         preset: str | None = None,
     ) -> JSONObject:
@@ -2036,6 +2042,7 @@ class AiBuilderTools(ToolBase):
                 {
                     "app_key": app_key,
                     "upsert_views": upsert_views or [],
+                    "patch_views": patch_views or [],
                     "remove_views": remove_views or [],
                     "preset": preset,
                 }
@@ -2052,6 +2059,7 @@ class AiBuilderTools(ToolBase):
                         "app_key": app_key,
                         "preset": "default_table",
                         "upsert_views": [],
+                        "patch_views": [],
                         "remove_views": [],
                     },
                 },
@@ -2059,8 +2067,24 @@ class AiBuilderTools(ToolBase):
         return _safe_tool_call(
             lambda: self._facade.app_views_plan(profile=profile, request=request),
             error_code="VIEWS_PLAN_FAILED",
-            normalized_args=request.model_dump(mode="json"),
-            suggested_next_call={"tool_name": "app_views_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
+            normalized_args={
+                "app_key": request.app_key,
+                "upsert_views": [public_view_upsert_payload(view) for view in request.upsert_views],
+                "patch_views": [public_view_partial_payload(patch) for patch in request.patch_views],
+                "remove_views": list(request.remove_views),
+                "preset": request.preset.value if request.preset is not None else None,
+            },
+            suggested_next_call={
+                "tool_name": "app_views_plan",
+                "arguments": {
+                    "profile": profile,
+                    "app_key": request.app_key,
+                    "upsert_views": [public_view_upsert_payload(view) for view in request.upsert_views],
+                    "patch_views": [public_view_partial_payload(patch) for patch in request.patch_views],
+                    "remove_views": list(request.remove_views),
+                    "preset": request.preset.value if request.preset is not None else None,
+                },
+            },
         )
 
     @tool_cn_name("应用结构应用")
@@ -2080,6 +2104,7 @@ class AiBuilderTools(ToolBase):
         visibility: JSONObject | None = None,
         create_if_missing: bool | None = None,
         publish: bool = True,
+        form: list[JSONObject] | None = None,
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
@@ -2105,6 +2130,21 @@ class AiBuilderTools(ToolBase):
             package_id = normalized_apps_payload.get("package_id")  # type: ignore[assignment]
             apps = normalized_apps_payload.get("apps")  # type: ignore[assignment]
             input_warnings = list(normalized_apps_payload.get("warnings") or [])
+            normalized_apps: list[JSONObject] = []
+            for index, app_item in enumerate(apps or []):
+                if not isinstance(app_item, dict):
+                    normalized_apps.append(app_item)
+                    continue
+                form_result = _apply_schema_form_to_payload(
+                    tool_name="app_schema_apply",
+                    payload=app_item,
+                    path=f"apps[{index}]",
+                )
+                failure = form_result.get("failure")
+                if isinstance(failure, dict):
+                    return _attach_builder_apply_envelope("app_schema_apply", failure)
+                normalized_apps.append(form_result.get("payload") or app_item)
+            apps = normalized_apps
             result = self._app_schema_apply_multi(
                 profile=profile,
                 package_id=package_id,
@@ -2118,6 +2158,22 @@ class AiBuilderTools(ToolBase):
                 result_warnings.extend(deepcopy(input_warnings))
                 result["warnings"] = result_warnings
             return _attach_builder_apply_envelope("app_schema_apply", result)
+        inline_form_layout_sections: list[JSONObject] = []
+        if form:
+            form_payload: JSONObject = {"form": form}
+            if add_fields:
+                form_payload["add_fields"] = add_fields
+            form_result = _apply_schema_form_to_payload(
+                tool_name="app_schema_apply",
+                payload=form_payload,
+                path="schema",
+            )
+            failure = form_result.get("failure")
+            if isinstance(failure, dict):
+                return _attach_builder_apply_envelope("app_schema_apply", failure)
+            normalized_payload = form_result.get("payload") if isinstance(form_result.get("payload"), dict) else {}
+            add_fields = list(normalized_payload.get("add_fields") or [])
+            inline_form_layout_sections = list(form_result.get("layout_sections") or [])
         result = self._app_schema_apply_once(
             profile=profile,
             app_key=app_key,
@@ -2132,6 +2188,7 @@ class AiBuilderTools(ToolBase):
             add_fields=add_fields,
             update_fields=update_fields,
             remove_fields=remove_fields,
+            inline_form_layout_sections=inline_form_layout_sections,
         )
         result = self._retry_after_self_lock_release(
             profile=profile,
@@ -2150,6 +2207,7 @@ class AiBuilderTools(ToolBase):
                 add_fields=add_fields,
                 update_fields=update_fields,
                 remove_fields=remove_fields,
+                inline_form_layout_sections=inline_form_layout_sections,
             ),
         )
         return _attach_builder_apply_envelope("app_schema_apply", result)
@@ -2408,6 +2466,19 @@ class AiBuilderTools(ToolBase):
             remove_fields = list(compiled_item.get("remove_fields") or [])
             if bool(existing.get("created")) and not deferred_add_fields and not update_fields and not remove_fields:
                 shell_result = existing.get("shell_result") if isinstance(existing.get("shell_result"), dict) else {}
+                layout_sections = list(compiled_item.get("_inline_form_layout_sections") or [])
+                if layout_sections:
+                    shell_result = self._apply_inline_form_layout_after_schema(
+                        profile=profile,
+                        schema_result=shell_result,
+                        fallback_app_key=app_key,
+                        publish=publish,
+                        sections=layout_sections,
+                    )
+                    if _schema_apply_result_has_write(shell_result):
+                        any_write_executed = True
+                    if _schema_apply_result_may_have_write(shell_result):
+                        any_write_may_have_succeeded = True
                 item_status = shell_result.get("status") if shell_result.get("status") in {"success", "partial_success"} else "failed"
                 shell_field_diff = existing.get("shell_field_diff") if isinstance(existing.get("shell_field_diff"), dict) else {}
                 shell_field_diff_details = existing.get("shell_field_diff_details") if isinstance(existing.get("shell_field_diff_details"), dict) else {}
@@ -2428,6 +2499,8 @@ class AiBuilderTools(ToolBase):
                     "safe_to_retry": False,
                     **({"next_action": shell_result.get("next_action")} if shell_result.get("next_action") else {}),
                     **({"verification": shell_result.get("verification")} if isinstance(shell_result.get("verification"), dict) else {}),
+                    **({"inline_form_layout": shell_result.get("inline_form_layout")} if isinstance(shell_result.get("inline_form_layout"), dict) else {}),
+                    **({"inline_form_layout_result": shell_result.get("inline_form_layout_result")} if isinstance(shell_result.get("inline_form_layout_result"), dict) else {}),
                 })
                 continue
 
@@ -2447,6 +2520,15 @@ class AiBuilderTools(ToolBase):
                 remove_fields=remove_fields,
             )
             public_result = _publicize_package_fields(field_result)
+            layout_sections = list(compiled_item.get("_inline_form_layout_sections") or [])
+            if layout_sections:
+                public_result = self._apply_inline_form_layout_after_schema(
+                    profile=profile,
+                    schema_result=public_result,
+                    fallback_app_key=app_key,
+                    publish=publish,
+                    sections=layout_sections,
+                )
             if _schema_apply_result_has_write(public_result):
                 any_write_executed = True
             if _schema_apply_result_may_have_write(public_result):
@@ -2478,6 +2560,8 @@ class AiBuilderTools(ToolBase):
                 "safe_to_retry": False,
                 **({"next_action": public_result.get("next_action")} if public_result.get("next_action") else {}),
                 **({"verification": public_result.get("verification")} if isinstance(public_result.get("verification"), dict) else {}),
+                **({"inline_form_layout": public_result.get("inline_form_layout")} if isinstance(public_result.get("inline_form_layout"), dict) else {}),
+                **({"inline_form_layout_result": public_result.get("inline_form_layout_result")} if isinstance(public_result.get("inline_form_layout_result"), dict) else {}),
             })
 
         pending_readback = sum(1 for item in final_items if item.get("status") == "pending_readback")
@@ -2541,6 +2625,7 @@ class AiBuilderTools(ToolBase):
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
         remove_fields: list[JSONObject],
+        inline_form_layout_sections: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
         effective_app_name = app_name or app_title
@@ -2652,7 +2737,83 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_schema_apply", "arguments": {"profile": profile, **normalized_args}},
         )
-        return _publicize_package_fields(result)
+        public_result = _publicize_package_fields(result)
+        if inline_form_layout_sections:
+            public_result = self._apply_inline_form_layout_after_schema(
+                profile=profile,
+                schema_result=public_result,
+                fallback_app_key=str(plan_args.get("app_key") or app_key),
+                publish=publish,
+                sections=inline_form_layout_sections,
+            )
+        return public_result
+
+    def _apply_inline_form_layout_after_schema(
+        self,
+        *,
+        profile: str,
+        schema_result: JSONObject,
+        fallback_app_key: str = "",
+        publish: bool,
+        sections: list[JSONObject],
+    ) -> JSONObject:
+        result = deepcopy(schema_result)
+        if not sections:
+            return result
+        app_key = str(result.get("app_key") or result.get("appKey") or fallback_app_key or "").strip()
+        result["inline_form_layout"] = {
+            "requested": True,
+            "section_count": len(sections),
+            "applied": False,
+        }
+        if result.get("status") not in {"success", "partial_success"}:
+            result["inline_form_layout"]["skipped_reason"] = "schema_apply_failed"
+            verification = result.get("verification") if isinstance(result.get("verification"), dict) else {}
+            verification = deepcopy(verification)
+            verification["inline_form_layout_verified"] = False
+            result["verification"] = verification
+            return result
+        if not app_key:
+            result["status"] = "partial_success"
+            result["error_code"] = result.get("error_code") or "INLINE_FORM_LAYOUT_APP_KEY_MISSING"
+            result["message"] = "schema applied but inline form layout could not run because app_key was not resolved"
+            result["inline_form_layout"]["error_code"] = "INLINE_FORM_LAYOUT_APP_KEY_MISSING"
+            verification = result.get("verification") if isinstance(result.get("verification"), dict) else {}
+            verification = deepcopy(verification)
+            verification["inline_form_layout_verified"] = False
+            result["verification"] = verification
+            result["safe_to_retry"] = False
+            return result
+        layout_result = self._app_layout_apply_once(
+            profile=profile,
+            app_key=app_key,
+            mode="merge",
+            publish=publish,
+            sections=sections,
+        )
+        layout_ok = isinstance(layout_result, dict) and layout_result.get("status") in {"success", "partial_success"}
+        result["inline_form_layout"] = {
+            "requested": True,
+            "section_count": len(sections),
+            "app_key": app_key,
+            "applied": layout_ok,
+            "layout_status": layout_result.get("status") if isinstance(layout_result, dict) else "failed",
+            **({"error_code": layout_result.get("error_code")} if isinstance(layout_result, dict) and layout_result.get("error_code") else {}),
+            **({"message": layout_result.get("message")} if isinstance(layout_result, dict) and layout_result.get("message") else {}),
+        }
+        result["inline_form_layout_result"] = layout_result
+        verification = result.get("verification") if isinstance(result.get("verification"), dict) else {}
+        verification = deepcopy(verification)
+        verification["inline_form_layout_verified"] = layout_ok
+        result["verification"] = verification
+        if layout_ok:
+            result["write_executed"] = True
+            return result
+        result["status"] = "partial_success" if result.get("status") == "success" else result.get("status", "partial_success")
+        result["error_code"] = result.get("error_code") or "INLINE_FORM_LAYOUT_APPLY_FAILED"
+        result["message"] = "schema applied but inline form layout failed"
+        result["safe_to_retry"] = False
+        return result
 
     @tool_cn_name("应用布局应用")
     def app_layout_apply(
@@ -2990,7 +3151,7 @@ class AiBuilderTools(ToolBase):
         )
         if reserved_failure is not None:
             return reserved_failure
-        if patch_views:
+        if patch_views or _view_payload_has_action_buttons(upsert_views=upsert_views, patch_views=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]
@@ -3016,8 +3177,8 @@ class AiBuilderTools(ToolBase):
             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],
+                "upsert_views": [public_view_upsert_payload(view) for view in parsed_views],
+                "patch_views": [public_view_partial_payload(patch) for patch in parsed_patch_views],
                 "remove_views": list(remove_views or []),
             }
             return _safe_tool_call(
@@ -3072,7 +3233,8 @@ class AiBuilderTools(ToolBase):
         normalized_args = {
             "app_key": str(plan_args.get("app_key") or app_key),
             "publish": publish,
-            "upsert_views": [view.model_dump(mode="json") for view in parsed_views],
+            "upsert_views": [public_view_upsert_payload(view) for view in parsed_views],
+            "patch_views": [],
             "remove_views": list(plan_args.get("remove_views") or remove_views),
         }
         return _safe_tool_call(
@@ -3534,7 +3696,12 @@ def _schema_apps_expected_shape() -> JSONObject:
                 "app_name": "员工花名册",
                 "icon": "business-personalcard",
                 "color": "emerald",
-                "add_fields": [{"name": "员工名称", "type": "text", "as_data_title": True}],
+                "form": [
+                    {
+                        "section": "基础信息",
+                        "rows": [[{"name": "员工名称", "type": "text", "data_title": True}]],
+                    }
+                ],
             }
         ],
     }
@@ -3543,7 +3710,7 @@ def _schema_apps_expected_shape() -> JSONObject:
 def _schema_apps_expected_shape_json() -> str:
     return (
         '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
-        '"icon":"business-personalcard","color":"emerald","add_fields":[{"name":"员工名称","type":"text","as_data_title":true}]}]}'
+        '"icon":"business-personalcard","color":"emerald","form":[{"section":"基础信息","rows":[[{"name":"员工名称","type":"text","data_title":true}]]}]}]}'
     )
 
 
@@ -3628,6 +3795,163 @@ def _normalize_schema_apps_argument(*, tool_name: str, package_id: int | None, a
     return {"package_id": normalized_package_id, "apps": normalized_items, "warnings": warnings}
 
 
+def _normalize_schema_form_field(field: JSONObject) -> JSONObject:
+    payload = deepcopy(field)
+    if "data_title" in payload and "as_data_title" not in payload and "asDataTitle" not in payload:
+        payload["as_data_title"] = payload.pop("data_title")
+    if "dataTitle" in payload and "as_data_title" not in payload and "asDataTitle" not in payload:
+        payload["as_data_title"] = payload.pop("dataTitle")
+    if "data_cover" in payload and "as_data_cover" not in payload and "asDataCover" not in payload:
+        payload["as_data_cover"] = payload.pop("data_cover")
+    if "dataCover" in payload and "as_data_cover" not in payload and "asDataCover" not in payload:
+        payload["as_data_cover"] = payload.pop("dataCover")
+    return payload
+
+
+def _schema_form_entry_name(entry: object) -> str:
+    if isinstance(entry, dict):
+        for key in ("name", "title", "label", "field_name", "fieldName"):
+            if entry.get(key) is not None:
+                return str(entry.get(key) or "").strip()
+        return ""
+    if isinstance(entry, (str, int)):
+        return str(entry).strip()
+    return ""
+
+
+def _schema_form_failure(*, tool_name: str, path: str, message: str, fix_hint: str) -> JSONObject:
+    return _config_failure(
+        tool_name=tool_name,
+        error_code="FORM_SHAPE_INVALID",
+        message=message,
+        fix_hint=fix_hint,
+        details={
+            "path": path,
+            "expected_shape": {
+                "form": [
+                    {
+                        "section": "基础信息",
+                        "rows": [
+                            [
+                                {"name": "标题", "type": "text", "data_title": True},
+                                {"name": "状态", "type": "single_select", "options": ["待处理", "处理中", "已完成"]},
+                            ]
+                        ],
+                    }
+                ]
+            },
+        },
+    )
+
+
+def _compile_schema_form_payload(*, tool_name: str, form: object, path: str = "form") -> JSONObject:
+    if form is None:
+        return {"add_fields": [], "layout_sections": []}
+    if not isinstance(form, list) or not form:
+        return {
+            "failure": _schema_form_failure(
+                tool_name=tool_name,
+                path=path,
+                message=f"{path} must be a non-empty list of form sections.",
+                fix_hint='Use form=[{"section":"基础信息","rows":[[{"name":"标题","type":"text","data_title":true}]]}].',
+            )
+        }
+
+    add_fields: list[JSONObject] = []
+    layout_sections: list[JSONObject] = []
+    for section_index, section in enumerate(form):
+        section_path = f"{path}[{section_index}]"
+        if not isinstance(section, dict):
+            return {
+                "failure": _schema_form_failure(
+                    tool_name=tool_name,
+                    path=section_path,
+                    message=f"{section_path} must be an object.",
+                    fix_hint="Each form section must include section and rows.",
+                )
+            }
+        section_title = str(section.get("section") or section.get("title") or section.get("name") or "").strip()
+        rows = section.get("rows")
+        if not section_title:
+            return {
+                "failure": _schema_form_failure(
+                    tool_name=tool_name,
+                    path=f"{section_path}.section",
+                    message=f"{section_path}.section is required.",
+                    fix_hint='Set a business section title such as "基础信息" or "生产信息".',
+                )
+            }
+        if not isinstance(rows, list) or not rows:
+            return {
+                "failure": _schema_form_failure(
+                    tool_name=tool_name,
+                    path=f"{section_path}.rows",
+                    message=f"{section_path}.rows must be a non-empty list.",
+                    fix_hint="Use rows as a list of field rows; each row is a list of field objects.",
+                )
+            }
+        layout_rows: list[list[str]] = []
+        for row_index, row in enumerate(rows):
+            row_path = f"{section_path}.rows[{row_index}]"
+            if isinstance(row, dict):
+                row_fields = row.get("fields")
+            else:
+                row_fields = row
+            if not isinstance(row_fields, list) or not row_fields:
+                return {
+                    "failure": _schema_form_failure(
+                        tool_name=tool_name,
+                        path=row_path,
+                        message=f"{row_path} must be a non-empty field list.",
+                        fix_hint='Use rows like [[{"name":"字段A","type":"text"},{"name":"字段B","type":"number"}]].',
+                    )
+                }
+            layout_row: list[str] = []
+            for field_index, field in enumerate(row_fields):
+                field_path = f"{row_path}[{field_index}]"
+                field_name = _schema_form_entry_name(field)
+                if not field_name:
+                    return {
+                        "failure": _schema_form_failure(
+                            tool_name=tool_name,
+                            path=field_path,
+                            message=f"{field_path} must include a field name.",
+                            fix_hint='Each new field object must include name, for example {"name":"工单编号","type":"text"}.',
+                        )
+                    }
+                layout_row.append(field_name)
+                if isinstance(field, dict):
+                    add_fields.append(_normalize_schema_form_field(field))
+            layout_rows.append(layout_row)
+        layout_sections.append({"title": section_title, "rows": layout_rows})
+    return {"add_fields": add_fields, "layout_sections": layout_sections}
+
+
+def _apply_schema_form_to_payload(*, tool_name: str, payload: JSONObject, path: str) -> JSONObject:
+    form = payload.get("form")
+    if form is None:
+        return {"payload": payload, "layout_sections": []}
+    existing_add_fields = payload.get("add_fields") or payload.get("addFields")
+    if isinstance(existing_add_fields, list) and existing_add_fields:
+        return {
+            "failure": _config_failure(
+                tool_name=tool_name,
+                error_code="FORM_WITH_ADD_FIELDS_CONFLICT",
+                message=f"{path} cannot use form and add_fields together.",
+                fix_hint="Use form as the single schema creation shape: put fields under form[].rows[][].",
+                details={"path": path, "conflicting_keys": ["form", "add_fields"]},
+            )
+        }
+    compiled = _compile_schema_form_payload(tool_name=tool_name, form=form, path=f"{path}.form")
+    if isinstance(compiled.get("failure"), dict):
+        return {"failure": compiled["failure"]}
+    normalized = deepcopy(payload)
+    normalized.pop("form", None)
+    normalized["add_fields"] = compiled.get("add_fields") or []
+    normalized["_inline_form_layout_sections"] = compiled.get("layout_sections") or []
+    return {"payload": normalized, "layout_sections": compiled.get("layout_sections") or []}
+
+
 def _multi_app_item_app_name(item: JSONObject) -> str:
     return str(item.get("app_name") or item.get("appName") or item.get("appTitle") or item.get("app_title") or item.get("title") or "").strip()
 
@@ -3649,7 +3973,7 @@ def _field_type_for_static_validation(field: JSONObject) -> str:
 
 
 def _is_data_title_field(field: JSONObject) -> bool:
-    return bool(field.get("as_data_title") or field.get("asDataTitle"))
+    return bool(field.get("as_data_title") or field.get("asDataTitle") or field.get("data_title") or field.get("dataTitle"))
 
 
 def _collect_multi_app_target_refs(value: object, *, path: str) -> list[JSONObject]:
@@ -4278,6 +4602,23 @@ def _reserved_system_view_name_failure(
     return None
 
 
+def _view_payload_has_action_buttons(
+    *,
+    upsert_views: list[JSONObject] | None = None,
+    patch_views: list[JSONObject] | None = None,
+) -> bool:
+    for item in upsert_views or []:
+        if isinstance(item, dict) and any(key in item for key in ("action_buttons", "actionButtons")):
+            return True
+    for item in patch_views or []:
+        if not isinstance(item, dict):
+            continue
+        raw_set = item.get("set")
+        if isinstance(raw_set, dict) and any(key in raw_set for key in ("action_buttons", "actionButtons")):
+            return True
+    return False
+
+
 def _config_failure(
     *,
     tool_name: str,
@@ -4986,6 +5327,15 @@ def _builder_view_resources(payload: JSONObject) -> list[JSONObject]:
                 message=message,
             )
         )
+    details = payload.get("details") if isinstance(payload.get("details"), dict) else {}
+    action_buttons_result = details.get("action_buttons_result") if isinstance(details, dict) else None
+    if isinstance(action_buttons_result, dict):
+        nested_payload = {
+            **action_buttons_result,
+            "app_key": payload.get("app_key"),
+            "app_name": payload.get("app_name"),
+        }
+        resources.extend(_builder_button_resources(nested_payload))
     return resources
 
 
@@ -5956,6 +6306,10 @@ _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.data_title": "field.as_data_title",
+            "field.dataTitle": "field.as_data_title",
+            "field.data_cover": "field.as_data_cover",
+            "field.dataCover": "field.as_data_cover",
             "field.asDataTitle": "field.as_data_title",
             "field.asDataCover": "field.as_data_cover",
         },
@@ -5983,7 +6337,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "color": "emerald",
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
-            "add_fields": [{"name": "项目名称", "type": "text", "as_data_title": True}],
+            "add_fields": [{"name": "项目名称", "type": "text", "data_title": True}],
             "update_fields": [],
             "remove_fields": [],
         },
@@ -6018,6 +6372,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "visibility",
             "create_if_missing",
             "publish",
+            "form",
             "add_fields",
             "update_fields",
             "remove_fields",
@@ -6031,6 +6386,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "apps[].icon_color",
             "apps[].icon_config",
             "apps[].visibility",
+            "apps[].form",
+            "apps[].form[].section",
+            "apps[].form[].rows",
             "apps[].add_fields",
             "apps[].update_fields",
             "apps[].remove_fields",
@@ -6075,6 +6433,10 @@ _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.data_title": "field.as_data_title",
+            "field.dataTitle": "field.as_data_title",
+            "field.data_cover": "field.as_data_cover",
+            "field.dataCover": "field.as_data_cover",
             "field.asDataTitle": "field.as_data_title",
             "field.asDataCover": "field.as_data_cover",
         },
@@ -6095,6 +6457,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "create mode follows backend CreateAppBean: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
             "multi-app mode: pass package_id + apps[]; create_if_missing defaults to true for app_name items and may be set false only when every item uses app_key",
             "CLI --apps-file primary shape is {package_id, apps:[...]}; raw app arrays and singleton wrapper arrays are compatibility paths, not recommended examples",
+            "create app schemas with form: form[].section names form sections; form[].rows[][] contains field objects; builder splits form into field creation plus form layout apply",
+            "single-app CLI primary shape is --form-file; multi-app primary shape is apps[].form inside --apps-file",
             "multi-app mode preflights static errors before writing: duplicate client_key/app_name, missing data title on new apps, explicit create_if_missing=false with app_name items, and unresolved target_app_ref/target_app",
             "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
             "multi-app relation fields may also use target_app with another apps[].app_name; prefer target_app_ref/client_key when names may collide",
@@ -6138,9 +6502,16 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "visibility": deepcopy(_VISIBILITY_WORKSPACE_EXAMPLE),
             "create_if_missing": True,
             "publish": True,
-            "add_fields": [
-                {"name": "项目名称", "type": "text", "as_data_title": True},
-                {"name": "项目封面", "type": "attachment", "as_data_cover": True},
+            "form": [
+                {
+                    "section": "基础信息",
+                    "rows": [
+                        [
+                            {"name": "项目名称", "type": "text", "data_title": True},
+                            {"name": "项目封面", "type": "attachment", "data_cover": True},
+                        ]
+                    ],
+                }
             ],
             "update_fields": [],
             "remove_fields": [],
@@ -6155,9 +6526,16 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                     "app_name": "员工花名册",
                     "icon": "business-personalcard",
                     "color": "emerald",
-                    "add_fields": [
-                        {"name": "员工名称", "type": "text", "as_data_title": True},
-                        {"name": "员工照片", "type": "attachment", "as_data_cover": True},
+                    "form": [
+                        {
+                            "section": "基础信息",
+                            "rows": [
+                                [
+                                    {"name": "员工名称", "type": "text", "data_title": True},
+                                    {"name": "员工照片", "type": "attachment", "data_cover": True},
+                                ]
+                            ],
+                        }
                     ],
                 },
                 {
@@ -6165,15 +6543,22 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                     "app_name": "工时表",
                     "icon": "clock",
                     "color": "blue",
-                    "add_fields": [
-                        {"name": "工时标题", "type": "text", "as_data_title": True},
+                    "form": [
                         {
-                            "name": "关联员工",
-                            "type": "relation",
-                            "target_app_ref": "employee",
-                            "display_field": {"name": "员工名称"},
-                            "visible_fields": [{"name": "员工名称"}],
-                        },
+                            "section": "基础信息",
+                            "rows": [
+                                [{"name": "工时标题", "type": "text", "data_title": True}],
+                                [
+                                    {
+                                        "name": "关联员工",
+                                        "type": "relation",
+                                        "target_app_ref": "employee",
+                                        "display_field": {"name": "员工名称"},
+                                        "visible_fields": [{"name": "员工名称"}],
+                                    }
+                                ],
+                            ],
+                        }
                     ],
                 },
             ],
@@ -6460,11 +6845,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "upsert_views[].columns",
             "upsert_views[].filters",
             "upsert_views[].buttons",
+            "upsert_views[].action_buttons",
+            "upsert_views[].action_buttons_mode",
             "upsert_views[].visibility",
             "upsert_views[].query_conditions",
             "patch_views[].view_key",
             "patch_views[].name",
             "patch_views[].set",
+            "patch_views[].set.action_buttons",
+            "patch_views[].set.action_buttons_mode",
             "patch_views[].unset",
         ],
         "aliases": {
@@ -6492,6 +6881,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "buttons[].buttonFormula": "buttons[].button_formula",
             "buttons[].buttonFormulaType": "buttons[].button_formula_type",
             "buttons[].printTpls": "buttons[].print_tpls",
+            "actionButtons": "action_buttons",
+            "actionButtonsMode": "action_buttons_mode",
+            "action_buttons[].button_text": "action_buttons[].text",
+            "action_buttons[].trigger_action": "action_buttons[].action",
+            "action_buttons[].trigger_link_url": "action_buttons[].url",
+            "action_buttons[].visibleWhen": "action_buttons[].visible_when",
+            "action_buttons[].fieldMappings": "action_buttons[].field_mappings",
+            "action_buttons[].defaultValues": "action_buttons[].default_values",
         },
         "allowed_values": {
             "preset": [member.value for member in ViewsPreset],
@@ -6499,6 +6896,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.filter.operator": [member.value for member in ViewFilterOperator],
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
             "view.buttons.config_type": ["TOP", "DETAIL", "INSIDE"],
+            "view.action_buttons.action": ["add_data", "link", "qRobot", "wings"],
+            "view.action_buttons.placement": [member.value for member in PublicButtonPlacement],
+            "view.action_buttons_mode": ["merge", "replace"],
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
@@ -6508,6 +6908,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
             "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
             "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",
+            "business buttons should be declared with action_buttons on the target view; app_views_apply writes the view first, then compiles action_buttons through the custom button writer and binds them to the resulting view_key",
+            "action_buttons_mode defaults to merge; replace rewrites this view's custom button bindings, and replace plus action_buttons=[] clears this view's custom button bindings without deleting button bodies",
+            "legacy upsert_views[].buttons is a compatibility path for raw full replacement of existing view button config; do not use it as the normal agent path",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
             "do not create business views named 全部数据, 我的数据, 我发起的, 待办, 已办, or 抄送; these are built-in system/default views. Use business-specific names for new views, and pass the existing raw view_key or patch_views when changing a built-in view",
@@ -6538,6 +6941,27 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             ],
             "remove_views": [],
         },
+        "action_buttons_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "upsert_views": [
+                {
+                    "name": "生产工单执行视图",
+                    "type": "table",
+                    "columns": ["工单编号", "产品", "状态", "负责人"],
+                    "action_buttons": [
+                        {
+                            "text": "开始生产",
+                            "action": "link",
+                            "url": "https://example.com/start",
+                            "placement": "list",
+                            "visible_when": [{"field_name": "状态", "operator": "eq", "value": "待排产"}],
+                        }
+                    ],
+                }
+            ],
+            "remove_views": [],
+        },
         "full_upsert_query_conditions_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -6595,11 +7019,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "upsert_views[].columns",
             "upsert_views[].filters",
             "upsert_views[].buttons",
+            "upsert_views[].action_buttons",
+            "upsert_views[].action_buttons_mode",
             "upsert_views[].visibility",
             "upsert_views[].query_conditions",
             "patch_views[].view_key",
             "patch_views[].name",
             "patch_views[].set",
+            "patch_views[].set.action_buttons",
+            "patch_views[].set.action_buttons_mode",
             "patch_views[].unset",
         ],
         "aliases": {
@@ -6627,12 +7055,23 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "buttons[].buttonFormula": "buttons[].button_formula",
             "buttons[].buttonFormulaType": "buttons[].button_formula_type",
             "buttons[].printTpls": "buttons[].print_tpls",
+            "actionButtons": "action_buttons",
+            "actionButtonsMode": "action_buttons_mode",
+            "action_buttons[].button_text": "action_buttons[].text",
+            "action_buttons[].trigger_action": "action_buttons[].action",
+            "action_buttons[].trigger_link_url": "action_buttons[].url",
+            "action_buttons[].visibleWhen": "action_buttons[].visible_when",
+            "action_buttons[].fieldMappings": "action_buttons[].field_mappings",
+            "action_buttons[].defaultValues": "action_buttons[].default_values",
         },
         "allowed_values": {
             "view.type": [member.value for member in PublicViewType],
             "view.filter.operator": [member.value for member in ViewFilterOperator],
             "view.buttons.button_type": ["SYSTEM", "CUSTOM"],
             "view.buttons.config_type": ["TOP", "DETAIL", "INSIDE"],
+            "view.action_buttons.action": ["add_data", "link", "qRobot", "wings"],
+            "view.action_buttons.placement": [member.value for member in PublicButtonPlacement],
+            "view.action_buttons_mode": ["merge", "replace"],
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
@@ -6642,6 +7081,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "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",
+            "business buttons should be declared with action_buttons on the target view; app_views_apply writes the view first, then compiles action_buttons through the custom button writer and binds them to the resulting view_key",
+            "patch_views[].set.action_buttons can add buttons to an existing view without rewriting columns/filters; action_buttons_mode defaults to merge, replace rewrites this view's custom button bindings, and replace plus action_buttons=[] clears bindings without deleting button bodies",
+            "publish=false with action_buttons is blocked as VIEW_ACTION_BUTTONS_REQUIRE_PUBLISH because the underlying custom button writer may publish after successful button writes",
+            "legacy upsert_views[].buttons is a compatibility path for raw full replacement of existing view button config; do not use it as the normal agent path",
             "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 query-panel supported field names; it is compiled to backend queryCondition queIds",
@@ -6679,6 +7122,51 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             ],
             "remove_views": [],
         },
+        "action_buttons_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "upsert_views": [
+                {
+                    "name": "生产工单执行视图",
+                    "type": "table",
+                    "columns": ["工单编号", "产品", "状态", "负责人"],
+                    "action_buttons": [
+                        {
+                            "text": "开始生产",
+                            "action": "link",
+                            "url": "https://example.com/start",
+                            "placement": "list",
+                            "visible_when": [{"field_name": "状态", "operator": "eq", "value": "待排产"}],
+                        }
+                    ],
+                }
+            ],
+            "remove_views": [],
+        },
+        "action_buttons_patch_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "publish": True,
+            "patch_views": [
+                {
+                    "view_key": "RAW_VIEW_KEY",
+                    "set": {
+                        "action_buttons": [
+                            {
+                                "text": "创建验收单",
+                                "action": "add_data",
+                                "target_app_key": "ARRIVAL_APP",
+                                "field_mappings": [{"source_field": "数据ID", "target_field": "关联工单"}],
+                                "default_values": {"状态": "待验收"},
+                                "placement": "detail",
+                            }
+                        ]
+                    },
+                }
+            ],
+            "remove_views": [],
+        },
         "full_upsert_query_conditions_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -6954,15 +7442,38 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "name": "dash_name",
             "sourceType": "source_type",
             "chartRef": "chart_ref",
+            "inlineChart": "inline_chart",
+            "createChart": "inline_chart",
             "viewRef": "view_ref",
             "dashStyleConfigBO": "dash_style_config",
         },
-        "section_allowed_keys": ["title", "source_type", "role", "position", "dash_style_config", "config", "chart_ref", "view_ref", "text", "url"],
+        "section_allowed_keys": [
+            "title",
+            "source_type",
+            "role",
+            "position",
+            "dash_style_config",
+            "config",
+            "chart_ref",
+            "inline_chart",
+            "inline_chart.app_key",
+            "inline_chart.chart_name",
+            "inline_chart.chart_type",
+            "inline_chart.metric",
+            "inline_chart.metrics",
+            "inline_chart.group_by",
+            "inline_chart.where",
+            "view_ref",
+            "text",
+            "url",
+        ],
         "section_aliases": {
             "sourceType": "source_type",
             "zone": "role",
             "sectionRole": "role",
             "chartRef": "chart_ref",
+            "inlineChart": "inline_chart",
+            "createChart": "inline_chart",
             "viewRef": "view_ref",
             "dashStyleConfigBO": "dash_style_config",
         },
@@ -6988,6 +7499,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "package_id is required when creating a new portal",
             "publish=false only guarantees draft and base-info updates; it does not claim live has changed",
             "chart_ref resolves by chart_id first, then exact unique chart_name",
+            "inline_chart internally creates or updates an app-source QingBI report, then uses the returned chart_id for this portal section",
+            "use chart_ref when an existing report already matches; use inline_chart when the portal needs a new or adjusted report",
             "view_ref resolves by view_key first, then exact unique view_name",
             "pc layout uses a 24-column grid; mobile layout uses a 6-column grid",
             "if unsure about layout, omit position or use layout_preset=auto/dashboard_2col/dashboard_3col",
@@ -7015,7 +7528,12 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 {
                     "title": "经营概览",
                     "source_type": "chart",
-                    "chart_ref": {"app_key": "APP_KEY", "chart_name": "数据总量"},
+                    "inline_chart": {
+                        "app_key": "APP_KEY",
+                        "chart_name": "数据总量",
+                        "chart_type": "summary",
+                        "metric": {"field": "数据ID", "agg": "count"},
+                    },
                     "position": {
                         "pc": {"x": 0, "y": 0, "cols": 12, "rows": 6},
                         "mobile": {"x": 0, "y": 0, "cols": 6, "rows": 6},