@josephyan/qingflow-app-builder-mcp 1.0.9 → 1.1.2

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

@@ -14,7 +14,7 @@ Assumes MCP is already connected, authenticated, and on the correct workspace.
 
 Before any write or verification flow, identify whether the task targets `test` or `prod` and read [references/environments.md](references/environments.md). If the user did not specify one, default to `prod`.
 
-Before choosing a route, skim the shared maintenance baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.md).
+Before choosing a route, skim the shared maintenance baseline: [public-surface-sync.md](references/public-surface-sync.md).
 
 ## Current Public Mental Model
 
@@ -35,10 +35,10 @@ Default modeling rules:
 ## Public Tools You Should Think In
 
 - Package: `package_get`, `package_apply`
-- App reads: `app_resolve`, `app_get`, `app_get_fields`, `app_get_layout`, `app_get_views`, `app_get_flow`, `app_get_charts`
+- App reads: `app_resolve`, `app_get`, `app_get_fields`, `app_get_layout`, `app_get_views`, `app_get_flow`, `app_get_charts`, `app_get_buttons`, `app_get_associated_resources`
 - 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
 
@@ -49,20 +49,61 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Package work:
   - use `package_get(package_id=...)` to read one known package
   - use `package_apply(...)` for package creation, rename, icon, visibility, grouping, ordering, and app/portal layout
+- Multi-app schema work:
+  - use one `app_schema_apply(apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
+  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`
 - 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
+  - portal sections use a 24-column PC grid; all components sharing the same `y` coordinate must have identical `rows` values and their `cols` must sum to exactly 24; mixing `rows` in the same row causes height misalignment, and a `cols` sum under 24 leaves blank space at the row end; the next row's `y` must equal the previous row's `y` + `rows`
 - Chart work:
-  - `app_charts_apply` is the public write path
+  - `app_charts_apply` is the public write path for app-source QingBI report bodies/configs; it creates/updates reports with `dataSourceType=qingflow`
+  - dataset BI reports are not created or edited by `app_charts_apply` yet; create them in QingBI first, then attach the existing report with `app_associated_resources_apply` and `report_source="dataset"`
+  - it does not attach the report to the Qingflow app associated-resource display; use `app_associated_resources_apply` for that
+  - supported `chart_type` values include legacy public aliases `target`, `table` and QingBI types such as `summary`, `columnar`, `area`, `stacked_area`, `funnel`, `waterfall`, `gauge`, `heatmap`, `histogram`, `treemap`, `radar`, `stacked_bar`, `stacked_column`, `scatter`, `ring`, `rose`, `dualaxes`, `map`, and `timeline`
+  - 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 Qingflow app-level associated report/view pool and per-view display config
+  - it attaches existing BI reports/views for in-app display; it does not create or edit QingBI report bodies/configs, including dataset reports
+  - use `patch_resources` for changing match rules or other existing associated-resource parameters; the tool preserves backend-required raw fields internally
+  - `associated_item_id` is the backend internal associated-resource id; for `view_configs`, `remove_associated_item_ids`, and `reorder_associated_item_ids`, you may pass `associated_item_id` or an existing resource's `chart_id`/`chart_key`/`view_key`, and the tool resolves it to the internal id
+  - 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 existing 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
+  - when creating any new table or card view, always include `query_conditions` with `enabled: true`; populate `rows` with the fields most useful for searching — 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 default the associated report/view display area to visible with `limit_type="all"`; existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched
+  - configure associated reports/views through `app_associated_resources_apply`, not through `app_views_apply`
 
 ## Standard Operating Order
 
@@ -74,20 +115,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 +141,9 @@ 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.
+- Always pass `publish: true` (or CLI `--publish`) explicitly on `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, and `portal_apply` — do not rely on the default. `app_custom_buttons_apply` and `app_associated_resources_apply` publish automatically after at least one write succeeds and do not accept a `publish` parameter. `app_charts_apply` is immediate-live without a publish step.
+- 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.
+- When any tool returns `error_code` or `VALIDATION_ERROR`, read the `message` field verbatim first before guessing at parameter or CLI parsing issues. A clear `message` like "relation field requires visible_fields" is the root cause — do not redirect to unrelated hypotheses such as `create_if_missing` parsing or flag conflicts.
 - 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.
@@ -107,11 +152,18 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 
 ## Response Interpretation
 
+- All builder apply/write tools return a standard UI envelope in addition to legacy fields:
+  `schema_version`, `operation`, `summary`, and `resources[]`.
+- For UI cards or quick narration, read `resources[]` first. Each resource has `resource_type`, `operation`, `status`, `id`, `key`, `name`, typed `ids`, and `parent`.
+- Use legacy fields such as `field_diff`, `views_diff`, `chart_results`, `created/updated/removed`, and `verification` only for compatibility and troubleshooting.
 - Treat post-write readback as the source of truth, not just write status codes.
 - `success` means write and verification completed; `partial_success` means the write landed but verification is incomplete.
 - 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 +174,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 +186,84 @@ 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.
+
+## Playbook Selection
+
+Before starting any build or create task, route to the right reference first:
+
+| User intent | Signal phrases | Playbook |
+|-------------|---------------|---------|
+| Multi-app business system with cross-app relations, shared workflow, and a portal dashboard | "建一套系统"、"包含 N 个模块"、"这几个表单之间建立关联"、"完整的业务系统" | [build-complete-system.md](references/build-complete-system.md) |
+| Single app end-to-end: rich schema, layout, flow, multiple view types, custom buttons, in-app charts, associated resources, and sample data | "建一个应用"、"帮我搭一个XX管理"、"从零开始建一个XX"、"我需要一个管理XX的应用" | [build-single-app.md](references/build-single-app.md) |
+| Add one new app inside an existing package | "在这个包里加一个表单"、"现有系统里新增一个模块" | [create-app.md](references/create-app.md) |
+| Update fields or schema only | "加一个字段"、"改字段名"、"删除字段" | [update-schema.md](references/update-schema.md) |
+| Update layout only | "调整分组"、"改排列顺序" | [update-layout.md](references/update-layout.md) |
+| Update workflow only | "修改审批流"、"加一个审批节点" | [update-flow.md](references/update-flow.md) |
+| Update views only | "加一个看板"、"改筛选条件"、"新增视图" | [update-views.md](references/update-views.md) |
+
+Decision rule: if the user mentions **multiple related apps or a portal**, use `build-complete-system.md`. If it is **one app** with a from-scratch setup request, use `build-single-app.md`. If the target app already exists and the user only wants to change one layer, use the matching single-layer playbook.
+
 ## Resources
 
-- Shared public-surface baseline: [public-surface-sync.md](../qingflow-app-user/references/public-surface-sync.md)
+- Shared public-surface baseline: [public-surface-sync.md](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)
@@ -153,3 +272,5 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 - Workflow assignees and node permissions: [references/flow-actors-and-permissions.md](references/flow-actors-and-permissions.md)
 - Update views only: [references/update-views.md](references/update-views.md)
 - Standard end-to-end builder sequences: [references/solution-playbooks.md](references/solution-playbooks.md)
+- Build a complete multi-app system from scratch: [references/build-complete-system.md](references/build-complete-system.md)
+- Build a single app end-to-end (schema + layout + flow + views + buttons + charts + associated resources + data): [references/build-single-app.md](references/build-single-app.md)