@qingflow-tech/qingflow-cli 1.1.44-beta.2 → 1.1.45-beta.1

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.44-beta.2
+npm install @qingflow-tech/qingflow-cli@1.1.45-beta.1
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.44-beta.2 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.45-beta.1 qingflow
 ```
 
 全局安装后可以直接运行：
@@ -62,7 +62,7 @@ qingflow-skills install --agent codex --scope user
 如果你通过一次性 `npx -p` 执行 skills 安装，建议加 `--copy`，避免 symlink 指向 npm 临时执行缓存：
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.44-beta.2 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.45-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.44-beta.2",
+  "version": "1.1.45-beta.1",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/src/qingflow_mcp/app_form_validator.py

@@ -24,6 +24,8 @@ _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
 }
 _Q_LINKER_TEMPLATE_RE = re.compile(r"\{\{(?P<key>[^{}\s]+)\}\}")
 _FORMULA_IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+#: 公式字段引用正则（#queId_<id>$，支持表格嵌套 <id>.<id>）
+_FORMULA_FIELD_REF_RE = re.compile(r"#queId_([^$]+)\$")
 
 
 class AppFormValidationError(ValueError):
@@ -460,3 +462,82 @@ def validate_declaration(
         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)}
+
+
+def validate_formula_expression(
+    formula: str,
+    fields: list[dict[str, Any]] | None = None,
+) -> list[dict[str, str]]:
+    """校验单条公式表达式：函数名合法 + 字段引用存在性。不依赖整份 AppForm，不调后端。
+
+    Args:
+        formula: 公式文本，如 ``CONCAT(#queId_101$, "：", #queId_102$)``。
+        fields: 字段清单 ``[{queId, name}]``（兼容 ``que_id``/``id``）；提供时校验字段引用存在性，
+            不提供时跳过字段引用校验。
+    Returns:
+        错误列表 ``[{pointer, message}]``，空列表表示本地语法通过。
+    """
+    errors: list[dict[str, str]] = []
+    if not isinstance(formula, str) or not formula.strip():
+        errors.append({"pointer": "formula", "message": "formula is empty"})
+        return errors
+
+    # 函数名合法性（复用 AppForm formula Schema 的函数目录）
+    supported = _supported_formula_functions("v1alpha1")
+    unknown = sorted(
+        name for name in _formula_function_calls(formula) if name.upper() not in supported
+    )
+    for name in unknown:
+        errors.append({"pointer": "formula", "message": f"unsupported formula function '{name}'"})
+
+    # 字段引用存在性（#queId_<id>$，支持表格嵌套 <id>.<id>，按叶子 id 与原始 id 双重匹配）
+    if fields:
+        known_ids = {
+            str(identifier)
+            for field in fields
+            if isinstance(field, dict)
+            for identifier in (
+                field.get("queId"),
+                field.get("que_id"),
+                field.get("id"),
+            )
+            if identifier is not None and str(identifier) != ""
+        }
+        for match in _FORMULA_FIELD_REF_RE.finditer(formula):
+            raw_id = match.group(1)
+            leaf_id = raw_id.split(".")[-1]
+            if leaf_id not in known_ids and raw_id not in known_ids:
+                errors.append(
+                    {
+                        "pointer": "formula",
+                        "message": f"field reference '{match.group(0)}' refers to unknown queId {raw_id}",
+                    }
+                )
+    return errors
+
+
+def validate_code_block_static(code: str) -> list[dict[str, str]]:
+    """校验代码块静态结构：qf_output 赋值 + 基本语法。不调后端。
+
+    Args:
+        code: 代码文本。
+    Returns:
+        错误列表 ``[{pointer, message}]``，空列表表示本地静态校验通过。
+    """
+    errors: list[dict[str, str]] = []
+    if not isinstance(code, str) or not code.strip():
+        errors.append({"pointer": "code", "message": "code is empty"})
+        return errors
+
+    # qf_output 必须直接赋值（不能用 const/let 声明）；仅当代码涉及 outputs 绑定时才提示
+    has_qf_output = bool(re.search(r"(^|[^A-Za-z0-9_$])qf_output\s*=(?!=)", code))
+    has_outputs_binding = "outputs" in code
+    if not has_qf_output and has_outputs_binding:
+        errors.append(
+            {
+                "pointer": "code",
+                "message": "code declares outputs but does not assign qf_output; "
+                "use 'qf_output = {...}' (not const/let)",
+            }
+        )
+    return errors

package/src/qingflow_mcp/cli/commands/builder.py

@@ -2,9 +2,15 @@ from __future__ import annotations
 
 import argparse
 from copy import deepcopy
+from pathlib import Path
 
 from ..context import CliContext
-from ...app_form_validator import AppFormValidationError, validate_declaration
+from ...app_form_validator import (
+    AppFormValidationError,
+    validate_code_block_static,
+    validate_declaration,
+    validate_formula_expression,
+)
 from ..json_io import load_json_value
 from .common import load_list_arg, load_object_arg, parse_bool_text, raise_config_error, require_list_arg
 
@@ -123,6 +129,41 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     app_form_validate.add_argument("--schema-version", help="固定使用的 AppForm Schema 版本")
     app_form_validate.set_defaults(handler=_handle_app_form_validate, format_hint="builder_summary", force_json_output=True)
 
+    app_form_validate_formula = app_form_subparsers.add_parser(
+        "validate-formula", help="校验公式表达式（本地语法 + 后端求值）"
+    )
+    app_form_validate_formula.add_argument("--app-key", required=True, help="目标应用 key")
+    app_form_validate_formula.add_argument("--formula", required=True, help="公式文本")
+    app_form_validate_formula.add_argument(
+        "--test-case",
+        required=True,
+        help="测试用例 JSON 文件路径，- 表示 stdin；格式 {queId: value}",
+    )
+    app_form_validate_formula.add_argument(
+        "--fields",
+        required=False,
+        help="字段清单 JSON 文件路径（用于本地字段引用校验）；缺省时从后端拉取",
+    )
+    app_form_validate_formula.set_defaults(
+        handler=_handle_app_form_validate_formula, format_hint="builder_summary", force_json_output=True
+    )
+
+    app_form_validate_code_block = app_form_subparsers.add_parser(
+        "validate-code-block", help="校验代码块（本地静态 + 后端真跑）"
+    )
+    app_form_validate_code_block.add_argument("--app-key", required=True, help="目标应用 key")
+    app_form_validate_code_block.add_argument(
+        "--code", required=True, help="代码文本（或 @文件路径读取）"
+    )
+    app_form_validate_code_block.add_argument(
+        "--test-case",
+        required=True,
+        help="测试用例 JSON 文件路径，- 表示 stdin；格式 [{keyQueId, ordinal?, values}]",
+    )
+    app_form_validate_code_block.set_defaults(
+        handler=_handle_app_form_validate_code_block, format_hint="builder_summary", force_json_output=True
+    )
+
     app = builder_subparsers.add_parser("app", help="应用")
     app_subparsers = app.add_subparsers(dest="builder_app_command", required=True)
 
@@ -390,6 +431,168 @@ def _handle_app_form_validate(args: argparse.Namespace, _context: CliContext) ->
     return {"category": "validation", "status": "success", "ok": True, **result, "message": "AppForm declaration is valid"}
 
 
+def _handle_app_form_validate_formula(args: argparse.Namespace, context: CliContext) -> dict:
+    formula = args.formula
+    test_case = load_json_value(
+        args.test_case, option_name="--test-case", max_bytes=1 * 1024 * 1024, max_depth=32
+    )
+    if not isinstance(test_case, dict):
+        raise_config_error(
+            "--test-case must be a JSON object {queId: value}", error_code="INVALID_TEST_CASE"
+        )
+
+    # ① 本地语法校验（函数名 + 字段引用存在性）
+    fields = _load_fields_for_validation(args, context)
+    syntax_errors = validate_formula_expression(formula, fields)
+
+    # ② 后端求值校验（语法有错时不浪费后端调用）
+    evaluation = None
+    evaluation_error = None
+    if not syntax_errors:
+        result = context.builder.app_form_evaluate_formula(
+            profile=args.profile, app_key=args.app_key, formula=formula, test_case=test_case
+        )
+        evaluation = result.get("evaluation")
+        evaluation_error = result.get("evaluationError")
+
+    ok = bool(
+        not syntax_errors
+        and isinstance(evaluation, dict)
+        and evaluation.get("valid") is True
+    )
+    return {
+        "category": "validation",
+        "status": "success" if ok else "failed",
+        "ok": ok,
+        "syntaxErrors": syntax_errors,
+        "evaluation": evaluation,
+        "evaluationError": evaluation_error,
+        "message": "formula is valid" if ok else "formula validation failed",
+    }
+
+
+def _handle_app_form_validate_code_block(args: argparse.Namespace, context: CliContext) -> dict:
+    code = _read_code_arg(args.code)
+    test_case = load_json_value(
+        args.test_case, option_name="--test-case", max_bytes=1 * 1024 * 1024, max_depth=32
+    )
+    if not isinstance(test_case, list):
+        raise_config_error(
+            "--test-case must be a JSON array [{keyQueId, ordinal?, values}]",
+            error_code="INVALID_TEST_CASE",
+        )
+
+    # ① 本地静态校验（qf_output 赋值 + 基本语法）
+    static_errors = validate_code_block_static(code)
+
+    # ② 后端真跑校验（静态有错时不浪费后端调用）
+    key_que_values = _normalize_code_block_test_case(test_case)
+    run_result = None
+    run_error = None
+    if not static_errors:
+        result = context.builder.app_form_run_code_block(
+            profile=args.profile, app_key=args.app_key, code=code, key_que_values=key_que_values
+        )
+        run_result = result.get("runResult")
+        run_error = result.get("runError")
+
+    ok = not static_errors and run_result is not None
+    return {
+        "category": "validation",
+        "status": "success" if ok else "failed",
+        "ok": ok,
+        "staticErrors": static_errors,
+        "runResult": run_result,
+        "runError": run_error,
+        "message": "code block is valid" if ok else "code block validation failed",
+    }
+
+
+def _load_fields_for_validation(args: argparse.Namespace, context: CliContext) -> list[dict] | None:
+    """加载字段清单：优先 --fields 参数，缺省时从后端拉取应用字段。
+
+    后端拉取失败时返回 None（跳过字段引用校验，不阻断流程）。
+    """
+    fields_path = getattr(args, "fields", None)
+    if fields_path:
+        fields = load_json_value(
+            fields_path, option_name="--fields", max_bytes=2 * 1024 * 1024, max_depth=64
+        )
+        if not isinstance(fields, list):
+            raise_config_error(
+                "--fields must be a JSON array of field objects", error_code="INVALID_FIELDS"
+            )
+        return fields
+    fetched = context.builder.app_get_fields(profile=args.profile, app_key=args.app_key)
+    if not isinstance(fetched, dict) or fetched.get("status") != "success":
+        return None
+    raw_fields = fetched.get("fields")
+    if not isinstance(raw_fields, list):
+        return None
+    return [
+        {"queId": field.get("que_id"), "name": field.get("name")}
+        for field in raw_fields
+        if isinstance(field, dict)
+    ]
+
+
+def _read_code_arg(code_arg: str) -> str:
+    """读取 --code 参数：@ 前缀读文件内容，否则当文本。"""
+    if not isinstance(code_arg, str) or not code_arg:
+        raise_config_error("--code is required", error_code="INVALID_CODE")
+    if code_arg.startswith("@"):
+        path = code_arg[1:]
+        try:
+            return Path(path).expanduser().read_text(encoding="utf-8")
+        except OSError as exc:
+            raise_config_error(
+                f"failed to read --code from '{path}': {exc}", error_code="INVALID_CODE"
+            )
+    return code_arg
+
+
+def _normalize_code_block_test_case(test_case: list) -> list[dict]:
+    """将 --test-case 规范化为后端 OpenMatchQueValue 结构 [{keyQueId, ordinal?, values}]。"""
+    normalized: list[dict] = []
+    for item in test_case:
+        if not isinstance(item, dict):
+            raise_config_error(
+                "--test-case items must be JSON objects {keyQueId, ordinal?, values}",
+                error_code="INVALID_TEST_CASE",
+            )
+        raw_que_id = item.get("keyQueId", item.get("key_que_id"))
+        if raw_que_id is None:
+            raise_config_error(
+                "--test-case items require keyQueId", error_code="INVALID_TEST_CASE"
+            )
+        try:
+            key_que_id = int(raw_que_id)
+        except (TypeError, ValueError):
+            raise_config_error(
+                f"--test-case keyQueId must be an integer, got {raw_que_id!r}",
+                error_code="INVALID_TEST_CASE",
+            )
+        entry: dict = {"keyQueId": key_que_id}
+        if item.get("ordinal") is not None:
+            try:
+                entry["ordinal"] = int(item.get("ordinal"))
+            except (TypeError, ValueError):
+                raise_config_error(
+                    f"--test-case ordinal must be an integer, got {item.get('ordinal')!r}",
+                    error_code="INVALID_TEST_CASE",
+                )
+        values = item.get("values", [])
+        if not isinstance(values, list):
+            raise_config_error(
+                "--test-case item values must be a JSON array", error_code="INVALID_TEST_CASE"
+            )
+        entry["values"] = [str(value) for value in values]
+        if item.get("tableValues") is not None:
+            entry["tableValues"] = item.get("tableValues")
+        normalized.append(entry)
+    return normalized
+
+
 def _handle_app_delete(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_delete(profile=args.profile, app_key=args.app_key)
 

package/src/qingflow_mcp/public_surface.py

@@ -144,6 +144,8 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(BUILDER_DOMAIN, "app_resolve", ("app_resolve",), ("builder", "app", "resolve"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_form_schema", ("app_form_schema",), ("builder", "app-form", "schema")),
     PublicToolSpec(BUILDER_DOMAIN, "app_form_validate", (), ("builder", "app-form", "validate"), mcp_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "app_form_validate_formula", (), ("builder", "app-form", "validate-formula"), mcp_public=False),
+    PublicToolSpec(BUILDER_DOMAIN, "app_form_validate_code_block", (), ("builder", "app-form", "validate-code-block"), mcp_public=False),
     PublicToolSpec(BUILDER_DOMAIN, "app_form_get", ("app_form_get",), ("builder", "app-form", "get"), cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_form_apply", ("app_form_apply",), ("builder", "app-form", "apply"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_delete", ("app_delete",), ("builder", "app", "delete"), cli_show_effective_context=True, cli_context_write=True),

package/src/qingflow_mcp/response_trim.py

@@ -51,6 +51,10 @@ COMMON_ERROR_DROP_TOP = {
 
 SUCCESS_POLICY_BY_TOOL: dict[str, TransformFn] = {}
 
+#: 这两个校验命令的产出契约明确包含 ok 字段（供阶段 2 SKILL.md 引用），
+#: 需在 success 裁剪时保留 ok（默认 COMMON_SUCCESS_DROP_TOP 会丢弃 ok）。
+_KEEP_OK_TOOLS = {"builder:app_form_validate_formula", "builder:app_form_validate_code_block"}
+
 
 def trim_public_response(tool_name: str | None, payload: dict[str, Any]) -> dict[str, Any]:
     if not isinstance(payload, dict):
@@ -85,6 +89,8 @@ def trim_success_response(tool_name: str | None, payload: dict[str, Any]) -> dic
         drop_keys = COMMON_SUCCESS_DROP_TOP - {"output_profile"}
     if tool_name in {"user:record_insert", "user:record_update", "user:record_delete"} and payload.get("ok") is False:
         drop_keys = drop_keys - {"ok"}
+    if tool_name in _KEEP_OK_TOOLS:
+        drop_keys = drop_keys - {"ok"}
     if tool_name == "builder:app_form_apply" and payload.get("mustReadCurrentStateBeforeRepair") is True:
         drop_keys = drop_keys - {"suggested_next_call"}
     _drop_top_keys(trimmed, drop_keys)

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -852,6 +852,64 @@ class AiBuilderTools(ToolBase):
         """Reconcile one complete declarative AppForm target."""
         return self._app_form.apply(profile=profile, spec=spec)
 
+    def app_form_evaluate_formula(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        formula: str,
+        test_case: dict[int, Any],
+    ) -> JSONObject:
+        """调用后端 POST /ai/coding/formula/validate 对公式求值。
+
+        本地语法校验由 CLI handler 负责；本方法只做后端求值，捕获后端错误为 evaluationError。
+        鉴权/会话错误（未登录/未选工作区）按既有约定向上抛出 QingflowApiError。
+        """
+        _session_profile, _backend_session, context = self._require_context(profile, require_workspace=True)
+        evaluation_result: Any = None
+        evaluation_error: str | None = None
+        try:
+            evaluation_result = self.backend.request(
+                "POST",
+                context,
+                "/ai/coding/formula/validate",
+                json_body={"appKey": app_key, "formula": formula, "testCase": test_case},
+            )
+        except QingflowApiError as exc:
+            evaluation_error = exc.message
+        return {"evaluation": evaluation_result, "evaluationError": evaluation_error}
+
+    def app_form_run_code_block(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        code: str,
+        key_que_values: list[JSONObject],
+    ) -> JSONObject:
+        """调用后端 POST /data/{appKey}/codeBlock/detection 真跑代码块。
+
+        本地静态校验由 CLI handler 负责；本方法只做后端真跑，捕获后端错误为 runError。
+        ``key_que_values`` 需符合后端 OpenMatchQueValue 结构 ``{keyQueId, ordinal?, values}``。
+
+        传入的 ``code`` 是原始 JS（未经前端字段公式加密），必须声明 ``unEncrypted=True``；
+        否则后端 ``DataSvcImpl.codeBlockTest`` 会走 ``FormulaDecoder.extractFormula``
+        对原始 JS 解密并抛 ``QFRuntimeException``，导致后端真跑对所有真实代码必然失败。
+        """
+        _session_profile, _backend_session, context = self._require_context(profile, require_workspace=True)
+        run_result: Any = None
+        run_error: str | None = None
+        try:
+            run_result = self.backend.request(
+                "POST",
+                context,
+                f"/data/{app_key}/codeBlock/detection",
+                json_body={"code": code, "keyQueValues": key_que_values, "unEncrypted": True},
+            )
+        except QingflowApiError as exc:
+            run_error = exc.message
+        return {"runResult": run_result, "runError": run_error}
+
     def app_delete(self, *, profile: str, app_key: str) -> JSONObject:
         """Delete an application explicitly."""
         return self._app_form.delete(profile=profile, app_key=app_key)