@josephyan/qingflow-app-user-mcp 1.1.26 → 1.1.28

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

@@ -1,186 +0,0 @@
-# Update Flow
-
-Use this when the app already exists and the task is only about workflow.
-
-## Minimal sequence
-
-1. `builder_tool_contract(tool_name="app_flow_apply")`
-2. `app_get_fields`
-3. `app_get_flow`
-4. `role_search` or `member_search`
-5. `role_create` if the user wants a reusable directory role and no good role exists
-6. start from a canonical preset when possible
-7. patch the skeleton instead of freehanding a full graph
-8. reuse preset node ids when patching:
-   - `basic_approval` -> patch `approve_1`
-   - `basic_fill_then_approve` -> patch `fill_1` and `approve_1`
-   Do not add a second approval/fill node with a new id unless you are intentionally replacing the skeleton.
-   The MCP now auto-aligns the simplest single-node preset overrides, but still prefer explicit preset ids so the merged graph stays predictable.
-9. `app_flow_apply`
-10. `app_get_flow` when apply returns `partial_success` or the user asked for verification
-
-If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
-
-## Example
-
-Canonical preset mapping:
-
-- “默认审批/基础审批/普通审批” -> `basic_approval`
-- “先填报再审批/提交后审批” -> `basic_fill_then_approve`
-
-Apply a simple approval flow with a role assignee and node-level editable fields:
-
-```json
-{
-  "tool_name": "app_flow_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "preset": "basic_approval",
-    "publish": true,
-    "nodes": [
-      {
-        "id": "approve_1",
-        "type": "approve",
-        "name": "部门审批",
-        "assignees": {
-          "role_names": ["项目经理"]
-        },
-        "permissions": {
-          "editable_fields": ["状态", "审批意见"]
-        }
-      }
-    ]
-  }
-}
-```
-
-For flexible business requirements, do not jump straight to a full custom graph. Use this safer pattern:
-
-1. build a base skeleton from a preset
-2. identify the business-specific changes
-3. patch nodes/transitions explicitly
-
-## Targeted node updates
-
-To change one or a few nodes without rewriting the full spec, use `patch_nodes[]` instead of `spec`:
-
-```json
-{
-  "tool_name": "app_flow_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "publish": true,
-    "patch_nodes": [
-      {
-        "id": "approve_1",
-        "set": {
-          "name": "总监审批",
-          "assignees": {"role_names": ["总监"]}
-        }
-      }
-    ]
-  }
-}
-```
-
-`patch_nodes[]` reads the current flow, merges `set` keys and removes `unset` keys on the matched node, then writes the full spec back. It returns `FLOW_NODE_NOT_FOUND` if the `id` does not match any existing node — call `app_get_flow` first to confirm ids.
-
-Do NOT use `patch_nodes` and `spec` together in the same call.
-
-Public flow building is intentionally limited to linear workflows. Use only:
-
-- `start`
-- `approve`
-- `fill`
-- `copy`
-- `webhook`
-- `end`
-
-Do not generate `branch` or `condition` nodes through `app_flow_apply`. The backend workflow route is not front-end stable for those node types, and MCP now returns `FLOW_NODE_TYPE_UNSUPPORTED` instead of writing a visually broken flow.
-After `app_flow_apply` returns blocking issues or canonical arguments, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite the result into internal fields such as `role_entries` or `editable_que_ids`.
-When you patch a preset, patch the preset node itself. Do not leave the preset approval node unassigned while adding a second custom approval node.
-
-## Common failures
-
-### `FLOW_ASSIGNEE_REQUIRED`
-
-Approval, fill, and copy nodes must declare at least one assignee.
-
-If this happens after using a preset, check for this specific mistake first:
-
-- the preset created `approve_1` or `fill_1`
-- your patch created a different node id instead of patching that preset node
-- the original preset node remained in the graph without assignees
-
-Preferred fix order:
-
-1. `role_search`
-2. `member_search` only if the user explicitly named members
-3. `role_create` if the business needs a reusable role
-4. patch the preset node id itself with canonical `assignees.*`
-5. retry `app_flow_apply`
-
-### `FLOW_DEPENDENCY_MISSING`
-
-The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
-
-Preferred recovery:
-
-1. use the returned `suggested_next_call`
-2. apply the minimal schema patch
-3. rerun `app_get_fields`
-4. rerun `app_flow_apply`
-
-### `INVALID_FLOW_EDGE`
-
-One or more transitions reference unknown nodes or create an invalid graph.
-
-### `UNKNOWN_FLOW_FIELD`
-
-The workflow referenced a field name that does not exist, often in:
-
-- `permissions.editable_fields`
-
-Call `app_get_fields` and retry with the exact field names returned by the app.
-
-### `FLOW_NODE_TYPE_UNSUPPORTED`
-
-The public workflow builder only supports linear flows. Remove `branch` and `condition` nodes and redesign the flow with stable sequential nodes instead of retrying the same graph.
-
-### `STATUS_FIELD_REQUIRED`
-
-The app has no explicit status field recognized by the internal workflow compiler. Add one with `app_schema_apply`, then retry.
-
-### `FLOW_STAGE_CONTEXT_MISSING`
-
-Internal flow stage context was missing or invalid. Re-run `app_flow_apply` with the normalized arguments, and do not switch to hidden `solution_*` tools.
-
-### `VALIDATION_ERROR`
-
-Do not keep guessing preset names or node shapes. First:
-
-1. inspect `suggested_next_call`
-2. reuse `canonical_arguments` if present
-3. check `allowed_values`
-4. retry with canonical preset or canonical node types
-5. for workflow actors and permissions, always convert to:
-   - `assignees.role_names`
-   - `assignees.member_names`
-   - `permissions.editable_fields`
-
-Do not copy internal keys from old plan outputs or logs, including:
-
-- `role_entries`
-- `editable_que_ids`
-
-## Notes
-
-- `mode=replace` is the only supported flow apply mode when using `spec`; `patch_nodes[]` does not require a `mode`
-- `app_flow_apply` publishes by default
-- Prefer roles over explicit members unless the user explicitly asks for named members
-- `basic_approval` and `basic_fill_then_approve` are skeletons, not complete business workflows
-- Report results precisely:
-  - “基础流程骨架已创建” when only the preset landed
-  - “业务定制规则已补齐” only after the patch phase is complete

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

@@ -1,68 +0,0 @@
-# Update Layout
-
-Use this when fields already exist and the task is only about form grouping or ordering.
-
-## Minimal sequence
-
-1. `app_get_fields`
-2. `app_get_layout`
-3. `builder_tool_contract` when the section shape is not already obvious
-4. `app_layout_apply`
-
-## Example
-
-Apply a custom layout with the canonical public section shape:
-
-```json
-{
-  "tool_name": "app_layout_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "mode": "merge",
-    "publish": true,
-    "sections": [
-      {
-        "title": "基础信息",
-        "rows": [
-          ["客户名称", "订单金额"],
-          ["状态", "跟进日期"]
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Common failures
-
-### `UNKNOWN_LAYOUT_FIELD`
-
-At least one field name does not exist. Re-read with `app_get_fields`.
-
-### `DUPLICATE_LAYOUT_FIELD`
-
-The same field appears more than once in the requested layout.
-
-### `INCOMPLETE_LAYOUT`
-
-Only happens in `mode=replace`. Switch to `mode=merge` unless you intend to place every field exactly once.
-
-### `LAYOUT_APPLY_FAILED`
-
-Re-read with `app_get_layout`. Check `current_field_names`, `request_id`, and `suggested_next_call`.
-
-### `VALIDATION_ERROR`
-
-Do not keep guessing section keys. Reuse `suggested_next_call`, `canonical_arguments`, `section_allowed_keys`, and `minimal_section_example`.
-
-If the same shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_apply)`.
-
-## Notes
-
-- `section_id` is optional; it is generated from the section title
-- `merge` is safer than `replace`
-- Unmentioned fields stay in place or get auto-added to `未分组字段`
-- Public builder layout sections use `title + rows`
-- Do not treat “一行四个字段 / 四列布局 / 每行放四个” as a top-level `columns` parameter; translate it into a `rows` matrix
-- Do not prefer `fields` or `field_ids` once `rows` is known, even though MCP may normalize those shorthands for recovery

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

@@ -1,72 +0,0 @@
-# Update Schema
-
-Use this when the app already exists and the task is only about fields.
-
-## Minimal sequence
-
-1. `app_resolve`
-2. `app_get_fields`
-3. `app_schema_apply`
-
-## Example
-
-Read current fields first:
-
-```json
-{
-  "tool_name": "app_get_fields",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123"
-  }
-}
-```
-
-Apply the patch:
-
-```json
-{
-  "tool_name": "app_schema_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "publish": true,
-    "add_fields": [
-      {"name": "跟进日期", "type": "date"},
-      {"name": "数据封面", "type": "attachment", "as_data_cover": true}
-    ],
-    "update_fields": [
-      {"selector": {"name": "金额"}, "set": {"name": "订单金额", "required": true}},
-      {"selector": {"name": "客户名称"}, "set": {"as_data_title": true}}
-    ],
-    "remove_fields": [
-      {"name": "旧字段"}
-    ]
-  }
-}
-```
-
-## Common failures
-
-### `FIELD_NOT_FOUND`
-
-The selector did not match current schema. Re-read with `app_get_fields` and use `name`, `field_id`, or `que_id`.
-
-### `DUPLICATE_FIELD`
-
-The field already exists with a different shape. Switch from `add_fields` to `update_fields`.
-
-### `SCHEMA_APPLY_FAILED`
-
-Treat it as uncertain write state. Read back with `app_get_fields` before retrying.
-
-## Notes
-
-- `title` and `label` are accepted aliases for `name`
-- `textarea -> long_text`
-- `currency -> amount`
-- `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

@@ -1,291 +0,0 @@
-# Update Views
-
-Use this when the task is only about table, card, board, or gantt views.
-
-## Minimal sequence
-
-1. `builder_tool_contract(tool_name="app_views_apply")`
-2. `app_get_fields`
-3. `app_get` for current view/chart/button inventory and app-level associated resource ids
-4. `app_views_apply`
-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` 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
-
-Canonical rules before any example:
-
-- Always use `columns`
-- Do not emit `column_names`
-- Treat `fields` only as a legacy alias the MCP may normalize, not as the preferred shape
-- Use `filters` with canonical keys `field_name`, `operator`, `value`/`values`
-- Use `query_conditions` for the frontend query panel. Do not put query-panel fields into `filters`.
-- When creating any new table or card view, always include `query_conditions` with `enabled: true`. In `rows`, list the fields users would most commonly search by — typically the data-title field, any status/type select fields, date fields, and member fields. Do not omit `query_conditions` or leave `rows` empty on a new view.
-- New views created by `app_views_apply` default the frontend associated report/view area to visible with `limit_type="all"`. Existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched.
-- Use `app_associated_resources_apply` for the associated report/view resource pool, selected resources, and match rules. `associated_item_id` is the internal associated-resource id from `app_get.associated_resources`; `view_configs`, remove, and reorder may also pass an existing resource's `chart_id`/`chart_key`/`view_key`, which the tool resolves to the internal id. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
-- For gantt, use `start_field`, `end_field`, and optionally `title_field`
-- If `app_get.views` 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:
-
-```json
-{
-  "tool_name": "app_views_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "publish": true,
-    "upsert_views": [
-      {
-        "name": "全部订单",
-        "view_key": "VIEW_KEY_IF_DUPLICATE_NAMES_EXIST",
-        "type": "table",
-        "columns": ["订单编号", "客户名称", "订单金额", "状态", "负责人", "创建时间"],
-        "query_conditions": {
-          "enabled": true,
-          "exact": false,
-          "hide_before_query": false,
-          "rows": [["订单编号", "客户名称"], ["状态", "负责人"], ["创建时间"]]
-        }
-      }
-    ],
-    "remove_views": []
-  }
-}
-```
-After `app_views_apply` returns canonical arguments or blocking issues, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite aliases back into non-canonical keys such as `column_names`.
-
-Existing table view: replace only frontend query conditions:
-
-```json
-{
-  "tool_name": "app_views_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "publish": true,
-    "patch_views": [
-      {
-        "view_key": "VIEW_KEY",
-        "set": {
-          "query_conditions": {
-            "enabled": true,
-            "exact": false,
-            "hide_before_query": false,
-            "rows": [["客户名称", "负责人"], ["创建时间"]]
-          }
-        }
-      }
-    ],
-    "remove_views": []
-  }
-}
-```
-
-Meaning:
-
-- `filters` are saved view filters and apply immediately when the view opens.
-- `query_conditions` only configures which fields appear in the frontend query panel. The query values come later from the user through the page.
-- `query_conditions.rows` is a matrix of field names and is compiled to backend `queryCondition` field ids.
-- The patch call preserves the view's existing columns, saved filters, type-specific date/card/board config, buttons, visibility, and other backend-required fields.
-
-View associated resources example:
-
-```json
-{
-  "tool_name": "app_associated_resources_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "upsert_resources": [],
-    "remove_associated_item_ids": [],
-    "reorder_associated_item_ids": [],
-    "view_configs": [
-      {
-        "view_key": "VIEW_KEY",
-        "visible": true,
-        "limit_type": "select",
-        "associated_item_ids": [123, 124]
-      }
-    ]
-  }
-}
-```
-
-Use `{"visible": true, "limit_type": "all"}` to show all app-level associated resources, and `{"visible": false}` to hide the area. The ids above can be internal `associated_item_id` values or existing resource `chart_id`/`chart_key`/`view_key` values from `app_get.associated_resources`. Before creating a resource, check whether the same `target_app_key + view_key/chart_key` already exists; if it does, use `patch_resources` with that `associated_item_id`. Dataset BI reports must already exist in QingBI and should be attached with `report_source="dataset"`; do not try to create them through `app_charts_apply`. If you create a new associated item in the same call, give it a `client_key` and reference it from `view_configs[].associated_item_refs`; `client_key` is not persisted and cannot deduplicate a later call.
-
-Create and show a BI indicator-card report in the same call:
-
-```json
-{
-  "tool_name": "app_associated_resources_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "upsert_resources": [
-      {
-        "client_key": "total_hours_card",
-        "graph_type": "chart",
-        "target_app_key": "TIMESHEET_APP",
-        "chart_key": "CHART_KEY",
-        "report_source": "app",
-        "match_mappings": [
-          {"target_field": "关联员工", "source_field": "数据ID"},
-          {"target_field": "状态", "value": "待提交"}
-        ]
-      }
-    ],
-    "remove_associated_item_ids": [],
-    "reorder_associated_item_ids": [],
-    "view_configs": [
-      {
-        "view_key": "VIEW_KEY",
-        "visible": true,
-        "limit_type": "select",
-        "associated_item_refs": ["total_hours_card"]
-      }
-    ]
-  }
-}
-```
-
-Board example:
-
-```json
-{
-  "tool_name": "app_views_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "upsert_views": [
-      {
-        "name": "按状态看板",
-        "type": "board",
-        "group_by": "状态",
-        "columns": ["订单编号", "客户名称", "订单金额"]
-      }
-    ],
-    "remove_views": []
-  }
-}
-```
-
-Gantt example with filters:
-
-```json
-{
-  "tool_name": "app_views_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "upsert_views": [
-      {
-        "name": "项目甘特图",
-        "type": "gantt",
-        "columns": ["项目名称", "开始日期", "结束日期", "状态"],
-        "start_field": "开始日期",
-        "end_field": "结束日期",
-        "title_field": "项目名称",
-        "filters": [
-          {
-            "field_name": "状态",
-            "operator": "eq",
-            "value": "进行中"
-          }
-        ]
-      }
-    ],
-    "remove_views": []
-  }
-}
-```
-
-## Common failures
-
-### `UNKNOWN_VIEW_FIELD`
-
-At least one `columns` or `group_by` field name does not exist.
-
-### `INVALID_VIEW_TYPE`
-
-Public view types are only `table`, `card`, `board`, `gantt`.
-
-Map old or intuitive labels before calling the tool:
-
-- `tableView` -> `table`
-- `cardView` -> `card`
-- `kanban` -> `board`
-
-### `INVALID_GANTT_CONFIG`
-
-Gantt views require at least:
-
-- `start_field`
-- `end_field`
-
-Also make sure these field names already exist on the app.
-
-### `VIEW_APPLY_FAILED`
-
-The backend rejected the normalized view payload. Re-read fields and inspect `request_id` before retrying.
-
-Do not repeat `app_views_apply` with guessed keys. First:
-
-1. check `suggested_next_call`
-2. reuse `canonical_arguments` if present
-3. call `app_get_views` to see whether any requested views landed anyway
-4. if needed, call `builder_tool_contract`
-5. retry only the minimal failed view patch
-
-### `VIEW_FILTER_READBACK_MISMATCH`
-
-The view object was created or updated, but the readback config did not keep the intended filter values.
-
-Treat this as:
-
-- the view exists
-- the filter is **not yet verified**
-
-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`
-- `column_names` should not appear in skill examples
-- `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