@qingflow-tech/qingflow-cli 1.1.45 → 1.1.47-beta.1

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

@@ -2,13 +2,32 @@ 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,
+    build_encoded_id_map,
+    referenced_formula_field_ids,
+    translate_formula_test_case_values,
+    encode_code_block_field_ids,
+    referenced_code_block_field_ids,
+    restore_decimal_ids_in_text,
+    strip_placeholder_quotes,
+    translate_select_test_case_values,
+    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
 
 
+# BEGIN temporary flow edit maintenance guard: remove this block when flow editing is restored.
+FLOW_EDIT_MAINTENANCE_NODE_THRESHOLD = 5
+# END temporary flow edit maintenance guard.
+
+
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
     parser = subparsers.add_parser("builder", aliases=["build"], help="稳定 builder 命令")
     builder_subparsers = parser.add_subparsers(dest="builder_command", required=True)
@@ -123,6 +142,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 +444,283 @@ 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;缺省拉全量(保留 option_details 供选择类值翻译)
+    fields_path = getattr(args, "fields", None)
+    if fields_path:
+        fields = _load_fields_for_validation(args, context)
+    else:
+        fields = _load_code_block_validation_fields(args, context) or _load_fields_for_validation(args, context)
+
+    # ① 本地语法校验（函数名 + 字段引用存在性）
+    syntax_fields = [
+        {"queId": f.get("que_id") or f.get("queId"), "name": f.get("name")} for f in (fields or [])
+    ] if fields else None
+    syntax_errors = validate_formula_expression(formula, syntax_fields)
+
+    # ①' 选择类值翻译:实测后端只认 [optId 数组],文案/标量 optId 均报错——把文案自动翻成 [optId]
+    test_case, select_changes, option_errors = translate_formula_test_case_values(fields, test_case)
+
+    # ①'' 覆盖校验:公式引用缺值字段会静默变空(CONCAT 直接跳过)→ 空洞通过,这里拦下
+    referenced_ids = referenced_formula_field_ids(formula)
+    underivable = _underivable_field_ids(fields)
+    covered_ids = {int(k) for k in test_case if str(k).isdigit()}
+    missing_ids = sorted((referenced_ids - covered_ids) - underivable)
+    coverage_errors = [
+        {
+            "pointer": "test-case",
+            "message": f"field queId {que_id} is referenced by formula but has no test-case value "
+            f"(reference would evaluate as empty)",
+        }
+        for que_id in missing_ids
+    ]
+
+    # ② 后端求值校验（本地有错时不浪费后端调用）
+    evaluation = None
+    evaluation_error = None
+    if not syntax_errors and not coverage_errors and not option_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 not coverage_errors
+        and not option_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,
+        "coverageErrors": coverage_errors,
+        "optionErrors": option_errors,
+        "autoFixes": {"selectValuesTranslated": select_changes},
+        "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:
+    raw_code = _read_code_arg(args.code)
+    # 占位符容错:模型常给字段名加引号(qf_field.{"名$$id$$"}),后端替换正则要求结尾恰为
+    # `$$}`,带引号直接匹配失败→占位符原样进 JS→语法错误。先剥离引号再进编码。
+    code_after_quotes, quote_fixes = strip_placeholder_quotes(raw_code)
+    # 后端运行时按 encryptQueId 的编码形态解码代码里的 $$id$$ 段再匹配 test-case 填值；
+    # AI 生成的代码是十进制 queId，先编码归一化（含字母的已编码段原样保留，防双重编码）。
+    code = encode_code_block_field_ids(code_after_quotes)
+    # 错误回显还原映射:后端错误里出现的编码 id 还原为模型写的十进制,避免模型逆向混淆。
+    encoded_id_map = build_encoded_id_map(code_after_quotes)
+    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",
+        )
+
+    # 字段定义(选项翻译/覆盖豁免用;拉取失败不阻断,只是少一层自动修正)
+    fields = _load_code_block_validation_fields(args, context)
+
+    # ① 本地静态校验（qf_output 赋值 + 基本语法）
+    static_errors = validate_code_block_static(code)
+
+    # ①' 选择类值翻译:后端只认选项 optId,传文案静默变 null——把文案自动翻成 optId。
+    key_que_values = _normalize_code_block_test_case(test_case)
+    key_que_values, select_changes, option_errors = translate_select_test_case_values(fields, key_que_values)
+
+    # ①'' 测试覆盖校验：代码引用的字段必须在 test-case 中给值（成员/部门类豁免——
+    # 其值是 uid/部门 id,模型无从得知,代码须自行 null 安全）。缺值时后端会把占位符
+    # 替换成字面量 null 静默跑通（空洞通过）——在这里拦下，逼 test-case 补全而不是放行。
+    covered_ids = _code_block_test_case_field_ids(key_que_values)
+    underivable = _underivable_field_ids(fields)
+    referenced_ids = referenced_code_block_field_ids(raw_code)
+    missing_ids = sorted((referenced_ids - covered_ids) - underivable)
+    coverage_errors = [
+        {
+            "pointer": "test-case",
+            "message": f"field queId {que_id} is referenced by code but has no test-case value "
+            f"(placeholder would run as literal null)",
+        }
+        for que_id in missing_ids
+    ]
+
+    # ② 后端真跑校验（本地有错时不浪费后端调用）
+    run_result = None
+    run_error = None
+    if not static_errors and not coverage_errors and not option_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")
+
+    if isinstance(run_error, str):
+        run_error = restore_decimal_ids_in_text(run_error, encoded_id_map)
+
+    ok = not static_errors and not coverage_errors and not option_errors and run_result is not None
+    return {
+        "category": "validation",
+        "status": "success" if ok else "failed",
+        "ok": ok,
+        "staticErrors": static_errors,
+        "coverageErrors": coverage_errors,
+        "optionErrors": option_errors,
+        "autoFixes": {
+            "placeholderQuotesStripped": quote_fixes,
+            "selectValuesTranslated": select_changes,
+        },
+        "runResult": run_result,
+        "runError": run_error,
+        "message": "code block is valid" if ok else "code block validation failed",
+    }
+
+
+def _load_code_block_validation_fields(
+    args: argparse.Namespace, context: CliContext
+) -> list[dict] | None:
+    """加载字段定义(类型+选项 optId),供选择类值翻译与成员/部门覆盖豁免;失败返回 None。"""
+    try:
+        fetched = context.builder.app_get_fields(profile=args.profile, app_key=args.app_key)
+    except Exception:  # noqa: BLE001 - 字段拉取失败不阻断校验主流程
+        return None
+    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 [field for field in raw_fields if isinstance(field, dict)]
+
+
+def _underivable_field_ids(fields: list[dict] | None) -> set[int]:
+    """值不可由模型推导的字段(成员/部门):test-case 覆盖校验豁免。"""
+    if not fields:
+        return set()
+    result: set[int] = set()
+    for field in fields:
+        field_type = str(field.get("type") or "")
+        if field_type in {"member", "department"}:
+            que_id = field.get("que_id") or field.get("queId")
+            if isinstance(que_id, int):
+                result.add(que_id)
+    return result
+
+
+def _code_block_test_case_field_ids(key_que_values: list[dict]) -> set[int]:
+    """test-case 覆盖的字段 id 集合：顶层 keyQueId + 表格 tableValues 行内 keyQueId。"""
+    covered: set[int] = set()
+    for item in key_que_values:
+        key = item.get("keyQueId")
+        if isinstance(key, int):
+            covered.add(key)
+        for row in item.get("tableValues") or []:
+            if isinstance(row, list):
+                for cell in row:
+                    if isinstance(cell, dict) and isinstance(cell.get("keyQueId"), int):
+                        covered.add(cell["keyQueId"])
+    return covered
+
+
+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)
 
@@ -933,6 +1264,30 @@ def _handle_flow_apply(args: argparse.Namespace, context: CliContext) -> dict:
             "builder flow apply requires exactly one input mode: --spec-file or --patch-nodes-file.",
             fix_hint="Use --spec-file for a complete WorkflowSpec, or --patch-nodes-file for targeted edits after builder flow get.",
         )
+    # BEGIN temporary flow edit maintenance guard: remove this block when flow editing is restored.
+    current_flow = context.builder.app_flow_get(profile=args.profile, app_key=args.app_key)
+    if str(current_flow.get("status") or "").lower() != "success":
+        return current_flow
+    current_node_count = _flow_spec_node_count(current_flow)
+    if current_node_count is None:
+        raise_config_error(
+            "无法读取当前流程节点，未执行流程变更。",
+            fix_hint="当前流程状态无法确认，未执行流程变更。请稍后重试。",
+            error_code="FLOW_STATE_UNAVAILABLE",
+            details={"app_key": args.app_key},
+        )
+    if current_node_count > FLOW_EDIT_MAINTENANCE_NODE_THRESHOLD:
+        raise_config_error(
+            "功能维护中，暂时不允许处理",
+            fix_hint="当前流程节点超过 5 个，流程编辑功能维护中；请稍后重试。",
+            error_code="FLOW_EDIT_UNDER_MAINTENANCE",
+            details={
+                "app_key": args.app_key,
+                "current_node_count": current_node_count,
+                "maintenance_node_threshold": FLOW_EDIT_MAINTENANCE_NODE_THRESHOLD,
+            },
+        )
+    # END temporary flow edit maintenance guard.
     if patch_nodes:
         return context.builder.app_flow_apply(
             profile=args.profile,
@@ -957,6 +1312,18 @@ def _handle_flow_apply(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+# BEGIN temporary flow edit maintenance guard: remove this helper when flow editing is restored.
+def _flow_spec_node_count(flow_result: dict) -> int | None:
+    spec = flow_result.get("spec")
+    if not isinstance(spec, dict):
+        return None
+    nodes = spec.get("nodes")
+    return len(nodes) if isinstance(nodes, list) else None
+
+
+# END temporary flow edit maintenance guard.
+
+
 def _handle_flow_schema(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_flow_get_schema(profile=args.profile, schema_version=args.schema_version)
 

package/src/qingflow_mcp/cli/context.py

@@ -10,6 +10,7 @@ from ..session_store import SessionStore
 from ..tools.ai_builder_tools import AiBuilderTools
 from ..tools.app_tools import AppTools
 from ..tools.auth_tools import AuthTools
+from ..tools.login_link_tools import LoginLinkTools
 from ..tools.code_block_tools import CodeBlockTools
 from ..tools.export_tools import ExportTools
 from ..tools.feedback_tools import FeedbackTools
@@ -27,6 +28,7 @@ class CliContext:
     sessions: CliSessionFacade
     backend: BackendClient
     auth: AuthTools
+    login_link: LoginLinkTools
     workspace: WorkspaceTools
     app: AppTools
     resource: ResourceReadTools
@@ -57,6 +59,7 @@ def build_cli_context() -> CliContext:
         sessions=sessions,
         backend=backend,
         auth=AuthTools(sessions, backend),
+        login_link=LoginLinkTools(sessions, backend),
         workspace=WorkspaceTools(sessions, backend),
         app=AppTools(sessions, backend),
         resource=ResourceReadTools(sessions, backend),

package/src/qingflow_mcp/cli/formatters.py

@@ -1566,7 +1566,12 @@ def _task_action_debug_lines(result: dict[str, Any]) -> list[str]:
     return lines
 
 
+def _format_login_link(result: dict[str, Any]) -> str:
+    return f"登录链接：{result['url']}\n过期时间（Unix 毫秒）：{result['expires_at']}\n链接仅可使用一次，请勿泄露。\n"
+
+
 _FORMATTERS = {
+    "login_link": _format_login_link,
     "auth_whoami": _format_whoami,
     "workspace_list": _format_workspace_list,
     "workspace_get": _format_workspace_get,

package/src/qingflow_mcp/config.py

@@ -2,16 +2,20 @@ from __future__ import annotations
 
 import json
 import os
+import re
 from pathlib import Path
 from typing import Any
 from urllib.parse import urlsplit, urlunsplit
 
+from .errors import QingflowApiError
+
 DEFAULT_PROFILE = "default"
 DEFAULT_TIMEOUT_SECONDS = 30.0
 DEFAULT_USER_AGENT = "qingflow-mcp/1.0"
 DEFAULT_RECORD_LIST_TYPE = 8
 ATTACHMENT_QUESTION_TYPE = 13
 DEFAULT_BASE_URL = "https://qingflow.com/api"
+DEFAULT_WEB_BASE_URL = "https://qingflow.com"
 DEFAULT_CLI_OAUTH_RESOURCE_URL = "https://mcp.qingflow.com/mcp"
 DEFAULT_FEEDBACK_APP_KEY = "e0d017kju002"
 DEFAULT_FEEDBACK_QSOURCE_TOKEN = "mcp-feedback-7755d14748fc"
@@ -153,6 +157,41 @@ def get_default_base_url() -> str | None:
     return normalize_base_url(value) if value else None
 
 
+def get_web_base_url() -> str:
+    """读取网页根地址；空白配置逐级回退，不复用后端或 OAuth 地址。"""
+    value = os.getenv("QINGFLOW_MCP_WEB_BASE_URL")
+    if value is None or not value.strip():
+        value = get_config_value("web_base_url", default=DEFAULT_WEB_BASE_URL)
+    if isinstance(value, str) and not value.strip():
+        value = DEFAULT_WEB_BASE_URL
+    try:
+        if not isinstance(value, str):
+            raise ValueError
+        value = value.strip()
+        parsed = urlsplit(value)
+        host = parsed.hostname or ""
+        # urlsplit 会校验 IPv6；域名标签额外拒绝空格、转义字符及无效边界。
+        valid_host = bool(host) and (":" in host or all(
+            re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?", label)
+            for label in host.rstrip(".").split(".")
+        ))
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not valid_host or host.lower() in {"null", "undefined"}
+            or parsed.username is not None or parsed.password is not None
+            or parsed.path not in {"", "/"} or "?" in value or "#" in value
+            or any(character.isspace() or ord(character) < 32 for character in value)
+        ):
+            raise ValueError
+        # 访问 port 触发 urllib 的端口格式与范围校验。
+        _ = parsed.port
+        return urlunsplit((parsed.scheme, parsed.netloc, "", "", ""))
+    except ValueError:
+        raise QingflowApiError.config_error(
+            "QINGFLOW_MCP_WEB_BASE_URL（web_base_url）必须是有效的 HTTP(S) 网页根地址，不包含路径、查询参数或用户凭证"
+        ) from None
+
+
 def get_default_qf_version() -> str | None:
     """获取默认的 qfVersion 路由值"""
     value = get_config_value(

package/src/qingflow_mcp/public_surface.py

@@ -33,6 +33,7 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "auth_login", cli_route=("auth", "login"), mcp_public=False),
     PublicToolSpec(USER_DOMAIN, "auth_use_credential", ("auth_use_credential",), ("auth", "use-credential")),
     PublicToolSpec(USER_DOMAIN, "auth_whoami", ("auth_whoami",), ("auth", "whoami")),
+    PublicToolSpec(USER_DOMAIN, "get_login_link", ("get_login_link",), ("auth", "login-link")),
     PublicToolSpec(USER_DOMAIN, "auth_logout", ("auth_logout",), ("auth", "logout")),
     PublicToolSpec(USER_DOMAIN, "workspace_list", ("workspace_list",), ("workspace", "list")),
     PublicToolSpec(USER_DOMAIN, "workspace_get", ("workspace_get",), ("workspace", "get")),
@@ -144,6 +145,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)
@@ -1128,6 +1134,13 @@ def _summarize_form_diff(diff: dict[str, Any]) -> dict[str, Any]:
     return summary
 
 
+def _trim_login_link(payload: JSONObject) -> None:
+    # 临时票据只通过链接交付，必须保留链接和过期时间。
+    for key in list(payload):
+        if key not in {"url", "expires_at"}:
+            payload.pop(key)
+
+
 def _register_policy(domains: tuple[str, ...], names: tuple[str, ...], transform: TransformFn) -> None:
     for domain in domains:
         for name in names:
@@ -1135,6 +1148,7 @@ def _register_policy(domains: tuple[str, ...], names: tuple[str, ...], transform
 
 
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("auth_use_credential", "auth_whoami"), _trim_auth_payload)
+_register_policy((USER_DOMAIN,), ("get_login_link",), _trim_login_link)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("auth_logout",), _trim_auth_logout)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("workspace_list",), _trim_workspace_list)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("workspace_get", "workspace_select"), _trim_workspace_get)

package/src/qingflow_mcp/server.py

@@ -13,6 +13,7 @@ from .tools.feedback_tools import FeedbackTools
 from .tools.export_tools import ExportTools
 from .tools.file_tools import FileTools
 from .tools.import_tools import ImportTools
+from .tools.login_link_tools import LoginLinkTools
 from .tools.package_tools import PackageTools
 from .tools.navigation_tools import NavigationTools
 from .tools.directory_tools import DirectoryTools
@@ -238,6 +239,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     sessions = SessionStore()
     backend = BackendClient()
     AuthTools(sessions, backend).register(server)
+    LoginLinkTools(sessions, backend).register(server)
     FeedbackTools(backend, mcp_side="通用").register(server)
     WorkspaceTools(sessions, backend).register(server)
     FileTools(sessions, backend).register(server)

package/src/qingflow_mcp/server_app_user.py

@@ -17,6 +17,7 @@ from .tools.export_tools import ExportTools
 from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
 from .tools.import_tools import ImportTools
+from .tools.login_link_tools import LOGIN_LINK_DESCRIPTION, LoginLinkTools
 from .tools.resource_read_tools import ResourceReadTools
 from .tools.task_context_tools import TaskContextTools
 from .tools.workspace_tools import WorkspaceTools
@@ -30,6 +31,16 @@ def build_user_server(*, stateless_http: bool = False) -> FastMCP:
         stateless_http=stateless_http,
         instructions=f"""Use this server for Qingflow operational workflows. Current date: `{today.isoformat()}`.
 
+## 页面交接
+
+用户需要查看结果、继续编辑、处理业务或进入工作区页面时，使用 `get_login_link`；纯数据查询不自动签发链接。
+目标路径由业务工具或领域 Skill 根据真实前端路由确定，不由票据工具根据业务标识推导。
+已知目标传可选 `redirect_path`；明确指定页面但路径未知时继续定位或说明限制，不猜测，也不静默改为首页。
+搜索未命中时继续搜索 `login` 或查看服务工具列表，不擅自打开固定正式站点；鉴权或工具失败时如实说明。
+临近交付时再签发，使用返回的完整 URL。要求“给我链接”时仅交付，不提前消费；要求“打开”时才调用浏览器。
+浏览器不可用时提供可点击链接；用“查看记录”“继续编辑”等文案，不展示工作区数字 ID 或原始 JSON。
+链接约 5 分钟内一次性有效，不能作为长期书签；安全验证及原有业务权限不变。
+
 ## App Discovery
 
 If `app_key` is unknown, use `app_list` first. Pass `query` to filter visible apps by keyword.
@@ -237,6 +248,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     code_block_tools = wrap_trimmed_methods(CodeBlockTools(sessions, backend), USER_SERVER_METHOD_MAP)
     task_context_tools = wrap_trimmed_methods(TaskContextTools(sessions, backend), USER_SERVER_METHOD_MAP)
     directory_tools = wrap_trimmed_methods(DirectoryTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    login_link = LoginLinkTools(sessions, backend)
 
     @server.tool()
     def auth_use_credential(
@@ -258,6 +270,11 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     def auth_whoami(profile: str = DEFAULT_PROFILE) -> dict:
         return auth.auth_whoami(profile=profile)
 
+    @server.tool(description=LOGIN_LINK_DESCRIPTION)
+    def get_login_link(profile: str = DEFAULT_PROFILE, redirect_path: str = "") -> dict:
+        """获取一次性免登录链接；redirect_path 可选，仅接受站内业务路径，省略进入首页。"""
+        return login_link.get_login_link(profile=profile, redirect_path=redirect_path)
+
     @server.tool()
     def auth_logout(profile: str = DEFAULT_PROFILE, forget_persisted: bool = False) -> dict:
         return auth.auth_logout(profile=profile, forget_persisted=forget_persisted)

package/src/qingflow_mcp/solution/compiler/form_compiler.py

@@ -242,7 +242,6 @@ def build_question(field: dict[str, Any], temp_id: int) -> tuple[dict[str, Any],
             {
                 "referenceConfig": build_reference_config(field, temp_id),
                 "queOriginType": 25,
-                "queDefaultType": 2,
             }
         )
     if field_type == FieldType.code_block: