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

package/skills/qingflow-app-builder/references/build-single-app.md

@@ -0,0 +1,530 @@
+# Build Single App（单应用完整搭建）
+
+Use this when the user wants to set up one Qingflow app end-to-end: a rich field schema, grouped layout, approval flow, multiple view types, custom action buttons, in-app charts, associated reports on views, and sample data.
+
+**Signal phrases**: "创建一个应用"、"帮我搭一个XX管理"、"从零开始建一个XX表单"、"我需要一个管理XX的应用"
+
+For a multi-app system with cross-app relations and a portal dashboard, use [build-complete-system.md](./build-complete-system.md) instead.
+
+---
+
+## Execution order (never reorder)
+
+```
+Phase 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6 → Phase 7 → Phase 8 → Phase 9
+ Package   Schema   Layout    Flow      Views    Buttons   Charts  Assoc.   Data    Verify
+                                                                   Res.
+```
+
+- Phase 4 (views) must complete before Phase 7 (associated resources) — `view_key` values must be known first
+- Phase 6 (charts) must complete before Phase 7 (associated resources) — `chart_id`/`chart_key` values must be known first
+- Phase 8 (data) runs after all config phases — fields, flow, and views must be live
+
+---
+
+## Phase 0 — Scan workspace packages
+
+```json
+{"tool_name": "package_list", "arguments": {"profile": "default"}}
+```
+
+- **Package name exists in workspace** → tell the user, wait for explicit confirmation before adding the app into it
+- **Package name not in workspace** → create immediately, no confirmation needed:
+
+```json
+{
+  "tool_name": "package_apply",
+  "arguments": {
+    "profile": "default",
+    "package_name": "合同管理",
+    "create_if_missing": true
+  }
+}
+```
+
+Record the returned `package_id`. All subsequent phases use it.
+
+---
+
+## Phase 1 — Schema (15–20 fields)
+
+> **Read first**: [update-schema.md](./update-schema.md)
+
+### Field type distribution
+
+| Type | Count | Examples |
+|------|-------|---------|
+| `text` | 2–3 | 名称、编号、联系人 |
+| `long_text` | 1–2 | 描述、摘要、备注 |
+| `single_select` | 2–3 | 状态、类型、优先级 |
+| `multi_select` | 1–2 | 标签、关联业务线 |
+| `date` / `datetime` | 2–3 | 签署日期、生效日期、到期日期 |
+| `amount` | 1–2 | 合同金额、已付金额 |
+| `number` | 1–2 | 期限（月）、完成率（%） |
+| `member` | 2 | 负责人、审核人 |
+| `department` | 0–1 | 所属部门 |
+| `phone` | 0–1 | 联系电话 |
+| `attachment` | 1 | 附件（`as_data_cover: true` for cover display） |
+
+### Hard rules
+
+- Exactly one field must have `as_data_title: true`
+- `as_data_cover: true` requires `type: attachment`
+- No `relation` fields in a single-app build — use [build-complete-system.md](./build-complete-system.md) if cross-app links are needed
+- `single_select`/`multi_select` fields must include an `options` array
+
+### Example — 合同管理
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "package_id": 1218950,
+    "create_if_missing": true,
+    "publish": true,
+    "apps": [
+      {
+        "client_key": "contract",
+        "app_name": "合同",
+        "add_fields": [
+          {"name": "合同名称", "type": "text", "required": true, "as_data_title": true},
+          {"name": "合同编号", "type": "text"},
+          {"name": "合同类型", "type": "single_select", "options": ["服务合同", "采购合同", "劳务合同", "保密协议", "其他"]},
+          {"name": "合同状态", "type": "single_select", "options": ["草稿", "审批中", "已生效", "已到期", "已终止"]},
+          {"name": "优先级", "type": "single_select", "options": ["高", "中", "低"]},
+          {"name": "合同标签", "type": "multi_select", "options": ["重点客户", "续签", "新签", "框架协议"]},
+          {"name": "签署日期", "type": "date"},
+          {"name": "生效日期", "type": "date"},
+          {"name": "到期日期", "type": "date"},
+          {"name": "合同金额", "type": "amount"},
+          {"name": "已付金额", "type": "amount"},
+          {"name": "付款比例", "type": "number"},
+          {"name": "合同期限（月）", "type": "number"},
+          {"name": "负责人", "type": "member"},
+          {"name": "法务审核人", "type": "member"},
+          {"name": "所属部门", "type": "department"},
+          {"name": "甲方联系人", "type": "text"},
+          {"name": "甲方联系电话", "type": "phone"},
+          {"name": "合同内容摘要", "type": "long_text"},
+          {"name": "合同附件", "type": "attachment", "as_data_cover": true}
+        ]
+      }
+    ]
+  }
+}
+```
+
+Record the returned `app_key`. All subsequent phases use it.
+
+---
+
+## Phase 2 — Layout
+
+> **Read first**: [update-layout.md](./update-layout.md)
+
+Group fields into 3–4 logical sections with 2–3 fields per row.
+
+```json
+{
+  "tool_name": "app_layout_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "mode": "merge",
+    "publish": true,
+    "sections": [
+      {
+        "title": "基础信息",
+        "rows": [
+          ["合同名称", "合同编号"],
+          ["合同类型", "合同状态"],
+          ["优先级", "合同标签"]
+        ]
+      },
+      {
+        "title": "时间与金额",
+        "rows": [
+          ["签署日期", "生效日期", "到期日期"],
+          ["合同金额", "已付金额"],
+          ["付款比例", "合同期限（月）"]
+        ]
+      },
+      {
+        "title": "责任人",
+        "rows": [
+          ["负责人", "法务审核人"],
+          ["所属部门"]
+        ]
+      },
+      {
+        "title": "对方信息与附件",
+        "rows": [
+          ["甲方联系人", "甲方联系电话"],
+          ["合同内容摘要"],
+          ["合同附件"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Phase 3 — Flow
+
+> **Read first**: [update-flow.md](./update-flow.md) and [flow-actors-and-permissions.md](./flow-actors-and-permissions.md)
+
+Search for roles first; create only if none fits:
+
+```json
+{"tool_name": "role_search", "arguments": {"profile": "default", "query": "法务"}}
+```
+
+```json
+{
+  "tool_name": "app_flow_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "preset": "basic_approval",
+    "publish": true,
+    "nodes": [
+      {
+        "id": "approve_1",
+        "type": "approve",
+        "name": "法务审核",
+        "assignees": {"role_names": ["法务"]},
+        "permissions": {"editable_fields": ["合同状态", "合同内容摘要"]}
+      },
+      {
+        "id": "approve_2",
+        "type": "approve",
+        "name": "负责人确认",
+        "assignees": {"role_names": ["部门主管"]},
+        "permissions": {"editable_fields": ["合同状态"]}
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Phase 4 — Views (multiple types)
+
+> **Read first**: [update-views.md](./update-views.md)
+
+Build all applicable view types in one call. All views require `query_conditions` with `enabled: true`.
+
+| Type | Build condition | Key config |
+|------|----------------|------------|
+| **table** | Always — build first | `columns` covering title/status/date/amount/member |
+| **board** | App has a `single_select` status or stage field | `group_by` = that field name |
+| **gantt** | App has 2+ date fields | `start_field` + `end_field` |
+| **card** | App has `attachment` with `as_data_cover: true` | Visual browsing |
+| **calendar** | App has a key due/expiry date field | `date_field` = that field name |
+
+```json
+{
+  "tool_name": "app_views_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "publish": true,
+    "upsert_views": [
+      {
+        "name": "全部合同",
+        "type": "table",
+        "columns": ["合同名称", "合同编号", "合同类型", "合同状态", "合同金额", "负责人", "签署日期", "到期日期"],
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["合同名称", "合同类型"], ["合同状态", "负责人"], ["签署日期", "到期日期"]]
+        }
+      },
+      {
+        "name": "合同看板",
+        "type": "board",
+        "columns": ["合同名称", "合同类型", "合同金额", "负责人", "到期日期"],
+        "group_by": "合同状态",
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["合同名称", "负责人"]]
+        }
+      },
+      {
+        "name": "合同甘特图",
+        "type": "gantt",
+        "columns": ["合同名称", "合同状态", "负责人", "合同金额"],
+        "start_field": "生效日期",
+        "end_field": "到期日期",
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["合同名称", "合同状态"]]
+        }
+      },
+      {
+        "name": "合同卡片",
+        "type": "card",
+        "columns": ["合同名称", "合同类型", "合同状态", "合同金额", "到期日期"],
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["合同名称", "合同状态"]]
+        }
+      },
+      {
+        "name": "到期日历",
+        "type": "calendar",
+        "columns": ["合同名称", "合同类型", "合同金额", "负责人"],
+        "date_field": "到期日期",
+        "query_conditions": {
+          "enabled": true,
+          "exact": false,
+          "hide_before_query": false,
+          "rows": [["合同名称", "合同状态"]]
+        }
+      }
+    ]
+  }
+}
+```
+
+Record all `view_key` values before Phase 7.
+
+---
+
+## Phase 5 — Custom Buttons
+
+> Call `builder_tool_contract(tool="app_custom_buttons_apply")` if the exact button schema is unclear.
+> `app_custom_buttons_apply` publishes automatically — do **not** pass `publish`.
+
+Build 2–3 buttons. Common patterns for a single app:
+
+| Button | Trigger type | Placement | When to use |
+|--------|-------------|-----------|-------------|
+| 快捷创建子记录 | `add_data` | header, detail | When a related app exists in the same package |
+| 外部跳转 | `link` | header, list | Always applicable — jump to external URL or doc |
+| 列表行操作 | `add_data` / `link` | list | Row-level quick action in table view |
+
+**Example — link button (always applicable) + add-data button (requires a related app):**
+
+```json
+{
+  "tool_name": "app_custom_buttons_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "upsert_buttons": [
+      {
+        "name": "查看合同模板",
+        "trigger_type": "link",
+        "style": "default",
+        "placements": ["header", "detail"],
+        "trigger_link_config": {
+          "url": "https://your-template-url"
+        }
+      },
+      {
+        "name": "发起变更申请",
+        "trigger_type": "add_data",
+        "style": "primary",
+        "placements": ["header", "detail", "list"],
+        "trigger_add_data_config": {
+          "target_app_key": "CHANGE_REQUEST_APP_KEY",
+          "field_mappings": [
+            {"source_field": "数据ID", "target_field": "关联合同"},
+            {"source_field": "合同名称", "target_field": "合同标题"},
+            {"source_field": "负责人", "target_field": "申请人"}
+          ]
+        }
+      }
+    ],
+    "view_configs": [
+      {
+        "view_key": "TABLE_VIEW_KEY",
+        "mode": "merge",
+        "buttons": ["发起变更申请", "查看合同模板"]
+      }
+    ]
+  }
+}
+```
+
+**Notes:**
+- `placements: ["list"]` maps to the backend row-level `INSIDE` position
+- `view_configs[].buttons` is required in merge mode — do not send a view config with only `view_key`
+- `source_field: "数据ID"` passes the current record's ID to the target relation field
+- If this app has no related app, skip the add-data button and use the link button only
+- Use raw `view_key` from `app_get.views[].view_key`; do not prefix with `custom:`
+
+---
+
+## Phase 6 — Charts
+
+> `app_charts_apply` is immediate-live — no publish step. Record all returned `chart_id`/`chart_key` values before Phase 7.
+
+Build 2–4 charts: 2 indicator cards + 1 distribution chart + 1 trend chart.
+
+```json
+{
+  "tool_name": "app_charts_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "upsert_charts": [
+      {
+        "name": "合同总金额",
+        "chart_type": "target",
+        "config": {
+          "measure_field": "合同金额",
+          "aggregate": "SUM"
+        }
+      },
+      {
+        "name": "有效合同数",
+        "chart_type": "target",
+        "config": {
+          "filter": {"合同状态": ["已生效"]},
+          "aggregate": "COUNT"
+        }
+      },
+      {
+        "name": "合同状态分布",
+        "chart_type": "columnar",
+        "config": {
+          "dimension_field": "合同状态",
+          "measure_field": "合同金额",
+          "aggregate": "SUM"
+        }
+      },
+      {
+        "name": "月度签约趋势",
+        "chart_type": "area",
+        "config": {
+          "dimension_field": "签署日期",
+          "time_granularity": "month",
+          "measure_field": "合同金额",
+          "aggregate": "SUM"
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Phase 7 — Associated Resources
+
+Attach charts to the app's view area so users can see them inline without leaving the app.
+
+Before running `upsert_resources`, check existing resources with the dedicated read tool:
+
+```json
+{"tool_name": "app_get_associated_resources", "arguments": {"profile": "default", "app_key": "APP_KEY"}}
+```
+
+If the result already contains the target chart, use `patch_resources` with its `associated_item_id` instead of re-upserting.
+
+```json
+{
+  "tool_name": "app_associated_resources_apply",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "upsert_resources": [
+      {
+        "client_key": "res_status_chart",
+        "resource_type": "chart",
+        "chart_key": "CHART_KEY_FOR_STATUS_DISTRIBUTION",
+        "display_name": "合同状态分布"
+      },
+      {
+        "client_key": "res_trend_chart",
+        "resource_type": "chart",
+        "chart_key": "CHART_KEY_FOR_TREND",
+        "display_name": "月度签约趋势"
+      }
+    ],
+    "view_configs": [
+      {
+        "view_key": "TABLE_VIEW_KEY",
+        "associated_item_refs": ["res_status_chart", "res_trend_chart"]
+      }
+    ]
+  }
+}
+```
+
+**Notes:**
+- `app_associated_resources_apply` publishes automatically — do **not** pass `publish`
+- `client_key` is a same-call alias only; repeated `upsert_resources` without `associated_item_id` creates duplicates
+- On subsequent edits, use `patch_resources` with `associated_item_id` instead
+
+---
+
+## Phase 8 — Sample Data
+
+> **Hand off to `qingflow-record-insert` skill**. Read the record-insert skill docs before inserting.
+
+Insert **5–8 records** covering all status values and realistic amounts. Call `record_insert_schema_get` first.
+
+```json
+{"tool_name": "record_insert_schema_get", "arguments": {"profile": "default", "app_key": "APP_KEY"}}
+```
+
+```json
+{
+  "tool_name": "record_insert",
+  "arguments": {
+    "profile": "default",
+    "app_key": "APP_KEY",
+    "items": [
+      {"合同名称": "上海科技服务协议", "合同编号": "HT-2024-001", "合同类型": "服务合同", "合同状态": "已生效", "合同金额": 580000, "已付金额": 290000, "负责人": "张三", "签署日期": "2024-01-15", "生效日期": "2024-02-01", "到期日期": "2025-01-31", "优先级": "高", "合同期限（月）": 12},
+      {"合同名称": "北京采购框架合同", "合同编号": "HT-2024-002", "合同类型": "采购合同", "合同状态": "审批中", "合同金额": 1200000, "已付金额": 0, "负责人": "李四", "签署日期": "2024-03-10", "生效日期": "2024-04-01", "到期日期": "2025-03-31", "优先级": "高", "合同期限（月）": 12},
+      {"合同名称": "广州运维服务合同", "合同编号": "HT-2024-003", "合同类型": "服务合同", "合同状态": "已生效", "合同金额": 240000, "已付金额": 120000, "负责人": "王五", "签署日期": "2024-02-20", "生效日期": "2024-03-01", "到期日期": "2024-12-31", "优先级": "中", "合同期限（月）": 10},
+      {"合同名称": "深圳保密协议", "合同编号": "HT-2024-004", "合同类型": "保密协议", "合同状态": "已生效", "合同金额": 0, "已付金额": 0, "负责人": "张三", "签署日期": "2024-04-05", "生效日期": "2024-04-05", "到期日期": "2027-04-04", "优先级": "中", "合同期限（月）": 36},
+      {"合同名称": "杭州合作开发合同", "合同编号": "HT-2024-005", "合同类型": "服务合同", "合同状态": "草稿", "合同金额": 850000, "已付金额": 0, "负责人": "李四", "签署日期": "2024-05-01", "生效日期": "2024-06-01", "到期日期": "2025-05-31", "优先级": "高", "合同期限（月）": 12},
+      {"合同名称": "成都劳务外包合同", "合同编号": "HT-2023-006", "合同类型": "劳务合同", "合同状态": "已到期", "合同金额": 360000, "已付金额": 360000, "负责人": "王五", "签署日期": "2023-01-01", "生效日期": "2023-01-01", "到期日期": "2023-12-31", "优先级": "低", "合同期限（月）": 12}
+    ]
+  }
+}
+```
+
+Member and department fields accept natural language values — do not look up IDs manually.
+
+---
+
+## Phase 9 — Publish Verify
+
+```json
+{"tool_name": "app_publish_verify", "arguments": {"profile": "default", "app_key": "APP_KEY"}}
+```
+
+Confirm `publish_status` is live and `unplaced_fields` is empty. If `unplaced_fields` is non-empty, run `app_layout_apply` to place them before reporting completion.
+
+---
+
+## Common failures
+
+| Error | Phase | Fix |
+|-------|-------|-----|
+| `VALIDATION_ERROR` on select field | 1 | `single_select`/`multi_select` must include `options` array |
+| `UNKNOWN_LAYOUT_FIELD` | 2 | Re-read with `app_get_fields`; field name in `rows` must match exactly |
+| `FLOW_ASSIGNEE_REQUIRED` | 3 | Run `role_search` first; every approve/fill node must have at least one assignee |
+| View `partial_success` | 4 | Check `verification.view_query_conditions_verified`; read `views_diff.failed` |
+| `calendar` view rejected | 4 | Build calendar only when a date field exists; verify field type |
+| Button `view_configs` blocked | 5 | `buttons` array is required in merge mode; do not send a view config with only `view_key` |
+| Button add-data fails — no related app | 5 | Skip add-data button; use link button only |
+| Chart config rejected | 6 | Call `builder_tool_contract(tool="app_charts_apply")` for exact field/aggregate schema |
+| Associated resource duplicate | 7 | Check `app_get.associated_resources` first; use `patch_resources` with `associated_item_id` if already exists |
+| `unplaced_fields` non-empty on verify | 9 | Run `app_layout_apply` to place the missing fields, then re-verify |

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

@@ -37,8 +37,8 @@ then do not treat that as one app.
 Use this pattern instead:
 
 1. `package_get` or `package_apply(create_if_missing=true, package_name=...)`
-2. for each app name, run `app_schema_apply`
-3. once the apps exist, add `relation` fields between them
+2. for a multi-app system, run one `app_schema_apply` with `apps[]`
+3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
 
 ## Example
 
@@ -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,45 @@ Apply schema for a new app:
 }
 ```
 
+Apply schema for multiple apps in one call:
+
+```json
+{
+  "tool_name": "app_schema_apply",
+  "arguments": {
+    "profile": "default",
+    "package_id": 1218950,
+    "create_if_missing": true,
+    "publish": true,
+    "apps": [
+      {
+        "client_key": "customer",
+        "app_name": "客户",
+        "add_fields": [
+          {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
+        ]
+      },
+      {
+        "client_key": "order",
+        "app_name": "订单",
+        "add_fields": [
+          {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
+          {
+            "name": "关联客户",
+            "type": "relation",
+            "target_app_ref": "customer",
+            "display_field": {"name": "客户名称"},
+            "visible_fields": [{"name": "客户名称"}]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+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

@@ -18,12 +18,46 @@
 - If the user names multiple forms/modules that relate to each other, create multiple apps and connect them with relation fields
 - Do not use child app names like “项目/需求/任务/缺陷/团队” as plain text fields inside one app
 
-## Auto publish
+## 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
+- Always pass `publish: true` explicitly on `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, and `portal_apply` — do not rely on the default
+- Pass `publish: false` on those five tools 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 a `publish` parameter
+- `app_charts_apply` is immediate-live and has no publish step
 - `app_publish_verify` is for explicit final verification, not the default next step after every write
 
+## BI Reports
+
+- Use `app_charts_apply` for QingBI report body/config creation or updates.
+- Use `app_associated_resources_apply` only when an existing BI report or view needs to appear in the Qingflow app associated-resource area or a specific view.
+- `app_charts_apply` currently creates/updates app-source BI reports only (`dataSourceType=qingflow`); dataset BI reports can only be attached when they already exist.
+- Creating a chart with `app_charts_apply` does not automatically show it in the Qingflow app UI; attach it separately if display is required.
+- `target` and `table` remain compatibility aliases for QingBI `indicator` and `detail`; use the real QingBI chart type when you need a specific type such as `summary`, `columnar`, `stacked_bar`, `scatter`, or `dualaxes`.
+
+## 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.
+- For per-view display, remove, and reorder, existing associated reports/views may be referenced by `associated_item_id`, `chart_id`/`chart_key`, or `view_key`; the tool resolves these to the internal id before writing.
+- `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 +66,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 +97,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.