@qingflow-tech/qingflow-cli 1.1.61-beta.4 → 1.1.61-beta.6

package/src/qingflow_mcp/builder_facade/portals_schema.py

@@ -0,0 +1,397 @@
+from __future__ import annotations
+
+import json
+import os
+from copy import deepcopy
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator, FormatChecker
+from referencing import Registry, Resource
+
+from .app_form_schema import compact_schema_errors, schema_error_message
+
+JSONObject = dict[str, Any]
+PORTALS_SCHEMA_ROOT = Path(__file__).with_name("schemas") / "portals"
+PORTALS_SUPPORTED_SCHEMA_KINDS = (
+    "summary",
+    "complete",
+    "chart",
+    "view",
+    "grid",
+    "filter",
+    "text",
+    "link",
+    "carousel",
+    "task",
+    "favourite",
+)
+
+
+class PortalsContractError(ValueError):
+    """Raised when a portals declaration violates the versioned schema contract."""
+
+    def __init__(self, error_code: str, message: str, *, path: str | None = None, details: JSONObject | None = None) -> None:
+        super().__init__(message)
+        self.error_code = error_code
+        self.message = message
+        self.path = path
+        self.details = details or {}
+
+
+def compact_none_values(value: Any) -> Any:
+    """Recursively drop None values so pydantic dumps match the JSON Schema contract."""
+    if isinstance(value, dict):
+        return {key: compact_none_values(item) for key, item in value.items() if item is not None}
+    if isinstance(value, list):
+        return [compact_none_values(item) for item in value]
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class PortalsSchemaContext:
+    """Resolved schema context for one portals schema version."""
+
+    schema_version: str
+    api_version: str
+    schemas: dict[str, JSONObject]
+    schema_files: dict[str, str]
+    ref_registry: Registry
+    supported_schema_kinds: tuple[str, ...]
+    contract_source: str
+    contract_version: str
+
+    @property
+    def summary_schema(self) -> JSONObject:
+        return self.schemas["summary"]
+
+    @property
+    def complete_schema(self) -> JSONObject:
+        return self.schemas["complete"]
+
+    def schema_for_kind(self, schema_kind: str) -> JSONObject:
+        requested = str(schema_kind or "").strip()
+        schema = self.schemas.get(requested)
+        if schema is not None:
+            return schema
+        raise PortalsContractError(
+            "UNSUPPORTED_SCHEMA_KIND",
+            f"unsupported portals schema kind: {requested}",
+            details={"supportedKinds": list(self.supported_schema_kinds)},
+        )
+
+    def _validate(self, payload: JSONObject, *, schema_kind: str) -> None:
+        schema = self.schema_for_kind(schema_kind)
+        validator = Draft202012Validator(schema, format_checker=FormatChecker(), registry=self.ref_registry)
+        errors = sorted(validator.iter_errors(payload), key=lambda item: (list(item.absolute_path), item.message))
+        if not errors:
+            return
+        compact_errors = compact_schema_errors(errors, schema)
+        error = compact_errors[0] if compact_errors else errors[0]
+        pointer = "".join(f"/{str(part).replace('~', '~0').replace('/', '~1')}" for part in error.absolute_path) or "/"
+        raise PortalsContractError(
+            "INVALID_SPEC",
+            schema_error_message(error),
+            path=pointer,
+            details={
+                "validator": error.validator,
+                "schemaPath": "/".join(str(part) for part in error.absolute_schema_path),
+                "schemaKind": schema_kind,
+            },
+        )
+
+    def validate_upsert(self, payload: JSONObject, *, schema_kind: str = "complete") -> None:
+        """Validate a single (alias-normalized) portal declaration."""
+        self._validate(payload, schema_kind=schema_kind)
+
+    def validate_declaration(self, payload: JSONObject, *, schema_kind: str = "complete") -> None:
+        """Validate one portal declaration used by ``portal_apply``."""
+        if not isinstance(payload, dict):
+            raise PortalsContractError("INVALID_SPEC", "portals declaration must be a JSON object", path="/")
+        self._validate(payload, schema_kind=schema_kind)
+
+
+class PortalsSchemaRegistry:
+    """Registry for versioned portals declaration schemas (mirrors ViewsSchemaRegistry)."""
+
+    def __init__(self, root: Path = PORTALS_SCHEMA_ROOT, *, enabled_versions: tuple[str, ...] | None = None) -> None:
+        self.root = root
+        self.manifest = self._read_json(root / "manifest.json")
+        versions = self.manifest.get("versions")
+        if not isinstance(versions, dict) or not versions:
+            raise RuntimeError("portals schema manifest must define versions")
+        env_versions = self._configured_versions()
+        defaults = tuple(
+            str(version)
+            for version, metadata in versions.items()
+            if isinstance(metadata, dict) and bool(metadata.get("enabledByDefault"))
+        )
+        configured = tuple(enabled_versions) if enabled_versions is not None else (env_versions or defaults)
+        self.stored_versions = tuple(str(version) for version in versions)
+        self.latest_version = str(self.manifest.get("latestVersion") or "")
+        self._stored_api_to_version: dict[str, str] = {}
+        for version, metadata in versions.items():
+            if not isinstance(metadata, dict):
+                raise RuntimeError(f"portals schema metadata must be an object: {version}")
+            api_version = str(metadata.get("apiVersion") or "")
+            if not api_version:
+                raise RuntimeError(f"portals schema version has no apiVersion: {version}")
+            if api_version in self._stored_api_to_version:
+                raise RuntimeError(f"duplicate portals apiVersion: {api_version}")
+            self._stored_api_to_version[api_version] = str(version)
+        self.enabled_versions = configured
+        if self.latest_version not in versions:
+            raise RuntimeError("portals latestVersion is not stored")
+        if self.latest_version not in self.enabled_versions:
+            raise RuntimeError("portals latestVersion must remain enabled")
+        self._contexts: dict[str, PortalsSchemaContext] = {}
+        self._api_to_version: dict[str, str] = {}
+        for version in self.enabled_versions:
+            metadata = versions.get(version)
+            if not isinstance(metadata, dict):
+                raise RuntimeError(f"enabled portals schema version is not stored: {version}")
+            api_version = str(metadata.get("apiVersion") or "")
+            schema_files = metadata.get("schemaFiles")
+            if not isinstance(schema_files, dict):
+                schema_files = {kind: f"{version}/{kind}.json" for kind in ("summary", "complete")}
+            supported_schema_kinds = tuple(str(item) for item in metadata.get("schemaKinds") or schema_files)
+            if not {"summary", "complete"}.issubset(supported_schema_kinds):
+                raise RuntimeError(f"portals schema version must support summary and complete kinds: {version}")
+            schemas: dict[str, JSONObject] = {}
+            paths: dict[str, Path] = {}
+            for name in supported_schema_kinds:
+                relative_path = schema_files.get(name)
+                if not isinstance(relative_path, str) or not relative_path:
+                    raise RuntimeError(f"portals schema kind has no schema file: {version}/{name}")
+                path = root / relative_path
+                schema = self._read_json(path)
+                schemas[name] = schema
+                paths[name] = path
+            ref_registry = Registry()
+            for name, schema in schemas.items():
+                schema_id = str(schema.get("$id") or "")
+                if version not in schema_id:
+                    raise RuntimeError(f"portals {name} schema $id mismatch for {version}: {schema_id}")
+                Draft202012Validator.check_schema(schema)
+                resource = Resource.from_contents(schema)
+                if schema_id:
+                    ref_registry = ref_registry.with_resource(schema_id, resource)
+                ref_registry = ref_registry.with_resource(paths[name].resolve().as_uri(), resource)
+            for name, schema in schemas.items():
+                self._validate_local_refs(schema, paths[name], schemas, paths)
+            context = PortalsSchemaContext(
+                version,
+                api_version,
+                schemas,
+                {name: str(schema_files[name]) for name in supported_schema_kinds},
+                ref_registry,
+                supported_schema_kinds,
+                str(metadata.get("contractSource") or "portal_apply"),
+                str(metadata.get("contractVersion") or version),
+            )
+            self._contexts[version] = context
+            self._api_to_version[api_version] = version
+
+    def schema(
+        self,
+        *,
+        schema_version: str | None = None,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
+        context = self.resolve_schema_version(schema_version)
+        requested_kind = str(schema_kind or "summary").strip()
+        if requested_kind not in context.supported_schema_kinds:
+            raise PortalsContractError(
+                "UNSUPPORTED_SCHEMA_KIND",
+                f"unsupported portals schema kind: {requested_kind}",
+                details={"supportedKinds": list(context.supported_schema_kinds)},
+            )
+        schema, dependencies = self._bundle_schema(
+            context.schema_for_kind(requested_kind),
+            schema_path=(self.root / context.schema_files[requested_kind]),
+            schemas=context.schemas,
+            schema_files=context.schema_files,
+        )
+        return {
+            "schemaVersion": context.schema_version,
+            "apiVersion": context.api_version,
+            "latestVersion": self.latest_version,
+            "storedVersions": list(self.stored_versions),
+            "enabledVersions": list(self.enabled_versions),
+            "supportedSchemaKinds": list(context.supported_schema_kinds),
+            "schemaKind": requested_kind,
+            "schemaFile": context.schema_files[requested_kind],
+            "schemaBundled": bool(dependencies),
+            "schemaDependencies": dependencies,
+            "schema": schema,
+        }
+
+    @classmethod
+    def _bundle_schema(
+        cls,
+        schema: JSONObject,
+        *,
+        schema_path: Path,
+        schemas: dict[str, JSONObject],
+        schema_files: dict[str, str],
+    ) -> tuple[JSONObject, list[str]]:
+        """Inline reachable cross-file definitions for standalone consumers."""
+        bundled = deepcopy(schema)
+        definitions = bundled.get("$defs")
+        if not isinstance(definitions, dict):
+            definitions = {}
+        dependencies: set[str] = set()
+        # schema_path is <root>/<version>/components/<file> or <root>/<version>/<file>.
+        # Find the manifest root from the configured path instead of relying on
+        # a fixed components depth.
+        cls_root = schema_path.parent
+        for candidate in schema_path.parents:
+            if (candidate / "manifest.json").is_file():
+                cls_root = candidate
+                break
+        paths = {name: cls_root / relative for name, relative in schema_files.items()}
+
+        def resolve_pointer(document: JSONObject, fragment: str, *, ref: str) -> Any:
+            target: Any = document
+            for raw_part in fragment[1:].split("/") if fragment.startswith("/") else ():
+                part = raw_part.replace("~1", "/").replace("~0", "~")
+                if not isinstance(target, dict) or part not in target:
+                    raise RuntimeError(f"portals schema contains a dangling $ref in {schema_path}: {ref}")
+                target = target[part]
+            return target
+
+        pending: list[tuple[str, JSONObject, Path]] = []
+
+        def add_definition(name: str, source: JSONObject, source_path: Path) -> None:
+            if name in definitions:
+                return
+            source_definitions = source.get("$defs")
+            if not isinstance(source_definitions, dict) or name not in source_definitions:
+                raise RuntimeError(f"portals schema references an unknown definition: {name}")
+            definitions[name] = deepcopy(source_definitions[name])
+            pending.append((name, source, source_path))
+
+        def rewrite(value: Any, source: JSONObject, source_path: Path) -> None:
+            if isinstance(value, dict):
+                ref = value.get("$ref")
+                if isinstance(ref, str):
+                    ref_file, _, fragment = ref.partition("#")
+                    target_source = source
+                    target_path = source_path
+                    if ref_file:
+                        target_path = (source_path.parent / ref_file).resolve()
+                        target_name = next(
+                            (name for name, path in paths.items() if path.resolve() == target_path),
+                            None,
+                        )
+                        if target_name is None:
+                            raise RuntimeError(f"portals schema contains an external $ref in {source_path}: {ref}")
+                        target_source = schemas[target_name]
+                        dependencies.add(schema_files[target_name])
+                        value["$ref"] = f"#{fragment}"
+                    local_ref = str(value["$ref"])
+                    if local_ref.startswith("#/$defs/"):
+                        name = local_ref.removeprefix("#/$defs/").split("/", 1)[0]
+                        add_definition(name, target_source, target_path)
+                    else:
+                        resolve_pointer(target_source, fragment, ref=ref)
+                for child in value.values():
+                    rewrite(child, source, source_path)
+            elif isinstance(value, list):
+                for child in value:
+                    rewrite(child, source, source_path)
+
+        for key, value in bundled.items():
+            if key != "$defs":
+                rewrite(value, schema, schema_path)
+        while pending:
+            name, source, source_path = pending.pop()
+            rewrite(definitions[name], source, source_path)
+        if definitions:
+            bundled["$defs"] = definitions
+        return bundled, sorted(dependencies)
+
+    def resolve_schema_version(self, schema_version: str | None) -> PortalsSchemaContext:
+        version = str(schema_version or self.latest_version).strip()
+        if version not in self.stored_versions:
+            raise self._version_error("UNSUPPORTED_SCHEMA_VERSION", version)
+        if version not in self.enabled_versions:
+            raise self._version_error("SCHEMA_VERSION_DISABLED", version)
+        return self._contexts[version]
+
+    def resolve_api_version(self, api_version: str) -> PortalsSchemaContext:
+        version = self._api_to_version.get(api_version)
+        if version is not None:
+            return self._contexts[version]
+        stored = self._stored_api_to_version.get(api_version)
+        if stored is not None:
+            raise self._version_error("SCHEMA_VERSION_DISABLED", stored)
+        raise self._version_error("UNSUPPORTED_SCHEMA_VERSION", api_version)
+
+    def _version_error(self, error_code: str, requested: str) -> PortalsContractError:
+        return PortalsContractError(
+            error_code,
+            f"unsupported portals schema selection: {requested}",
+            details={
+                "requestedVersion": requested,
+                "latestVersion": self.latest_version,
+                "storedVersions": list(self.stored_versions),
+                "enabledVersions": list(self.enabled_versions),
+            },
+        )
+
+    @staticmethod
+    def _read_json(path: Path) -> JSONObject:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(value, dict):
+            raise RuntimeError(f"portals schema artifact must be an object: {path}")
+        return value
+
+    @staticmethod
+    def _validate_local_refs(
+        document: JSONObject,
+        path: Path,
+        documents: dict[str, JSONObject],
+        paths: dict[str, Path],
+    ) -> None:
+        stack: list[Any] = [document]
+        while stack:
+            value = stack.pop()
+            if isinstance(value, dict):
+                ref = value.get("$ref")
+                if ref is not None:
+                    if not isinstance(ref, str):
+                        raise RuntimeError(f"portals schema contains an invalid $ref in {path}: {ref}")
+                    ref_file, _, fragment = ref.partition("#")
+                    target_document = document
+                    if ref_file:
+                        target_path = (path.parent / ref_file).resolve()
+                        if target_path not in {item.resolve() for item in paths.values()}:
+                            raise RuntimeError(f"portals schema contains an external $ref in {path}: {ref}")
+                        target_name = next(name for name, item in paths.items() if item.resolve() == target_path)
+                        target_document = documents[target_name]
+                    target: Any = target_document
+                    for raw_part in fragment[1:].split("/") if fragment.startswith("/") else ():
+                        part = raw_part.replace("~1", "/").replace("~0", "~")
+                        if not isinstance(target, dict) or part not in target:
+                            raise RuntimeError(f"portals schema contains a dangling $ref in {path}: {ref}")
+                        target = target[part]
+                stack.extend(value.values())
+            elif isinstance(value, list):
+                stack.extend(value)
+
+    @staticmethod
+    def _configured_versions() -> tuple[str, ...]:
+        raw = os.environ.get("QINGFLOW_PORTALS_SCHEMA_VERSIONS", "")
+        return tuple(part.strip() for part in raw.split(",") if part.strip())
+
+
+_REGISTRY: PortalsSchemaRegistry | None = None
+
+
+def portals_schema_registry() -> PortalsSchemaRegistry:
+    global _REGISTRY
+    if _REGISTRY is None:
+        _REGISTRY = PortalsSchemaRegistry()
+    return _REGISTRY

package/src/qingflow_mcp/builder_facade/schemas/app_form/manifest.json

@@ -29,7 +29,20 @@
         "code_block",
         "data_relation",
         "relation",
-        "subtable"
+        "subtable",
+        "date_duration",
+        "image_select",
+        "location",
+        "ocr",
+        "embed_field",
+        "ai_content_generation",
+        "ai_content_extraction",
+        "ai_content_classification",
+        "ai_machine_translation",
+        "ai_image_recognition",
+        "ai_image_generation",
+        "ai_document_parsing",
+        "ai_text_summary"
       ],
       "normalizerVersion": "v1alpha1",
       "schemaKinds": [

package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/complete.json

@@ -910,6 +910,12 @@
             "null"
           ]
         },
+        "auditValueDescription": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "beingCanDecrypted": {
           "type": [
             "boolean",
@@ -940,6 +946,12 @@
             "null"
           ]
         },
+        "dataId": {
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
         "dateType": {
           "type": [
             "integer",
@@ -958,6 +970,15 @@
             "null"
           ]
         },
+        "previousTableRowOrdinalList": {
+          "items": {
+            "type": "integer"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        },
         "queId": {
           "type": [
             "integer",
@@ -976,6 +997,12 @@
             "null"
           ]
         },
+        "questionOrdinal": {
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
         "referValues": {
           "items": {
             "$ref": "#/$defs/ReferenceDefaultValue"
@@ -1309,11 +1336,11 @@
       "description": "段落内部字段行。",
       "properties": {
         "fields": {
-          "description": "本行的 1 到 4 个顶层字段。",
+          "description": "本行的 1 到 12 个顶层字段(后端无每行字段数上限,按 queWidth 渲染;上限仅约束声明输入)。",
           "items": {
             "$ref": "#/$defs/TopField"
           },
-          "maxItems": 4,
+          "maxItems": 12,
           "minItems": 1,
           "type": "array"
         }
@@ -1626,8 +1653,8 @@
           ]
         },
         "numberFormat": {
-          "description": "数字展示格式 ID。",
-          "minimum": 1,
+          "description": "数字展示格式 ID(1 默认/2 千分位/3 百分比;0 为历史存量值——后端写链无值域校验,原样落库回读)。",
+          "minimum": 0,
           "type": [
             "integer",
             "null"
@@ -1918,8 +1945,8 @@
           ]
         },
         "url": {
-          "description": "请求 URL;动态嵌入字段值时使用 {{key}},并在 inputs 中提供同名 source=json_path 映射。",
-          "minLength": 1,
+          "description": "请求 URL;动态嵌入字段值时使用 {{key}},并在 inputs 中提供同名 source=json_path 映射。自定义模式(configMode=1)后端要求非空;插件模板/连接中心/轻翼智能体模式的 URL 由模板侧提供,存量声明可为空字符串(写回按读面形态透传)。",
+          "minLength": 0,
           "type": "string"
         },
         "urlEncodedValue": {
@@ -2093,11 +2120,11 @@
       "description": "根级普通字段行;字段顺序即展示顺序。",
       "properties": {
         "fields": {
-          "description": "本行的 1 到 4 个顶层字段。",
+          "description": "本行的 1 到 12 个顶层字段(后端无每行字段数上限,按 queWidth 渲染;上限仅约束声明输入)。",
           "items": {
             "$ref": "#/$defs/TopField"
           },
-          "maxItems": 4,
+          "maxItems": 12,
           "minItems": 1,
           "type": "array"
         },
@@ -2736,7 +2763,20 @@
                   "enum": [
                     "date",
                     "datetime",
-                    "rich_text"
+                    "rich_text",
+                    "date_duration",
+                    "image_select",
+                    "location",
+                    "ocr",
+                    "embed_field",
+                    "ai_content_generation",
+                    "ai_content_extraction",
+                    "ai_content_classification",
+                    "ai_machine_translation",
+                    "ai_image_recognition",
+                    "ai_image_generation",
+                    "ai_document_parsing",
+                    "ai_text_summary"
                   ]
                 }
               },

package/src/qingflow_mcp/builder_facade/schemas/app_form/v1alpha1/fields/address.json

@@ -118,6 +118,12 @@
             "null"
           ]
         },
+        "auditValueDescription": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
         "beingCanDecrypted": {
           "type": [
             "boolean",
@@ -148,6 +154,12 @@
             "null"
           ]
         },
+        "dataId": {
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
         "dateType": {
           "type": [
             "integer",
@@ -166,6 +178,15 @@
             "null"
           ]
         },
+        "previousTableRowOrdinalList": {
+          "items": {
+            "type": "integer"
+          },
+          "type": [
+            "array",
+            "null"
+          ]
+        },
         "queId": {
           "type": [
             "integer",
@@ -184,6 +205,12 @@
             "null"
           ]
         },
+        "questionOrdinal": {
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
         "referValues": {
           "items": {
             "$ref": "#/$defs/ReferenceDefaultValue"