@qingflow-tech/qingflow-cli 1.1.41 → 1.1.43-beta.1

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.41
+npm install @qingflow-tech/qingflow-cli@1.1.43-beta.1
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.41 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.43-beta.1 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -38,7 +38,7 @@ qingflow
 
 首次安装时会自动初始化本地 Python 运行环境，随后提供 `qingflow` 命令行入口。
 
-## 内置 Skills
+## Bundled skills: 内置 Skills
 
 - `skills/qingflow-cli`
 - `skills/qingflow-mcp-setup`
@@ -55,7 +55,7 @@ qingflow-skills install --agent codex --scope user
 如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.41 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.43-beta.1 qingflow-skills install --agent codex --scope user --copy
 ```
 
 `qingflow-skills install` 默认使用 symlink，且遇到同名 skill 不会覆盖；只有显式传入 `--force` 才会替换。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-cli",
-  "version": "1.1.41",
+  "version": "1.1.43-beta.1",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",
@@ -16,6 +16,7 @@
     "pyproject.toml",
     "entry_point.py",
     "src/qingflow_mcp/**/*.py",
+    "src/qingflow_mcp/builder_facade/schemas/**/*.json",
     "src/qingflow_mcp/py.typed",
     "qingflow",
     "npm/",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.1.41"
+version = "1.1.43b1"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"
@@ -25,6 +25,7 @@ classifiers = [
 dependencies = [
   "mcp>=1.9.4,<2.0.0",
   "httpx>=0.27,<1.0",
+  "jsonschema>=4.23,<5.0",
   "keyring>=25.5,<26.0",
   "openpyxl>=3.1,<4.0",
   "pydantic>=2.8,<3.0",
@@ -64,7 +65,7 @@ Issues = "https://github.com/qingflow/qingflow-mcp/issues"
 where = ["src"]
 
 [tool.setuptools.package-data]
-qingflow_mcp = ["py.typed"]
+qingflow_mcp = ["py.typed", "builder_facade/schemas/app_form/**/*.json"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

package/skills/qingflow-cli/reference/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md

@@ -114,7 +114,7 @@ qingflow --json task action \
 - **定位只认 `task_id`**：来自 `task list` 的 `data.items[].task_id`；`app_key`、`record_id`、`workflow_node_id` 不是动作执行入参。
 - `**approve` / `reject`**：执行上下文以当前待办详情或用户/前端已给出的显式 `formId` 为准；只有缺少 `formId` 时才兜底读取应用 baseInfo。不要把应用 baseInfo 的 `40002` 当作待办动作最终无权结论，最终是否可执行以后端审批动作接口为准。
 - `**save_only`**：必须 提供非空 `**--fields-file`**（或 payload 与 fields 不能同时塞 `answers` 与 fields，具体以报错为准）。以当前待办节点的 `data.editable_fields` / `editableQueIds` 为准；若 `editableQueIds` 被当前权限链路挡住，但任务详情里的 `queAuthSetting` 已暴露可编辑字段，CLI 会按任务详情继续允许 save-only，并由最终保存接口裁决。申请表单 schema 或辅助 `editableQueIds` 的 `40002` 不是待办字段保存的最终无权结论。
-- `**transfer**`：`**payload` 内需要** `target_member_id`（或别名 `uid` / `targetMemberId`）；不能转给当前登录人。
+- `**transfer**`：`**payload` 内需要** `target_member_id`（或别名 `uid` / `targetMemberId`）；不能转给当前登录人。未提供 `payload.answers` 且没有通过 `--fields-file` 修改字段时，CLI 会先读取当前待办详情，并将已有 `answers` 原样带入转交请求；显式 `payload.answers` 或 `--fields-file` 合并结果优先。
 - **意见必填**：若详情里 `**action_constraints.feedback_required_for`** 包含当前动作，需在 `**payload.audit_feedback`**（实现从 payload 抽取审计意见，具体键名以 `--help` / 服务端为准）中提供，否则会 config 错误。
 - `**urge`**：**不支持** 与 `fields` 同时提交。
 - **禁止臆测动作**：只允许 `**data.available_actions`** 中出现的动作；`approve` 不在列表则不可硬放行。

package/skills/qingflow-cli/reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md

@@ -116,7 +116,7 @@ qingflow --json task action \
 - **定位只认 `task_id`**：来自 `task list` 的 `data.items[].task_id`；`app_key`、`record_id`、`workflow_node_id` 不是动作执行入参。
 - `**approve` / `reject`**：执行上下文以当前待办详情或用户/前端已给出的显式 `formId` 为准；只有缺少 `formId` 时才兜底读取应用 baseInfo。不要把应用 baseInfo 的 `40002` 当作待办动作最终无权结论，最终是否可执行以后端审批动作接口为准。
 - `**save_only`**：必须 提供非空 `**--fields-file`**（或 payload 与 fields 不能同时塞 `answers` 与 fields，具体以报错为准）。以当前待办节点的 `data.editable_fields` / `editableQueIds` 为准；若 `editableQueIds` 被当前权限链路挡住，但任务详情里的 `queAuthSetting` 已暴露可编辑字段，CLI 会按任务详情继续允许 save-only，并由最终保存接口裁决。申请表单 schema 或辅助 `editableQueIds` 的 `40002` 不是待办字段保存的最终无权结论。
-- `**transfer**`：`**payload` 内需要** `target_member_id`（或别名 `uid` / `targetMemberId`）；不能转给当前登录人。
+- `**transfer**`：`**payload` 内需要** `target_member_id`（或别名 `uid` / `targetMemberId`）；不能转给当前登录人。未提供 `payload.answers` 且没有通过 `--fields-file` 修改字段时，CLI 会先读取当前待办详情，并将已有 `answers` 原样带入转交请求；显式 `payload.answers` 或 `--fields-file` 合并结果优先。
 - **意见必填**：若详情里 `**action_constraints.feedback_required_for`** 包含当前动作，需在 `**payload.audit_feedback`**（实现从 payload 抽取审计意见，具体键名以 `--help` / 服务端为准）中提供，否则会 config 错误。
 - `**urge`**：**不支持** 与 `fields` 同时提交。
 - **禁止臆测动作**：只允许 `**data.available_actions`** 中出现的动作；`approve` 不在列表则不可硬放行。

package/src/qingflow_mcp/app_form_compat.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from .builder_facade.app_form_schema import AppFormContractError
+from .json_types import JSONObject
+from .solution.compiler.icon_utils import validate_workspace_icon_choice
+
+
+TYPE_ALIASES = {
+    "multiline": "long_text",
+    "textarea": "long_text",
+    "radio": "single_choice",
+    "boolean": "single_choice",
+    "select": "single_select",
+    "dropdown": "single_select",
+    "checkbox": "multi_select",
+    "multi_choice": "multi_select",
+    "url": "link",
+    "hyperlink": "link",
+    "reference": "relation",
+    "quote": "relation",
+}
+FIELD_CONFIG_ALIASES = {
+    "options": "options",
+    "department_scope": "departmentScope",
+    "target_app_key": "targetAppKey",
+    "relation_mode": "relationMode",
+    "display_field": "displayField",
+    "visible_fields": "visibleFields",
+    "q_linker_binding": "qLinkerBinding",
+    "code_block_binding": "codeBlockBinding",
+}
+
+
+def normalize_app_form_declaration(payload: JSONObject) -> tuple[JSONObject, list[JSONObject]]:
+    """Normalize supported v1alpha1 compatibility aliases before Schema validation."""
+    result = deepcopy(payload)
+    warnings: list[JSONObject] = []
+
+    def visit(field: JSONObject, path: str) -> None:
+        raw_type = str(field.get("type") or "").strip()
+        canonical_type = TYPE_ALIASES.get(raw_type, raw_type)
+        if canonical_type:
+            field["type"] = canonical_type
+        if canonical_type != raw_type and raw_type == "boolean":
+            warnings.append({"code": "LEGACY_BOOLEAN_NORMALIZED", "path": f"{path}/type"})
+
+        for old, new in (("as_data_title", "dataTitle"), ("as_data_cover", "dataCover")):
+            if old not in field:
+                continue
+            if new in field:
+                raise AppFormContractError("INVALID_SPEC", f"conflicting aliases: {old} and {new}", path=path)
+            field[new] = field.pop(old)
+
+        config = field.get("config")
+        if config is None:
+            config = {}
+        if not isinstance(config, dict):
+            return
+        for old, new in FIELD_CONFIG_ALIASES.items():
+            if old not in field:
+                continue
+            if new in config:
+                raise AppFormContractError("INVALID_SPEC", f"conflicting aliases: {old} and config.{new}", path=path)
+            config[new] = field.pop(old)
+        if raw_type == "boolean" and "options" not in config:
+            config["options"] = ["是", "否"]
+        if config:
+            field["config"] = config
+
+        if "fields" in field:
+            if "subfields" in field:
+                raise AppFormContractError("INVALID_SPEC", "conflicting aliases: fields and subfields", path=path)
+            field["subfields"] = field.pop("fields")
+        children = field.get("subfields")
+        for index, child in enumerate(children if isinstance(children, list) else []):
+            if isinstance(child, dict):
+                visit(child, f"{path}/subfields/{index}")
+
+    spec = result.get("spec")
+    for block_index, block in enumerate(spec.get("body") or [] if isinstance(spec, dict) else []):
+        if not isinstance(block, dict):
+            continue
+        rows = [block] if block.get("kind") == "row" else block.get("rows") or []
+        for row_index, row in enumerate(rows):
+            if not isinstance(row, dict):
+                continue
+            for field_index, field in enumerate(row.get("fields") or []):
+                if isinstance(field, dict):
+                    visit(field, f"/spec/body/{block_index}/rows/{row_index}/fields/{field_index}")
+    return result, warnings
+
+
+def validate_app_form_create_icon(payload: JSONObject) -> None:
+    if "appKey" in payload:
+        return
+    spec = payload.get("spec")
+    if not isinstance(spec, dict):
+        return
+    ok, error_code, message, details = validate_workspace_icon_choice(
+        icon=str(spec.get("icon") or "") or None,
+        color=str(spec.get("color") or "") or None,
+        require_explicit=True,
+        disallow_generic=True,
+    )
+    if not ok:
+        color_errors = {"WORKSPACE_ICON_COLOR_REQUIRED", "WORKSPACE_ICON_COLOR_NOT_FOUND"}
+        raise AppFormContractError(
+            error_code or "WORKSPACE_ICON_INVALID",
+            message or "invalid workspace icon configuration",
+            path="/spec/color" if error_code in color_errors else "/spec/icon",
+            details=details,
+        )

package/src/qingflow_mcp/app_form_validator.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+from typing import Any, Iterable
+
+from jsonschema import Draft202012Validator, FormatChecker
+
+from .app_form_compat import normalize_app_form_declaration, validate_app_form_create_icon
+from .builder_facade.app_form_schema import AppFormContractError
+
+
+class AppFormValidationError(ValueError):
+    """Raised when a declaration fails local AppForm validation."""
+
+    def __init__(self, issues: list[dict[str, str]], *, schema_version: str, api_version: str) -> None:
+        super().__init__("AppForm declaration is invalid")
+        self.issues = issues
+        self.schema_version = schema_version
+        self.api_version = api_version
+
+
+def _field_types(payload: dict[str, Any]) -> tuple[str, ...]:
+    found: set[str] = set()
+
+    def visit(field: Any) -> None:
+        if not isinstance(field, dict):
+            return
+        field_type = str(field.get("type") or "").strip()
+        if field_type:
+            found.add(field_type)
+        for child in field.get("subfields") or []:
+            visit(child)
+
+    spec = payload.get("spec")
+    for block in spec.get("body") or [] if isinstance(spec, dict) else []:
+        if not isinstance(block, dict):
+            continue
+        rows = [block] if block.get("kind") == "row" else block.get("rows") or []
+        for row in rows:
+            for field in row.get("fields") or [] if isinstance(row, dict) else []:
+                visit(field)
+    return tuple(sorted(found))
+
+
+def _local_schema_call(schema_version: str | None, field_type: str | None) -> dict[str, Any]:
+    from .builder_facade.app_form_schema import app_form_schema_registry
+
+    return {"status": "success", **app_form_schema_registry().schema(schema_version=schema_version, field_type=field_type)}
+
+
+def _compose(summary: dict[str, Any], details: list[dict[str, Any]]) -> dict[str, Any]:
+    if not details:
+        raise RuntimeError("at least one field Schema is required to compose AppForm validation")
+    schema = deepcopy(summary["schema"])
+    shared_defs = deepcopy(schema.get("$defs") or {})
+    field_branches = []
+    for detail in details:
+        detail_schema = detail["schema"]
+        for name, definition in (detail_schema.get("$defs") or {}).items():
+            existing = shared_defs.get(name)
+            if existing is not None and existing != definition:
+                raise RuntimeError(f"field Schema definition conflict: {name}")
+            shared_defs[name] = deepcopy(definition)
+        branch = {
+            key: deepcopy(value)
+            for key, value in detail_schema.items()
+            if key not in {"$schema", "$id", "$defs", "title"}
+        }
+        field_branches.append(branch)
+    shared_defs["TopField"] = {"oneOf": field_branches}
+    schema["$defs"] = shared_defs
+    schema["properties"]["spec"] = {
+        "$ref": "#/$defs/AppFormSpec",
+        "description": "Application form target state.",
+    }
+    return schema
+
+
+def _leaf_errors(error: Any) -> Iterable[Any]:
+    if not error.context:
+        yield error
+        return
+    for child in error.context:
+        yield from _leaf_errors(child)
+
+
+def _pointer(parts: Iterable[Any]) -> str:
+    encoded = [str(item).replace("~", "~0").replace("/", "~1") for item in parts]
+    return "/" + "/".join(encoded) if encoded else "/"
+
+
+def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
+    errors: list[tuple[str, str]] = []
+    spec = payload.get("spec")
+    body = spec.get("body") if isinstance(spec, dict) else None
+    if not isinstance(body, list):
+        return errors
+    top_fields: list[tuple[str, dict[str, Any]]] = []
+    for block_index, block in enumerate(body):
+        if not isinstance(block, dict):
+            continue
+        rows = [block] if block.get("kind") == "row" else block.get("rows") or []
+        for row_index, row in enumerate(rows):
+            if not isinstance(row, dict):
+                continue
+            fields = row.get("fields")
+            if not isinstance(fields, list):
+                continue
+            row_path = f"/spec/body/{block_index}/" + ("fields" if block.get("kind") == "row" else f"rows/{row_index}/fields")
+            widths = ["width" in field for field in fields if isinstance(field, dict)]
+            if widths and any(widths) and not all(widths):
+                errors.append((row_path, "width must be present on every field in the row or omitted from all"))
+            if widths and all(widths) and sum(field.get("width", 0) for field in fields if isinstance(field, dict)) != 100:
+                errors.append((row_path, "field widths must total 100"))
+            for field_index, field in enumerate(fields):
+                if isinstance(field, dict):
+                    top_fields.append((f"{row_path}/{field_index}", field))
+    if top_fields and sum(field.get("dataTitle") is True for _, field in top_fields) != 1:
+        errors.append(("/spec/body", "a non-empty body must contain exactly one dataTitle field"))
+    covers = [(path, field) for path, field in top_fields if field.get("dataCover") is True]
+    if len(covers) > 1:
+        errors.append(("/spec/body", "body may contain at most one dataCover field"))
+    for path, field in covers:
+        if field.get("type") != "attachment":
+            errors.append((f"{path}/dataCover", "dataCover is only valid on attachment fields"))
+    names: dict[str, str] = {}
+    fields_by_id = {
+        field.get("queId"): field
+        for _, field in top_fields
+        if isinstance(field.get("queId"), int) and not isinstance(field.get("queId"), bool)
+    }
+    for path, field in top_fields:
+        name = str(field.get("name") or "")
+        if name in names:
+            errors.append((f"{path}/name", f"duplicate top-level field name; first declared at {names[name]}"))
+        else:
+            names[name] = f"{path}/name"
+        if field.get("type") != "q_linker":
+            continue
+        binding = (field.get("config") or {}).get("qLinkerBinding") if isinstance(field.get("config"), dict) else None
+        for index, item in enumerate((binding or {}).get("inputs") or [] if isinstance(binding, dict) else []):
+            if not isinstance(item, dict) or item.get("source") != "json_path":
+                continue
+            selector = item.get("field") if isinstance(item.get("field"), dict) else {}
+            selected_name = selector.get("name")
+            if not selected_name and selector.get("queId") in fields_by_id:
+                selected_name = fields_by_id[selector["queId"]].get("name")
+            if selected_name and item.get("key") != selected_name:
+                errors.append((f"{path}/config/qLinkerBinding/inputs/{index}/key", "json_path key must equal the selected field name"))
+    return errors
+
+
+def validate_declaration(
+    payload: dict[str, Any],
+    *,
+    schema_version: str | None = None,
+    schema_call: Any = _local_schema_call,
+) -> dict[str, Any]:
+    """Validate a complete AppForm declaration without network or write calls."""
+    summary = schema_call(schema_version, None)
+    if not isinstance(summary, dict) or summary.get("status") != "success" or not isinstance(summary.get("schema"), dict):
+        raise RuntimeError(f"AppForm Schema query failed: {json.dumps(summary, ensure_ascii=False)}")
+    pinned = str(summary.get("schemaVersion") or "")
+    api_version = str(summary.get("apiVersion") or "")
+    if schema_version and pinned != schema_version:
+        raise ValueError(f"/: requested schemaVersion {schema_version!r} resolved to {pinned!r}")
+    try:
+        declaration, _warnings = normalize_app_form_declaration(payload)
+    except AppFormContractError as error:
+        raise AppFormValidationError(
+            [{"pointer": error.path or "/", "message": error.message}],
+            schema_version=pinned,
+            api_version=api_version,
+        ) from error
+    if declaration.get("apiVersion") != api_version:
+        raise ValueError(f"/apiVersion: expected {api_version!r} for schemaVersion {pinned!r}")
+    types = _field_types(declaration)
+    details = [schema_call(pinned, field_type) for field_type in (types or ("text",))]
+    for detail in details:
+        if not isinstance(detail, dict) or detail.get("status") != "success" or detail.get("schemaVersion") != pinned or detail.get("apiVersion") != api_version:
+            raise RuntimeError("/: AppForm Schema responses mixed versions")
+    schema = _compose(summary, details)
+    Draft202012Validator.check_schema(schema)
+    validator = Draft202012Validator(schema, format_checker=FormatChecker())
+    found: dict[tuple[str, str], None] = {}
+    for error in validator.iter_errors(declaration):
+        for leaf in _leaf_errors(error):
+            found[(_pointer(leaf.absolute_path), f"{leaf.validator}: {leaf.message}")] = None
+    for pointer, message in _static_errors(declaration):
+        found[(pointer, message)] = None
+    try:
+        validate_app_form_create_icon(declaration)
+    except AppFormContractError as error:
+        found[(error.path or "/", error.message)] = None
+    if found:
+        issues = [{"pointer": pointer, "message": message} for pointer, message in sorted(found)]
+        raise AppFormValidationError(issues, schema_version=pinned, api_version=api_version)
+    return {"valid": True, "schemaVersion": pinned, "apiVersion": api_version, "fieldTypes": list(types)}