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

package/README.md

@@ -7,7 +7,7 @@ Qingflow CLI 是轻流面向开发者和 AI Agent 的命令行工具。它把轻
 ## 安装
 
 ```bash
-npm install @qingflow-tech/qingflow-cli@1.1.44
+npm install @qingflow-tech/qingflow-cli@1.1.45-beta.2
 ```
 
 推荐从官网复制这一条一键安装 Qingflow CLI：
@@ -21,7 +21,7 @@ npx qingflow-cli@latest install
 ## 运行
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-cli@1.1.44 qingflow
+npx -y -p @qingflow-tech/qingflow-cli@1.1.45-beta.2 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 qingflow-skills install --agent codex --scope user --copy
+npx -y -p @qingflow-tech/qingflow-cli@1.1.45-beta.2 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",
+  "version": "1.1.45-beta.2",
   "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.44"
+version = "1.1.45b2"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-cli/SKILL.md

@@ -444,7 +444,7 @@ qingflow auth logout --forget-persisted
 | **app / portal / view / chart** | `app list [--query 关键词]` → **`app get --app-key`**（`accessible_views` / `view_id`、`import_capability`）· `builder package list [--query 关键词]` → `builder package get --package-id` · `portal list` · `portal get --dash-key` · `view get --view-id`（只读视图元信息；`baseInfo` 或 `viewConfig` 只有 40002 / 40027 / 404 这类权限/缺失边界可用另一侧降级，非权限类后端错误不隐藏；解析 app 仅依赖同源 view/form 与可见应用树，不回退旧应用搜索）· `chart get --chart-id`（图表 `baseInfo` / 数据 / 配置分阶段读取；单个辅助阶段 40002 / 40027 / 404 只作为 warning，非权限类后端错误不隐藏） |
 | **record** | `record schema insert`（新建记录 insert-ready schema，仅 `--app-key`）· **`browse`/`list`/`access`：`--app-key` + `--view-id`（缺一常 CONFIG）** · `record list --query ... [--query-field FIELD_ID] [--page-size N]` 用于候选定位/样本浏览 · `record get --record-id` 读详情页首屏上下文 · `record logs --record-id` 读完整数据/流程日志 JSONL · `record insert --items-file`（单条也是 items 一行）· `schema update --record-id [--view-id]` / **`update`**（单条 `--fields-file` **或** 批量 `--items-file`/`--dry-run`，二者勿混）· `record delete --app-key --record-id --view-id system:*` / `--record-ids-file` · `export start/direct --view-id` 仅用于明确导出文件 · **大 schema**：先 **[FIELD_DATA_TYPES](./reference/core/QINGFLOW_CLI_FIELD_DATA_TYPES.md)** / **[RECORD_CREATE](./reference/record/QINGFLOW_CLI_RECORD_CREATE_WORKFLOW.md)** / **[RECORD_UPDATE](./reference/record/QINGFLOW_CLI_RECORD_UPDATE_WORKFLOW.md)** / **[RECORD_DELETE](./reference/record/QINGFLOW_CLI_RECORD_DELETE_WORKFLOW.md)**，再 `-h` |
 | **import** | `record schema import?` · `import template` → `verify` → `repair?` → `start`（**`being-enter-auditing` 必填**）→ `status`（**三者 selector 只选一**）；导入权限预检的 `baseInfo` 只有 40002 / 40027 / 404 可降级为 unknown，非权限错误不能当成无导入权或继续执行；**链路与本机目录**只靠本节不够 → **[RECORD_IMPORT](./reference/record/QINGFLOW_CLI_RECORD_IMPORT_WORKFLOW.md)** |
-| **builder** | **搭建／系统化配置**：先按 **[INDEX](./reference/00-INDEX.md)** / **[BUILDER](./reference/builder/README.md)** 选主路径，再读 `builder contract`。**完整系统/应用包**：`builder package apply --config-file` → 每个应用依次执行 `builder app-form schema`、更新时 `get --app-key APP_KEY --being-draft`、`validate --schema-version VERSION --file DECLARATION.json`、`apply --file DECLARATION.json`（固定版本、完整声明、记录返回的 `appKey`）→ 视图（按钮随视图 `action_buttons` 写）→ 门户（缺报表时写 `chart`）→ 发布/回读。旧 `schema apply` / `layout apply` 不在当前 CLI parser 中。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先读取 AppForm draft/published，再恢复，不得重复创建或创建 V2/测试/随机后缀绕过重名。**单应用**：新建和更新遵循同一 AppForm CLI 链路，再按需求配置流程/视图。更新动作归入对应资源文档：AppForm [30](./reference/builder/30-schema-fields.md)、视图 [50](./reference/builder/50-views.md)、报表 [60](./reference/builder/60-charts.md)、门户 [70](./reference/builder/70-portal.md)、关联资源/非主链路按钮维护 [80](./reference/builder/80-buttons-associated-resources.md)、流程 [90](./reference/builder/90-workflow.md)、发布 [99](./reference/builder/99-publish-verify.md)。 |
+| **builder** | **搭建／系统化配置**：先按 **[INDEX](./reference/00-INDEX.md)** / **[BUILDER](./reference/builder/README.md)** 选主路径，再读 `builder contract`。**完整系统/应用包**：`builder package apply --config-file` → 每个应用依次执行 `builder app-form schema`、更新时 `get --app-key APP_KEY --being-draft`、`validate --schema-version VERSION --file DECLARATION.json`、`apply --file DECLARATION.json`（固定版本、完整声明、记录返回的 `appKey`）→ 视图（按钮随视图 `action_buttons` 写）→ 门户（缺报表时写 `chart`）→ 发布/回读。旧 `schema apply` / `layout apply` 不在当前 CLI parser 中。超时、`partial_success`、`write_executed=true`、`safe_to_retry=false` 或回读不完整时先读取 AppForm draft/published，再恢复，不得重复创建或创建 V2/测试/随机后缀绕过重名。**单应用**：新建和更新遵循同一 AppForm CLI 链路，再按需求配置流程/视图。更新动作归入对应资源文档：AppForm [30](./reference/builder/30-schema-fields.md)、视图 [50](./reference/builder/50-views.md)、报表 [60](./reference/builder/60-charts.md)、门户 [70](./reference/builder/70-portal.md)、关联资源/非主链路按钮维护 [80](./reference/builder/80-buttons-associated-resources.md)、流程 [90](./reference/builder/90-workflow.md)、发布 [99](./reference/builder/99-publish-verify.md)。**AI 公式/代码块校验**：`builder app-form validate-formula --app-key KEY --formula '<公式>' --test-case '<{queId: value} JSON>'`（本地语法 + 后端求值，输出 `syntaxErrors` / `evaluation` / `evaluationError`）与 `builder app-form validate-code-block --app-key KEY --code '<代码>' --test-case '<[{keyQueId, ordinal?, values}] JSON 数组>'`（本地静态 + 后端真跑，输出 `staticErrors` / `runResult` / `runError`）；两者是公式/代码块生成场景的真实校验命令，校验结论必须来自其真实执行，不得以本地模拟替代。代码内占位符 `qf_field.{字段名$$queId$$}` 与 `keyQueId` 均使用**十进制** queId（CLI 真跑前自动把十进制占位符编码为运行时形态，已编码段原样保留）。 |
 | **task**（须落盘见上文） | `task list [--task-box][--flow-status][--app-key][--query] --page --page-size`（**枚举、`--query`、与 `record` 视图口径勿混**：见上文 SOP · **[TASK_CONTEXT](./reference/task/QINGFLOW_CLI_TASK_CONTEXT_WORKFLOW.md)**）· **`get`/`log`/`report`/`action`**：默认只传 `task list` 返回的 **`data.items[].task_id`**；`report` 另须必选 **`--report-id`**；`action` **无 `--dry-run`** |
 
 **高发必败**：旧应用搜索入口 · **`record list`/`browse`/`access` 缺 `--view-id`** · **`task report` 缺 `--report-id`** · **`record update` 批量与单条参数混用**。

package/skills/qingflow-cli/reference/builder/30-schema-fields.md

@@ -219,6 +219,8 @@ current CLI payload.
 | `data_relation` | 数据关联/引用填充 |
 | `subtable` | 子表（**`subfields[]`**） |
 
+历史表单中的后端 `queType=1` 是“描述文字”布局控件，不属于上述新建字段类型。`app-form get` 为了保持完整声明可校验，会将它兼容输出为 `long_text`；`app-form apply` 会根据已有字段模板恢复原始 `queType=1` 和 `queDefaultValue`，所以修改其他字段时不会丢失描述文字。新建可填写多行文本仍使用 `long_text`，不要用它创建描述文字控件。
+
 **`config.relationMode`**：仅 **`relation`** 使用，取值为 **`single`** 或 **`multiple`**。一个应用可以有多个 `relation` 字段；不要因为 relation 数量超过 1 就改成文本字段。
 
 ### 1.1 历史字段类型别名
@@ -246,6 +248,10 @@ current CLI payload.
 | `q_linker` | **`config.qLinkerBinding`**：`inputs`、`request`、**`outputs[]` 每项须含 `targetField`**（能解析到本表单字段） | `request.url` 等须符合**租户/后端远程查询策略**；以字段类型 Schema 返回的配置为准 |
 | `code_block` | **`config.codeBlockBinding`**：`inputs`、`code`、**`outputs[]` + `targetField`**；配置 outputs 时，代码必须显式写 **`qf_output = {...}`**，仅 `return {...}` 不会产生可回写结果，且每个 `outputs[].path` 必须从 `qf_output` 取值 | 以字段类型 Schema 返回的 camelCase 配置为准 |
 
+部门字段的 `defaultDepartments` 也遵循同一约束：`custom` 模式必须包含至少一个部门。读取历史后端数据时，如果默认部门值存在但部门列表为空，AppForm 归一化会将其视为“未配置默认部门”并省略 `defaultDepartments`；不要在新声明中写 `departments: []`。
+
+读取历史数据时，空的应用/段落/字段标题会按稳定 ID 生成兼容名称，空行和空筛选组会被忽略；选择项、子表列、序列号组件、Q-Linker 输出和代码源码等语义必需值无法安全推断时，读取会返回结构化 `UNSUPPORTED_FIELD_CONFIG`，不会伪造声明值。`validate/apply` 对新声明仍保持严格 Schema 约束。
+
 别名：契约会把 `title`/`label` 映射到 **`name`** 等；字段类型自然别名见 §1.1。
 
 ### 2.1 `relation` 选择器形态

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,132 @@ 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
+
+
+# ---------------------------------------------------------------------------
+# 代码块字段占位符编码
+#
+# 后端 codeBlockTest 运行时通过 CustomPushContentConverter.getQueId 解码代码里的
+# ``qf_field.{label$$<encoded>$$}`` 段（私有混淆编码，非十进制），再按解码出的十进制
+# queId 匹配 --test-case 的 keyQueId 填值；匹配不上会静默跳过（占位符原样留跑）。
+# AI 生成的代码按十进制 queId 书写（与 skill/编辑器上下文一致），本模块在真跑前把
+# 纯数字的 ``$$<digits>$$`` 段编码为运行时形态——与后端采纳链路（encryptQueId）同一
+# 编码、同一"纯数字才编码"规则，已编码（含字母）的段原样保留，避免双重编码。
+# ---------------------------------------------------------------------------
+
+_ENC_KEY = 1000013
+_INT_TO_HEX = "0123456789ABCDEF"
+_DECIMAL_PLACEHOLDER = re.compile(r"\$\$(-?\d+)\$\$")
+
+
+def encode_que_id(que_id: int) -> str:
+    """Java ``CustomPushContentConverter.encryptQueId`` 的逐行为等价移植。"""
+    have_prefix = que_id < 0
+    abs_id = abs(que_id)
+    ran = abs_id * 17
+    inp = str(abs_id)
+    seeds: list[int] = []
+    salt_sum = 0
+    for _ in range(max(0, 4 - len(inp))):
+        tmp = (ran % 20) + 71
+        ran = ((ran + 13) * 17) % _ENC_KEY
+        salt_sum += tmp
+        seeds.append(tmp)
+    result = [(salt_sum + i + int(ch, 16)) % 15 for i, ch in enumerate(inp)]
+    for seed in seeds:
+        pos = (ran + seed) % len(result)
+        ran = ((ran + 13) * 17) % _ENC_KEY
+        result.insert(pos, seed)
+    encoded = "".join(chr(value) if value > 15 else _INT_TO_HEX[value] for value in result)
+    return ("-" if have_prefix else "") + encoded
+
+
+def encode_code_block_field_ids(code: str) -> str:
+    """把代码里的十进制 queId 占位符段编码为后端运行时形态。
+
+    仅处理纯数字（可带负号）的 ``$$...$$`` 段；混有字母的段视为已编码，原样保留。
+    """
+    if not isinstance(code, str):
+        return code
+    return _DECIMAL_PLACEHOLDER.sub(
+        lambda match: f"$${encode_que_id(int(match.group(1)))}$$", code
+    )

package/src/qingflow_mcp/builder_facade/app_form.py

@@ -31,6 +31,10 @@ from .service import (
 
 API_VERSION = "builder.qingflow.com/v1alpha1"
 QUE_TYPE_TO_CANONICAL = {
+    # Historical description-text controls are read as long_text for the
+    # public declaration shape; the compiler restores queType=1 from the
+    # existing backend template when writing them back.
+    1: "long_text",
     2: "text",
     3: "long_text",
     5: "member",
@@ -227,23 +231,33 @@ def _canonical_member_scope(scope: Any, scope_type: Any, *, department: bool = F
     }
     if department:
         result["departments"] = [
-            _without_none({"deptId": _positive_int(item.get("deptId") or item.get("id")), "deptName": item.get("deptName") or item.get("name")})
+            _without_none(
+                {
+                    "deptId": _positive_int(item.get("deptId") or item.get("id")),
+                    "deptName": _compat_label(item.get("deptName") or item.get("name"), "Department", item.get("deptId") or item.get("id")),
+                }
+            )
             for item in _scope_items(raw, "depart")
             if _positive_int(item.get("deptId") or item.get("id")) is not None
         ]
     else:
         result["members"] = [
-            _without_none({"uid": _positive_int(item.get("uid")), "nickName": item.get("nickName")})
+            _without_none({"uid": _positive_int(item.get("uid")), "nickName": _compat_label(item.get("nickName"), "Member", item.get("uid"))})
             for item in _scope_items(raw, "member")
             if _positive_int(item.get("uid")) is not None
         ]
         result["departments"] = [
-            _without_none({"deptId": _positive_int(item.get("deptId")), "deptName": item.get("deptName")})
+            _without_none(
+                {
+                    "deptId": _positive_int(item.get("deptId")),
+                    "deptName": _compat_label(item.get("deptName"), "Department", item.get("deptId")),
+                }
+            )
             for item in _scope_items(raw, "depart")
             if _positive_int(item.get("deptId")) is not None
         ]
         result["roles"] = [
-            _without_none({"roleId": _positive_int(item.get("roleId")), "roleName": item.get("roleName")})
+            _without_none({"roleId": _positive_int(item.get("roleId")), "roleName": _compat_label(item.get("roleName"), "Role", item.get("roleId"))})
             for item in _scope_items(raw, "role")
             if _positive_int(item.get("roleId")) is not None
         ]
@@ -281,11 +295,12 @@ def _canonical_scope_relation(relation: Any) -> JSONObject | None:
         return None
     displayed = relation.get("displayedQueInfo") if isinstance(relation.get("displayedQueInfo"), dict) else {}
     displayed_id = _positive_int(relation.get("displayedQueId") or displayed.get("queId"))
-    if displayed_id is None or not displayed.get("appKey"):
+    target_app_key = str(displayed.get("appKey") or "")
+    if displayed_id is None or not target_app_key.strip():
         return None
     result: JSONObject = {
         "displayedField": _selector(displayed_id, displayed.get("queTitle")),
-        "targetAppKey": displayed.get("appKey"),
+        "targetAppKey": target_app_key,
         "targetAppTitle": displayed.get("appTitle"),
         "displayedFieldType": displayed.get("queType"),
         "matchRuleType": relation.get("matchRuleType"),
@@ -334,6 +349,22 @@ def _selector(que_id: Any, name: Any) -> JSONObject:
     return result
 
 
+def _compat_label(value: Any, kind: str, identity: Any) -> str:
+    """Give legacy records with an empty display label a stable, non-empty name."""
+    label = str(value or "")
+    if label.strip():
+        return label
+    normalized_identity = str(identity or "").strip()
+    return f"{kind} {normalized_identity}" if normalized_identity else f"Unnamed {kind}"
+
+
+def _required_text(value: Any, *, message: str, details: JSONObject | None = None) -> str:
+    text = str(value or "")
+    if not text.strip():
+        raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", message, "NORMALIZE", details=details)
+    return text
+
+
 def _require_selector(que_id: Any, name: Any, *, message: str, details: JSONObject | None = None) -> JSONObject:
     result = _selector(que_id, name)
     if not result:
@@ -620,21 +651,40 @@ class AppFormNormalizer:
                 section_id = _positive_int(section.get("queId")) or _positive_int(section.get("sectionId"))
                 if section_id is None:
                     raise AppFormFailure("UNSUPPORTED_LAYOUT", "existing section has no stable ID", "NORMALIZE")
-                rows = [
-                    {"fields": [self._field(question, relations, select_scope_relations, field_names, supports_reference_default_formula) for question in inner if isinstance(question, dict)]}
-                    for inner in section.get("innerQuestions") or []
-                    if isinstance(inner, list) and inner
-                ]
+                rows = []
+                for inner in section.get("innerQuestions") or []:
+                    if not isinstance(inner, list) or not inner:
+                        continue
+                    fields = [
+                        self._field(question, relations, select_scope_relations, field_names, supports_reference_default_formula)
+                        for question in inner
+                        if isinstance(question, dict)
+                    ]
+                    if fields:
+                        rows.append({"fields": fields})
                 if not rows:
                     raise AppFormFailure("UNSUPPORTED_LAYOUT", "existing section is empty", "NORMALIZE")
-                body.append({"kind": "section", "sectionId": str(section_id), "title": str(section.get("queTitle") or ""), "rows": rows})
+                body.append(
+                    {
+                        "kind": "section",
+                        "sectionId": str(section_id),
+                        "title": _compat_label(section.get("queTitle"), "Section", section_id),
+                        "rows": rows,
+                    }
+                )
             else:
-                body.append({"kind": "row", "fields": [self._field(question, relations, select_scope_relations, field_names, supports_reference_default_formula) for question in row if isinstance(question, dict)]})
+                fields = [
+                    self._field(question, relations, select_scope_relations, field_names, supports_reference_default_formula)
+                    for question in row
+                    if isinstance(question, dict)
+                ]
+                if fields:
+                    body.append({"kind": "row", "fields": fields})
         resource = {
             "apiVersion": context.api_version,
             "appKey": app_key,
             "spec": {
-                "appName": str(form.get("formTitle") or ""),
+                "appName": _compat_label(form.get("formTitle"), "App", app_key),
                 "appDescription": form.get("formDesc") or None,
                 "dataTitleField": _selector(title_id, field_names.get(title_id or 0)) if title_id is not None else None,
                 "dataCoverField": _selector(cover_id, field_names.get(cover_id or 0)) if cover_id is not None else None,
@@ -676,18 +726,27 @@ class AppFormNormalizer:
                 details={"queId": que_id, "queType": que_type},
             )
         field: JSONObject = {
-            "name": str(question.get("queTitle") or ""),
+            "name": _compat_label(question.get("queTitle"), "Field", que_id),
             "questionType": field_type,
             "beingRequired": bool(question.get("required")),
             "questionDescription": question.get("queHint") or None,
         }
         default_type = _positive_int(question.get("queDefaultType"))
-        if default_type is not None and (
+        raw_default_value = question.get("queDefaultValue")
+        decoded_default_value = (
+            _decode_formula_default(raw_default_value)
+            if isinstance(raw_default_value, (str, int, float, bool))
+            else raw_default_value
+        )
+        empty_formula_default = default_type == 3 and (
+            decoded_default_value is None
+            or (isinstance(decoded_default_value, str) and not decoded_default_value.strip())
+        )
+        if default_type is not None and not empty_formula_default and (
             question.get("queDefaultValue") is not None
             or (default_type != 1 and field_type != "relation")
         ):
             field["defaultType"] = default_type
-        raw_default_value = question.get("queDefaultValue")
         if isinstance(raw_default_value, (dict, list)) and field_type not in {"address", "attachment", "relation", "subtable"}:
             raise AppFormFailure(
                 "UNSUPPORTED_FIELD_CONFIG",
@@ -695,9 +754,14 @@ class AppFormNormalizer:
                 "NORMALIZE",
                 details={"queId": que_id, "type": field_type},
             )
-        if "queDefaultValue" in question and raw_default_value is not None and not isinstance(raw_default_value, (dict, list)):
-            default_value = question.get("queDefaultValue")
-            field["defaultValue"] = _decode_formula_default(default_value)
+        if (
+            "queDefaultValue" in question
+            and raw_default_value is not None
+            and not isinstance(raw_default_value, (dict, list))
+            and not empty_formula_default
+            and not (default_type == 2 and isinstance(decoded_default_value, str) and not decoded_default_value.strip())
+        ):
+            field["defaultValue"] = decoded_default_value
         if que_id is not None:
             field["queId"] = que_id
         width = _positive_int(question.get("queWidth"))
@@ -735,9 +799,20 @@ class AppFormNormalizer:
             if config:
                 field["config"] = config
         elif field_type in CHOICE_TYPES:
-            options = [str(item.get("optValue")) for item in question.get("options") or [] if isinstance(item, dict) and item.get("optValue") is not None]
+            options = [
+                str(item.get("optValue"))
+                for item in question.get("options") or []
+                if isinstance(item, dict) and item.get("optValue") is not None and str(item.get("optValue")).strip()
+            ]
             if not options and field_type == "single_choice":
                 options = ["是", "否"]
+            if not options:
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "choice field has no options",
+                    "NORMALIZE",
+                    details={"queId": que_id, "type": field_type, "path": "/config/options"},
+                )
             field["config"] = _without_none({
                 "options": options,
                 "minOpts": _canonical_unlimited(question.get("minOpts")),
@@ -745,7 +820,14 @@ class AppFormNormalizer:
                 "optDirection": question.get("optDirection") if question.get("optDirection") not in {None, 0} else None,
                 "optSelectMode": question.get("optSelectMode"),
                 "beingShowColor": question.get("beingShowColor"),
-                "defaultOptions": [str(item.get("optValue")) for item in question.get("options") or [] if isinstance(item, dict) and item.get("beingDefault") is True],
+                "defaultOptions": [
+                    str(item.get("optValue"))
+                    for item in question.get("options") or []
+                    if isinstance(item, dict)
+                    and item.get("beingDefault") is True
+                    and item.get("optValue") is not None
+                    and str(item.get("optValue")).strip()
+                ],
             })
             if not field["config"].get("defaultOptions"):
                 field["config"].pop("defaultOptions", None)
@@ -766,7 +848,12 @@ class AppFormNormalizer:
             scope = question.get("deptSelectScope") if isinstance(question.get("deptSelectScope"), dict) else {}
             departments = scope.get("depart") if isinstance(scope.get("depart"), list) else []
             canonical_departments = [
-                _without_none({"deptId": _positive_int(item.get("deptId") or item.get("id")), "deptName": item.get("deptName") or item.get("name")})
+                _without_none(
+                    {
+                        "deptId": _positive_int(item.get("deptId") or item.get("id")),
+                        "deptName": _compat_label(item.get("deptName") or item.get("name"), "Department", item.get("deptId") or item.get("id")),
+                    }
+                )
                 for item in departments
                 if isinstance(item, dict) and _positive_int(item.get("deptId") or item.get("id")) is not None
             ]
@@ -791,7 +878,10 @@ class AppFormNormalizer:
             else:
                 field["config"] = {"departmentScope": {"mode": "all", "includeSubDeparts": bool(scope.get("includeSubDeparts"))}}
             if question.get("deptDftValue") is not None:
-                field["config"]["defaultDepartments"] = _canonical_member_scope(question.get("deptDftValue"), 2, department=True)
+                default_scope = _canonical_member_scope(question.get("deptDftValue"), 2, department=True)
+                # Older backend responses may include an empty default-value container when no default department is set.
+                if default_scope.get("departments"):
+                    field["config"]["defaultDepartments"] = default_scope
             relation = next((item for item in select_scope_relations if _positive_int(item.get("queId")) == que_id), None)
             scope_relation = _canonical_scope_relation(relation)
             if scope_relation is not None:
@@ -800,9 +890,14 @@ class AppFormNormalizer:
                 if question.get(key) is not None:
                     field["config"][key] = question[key]
         elif field_type == "attachment":
+            file_types = question.get("fileType")
+            if isinstance(file_types, list):
+                file_types = [item for item in file_types if str(item or "").strip()]
+            elif isinstance(file_types, str) and not file_types.strip():
+                file_types = None
             field["config"] = _without_none({
                 "fileSize": question.get("fileSize"),
-                "fileType": question.get("fileType"),
+                "fileType": file_types,
                 "fileBeingCaptureOnly": question.get("fileBeingCaptureOnly"),
                 "imageCompress": question.get("imageCompress"),
                 "pluginStatus": question.get("pluginStatus"),
@@ -826,14 +921,22 @@ class AppFormNormalizer:
             display_id = _positive_int(reference.get("referQueId"))
             display = next((item for item in refer_questions if _positive_int(item.get("queId")) == display_id), None)
             visible = [item for item in refer_questions if _positive_int(item.get("queAuth")) != 2]
+            target_app_key = str(reference.get("referAppKey") or "")
+            if not target_app_key.strip():
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "relation target app cannot be normalized",
+                    "NORMALIZE",
+                    details={"queId": que_id, "path": "/config/targetAppKey"},
+                )
             relation_config: JSONObject = {
-                "targetAppKey": reference.get("referAppKey"),
+                "targetAppKey": target_app_key,
                 "relationMode": "multiple" if _positive_int(reference.get("optionalDataNum")) not in {None, 1} else "single",
                 "displayField": _require_selector(
                     display_id,
                     (display or {}).get("queTitle"),
                     message="relation display field cannot be normalized",
-                    details={"queId": que_id},
+                    details={"queId": que_id, "path": "/config/displayField"},
                 ),
                 "visibleFields": [
                     _require_selector(
@@ -849,7 +952,8 @@ class AppFormNormalizer:
                 "defaultValues": question.get("queDefaultValues") if isinstance(question.get("queDefaultValues"), dict) else None,
             }
             if supports_reference_default_formula:
-                relation_config["defaultValueFormula"] = reference.get("defaultValueFormula")
+                formula = reference.get("defaultValueFormula")
+                relation_config["defaultValueFormula"] = formula if not isinstance(formula, str) or formula.strip() else None
             field["config"] = _without_none(relation_config)
         elif field_type == "q_linker":
             field["config"] = {"qLinkerBinding": self._q_linker_binding(question, relations, field_names)}
@@ -858,34 +962,54 @@ class AppFormNormalizer:
         elif field_type == "data_relation":
             field["config"] = self._data_relation_config(question, relations)
         elif field_type == "subtable":
-            field["subfields"] = [
+            subfields = [
                 self._field(item, relations, select_scope_relations, field_names, supports_reference_default_formula)
                 for item in question.get("subQuestions") or []
                 if isinstance(item, dict)
             ]
+            if not subfields:
+                raise AppFormFailure(
+                    "UNSUPPORTED_FIELD_CONFIG",
+                    "subtable has no subfields",
+                    "NORMALIZE",
+                    details={"queId": que_id, "path": "/subfields"},
+                )
+            field["subfields"] = subfields
             for subfield in field["subfields"]:
                 subfield.pop("width", None)
+            row_height = question.get("tableRowHeight")
+            if isinstance(row_height, str) and not row_height.strip():
+                row_height = None
             field["config"] = _without_none({
                 "tableRowsLimit": question.get("tableRowsLimit"),
                 "tableNoRepeatStatus": question.get("tableNoRepeatStatus"),
                 "tableNoRepeatQuestion": [_selector(item, field_names.get(_positive_int(item))) for item in question.get("tableNoRepeatQuestion") or [] if _positive_int(item) is not None],
-                "tableRowHeight": question.get("tableRowHeight"),
+                "tableRowHeight": row_height,
                 "defaultValues": question.get("queDefaultValues") if isinstance(question.get("queDefaultValues"), dict) and (question.get("queDefaultValues", {}).get("values") or question.get("queDefaultValues", {}).get("tableValues")) else None,
             })
         return field
 
     @staticmethod
     def _attachments(value: Any) -> list[JSONObject]:
+        def attachment_text(item: JSONObject, *keys: str) -> Any:
+            for key in keys:
+                candidate = item.get(key)
+                if candidate:
+                    return candidate
+            return None
+
         result = [
             _without_none(
                 {
                     "attachId": _positive_int(item.get("attachId") or item.get("id")),
-                    "fileName": item.get("fileName") or item.get("name"),
-                    "fileUrl": item.get("fileUrl") or item.get("url"),
+                    "fileName": attachment_text(item, "fileName", "name"),
+                    "fileUrl": attachment_text(item, "fileUrl", "url"),
                 }
             )
             for item in value or []
-            if isinstance(item, dict) and (item.get("fileName") or item.get("name")) and (item.get("fileUrl") or item.get("url"))
+            if isinstance(item, dict)
+            and str(attachment_text(item, "fileName", "name") or "").strip()
+            and str(attachment_text(item, "fileUrl", "url") or "").strip()
         ]
         return sorted(result, key=lambda item: (item.get("attachId", 0), item["fileName"], item["fileUrl"]))
 
@@ -907,12 +1031,28 @@ class AppFormNormalizer:
             elif kind == "submit_datetime":
                 component["dateFormat"] = date_names.get(item.get("dateFormat"), "year_month_day")
             elif kind == "fixed_text":
-                component["value"] = str(item.get("customTitle") or "")
+                component["value"] = _required_text(
+                    item.get("customTitle"),
+                    message="custom serial number fixed text is empty",
+                    details={"componentId": _positive_int(item.get("id")), "path": "/spec/serialNumber/components/value"},
+                )
             else:
-                component["field"] = _selector(item.get("queId"), item.get("queTitle"))
+                component["field"] = _require_selector(
+                    item.get("queId"),
+                    item.get("queTitle"),
+                    message="custom serial number field cannot be normalized",
+                    details={"componentId": _positive_int(item.get("id")), "path": "/spec/serialNumber/components/field"},
+                )
                 if item.get("dateFormat") is not None:
                     component["dateFormat"] = date_names.get(item.get("dateFormat"), "year_month_day")
             components.append(component)
+        if not components:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "custom serial number has no components",
+                "NORMALIZE",
+                details={"path": "/spec/serialNumber/components"},
+            )
         return {"mode": "custom", "components": components}
 
     @staticmethod
@@ -926,9 +1066,11 @@ class AppFormNormalizer:
                     for inner in item.get("innerQuestions") or []:
                         for nested in inner if isinstance(inner, list) else []:
                             if isinstance(nested, dict) and _positive_int(nested.get("queId")):
-                                result[_positive_int(nested.get("queId")) or 0] = str(nested.get("queTitle") or "")
+                                nested_id = _positive_int(nested.get("queId")) or 0
+                                result[nested_id] = _compat_label(nested.get("queTitle"), "Field", nested_id)
                 elif _positive_int(item.get("queId")):
-                    result[_positive_int(item.get("queId")) or 0] = str(item.get("queTitle") or "")
+                    item_id = _positive_int(item.get("queId")) or 0
+                    result[item_id] = _compat_label(item.get("queTitle"), "Field", item_id)
         return result
 
     @staticmethod
@@ -939,7 +1081,16 @@ class AppFormNormalizer:
         for alias in config.get("resultFormatPath") or []:
             if not isinstance(alias, dict):
                 continue
-            name = str(alias.get("aliasName") or "")
+            name = _required_text(
+                alias.get("aliasName"),
+                message="Q-Linker output alias is empty",
+                details={"queId": source_id, "path": "/config/qLinkerBinding/outputs/alias"},
+            )
+            path = _required_text(
+                alias.get("aliasPath"),
+                message="Q-Linker output path is empty",
+                details={"queId": source_id, "alias": name, "path": "/config/qLinkerBinding/outputs/path"},
+            )
             relation = next(
                 (
                     item
@@ -953,7 +1104,7 @@ class AppFormNormalizer:
                 _without_none(
                     {
                         "alias": name,
-                        "path": str(alias.get("aliasPath") or ""),
+                        "path": path,
                         "aliasId": _positive_int(alias.get("aliasId")) or _positive_int((relation.get("aliasConfig") or {}).get("aliasId")),
                         "targetField": _require_selector(
                             relation.get("queId"),
@@ -973,15 +1124,30 @@ class AppFormNormalizer:
                     continue
                 if _positive_int(item.get("type")) == 2:
                     input_que_id = _positive_int(item.get("value"))
+                    input_key = _required_text(
+                        item.get("key"),
+                        message="Q-Linker input key is empty",
+                        details={"queId": source_id, "source": source, "path": "/config/qLinkerBinding/inputs/key"},
+                    )
                     inputs.append(
                         {
-                            "field": _selector(input_que_id, field_names.get(input_que_id or -1)),
-                            "key": str(item.get("key") or ""),
+                            "field": _require_selector(
+                                input_que_id,
+                                field_names.get(input_que_id or -1),
+                                message="Q-Linker input field cannot be normalized",
+                                details={"queId": source_id, "key": input_key},
+                            ),
+                            "key": input_key,
                             "source": source,
                         }
                     )
                 else:
-                    static[key].append({"key": str(item.get("key") or ""), "value": item.get("value")})
+                    static_key = _required_text(
+                        item.get("key"),
+                        message="Q-Linker request key is empty",
+                        details={"queId": source_id, "source": source, "path": f"/config/qLinkerBinding/request/{source}/key"},
+                    )
+                    static[key].append({"key": static_key, "value": item.get("value")})
         request_values = {
             "url": config.get("url"),
             "jsonValue": config.get("jsonValue"),
@@ -1013,9 +1179,14 @@ class AppFormNormalizer:
 
             request_values[request_key] = Q_LINKER_VALUE_REFERENCE_RE.sub(replace_reference, raw_value)
         inputs.extend(json_path_inputs.values())
+        request_url = _required_text(
+            request_values["url"],
+            message="Q-Linker request URL is empty",
+            details={"queId": source_id, "path": "/config/qLinkerBinding/request/url"},
+        )
         request = _without_none(
             {
-                "url": request_values["url"],
+                "url": request_url,
                 "method": config.get("method") or "GET",
                 **static,
                 "bodyType": {1: "url_encoded", 2: "json", 3: "xml"}.get(_positive_int(config.get("bodyType")) or 1, "url_encoded"),
@@ -1029,6 +1200,13 @@ class AppFormNormalizer:
                 "hideOnForm": bool(config.get("beingHideOnForm")),
             }
         )
+        if not outputs:
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "Q-Linker has no output mapping",
+                "NORMALIZE",
+                details={"queId": source_id, "path": "/config/qLinkerBinding/outputs"},
+            )
         return {"inputs": inputs, "request": request, "outputs": outputs}
 
     @staticmethod
@@ -1039,7 +1217,16 @@ class AppFormNormalizer:
         for alias in config.get("resultAliasPath") or []:
             if not isinstance(alias, dict):
                 continue
-            name = str(alias.get("aliasName") or "")
+            name = _required_text(
+                alias.get("aliasName"),
+                message="code block output alias is empty",
+                details={"queId": source_id, "path": "/config/codeBlockBinding/outputs/alias"},
+            )
+            path = _required_text(
+                alias.get("aliasPath"),
+                message="code block output path is empty",
+                details={"queId": source_id, "alias": name, "path": "/config/codeBlockBinding/outputs/path"},
+            )
             relation = next(
                 (
                     item
@@ -1051,7 +1238,7 @@ class AppFormNormalizer:
             )
             output = {
                 "alias": name,
-                "path": str(alias.get("aliasPath") or ""),
+                "path": path,
                 "targetField": _require_selector(
                     relation.get("queId"),
                     relation.get("queTitle") or field_names.get(_positive_int(relation.get("queId")) or -1),
@@ -1069,11 +1256,29 @@ class AppFormNormalizer:
             line = lines.pop(0).strip()
             var = line[6:].split("=", 1)[0].strip()
             name = line.split("qf_field.{", 1)[1].split("$$", 1)[0]
-            inputs.append({"field": {"name": name}, "var": var})
+            input_name = _required_text(
+                name,
+                message="code block input field is empty",
+                details={"queId": source_id, "path": "/config/codeBlockBinding/inputs/field"},
+            )
+            inputs.append(
+                {
+                    "field": {"name": input_name},
+                    "var": var,
+                }
+            )
+        code = "\n".join(lines).lstrip("\n")
+        if not code.strip():
+            raise AppFormFailure(
+                "UNSUPPORTED_FIELD_CONFIG",
+                "code block has no code",
+                "NORMALIZE",
+                details={"queId": source_id, "path": "/config/codeBlockBinding/code"},
+            )
         return _without_none(
             {
                 "inputs": inputs,
-                "code": "\n".join(lines).lstrip("\n"),
+                "code": code,
                 "autoTrigger": question.get("autoTrigger"),
                 "customButtonTextEnabled": question.get("customBtnTextStatus"),
                 "customButtonText": question.get("customBtnText"),
@@ -1092,7 +1297,8 @@ class AppFormNormalizer:
         displayed = relation.get("displayedQueInfo") if isinstance(relation.get("displayedQueInfo"), dict) else {}
         alias = relation.get("aliasConfig") if isinstance(relation.get("aliasConfig"), dict) else {}
         if relation_type == 1:
-            if not str(displayed.get("appKey") or "").strip():
+            source_app_key = str(displayed.get("appKey") or "")
+            if not source_app_key.strip():
                 raise AppFormFailure(
                     "UNSUPPORTED_FIELD_CONFIG",
                     "data_relation source app cannot be normalized",
@@ -1101,7 +1307,7 @@ class AppFormNormalizer:
                 )
             source = {
                 "kind": "app",
-                "appKey": displayed.get("appKey"),
+                "appKey": source_app_key,
                 "field": _require_selector(
                     relation.get("displayedQueId"),
                     displayed.get("queTitle"),
@@ -1143,7 +1349,9 @@ class AppFormNormalizer:
             for group in relation.get("matchRules") or []:
                 if not isinstance(group, list):
                     raise AppFormFailure("UNSUPPORTED_FIELD_CONFIG", "data_relation match rules are malformed", "NORMALIZE", details={"queId": que_id})
-                groups.append([AppFormNormalizer._data_relation_condition(item, que_id=que_id) for item in group if isinstance(item, dict)])
+                conditions = [AppFormNormalizer._data_relation_condition(item, que_id=que_id) for item in group if isinstance(item, dict)]
+                if conditions:
+                    groups.append(conditions)
             result["filters"] = {"mode": "simple", "groups": groups}
         sort = relation.get("sortConfig") if isinstance(relation.get("sortConfig"), dict) else None
         if sort is not None:
@@ -2173,6 +2381,11 @@ class AppFormCompiler:
                 "queHint": field.get("questionDescription") or "",
             }
         )
+        if _positive_int((template or {}).get("queType")) == 1 and field_type == "long_text":
+            # queType=1 is a non-data description control. Keep its backend
+            # type and template-only settings while allowing the declaration
+            # to carry its stable identity and default content.
+            question["queType"] = 1
         config = field.get("config") if isinstance(field.get("config"), dict) else {}
         if field_type in {"text", "long_text", "link", "phone", "email"}:
             for key in ("minWordCount", "maxWordCount", "noRepeat", "canScan", "scanType"):

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

@@ -2,9 +2,16 @@ 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,
+    encode_code_block_field_ids,
+    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 +130,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 +432,171 @@ 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)
+    # 后端运行时按 encryptQueId 的编码形态解码代码里的 $$id$$ 段再匹配 test-case 填值；
+    # AI 生成的代码是十进制 queId，先编码归一化（含字母的已编码段原样保留，防双重编码）。
+    code = encode_code_block_field_ids(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)