@qingflow-tech/qingflow-app-builder-mcp 1.0.42 → 1.0.44

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.42
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.44
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.42 qingflow-app-builder-mcp
+npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.44 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.42",
+  "version": "1.0.44",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.0.42"
+version = "1.0.44"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

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

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow App Builder
 
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 ## Overview
 
@@ -93,6 +93,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - 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
+  - for complete systems, submit `upsert_charts` in batches of 4-8. More than 8 upserts is blocked before write with `CHART_UPSERT_BATCH_TOO_LARGE`; execute `details.suggested_batch_payloads[]` one batch at a time.
   - 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
@@ -121,11 +122,13 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - 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`
+  - before building approval/fill/copy flows, make sure the app schema has an explicit business status `select` field such as `状态` / `处理状态` / `审批状态`; do not create platform workflow system fields such as `当前流程状态`
   - 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
+  - keep relation/attachment/subtable/address/Q-Linker/code-block fields out of `query_conditions`; member/department fields may be used as query-panel fields when readback supports them. Use `filters` for fixed filters or associated-resource `match_mappings` for current-record related report/view matching
   - 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`
 
@@ -161,6 +164,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - 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
+9. For complete-system builds, write `tmp/qingflow_system_build_summary.json` before the final response and make the final report match that file
 
 ## Safe Usage Rules
 

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

@@ -11,6 +11,7 @@ Required:
 - 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`
+- no app creates platform system fields such as `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`
 - 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
@@ -22,6 +23,12 @@ Strongly recommended:
 - 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
 
+Workflow preflight:
+
+- If an app will have approval/fill/copy workflow nodes, create an explicit business status `select` field in schema first, such as `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`.
+- Do not create platform workflow system fields such as `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
+- If `app_flow_apply` returns `FLOW_DEPENDENCY_MISSING`, fix schema with the returned `suggested_next_call`, read fields back, then retry the flow. Do not skip the workflow silently.
+
 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
@@ -33,9 +40,66 @@ Optional:
 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.
+6. Create charts before portals when the portal needs metrics or BI sections. Submit chart upserts in batches of 4-8; if `CHART_UPSERT_BATCH_TOO_LARGE` appears, execute `details.suggested_batch_payloads[]` one at a time.
 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.
+9. Before the final response, write the complete-system delivery summary file described below.
+
+## Field Modeling Rules
+
+- Use agent-friendly field types in drafts: `text`, `multiline`, `select`, `multi_select`, `number`, `amount`, `date`, `datetime`, `member`, `department`, `attachment`, `relation`. The tool normalizes aliases such as `multiline -> long_text` and `select -> single_select`.
+- Create only business fields. Do not create platform system fields listed in Required; reference them only where a tool explicitly supports system fields, such as button `source_field: "数据ID"`.
+- Use `number` for ratios, completion rates, scores, percentages, durations, and quantities that may need decimals. Use `amount` only for currency/money semantics. This prevents sample data from producing decimal values for a field that the backend treats as integer money.
+- For select fields, define the option set during schema design. Later sample data must use only those option labels or ids.
+
+## View Query Rules
+
+- Use `filters` for fixed saved filters that apply when the view opens.
+- Use `query_conditions` only for the frontend query panel layout. It is not another filter DSL and it does not express OR.
+- `query_conditions.rows` should contain query-panel fields such as text, long text, number, amount, date/datetime, select, member, department, phone, email, or boolean.
+- Do not put relation, attachment, subtable/subfield, address, Q-Linker, or code-block fields in `query_conditions`.
+- For current-record related views/reports, use `app_associated_resources_apply.match_mappings`, not `query_conditions`.
+
+## Delivery Summary File
+
+For complete-system builds, create or update one local JSON file before the final response:
+
+`tmp/qingflow_system_build_summary.json`
+
+Use this file as the structured source of truth for the final report. Include at least:
+
+```json
+{
+  "package_id": 0,
+  "package_name": "",
+  "portal_dash_key": "",
+  "portal_live_status": "verified | unverified | not_created",
+  "front_end_visible": true,
+  "apps": [
+    {
+      "app_key": "",
+      "app_name": "",
+      "fields_count": 0,
+      "views_count": 0,
+      "flows_count": 0,
+      "charts_count": 0,
+      "publish_verify_status": "verified | unverified | failed"
+    }
+  ],
+  "warnings": [],
+  "partial_items": [],
+  "needs_followup": []
+}
+```
+
+Rules:
+
+- Populate IDs and counts from readback, not from intended payload only.
+- If a required resource is not verified, put it in `partial_items` or `needs_followup` instead of reporting the system as fully complete.
+- If the user later adds a data-entry task, keep that separate from the system-build summary unless the user explicitly wants one combined report.
+- The final response should match this file: completed resources, unverified items, frontend visibility, and follow-up needs must not contradict the JSON.
+- When running from the CLI repo or a test harness, validate the file with:
+  `python scripts/validate_system_build_summary.py tmp/qingflow_system_build_summary.json`.
 
 ## Recovery Rules
 

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

@@ -97,6 +97,9 @@
 - 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 `builder_tool_contract`, read the returned `json_paths` first. Successful contract data is under `$.contract`; `allowed_values` uses flat dotted keys such as `["field.type"]`, not nested objects. Do not read successful field enums from top-level `allowed_values`.
+- For `workspace_icon_catalog_get`, read icon candidates from `$.icon_names` and colors from `$.icon_colors`.
+- For builder apply responses, read returned `json_paths` first. Stable fields are `$.summary` and `$.resources[]`; use `resources[].id/key/name` before legacy top-level fields.
 - 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`

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

@@ -24,6 +24,11 @@ Optional:
 
 - workflow, portal entry, sample data, roles, or visibility changes when requested by the user or clearly needed by the app's job
 
+Workflow preflight:
+
+- If the app will have approval/fill/copy workflow nodes, add one explicit business status `select` field first, such as `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`.
+- Do not create platform workflow system fields: `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
+
 ## Standard Path
 
 1. Read current target: `app_resolve` or `app_get`.
@@ -40,6 +45,12 @@ Optional:
 - Do not create `数据ID`, `编号`, `申请人`, `申请时间`, `创建人`, `创建时间`, `提交人`, `提交时间`, `更新时间`, `更新人`, `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`.
 - Do not create built-in default views such as `全部数据` or `我的数据`; Qingflow provides system views.
 
+## View Query Rules
+
+- `filters` are fixed saved filters; `query_conditions` only configures frontend query-panel fields.
+- Put only query-panel fields in `query_conditions.rows`: text, long text, number, amount, date/datetime, select, member, department, phone, email, or boolean.
+- Do not put relation, attachment, subtable/subfield, address, Q-Linker, or code-block fields in `query_conditions`; use fixed `filters` or associated-resource `match_mappings` instead.
+
 ## Stop Conditions
 
 - If the task actually needs multiple business objects, stop and switch to the complete-system guide.

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

@@ -55,7 +55,7 @@ These execute normalized patches. Some app apply tools publish by default and st
 - `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
+- `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; for complete systems, submit large chart sets in batches of 4-8 upserts. More than 8 upserts is blocked before write with `CHART_UPSERT_BATCH_TOO_LARGE`; execute `details.suggested_batch_payloads[]` one batch at a time.
 - `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.

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

@@ -6,18 +6,19 @@ Use this when the app already exists and the task is only about workflow.
 
 1. `builder_tool_contract(tool_name="app_flow_apply")`
 2. `app_get_fields`
-3. `app_get_flow`
-4. `role_search` or `member_search`
-5. `role_create` if the user wants a reusable directory role and no good role exists
-6. start from a canonical preset when possible
-7. patch the skeleton instead of freehanding a full graph
-8. reuse preset node ids when patching:
+3. Confirm the app has one explicit business status field, usually a `select` named `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`
+4. `app_get_flow`
+5. `role_search` or `member_search`
+6. `role_create` if the user wants a reusable directory role and no good role exists
+7. start from a canonical preset when possible
+8. patch the skeleton instead of freehanding a full graph
+9. reuse preset node ids when patching:
    - `basic_approval` -> patch `approve_1`
    - `basic_fill_then_approve` -> patch `fill_1` and `approve_1`
    Do not add a second approval/fill node with a new id unless you are intentionally replacing the skeleton.
    The MCP now auto-aligns the simplest single-node preset overrides, but still prefer explicit preset ids so the merged graph stays predictable.
-9. `app_flow_apply`
-10. `app_get_flow` when apply returns `partial_success` or the user asked for verification
+10. `app_flow_apply`
+11. `app_get_flow` when apply returns `partial_success` or the user asked for verification
 
 If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
 
@@ -96,7 +97,18 @@ Preferred fix order:
 
 ### `FLOW_DEPENDENCY_MISSING`
 
-The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
+The workflow depends on fields that do not exist yet, usually an explicit business status field. Fix schema first.
+
+Do:
+
+- add a business field such as `状态`, `处理状态`, `审批状态`, `工单状态`, or `流程阶段`
+- use type `select` / `single_select`
+- use business options such as `草稿`, `进行中`, `已完成`
+
+Do not:
+
+- create platform workflow system fields such as `当前流程状态`, `当前处理人`, `当前处理节点`, or `流程标题`
+- skip the flow and still report workflow completion
 
 Preferred recovery:
 

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

@@ -272,7 +272,32 @@ At least one `query_conditions.rows` field does not exist on the app.
 
 ### `INVALID_QUERY_CONDITION_FIELD`
 
-The field exists but cannot be used in the frontend query-condition panel, such as attachment, relation, Q-Linker, code block, location/address, or subtable/subfield selections.
+The field exists but cannot be used in the frontend query-condition panel.
+
+Supported `query_conditions.rows` fields are query-panel fields:
+
+- text / long text
+- number / amount
+- date / datetime
+- single select / multi select
+- member / department
+- phone / email
+- boolean
+
+Do not use these fields in `query_conditions`:
+
+- relation
+- attachment
+- subtable or subtable subfield
+- address/location
+- Q-Linker
+- code block
+
+Fix path:
+
+- If you wanted a saved filter that opens with the view, use `filters`.
+- If you wanted a related report/view to match the current record, use `app_associated_resources_apply.match_mappings`.
+- If you only need frontend search fields, remove unsupported fields from `query_conditions.rows` and keep query-panel supported fields only.
 
 ## Notes
 
@@ -281,6 +306,6 @@ The field exists but cannot be used in the frontend query-condition panel, such
 - `app_get_views` should be treated as canonical readback and now returns `columns`
 - If `app_views_apply` returns `AMBIGUOUS_VIEW`, stop and re-run `app_get_views`; then retry with the exact `view_key`
 - `filters` are ANDed together as one flat condition group
-- `query_conditions.rows` does not mean OR; it controls frontend query-field layout
+- `query_conditions.rows` does not mean OR; it controls frontend query-field layout and should only contain query-panel supported fields
 - `app_views_apply` publishes by default
 - For select-style filters, success means the backend preserved the option value in readback, not just that the view name now exists

package/skills/qingflow-app-builder/scripts/validate_system_build_summary.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+VALID_PORTAL_STATUSES = {"verified", "unverified", "not_created"}
+VALID_APP_VERIFY_STATUSES = {"verified", "unverified", "failed"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate a Qingflow complete-system delivery summary JSON file.")
+    parser.add_argument("summary_file", nargs="?", default="tmp/qingflow_system_build_summary.json")
+    args = parser.parse_args(argv)
+    path = Path(args.summary_file)
+    issues = validate_summary_file(path)
+    if issues:
+        _emit({"status": "failed", "error_code": "SYSTEM_BUILD_SUMMARY_INVALID", "path": str(path), "issues": issues})
+        return 1
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    _emit(
+        {
+            "status": "success",
+            "path": str(path),
+            "summary": {
+                "package_id": payload.get("package_id"),
+                "package_name": payload.get("package_name"),
+                "portal_dash_key": payload.get("portal_dash_key"),
+                "portal_live_status": payload.get("portal_live_status"),
+                "app_count": len(payload.get("apps") or []),
+                "partial_count": len(payload.get("partial_items") or []),
+                "needs_followup_count": len(payload.get("needs_followup") or []),
+            },
+        }
+    )
+    return 0
+
+
+def validate_summary_file(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return [_issue("MISSING_FILE", "$", f"summary file does not exist: {path}")]
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        return [_issue("READ_FAILED", "$", str(exc))]
+    except json.JSONDecodeError as exc:
+        return [_issue("INVALID_JSON", "$", exc.msg)]
+    if not isinstance(payload, dict):
+        return [_issue("INVALID_ROOT", "$", "summary root must be a JSON object")]
+
+    issues: list[dict[str, Any]] = []
+    _require_positive_int(payload, "package_id", issues)
+    _require_nonempty_string(payload, "package_name", issues)
+    _require_bool(payload, "front_end_visible", issues)
+    _require_string_enum(payload, "portal_live_status", VALID_PORTAL_STATUSES, issues)
+    if payload.get("portal_live_status") == "verified":
+        _require_nonempty_string(payload, "portal_dash_key", issues)
+    elif "portal_dash_key" in payload and payload.get("portal_dash_key") is not None and not isinstance(payload.get("portal_dash_key"), str):
+        issues.append(_issue("INVALID_TYPE", "$.portal_dash_key", "portal_dash_key must be a string when present"))
+
+    apps = payload.get("apps")
+    if not isinstance(apps, list) or not apps:
+        issues.append(_issue("INVALID_APPS", "$.apps", "apps must be a non-empty array"))
+    else:
+        for index, app in enumerate(apps):
+            prefix = f"$.apps[{index}]"
+            if not isinstance(app, dict):
+                issues.append(_issue("INVALID_APP_ITEM", prefix, "app item must be an object"))
+                continue
+            _require_nonempty_string(app, "app_key", issues, prefix)
+            _require_nonempty_string(app, "app_name", issues, prefix)
+            for key in ("fields_count", "views_count", "flows_count", "charts_count"):
+                _require_nonnegative_int(app, key, issues, prefix)
+            _require_string_enum(app, "publish_verify_status", VALID_APP_VERIFY_STATUSES, issues, prefix)
+
+    for key in ("warnings", "partial_items", "needs_followup"):
+        if not isinstance(payload.get(key), list):
+            issues.append(_issue("INVALID_TYPE", f"$.{key}", f"{key} must be an array"))
+    return issues
+
+
+def _require_positive_int(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a positive integer"))
+
+
+def _require_nonnegative_int(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a non-negative integer"))
+
+
+def _require_nonempty_string(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a non-empty string"))
+
+
+def _require_bool(payload: dict[str, Any], key: str, issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    if not isinstance(payload.get(key), bool):
+        issues.append(_issue("INVALID_TYPE", f"{prefix}.{key}", f"{key} must be a boolean"))
+
+
+def _require_string_enum(payload: dict[str, Any], key: str, allowed: set[str], issues: list[dict[str, Any]], prefix: str = "$") -> None:
+    value = payload.get(key)
+    if value not in allowed:
+        issues.append(_issue("INVALID_VALUE", f"{prefix}.{key}", f"{key} must be one of {sorted(allowed)}"))
+
+
+def _issue(code: str, path: str, message: str) -> dict[str, Any]:
+    return {"code": code, "path": path, "message": message}
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -7,7 +7,7 @@ metadata:
 
 # Qingflow App Builder Code Integrations
 
-> **Skill 版本**：`qingflow-skills-2026.06.23.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+> **Skill 版本**：`qingflow-skills-2026.06.24.1`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
 
 Use this skill when the user wants to build or repair:
 - `code_block` fields

package/src/qingflow_mcp/builder_facade/service.py

@@ -101,6 +101,7 @@ from .models import (
 )
 
 BUILDER_PORTAL_LIST_DETAIL_VERIFY_LIMIT = 50
+CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE = 8
 
 
 QUESTION_TYPE_TO_FIELD_TYPE: dict[int, str] = {
@@ -186,6 +187,37 @@ QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES = {
     FieldType.relation.value,
     FieldType.subtable.value,
 }
+QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES_PUBLIC = sorted(
+    {
+        "address",
+        "attachment",
+        "code_block",
+        "q_linker",
+        "relation",
+        "subtable",
+    }
+)
+QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC = sorted(
+    {
+        "text",
+        "long_text",
+        "number",
+        "amount",
+        "date",
+        "datetime",
+        "single_select",
+        "multi_select",
+        "phone",
+        "email",
+        "boolean",
+        "member",
+        "department",
+    }
+)
+QUERY_CONDITION_FIX_HINT = (
+    "Remove this field from query_conditions. query_conditions only configures the frontend query panel for supported query fields. "
+    "Use filters for fixed saved filters, and use associated-resource match_mappings for current-record relation/report matching."
+)
 
 ASSOCIATED_RESOURCE_LIMIT_TYPE_ALL = 1
 ASSOCIATED_RESOURCE_LIMIT_TYPE_SELECT = 2
@@ -4378,7 +4410,7 @@ class AiBuilderFacade:
                 "details": {"edit_version_no": None, "associated_item_ids_by_client_key": client_key_to_id, "readback_failed": False},
                 "request_id": None,
                 "suggested_next_call": None,
-                "noop": True,
+                "noop": False,
                 "warnings": [],
                 "verification": {"associated_resources_verified": True, "associated_resource_view_configs_verified": True, "readback_loaded": True, "published": False},
                 "verified": True,
@@ -7511,7 +7543,12 @@ class AiBuilderFacade:
                     "nodes": public_nodes,
                     "transitions": transitions,
                 },
-                details={"missing_dependencies": ["status field"]},
+                details={
+                    "missing_dependencies": ["status field"],
+                    "fix_hint": "Add an explicit business status select field before applying approval workflows. Do not create platform system fields such as 当前流程状态.",
+                    "recommended_field_names": ["状态", "处理状态", "审批状态", "工单状态", "流程阶段"],
+                    "forbidden_system_field_names": ["当前流程状态", "当前处理人", "当前处理节点", "流程标题"],
+                },
                 missing_fields=["status"],
                 suggested_next_call={
                     "tool_name": "app_schema_apply",
@@ -7519,7 +7556,7 @@ class AiBuilderFacade:
                         "profile": profile,
                         "app_key": request.app_key,
                         "create_if_missing": False,
-                        "add_fields": [{"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": True}],
+                        "add_fields": [{"name": "状态", "type": "select", "options": ["草稿", "进行中", "已完成"], "required": True}],
                         "update_fields": [],
                         "remove_fields": [],
                     },
@@ -8266,7 +8303,16 @@ class AiBuilderFacade:
         relation_field_count = _count_relation_fields(current_fields)
         relation_limit_verified = relation_field_count <= 1
         relation_warnings = (
-            [_warning("RELATION_FIELD_LIMIT_RISK", "multiple relation fields are not a stable backend capability", relation_field_count=relation_field_count)]
+            [
+                _warning(
+                    "RELATION_FIELD_LIMIT_RISK",
+                    "multiple relation fields were written and verified, but this backend capability can be unstable; do not downgrade to text unless the write fails or relation readback mismatches",
+                    severity="warning",
+                    relation_field_count=relation_field_count,
+                    relation_fields_created=True,
+                    do_not_downgrade_to_text_unless_apply_failed=True,
+                )
+            ]
             if not relation_limit_verified
             else []
         )
@@ -8397,6 +8443,8 @@ class AiBuilderFacade:
                         "app_key": target.app_key,
                         "field_diff": {"added": added, "updated": updated, "removed": removed},
                         "relation_field_count": relation_field_count,
+                        "relation_fields_created": False,
+                        "recommended_modeling_fallback": "Keep the primary relation field as relation; use text/reference summary fields only for secondary cross-object links, and report the downgrade as partial.",
                         "transport_error": {
                             "http_status": api_error.http_status,
                             "backend_code": api_error.backend_code,
@@ -10154,6 +10202,12 @@ class AiBuilderFacade:
                             "backend_code": api_error.backend_code,
                             "category": api_error.category,
                         },
+                        **_view_apply_failure_diagnostics(
+                            patch=patch,
+                            current_fields_by_name=current_fields_by_name,
+                            backend_code=api_error.backend_code,
+                            operation_phase=operation_phase,
+                        ),
                     },
                 }
                 failed_views.append(failure_entry)
@@ -11224,6 +11278,56 @@ class AiBuilderFacade:
             normalized_args["upsert_charts"] = [patch.model_dump(mode="json") for patch in upsert_charts]
             normalized_args["patch_results"] = patch_results
 
+        if len(upsert_charts) > CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE:
+            batching_context = _chart_apply_batching_context(
+                request=request,
+                upsert_charts=upsert_charts,
+                batch_size=CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE,
+            )
+            first_batch = batching_context["suggested_batch_payloads"][0]
+            return finalize({
+                "status": "failed",
+                "error_code": "CHART_UPSERT_BATCH_TOO_LARGE",
+                "recoverable": True,
+                "message": (
+                    f"upsert_charts contains {len(upsert_charts)} items; split into batches of "
+                    f"{CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE} or fewer before writing"
+                ),
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
+                "details": batching_context,
+                "request_id": None,
+                "suggested_next_call": {"tool_name": "app_charts_apply", "arguments": {"profile": profile, **first_batch}},
+                "backend_code": None,
+                "http_status": None,
+                "noop": False,
+                "warnings": [
+                    _warning(
+                        "CHART_UPSERT_BATCH_SIZE_BLOCKED",
+                        "large chart upsert batches are blocked before write to avoid timeout and unknown write state",
+                        upsert_count=len(upsert_charts),
+                        max_upsert_count=CHART_APPLY_RECOMMENDED_UPSERT_BATCH_SIZE,
+                    )
+                ],
+                "verification": {
+                    "charts_verified": False,
+                    "readback_unavailable": False,
+                    "readback_before_retry": False,
+                    "chart_delete_readback_results": [],
+                    "chart_order_verified": True,
+                    "chart_list_source": existing_chart_list_source,
+                },
+                "app_key": app_key,
+                "app_name": app_name,
+                "chart_results": [],
+                "verified": False,
+                "write_executed": False,
+                "write_succeeded": False,
+                "safe_to_retry": True,
+                "next_action": "split_upsert_charts_and_retry",
+            })
+
         chart_results: list[dict[str, Any]] = []
         created_ids: list[str] = []
         updated_ids: list[str] = []
@@ -11510,6 +11614,15 @@ class AiBuilderFacade:
             primary_failure = failed_items[0]
             primary_error_code = str(primary_failure.get("error_code") or "").strip()
             primary_message = str(primary_failure.get("message") or "").strip()
+            retry_context = _chart_apply_retry_context(
+                request=request,
+                failed_items=failed_items,
+                created_ids=created_ids,
+                updated_ids=updated_ids,
+                removed_ids=removed_ids,
+                reordered=reordered,
+                write_executed=write_executed,
+            )
             return finalize({
                 "status": "partial_success" if successful_changes else "failed",
                 "error_code": "CHART_APPLY_PARTIAL" if successful_changes else primary_error_code or "CHART_APPLY_FAILED",
@@ -11520,6 +11633,7 @@ class AiBuilderFacade:
                 "allowed_values": {"chart.chart_type": [member.value for member in PublicChartType], "chart.filter.operator": [member.value for member in ViewFilterOperator]},
                 "details": {
                     "per_chart_results": chart_results,
+                    **retry_context,
                     **({"readback_error": _transport_error_payload(readback_error)} if readback_error is not None else {}),
                 },
                 "request_id": failed_items[0].get("request_id") or (readback_error.request_id if readback_error is not None else None),
@@ -11536,6 +11650,7 @@ class AiBuilderFacade:
                 "verification": {
                     "charts_verified": False if failed_items else verified,
                     "readback_unavailable": any_readback_unavailable,
+                    "readback_before_retry": bool(write_executed),
                     "chart_delete_readback_results": [deepcopy(item) for item in chart_results if item.get("operation") == "delete"],
                     "chart_order_verified": False if request.reorder_chart_ids else True,
                     "chart_list_source": readback_list_source or existing_chart_list_source,
@@ -11546,6 +11661,7 @@ class AiBuilderFacade:
                 "verified": False if failed_items else verified,
                 "write_executed": write_executed,
                 "write_succeeded": write_succeeded,
+                **({"write_may_have_succeeded": True, "next_action": "readback_before_retry"} if write_executed else {}),
                 "safe_to_retry": not write_executed,
             })
         result_verified = verified or noop
@@ -15682,6 +15798,155 @@ def _public_chart_filter_groups_from_qingbi_config(config: dict[str, Any]) -> li
     return groups
 
 
+def _chart_apply_retry_context(
+    *,
+    request: ChartApplyRequest,
+    failed_items: list[dict[str, Any]],
+    created_ids: list[str],
+    updated_ids: list[str],
+    removed_ids: list[str],
+    reordered: bool,
+    write_executed: bool,
+) -> dict[str, Any]:
+    failed_chart_names = [
+        str(item.get("name") or "").strip()
+        for item in failed_items
+        if str(item.get("name") or "").strip()
+    ]
+    failed_delete_ids = [
+        str(item.get("chart_id") or "").strip()
+        for item in failed_items
+        if str(item.get("operation") or "") == "delete" and str(item.get("chart_id") or "").strip()
+    ]
+    reorder_failed = any(str(item.get("operation") or "") == "reorder" for item in failed_items)
+    failed_name_set = set(failed_chart_names)
+    retry_payload: dict[str, Any] = {"app_key": request.app_key}
+    retry_upserts = [
+        patch.model_dump(mode="json", exclude_none=True)
+        for patch in request.upsert_charts
+        if patch.name in failed_name_set
+    ]
+    if retry_upserts:
+        retry_payload["upsert_charts"] = retry_upserts
+    if failed_delete_ids:
+        retry_payload["remove_chart_ids"] = failed_delete_ids
+    if reorder_failed and request.reorder_chart_ids:
+        retry_payload["reorder_chart_ids"] = list(request.reorder_chart_ids)
+    has_retry_payload = any(key in retry_payload for key in ("upsert_charts", "remove_chart_ids", "reorder_chart_ids"))
+    context: dict[str, Any] = {
+        "created_chart_ids": list(created_ids),
+        "updated_chart_ids": list(updated_ids),
+        "removed_chart_ids": list(removed_ids),
+        "failed_chart_names": failed_chart_names,
+        "failed_delete_chart_ids": failed_delete_ids,
+        "readback_first": bool(write_executed),
+        "retry_rule": (
+            "read app charts before retrying; retry only the failed chart payloads if they are still missing or unverified"
+            if write_executed
+            else "fix the failed chart payloads and retry only those items"
+        ),
+    }
+    if has_retry_payload:
+        context["suggested_retry_payload"] = retry_payload
+    return context
+
+
+def _chart_apply_batching_context(
+    *,
+    request: ChartApplyRequest,
+    upsert_charts: list[ChartUpsertPatch],
+    batch_size: int,
+) -> dict[str, Any]:
+    suggested_batch_payloads: list[dict[str, Any]] = []
+    for start in range(0, len(upsert_charts), batch_size):
+        batch = upsert_charts[start : start + batch_size]
+        suggested_batch_payloads.append(
+            {
+                "app_key": request.app_key,
+                "upsert_charts": [patch.model_dump(mode="json", exclude_none=True) for patch in batch],
+            }
+        )
+
+    followup_payload: dict[str, Any] = {"app_key": request.app_key}
+    if request.remove_chart_ids:
+        followup_payload["remove_chart_ids"] = list(request.remove_chart_ids)
+    if request.reorder_chart_ids:
+        followup_payload["reorder_chart_ids"] = list(request.reorder_chart_ids)
+    if len(followup_payload) > 1:
+        suggested_batch_payloads.append(followup_payload)
+
+    return {
+        "upsert_count": len(upsert_charts),
+        "max_upsert_count": batch_size,
+        "write_executed": False,
+        "readback_first": False,
+        "retry_rule": "run suggested_batch_payloads one at a time; do not submit the original large upsert_charts array",
+        "suggested_batch_payloads": suggested_batch_payloads,
+    }
+
+
+def _view_apply_failure_diagnostics(
+    *,
+    patch: ViewUpsertPatch,
+    current_fields_by_name: dict[str, dict[str, Any]],
+    backend_code: Any,
+    operation_phase: str,
+) -> dict[str, Any]:
+    references: list[tuple[str, str]] = []
+
+    def add_reference(name: Any, source: str) -> None:
+        text = str(name or "").strip()
+        if text:
+            references.append((text, source))
+
+    for column in patch.columns:
+        add_reference(column, "columns")
+    add_reference(patch.group_by, "group_by")
+    add_reference(patch.start_field, "start_field")
+    add_reference(patch.end_field, "end_field")
+    add_reference(patch.title_field, "title_field")
+    for rule in patch.filters:
+        add_reference(rule.field_name, "filters")
+
+    seen: set[str] = set()
+    field_entries: list[dict[str, Any]] = []
+    for field_name, source in references:
+        key = f"{field_name}\0{source}"
+        if key in seen:
+            continue
+        seen.add(key)
+        field = current_fields_by_name.get(field_name) or {}
+        field_entries.append(
+            {
+                "field_name": field_name,
+                "source": source,
+                "field_id": field.get("field_id"),
+                "que_id": field.get("que_id"),
+                "field_type": field.get("type"),
+                "que_type": field.get("que_type"),
+                "exists_in_schema": bool(field),
+            }
+        )
+    diagnostics: dict[str, Any] = {
+        "operation_phase": operation_phase,
+        "field_level_diagnostics": field_entries,
+    }
+    if backend_code_value_int(backend_code) == 40038:
+        diagnostics.update(
+            {
+                "suspected_fields": field_entries,
+                "recovery_hint": "Do not delete app fields or recreate the app. First retry the view with the smallest required columns; then add non-critical columns back one by one.",
+                "recommended_minimal_retry": {
+                    "name": patch.name,
+                    "type": patch.type.value,
+                    "columns": [field_entries[0]["field_name"]] if field_entries else [],
+                    **({"filters": [rule.model_dump(mode="json", exclude_none=True) for rule in patch.filters]} if patch.filters else {}),
+                },
+            }
+        )
+    return diagnostics
+
+
 def _public_chart_group_by_from_qingbi_config(config: dict[str, Any]) -> list[str]:
     fields: list[dict[str, Any]] = []
     for key in ("selectedDimensions", "xDimensions", "yDimensions", "selectedTime"):
@@ -23737,6 +24002,9 @@ def _resolve_query_condition_field(
                 "field": raw,
                 "parent_field": subfield_parent.get("name"),
                 "message": "subtable subfields cannot be used as view query conditions",
+                "fix_hint": QUERY_CONDITION_FIX_HINT,
+                "supported_field_types": QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC,
+                "unsupported_field_types": QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES_PUBLIC,
             }
         return {}, {
             "error_code": "QUERY_CONDITION_FIELD_NOT_FOUND",
@@ -23753,6 +24021,9 @@ def _resolve_query_condition_field(
             "field": field.get("name"),
             "field_type": field_type,
             "message": "this field type is not supported by the frontend query condition panel",
+            "fix_hint": QUERY_CONDITION_FIX_HINT,
+            "supported_field_types": QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC,
+            "unsupported_field_types": QUERY_CONDITION_UNSUPPORTED_FIELD_TYPES_PUBLIC,
         }
     que_id = _coerce_positive_int(field.get("que_id"))
     if que_id is None:
@@ -23762,6 +24033,8 @@ def _resolve_query_condition_field(
             "missing_fields": [],
             "field": field.get("name"),
             "message": "query condition field has no backend queId",
+            "fix_hint": QUERY_CONDITION_FIX_HINT,
+            "supported_field_types": QUERY_CONDITION_SUPPORTED_FIELD_TYPES_PUBLIC,
         }
     return field, None
 

package/src/qingflow_mcp/cli/main.py

@@ -9,7 +9,7 @@ from ..errors import QingflowApiError, backend_code_value_int, message_looks_lik
 from ..public_surface import cli_public_tool_spec_from_namespace
 from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
 from ..tools.ai_builder_tools import _attach_builder_apply_envelope
-from ..version import get_cli_version
+from ..version import get_cli_version, get_cli_version_info
 from .context import CliContext, build_cli_context
 from .formatters import emit_json_result, emit_text_result
 from .commands import register_all_commands
@@ -120,12 +120,11 @@ def run(
 
 
 def _handle_version(_args: argparse.Namespace, _context: CliContext) -> dict[str, Any]:
-    version = get_cli_version()
+    info = get_cli_version_info()
     return {
         "ok": True,
         "status": "success",
-        "version": version,
-        "package": "@qingflow-tech/qingflow-cli",
+        **info,
     }
 
 
@@ -136,8 +135,7 @@ def _emit_version(*, json_mode: bool, stdout: TextIO) -> int:
             {
                 "ok": True,
                 "status": "success",
-                "version": version,
-                "package": "@qingflow-tech/qingflow-cli",
+                **get_cli_version_info(),
             },
             stream=stdout,
         )

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -631,15 +631,16 @@ class AiBuilderTools(ToolBase):
                 "allowed_values": {"tool_name": public_tool_names},
                 "details": {"reason_path": "tool_name"},
                 "suggested_next_call": None,
-            "request_id": None,
-            "backend_code": None,
-            "http_status": None,
-            "noop": False,
-            "warnings": [],
-            "verification": {},
-            "verified": False,
-        }
+                "request_id": None,
+                "backend_code": None,
+                "http_status": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {},
+                "verified": False,
+            }
         contract = _builder_contract_with_apply_output(lookup_name, contract)
+        contract_summary = _builder_tool_contract_summary(lookup_name, contract)
         return {
             "status": "success",
             "error_code": None,
@@ -658,6 +659,8 @@ class AiBuilderTools(ToolBase):
             "verification": {},
             "verified": True,
             "tool_name": requested,
+            "summary": contract_summary,
+            "json_paths": contract_summary["json_paths"],
             "contract": contract,
         }
 
@@ -680,6 +683,12 @@ class AiBuilderTools(ToolBase):
             "color_count": len(catalog["icon_colors"]),
             "warnings": [],
             "verification": {"source": "backend AiBuildConstant ICON_NAMES/ICON_COLORS"},
+            "json_paths": {
+                "icon_names": "$.icon_names",
+                "icon_colors": "$.icon_colors",
+                "generic_icon_names": "$.generic_icon_names",
+                "common_examples": "$.common_examples",
+            },
         }
 
     @tool_cn_name("分组创建")
@@ -3927,11 +3936,58 @@ def _builder_contract_with_apply_output(tool_name: str, contract: JSONObject) ->
         "schema_version": BUILDER_APPLY_SCHEMA_VERSION,
         "preferred_ui_fields": ["operation", "summary", "resources"],
         "resource_fields": ["resource_type", "operation", "status", "id", "key", "name", "ids", "parent", "icon_config", "error_code", "message"],
+        "json_paths": _builder_apply_json_paths(),
         "legacy_fields_preserved": True,
     }
     return public
 
 
+def _builder_tool_contract_summary(tool_name: str, contract: JSONObject) -> JSONObject:
+    allowed_values = contract.get("allowed_values") if isinstance(contract, dict) else {}
+    allowed_values_keys = sorted(str(key) for key in allowed_values) if isinstance(allowed_values, dict) else []
+    return {
+        "tool_name": tool_name,
+        "contract_path": "$.contract",
+        "allowed_keys_path": "$.contract.allowed_keys",
+        "allowed_values_path": "$.contract.allowed_values",
+        "allowed_values_key_style": "flat_dotted_keys",
+        "minimal_example_path": "$.contract.minimal_example",
+        "execution_notes_path": "$.contract.execution_notes",
+        "top_level_allowed_values_usage": "empty on successful contract lookup; use $.contract.allowed_values instead",
+        "allowed_values_keys_sample": allowed_values_keys[:12],
+        "json_paths": {
+            "contract": "$.contract",
+            "allowed_keys": "$.contract.allowed_keys",
+            "allowed_values": "$.contract.allowed_values",
+            "minimal_example": "$.contract.minimal_example",
+            "execution_notes": "$.contract.execution_notes",
+            "aliases": "$.contract.aliases",
+        },
+    }
+
+
+def _builder_apply_json_paths() -> JSONObject:
+    return {
+        "status": "$.status",
+        "schema_version": "$.schema_version",
+        "operation": "$.operation",
+        "summary": "$.summary",
+        "resources": "$.resources",
+        "warnings": "$.warnings",
+        "verification": "$.verification",
+        "details": "$.details",
+        "write_executed": "$.write_executed",
+        "write_may_have_succeeded": "$.write_may_have_succeeded",
+        "safe_to_retry": "$.safe_to_retry",
+        "next_action": "$.next_action",
+        "summary_write_executed": "$.summary.write_executed",
+        "summary_safe_to_retry": "$.summary.safe_to_retry",
+        "resource_keys": "$.resources[].key",
+        "resource_ids": "$.resources[].id",
+        "resource_statuses": "$.resources[].status",
+    }
+
+
 def _attach_builder_apply_envelope(tool_name: str, payload: JSONObject) -> JSONObject:
     if not isinstance(payload, dict):
         return payload
@@ -3940,6 +3996,7 @@ def _attach_builder_apply_envelope(tool_name: str, payload: JSONObject) -> JSONO
     payload["operation"] = tool_name
     payload["resources"] = resources
     payload["summary"] = _builder_apply_summary(payload, resources)
+    payload["json_paths"] = _builder_apply_json_paths()
     return payload
 
 
@@ -5768,12 +5825,13 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
         },
         "dependency_hints": [
-            "approval-style workflows require an explicit status field",
+            "approval-style workflows require an explicit business status select field before app_flow_apply, such as 状态 / 处理状态 / 审批状态 / 工单状态",
             "approve/fill/copy nodes require at least one assignee",
         ],
         "execution_notes": [
             "public flow building is intentionally limited to linear workflows",
             "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
+            "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
         ],
         "minimal_example": {
             "profile": "default",
@@ -5808,13 +5866,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
         },
         "dependency_hints": [
-            "approval-style workflows require an explicit status field",
+            "approval-style workflows require an explicit business status select field before app_flow_apply, such as 状态 / 处理状态 / 审批状态 / 工单状态",
             "approve/fill/copy nodes require at least one assignee",
         ],
         "execution_notes": [
             "public flow building is intentionally limited to linear workflows",
             "app_flow_apply is replace-only; do not treat node snippets as partial patches",
             "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
+            "do not create platform system workflow fields such as 当前流程状态 / 当前处理人 / 当前处理节点 / 流程标题; use an explicit business status field instead",
             "workflow verification only covers linear node structure in the public tool surface",
         ],
         "minimal_example": {
@@ -5894,7 +5953,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "creating a new view follows backend createViewgraphConfig and requires both ViewManagementAuth and DataManageAuth; updating/deleting existing views only requires ViewManagementAuth",
             "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
-            "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
+            "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
+            "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
             "use patch_views for partial parameter replacement on existing views; the tool reads current config, merges patch_views[].set/unset, then submits the backend full-save payload internally",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
@@ -5945,6 +6005,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             ],
             "remove_views": [],
         },
+        "query_conditions_field_rules": {
+            "supported_field_types": ["text", "long_text", "number", "amount", "date", "datetime", "single_select", "multi_select", "phone", "email", "boolean", "member", "department"],
+            "unsupported_field_types": ["relation", "attachment", "subtable", "address", "code_block", "q_linker"],
+            "use_instead": {
+                "fixed_filter": "filters",
+                "current_record_related_report_or_view": "app_associated_resources_apply.match_mappings",
+            },
+        },
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -6024,7 +6092,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "buttons omitted preserves existing button config; buttons=[] clears all buttons; buttons=[...] replaces the full button config",
             "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
-            "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
+            "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
+            "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
             "use patch_views for partial parameter replacement on existing views; the public update mode is patch even though the backend save is still a full view payload",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
@@ -6078,6 +6147,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             ],
             "remove_views": [],
         },
+        "query_conditions_field_rules": {
+            "supported_field_types": ["text", "long_text", "number", "amount", "date", "datetime", "single_select", "multi_select", "phone", "email", "boolean", "member", "department"],
+            "unsupported_field_types": ["relation", "attachment", "subtable", "address", "code_block", "q_linker"],
+            "use_instead": {
+                "fixed_filter": "filters",
+                "current_record_related_report_or_view": "app_associated_resources_apply.match_mappings",
+            },
+        },
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",

package/src/qingflow_mcp/version.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 import json
+import re
+import shutil
+import sys
 from importlib import metadata
 from pathlib import Path
 
@@ -15,7 +18,31 @@ def get_cli_version() -> str:
         return "0+local"
 
 
+def get_cli_version_info() -> dict[str, str | None]:
+    package_root = _find_package_root()
+    return {
+        "version": get_cli_version(),
+        "package": _find_package_name(package_root) or "@qingflow-tech/qingflow-cli",
+        "executable_path": _resolve_executable_path(),
+        "command_path": shutil.which("qingflow"),
+        "package_root": str(package_root) if package_root is not None else None,
+        "skill_version": _find_skill_version(package_root),
+    }
+
+
 def _find_package_json_version() -> str | None:
+    package_root = _find_package_root()
+    if package_root is None:
+        return None
+    try:
+        payload = json.loads((package_root / "package.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    version = str(payload.get("version") or "")
+    return version or None
+
+
+def _find_package_root() -> Path | None:
     current = Path(__file__).resolve()
     for parent in current.parents:
         package_json = parent / "package.json"
@@ -36,5 +63,48 @@ def _find_package_json_version() -> str | None:
             "@josephyan/qingflow-app-user-mcp",
             "@josephyan/qingflow-app-builder-mcp",
         }:
-            return version
+            return parent
+    return None
+
+
+def _find_package_name(package_root: Path | None) -> str | None:
+    if package_root is None:
+        return None
+    try:
+        payload = json.loads((package_root / "package.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    name = str(payload.get("name") or "")
+    return name or None
+
+
+def _resolve_executable_path() -> str | None:
+    if not sys.argv:
+        return None
+    raw = str(sys.argv[0] or "").strip()
+    if not raw:
+        return None
+    try:
+        return str(Path(raw).resolve())
+    except OSError:
+        return raw
+
+
+def _find_skill_version(package_root: Path | None) -> str | None:
+    if package_root is None:
+        return None
+    candidates = [
+        package_root / "skills" / "qingflow-cli" / "SKILL.md",
+        package_root / "skill" / "qingflow-cli" / "SKILL.md",
+    ]
+    for skill_file in candidates:
+        if not skill_file.exists():
+            continue
+        try:
+            text = skill_file.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        match = re.search(r"Skill\s*版本\**[:：]\s*`?([^`\s）)]+)", text)
+        if match:
+            return match.group(1).strip()
     return None