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

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

@@ -1,290 +0,0 @@
----
-name: qingflow-app-builder
-description: Build, configure, and modify Qingflow apps and systems using the current Wingent Momo runtime MCP session. 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
-
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
-
-## Overview
-
-This skill is for the current **public builder surface**, not for legacy low-level builder writes.
-In Wingent Momo runtime, trust the injected MCP session, credentials, workspace, and route context until a tool explicitly reports otherwise.
-
-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).
-Then pick the matching development guide: [single-app-development-guide.md](references/single-app-development-guide.md) for one app, or [complete-system-development-guide.md](references/complete-system-development-guide.md) for app packages/systems.
-
-## 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
-
-## Route First
-
-Before any builder write, classify the request:
-
-- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(package_id=..., apps=[...])` for the app shells and fields. This is the main path for complete systems, not a bulk shortcut to abandon after the first slow response. Do not squeeze several business objects into one app.
-- **Single app**: the user names one form/app or gives one `app_key`. Use `app_resolve`/`app_get`, then `app_schema_apply` and the app-scoped apply tools.
-- **Record/user operation**: the user wants to add, edit, delete, approve, or analyze data. Route to the record/task skills instead of builder tools.
-
-For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields should use `target_app_ref` for another `apps[].client_key`; use `target_app_key` only when the target app already exists or has been confirmed by readback. Create the related apps with one multi-app schema apply; do not create each app separately just to collect app keys and then patch relations afterward.
-
-If a complete-system `app_schema_apply` times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, treat it as an uncertain write, not as a failed create. The next action is always `readback_before_retry`: read the package/app/fields first, compare intended `client_key`/`app_name`/relations against reality, and only then repair the missing slice. Do not retry the whole multi-app create, create `V2`/`测试`/random-suffix apps, or split the system into single-app rebuilds to bypass a duplicate/conflict.
-
-Builder schema inputs should follow agent-intuitive semantics:
-
-- primary icon syntax is `icon + color`, for example `icon: "table", color: "blue"`; `icon_name/icon_color`, `icon_config`, and `icon: {name, color}` are compatibility aliases only
-- `single_select` / `multi_select` options may be strings or objects such as `{label, value}`; tools normalize to option labels
-- relation fields need a target plus `display_field` and `visible_fields`
-- do not create built-in system fields as form fields: `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, `流程标题`. They are platform-generated; only reference supported system fields where a tool explicitly says so, such as button `source_field: "数据ID"`
-
-## 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`
-- 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(package_id=..., apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
-  - every `apps[]` item should carry its own `client_key`, `app_name`, `icon`, `color`, and `add_fields`
-  - same-call relation fields should use `target_app_ref` to point at another `apps[].client_key`; use `target_app` only when the app name is unique and stable, and use `target_app_key` only after the target app already exists or readback has confirmed it
-  - timeout / `partial_success` / `write_executed=true` / `safe_to_retry=false` means `readback_before_retry`; do not directly downgrade to single-app creation
-- 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
-- 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`
-  - chart `filters` use the unified fixed-filter DSL: `field_name + operator + value/values`; the tool compiles them to QingBI string judge types
-  - 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 context matches use `source_field`, static filters use `value`; do not handwrite raw `matchRules`
-  - 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`
-  - do not create platform default/system views named `全部数据`, `我的数据`, `我发起的`, `待办`, `已办`, or `抄送`; they are built in. New views must use business-specific names. To change a built-in view, patch by its existing raw `view_key`
-  - use `builder_tool_contract` whenever the minimal legal shape is unclear
-  - keep view `filters` and `query_conditions` separate: `filters` use `field_name + operator + value/values` and are fixed saved filters; `query_conditions` configure the frontend query panel fields and only take effect after users enter query values
-  - 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. Trust the current MCP/session when it is already injected by the runtime; only run auth/workspace recovery after a tool explicitly reports an auth, credential, or workspace error
-2. Confirm whether the task is read-only or write-impacting
-3. Classify the build scope:
-   - complete system/package -> `package_apply` or `package_get`, then one `app_schema_apply(package_id=..., apps=[...])`
-   - single app -> `app_resolve` / `app_get`, then app-scoped apply tools
-   - record/task/data request -> leave builder and use the matching record/task skill
-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`.
-- Do not perform routine auth probes before every builder action in runtime contexts with injected MCP credentials; recover auth only after an actual auth/workspace failure.
-- 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 bypass package/app-name conflicts by inventing `V2`, `测试`, timestamp, or random suffix apps in a real business package. Read back and decide whether to update the existing app, create only a truly missing app, or ask the user.
-- After any uncertain schema write, do `readback_before_retry` with `package_get` / `app_resolve` / `app_get_fields`; retry only the verified missing or failed slice.
-- Do not use `package_create` or `package_attach_app` as a public default path. If they still appear in low-level code, treat them as internal/legacy implementation details.
-- Do not use raw `portal_*` writes or raw `qingbi_report_*` writes as the default builder strategy.
-- `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, and `app_views_apply` publish by default; `app_custom_buttons_apply` and `app_associated_resources_apply` publish after at least one write succeeds and do not accept a draft-only `publish` parameter; `app_charts_apply` is immediate-live without publish.
-- 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.
-- Do not add platform system fields to `add_fields`; if the user asks for record id, number, applicant, creation/update time, or workflow status, use the built-in data/list/readback fields instead of creating duplicate controls.
-- 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 or may have landed but verification is incomplete. If `write_executed=true`, `safe_to_retry=false`, or readback is unavailable, do `readback_before_retry` before any create retry.
-- 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.
-
-## 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)
-- Single app development guide: [references/single-app-development-guide.md](references/single-app-development-guide.md)
-- Complete system development guide: [references/complete-system-development-guide.md](references/complete-system-development-guide.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)

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

@@ -1,4 +0,0 @@
-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."

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

@@ -1,59 +0,0 @@
-# Complete System Development Guide
-
-Use this when the user asks for a system, app package, workspace module set, or several related apps/forms.
-Do not compress several business objects into one app.
-
-## Recommended Completeness
-
-Required:
-
-- package exists or is created through `package_apply`
-- core business objects are modeled as separate apps
-- all new apps are created in one multi-app `app_schema_apply(package_id=..., apps=[...])`
-- every app has stable `client_key`, `app_name`, `icon`, `color`, and one readable `as_data_title: true`
-- same-call relations use `target_app_ref` to point to another `apps[].client_key`
-- basic operating views exist for each core app
-- package/apps/fields/relations are read back before repair or retry
-
-Strongly recommended:
-
-- cross-app relation fields for the main business links
-- core metric charts and BI charts using semantic `metric`, `metrics`, `group_by`, and `where`
-- a standard portal: business entry area, core metrics, BI charts, then concrete data views
-- portal grid/business-entry sections contain real `config.items[]`, not empty containers
-
-Optional:
-
-- workflow, reminders, buttons, associated resources, sample data, roles, and permissions when the user asks for them or the business process clearly depends on them
-
-## Standard Path
-
-1. Resolve or create package: `package_get` / `package_apply`.
-2. Draft all apps and relations with stable `client_key` values.
-3. Run one multi-app `app_schema_apply` with `apps[]`.
-4. If write result is uncertain, run readback before retrying.
-5. For each app, apply layout and views.
-6. Create charts before portals when the portal needs metrics or BI sections.
-7. Create portal only after referenced apps, views, and charts are known.
-8. Add workflows/buttons/associated resources when they are part of the requested business process.
-
-## Recovery Rules
-
-- Timeout, `partial_success`, `write_executed=true`, `safe_to_retry=false`, or incomplete readback means `write_may_have_succeeded`.
-- Next action is always `readback_before_retry`: read package, resolve intended apps, then read fields/relations.
-- Retry only verified missing apps, fields, or relations.
-- Do not rebuild the system as separate single-app creates.
-- Do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
-
-## Portal Template
-
-- Top area: one business entry grid plus one todo/common/frequent component when useful.
-- Metrics: one row of 4-6 indicator/target cards with portal section `role: "metric"`; recommended height 5.
-- BI charts: one row of 2-3 charts, 1-2 rows; recommended height 7.
-- Data views: one row of 1-2 concrete views, 1-2 rows; recommended height 11.
-
-## Stop Conditions
-
-- If the user only asked for one app, switch to the single-app guide.
-- If required package/app/field/relation readback contradicts the intended model, repair the specific missing slice before building dependent resources.
-- If a public tool cannot express a needed business feature, state the gap and ask before using any fallback or submitting feedback.

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

@@ -1,162 +0,0 @@
-# Create App
-
-Use this when the user wants one new app inside an existing package.
-This playbook follows the current public builder surface, not legacy package helper tools.
-
-Do not use this playbook when the user is really asking for a system/package with multiple forms or modules. In that case:
-
-1. read or create the package through `package_get` / `package_apply`
-2. create the related apps in one `app_schema_apply(package_id=..., apps=[...])` call
-3. keep package ownership on the public `package_id` path instead of a separate attach step
-4. add same-call relation fields with `target_app_ref` when one new app references another new app; use `target_app_key` only after the target app already exists or readback confirms it
-5. choose explicit non-template `icon + color` for each new package/app
-
-Hierarchy reminder:
-
-- package -> app -> field -> relation
-- another business object is another app, not a text field
-
-If creating a brand new package would help, ask the user to confirm package creation first. After confirmation, create it through `package_apply(create_if_missing=true, package_name=...)`.
-
-## Minimal sequence
-
-1. `package_get` if `package_id` is already known; otherwise derive the package from related readback or ask the user for the id
-2. `app_resolve`
-3. `app_schema_apply`
-4. `app_publish_verify` only when the user asks for explicit final verification
-
-## Multi-app systems are different
-
-If the user says things like:
-
-- “创建一个完整应用包”
-- “包含项目、需求、任务、缺陷、团队这几个表单”
-- “这些表单之间建立关联关系”
-
-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 a multi-app system, run one `app_schema_apply` with `package_id` and `apps[]`
-3. use `apps[].client_key` plus relation field `target_app_ref` when one new app references another new app
-
-If that multi-app call times out, returns `partial_success`, returns `write_executed=true`, has `safe_to_retry=false`, or has incomplete readback, do not decide that the create failed. Run `readback_before_retry`: read the package, resolve each intended app by package/name or returned app key, read fields, and retry only verified missing apps or fields. Do not rebuild the same complete system as separate single-app creates, and do not create `V2`, `测试`, timestamp, or random-suffix apps to bypass duplicate names.
-
-## Example
-
-When designing fields, do not add platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`. Qingflow provides them automatically; create only business fields.
-
-Create a new package only after the user confirms package creation:
-
-```json
-{
-  "tool_name": "package_apply",
-  "arguments": {
-    "profile": "default",
-    "package_name": "研发项目管理",
-    "create_if_missing": true,
-    "icon": "briefcase",
-    "color": "azure"
-  }
-}
-```
-
-Read the package when `package_id` is already known:
-
-```json
-{
-  "tool_name": "package_get",
-  "arguments": {
-    "profile": "default",
-    "package_id": 1218950
-  }
-}
-```
-
-Apply schema for a new app:
-
-```json
-{
-  "tool_name": "app_schema_apply",
-  "arguments": {
-    "profile": "default",
-    "app_name": "客户订单",
-    "package_id": 1218950,
-    "icon": "delivery-box-1",
-    "color": "emerald",
-    "create_if_missing": true,
-    "publish": true,
-    "add_fields": [
-      {"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": [{"label": "草稿"}, {"label": "进行中"}, {"label": "已完成"}], "required": true}
-    ],
-    "update_fields": [],
-    "remove_fields": []
-  }
-}
-```
-
-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": "客户",
-        "icon": "business-personalcard",
-        "color": "emerald",
-        "add_fields": [
-          {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
-        ]
-      },
-      {
-        "client_key": "order",
-        "app_name": "订单",
-        "icon": "delivery-box-1",
-        "color": "blue",
-        "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`
-
-Expected on create. Continue with `create_if_missing=true`.
-
-### `CREATE_APP_ROUTE_NOT_FOUND`
-
-The create route did not resolve in the current backend route context. In Wingent Momo runtime, first retry the same `app_schema_apply` after confirming the injected session is still active. Only run `workspace_select` if a business tool explicitly reports a missing or wrong workspace.
-
-### Hierarchy modeling mistake
-
-If the user asked for several named forms/apps but the draft patch turns them into text fields inside one app, stop and remodel the task as:
-
-- one package
-- many apps
-- relation fields between those apps

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

@@ -1,63 +0,0 @@
-# Environment Switching
-
-Use this reference before any builder-side write, repair, or verification flow.
-
-## Step 1: Resolve the active environment
-
-Decide explicitly whether the task targets:
-
-- `test`: build validation, mock data, trial package creation, safe iteration
-- `prod`: formal business system changes in the live environment
-
-If the user did not specify an environment, default to `prod`.
-
-## Test Environment
-
-Use test for:
-
-- first application of a new `SolutionSpec`
-- trying builder apply flows end-to-end with readback verification, or `solution_install` when the user is installing an existing packaged solution
-- package initialization and schema evolution experiments
-- mock data creation, with at least `5` records per relevant entity unless the user asks for fewer
-
-Builder behavior in test:
-
-- `preflight` or `plan` is still preferred, but fast `apply` is acceptable when the user explicitly wants an end-to-end smoke test
-- package creation is acceptable
-- verify should read back apps, views, portal, navigation, and sample records
-
-Known current test backend:
-
-- use an explicitly provided non-production backend
-
-## Production Environment
-
-Use production for:
-
-- changes to real business systems
-- additive modifications to live packages and apps
-- controlled rollout of approved solution specs
-
-Builder behavior in prod:
-
-- always identify the target package or app set before changing anything
-- default to `preflight` or `plan` before any `apply`
-- additive requirements should modify the existing package with ordinary tools by default
-- if creating a new package seems necessary in prod, ask the user to confirm package creation first
-- do not seed mock data unless the user explicitly approves it for production
-- verify is mandatory after writes
-
-Production guardrails:
-
-- restate the target workspace and target package before any write
-- call out whether the action creates, mutates, or deletes builder-side configuration
-- if a safer read-only inspection can answer the request, do that first
-
-## Reporting Rule
-
-For builder work, always report:
-
-- active environment
-- target workspace
-- whether the operation is `plan`, `apply`, `repair`, or `verify`
-- whether it touches an existing package or creates a new one