@josephyan/qingflow-app-user-mcp 1.1.17 → 1.1.18

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-user-mcp@1.1.17
+npm install @josephyan/qingflow-app-user-mcp@1.1.18
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-user-mcp@1.1.17 qingflow-app-user-mcp
+npx -y -p @josephyan/qingflow-app-user-mcp@1.1.18 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.17"
+version = "1.1.18"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/builder_facade/models.py

@@ -2260,6 +2260,22 @@ class ChartApplyRequest(StrictModel):
         return self
 
 
+class PortalInlineChartPatch(ChartUpsertPatch):
+    app_key: str = Field(validation_alias=AliasChoices("app_key", "appKey"))
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_inline_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "chart_name" in payload and "name" not in payload:
+            payload["name"] = payload.pop("chart_name")
+        if "chartName" in payload and "name" not in payload:
+            payload["name"] = payload.pop("chartName")
+        return payload
+
+
 class PortalComponentPositionPatch(StrictModel):
     pc_x: int = Field(default=0, validation_alias=AliasChoices("pc_x", "pcX", "x"))
     pc_y: int = Field(default=0, validation_alias=AliasChoices("pc_y", "pcY", "y"))
@@ -2344,6 +2360,7 @@ class PortalSectionPatch(StrictModel):
     dash_style_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_style_config", "dashStyleConfigBO"))
     config: dict[str, Any] = Field(default_factory=dict)
     chart_ref: PortalChartRefPatch | None = None
+    chart: PortalInlineChartPatch | None = Field(default=None, validation_alias=AliasChoices("chart", "inline_chart", "inlineChart", "create_chart", "createChart"))
     view_ref: PortalViewRefPatch | None = None
     text: str | None = None
     url: str | None = None
@@ -2362,6 +2379,14 @@ class PortalSectionPatch(StrictModel):
             payload["role"] = raw_role.strip().lower()
         if "chartRef" in payload and "chart_ref" not in payload:
             payload["chart_ref"] = payload.pop("chartRef")
+        if "inlineChart" in payload and "chart" not in payload:
+            payload["chart"] = payload.pop("inlineChart")
+        if "inline_chart" in payload and "chart" not in payload:
+            payload["chart"] = payload.pop("inline_chart")
+        if "createChart" in payload and "chart" not in payload:
+            payload["chart"] = payload.pop("createChart")
+        if "create_chart" in payload and "chart" not in payload:
+            payload["chart"] = payload.pop("create_chart")
         if "viewRef" in payload and "view_ref" not in payload:
             payload["view_ref"] = payload.pop("viewRef")
         if "dashStyleConfigBO" in payload and "dash_style_config" not in payload:
@@ -2373,8 +2398,8 @@ class PortalSectionPatch(StrictModel):
         supported = {"chart", "view", "grid", "filter", "text", "link"}
         if self.source_type not in supported:
             raise ValueError(f"unsupported portal source_type '{self.source_type}'")
-        if self.source_type == "chart" and self.chart_ref is None:
-            raise ValueError("chart section requires chart_ref")
+        if self.source_type == "chart" and self.chart_ref is None and self.chart is None:
+            raise ValueError("chart section requires chart_ref or chart")
         if self.source_type == "view" and self.view_ref is None:
             raise ValueError("view section requires view_ref")
         if self.source_type == "text" and self.text is None:
@@ -2662,6 +2687,14 @@ def _normalize_field_payload(value: Any) -> Any:
     if not isinstance(value, dict):
         return value
     payload = dict(value)
+    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")
     if "fields" in payload and "subfields" not in payload:
         payload["subfields"] = payload.pop("fields")
     if "options" in payload:

package/src/qingflow_mcp/builder_facade/service.py

@@ -13018,6 +13018,7 @@ class AiBuilderFacade:
         draft_readback_error: JSONObject | None = None
         live_readback_error: JSONObject | None = None
         update_payload: dict[str, Any] = {}
+        inline_chart_results: list[dict[str, Any]] = []
         try:
             layout_diagnostics: dict[str, Any] = _empty_portal_layout_diagnostics()
             if creating:
@@ -13065,10 +13066,11 @@ class AiBuilderFacade:
                 base_payload=base_payload,
             )
             if sections_requested:
-                component_payload, layout_metadata = self._build_portal_components_from_sections(
+                component_payload, layout_metadata, inline_chart_results = self._build_portal_components_from_sections(
                     profile=profile,
                     sections=request.sections,
                     layout_preset=request.layout_preset,
+                    inline_chart_results=inline_chart_results,
                 )
                 layout_diagnostics = _portal_layout_diagnostics(request.sections, component_payload, layout_metadata=layout_metadata)
                 update_payload["components"] = component_payload
@@ -13096,11 +13098,12 @@ class AiBuilderFacade:
                 draft_result = {}
         except (QingflowApiError, RuntimeError, ValueError) as error:
             api_error = _coerce_api_error(error) if not isinstance(error, ValueError) else None
-            if write_executed:
+            inline_chart_write_executed = any(bool(item.get("write_executed")) for item in inline_chart_results)
+            if write_executed or inline_chart_write_executed:
                 transport_error = _transport_error_payload(api_error) if api_error is not None else None
                 warning = _warning(
                     "PORTAL_WRITE_INCOMPLETE_AFTER_PARTIAL_WRITE",
-                    "one or more portal write steps executed before a later write step failed",
+                    "one or more portal or inline-chart write steps executed before a later write step failed",
                 )
                 if transport_error is not None:
                     for key in ("backend_code", "http_status", "request_id"):
@@ -13121,6 +13124,7 @@ class AiBuilderFacade:
                             if api_error is not None
                             else {"message": str(error)}
                         ),
+                        **({"inline_chart_results": deepcopy(inline_chart_results)} if inline_chart_results else {}),
                     },
                     "request_id": api_error.request_id if api_error else None,
                     "backend_code": api_error.backend_code if api_error else None,
@@ -13136,6 +13140,7 @@ class AiBuilderFacade:
                         "published": False,
                         "publish_failed": False,
                         "write_incomplete": True,
+                        "inline_charts_verified": False if inline_chart_results else None,
                         "readback_unavailable": False,
                         "metadata_unverified": True,
                     },
@@ -13147,6 +13152,7 @@ class AiBuilderFacade:
                     "verified": False,
                     "write_executed": True,
                     "safe_to_retry": False,
+                    "inline_chart_results": deepcopy(inline_chart_results),
                 })
             return _failed(
                 "PORTAL_APPLY_FAILED",
@@ -13258,6 +13264,7 @@ class AiBuilderFacade:
                 "draft": draft_meta_mismatches,
                 "live": live_meta_mismatches,
             },
+            **({"inline_chart_results": deepcopy(inline_chart_results)} if inline_chart_results else {}),
             **({"publish_error": publish_error} if publish_error is not None else {}),
             **({"draft_readback_error": draft_readback_error} if draft_readback_error is not None else {}),
             **({"live_readback_error": live_readback_error} if live_readback_error is not None else {}),
@@ -13295,6 +13302,7 @@ class AiBuilderFacade:
             "noop": False,
             "warnings": warnings,
             "layout_diagnostics": layout_diagnostics,
+            "inline_chart_results": deepcopy(inline_chart_results),
             "verification": {
                 "draft_verified": draft_verified,
                 "draft_metadata_verified": draft_meta_verified,
@@ -13302,6 +13310,7 @@ class AiBuilderFacade:
                 "live_metadata_verified": live_meta_verified,
                 "published": published,
                 "publish_failed": publish_failed,
+                "inline_charts_verified": all(str(item.get("status") or "") in {"created", "updated"} and str(item.get("chart_id") or "").strip() for item in inline_chart_results),
                 "readback_unavailable": draft_readback_error is not None or live_readback_error is not None,
                 "metadata_unverified": draft_readback_error is not None or live_readback_error is not None,
             },
@@ -14055,9 +14064,11 @@ class AiBuilderFacade:
         profile: str,
         sections: list[PortalSectionPatch],
         layout_preset: str | None = None,
-    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        inline_chart_results: list[dict[str, Any]] | None = None,
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
         resolved_components: list[dict[str, Any]] = []
         layout_metadata: list[dict[str, Any]] = []
+        inline_chart_results = inline_chart_results if inline_chart_results is not None else []
         pc_x = 0
         pc_y = 0
         pc_row_height = 0
@@ -14084,11 +14095,53 @@ class AiBuilderFacade:
             dash_style = deepcopy(section.dash_style_config) if isinstance(section.dash_style_config, dict) else None
             component: dict[str, Any]
             if section.source_type == "chart":
-                resolved_chart = _resolve_chart_reference(
-                    charts=self.charts,
-                    profile=profile,
-                    ref=section.chart_ref,
-                )
+                if section.chart is not None:
+                    inline_chart_payload = section.chart.model_dump(mode="json", exclude={"app_key"})
+                    chart_request = ChartApplyRequest(
+                        app_key=section.chart.app_key,
+                        upsert_charts=[ChartUpsertPatch.model_validate(inline_chart_payload)],
+                        patch_charts=[],
+                        remove_chart_ids=[],
+                        reorder_chart_ids=[],
+                    )
+                    chart_apply = self.chart_apply(profile=profile, request=chart_request)
+                    chart_items = chart_apply.get("chart_results") if isinstance(chart_apply.get("chart_results"), list) else []
+                    successful_chart = next(
+                        (
+                            item
+                            for item in chart_items
+                            if isinstance(item, dict)
+                            and str(item.get("status") or "") in {"created", "updated"}
+                            and str(item.get("chart_id") or "").strip()
+                        ),
+                        None,
+                    )
+                    inline_chart_results.append({
+                        "title": section.title,
+                        "app_key": section.chart.app_key,
+                        "chart_name": section.chart.name,
+                        "chart_type": section.chart.chart_type.value,
+                        "status": str(successful_chart.get("status") or "") if isinstance(successful_chart, dict) else "failed",
+                        "chart_id": str(successful_chart.get("chart_id") or "") if isinstance(successful_chart, dict) else "",
+                        "chart_apply_status": chart_apply.get("status"),
+                        "write_executed": bool(chart_apply.get("write_executed")),
+                        **({"error_code": chart_apply.get("error_code")} if chart_apply.get("error_code") else {}),
+                        **({"message": chart_apply.get("message")} if chart_apply.get("message") else {}),
+                    })
+                    if not isinstance(successful_chart, dict):
+                        raise ValueError(f"inline chart '{section.chart.name}' could not be created or updated for portal section '{section.title}'")
+                    resolved_chart = {
+                        "chart_id": str(successful_chart.get("chart_id") or "").strip(),
+                        "chart_name": str(successful_chart.get("name") or section.chart.name).strip(),
+                        "app_key": section.chart.app_key,
+                        "chart_type": section.chart.chart_type.value,
+                    }
+                else:
+                    resolved_chart = _resolve_chart_reference(
+                        charts=self.charts,
+                        profile=profile,
+                        ref=section.chart_ref,
+                    )
                 chart_type = str(
                     resolved_chart.get("chart_type")
                     or _public_chart_type_from_backend(section.config.get("chartType") or section.config.get("chart_type"))
@@ -14148,7 +14201,7 @@ class AiBuilderFacade:
             if dash_style is not None:
                 component["dashStyleConfigBO"] = dash_style
             resolved_components.append(component)
-        return resolved_components, layout_metadata
+        return resolved_components, layout_metadata, inline_chart_results
 
     def _resolve_current_user_identity(self, *, profile: str) -> JSONObject:
         session_profile = self.apps.sessions.get_profile(profile)
@@ -17794,12 +17847,12 @@ def _portal_layout_diagnostics(
         if source_type == "chart" and role in {"metric", "metrics", "indicator", "kpi"} and not is_metric_chart:
             warnings.append(_warning(
                 "PORTAL_METRIC_SECTION_CHART_TYPE_MISMATCH",
-                "metric portal section must reference a target/indicator chart; create the missing metric chart before assembling the portal",
+                "metric portal section must reference a target/indicator chart; use inline_chart to create the missing metric chart while assembling the portal",
                 section_index=index,
                 title=title,
                 role=role,
                 chart_type=chart_type or None,
-                fix_hint="Use app_charts_apply with chart_type=target and metric='count(*)' or another metric expression, then reference that chart.",
+                fix_hint="Use section.inline_chart with chart_type=target or indicator and a metric expression, or change role away from metric.",
             ))
         if section is not None and section.position is not None and not bool(getattr(section.position, "mobile_provided", False)):
             warnings.append(_warning(
@@ -17859,7 +17912,7 @@ def _append_portal_standard_count_warnings(
             "standard portal metric area should contain 4-6 metric cards",
             actual_count=metric_count,
             expected_count="4-6",
-            fix_hint="Create missing target/indicator charts first, or keep 4 metric cards in one row with pc.cols=6, pc.rows=5.",
+            fix_hint="Use inline_chart for missing target/indicator metric cards, or keep 4 metric cards in one row with pc.cols=6, pc.rows=5.",
         ))
     if (bi_count or require_complete_standard) and not 2 <= bi_count <= 3:
         warnings.append(_warning(

package/src/qingflow_mcp/cli/commands/builder.py

@@ -214,7 +214,8 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     schema_apply_apply.add_argument("--visibility-file")
     schema_apply_apply.add_argument("--create-if-missing", action="store_true")
     schema_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=None)
-    schema_apply_apply.add_argument("--apps-file", help="多应用 schema JSON 数组；每项可带 client_key/app_name/add_fields，支持 relation target_app_ref")
+    schema_apply_apply.add_argument("--apps-file", help="多应用 schema JSON 对象；每项可带 client_key/app_name/form，支持 relation target_app_ref")
+    schema_apply_apply.add_argument("--form-file", help="单应用表单结构 JSON 数组；form[].rows[][] 同时声明字段和表单分组布局")
     schema_apply_apply.add_argument("--add-fields-file", help="字段 JSON 数组；字段可用 as_data_title/as_data_cover 标记数据标题/封面")
     schema_apply_apply.add_argument("--update-fields-file", help="字段更新 JSON 数组；set 内可用 as_data_title/as_data_cover 标记数据标题/封面")
     schema_apply_apply.add_argument("--remove-fields-file")
@@ -578,10 +579,10 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
                 fix_hint="Pass a JSON array, or a JSON object like {\"package_id\":1001,\"apps\":[...]} with at least one app item.",
                 error_code="APPS_FILE_EMPTY",
             )
-        if args.app_key or args.app_name or args.app_title or args.add_fields_file or args.update_fields_file or args.remove_fields_file:
+        if args.app_key or args.app_name or args.app_title or args.form_file or args.add_fields_file or args.update_fields_file or args.remove_fields_file:
             raise_config_error(
                 "schema apply multi-app mode accepts --package-id plus --apps-file only; --create-if-missing is optional.",
-                fix_hint="Use `--apps-file` for batch mode, or remove `--apps-file` and use the single-app arguments.",
+                fix_hint="Use apps[].form inside --apps-file for batch mode, or remove --apps-file and use --form-file for a single app.",
             )
         if package_id is None:
             raise_config_error(
@@ -595,6 +596,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             create_if_missing=effective_create_if_missing,
             publish=effective_publish,
             apps=apps,
+            form=None,
             add_fields=[],
             update_fields=[],
             remove_fields=[],
@@ -631,6 +633,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
         visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
         create_if_missing=bool(args.create_if_missing),
         publish=True if args.publish is None else bool(args.publish),
+        form=load_list_arg(args.form_file, option_name="--form-file") if args.form_file else [],
         add_fields=load_list_arg(args.add_fields_file, option_name="--add-fields-file"),
         update_fields=load_list_arg(args.update_fields_file, option_name="--update-fields-file"),
         remove_fields=load_list_arg(args.remove_fields_file, option_name="--remove-fields-file"),

package/src/qingflow_mcp/server_app_builder.py

@@ -428,16 +428,17 @@ def build_builder_server() -> FastMCP:
         visibility: dict | None = None,
         create_if_missing: bool | None = None,
         publish: bool = True,
+        form: list[dict] | None = None,
         add_fields: list[dict] | None = None,
         update_fields: list[dict] | None = None,
         remove_fields: list[dict] | None = None,
         apps: list[dict] | None = None,
     ) -> dict:
         if apps:
-            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(
                     "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="Use apps[].form for batch mode, or use the single-app arguments without apps.",
                 )
             if package_id is None:
                 return _config_failure(
@@ -450,6 +451,7 @@ def build_builder_server() -> FastMCP:
                 visibility=visibility,
                 create_if_missing=True if create_if_missing is None else bool(create_if_missing),
                 publish=publish,
+                form=None,
                 add_fields=[],
                 update_fields=[],
                 remove_fields=[],
@@ -482,10 +484,11 @@ def build_builder_server() -> FastMCP:
             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,
         )
 
     @server.tool()

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -577,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(
@@ -602,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=[],
@@ -638,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()
@@ -2101,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],
@@ -2126,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,
@@ -2139,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,
@@ -2153,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,
@@ -2171,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)
@@ -2429,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 {}
@@ -2449,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
 
@@ -2468,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):
@@ -2499,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")
@@ -2562,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
@@ -2673,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(
@@ -3556,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}]],
+                    }
+                ],
             }
         ],
     }
@@ -3565,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}]]}]}]}'
     )
 
 
@@ -3650,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()
 
@@ -3671,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]:
@@ -6004,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",
         },
@@ -6031,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": [],
         },
@@ -6066,6 +6372,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "visibility",
             "create_if_missing",
             "publish",
+            "form",
             "add_fields",
             "update_fields",
             "remove_fields",
@@ -6079,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",
@@ -6123,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",
         },
@@ -6143,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",
@@ -6186,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": [],
@@ -6203,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},
+                                ]
+                            ],
+                        }
                     ],
                 },
                 {
@@ -6213,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": "员工名称"}],
+                                    }
+                                ],
+                            ],
+                        }
                     ],
                 },
             ],
@@ -7105,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",
         },
@@ -7139,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",
@@ -7166,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},