@qingflow-tech/qingflow-app-user-mcp 1.0.11 → 1.0.12

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

@@ -0,0 +1,68 @@
+# Update Layout
+
+Use this when fields already exist and the task is only about form grouping or ordering.
+
+## Minimal sequence
+
+1. `app_get_fields`
+2. `app_get_layout`
+3. `builder_tool_contract` when the section shape is not already obvious
+4. `app_layout_apply`
+
+## Example
+
+Apply a custom layout with the canonical public section shape:
+
+```json
+{
+  "tool_name": "app_layout_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "mode": "merge",
+    "publish": true,
+    "sections": [
+      {
+        "title": "基础信息",
+        "rows": [
+          ["客户名称", "订单金额"],
+          ["状态", "跟进日期"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Common failures
+
+### `UNKNOWN_LAYOUT_FIELD`
+
+At least one field name does not exist. Re-read with `app_get_fields`.
+
+### `DUPLICATE_LAYOUT_FIELD`
+
+The same field appears more than once in the requested layout.
+
+### `INCOMPLETE_LAYOUT`
+
+Only happens in `mode=replace`. Switch to `mode=merge` unless you intend to place every field exactly once.
+
+### `LAYOUT_APPLY_FAILED`
+
+Re-read with `app_get_layout`. Check `current_field_names`, `request_id`, and `suggested_next_call`.
+
+### `VALIDATION_ERROR`
+
+Do not keep guessing section keys. Reuse `suggested_next_call`, `canonical_arguments`, `section_allowed_keys`, and `minimal_section_example`.
+
+If the same shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_apply)`.
+
+## Notes
+
+- `section_id` is optional; it is generated from the section title
+- `merge` is safer than `replace`
+- Unmentioned fields stay in place or get auto-added to `未分组字段`
+- Public builder layout sections use `title + rows`
+- Do not treat “一行四个字段 / 四列布局 / 每行放四个” as a top-level `columns` parameter; translate it into a `rows` matrix
+- Do not prefer `fields` or `field_ids` once `rows` is known, even though MCP may normalize those shorthands for recovery

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

@@ -0,0 +1,72 @@
+# Update Schema
+
+Use this when the app already exists and the task is only about fields.
+
+## Minimal sequence
+
+1. `app_resolve`
+2. `app_get_fields`
+3. `app_schema_apply`
+
+## Example
+
+Read current fields first:
+
+```json
+{
+  "tool_name": "app_get_fields",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123"
+  }
+}
+```
+
+Apply the patch:
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "add_fields": [
+      {"name": "跟进日期", "type": "date"},
+      {"name": "数据封面", "type": "attachment", "as_data_cover": true}
+    ],
+    "update_fields": [
+      {"selector": {"name": "金额"}, "set": {"name": "订单金额", "required": true}},
+      {"selector": {"name": "客户名称"}, "set": {"as_data_title": true}}
+    ],
+    "remove_fields": [
+      {"name": "旧字段"}
+    ]
+  }
+}
+```
+
+## Common failures
+
+### `FIELD_NOT_FOUND`
+
+The selector did not match current schema. Re-read with `app_get_fields` and use `name`, `field_id`, or `que_id`.
+
+### `DUPLICATE_FIELD`
+
+The field already exists with a different shape. Switch from `add_fields` to `update_fields`.
+
+### `SCHEMA_APPLY_FAILED`
+
+Treat it as uncertain write state. Read back with `app_get_fields` before retrying.
+
+## Notes
+
+- `title` and `label` are accepted aliases for `name`
+- `textarea -> long_text`
+- `currency -> amount`
+- `mobile -> phone`
+- `select/radio -> single_select`
+- `checkbox -> multi_select`
+- `as_data_title: true` marks the app data title; the final form must have exactly one top-level data title field
+- `as_data_cover: true` marks the app data cover; the cover is optional and must be a top-level `attachment` field

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

@@ -0,0 +1,284 @@
+# Update Views
+
+Use this when the task is only about table, card, board, or gantt views.
+
+## Minimal sequence
+
+1. `builder_tool_contract(tool_name="app_views_apply")`
+2. `app_get_fields`
+3. `app_get` for current view/chart/button inventory and app-level associated resource ids
+4. `app_views_apply`
+5. Use `app_associated_resources_apply` if the task includes associated reports/views
+6. `app_get` or `view_get` again whenever apply returns `failed` or `partial_success`
+
+If you are unsure about keys or view types, call `builder_tool_contract(tool_name="app_views_apply")` before guessing.
+
+Important verification rule:
+
+- `app_views_apply` can create a view object before every filter is fully verified in readback
+- Do not report “筛选已成功应用” unless the apply result also shows `verification.views_verified=true` and `verification.view_filters_verified=true`
+- Do not report “查询条件已成功配置” unless the apply result also shows `verification.view_query_conditions_verified=true`
+- Do not report “关联资源已成功配置” unless `app_associated_resources_apply` shows `verification.associated_resource_view_configs_verified=true`
+- If apply returns `partial_success`, inspect `verification.by_view`, `details.filter_mismatches`, `details.query_condition_mismatches`, and `details.associated_resource_mismatches` before claiming filters/query conditions/associated resources are active
+
+## Example
+
+Canonical rules before any example:
+
+- Always use `columns`
+- Do not emit `column_names`
+- Treat `fields` only as a legacy alias the MCP may normalize, not as the preferred shape
+- 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. 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`.
+- For an existing view, prefer `patch_views` for parameter replacement. Do not send a partial `upsert_views` object such as only `name/type/query_conditions`; backend view saves require other type-specific fields, and the patch path preserves them for you.
+
+Apply a default table view:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "upsert_views": [
+      {
+        "name": "全部订单",
+        "view_key": "VIEW_KEY_IF_DUPLICATE_NAMES_EXIST",
+        "type": "table",
+        "columns": ["订单编号", "客户名称", "订单金额", "状态"]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+After `app_views_apply` returns canonical arguments or blocking issues, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite aliases back into non-canonical keys such as `column_names`.
+
+Existing table view: replace only frontend query conditions:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "patch_views": [
+      {
+        "view_key": "VIEW_KEY",
+        "set": {
+          "query_conditions": {
+            "enabled": true,
+            "exact": false,
+            "hide_before_query": false,
+            "rows": [["客户名称", "负责人"], ["创建时间"]]
+          }
+        }
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+
+Meaning:
+
+- `filters` are saved view filters and apply immediately when the view opens.
+- `query_conditions` only configures which fields appear in the frontend query panel. The query values come later from the user through the page.
+- `query_conditions.rows` is a matrix of field names and is compiled to backend `queryCondition` field ids.
+- The patch call preserves the view's existing columns, saved filters, type-specific date/card/board config, buttons, visibility, and other backend-required fields.
+
+View associated resources example:
+
+```json
+{
+  "tool_name": "app_associated_resources_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "upsert_resources": [],
+    "remove_associated_item_ids": [],
+    "reorder_associated_item_ids": [],
+    "view_configs": [
+      {
+        "view_key": "VIEW_KEY",
+        "visible": true,
+        "limit_type": "select",
+        "associated_item_ids": [123, 124]
+      }
+    ]
+  }
+}
+```
+
+Use `{"visible": true, "limit_type": "all"}` to show all app-level associated resources, and `{"visible": false}` to hide the area. The ids above can be internal `associated_item_id` values or existing resource `chart_id`/`chart_key`/`view_key` values from `app_get.associated_resources`. Before creating a resource, check whether the same `target_app_key + view_key/chart_key` already exists; if it does, use `patch_resources` with that `associated_item_id`. Dataset BI reports must already exist in QingBI and should be attached with `report_source="dataset"`; do not try to create them through `app_charts_apply`. If you create a new associated item in the same call, give it a `client_key` and reference it from `view_configs[].associated_item_refs`; `client_key` is not persisted and cannot deduplicate a later call.
+
+Create and show a BI indicator-card report in the same call:
+
+```json
+{
+  "tool_name": "app_associated_resources_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "upsert_resources": [
+      {
+        "client_key": "total_hours_card",
+        "graph_type": "chart",
+        "target_app_key": "TIMESHEET_APP",
+        "chart_key": "CHART_KEY",
+        "report_source": "app",
+        "match_mappings": [
+          {"target_field": "关联员工", "source_field": "数据ID"},
+          {"target_field": "状态", "value": "待提交"}
+        ]
+      }
+    ],
+    "remove_associated_item_ids": [],
+    "reorder_associated_item_ids": [],
+    "view_configs": [
+      {
+        "view_key": "VIEW_KEY",
+        "visible": true,
+        "limit_type": "select",
+        "associated_item_refs": ["total_hours_card"]
+      }
+    ]
+  }
+}
+```
+
+Board example:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "upsert_views": [
+      {
+        "name": "按状态看板",
+        "type": "board",
+        "group_by": "状态",
+        "columns": ["订单编号", "客户名称", "订单金额"]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+
+Gantt example with filters:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "upsert_views": [
+      {
+        "name": "项目甘特图",
+        "type": "gantt",
+        "columns": ["项目名称", "开始日期", "结束日期", "状态"],
+        "start_field": "开始日期",
+        "end_field": "结束日期",
+        "title_field": "项目名称",
+        "filters": [
+          {
+            "field_name": "状态",
+            "operator": "eq",
+            "value": "进行中"
+          }
+        ]
+      }
+    ],
+    "remove_views": []
+  }
+}
+```
+
+## Common failures
+
+### `UNKNOWN_VIEW_FIELD`
+
+At least one `columns` or `group_by` field name does not exist.
+
+### `INVALID_VIEW_TYPE`
+
+Public view types are only `table`, `card`, `board`, `gantt`.
+
+Map old or intuitive labels before calling the tool:
+
+- `tableView` -> `table`
+- `cardView` -> `card`
+- `kanban` -> `board`
+
+### `INVALID_GANTT_CONFIG`
+
+Gantt views require at least:
+
+- `start_field`
+- `end_field`
+
+Also make sure these field names already exist on the app.
+
+### `VIEW_APPLY_FAILED`
+
+The backend rejected the normalized view payload. Re-read fields and inspect `request_id` before retrying.
+
+Do not repeat `app_views_apply` with guessed keys. First:
+
+1. check `suggested_next_call`
+2. reuse `canonical_arguments` if present
+3. call `app_get_views` to see whether any requested views landed anyway
+4. if needed, call `builder_tool_contract`
+5. retry only the minimal failed view patch
+
+### `VIEW_FILTER_READBACK_MISMATCH`
+
+The view object was created or updated, but the readback config did not keep the intended filter values.
+
+Treat this as:
+
+- the view exists
+- the filter is **not yet verified**
+
+Do not tell the user the filter is active until the readback verification matches the intended filter.
+
+### `VIEW_QUERY_CONDITION_READBACK_MISMATCH`
+
+The view object was created or updated, but the readback config did not keep the intended frontend query-condition settings.
+
+Treat this as:
+
+- the view exists
+- the query panel configuration is **not yet verified**
+
+Do not tell the user the query condition is active until readback matches the intended `query_conditions`.
+
+### `QUERY_CONDITION_FIELD_NOT_FOUND`
+
+At least one `query_conditions.rows` field does not exist on the app.
+
+### `INVALID_QUERY_CONDITION_FIELD`
+
+The field exists but cannot be used in the frontend query-condition panel, such as attachment, relation, Q-Linker, code block, location/address, or subtable/subfield selections.
+
+## Notes
+
+- `fields` is accepted as an alias for `columns`, but skill examples should still use `columns`
+- `column_names` should not appear in skill examples
+- `app_get_views` should be treated as canonical readback and now returns `columns`
+- If `app_views_apply` returns `AMBIGUOUS_VIEW`, stop and re-run `app_get_views`; then retry with the exact `view_key`
+- `filters` are ANDed together as one flat condition group
+- `query_conditions.rows` does not mean OR; it controls frontend query-field layout
+- `app_views_apply` publishes by default
+- For select-style filters, success means the backend preserved the option value in readback, not just that the view name now exists

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

@@ -0,0 +1,137 @@
+---
+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. 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
+---
+
+# Qingflow App Builder Code Integrations
+
+Use this skill when the user wants to build or repair:
+- `code_block` fields
+- `q_linker` fields
+- output alias parsing
+- target field binding
+- form configurations that depend on code block or Q-Linker relations
+
+Do not use this skill for MCP setup, generic field CRUD, or runtime execution debugging unless those are strictly supporting code block or Q-Linker configuration work.
+
+## Core Rule
+
+Treat code blocks and Q-Linkers as **integration fields**, not ordinary fields.
+
+For both of them, the public builder request may look like one step, but the real backend form structure has multiple layers. Never invent a new backend meaning. Only compile into the backend structures that already exist.
+
+## Mental Model
+
+### Code block
+
+There are three conceptual layers:
+
+1. Code block field itself
+2. Parsed output aliases
+3. Target field bindings
+
+Current builder support:
+- configure the code block field itself
+- configure input insertion into code content
+- configure alias parsing
+
+Important:
+- keep `qf_output = {...}` as a plain assignment
+- do not emit `const qf_output =` or `let qf_output =`
+
+### Q-Linker
+
+There are two conceptual layers:
+
+1. Q-Linker field itself via `remoteLookupConfig`
+2. Target field bindings via relation-default + `questionRelations(relationType=Q_LINKER)`
+
+Current builder support:
+- one-step high-level config through `q_linker_binding`
+- internal compilation into existing backend payloads
+
+## Operating Order
+
+For code block or Q-Linker work, use this order:
+
+1. Resolve the app and read fields:
+   - `app_resolve`
+   - `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:
+   - field type
+   - alias config
+   - target field binding shape
+5. For page-safety checks, use user-side schema or insert checks:
+   - `record_insert_schema_get`
+   - optional safe `record_insert`
+
+Do not treat raw apply success as enough. Always re-read the field config.
+
+## Code Block Rules
+
+Read [references/code-block.md](references/code-block.md) before changing a code block field.
+
+Use builder high-level config only for:
+- input field insertion
+- code content
+- alias parsing
+- auto trigger
+- custom button text
+
+When binding outputs to target fields, do not guess payload shape from memory. Follow the current builder implementation and the readback shape.
+
+Hard rules:
+- target fields must already exist
+- keep target field types business-compatible
+- if a page starts hanging on “关联中”, inspect whether the target field default type or relation config was written incorrectly
+
+## Q-Linker Rules
+
+Read [references/q-linker.md](references/q-linker.md) before changing a Q-Linker field.
+
+First-stage stable support is only:
+- custom mode
+- request config
+- alias parsing
+- target field binding
+- auto trigger / button text
+
+Do not generate:
+- template mode
+- openApp/light-wing branches
+- subtable table-match bindings
+
+Hard rules:
+- `outputs[*].target_field` is required
+- use only supported target field types
+- on rebinding, old target fields must be restored from relation-default to safe default type
+- `resultFormatPath` must preserve backend-required alias metadata
+
+## Verification Checklist
+
+After each code block or Q-Linker change, verify all of these:
+
+- `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
+- record insert does not get blocked by malformed integration config
+
+If the task explicitly includes runtime verification, keep it separate from configuration verification.
+
+## Common Pitfalls
+
+- Writing code block code with `const qf_output =`
+- Treating a Q-Linker or code block binding as a plain field default
+- Forgetting to restore old target fields after unbinding
+- Using unsupported target field types
+- Assuming apply success means the form page can open
+
+## References
+
+- Code block details: [references/code-block.md](references/code-block.md)
+- Q-Linker details: [references/q-linker.md](references/q-linker.md)

package/skills/qingflow-app-builder-code-integrations/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow Code Integrations"
+  short_description: "Configure Qingflow code block and Q-Linker fields safely"
+  default_prompt: "Use $qingflow-app-builder-code-integrations when configuring Qingflow code block or Q-Linker fields, especially when input insertion, alias parsing, target field binding, or page-safety verification matter."

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

@@ -0,0 +1,66 @@
+# Code Block Builder Notes
+
+## What Builder Should Configure
+
+- code block field type
+- code content
+- inserted input fields inside code content
+- alias parsing
+- auto trigger
+- custom button text
+
+## Stable Writing Rules
+
+- Always emit `qf_output = {...}`
+- Never emit `const qf_output = {...}`
+- Never emit `let qf_output = {...}`
+
+## Useful CRM Pattern
+
+Inputs:
+- customer name
+- source
+- budget
+- timing
+- decision-maker flag
+
+Outputs:
+- score
+- level
+- priority
+- summary
+- next follow date
+
+## Target Field Rules
+
+Required:
+- every `outputs[*].target_field` must point to an existing field
+
+Allowed target field types:
+- text
+- long text
+- number
+- amount
+- date
+- datetime
+- single select
+- multi select
+- boolean
+
+Do not bind code block outputs to:
+- q_linker
+- code_block
+- relation
+- subtable
+- attachment
+- member
+- department
+- address
+
+## Safe Verification
+
+- `app_get_fields`
+- `record_insert_schema_get`
+- optional `record_code_block_run`
+
+Treat configuration verification and runtime verification as separate checks.