@josephyan/qingflow-app-builder-mcp 1.1.25 → 1.1.27

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

@@ -19,40 +19,27 @@ Before picking tools, decide which layer the request targets:
 
 If the user asks for multiple forms/modules that relate to each other, this is a package-level multi-app task, not a single-app create.
 
-Use this split consistently:
-
-- Complete system/package: `package_apply` first, then one `app_schema_apply(package_id=..., apps=[...])`.
-- Single app: `app_resolve/app_get` first, then app-scoped apply tools.
-- Record/task/data operation: leave builder and use record/task skills.
-
-Decision gate before writing:
-
-| Evidence | Action |
-| --- | --- |
-| User gives an `app_key`, `view_key`, `chart_id`, `dash_key`, or exact `package_id` | Treat the task as an update to that existing target unless the user explicitly asks for a new one |
-| User names several forms/modules or asks for a system/package | Use the complete-system path; do not compress them into one app |
-| Same or very similar package/app already exists and the user did not say extend/replace/new | Stop and ask whether to extend existing, repair missing parts, or create a new target |
-| Existing readback already contains part of the requested system | List verified existing resources, identify gaps, and patch only missing or incorrect slices |
-| A write is uncertain: timeout, `partial_success`, `write_executed=true`, or `safe_to_retry=false` | Read back before retrying; do not create `V2`, `测试`, timestamp, or random-suffix resources |
-
 ## Resolve
 
-- `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; `package_name` without `package_id` creates a package; layout/group/order changes require package edit permission because they call the backend package ordering route
+- `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
 - `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`; 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
+- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_id`
 
 ## Summary reads
 
+All `app_get_*` tools accept either `app_key` (single) or `app_keys[]` (batch). Batch returns `{status, apps[], errors[]}` — prefer batch when reading multiple apps in one step.
+
 - `app_get`: overall app config health, publish state, counts, and builder editability
 - `app_get_fields`: field names, types, required flags, section ids
 - `app_get_layout`: sections, rows, unplaced fields
 - `app_get_views`: current view names, types, columns, group-by
-- `app_get_flow`: workflow enabled state, nodes, transitions
+- `app_get_flow`: workflow enabled state, full spec (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.
+- `app_get_associated_resources`: current associated resource pool (draft state)
+- `app_publish_verify`: publish state and package tag verification — accepts `app_keys[]` for multi-app batch
 - `portal_get`: current portal config detail and component inventory
 
 ## Apply tools
@@ -60,15 +47,14 @@ Decision gate before writing:
 These execute normalized patches. Some app apply tools publish by default and still accept `publish=false`; custom button and associated-resource apply publish after at least one write succeeds and do not expose that switch.
 
 - `app_schema_apply`: create app shell or change fields
-- `app_layout_apply`: merge or replace layout
-- `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; for normal view-specific business buttons, declare `action_buttons` in the view object or `patch_views[].set`; new views default associated report/view display to visible with `limit_type="all"`
-- `app_custom_buttons_apply`: advanced custom-button maintenance only: style/icon changes, cross-view reuse, deleting button bodies, bulk reordering bindings, or exact qRobot/wings configs. Use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; 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. 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` with `target_field + operator + source_field/value` 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 `app_get_fields.chart_fields` as the source for dimensions, metrics, and filters. Use semantic `metric`, `metrics`, `group_by`, and `where`: `target/indicator` for one KPI, `bar/columnar/pie` for distribution, `line/area` for trend, `table/detail/summary` for tabular summaries, and `dualaxes` for two-metric comparison. Do not use `summary` for a single metric card. Use `filters` with `field_name + operator + value/values`; the tool compiles them to QingBI string judge types. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; avoid raw `indicator_field_ids`, `selectedMetrics`, and QingBI filter matrices on the main path; charts are immediate-live and do not publish; use `chart_id` when names are not unique; for complete systems, keep chart writes business-scoped, commonly 4-8 upserts by app or topic. Larger calls are accepted; if `CHART_UPSERT_BATCH_SIZE_RECOMMENDED` appears, read back before retrying and only repair failed items.
-- `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. Build portals only after referenced apps, raw `view_key`s, and chart ids/keys are known. PC layout uses 24 columns: components with the same `y` must have the same `rows`, same-row `cols` should sum to 24, metric cards use `rows=5`, BI charts use `rows=7`, data views use `rows=11`, and business-entry grids must include real `config.items[]`. Use business entry -> metrics -> BI charts -> concrete data views; do not use platform default views or raw `source_type: "filter"` as the main path.
+- `app_layout_apply`: layout-only maintenance for existing apps; new app layout belongs in `app_schema_apply` `form.sections`
+- `app_flow_apply`: replace full workflow spec; use `patch_nodes[]` (`{id, set, unset}`) to update specific nodes without rewriting the full spec
+- `app_views_apply`: use top-level `views[]` for same-app/cross-app batch create, patch, and remove; view business actions belong in each view item's `action_buttons`
+- `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. Use `apps[]` for multi-app batch.
+- `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; use `apps[]` for multi-app batch
+- `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; sections use a 24-column PC grid — all components in the same row (same `y`) must share the same `rows` value and their `cols` must sum to exactly 24; mismatched `rows` causes height misalignment, `cols` under 24 leaves trailing blank space; use `patch_sections[]` (`{chart/view_ref/order, set, unset}`) to update individual sections without replacing all
 
-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.
+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_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`, `patch_nodes: [{"id": "approve_1", "set": {...}}]`, `patch_sections: [{"chart": {"chart_key": "ck_001"}, "set": {"title": "新标题"}}]`. 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.
 
 ## Explicit post-apply tools
 
@@ -79,29 +65,27 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Create one app inside an existing package:
   `package_get -> app_resolve -> app_schema_apply`
 - Create a brand new package, then create one app in it:
-  `package_apply(package_name, icon, color) -> app_schema_apply`
+  `package_apply(create_if_missing=true) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_apply(package_name, icon, color) -> app_schema_apply(apps[])`; use `apps[].client_key` plus `target_app_ref`, or `target_app` when referencing by app name
+  `package_apply(create_if_missing=true) -> app_schema_apply(apps[] with form.sections)`
 - Update fields on an existing app:
   `app_resolve -> app_get_fields -> app_schema_apply`
 - Tidy layout:
-  `app_get_fields -> app_get_layout -> builder_tool_contract (if shape is unclear) -> app_layout_apply`
+  `app_get_fields -> app_get_layout -> app_layout_apply`
 - Add workflow:
   `builder_tool_contract -> app_get_fields -> app_get_flow -> role_search/member_search -> app_flow_apply -> app_get_flow`
+- Update specific flow nodes:
+  `app_get_flow -> app_flow_apply.patch_nodes[]`
 - Add views:
-  `builder_tool_contract -> app_get_fields -> app_get_views -> app_views_apply.patch_views/upsert_views -> app_get_views`
-- Add ordinary view buttons:
-  `app_get_views -> app_views_apply.patch_views/upsert_views with action_buttons -> app_get_views`
-- Maintain advanced custom buttons:
-  `app_get -> app_custom_buttons_apply.patch_buttons/upsert_buttons + view_configs -> app_get_views`
-- Add QingBI charts:
-  `builder_tool_contract -> app_get_fields -> app_get_charts -> app_charts_apply.patch_charts/upsert_charts -> app_get_charts`
+  `app_get_fields -> app_get_views -> app_views_apply.views[] -> app_get_views`
+- Add QingBI charts for a portal:
+  `portal_apply.sections[].chart`
 - Show an existing QingBI chart inside a Qingflow app/view:
   `app_get -> app_associated_resources_apply.upsert_resources/patch_resources + view_configs -> app_get`
 - Create or update a portal:
   `builder_tool_contract -> portal_get -> portal_apply -> portal_get`
-- Patch one portal section:
-  `portal_get -> portal_apply.patch_sections[] -> portal_get`
+- Update portal section(s) without replacing all:
+  `portal_get -> portal_apply.patch_sections[]`
 
 ## Avoid
 
@@ -119,4 +103,3 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Do not omit assignees on approval/fill/copy nodes
 - Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
 - Do not guess role ids, member ids, or editable field ids; resolve names first
-- Do not force agent-authored schema into backend-internal names when public keys exist: write icons as `icon + color` first; `icon_config` / `icon:{name,color}` are compatibility aliases only. Options may use `{label,value}`, and same-call relation targets may use `target_app_ref` / `target_app`.

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

@@ -6,19 +6,18 @@ Use this when the app already exists and the task is only about workflow.
 
 1. `builder_tool_contract(tool_name="app_flow_apply")`
 2. `app_get_fields`
-3. Confirm the app has one explicit business status field, usually a `select` named `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`
-4. `app_get_flow`
-5. `role_search` or `member_search`
-6. `role_create` if the user wants a reusable directory role and no good role exists
-7. start from a canonical preset when possible
-8. patch the skeleton instead of freehanding a full graph
-9. reuse preset node ids when patching:
+3. `app_get_flow`
+4. `role_search` or `member_search`
+5. `role_create` if the user wants a reusable directory role and no good role exists
+6. start from a canonical preset when possible
+7. patch the skeleton instead of freehanding a full graph
+8. reuse preset node ids when patching:
    - `basic_approval` -> patch `approve_1`
    - `basic_fill_then_approve` -> patch `fill_1` and `approve_1`
    Do not add a second approval/fill node with a new id unless you are intentionally replacing the skeleton.
    The MCP now auto-aligns the simplest single-node preset overrides, but still prefer explicit preset ids so the merged graph stays predictable.
-10. `app_flow_apply`
-11. `app_get_flow` when apply returns `partial_success` or the user asked for verification
+9. `app_flow_apply`
+10. `app_get_flow` when apply returns `partial_success` or the user asked for verification
 
 If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
 
@@ -62,6 +61,34 @@ For flexible business requirements, do not jump straight to a full custom graph.
 2. identify the business-specific changes
 3. patch nodes/transitions explicitly
 
+## Targeted node updates
+
+To change one or a few nodes without rewriting the full spec, use `patch_nodes[]` instead of `spec`:
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "patch_nodes": [
+      {
+        "id": "approve_1",
+        "set": {
+          "name": "总监审批",
+          "assignees": {"role_names": ["总监"]}
+        }
+      }
+    ]
+  }
+}
+```
+
+`patch_nodes[]` reads the current flow, merges `set` keys and removes `unset` keys on the matched node, then writes the full spec back. It returns `FLOW_NODE_NOT_FOUND` if the `id` does not match any existing node — call `app_get_flow` first to confirm ids.
+
+Do NOT use `patch_nodes` and `spec` together in the same call.
+
 Public flow building is intentionally limited to linear workflows. Use only:
 
 - `start`
@@ -97,18 +124,7 @@ Preferred fix order:
 
 ### `FLOW_DEPENDENCY_MISSING`
 
-The workflow depends on fields that do not exist yet, usually an explicit business status field. Fix schema first.
-
-Do:
-
-- add a business field such as `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`
-- use type `select` / `single_select`
-- use business options such as `草稿`, `进行中`, `已完成`
-
-Do not:
-
-- create platform workflow system fields such as `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`
-- skip the flow and still report workflow completion
+The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
 
 Preferred recovery:
 
@@ -161,7 +177,7 @@ Do not copy internal keys from old plan outputs or logs, including:
 
 ## Notes
 
-- `mode=replace` is the only supported flow apply mode
+- `mode=replace` is the only supported flow apply mode when using `spec`; `patch_nodes[]` does not require a `mode`
 - `app_flow_apply` publishes by default
 - Prefer roles over explicit members unless the user explicitly asks for named members
 - `basic_approval` and `basic_fill_then_approve` are skeletons, not complete business workflows

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

@@ -10,18 +10,6 @@ Use this when the app already exists and the task is only about fields.
 
 ## Example
 
-Do not add platform system fields as form controls: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are generated by Qingflow; use readback/list fields when you need them.
-
-Field patch rules:
-
-- Re-read fields first, then choose `add_fields`, `update_fields`, or `remove_fields`. If a field already exists, use `update_fields` instead of adding a duplicate.
-- Drafts may use intuitive type aliases: `multiline -> long_text`, `select -> single_select`, `checkbox -> multi_select`, `currency -> amount`, `mobile -> phone`. Readback canonical types are normal and do not prove a failed update.
-- `title` and `label` are accepted aliases for `name`, but the preferred public key is `name`.
-- Keep exactly one top-level data title field after the patch. `as_data_cover` is optional and only valid on top-level `attachment`.
-- Select fields must keep a clear `options` set. Sample data and filters should use those option labels or ids.
-- Relation fields must use `target_app_key` for existing apps, or `target_app_ref` only in same-batch app creation. `display_field` and `visible_fields` are selector objects such as `{"name": "客户名称"}`, not bare strings.
-- Do not impose a one-relation-field limit when updating schema; add the relation fields the business needs and rely on backend validation/readback.
-
 Read current fields first:
 
 ```json
@@ -76,11 +64,9 @@ Treat it as uncertain write state. Read back with `app_get_fields` before retryi
 
 - `title` and `label` are accepted aliases for `name`
 - `textarea -> long_text`
-- `multiline` / `multiline_text -> 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
-- `数据ID`, `编号`, applicant/creation/update time, and workflow status fields are system-generated and must not appear in `add_fields`

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

@@ -28,25 +28,17 @@ 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 the unified fixed-filter DSL: `field_name`, `operator`, `value`/`values`; do not write raw `judgeType` / `judgeValues`
+- 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`.
-- Do not create views named `全部数据`, `我的数据`, `我发起的`, `待办`, `已办`, or `抄送`. These are built-in default/system views. New views must use business-specific names such as `订单台账视图`, `客户跟进视图`, or `逾期任务看板`.
-- To change a built-in default/system view, first read the existing raw `view_key` from `app_get.views` or `app_get_views`, then use `patch_views` or a full `upsert_views` item with that `view_key`.
+- When creating any new table or card view, always include `query_conditions` with `enabled: true`. In `rows`, list the fields users would most commonly search by — typically the data-title field, any status/type select fields, date fields, and member fields. Do not omit `query_conditions` or leave `rows` empty on a new view.
 - 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` with `target_field + operator + source_field/value` 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. `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.
-- For ordinary view-specific business buttons, declare `action_buttons` inside `upsert_views[]` or `patch_views[].set`. Use `app_custom_buttons_apply` only for style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings configs.
-- Choose the button by user intent before choosing a trigger type:
-  - current record -> downstream/related record: `add_data` with `target_app_key + field_mappings`
-  - global independent entry: `add_data` on `header` without current-record `source_field`
-  - URL/SOP/help page: `link` with `url`
-  - approval/status transition/close task: do not fake it with a normal button; use workflow/task action or exact existing automation config
-- Button placement choice: `header` is global and has no current-row context; `list` is row/list action; `detail` is the safest current-record context action. Do not use current-record `field_mappings` on `header`.
 
-Apply a business table view:
+Apply a default table view:
 
 ```json
 {
@@ -57,10 +49,16 @@ Apply a business table view:
     "publish": true,
     "upsert_views": [
       {
-        "name": "订单台账视图",
+        "name": "全部订单",
         "view_key": "VIEW_KEY_IF_DUPLICATE_NAMES_EXIST",
         "type": "table",
-        "columns": ["订单编号", "客户名称", "订单金额", "状态"]
+        "columns": ["订单编号", "客户名称", "订单金额", "状态", "负责人", "创建时间"],
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["订单编号", "客户名称"], ["状态", "负责人"], ["创建时间"]]
+        }
       }
     ],
     "remove_views": []
@@ -69,48 +67,6 @@ Apply a business 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`.
 
-Create a table view with ordinary business buttons:
-
-```json
-{
-  "tool_name": "app_views_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "publish": true,
-    "upsert_views": [
-      {
-        "name": "工单执行视图",
-        "type": "table",
-        "columns": ["工单编号", "产品", "状态", "负责人"],
-        "action_buttons": [
-          {
-            "text": "创建质检单",
-            "action": "add_data",
-            "target_app_key": "QUALITY_APP",
-            "field_mappings": [
-              {"source_field": "数据ID", "target_field": "关联工单"}
-            ],
-            "default_values": {"处理状态": "待处理"},
-            "placement": "detail",
-            "visible_when": [
-              {"field_name": "状态", "operator": "eq", "value": "已完工"}
-            ]
-          },
-          {
-            "text": "查看作业说明",
-            "action": "link",
-            "url": "https://example.com/sop",
-            "placement": "header"
-          }
-        ]
-      }
-    ],
-    "remove_views": []
-  }
-}
-```
-
 Existing table view: replace only frontend query conditions:
 
 ```json
@@ -321,32 +277,7 @@ 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.
-
-Supported `query_conditions.rows` fields are query-panel fields:
-
-- text / long text
-- number / amount
-- date / datetime
-- single select / multi select
-- member / department
-- phone / email
-- boolean
-
-Do not use these fields in `query_conditions`:
-
-- relation
-- attachment
-- subtable or subtable subfield
-- address/location
-- Q-Linker
-- code block
-
-Fix path:
-
-- If you wanted a saved filter that opens with the view, use `filters`.
-- If you wanted a related report/view to match the current record, use `app_associated_resources_apply.match_mappings`.
-- If you only need frontend search fields, remove unsupported fields from `query_conditions.rows` and keep query-panel supported fields only.
+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
 
@@ -355,6 +286,6 @@ Fix path:
 - `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 and should only contain query-panel supported fields
+- `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

@@ -1,14 +1,12 @@
 ---
 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.
+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
 
-> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
-
 Use this skill when the user wants to build or repair:
 - `code_block` fields
 - `q_linker` fields
@@ -60,7 +58,7 @@ For code block or Q-Linker work, use this order:
 
 1. Resolve the app and read fields:
    - `app_resolve`
-   - `app_get_fields`
+   - `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:
@@ -117,7 +115,7 @@ Hard rules:
 
 After each code block or Q-Linker change, verify all of these:
 
-- `app_get_fields` shows the intended field type
+- `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

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_get_fields`
+- `app_read_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_get_fields`
+- `app_read_fields`
 - `record_insert_schema_get`
 - `record_insert`
 

package/skills/qingflow-mcp-setup/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: qingflow-mcp-setup
+description: Install, connect, authenticate, and troubleshoot the Qingflow MCP server in local AI clients such as Claude Desktop or any stdio-compatible MCP client. Use when the user wants to configure the MCP, verify local startup, log in with token/password, select a workspace, or fix connection/authentication issues.
+metadata:
+  short-description: Install and connect the Qingflow MCP locally
+---
+
+# Qingflow MCP Setup
+
+## Overview
+
+This skill sets up the local Qingflow MCP server, connects it to a local AI client, and verifies authentication and workspace selection. Use it for installation, client configuration, token login, and connection troubleshooting.
+
+## Workflow
+
+Follow these steps in order.
+
+`feedback_submit` is also available as a cross-cutting helper when setup or MCP capability gaps still block the user after reasonable troubleshooting. It does not require Qingflow login or workspace selection, and should be called only after explicit user confirmation.
+
+Before configuration or live calls, identify the target environment explicitly as `test` or `prod`, then read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
+
+### Step 1: Verify the local project path
+
+Resolve the repository root first. In this repo, the MCP server should live at:
+
+- `<repo_root>/qingflow-support/mcp-server`
+
+Key entrypoint:
+
+- `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
+
+If the path differs, stop and update all client config snippets before proceeding.
+If the skill is installed under `$CODEX_HOME/skills` instead of the repo-local `.codex/skills`, set `QINGFLOW_MCP_ROOT=<repo_root>/qingflow-support/mcp-server` before running `scripts/check_local_server.sh`.
+
+### Step 2: Install local dependencies
+
+Run:
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+python3 -m venv .venv
+./.venv/bin/pip install -e '.[dev]'
+```
+
+Use `scripts/check_local_server.sh` to verify the entrypoint and virtualenv. The script will first try `QINGFLOW_MCP_ROOT`, then the current git repo, then a repo-local `.codex/skills` layout.
+
+### Step 3: Configure the local AI client
+
+For any stdio-compatible MCP client, map these values:
+
+- `command`: `<repo_root>/qingflow-support/mcp-server/qingflow-mcp`
+- `args`: `[]`
+- `env.QINGFLOW_MCP_DEFAULT_BASE_URL`: the target backend URL for the active environment
+- `env.QINGFLOW_MCP_DEFAULT_QF_VERSION`: set this when the environment must route to a specific version such as `canary`
+
+Client-specific snippets:
+
+- Claude Desktop: read [references/claude-desktop.md](references/claude-desktop.md)
+- Generic stdio MCP clients: read [references/generic-stdio.md](references/generic-stdio.md)
+
+When both test and production are in play, keep separate config snippets or clearly labeled `env` blocks so the user can switch without ambiguity.
+
+### Step 4: Validate startup
+
+The server is a stdio MCP process. A direct terminal launch may print nothing and wait for a client. That is normal.
+
+Manual startup command:
+
+```bash
+cd <repo_root>/qingflow-support/mcp-server
+./qingflow-mcp
+```
+
+Prefer validating through the client after config is added.
+
+### Step 5: Authenticate and select workspace
+
+Recommended order inside the client:
+
+1. `auth_use_token` or `auth_login`
+2. `workspace_list`
+3. `workspace_select`
+4. Only then use business tools
+
+If the user already knows the target workspace, prefer `auth_use_token(..., ws_id=<id>)`.
+After auth, prefer one read-only tool call that returns `request_route` so you can confirm the live `base_url` and `qf_version` before proceeding.
+`auth_use_token` is a tool call, not a custom HTTP header. The runtime injects `token`, `wsId`, and when needed `Cookie: qfVersion=...` after the session is established.
+Do not skip `workspace_select` on production paths. If `/user` does not return a version lane, the session now falls back to the workspace `systemVersion`.
+
+### Step 6: Troubleshoot in the right layer
+
+- If the client cannot launch the server, check path, execute permission, and `.venv`
+- If tools return `auth required`, re-run `auth_use_token` or `auth_login`
+- If tools return `workspace not selected`, call `workspace_list` and `workspace_select`
+- If calls fail after a working session, assume token expiry and re-authenticate
+- If the browser shows data but MCP does not, compare `request_route` against the browser environment and check whether `qf_version` should be `canary`
+
+## Guardrails
+
+- Never write tokens into the skill files
+- Never assume a workspace is selected until `auth_whoami` or `workspace_select` confirms it
+- When debugging, distinguish server startup issues from Qingflow auth issues
+- When the user mentions production, restate the exact `base_url`, `qf_version`, and workspace before any live validation
+- If setup is complete but the current MCP capability is still unsupported or the user's need still cannot be satisfied, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation
+
+## Resources
+
+- Environment switching: [references/environments.md](references/environments.md)
+- Claude Desktop config: [references/claude-desktop.md](references/claude-desktop.md)
+- Generic stdio config: [references/generic-stdio.md](references/generic-stdio.md)
+- Local checks: [scripts/check_local_server.sh](scripts/check_local_server.sh)

package/skills/qingflow-mcp-setup/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow MCP Setup"
+  short_description: "Install and connect the Qingflow MCP locally"
+  default_prompt: "Use $qingflow-mcp-setup to install and connect the Qingflow MCP in a local AI client, and to verify the active base_url, qf_version, auth state, and workspace selection."

package/skills/qingflow-mcp-setup/references/claude-desktop.md

@@ -0,0 +1,34 @@
+# Claude Desktop
+
+Use this when the user wants to install Qingflow MCP in Claude Desktop.
+
+## Config snippet
+
+```json
+{
+  "mcpServers": {
+    "qingflow": {
+      "command": "<ABSOLUTE_PATH_TO_REPO>/qingflow-support/mcp-server/qingflow-mcp",
+      "args": [],
+      "env": {
+        "QINGFLOW_MCP_DEFAULT_BASE_URL": "<QINGFLOW_BASE_URL>"
+      }
+    }
+  }
+}
+```
+
+## Environment examples
+
+- `prod` (default): set `QINGFLOW_MCP_DEFAULT_BASE_URL` to `https://qingflow.com/api`
+- `test`: if needed, set `QINGFLOW_MCP_DEFAULT_BASE_URL` to the explicitly provided non-production backend
+
+Keep separate snippets for `test` and `prod` so switching environments does not require editing values in-place under pressure.
+
+## Notes
+
+- After updating the config, restart Claude Desktop
+- Replace `<ABSOLUTE_PATH_TO_REPO>` with the real checkout path on the current machine
+- If the server path changes, update the `command` field
+- The server is local stdio MCP, so no remote URL is required
+- Do not store Qingflow token in Claude Desktop config; pass it through `auth_use_token` inside the chat