@qingflow-tech/qingflow-app-builder-mcp 1.0.6 → 1.0.8

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.6
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.8
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.6 qingflow-app-builder-mcp
+npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.8 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.0.6"
+version = "1.0.8"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -38,7 +38,7 @@ Default modeling rules:
 - App reads: `app_resolve`, `app_get`, `app_get_fields`, `app_get_layout`, `app_get_views`, `app_get_flow`, `app_get_charts`
 - Builder reads: `portal_list`, `portal_get`, `view_get`, `chart_get`, `builder_tool_contract`
 - Directory: `member_search`, `role_search`, `role_create`
-- Writes: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `app_charts_apply`, `portal_apply`, `app_release_edit_lock_if_mine`
+- 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_release_edit_lock_if_mine`
 - Verification: `app_publish_verify`
 - Cross-cutting escalation: `feedback_submit` after explicit user confirmation when the public builder surface still cannot satisfy the user's need
 
@@ -52,17 +52,48 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - App base permissions:
   - trust `app_get.editability.can_edit_app_base` for app base-info writes like app name, icon, and visibility
   - `can_edit_form` only means schema/form-route capability; it no longer implies app base-info write capability
+- Partial update rule:
+  - for existing views, custom buttons, associated resources, and charts, prefer `patch_views` / `patch_buttons` / `patch_resources` / `patch_charts`
+  - each patch item uses the object's real selector field (`view_key` / `button_id` / `associated_item_id` / `chart_id`, or unique name where supported) plus `set` and optional `unset`; do not send a literal `selector` key for these tools
+  - use `upsert_*` for creation or full target configuration; do not send a partial `upsert_*` and expect the backend to merge missing required fields
 - Portal work:
   - `portal_apply` is the public write path
   - in edit mode, omitting `sections` means “preserve existing layout and update base info only”
   - supplying `sections` means full replace semantics for sections
 - Chart work:
   - `app_charts_apply` is the public write path
+  - use `patch_charts` for changing a chart name, visibility, filters, or one config fragment on an existing chart
   - `visibility` is a public capability and should be treated as a base-only permission update
   - do not model chart visibility changes as raw config rewrites
+- Button work:
+  - `app_custom_buttons_apply` is the public write path for custom button bodies and view placement
+  - use `patch_buttons` for changing a single existing button parameter such as URL, text, icon, style, or add-data mapping
+  - for add-data buttons, use `trigger_add_data_config.target_app_key + field_mappings/default_values`; do not handwrite raw `que_relation`
+  - use `field_mappings` for dynamic current-record values, including system fields such as `数据ID` (`field_id=-17`) and `编号` (`field_id=0`)
+  - to prefill a target relation field with the current source record, map `{"source_field": "数据ID", "target_field": "目标引用字段"}`; use `default_values` only for static constants
+  - if field type compatibility is unclear, read [references/match-rules.md](references/match-rules.md)
+  - bind buttons to views through `view_configs[].buttons[]`; default to `placement`: `header` or `detail`
+  - builder `view_configs[].view_key` uses the raw key from `app_get.views[].view_key`, without a `custom:` prefix
+  - `buttons` is required in merge mode; do not send a view config with only `view_key`
+  - `view_configs[].mode` defaults to `merge`; use `mode: "replace"` or an explicit empty `buttons: []` to clear a view's custom button bindings
+  - `placement=list` configures row/list buttons and maps to the backend `INSIDE` button position
+  - advanced bindings may use `button_limit`, `button_formula`, `button_formula_type`, and `print_tpls` only when visibility or print-template behavior is required
+- Associated resources:
+  - `app_associated_resources_apply` is the public write path for the app-level associated report/view pool and per-view display config
+  - use `patch_resources` for changing match rules or other existing associated-resource parameters; the tool preserves backend-required raw fields internally
+  - `associated_item_id` must come from `app_get.associated_resources[].associated_item_id`; it is not `chart_id`, `chart_key`, or `view_key`
+  - before creating a resource, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`; if it already exists, use `patch_resources` with that `associated_item_id`
+  - `client_key` is only a same-call reference for `view_configs[].associated_item_refs`; it is not saved and cannot deduplicate later calls
+  - do not pass backend raw `sourceType`; view resources infer the internal Qingflow view source, report/chart resources default to BI app reports, and dataset reports use `report_source="dataset"`
+  - use `match_mappings` for associated view/report filters; dynamic conditions use `source_field`, static conditions use `value`
+  - if field type compatibility is unclear, read [references/match-rules.md](references/match-rules.md)
 - Views and flows:
   - stay on `app_views_apply` / `app_flow_apply`
+  - use `patch_views` for existing-view parameter changes such as `query_conditions`, `filters`, `columns`, or visibility
+  - builder view writes use raw `view_key` values from `app_get.views`; `custom:<viewKey>` is a record-data `view_id` form, not a builder `view_key`
   - use `builder_tool_contract` whenever the minimal legal shape is unclear
+  - keep view `filters` and `query_conditions` separate: `filters` are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
+  - configure associated reports/views through `app_associated_resources_apply`, not through `app_views_apply`
 
 ## Standard Operating Order
 
@@ -74,20 +105,22 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - package-scoped work with known id -> `package_get`
    - portal inventory -> `portal_list`
 5. Read only the smallest config slice needed:
-   - app summary -> `app_get`
+   - app map -> `app_get` (default entry; includes compact views, charts, custom buttons, and associated resource pool)
    - fields -> `app_get_fields`
    - layout -> `app_get_layout`
-   - views -> `app_get_views`
+   - views -> `app_get_views` only when the app_get compact list is not enough
    - flow -> `app_get_flow`
-   - charts -> `app_get_charts`
+   - charts -> `app_get_charts` only when the app_get compact list is not enough
    - portal -> `portal_get`
 6. If the public shape is unclear, call `builder_tool_contract`
 7. Apply the smallest patch tool that fits:
    - fields -> `app_schema_apply`
    - layout -> `app_layout_apply`
    - flow -> `app_flow_apply`
-   - views -> `app_views_apply`
-   - charts -> `app_charts_apply`
+   - existing views -> `app_views_apply.patch_views`; new/full views -> `app_views_apply.upsert_views`
+   - existing buttons -> `app_custom_buttons_apply.patch_buttons`; new/full buttons -> `app_custom_buttons_apply.upsert_buttons`
+   - existing associated resources -> `app_associated_resources_apply.patch_resources`; new/full resources -> `app_associated_resources_apply.upsert_resources`
+   - existing charts -> `app_charts_apply.patch_charts`; new/full charts -> `app_charts_apply.upsert_charts`
    - portal -> `portal_apply`
    - package metadata/layout -> `package_apply`
 8. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
@@ -98,7 +131,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - If `package_id` is unknown, derive it from related app/portal readback when possible; otherwise ask the user instead of falling back to hidden package lookup tools.
 - Do not use `package_create` or `package_attach_app` as a public default path. If they still appear in low-level code, treat them as internal/legacy implementation details.
 - Do not use raw `portal_*` writes or raw `qingbi_report_*` writes as the default builder strategy.
-- `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default; `app_charts_apply` is immediate-live without publish.
+- `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default; `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept a draft-only `publish` parameter; `app_charts_apply` is immediate-live without publish.
+- When creating or updating fields, configure the app data title/cover directly in field JSON: `as_data_title: true` is required on exactly one readable top-level title field; `as_data_cover: true` is optional and only valid on one top-level `attachment` field.
 - If the same validation error repeats twice, stop guessing and re-read `builder_tool_contract`.
 - For workflow assignees, prefer `role_search` over explicit members unless the user explicitly wants named members.
 - Public flow building is still intentionally limited to stable linear workflows. If a requirement sounds like branches/conditions, explain the limitation instead of freehanding unsupported graph shapes.
@@ -112,6 +146,9 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - For portals, distinguish clearly between:
   - base-info-only update with layout preserved
   - full sections replace
+- For object apply tools, distinguish clearly between:
+  - `patch_*`: public partial parameter replacement; the tool hydrates current config and full-saves internally
+  - `upsert_*`: create or full target configuration; omitted fields may mean default/clear depending on that object
 - For charts, distinguish clearly between:
   - base / visibility change
   - real chart-config change
@@ -122,7 +159,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Read one package: `package_get`
 - Create or update one package: `package_apply`
 - Resolve one app: `app_resolve`
-- Read one app summary: `app_get`
+- Read one app map: `app_get`
 - Read fields only: `app_get_fields`
 - Read layout summary: `app_get_layout`
 - Read views summary: `app_get_views`
@@ -134,17 +171,68 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Add/update/remove fields: `app_schema_apply`
 - Merge or replace layout: `app_layout_apply`
 - Replace workflow: `app_flow_apply`
-- Upsert/remove views: `app_views_apply`
-- Upsert/remove/reorder charts: `app_charts_apply`
+- Upsert/patch/remove views: `app_views_apply`
+- Upsert/patch/remove custom buttons and bind them to header/detail view positions: `app_custom_buttons_apply`
+- Upsert/patch/remove app associated reports/views and per-view display: `app_associated_resources_apply`
+- Upsert/patch/remove/reorder charts: `app_charts_apply`
 - Create or update portal pages: `portal_apply`
 - Release your own stale edit lock: `app_release_edit_lock_if_mine`
 - Final publish verification: `app_publish_verify`
 
+## Button Pattern
+
+Use `app_custom_buttons_apply` for the whole custom-button path: button body, add-data mapping, default values, and placement.
+
+```json
+{
+  "tool_name": "app_custom_buttons_apply",
+  "arguments": {
+    "app_key": "EMPLOYEE_APP",
+    "upsert_buttons": [
+      {
+        "client_key": "add_worklog",
+        "button_text": "快捷添加工时",
+        "style_preset": "primary_blue",
+        "button_icon": "ex-plus-circle",
+        "trigger_action": "addData",
+        "trigger_add_data_config": {
+          "target_app_key": "WORKLOG_APP",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联员工"},
+            {"source_field": "员工名称", "target_field": "员工姓名"},
+            {"source_field": "所属部门", "target_field": "部门名称"}
+          ],
+          "default_values": {
+            "工时类型": "日常工作",
+            "状态": "待提交"
+          }
+        }
+      }
+    ],
+    "remove_buttons": [],
+    "view_configs": [
+      {
+        "view_key": "EMPLOYEE_VIEW",
+        "mode": "merge",
+        "buttons": [
+          {"button_ref": "add_worklog", "placement": "detail", "primary": true}
+        ]
+      }
+    ]
+  }
+}
+```
+
+`button_ref` may be a same-call `client_key` or an existing `button_id`. Supported placements are `header`, `detail`, and `list`; `list` maps to the backend `INSIDE` row/list button position.
+
+For add-data buttons that create a child record linked back to the current record, map `source_field: "数据ID"` to the target relation field. Do not use raw `que_relation` unless maintaining an existing backend config.
+
 ## Resources
 
 - Shared public-surface baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.md)
 - Environment switching: [references/environments.md](references/environments.md)
 - Tool choice and sequencing: [references/tool-selection.md](references/tool-selection.md)
+- Field matching rules: [references/match-rules.md](references/match-rules.md)
 - Result semantics and gotchas: [references/gotchas.md](references/gotchas.md)
 - Create one app in an existing package: [references/create-app.md](references/create-app.md)
 - Update fields only: [references/update-schema.md](references/update-schema.md)

package/skills/qingflow-app-builder/references/create-app.md

@@ -79,8 +79,9 @@ Apply schema for a new app:
     "create_if_missing": true,
     "publish": true,
     "add_fields": [
-      {"name": "订单编号", "type": "text", "required": true},
+      {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
       {"name": "客户名称", "type": "text", "required": true},
+      {"name": "订单封面", "type": "attachment", "as_data_cover": true},
       {"name": "订单金额", "type": "amount"},
       {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
     ],
@@ -90,6 +91,8 @@ Apply schema for a new app:
 }
 ```
 
+Data title is required: mark exactly one top-level field with `as_data_title: true`. Data cover is optional and only valid on a top-level `attachment` field.
+
 ## Common failures
 
 ### `APP_NOT_FOUND`

package/skills/qingflow-app-builder/references/gotchas.md

@@ -21,9 +21,33 @@
 ## Auto publish
 
 - `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default
-- Pass `publish=false` only when the user explicitly wants to leave changes in draft
+- For those four tools, pass `publish=false` only when the user explicitly wants to leave changes in draft
+- `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept `publish=false`
 - `app_publish_verify` is for explicit final verification, not the default next step after every write
 
+## Custom buttons
+
+- Use `app_custom_buttons_apply` for button creation/update/removal and view placement; do not split placement into `app_views_apply.buttons` unless you are maintaining a legacy patch.
+- When changing one existing button parameter, use `patch_buttons` with `set/unset`. Do not send a partial `upsert_buttons` object and expect the backend to preserve hidden required fields.
+- For add-data buttons, prefer semantic `trigger_add_data_config.target_app_key`, `field_mappings`, and `default_values`.
+- Do not handwrite raw `que_relation` unless you are preserving an existing backend config. If `field_mappings` and `que_relation` are mixed, the tool blocks the write.
+- `field_mappings.source_field` can use source app fields and supported system fields such as `数据ID` (`field_id=-17`) and `编号` (`field_id=0`).
+- To fill a target relation field with the current source record, map `{"source_field": "数据ID", "target_field": "目标引用字段"}`. Use `default_values` only for static constants.
+- For field type compatibility, read `references/match-rules.md`.
+- Default button placements are `header` and `detail`; these map to the frontend's header and detail button areas.
+- `view_configs[].buttons` is required in merge mode. Do not send a view config with only `view_key`; it is blocked to avoid no-op writes and accidental publish.
+- Builder view configs use raw `view_key` from `app_get.views[].view_key`; do not prefix it with `custom:`. The `custom:<viewKey>` form is for record-data `view_id`.
+- View button bindings merge by default. Use `view_configs[].mode="replace"` to replace the full set, or pass an explicit empty `buttons: []` when you intend to clear all custom button bindings for that view.
+- Advanced view button bindings can include `button_limit`, `button_formula`, `button_formula_type`, and `print_tpls`, but keep ordinary buttons simple unless the user asks for conditional visibility or print templates.
+- `placement=list` configures row/list buttons. The tool maps it to the backend `INSIDE` button position, not a raw `LIST` config type.
+
+## Associated resources
+
+- Before creating an associated view/report, check `app_get.associated_resources` for the same `target_app_key + view_key/chart_key`.
+- If the resource already exists, use `patch_resources` with its `associated_item_id`; do not call `upsert_resources` again.
+- `client_key` is only a same-call alias for `view_configs[].associated_item_refs`. It is not stored by Qingflow and cannot prevent duplicates in later calls.
+- Repeated `upsert_resources` without `associated_item_id` can create multiple app-level associated items pointing to the same view/report.
+
 ## Readback scope
 
 - Prefer summary reads over large raw payloads
@@ -32,6 +56,15 @@
 - Use `app_get_flow` before workflow work
 - Use `app_get_views` before view work
 
+## Partial update discipline
+
+- Existing views, custom buttons, associated resources, and charts support the same public partial pattern: `patch_*[].set` plus optional `patch_*[].unset`.
+- The backend may still save a full payload. The MCP/CLI patch path is responsible for reading current config and preserving fields the user did not mention.
+- Do not use `upsert_views`, `upsert_buttons`, `upsert_resources`, or `upsert_charts` for a tiny parameter replacement unless you are deliberately providing the full desired target config.
+- `app_layout_apply(mode=merge)` is already a safe layout merge path; `mode=replace` is full layout replacement.
+- `portal_apply` without `sections` is base-info-only. Supplying `sections` replaces the portal sections list.
+- `app_flow_apply` is intentionally replace-only for the public linear workflow graph.
+
 ## Workflow dependencies
 
 - Approval-style flows usually require an explicit status field
@@ -54,6 +87,7 @@
   - `assignees.role_ids` / `assignees.member_uids` / `assignees.member_emails`
   - `permissions.editable_fields`
 - For view work, treat `columns` as the only canonical public key. `app_get_views` and `app_views_apply` should all be read and written in that shape.
+- For existing view parameter changes, prefer `patch_views`. Example: to change only query-panel fields, set only `query_conditions`; the tool will preserve columns, filters, date config, card fields, buttons, and other backend-required fields.
 - For layout work, treat `title + rows` as the only canonical public section shape. `fields`, `field_ids`, and `columns` may appear in legacy/internal shapes, but they are not the preferred public write shape.
 - A created view is not enough to claim a filter succeeded. When `app_views_apply` returns `partial_success`, `views_verified=false`, or `details.filter_mismatches`, treat the view as present but the filter as unverified.
 - If duplicate view names exist, do not retry by name. Read the exact `view_key` and target that one.

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/tool-selection.md

@@ -40,15 +40,19 @@ If the user asks for multiple forms/modules that relate to each other, this is a
 
 ## 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
+- `app_views_apply`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key
+- `app_custom_buttons_apply`: use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; configure add-data field mappings/default values; bind buttons to header/detail/list view positions; `placement=list` maps to the backend `INSIDE` row/list button position; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings. For child-record creation linked to the current source record, map `source_field: "数据ID"` to the target relation field.
+- `app_associated_resources_apply`: use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; use `match_mappings` for associated view/report filters; manage per-view display config; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only for BI dataset reports. 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`: use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; 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
 
+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.
+
 ## Explicit post-apply tools
 
 - `app_publish_verify`: explicit final publish verification when the user asks for live confirmation
@@ -68,9 +72,9 @@ These execute normalized patches and publish by default unless `publish=false`.
 - Add workflow:
   `builder_tool_contract -> app_get_fields -> app_get_flow -> role_search/member_search -> app_flow_apply -> app_get_flow`
 - 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`
 - Create or update a portal:
   `builder_tool_contract -> portal_get -> portal_apply -> portal_get`
 

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,12 @@ 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`.
+- Use `app_associated_resources_apply` for the frontend associated report/view area. `associated_item_id` must be copied from `app_get.associated_resources[].associated_item_id`; it is not `chart_id` or `chart_key`. 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:
 
@@ -52,6 +59,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 must come 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`. 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 +252,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 +278,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