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

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

@@ -0,0 +1,276 @@
+---
+name: qingflow-app-builder
+description: Build, configure, and modify Qingflow apps and systems after the MCP is already connected and authenticated. Use when the user wants to apply or repair an existing SolutionSpec, modify an existing package with app, view, workflow, portal, navigation, or reporting tools, verify builder-side results, or troubleshoot system-building behavior. Do not use this skill to install the MCP or to author a brand new SolutionSpec from scratch.
+metadata:
+  short-description: Build and modify Qingflow apps and systems
+---
+
+# Qingflow App Builder
+
+## Overview
+
+This skill is for the current **public builder surface**, not for legacy low-level builder writes.
+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](references/public-surface-sync.md).
+
+## Current Public Mental Model
+
+Model builder requests in four layers and keep them separate:
+
+- `package`: the app bundle or solution container
+- `app`: one form/app inside that package
+- `field`: one field inside one app
+- `relation`: a field that links one app to another app
+
+Default modeling rules:
+
+- One business object -> one app
+- Attributes of that object -> fields inside that app
+- Another business object -> a separate app, not a text field
+- Cross-object links -> relation fields, not text fields
+
+## 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_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_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
+
+Treat these as the official surface. Do not default to `package_create`, `package_attach_app`, raw `portal_*` writes, or raw `qingbi_report_*` writes.
+
+## Current Public Defaults
+
+- 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 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
+
+1. Ensure auth exists
+2. Ensure workspace is selected
+3. Confirm whether the task is read-only or write-impacting
+4. Resolve the smallest stable target:
+   - app-scoped work -> `app_resolve`
+   - package-scoped work with known id -> `package_get`
+   - portal inventory -> `portal_list`
+5. Read only the smallest config slice needed:
+   - 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` only when the app_get compact list is not enough
+   - flow -> `app_get_flow`
+   - 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`
+   - 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
+
+## Safe Usage Rules
+
+- Do not guess package identity from a loose name. Public package work assumes a known `package_id`, or an explicit create/update intent through `package_apply`.
+- 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.
+- 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.
+- Respect collaborative edit locks. Only use `app_release_edit_lock_if_mine` when the lock owner is the current authenticated user.
+- If the supported builder surface is still awkward or blocked after reasonable use, summarize the gap, ask whether to submit feedback, and call `feedback_submit` only after explicit user confirmation.
+
+## 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
+- For app permissions, report `can_edit_app_base` separately from `can_edit_form / can_edit_flow / can_edit_views / can_edit_charts`.
+
+## Practical Patterns
+
+- Read one package: `package_get`
+- Create or update one package: `package_apply`
+- Resolve one app: `app_resolve`
+- Read one app map: `app_get`
+- Read fields only: `app_get_fields`
+- Read layout summary: `app_get_layout`
+- Read views summary: `app_get_views`
+- Read flow summary: `app_get_flow`
+- Read chart summary: `app_get_charts`
+- Read portal config: `portal_get`
+- Search members or roles: `member_search`, `role_search`
+- Create reusable role: `role_create`
+- Add/update/remove fields: `app_schema_apply`
+- Merge or replace layout: `app_layout_apply`
+- Replace workflow: `app_flow_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](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)
+- Update layout only: [references/update-layout.md](references/update-layout.md)
+- Update workflow only: [references/update-flow.md](references/update-flow.md)
+- 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)

package/skills/qingflow-app-builder/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Qingflow App Builder"
+  short_description: "Build and modify Qingflow apps and systems"
+  default_prompt: "Use $qingflow-app-builder to build or modify a Qingflow app or system safely, and verify environment routing and post-write readbacks when builder flows touch live data."