@qingflow-tech/qingflow-app-builder-mcp 1.0.11 → 1.0.13

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

@@ -1610,6 +1610,7 @@ class AssociatedResourcesApplyRequest(StrictModel):
         if not isinstance(value, dict):
             return value
         payload = dict(value)
+        default_target_app_key = str(payload.get("app_key", payload.get("appKey", "")) or "").strip()
         if "upsertResources" in payload and "upsert_resources" not in payload:
             payload["upsert_resources"] = payload.pop("upsertResources")
         if "patchResources" in payload and "patch_resources" not in payload:
@@ -1622,6 +1623,16 @@ class AssociatedResourcesApplyRequest(StrictModel):
             payload["reorder_associated_item_ids"] = payload.pop("reorderAssociatedItemIds")
         if "viewConfigs" in payload and "view_configs" not in payload:
             payload["view_configs"] = payload.pop("viewConfigs")
+        if default_target_app_key and isinstance(payload.get("upsert_resources"), list):
+            normalized_resources = []
+            for item in payload["upsert_resources"]:
+                if isinstance(item, dict) and not any(
+                    str(item.get(key) or "").strip()
+                    for key in ("target_app_key", "targetAppKey", "app_key", "appKey")
+                ):
+                    item = {**item, "target_app_key": default_target_app_key}
+                normalized_resources.append(item)
+            payload["upsert_resources"] = normalized_resources
         return payload
 
     @model_validator(mode="after")