@josephyan/qingflow-app-builder-mcp 1.1.17 → 1.1.19

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -220,9 +220,10 @@ class AiBuilderTools(ToolBase):
                 wrapped["error"] = error
             app_results.append(wrapped)
 
+        partial = sum(1 for item in app_results if str(item.get("status") or "") == "partial_success")
         succeeded = sum(1 for item in app_results if str(item.get("status") or "") in {"success", "partial_success"})
         failed = len(app_results) - succeeded
-        status = "success" if failed == 0 else "failed" if succeeded == 0 else "partial_success"
+        status = "failed" if succeeded == 0 else "partial_success" if failed > 0 or partial > 0 else "success"
         write_executed = any(
             isinstance(item.get("result"), dict) and bool(item["result"].get("write_executed"))
             for item in app_results
@@ -230,7 +231,7 @@ class AiBuilderTools(ToolBase):
         payload: JSONObject = {
             "status": status,
             "error_code": None if status == "success" else f"{tool_name.upper()}_BATCH_PARTIAL" if succeeded else f"{tool_name.upper()}_BATCH_FAILED",
-            "recoverable": failed > 0,
+            "recoverable": failed > 0 or partial > 0,
             "message": (
                 f"applied {tool_name} to {succeeded}/{len(app_results)} apps"
                 if status != "success"
@@ -240,12 +241,13 @@ class AiBuilderTools(ToolBase):
             "apps": app_results,
             "errors": errors,
             "verification": {
-                "batch_verified": failed == 0,
+                "batch_verified": failed == 0 and partial == 0,
                 "succeeded": succeeded,
+                "partial": partial,
                 "failed": failed,
             },
             "write_executed": write_executed,
-            "write_succeeded": write_executed and failed == 0,
+            "write_succeeded": write_executed and failed == 0 and partial == 0,
             "safe_to_retry": not write_executed,
         }
         return _attach_builder_apply_envelope(tool_name, payload)
@@ -295,18 +297,20 @@ class AiBuilderTools(ToolBase):
                 app_item["error"] = error
                 errors.append(error)
             apps.append(app_item)
+        partial = sum(1 for item in apps if str(item.get("status") or "") == "partial_success")
         succeeded = sum(1 for item in apps if str(item.get("status") or "") in {"success", "partial_success"})
         failed = len(apps) - succeeded
+        status = "failed" if succeeded == 0 else "partial_success" if failed > 0 or partial > 0 else "success"
         return {
-            "status": "success" if failed == 0 else "failed" if succeeded == 0 else "partial_success",
-            "error_code": None if failed == 0 else f"{tool_name.upper()}_BATCH_PARTIAL" if succeeded else f"{tool_name.upper()}_BATCH_FAILED",
-            "recoverable": failed > 0,
-            "message": f"read {tool_name} for {succeeded}/{len(apps)} apps" if failed else f"read {tool_name} for {succeeded} apps",
+            "status": status,
+            "error_code": None if status == "success" else f"{tool_name.upper()}_BATCH_PARTIAL" if succeeded else f"{tool_name.upper()}_BATCH_FAILED",
+            "recoverable": failed > 0 or partial > 0,
+            "message": f"read {tool_name} for {succeeded}/{len(apps)} apps" if status != "success" else f"read {tool_name} for {succeeded} apps",
             "normalized_args": {"app_keys": normalized_keys},
             "app_keys": normalized_keys,
             "apps": apps,
             "errors": errors,
-            "verification": {"batch_verified": failed == 0, "succeeded": succeeded, "failed": failed},
+            "verification": {"batch_verified": failed == 0 and partial == 0, "succeeded": succeeded, "partial": partial, "failed": failed},
         }
 
     def register(self, mcp) -> None:
@@ -577,17 +581,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(
@@ -602,6 +607,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=[],
@@ -638,10 +644,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()
@@ -2101,6 +2108,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],
@@ -2126,6 +2134,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,
@@ -2139,6 +2162,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,
@@ -2153,6 +2192,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,
@@ -2171,6 +2211,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)
@@ -2429,6 +2470,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 {}
@@ -2449,6 +2503,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
 
@@ -2468,6 +2524,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):
@@ -2499,6 +2564,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")
@@ -2562,6 +2629,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
@@ -2673,7 +2741,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(
@@ -3556,7 +3700,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}]],
+                    }
+                ],
             }
         ],
     }
@@ -3565,7 +3714,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}]]}]}]}'
     )
 
 
@@ -3650,6 +3799,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()
 
@@ -3671,7 +3977,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]:
@@ -6004,6 +6310,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",
         },
@@ -6031,7 +6341,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": [],
         },
@@ -6066,6 +6376,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "visibility",
             "create_if_missing",
             "publish",
+            "form",
             "add_fields",
             "update_fields",
             "remove_fields",
@@ -6079,6 +6390,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",
@@ -6123,6 +6437,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",
         },
@@ -6143,6 +6461,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",
@@ -6186,9 +6506,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": [],
@@ -6203,9 +6530,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},
+                                ]
+                            ],
+                        }
                     ],
                 },
                 {
@@ -6213,15 +6547,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": "员工名称"}],
+                                    }
+                                ],
+                            ],
+                        }
                     ],
                 },
             ],
@@ -7105,15 +7446,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",
         },
@@ -7139,6 +7503,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",
@@ -7166,7 +7532,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},