@qingflow-tech/qingflow-app-user-mcp 1.0.41 → 1.0.42

package/skills/qingflow-app-builder/references/flow-actors-and-permissions.md

@@ -1,123 +0,0 @@
-# Flow Actors And Permissions
-
-Use this when the workflow needs real assignees or node-level editable field permissions.
-
-## Canonical policy
-
-- Approval, fill, and copy nodes must declare at least one assignee.
-- Prefer roles over explicit members.
-- Resolve directory actors before calling `app_flow_apply`.
-- Use canonical keys only:
-  - `assignees.role_names`
-  - `assignees.role_ids`
-  - `assignees.member_names`
-  - `assignees.member_emails`
-  - `assignees.member_uids`
-  - `permissions.editable_fields`
-
-## Recommended order
-
-1. `app_get_fields`
-2. `app_get_flow`
-3. `role_search`
-4. `member_search` when the user explicitly names people
-5. `role_create` when no reusable role exists and the user wants role-based routing
-6. `app_flow_apply`
-
-## Examples
-
-### Route an approval node to a reusable role
-
-```json
-{
-  "tool_name": "app_flow_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "preset": "basic_approval",
-    "nodes": [
-      {
-        "id": "approve_1",
-        "type": "approve",
-        "name": "部门审批",
-        "assignees": {
-          "role_names": ["项目经理"]
-        }
-      }
-    ]
-  }
-}
-```
-
-### Route to explicit members when the user names people
-
-```json
-{
-  "tool_name": "app_flow_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "preset": "basic_approval",
-    "nodes": [
-      {
-        "id": "approve_1",
-        "type": "approve",
-        "name": "部门审批",
-        "assignees": {
-          "member_names": ["严琪东", "张三"]
-        }
-      }
-    ]
-  }
-}
-```
-
-### Let one node edit selected fields only
-
-```json
-{
-  "tool_name": "app_flow_apply",
-  "arguments": {
-    "profile": "default",
-    "app_key": "APP_123",
-    "mode": "replace",
-    "publish": true,
-    "nodes": [
-      {"id": "start", "type": "start", "name": "发起"},
-      {
-        "id": "approve_1",
-        "type": "approve",
-        "name": "部门审批",
-        "assignees": {
-          "role_names": ["项目经理"]
-        },
-        "permissions": {
-          "editable_fields": ["状态", "审批意见", "项目负责人"]
-        }
-      },
-      {"id": "end", "type": "end", "name": "结束"}
-    ],
-    "transitions": [
-      {"from": "start", "to": "approve_1"},
-      {"from": "approve_1", "to": "end"}
-    ]
-  }
-}
-```
-
-## Common recovery
-
-### `ROLE_NOT_FOUND` / `AMBIGUOUS_ROLE`
-
-- retry with `role_search`
-- if the business wants a reusable route and no exact role exists, create one with `role_create`
-
-### `MEMBER_NOT_FOUND` / `AMBIGUOUS_MEMBER`
-
-- retry with `member_search`
-- do not guess user ids
-
-### `UNKNOWN_FLOW_FIELD`
-
-- reread fields with `app_get_fields`
-- only pass real current field names to `permissions.editable_fields`

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

@@ -1,113 +0,0 @@
-# Builder Gotchas
-
-## Auth and workspace
-
-- `auth_*` success does not mean a workspace is selected
-- In Wingent Momo runtime, do not run `workspace_select` before builder work. Re-run it only after an explicit auth/route recovery or when a business tool reports the workspace is missing.
-
-## Package ownership
-
-- Public package work should stay on `package_get / package_apply`
-- Do not treat `package_attach_app` as the public default story anymore; if it still exists in low-level code, treat it as internal/legacy
-- Check package-related readback after schema writes instead of assuming package ownership from the write alone
-
-## Package vs app vs field
-
-- A package/system is not an app
-- Another app is not a field
-- 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
-- For a complete system, the main creation path is one multi-app `app_schema_apply(package_id=..., apps=[...])` with stable `apps[].client_key` values and same-call relation fields using `target_app_ref`
-- Use `target_app_key` only for an app that already exists or has been confirmed by readback
-
-## Auto publish
-
-- `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default
-- 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
-
-## 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
-- Use `app_get_fields` before schema or view work
-- Use `app_get_layout` before layout work
-- 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
-- Approval, fill, and copy nodes also require at least one assignee
-- Prefer roles over explicit members unless the user explicitly names people
-- Resolve assignees with `role_search` / `member_search` before flow apply
-- Use `permissions.editable_fields` for node-level editable field permissions; do not guess field ids
-- Preset node ids matter. When patching `basic_approval` or `basic_fill_then_approve`, reuse `approve_1` and `fill_1` unless you are explicitly replacing the skeleton.
-- If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first
-- Do not switch to hidden `solution_*` tools from public builder flows
-
-## Retry discipline
-
-- If a write returns `partial_success`, read back before retrying
-- If multi-app schema apply times out, returns `write_executed=true`, returns `safe_to_retry=false`, or has incomplete readback, treat it as `write_may_have_succeeded`; the next action is `readback_before_retry`
-- `readback_before_retry` means read package/app/fields first, classify which intended apps and relation fields actually exist, and retry only the verified missing slice
-- Do not repeat create steps after `app_key` already exists
-- Do not split a complete-system schema create into single-app rebuilds until readback proves exactly what is missing
-- Do not bypass duplicate/conflict states by inventing `V2`, `测试`, timestamp, or random-suffix app names in a real business package
-- For backend rejects, keep the retry narrow: retry only the failed tool, not the whole chain
-- For `VALIDATION_ERROR`, do not keep guessing. Reuse `suggested_next_call`, `canonical_arguments`, `allowed_keys`, and `allowed_values` first.
-- For layout `VALIDATION_ERROR`, also inspect `section_allowed_keys`, `section_aliases`, and `minimal_section_example`. If the same layout-shape error repeats twice, stop free-form retries and re-read `builder_tool_contract(app_layout_apply)`.
-- For flow work, do not replay internal keys from old logs or plan outputs. Public builder calls should stay on:
-  - `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.
-- If a view or flow write fails, report the smallest next action:
-  - wrong key -> switch to canonical key
-  - unsupported preset -> switch to allowed canonical preset
-  - backend reject -> re-read summary and retry only the failed patch
-- Do not translate abstract user phrases like “灵活流程” or “默认视图” directly into MCP arguments. First convert them to a preset or explicit patch plan.

package/skills/qingflow-app-builder/references/match-rules.md

@@ -1,129 +0,0 @@
-# Builder Match Rules
-
-Use this reference for builder-side field matching rules in custom buttons and associated view/report filters.
-
-This is not the same thing as `record_access` analysis filters or normal view `filters`.
-
-Unified public semantics:
-
-- Fixed filters use `field_name + operator + value/values`, for example view `filters` and chart `filters`.
-- Current-record context matches use `target_field + operator + source_field/value`, for example associated resource `match_mappings` and add-data button mappings.
-- Do not handwrite `judgeType`, `judgeValues`, or `matchRules`; the CLI compiles them for the target backend protocol.
-
-## Where These Rules Apply
-
-- `app_custom_buttons_apply.upsert_buttons[].trigger_add_data_config.field_mappings`
-- `app_custom_buttons_apply.patch_buttons[].set.trigger_add_data_config.field_mappings`
-- `app_associated_resources_apply.upsert_resources[].match_mappings`
-- `app_associated_resources_apply.patch_resources[].set.match_mappings`
-
-Prefer semantic mappings. Do not handwrite raw `que_relation` or `match_rules` unless you are preserving an existing backend config.
-
-## System Fields
-
-System fields can participate in mappings:
-
-- `数据ID`, `row_record_id`, `apply_id`, `_id` -> `field_id=-17`
-  This is the current record's real apply/record ID.
-- `编号`, `数据编号`, `record_number` -> `field_id=0`
-  This is the frontend-visible record number. It may be custom formatted and is not the same as `数据ID`.
-
-Explicit selectors such as `{"field_id": -17}` and `{"field_id": 0}` are allowed and remove ambiguity.
-
-## Custom Buttons
-
-Use `field_mappings` for dynamic values copied from the current source record:
-
-```json
-{
-  "target_app_key": "WORKLOG_APP",
-  "field_mappings": [
-    {"source_field": "数据ID", "target_field": "关联员工"},
-    {"source_field": "员工名称", "target_field": "员工姓名"}
-  ],
-  "default_values": {
-    "状态": "待提交"
-  }
-}
-```
-
-Use `default_values` only for static constants. Do not use `default_values` as the preferred way to pass the current record.
-
-For an existing button, put the same semantic config under `patch_buttons[].set`:
-
-```json
-{
-  "button_id": 3858041,
-  "set": {
-    "trigger_add_data_config": {
-      "target_app_key": "WORKLOG_APP",
-      "field_mappings": [
-        {"source_field": "数据ID", "target_field": "关联员工"}
-      ],
-      "default_values": {
-        "状态": "待提交"
-      }
-    }
-  }
-}
-```
-
-## Associated Resources
-
-Use `match_mappings` for associated view/report filters:
-
-```json
-{
-  "graph_type": "view",
-  "target_app_key": "WORKLOG_APP",
-  "view_key": "WORKLOG_VIEW",
-  "match_mappings": [
-    {"target_field": "关联员工", "source_field": "数据ID"},
-    {"target_field": "状态", "value": "待提交"}
-  ]
-}
-```
-
-Dynamic conditions use `source_field`; static conditions use `value`.
-
-Recommended operators are `eq`, `neq`, `in`, `contains`, `gte`, `lte`, `is_empty`, and `not_empty`; aliases such as `equal`, `equals`, `=`, `!=`, `any_of`, `one_of`, and `empty` are accepted. `field_name` and `field` can be used as aliases for `target_field`. Static single-value filters should use `value`; a single-item `values` array is also accepted.
-
-Examples:
-
-```json
-{"target_field": "客户ID", "operator": "eq", "source_field": "数据ID"}
-{"target_field": "状态", "operator": "eq", "value": "有效"}
-```
-
-For an existing associated resource, put the same filter mapping under `patch_resources[].set`:
-
-```json
-{
-  "associated_item_id": 3497587,
-  "set": {
-    "match_mappings": [
-      {"target_field": "关联员工", "source_field": "数据ID"}
-    ]
-  }
-}
-```
-
-## Type Compatibility
-
-- Relation fields: match another relation field with the same target app, or match `数据ID(-17)` when the target relation points to the current source app.
-- Record ID `数据ID(-17)`: can match relation fields that point to the current source app, or ID-compatible text/number fields.
-- Record number `编号(0)`: can match text, long text, number, amount, or another record-number field.
-- Member fields: only match member fields.
-- Department fields: only match department fields.
-- Option fields: single select, multi select, and boolean can match option-family fields or static option values.
-- Date fields: date and datetime can match each other.
-- Text fields: text, long text, phone, and email can match each other.
-- Number fields: number and amount can match each other.
-- Attachment, subtable, code block, Q-Linker, and address fields are not default match fields.
-
-## Error Interpretation
-
-- Field not found: re-read `app_get` or `app_get_fields` and retry with an exact title or `field_id`.
-- Type mismatch: choose a compatible source/target pair from the matrix above.
-- Reference source mismatch: the target relation field points to a different app; choose a relation field that points back to the current source app, or match a non-relation field.
-- Mixed raw and semantic modes: use either semantic `field_mappings/match_mappings` or raw `que_relation/match_rules`, never both in the same item.

package/skills/qingflow-app-builder/references/public-surface-sync.md

@@ -1,75 +0,0 @@
-# Qingflow Core Public Surface Sync
-
-Use this file as the maintenance baseline for the core Qingflow skills.
-It is not a user-facing product spec. It exists to prevent skill drift.
-
-## Current Public Defaults
-
-### User data
-
-- Read range first with `app_get`, then `record_browse_schema_get(view_id=...)`
-- Treat `record_browse_schema_get.fields` as the selected Qingflow table view header schema; `record_access.fields` and `record_list` field selectors must stay aligned with it.
-- Standard flows:
-  - analyze: `app_get -> record_browse_schema_get -> record_access -> Python`
-  - browse detail: `app_get -> record_browse_schema_get -> record_list / record_get`
-  - explicit export/download/Excel: `app_get -> choose view_id -> view_get -> record_export_*` or `record_export_direct`; export tools require explicit `view_id`
-  - insert: `record_insert_schema_get -> record_insert(items)`
-  - update: `record_get -> record_update`; use `record_update_schema_get` only for failure diagnosis or ambiguous writable-field routing
-
-### Tasks
-
-- Discovery stays on `task_list`
-- `task_list --query` uses backend search first and only applies local fallback when backend returns zero rows
-- Public actions are:
-  - `approve`
-  - `reject`
-  - `rollback`
-  - `transfer`
-  - `urge`
-  - `save_only`
-- `reject` requires `payload.audit_feedback`
-- `save_only` requires non-empty `fields`
-- `TASK_RUNTIME_CONSUMED_AFTER_ACTION` is a normal post-success warning when the current node runtime is consumed and `46001` appears on re-read
-
-### Builder
-
-- Official package entry: `package_get`, `package_apply`
-- Official builder 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_publish_verify`
-- `portal_apply` edit mode may omit `sections` for base-info-only updates
-- `app_charts_apply.visibility` is a public capability and should be treated as a base-only visibility update
-- Existing object parameter replacement should use `patch_views`, `patch_buttons`, `patch_resources`, and `patch_charts`; `upsert_*` is for creation or full target config
-- `app_get.editability` uses:
-  - `can_edit_app_base`
-  - `can_edit_form`
-  - `can_edit_flow`
-  - `can_edit_views`
-  - `can_edit_charts`
-
-## Known High-Drift Areas
-
-- Task actions, especially `save_only`, reject payload requirements, and `46001` post-action interpretation
-- Package public tools: do not regress to `package_create` / `package_attach_app` as the public default story
-- App editability: do not let `can_edit_form` imply app base-info writes
-- Portal and chart visibility: keep the public story on `portal_apply` / `app_charts_apply`, not low-level internal writes
-- Analysis path: standard path stays `record_access -> Python`
-
-## Release Checklist For Skill Maintenance
-
-After each beta that changes public behavior, re-check:
-
-1. `public_surface.py`
-2. `README.md`
-3. `server_app_builder.py` and `server.py` top-level guidance
-4. CLI help for `task`, `builder package`, `builder portal`, `builder charts`
-5. Whether new warnings or verification fields need to be explained in skills
-
-If a tool behavior changed but the public surface did not, prefer updating the relevant skill section instead of expanding this file.

package/skills/qingflow-app-builder/references/single-app-development-guide.md

@@ -1,47 +0,0 @@
-# Single App Development Guide
-
-Use this when the user asks for one app/form, or gives one `app_key`.
-If the user asks for a package, system, or several related modules, use `complete-system-development-guide.md` instead.
-
-## Recommended Completeness
-
-Required:
-
-- target package/app resolved by `package_get`, `app_resolve`, or `app_get`
-- business fields created or updated through `app_schema_apply`
-- exactly one readable top-level `as_data_title: true`
-- no platform system fields in `add_fields`
-- layout places the important fields
-- at least one business view beyond platform default views when the task includes user-facing list work
-
-Strongly recommended:
-
-- saved filters and query panel fields for the main operating views
-- simple charts when the app has status, amount, date, or owner fields worth tracking
-- associated resources or buttons only when they support a concrete workflow
-
-Optional:
-
-- workflow, portal entry, sample data, roles, or visibility changes when requested by the user or clearly needed by the app's job
-
-## Standard Path
-
-1. Read current target: `app_resolve` or `app_get`.
-2. Read current fields: `app_get_fields`.
-3. Apply fields with `app_schema_apply`.
-4. Apply layout with `app_layout_apply`.
-5. Apply views with `app_views_apply` when list/table/card/gantt behavior is part of the request.
-6. Apply charts/buttons/associated resources only if they are part of the app's actual workflow.
-7. Use `app_publish_verify` only when explicit live verification is required.
-
-## Field Rules
-
-- Use agent-friendly field types where possible: `text`, `multiline`, `select`, `multi_select`, `number`, `amount`, `date`, `datetime`, `member`, `department`, `attachment`, `relation`.
-- Do not create `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
-- Do not create built-in default views such as `全部数据` or `我的数据`; Qingflow provides system views.
-
-## Stop Conditions
-
-- If the task actually needs multiple business objects, stop and switch to the complete-system guide.
-- If a write returns `partial_success`, `write_executed=true`, or `safe_to_retry=false`, read back before retrying.
-- If the same validation error repeats twice, re-read `builder_tool_contract` instead of guessing.

package/skills/qingflow-app-builder/references/solution-playbooks.md

@@ -1,62 +0,0 @@
-# Builder Playbooks
-
-Use these when you need a quick reminder of the standard v2 builder sequences.
-
-## Create a complete system / app package
-
-1. `package_get` or `package_apply`
-2. one multi-app `app_schema_apply(package_id=..., apps=[...])`
-3. use stable `apps[].client_key` values and relation `target_app_ref` for same-call app references
-4. use returned/readback `app_key` values for layout, views, workflow, charts, buttons, associated resources, and portal work
-5. `app_publish_verify` only when the user asks for explicit live verification or a final verification pass is required
-
-If the multi-app schema write times out or returns `partial_success`, `write_executed=true`, `safe_to_retry=false`, or incomplete readback, the next action is `readback_before_retry`: read package/app/fields first, then retry only verified missing pieces. Do not repeat the whole apps payload, split into single-app rebuilds, or create `V2` / `测试` / random-suffix apps to dodge duplicate names.
-
-## Create a new app in an existing package
-
-1. `package_get`
-2. `app_resolve`
-3. `app_schema_apply`
-5. `app_publish_verify` only if the user asks for explicit live verification
-
-## Update fields on an existing app
-
-1. `app_resolve`
-2. `app_get_fields`
-3. `app_schema_apply`
-
-## Rework layout
-
-1. `app_get_layout`
-2. `app_layout_apply`
-
-Prefer `mode=merge`. Use `mode=replace` only when every field placement is intentional.
-
-## Add or update workflow
-
-1. `app_get_fields`
-2. `app_get_flow`
-3. `role_search` or `member_search`
-4. `role_create` if the business wants a reusable role and no good exact role exists
-5. `app_flow_apply`
-
-If `app_flow_apply` reports `FLOW_DEPENDENCY_MISSING`, fix schema first.
-If it reports `FLOW_ASSIGNEE_REQUIRED`, resolve roles or members first and retry with canonical `assignees.*`.
-
-## Add or update views
-
-1. `app_get_fields`
-2. `app_get_views`
-3. `app_views_apply`
-
-For both workflow and view work, prefer `suggested_next_call` over re-guessing arguments after a validation failure.
-
-## Final readback
-
-Prefer these fields after writes:
-
-- `app_get.tag_ids`
-- `app_get.publish_status`
-- `app_get_layout.unplaced_fields`
-- `app_get_views.views`
-- `app_get_flow.nodes`

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

@@ -1,106 +0,0 @@
-# Tool Selection
-
-Use the smallest v2 builder tool chain that can finish the task.
-
-## Default path
-
-`summary read -> apply -> publish_verify`
-
-Public builder `apply` tools already perform server-side planning, normalization, and dependency checks internally. Do not route normal public builder work through explicit `*_plan` tools.
-
-## Hierarchy first
-
-Before picking tools, decide which layer the request targets:
-
-- `package`: a solution/app bundle like “研发项目管理” or “费控管理系统”
-- `app`: one form/app inside that package
-- `field`: one field inside one app
-- `relation`: a field that links two apps
-
-If the user asks for multiple forms/modules that relate to each other, this is a package-level multi-app task, not a single-app create.
-
-Use this split consistently:
-
-- Complete system/package: `package_apply` first, then one `app_schema_apply(package_id=..., apps=[...])`.
-- Single app: `app_resolve/app_get` first, then app-scoped apply tools.
-- Record/task/data operation: leave builder and use record/task skills.
-
-## Resolve
-
-- `package_get`: read one known package by `package_id`; it reads package `baseInfo` first and may warn `PACKAGE_DETAIL_READ_DEGRADED` when the richer detail endpoint needs package edit/add-app permission. Treat that warning as degraded detail, not as package-read failure.
-- `package_apply`: create or update one package; use `create_if_missing=true` only after explicit user intent; layout/group/order changes require package edit permission because they call the backend package ordering route
-- `member_search`: resolve named people from the directory
-- `role_search`: resolve reusable roles from the directory
-- `role_create`: create a reusable role when the business owner wants role-based routing
-- `app_resolve`: locate an existing app by exactly one selector mode: `app_key`, or `app_name + package_id`; by-name resolution checks package detail/current visible apps before using broader admin-style app search, so a `/app/item` permission miss is not a frontend-visible-app failure
-
-## Summary reads
-
-- `app_get`: overall app config health, publish state, counts, and builder editability
-- `app_get_fields`: field names, types, required flags, section ids
-- `app_get_layout`: sections, rows, unplaced fields
-- `app_get_views`: current view names, types, columns, group-by
-- `app_get_flow`: workflow enabled state, nodes, transitions
-- `app_get_charts`: current chart ids, names, types, order
-- `chart_get`: one chart's base/config detail; base info is read through the Qingflow/qflow visible route first, and config may degrade from chart data when the CHART_SEE config endpoint is unavailable. Treat degraded config as a read-mode warning, not as proof the user cannot see the chart.
-- `portal_get`: current portal config detail and component inventory
-
-## Apply tools
-
-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`: use `patch_views` for existing-view parameter replacement; use `upsert_views` for creation or full target config; remove views by key; new views default associated report/view display to visible with `limit_type="all"`
-- `app_custom_buttons_apply`: use `patch_buttons` for existing-button parameter replacement; use `upsert_buttons` for creation or full target config; configure add-data field mappings/default values; bind buttons to header/detail/list view positions; `placement=list` maps to the backend `INSIDE` row/list button position; merge-mode view configs require `buttons`; use `view_configs[].mode="replace"` or `buttons=[]` to clear a view's custom button bindings. For child-record creation linked to the current source record, map `source_field: "数据ID"` to the target relation field.
-- `app_associated_resources_apply`: attach existing BI reports/views to the Qingflow app associated-resource pool and per-view display area; it does not create or edit QingBI report bodies/configs. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. Use `patch_resources` for existing associated-resource parameter replacement; use `upsert_resources` for creation or full target config; `view_configs`, remove, and reorder may reference existing resources by internal `associated_item_id` or by `chart_id`/`chart_key`/`view_key`; use `match_mappings` with `target_field + operator + source_field/value` for associated view/report filters; publishes after successful writes; omit raw `sourceType`, and use `report_source="dataset"` only to attach an existing BI dataset report. Before `upsert_resources`, read `app_get.associated_resources` and reuse an existing matching `target_app_key + view_key/chart_key`; repeated upsert can create duplicates because `client_key` is only valid inside one apply call.
-- `app_charts_apply`: create/edit/remove/reorder app-source QingBI report bodies/configs with `dataSourceType=qingflow`; it does not create/edit dataset BI reports and does not attach reports to Qingflow app associated-resource display. Use `filters` with `field_name + operator + value/values`; the tool compiles them to QingBI string judge types. Use `patch_charts` for existing-chart parameter replacement; use `upsert_charts` for creation or full target config; supports `target/table` aliases plus QingBI chart types such as `summary`, `columnar`, `area`, `funnel`, `radar`, `scatter`, `dualaxes`, and `map`; 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; create mode only prechecks package add_app, matching backend portal creation; edit mode may omit `sections` for base-info-only updates; when sections are supplied they still use replace semantics
-
-For object-level updates, the safe partial syntax is `patch_*` with the object's real selector field plus `set` and optional `unset`. `selector` is only a concept, not a literal key. Examples: `patch_views: [{"view_key": "VIEW_KEY", "set": {...}}]`, `patch_buttons: [{"button_id": 1001, "set": {...}}]`, `patch_resources: [{"associated_item_id": 123, "set": {...}}]`, `patch_charts: [{"chart_id": 456, "set": {...}}]`. The tool reads the current backend config, merges the patch, then submits the full backend payload internally. Do not send a partial `upsert_*` and expect missing required fields to be preserved.
-
-## Explicit post-apply tools
-
-- `app_publish_verify`: explicit final publish verification when the user asks for live confirmation
-
-## Decision shortcuts
-
-- Create one app inside an existing package:
-  `package_get -> app_resolve -> app_schema_apply`
-- Create a brand new package, then create one app in it:
-  `package_apply(create_if_missing=true) -> app_schema_apply`
-- Create a brand new multi-app system/package:
-  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`; use `apps[].client_key` plus `target_app_ref`, or `target_app` when referencing by app name
-- Update fields on an existing app:
-  `app_resolve -> app_get_fields -> app_schema_apply`
-- Tidy layout:
-  `app_get_fields -> app_get_layout -> builder_tool_contract (if shape is unclear) -> app_layout_apply`
-- Add workflow:
-  `builder_tool_contract -> app_get_fields -> app_get_flow -> role_search/member_search -> app_flow_apply -> app_get_flow`
-- Add views:
-  `builder_tool_contract -> app_get_fields -> app_get_views -> app_views_apply.patch_views/upsert_views -> app_get_views`
-- Add QingBI charts:
-  `builder_tool_contract -> app_get_fields -> app_get_charts -> app_charts_apply.patch_charts/upsert_charts -> app_get_charts`
-- Show an existing QingBI chart inside a Qingflow app/view:
-  `app_get -> app_associated_resources_apply.upsert_resources/patch_resources + view_configs -> app_get`
-- Create or update a portal:
-  `builder_tool_contract -> portal_get -> portal_apply -> portal_get`
-
-## Avoid
-
-- Do not handcraft raw Qingflow schema payloads
-- Do not rely on internal `solution_*` tools in public builder flows
-- Do not create a new package without first asking the user to confirm package creation
-- Do not regress to `package_create` or `package_attach_app` as the public default story
-- Do not treat a package/system name as `app_name` when the user clearly wants multiple apps inside it
-- Do not compress multiple business objects into one app with several text fields
-- Do not skip summary reads before flow or view work
-- Do not emit `column_names`; always use `columns`
-- Do not model layout shape with `fields`, `field_ids`, or top-level `columns`; custom layout sections should be `title + rows`
-- Do not reuse internal flow keys such as `role_entries` or `editable_que_ids` in public builder calls
-- Do not pass natural-language preset guesses such as `default_approval`; map them to canonical preset values first
-- Do not omit assignees on approval/fill/copy nodes
-- Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
-- Do not guess role ids, member ids, or editable field ids; resolve names first
-- Do not force agent-authored schema into backend-internal names when public keys exist: write icons as `icon + color` first; `icon_config` / `icon:{name,color}` are compatibility aliases only. Options may use `{label,value}`, and same-call relation targets may use `target_app_ref` / `target_app`.