@qingflow-tech/qingflow-app-builder-mcp 1.0.10 → 1.0.12

package/skills/qingflow-app-builder/references/public-surface-sync.md

@@ -0,0 +1,75 @@
+# Qingflow Core Public Surface Sync
+
+Use this file as the maintenance baseline for the core Qingflow skills.
+It is not a user-facing product spec. It exists to prevent skill drift.
+
+## Current Public Defaults
+
+### User data
+
+- Read range first with `app_get`, then `record_browse_schema_get(view_id=...)`
+- Treat `record_browse_schema_get.fields` as the selected Qingflow table view header schema; `record_access.fields` and `record_list` field selectors must stay aligned with it.
+- Standard flows:
+  - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
+  - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`
+  - explicit export/download/Excel: `app_get -> choose view_id -> view_get -> record_export_*` or `record_export_direct`; export tools require explicit `view_id`
+  - insert: `record_insert_schema_get -> record_insert(items)`
+  - update: `record_get -> record_update`; use `record_update_schema_get` only for failure diagnosis or ambiguous writable-field routing
+
+### Tasks
+
+- Discovery stays on `task_list`
+- `task_list --query` uses backend search first and only applies local fallback when backend returns zero rows
+- Public actions are:
+  - `approve`
+  - `reject`
+  - `rollback`
+  - `transfer`
+  - `urge`
+  - `save_only`
+- `reject` requires `payload.audit_feedback`
+- `save_only` requires non-empty `fields`
+- `TASK_RUNTIME_CONSUMED_AFTER_ACTION` is a normal post-success warning when the current node runtime is consumed and `46001` appears on re-read
+
+### Builder
+
+- Official package entry: `package_get`, `package_apply`
+- Official builder writes:
+  - `app_schema_apply`
+  - `app_layout_apply`
+  - `app_flow_apply`
+  - `app_views_apply`
+  - `app_custom_buttons_apply`
+  - `app_associated_resources_apply`
+  - `app_charts_apply`
+  - `portal_apply`
+  - `app_publish_verify`
+- `portal_apply` edit mode may omit `sections` for base-info-only updates
+- `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
+- Existing object parameter replacement should use `patch_views`, `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
+- `app_get.editability` uses:
+  - `can_edit_app_base`
+  - `can_edit_form`
+  - `can_edit_flow`
+  - `can_edit_views`
+  - `can_edit_charts`
+
+## Known High-Drift Areas
+
+- Task actions, especially `save_only`, reject payload requirements, and `46001` post-action interpretation
+- Package public tools: do not regress to `package_create` / `package_attach_app` as the public default story
+- App editability: do not let `can_edit_form` imply app base-info writes
+- Portal and chart visibility: keep the public story on `portal_apply` / `app_charts_apply`, not low-level internal writes
+- Analysis path: standard path stays `record_access -> Python`
+
+## Release Checklist For Skill Maintenance
+
+After each beta that changes public behavior, re-check:
+
+1. `public_surface.py`
+2. `README.md`
+3. `server_app_builder.py` and `server.py` top-level guidance
+4. CLI help for `task`, `builder package`, `builder portal`, `builder charts`
+5. Whether new warnings or verification fields need to be explained in skills
+
+If a tool behavior changed but the public surface did not, prefer updating the relevant skill section instead of expanding this file.

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -21,12 +21,12 @@ If the user asks for multiple forms/modules that relate to each other, this is a
 
 ## Resolve
 
-- `package_get`: read one known package by `package_id`
-- `package_apply`: create or update one package; use `create_if_missing=true` only after explicit user intent
+- `package_get`: read one known package by `package_id`; it reads package `baseInfo` first and may warn `PACKAGE_DETAIL_READ_DEGRADED` when the richer detail endpoint needs package edit/add-app permission. Treat that warning as degraded detail, not as package-read failure.
+- `package_apply`: create or update one package; use `create_if_missing=true` only after explicit user intent; layout/group/order changes require package edit permission because they call the backend package ordering route
 - `member_search`: resolve named people from the directory
 - `role_search`: resolve reusable roles from the directory
 - `role_create`: create a reusable role when the business owner wants role-based routing
-- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_id`
+- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_id`; by-name resolution checks package detail/current visible apps before using broader admin-style app search, so a `/app/item` permission miss is not a frontend-visible-app failure
 
 ## Summary reads
 
@@ -36,6 +36,7 @@ If the user asks for multiple forms/modules that relate to each other, this is a
 - `app_get_views`: current view names, types, columns, group-by
 - `app_get_flow`: workflow enabled state, nodes, transitions
 - `app_get_charts`: current chart ids, names, types, order
+- `chart_get`: one chart's base/config detail; base info is read through the Qingflow/qflow visible route first, and config may degrade from chart data when the CHART_SEE config endpoint is unavailable. Treat degraded config as a read-mode warning, not as proof the user cannot see the chart.
 - `portal_get`: current portal config detail and component inventory
 
 ## Apply tools
@@ -47,9 +48,9 @@ These execute normalized patches. Some app apply tools publish by default and st
 - `app_flow_apply`: replace workflow
 - `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key; new views default associated report/view display to visible with `limit_type="all"`
 - `app_custom_buttons_apply`: use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; configure add-data field mappings/default values; bind buttons to header/detail/list view positions; `placement=list` maps to the backend `INSIDE` row/list button position; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings. For child-record creation linked to the current source record, map `source_field: "数据ID"` to the target relation field.
-- `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call.
+- `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call.
 - `app_charts_apply`: create/edit/remove/reorder app-source QingBI report bodies/configs with `dataSourceType=qingflow`; it does not create/edit dataset BI reports and does not attach reports to Qingflow app associated-resource display. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; supports `target/table` aliases plus QingBI chart types such as `summary`, `columnar`, `area`, `funnel`, `radar`, `scatter`, `dualaxes`, and `map`; charts are immediate-live and do not publish; use `chart_id` when names are not unique
-- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics
+- `portal_apply`: create or replace-update portal pages; use `dash_key` for update mode or `package_id + dash_name` for create mode; create mode only prechecks package add_app, matching backend portal creation; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics
 
 For object-level updates, the safe partial syntax is `patch_*` with the object's real selector field plus `set` and optional `unset`. `selector` is only a concept, not a literal key. Examples: `patch_views: [{"view_key": "VIEW_KEY", "set": {...}}]`, `patch_buttons: [{"button_id": 1001, "set": {...}}]`, `patch_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`. The tool reads the current backend config, merges the patch, then submits the full backend payload internally. Do not send a partial `upsert_*` and expect missing required fields to be preserved.
 

package/skills/qingflow-app-builder/references/update-views.md

@@ -31,7 +31,7 @@ Canonical rules before any example:
 - Use `filters` with canonical keys `field_name`, `operator`, `value`/`values`
 - Use `query_conditions` for the frontend query panel. Do not put query-panel fields into `filters`.
 - New views created by `app_views_apply` default the frontend associated report/view area to visible with `limit_type="all"`. Existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched.
-- Use `app_associated_resources_apply` for the associated report/view resource pool, selected resources, and match rules. `associated_item_id` is the internal associated-resource id from `app_get.associated_resources`; `view_configs`, remove, and reorder may also pass an existing resource's `chart_id`/`chart_key`/`view_key`, which the tool resolves to the internal id. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
+- Use `app_associated_resources_apply` for the associated report/view resource pool, selected resources, and match rules. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. `associated_item_id` is the internal associated-resource id from `app_get.associated_resources`; `view_configs`, remove, and reorder may also pass an existing resource's `chart_id`/`chart_key`/`view_key`, which the tool resolves to the internal id. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
 - For gantt, use `start_field`, `end_field`, and optionally `title_field`
 - If `app_get.views` or `app_get_views` shows duplicate view names, include `view_key` in `upsert_views[]` and update that exact target
 - Builder view writes always use the raw `view_key` from `app_get.views[].view_key`, such as `emsrao25rs02`. Do not pass `custom:emsrao25rs02`; that prefixed form is only for record-data `view_id`.

package/skills/qingflow-app-builder-code-integrations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qingflow-app-builder-code-integrations
-description: Configure Qingflow code block and Q-Linker fields through the builder surface when the task involves input field insertion, alias parsing, target field binding, or troubleshooting broken code/q-linker form configurations. Use after MCP is connected and authenticated, especially for CRM-style scoring, lookup, and enrichment forms.
+description: Configure Qingflow code block and Q-Linker fields through the builder surface when the task involves input field insertion, alias parsing, target field binding, or troubleshooting broken code/q-linker form configurations. In Wingent Momo runtime, use the injected MCP session and recover auth/workspace only after a tool error.
 metadata:
   short-description: Configure Qingflow code blocks and Q-Linkers safely
 ---
@@ -58,7 +58,7 @@ For code block or Q-Linker work, use this order:
 
 1. Resolve the app and read fields:
    - `app_resolve`
-   - `app_read_fields`
+   - `app_get_fields`
 2. Confirm the target field set already exists.
 3. Apply schema updates with `app_schema_apply`.
 4. Read fields again and verify:
@@ -115,7 +115,7 @@ Hard rules:
 
 After each code block or Q-Linker change, verify all of these:
 
-- `app_read_fields` shows the intended field type
+- `app_get_fields` shows the intended field type
 - the high-level config is readable and stable
 - target fields still have valid types
 - insert schema can be opened

package/skills/qingflow-app-builder-code-integrations/references/code-block.md

@@ -59,7 +59,7 @@ Do not bind code block outputs to:
 
 ## Safe Verification
 
-- `app_read_fields`
+- `app_get_fields`
 - `record_insert_schema_get`
 - optional `record_code_block_run`
 

package/skills/qingflow-app-builder-code-integrations/references/q-linker.md

@@ -70,7 +70,7 @@ Avoid:
 
 ## Safe Verification
 
-- `app_read_fields`
+- `app_get_fields`
 - `record_insert_schema_get`
 - `record_insert`
 

package/src/qingflow_mcp/__main__.py

@@ -1,5 +1,9 @@
-"""Entry point for running qingflow_mcp as a module."""
-from qingflow_mcp.server import main
+"""Entry point for running qingflow_mcp as a module.
+
+Default to the curated user-facing MCP surface. Split package and console
+entrypoints can still start the builder server explicitly.
+"""
+from qingflow_mcp.server_app_user import main
 
 if __name__ == "__main__":
     main()

package/src/qingflow_mcp/builder_facade/models.py

@@ -1893,8 +1893,9 @@ class PortalComponentPositionPatch(StrictModel):
     pc_h: int = Field(default=8, validation_alias=AliasChoices("pc_h", "pcH", "h"))
     mobile_x: int = Field(default=0, validation_alias=AliasChoices("mobile_x", "mobileX"))
     mobile_y: int = Field(default=0, validation_alias=AliasChoices("mobile_y", "mobileY"))
-    mobile_w: int = Field(default=12, validation_alias=AliasChoices("mobile_w", "mobileW"))
+    mobile_w: int = Field(default=6, validation_alias=AliasChoices("mobile_w", "mobileW"))
     mobile_h: int = Field(default=8, validation_alias=AliasChoices("mobile_h", "mobileH"))
+    mobile_provided: bool = Field(default=False, exclude=True)
 
     @model_validator(mode="before")
     @classmethod
@@ -1904,6 +1905,8 @@ class PortalComponentPositionPatch(StrictModel):
         payload = dict(value)
         pc = payload.pop("pc", None)
         mobile = payload.pop("mobile", None)
+        mobile_keys = {"mobile_x", "mobileX", "mobile_y", "mobileY", "mobile_w", "mobileW", "mobile_h", "mobileH"}
+        mobile_provided = isinstance(mobile, dict) or any(key in payload for key in mobile_keys)
         if isinstance(pc, dict):
             if "pc_x" not in payload and "x" in pc:
                 payload["pc_x"] = pc.get("x")
@@ -1922,6 +1925,7 @@ class PortalComponentPositionPatch(StrictModel):
                 payload["mobile_w"] = mobile.get("cols")
             if "mobile_h" not in payload and "rows" in mobile:
                 payload["mobile_h"] = mobile.get("rows")
+        payload["mobile_provided"] = mobile_provided
         return payload
 
 
@@ -2003,9 +2007,10 @@ class PortalSectionPatch(StrictModel):
 class PortalApplyRequest(StrictModel):
     dash_key: str | None = None
     dash_name: str | None = None
-    package_tag_id: int | None = None
+    package_tag_id: int | None = Field(default=None, validation_alias=AliasChoices("package_tag_id", "packageTagId", "package_id", "packageId"))
     publish: bool = True
     sections: list[PortalSectionPatch] = Field(default_factory=list)
+    layout_preset: str | None = Field(default=None, validation_alias=AliasChoices("layout_preset", "layoutPreset"))
     visibility: VisibilityPatch | None = None
     auth: dict[str, Any] | None = None
     icon: str | None = None
@@ -2014,6 +2019,33 @@ class PortalApplyRequest(StrictModel):
     dash_global_config: dict[str, Any] | None = Field(default=None, validation_alias=AliasChoices("dash_global_config", "dashGlobalConfig"))
     config: dict[str, Any] = Field(default_factory=dict)
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_compat_payload(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "dash_name" not in payload and "dashName" not in payload and "name" in payload:
+            payload["dash_name"] = payload.pop("name")
+        if "sections" not in payload and "pages" in payload:
+            pages = payload.pop("pages")
+            if not isinstance(pages, list):
+                raise ValueError("portal pages must be a list")
+            if len(pages) != 1:
+                raise ValueError("portal_apply currently supports a single page; pass one page or flatten components into sections")
+            page = pages[0]
+            if not isinstance(page, dict):
+                raise ValueError("portal pages[0] must be an object")
+            components = page.get("components")
+            if not isinstance(components, list) or not components:
+                raise ValueError("portal pages[0].components must be a non-empty list")
+            payload["sections"] = components
+        if "theme" in payload:
+            payload.pop("theme")
+        if "type" in payload:
+            payload.pop("type")
+        return payload
+
     @model_validator(mode="after")
     def validate_shape(self) -> "PortalApplyRequest":
         if not self.dash_key and not self.package_tag_id:
@@ -2024,6 +2056,8 @@ class PortalApplyRequest(StrictModel):
             raise ValueError("portal apply requires a non-empty sections list when creating a portal")
         if self.visibility is not None and self.auth is not None:
             raise ValueError("visibility and auth cannot be provided together")
+        if self.layout_preset is not None and self.layout_preset not in {"auto", "dashboard_2col", "dashboard_3col"}:
+            raise ValueError("layout_preset must be one of: auto, dashboard_2col, dashboard_3col")
         return self
 
 
@@ -2038,6 +2072,7 @@ class AppGetResponse(StrictModel):
     name: str | None = None
     title: str | None = None
     app_icon: str | None = None
+    icon_config: dict[str, Any] = Field(default_factory=dict)
     visibility: dict[str, Any] = Field(default_factory=dict)
     tag_ids: list[int] = Field(default_factory=list)
     publish_status: int | None = None
@@ -2062,6 +2097,8 @@ class AppGetFieldsResponse(StrictModel):
     app_key: str
     fields: list[dict[str, Any]] = Field(default_factory=list)
     field_count: int = 0
+    chart_fields: list[dict[str, Any]] = Field(default_factory=list)
+    chart_field_count: int = 0
     form_settings: dict[str, Any] = Field(default_factory=dict)
 
 
@@ -2109,6 +2146,7 @@ class PortalReadSummaryResponse(StrictModel):
     dash_name: str | None = None
     package_tag_ids: list[int] = Field(default_factory=list)
     dash_icon: str | None = None
+    icon_config: dict[str, Any] = Field(default_factory=dict)
     hide_copyright: bool | None = None
     config_keys: list[str] = Field(default_factory=list)
     dash_global_config_keys: list[str] = Field(default_factory=list)
@@ -2122,6 +2160,7 @@ class PortalGetResponse(StrictModel):
     dash_name: str | None = None
     package_tag_ids: list[int] = Field(default_factory=list)
     dash_icon: str | None = None
+    icon_config: dict[str, Any] = Field(default_factory=dict)
     hide_copyright: bool | None = None
     visibility: dict[str, Any] = Field(default_factory=dict)
     auth: dict[str, Any] = Field(default_factory=dict)