@josephyan/qingflow-app-builder-mcp 1.0.8 → 1.1.1

package/skills/qingflow-app-builder/references/match-rules.md

@@ -0,0 +1,114 @@
+# Builder Match Rules
+
+Use this reference for builder-side field matching rules in custom buttons and associated view/report filters.
+
+This is not the same thing as `record_access` analysis filters or normal view `filters`.
+
+## Where These Rules Apply
+
+- `app_custom_buttons_apply.upsert_buttons[].trigger_add_data_config.field_mappings`
+- `app_custom_buttons_apply.patch_buttons[].set.trigger_add_data_config.field_mappings`
+- `app_associated_resources_apply.upsert_resources[].match_mappings`
+- `app_associated_resources_apply.patch_resources[].set.match_mappings`
+
+Prefer semantic mappings. Do not handwrite raw `que_relation` or `match_rules` unless you are preserving an existing backend config.
+
+## System Fields
+
+System fields can participate in mappings:
+
+- `数据ID`, `row_record_id`, `apply_id`, `_id` -> `field_id=-17`
+  This is the current record's real apply/record ID.
+- `编号`, `数据编号`, `record_number` -> `field_id=0`
+  This is the frontend-visible record number. It may be custom formatted and is not the same as `数据ID`.
+
+Explicit selectors such as `{"field_id": -17}` and `{"field_id": 0}` are allowed and remove ambiguity.
+
+## Custom Buttons
+
+Use `field_mappings` for dynamic values copied from the current source record:
+
+```json
+{
+  "target_app_key": "WORKLOG_APP",
+  "field_mappings": [
+    {"source_field": "数据ID", "target_field": "关联员工"},
+    {"source_field": "员工名称", "target_field": "员工姓名"}
+  ],
+  "default_values": {
+    "状态": "待提交"
+  }
+}
+```
+
+Use `default_values` only for static constants. Do not use `default_values` as the preferred way to pass the current record.
+
+For an existing button, put the same semantic config under `patch_buttons[].set`:
+
+```json
+{
+  "button_id": 3858041,
+  "set": {
+    "trigger_add_data_config": {
+      "target_app_key": "WORKLOG_APP",
+      "field_mappings": [
+        {"source_field": "数据ID", "target_field": "关联员工"}
+      ],
+      "default_values": {
+        "状态": "待提交"
+      }
+    }
+  }
+}
+```
+
+## Associated Resources
+
+Use `match_mappings` for associated view/report filters:
+
+```json
+{
+  "graph_type": "view",
+  "target_app_key": "WORKLOG_APP",
+  "view_key": "WORKLOG_VIEW",
+  "match_mappings": [
+    {"target_field": "关联员工", "source_field": "数据ID"},
+    {"target_field": "状态", "value": "待提交"}
+  ]
+}
+```
+
+Dynamic conditions use `source_field`; static conditions use `value`.
+
+For an existing associated resource, put the same filter mapping under `patch_resources[].set`:
+
+```json
+{
+  "associated_item_id": 3497587,
+  "set": {
+    "match_mappings": [
+      {"target_field": "关联员工", "source_field": "数据ID"}
+    ]
+  }
+}
+```
+
+## Type Compatibility
+
+- Relation fields: match another relation field with the same target app, or match `数据ID(-17)` when the target relation points to the current source app.
+- Record ID `数据ID(-17)`: can match relation fields that point to the current source app, or ID-compatible text/number fields.
+- Record number `编号(0)`: can match text, long text, number, amount, or another record-number field.
+- Member fields: only match member fields.
+- Department fields: only match department fields.
+- Option fields: single select, multi select, and boolean can match option-family fields or static option values.
+- Date fields: date and datetime can match each other.
+- Text fields: text, long text, phone, and email can match each other.
+- Number fields: number and amount can match each other.
+- Attachment, subtable, code block, Q-Linker, and address fields are not default match fields.
+
+## Error Interpretation
+
+- Field not found: re-read `app_get` or `app_get_fields` and retry with an exact title or `field_id`.
+- Type mismatch: choose a compatible source/target pair from the matrix above.
+- Reference source mismatch: the target relation field points to a different app; choose a relation field that points back to the current source app, or match a non-relation field.
+- Mixed raw and semantic modes: use either semantic `field_mappings/match_mappings` or raw `que_relation/match_rules`, never both in the same item.

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

@@ -30,24 +30,33 @@ If the user asks for multiple forms/modules that relate to each other, this is a
 
 ## 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
+- `app_get_buttons`: current custom button list (draft state)
+- `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
 
-These execute normalized patches and publish by default unless `publish=false`.
+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`: upsert or remove views
-- `app_charts_apply`: upsert/remove/reorder QingBI charts; 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
+- `app_layout_apply`: merge or replace layout; use `apps[]` (each item `{app_key, mode?, sections}`) for multi-app batch
+- `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 `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"`; use `apps[]` for multi-app batch
+- `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. Use `apps[]` for multi-app batch.
+- `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_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_ref/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": {...}}]`, `patch_nodes: [{"id": "approve_1", "set": {...}}]`, `patch_sections: [{"chart_ref": {"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
 
@@ -60,19 +69,25 @@ These execute normalized patches and publish by default unless `publish=false`.
 - Create a brand new package, then create one app in it:
   `package_apply(create_if_missing=true) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_apply(create_if_missing=true) -> per-app app_schema_apply -> relation field patches`
+  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`
 - 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`
 - 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 -> app_get_views`
+  `builder_tool_contract -> app_get_fields -> app_get_views -> app_views_apply.patch_views/upsert_views -> app_get_views`
 - Add QingBI charts:
-  `builder_tool_contract -> app_get_fields -> app_get_charts -> app_charts_apply -> app_get_charts`
+  `builder_tool_contract -> app_get_fields -> app_get_charts -> app_charts_apply.patch_charts/upsert_charts -> app_get_charts`
+- 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`
+- Update portal section(s) without replacing all:
+  `portal_get -> portal_apply.patch_sections[]`
 
 ## Avoid
 

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

@@ -61,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`
@@ -149,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

@@ -32,10 +32,12 @@ Apply the patch:
     "app_key": "APP_123",
     "publish": true,
     "add_fields": [
-      {"name": "跟进日期", "type": "date"}
+      {"name": "跟进日期", "type": "date"},
+      {"name": "数据封面", "type": "attachment", "as_data_cover": true}
     ],
     "update_fields": [
-      {"selector": {"name": "金额"}, "set": {"name": "订单金额", "required": true}}
+      {"selector": {"name": "金额"}, "set": {"name": "订单金额", "required": true}},
+      {"selector": {"name": "客户名称"}, "set": {"as_data_title": true}}
     ],
     "remove_fields": [
       {"name": "旧字段"}
@@ -66,3 +68,5 @@ Treat it as uncertain write state. Read back with `app_get_fields` before retryi
 - `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

@@ -6,17 +6,20 @@ Use this when the task is only about table, card, board, or gantt views.
 
 1. `builder_tool_contract(tool_name="app_views_apply")`
 2. `app_get_fields`
-3. `app_get_views`
+3. `app_get` for current view/chart/button inventory and app-level associated resource ids
 4. `app_views_apply`
-5. `app_get_views` again whenever apply returns `failed` or `partial_success`
+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`
-- If apply returns `partial_success`, inspect `verification.by_view` and `details.filter_mismatches` before claiming the filters are active
+- 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
 
@@ -26,8 +29,14 @@ Canonical rules before any example:
 - 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`.
+- 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. `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` shows duplicate view names, include `view_key` in `upsert_views[]` and update that exact target
+- 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:
 
@@ -43,7 +52,13 @@ Apply a default table view:
         "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": []
@@ -52,6 +67,100 @@ Apply 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`.
 
+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
@@ -151,6 +260,25 @@ Treat this as:
 
 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`
@@ -158,5 +286,6 @@ Do not tell the user the filter is active until the readback verification matche
 - `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-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."