@josephyan/qingflow-app-builder-mcp 1.1.4 → 1.1.6

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

@@ -28,17 +28,18 @@ Canonical rules before any example:
 - Always use `columns`
 - Do not emit `column_names`
 - Treat `fields` only as a legacy alias the MCP may normalize, not as the preferred shape
-- Use `filters` with canonical keys `field_name`, `operator`, `value`/`values`
+- Use `filters` with the unified fixed-filter DSL: `field_name`, `operator`, `value`/`values`; do not write raw `judgeType` / `judgeValues`
 - Use `query_conditions` for the frontend query panel. Do not put query-panel fields into `filters`.
-- When creating any new table or card view, always include `query_conditions` with `enabled: true`. In `rows`, list the fields users would most commonly search by — typically the data-title field, any status/type select fields, date fields, and member fields. Do not omit `query_conditions` or leave `rows` empty on a new view.
+- Do not create views named `全部数据`, `我的数据`, `我发起的`, `待办`, `已办`, or `抄送`. These are built-in default/system views. New views must use business-specific names such as `订单台账视图`, `客户跟进视图`, or `逾期任务看板`.
+- To change a built-in default/system view, first read the existing raw `view_key` from `app_get.views` or `app_get_views`, then use `patch_views` or a full `upsert_views` item with that `view_key`.
 - New views created by `app_views_apply` default the frontend associated report/view area to visible with `limit_type="all"`. Existing views preserve their current associated-resource display unless `associated_resources` is explicitly patched.
-- Use `app_associated_resources_apply` for the associated report/view resource pool, selected resources, and match rules. `associated_item_id` is the internal associated-resource id from `app_get.associated_resources`; `view_configs`, remove, and reorder may also pass an existing resource's `chart_id`/`chart_key`/`view_key`, which the tool resolves to the internal id. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
+- Use `app_associated_resources_apply` for the associated report/view resource pool, selected resources, and match rules. Permission is split like the backend: resource pool writes use EditAppAuth, while `view_configs` uses the view config/DataManageAuth path. `associated_item_id` is the internal associated-resource id from `app_get.associated_resources`; `view_configs`, remove, and reorder may also pass an existing resource's `chart_id`/`chart_key`/`view_key`, which the tool resolves to the internal id. Do not write backend raw `sourceType`; reports default to BI app reports, and dataset reports use `report_source="dataset"`. Use `match_mappings` with `target_field + operator + source_field/value` for associated view/report filters; read `match-rules.md` if field type compatibility is unclear.
 - For gantt, use `start_field`, `end_field`, and optionally `title_field`
 - If `app_get.views` or `app_get_views` shows duplicate view names, include `view_key` in `upsert_views[]` and update that exact target
 - Builder view writes always use the raw `view_key` from `app_get.views[].view_key`, such as `emsrao25rs02`. Do not pass `custom:emsrao25rs02`; that prefixed form is only for record-data `view_id`.
 - For an existing view, prefer `patch_views` for parameter replacement. Do not send a partial `upsert_views` object such as only `name/type/query_conditions`; backend view saves require other type-specific fields, and the patch path preserves them for you.
 
-Apply a default table view:
+Apply a business table view:
 
 ```json
 {
@@ -49,16 +50,10 @@ Apply a default table view:
     "publish": true,
     "upsert_views": [
       {
-        "name": "全部订单",
+        "name": "订单台账视图",
         "view_key": "VIEW_KEY_IF_DUPLICATE_NAMES_EXIST",
         "type": "table",
-        "columns": ["订单编号", "客户名称", "订单金额", "状态", "负责人", "创建时间"],
-        "query_conditions": {
-          "enabled": true,
-          "exact": false,
-          "hide_before_query": false,
-          "rows": [["订单编号", "客户名称"], ["状态", "负责人"], ["创建时间"]]
-        }
+        "columns": ["订单编号", "客户名称", "订单金额", "状态"]
       }
     ],
     "remove_views": []
@@ -277,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
 
@@ -286,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

@@ -1,12 +1,14 @@
 ---
 name: qingflow-app-builder-code-integrations
-description: Configure Qingflow code block and Q-Linker fields through the builder surface when the task involves input field insertion, alias parsing, target field binding, or troubleshooting broken code/q-linker form configurations. Use after MCP is connected and authenticated, especially for CRM-style scoring, lookup, and enrichment forms.
+description: Configure Qingflow code block and Q-Linker fields through the builder surface when the task involves input field insertion, alias parsing, target field binding, or troubleshooting broken code/q-linker form configurations. In Wingent Momo runtime, use the injected MCP session and recover auth/workspace only after a tool error.
 metadata:
   short-description: Configure Qingflow code blocks and Q-Linkers safely
 ---
 
 # Qingflow App Builder Code Integrations
 
+> **Skill 版本**：`qingflow-skills-2026.06.24.2`（入口文档版本；如需确认 CLI 包版本，使用 `qingflow --version` 或 `qingflow --json version`）。
+
 Use this skill when the user wants to build or repair:
 - `code_block` fields
 - `q_linker` fields
@@ -58,7 +60,7 @@ For code block or Q-Linker work, use this order:
 
 1. Resolve the app and read fields:
    - `app_resolve`
-   - `app_read_fields`
+   - `app_get_fields`
 2. Confirm the target field set already exists.
 3. Apply schema updates with `app_schema_apply`.
 4. Read fields again and verify:
@@ -115,7 +117,7 @@ Hard rules:
 
 After each code block or Q-Linker change, verify all of these:
 
-- `app_read_fields` shows the intended field type
+- `app_get_fields` shows the intended field type
 - the high-level config is readable and stable
 - target fields still have valid types
 - insert schema can be opened

package/skills/qingflow-app-builder-code-integrations/references/code-block.md

@@ -59,7 +59,7 @@ Do not bind code block outputs to:
 
 ## Safe Verification
 
-- `app_read_fields`
+- `app_get_fields`
 - `record_insert_schema_get`
 - optional `record_code_block_run`
 

package/skills/qingflow-app-builder-code-integrations/references/q-linker.md

@@ -70,7 +70,7 @@ Avoid:
 
 ## Safe Verification
 
-- `app_read_fields`
+- `app_get_fields`
 - `record_insert_schema_get`
 - `record_insert`
 

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b1099"
+_FALLBACK_VERSION = "0.2.0b1017"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/__main__.py

@@ -1,5 +1,9 @@
-"""Entry point for running qingflow_mcp as a module."""
-from qingflow_mcp.server import main
+"""Entry point for running qingflow_mcp as a module.
+
+Default to the curated user-facing MCP surface. Split package and console
+entrypoints can still start the builder server explicitly.
+"""
+from qingflow_mcp.server_app_user import main
 
 if __name__ == "__main__":
     main()