@josephyan/qingflow-app-builder-mcp 0.2.0-beta.7 → 0.2.0-beta.71

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

@@ -6,34 +6,12 @@ Use this when fields already exist and the task is only about form grouping or o
 
 1. `app_read_fields`
 2. `app_read_layout_summary`
-3. `app_layout_plan`
+3. `builder_tool_contract` when the section shape is not already obvious
 4. `app_layout_apply`
 
 ## Example
 
-Plan a balanced merge layout:
-
-```json
-{
-  "tool_name": "app_layout_plan",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "mode": "merge",
-    "sections": [
-      {
-        "title": "基础信息",
-        "rows": [
-          ["客户名称", "订单金额"],
-          ["状态", "跟进日期"]
-        ]
-      }
-    ]
-  }
-}
-```
-
-Apply the layout. This publishes by default:
+Apply a custom layout with the canonical public section shape:
 
 ```json
 {
@@ -74,8 +52,17 @@ Only happens in `mode=replace`. Switch to `mode=merge` unless you intend to plac
 
 Re-read with `app_read_layout_summary`. 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

@@ -6,8 +6,7 @@ Use this when the app already exists and the task is only about fields.
 
 1. `app_resolve`
 2. `app_read_fields`
-3. `app_schema_plan`
-4. `app_schema_apply`
+3. `app_schema_apply`
 
 ## Example
 
@@ -23,27 +22,6 @@ Read current fields first:
 }
 ```
 
-Plan the patch:
-
-```json
-{
-  "tool_name": "app_schema_plan",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "add_fields": [
-      {"name": "跟进日期", "type": "date"}
-    ],
-    "update_fields": [
-      {"selector": {"name": "金额"}, "set": {"name": "订单金额", "required": true}}
-    ],
-    "remove_fields": [
-      {"name": "旧字段"}
-    ]
-  }
-}
-```
-
 Apply the patch:
 
 ```json

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

@@ -1,27 +1,47 @@
 # Update Views
 
-Use this when the task is only about list, card, or board views.
+Use this when the task is only about table, card, board, or gantt views.
 
 ## Minimal sequence
 
-1. `app_read_fields`
-2. `app_read_views_summary`
-3. `app_views_plan`
+1. `builder_tool_contract(tool_name="app_views_apply")`
+2. `app_read_fields`
+3. `app_read_views_summary`
 4. `app_views_apply`
+5. `app_read_views_summary` 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`
+- If apply returns `partial_success`, inspect `verification.by_view` and `details.filter_mismatches` before claiming the filters are active
 
 ## Example
 
-Plan a default table view:
+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`
+- For gantt, use `start_field`, `end_field`, and optionally `title_field`
+- If `app_read_views_summary` shows duplicate view names, include `view_key` in `upsert_views[]` and update that exact target
+
+Apply a default table view:
 
 ```json
 {
-  "tool_name": "app_views_plan",
+  "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": ["订单编号", "客户名称", "订单金额", "状态"]
       }
@@ -30,8 +50,9 @@ Plan a default table view:
   }
 }
 ```
+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`.
 
-Apply it:
+Board example:
 
 ```json
 {
@@ -39,12 +60,12 @@ Apply it:
   "arguments": {
     "profile": "default",
     "app_key": "APP_123",
-    "publish": true,
     "upsert_views": [
       {
-        "name": "全部订单",
-        "type": "table",
-        "columns": ["订单编号", "客户名称", "订单金额", "状态"]
+        "name": "按状态看板",
+        "type": "board",
+        "group_by": "状态",
+        "columns": ["订单编号", "客户名称", "订单金额"]
       }
     ],
     "remove_views": []
@@ -52,7 +73,7 @@ Apply it:
 }
 ```
 
-Board example:
+Gantt example with filters:
 
 ```json
 {
@@ -62,10 +83,19 @@ Board example:
     "app_key": "APP_123",
     "upsert_views": [
       {
-        "name": "按状态看板",
-        "type": "board",
-        "group_by": "状态",
-        "columns": ["订单编号", "客户名称", "订单金额"]
+        "name": "项目甘特图",
+        "type": "gantt",
+        "columns": ["项目名称", "开始日期", "结束日期", "状态"],
+        "start_field": "开始日期",
+        "end_field": "结束日期",
+        "title_field": "项目名称",
+        "filters": [
+          {
+            "field_name": "状态",
+            "operator": "eq",
+            "value": "进行中"
+          }
+        ]
       }
     ],
     "remove_views": []
@@ -81,16 +111,52 @@ At least one `columns` or `group_by` field name does not exist.
 
 ### `INVALID_VIEW_TYPE`
 
-Public view types are only `table`, `card`, `board`.
+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_read_views_summary` 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.
+
 ## Notes
 
-- `fields` is accepted as an alias for `columns`
-- `tableView -> table`
-- `cardView -> card`
-- `kanban -> board`
+- `fields` is accepted as an alias for `columns`, but skill examples should still use `columns`
+- `column_names` should not appear in skill examples
+- `app_read_views_summary` should be treated as canonical readback and now returns `columns`
+- If `app_views_apply` returns `AMBIGUOUS_VIEW`, stop and re-run `app_read_views_summary`; then retry with the exact `view_key`
+- `filters` are ANDed together as one flat condition group
 - `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. Use after MCP is connected and authenticated, especially for CRM-style scoring, lookup, and enrichment forms.
+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_read_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_read_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_read_fields`
+- `record_insert_schema_get`
+- optional `record_code_block_run`
+
+Treat configuration verification and runtime verification as separate checks.

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

@@ -0,0 +1,77 @@
+# Q-Linker Builder Notes
+
+## What Builder Should Configure
+
+- `remoteLookupConfig`
+- alias parsing
+- target field binding
+- auto trigger
+- custom button text
+
+## Current Supported Scope
+
+- custom mode only
+- standard request fields
+- alias path parsing
+- target field binding to existing ordinary fields
+
+## Recommended Public APIs For Samples
+
+### Httpbin
+
+- URL: `https://httpbin.org/get`
+- Good for:
+  - query echo
+  - request URL echo
+
+Useful paths:
+- `$.args.keyword`
+- `$.url`
+
+### Open-Meteo Geocoding
+
+- URL: `https://geocoding-api.open-meteo.com/v1/search`
+- Good for:
+  - place normalization
+  - country
+  - lat/lng summary
+
+Useful paths:
+- `$.results[0].name`
+- `$.results[0].country`
+- `$.results[0].latitude`
+- `$.results[0].longitude`
+
+## Target Field Rules
+
+Required:
+- every `outputs[*].target_field` must point to an existing field
+
+Prefer:
+- text
+- long text
+- number
+- amount
+- date
+- datetime
+- single select
+- multi select
+- boolean
+
+Avoid:
+- q_linker
+- code_block
+- relation
+- subtable
+- attachment
+- member
+- department
+- address
+
+## Safe Verification
+
+- `app_read_fields`
+- `record_insert_schema_get`
+- `record_insert`
+
+This verifies that the configuration does not break the form page, even before runtime execution is tested.

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b7"
+__version__ = "0.2.0b48"