@qingflow-tech/qingflow-app-builder-mcp 1.0.5 → 1.0.7

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "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.5"
+version = "1.0.7"
 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
 
@@ -60,9 +60,23 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - `app_charts_apply` is the public write path
   - `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
+  - for add-data buttons, use `trigger_add_data_config.target_app_key + field_mappings/default_values`; do not handwrite raw `que_relation`
+  - bind buttons to views through `view_configs[].buttons[]`; default to `placement`: `header` or `detail`
+  - `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` is experimental because some backend deployments reject it with `LIST_BUTTON_BACKEND_UNSUPPORTED`
+  - 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
+  - `associated_item_id` must come from `app_get.associated_resources[].associated_item_id`; it is not `chart_id`, `chart_key`, or `view_key`
+  - 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"`
 - Views and flows:
   - stay on `app_views_apply` / `app_flow_apply`
   - 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,12 +88,12 @@ 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:
@@ -98,7 +112,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.
@@ -122,7 +137,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`
@@ -135,11 +150,58 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Merge or replace layout: `app_layout_apply`
 - Replace workflow: `app_flow_apply`
 - Upsert/remove views: `app_views_apply`
+- Upsert/remove custom buttons and bind them to header/detail view positions: `app_custom_buttons_apply`
+- Manage app associated reports/views and per-view display: `app_associated_resources_apply`
 - Upsert/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": "员工名称", "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`. Default placements are `header` and `detail`; `list` is experimental and should only be used when the user explicitly asks for row/list buttons.
+
 ## Resources
 
 - Shared public-surface baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.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,21 @@
 ## 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.
+- 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.
+- 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.
+- 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` is experimental for row/list buttons. Some backend deployments still reject it. If the tool returns `LIST_BUTTON_BACKEND_UNSUPPORTED`, treat `header/detail` as applied when verified and report list placement as unsupported by the current backend route.
+
 ## Readback scope
 
 - Prefer summary reads over large raw payloads

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

@@ -40,12 +40,14 @@ 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_custom_buttons_apply`: create, update, or remove custom buttons; configure add-data field mappings/default values; bind buttons to header/detail view positions; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings; `placement=list` is experimental
+- `app_associated_resources_apply`: manage app associated reports/views and per-view display config; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only for BI dataset reports
 - `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
 

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,10 @@ 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"`.
 - 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
 
 Apply a default table view:
 
@@ -52,6 +57,102 @@ 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`.
 
+Table view with fixed filter plus frontend query conditions:
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_123",
+    "publish": true,
+    "upsert_views": [
+      {
+        "name": "客户查询视图",
+        "type": "table",
+        "columns": ["客户名称", "负责人", "客户状态", "创建时间"],
+        "filters": [
+          {
+            "field_name": "客户状态",
+            "operator": "eq",
+            "value": "有效"
+          }
+        ],
+        "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.
+
+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`. 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`.
+
+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"
+      }
+    ],
+    "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