@qingflow-tech/qingflow-cli 1.1.48 → 1.1.50

package/src/qingflow_mcp/resource_uri.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote, unquote, urlsplit, urlunsplit
+
+from .config import DEFAULT_WEB_BASE_URL, get_web_base_url
+from .errors import QingflowApiError
+from .json_types import JSONObject
+
+
+SYSTEM_VIEW_NAMES = frozenset({"all", "initiated", "todo", "done", "cc"})
+_ENCODED_OCTET = re.compile(r"%[0-9A-Fa-f]{2}")
+_CLI_RESOURCE_BASE_URL: ContextVar[str | None] = ContextVar(
+    "qingflow_cli_resource_base_url",
+    default=None,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ResourcePath:
+    resource_type: str
+    ws_id: int
+    package_id: int | None = None
+    app_key: str | None = None
+    view_kind: str | None = None
+    view_key: str | None = None
+
+
+@contextmanager
+def cli_resource_base_url(value: str) -> Iterator[None]:
+    """让一次 CLI 调用的资源 URI 使用 QINGFLOW_BASE_URL 对应的网页环境。"""
+    token = _CLI_RESOURCE_BASE_URL.set(value)
+    try:
+        yield
+    finally:
+        _CLI_RESOURCE_BASE_URL.reset(token)
+
+
+def validate_resource_identity(value: object, field: str = "resource_id") -> str:
+    """按资源 URI 单路径段合同校验并返回规范身份，不读取网页域名配置。"""
+    return _validate_identity(value, field)
+
+
+def validate_positive_resource_id(value: object, field: str = "resource_id") -> int:
+    """按资源 URI 数字路径段合同校验正整数，不接受布尔值或浮点截断。"""
+    return int(_positive_int_segment(value, field))
+
+
+def build_resource_uri(
+    *,
+    ws_id: object,
+    resource_type: str,
+    package_id: object = None,
+    app_key: object = None,
+    view_kind: str | None = None,
+    view_key: object = None,
+    web_origin: str | None = None,
+) -> str:
+    """按固定公共合同构造资源 URI，不接受通用目标路由。"""
+    workspace = _positive_int_segment(ws_id, "ws_id")
+    if resource_type == "package":
+        path = f"/resources/ws/{workspace}/package/{_positive_int_segment(package_id, 'package_id')}"
+    elif resource_type == "app":
+        path = f"/resources/ws/{workspace}/app/{_identity_segment(app_key, 'app_key')}"
+    elif resource_type == "view":
+        app_segment = _identity_segment(app_key, "app_key")
+        if view_kind == "custom":
+            view_segment = _identity_segment(view_key, "view_key")
+        elif view_kind == "system":
+            name = str(view_key or "").strip()
+            if name not in SYSTEM_VIEW_NAMES:
+                raise ValueError("system view name is not supported")
+            view_segment = name
+        else:
+            raise ValueError("view_kind must be custom or system")
+        path = f"/resources/ws/{workspace}/app/{app_segment}/view/{view_kind}/{view_segment}"
+    else:
+        raise ValueError("resource_type is not supported")
+    return f"{resolve_resource_web_origin(web_origin)}{path}"
+
+
+def parse_resource_path(value: str) -> ResourcePath:
+    """严格解析资源 pathname，供免登录签发前校验工作区。"""
+    try:
+        parsed = urlsplit(value)
+        if parsed.scheme or parsed.netloc or parsed.query or parsed.fragment or parsed.path != value:
+            raise ValueError
+        parts = parsed.path.split("/")
+        if len(parts) < 6 or parts[:3] != ["", "resources", "ws"]:
+            raise ValueError
+        ws_id = int(_decode_segment(parts[3], "ws_id"))
+        if ws_id <= 0:
+            raise ValueError
+        if len(parts) == 6 and parts[4] == "package":
+            package_id = int(_decode_segment(parts[5], "package_id"))
+            if package_id <= 0:
+                raise ValueError
+            return ResourcePath("package", ws_id, package_id=package_id)
+        if len(parts) == 6 and parts[4] == "app":
+            return ResourcePath("app", ws_id, app_key=_decode_segment(parts[5], "app_key"))
+        if len(parts) == 9 and parts[4] == "app" and parts[6] == "view":
+            app_key = _decode_segment(parts[5], "app_key")
+            view_kind = parts[7]
+            view_key = _decode_segment(parts[8], "view_key")
+            if view_kind == "system" and view_key not in SYSTEM_VIEW_NAMES:
+                raise ValueError
+            if view_kind not in {"custom", "system"}:
+                raise ValueError
+            return ResourcePath("view", ws_id, app_key=app_key, view_kind=view_kind, view_key=view_key)
+    except (TypeError, ValueError, UnicodeError):
+        pass
+    raise ValueError("resource path is invalid")
+
+
+def try_build_resource_uri(**kwargs: Any) -> tuple[str | None, JSONObject | None]:
+    try:
+        return build_resource_uri(**kwargs), None
+    except (QingflowApiError, ValueError, UnicodeError) as error:
+        return None, {
+            "code": "RESOURCE_URI_UNAVAILABLE",
+            "message": f"resource URI was omitted because its identity or web origin is invalid: {error}",
+        }
+
+
+def _positive_int_segment(value: object, field: str) -> str:
+    if isinstance(value, bool):
+        raise ValueError(f"{field} must be a positive integer")
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        raise ValueError(f"{field} must be a positive integer") from None
+    if parsed <= 0 or str(value).strip() != str(parsed):
+        raise ValueError(f"{field} must be a positive integer")
+    return str(parsed)
+
+
+def _normalize_web_origin(value: str) -> str:
+    try:
+        parsed = urlsplit(value.strip())
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.path not in {"", "/"}
+            or parsed.query
+            or parsed.fragment
+            or any(character.isspace() or ord(character) < 32 for character in value)
+        ):
+            raise ValueError
+        _ = parsed.port
+    except (AttributeError, ValueError):
+        raise ValueError("web_origin must be an absolute HTTP(S) origin") from None
+    return urlunsplit((parsed.scheme, parsed.netloc, "", "", ""))
+
+
+def resolve_resource_web_origin(web_origin: str | None = None) -> str:
+    """解析当前调用面的网页根地址；CLI 与 MCP 分别沿用各自的环境配置。"""
+    if web_origin is not None:
+        return _normalize_web_origin(web_origin)
+    cli_base_url = _CLI_RESOURCE_BASE_URL.get()
+    if cli_base_url is None:
+        return get_web_base_url()
+    return _web_origin_from_api_base_url(cli_base_url)
+
+
+def _web_origin_from_api_base_url(value: str) -> str:
+    normalized = value.strip()
+    if not normalized:
+        return DEFAULT_WEB_BASE_URL
+    try:
+        parsed = urlsplit(normalized)
+        host = parsed.hostname or ""
+        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.query
+            or parsed.fragment
+            or any(character.isspace() or ord(character) < 32 for character in normalized)
+        ):
+            raise ValueError
+        _ = parsed.port
+        return _normalize_web_origin(urlunsplit((parsed.scheme, parsed.netloc, "", "", "")))
+    except ValueError:
+        raise QingflowApiError.config_error(
+            "QINGFLOW_BASE_URL 必须是有效的 HTTP(S) API 地址，不包含查询参数、片段或用户凭证"
+        ) from None
+
+
+def _identity_segment(value: object, field: str) -> str:
+    raw = _validate_identity(value, field)
+    return quote(raw, safe="")
+
+
+def _decode_segment(value: str, field: str) -> str:
+    decoded = _validate_identity(unquote(value, errors="strict"), field)
+    if quote(decoded, safe="") != value:
+        raise ValueError(f"{field} must use canonical path encoding")
+    return decoded
+
+
+def _validate_identity(value: object, field: str) -> str:
+    source = str(value or "")
+    if any(ord(character) < 32 or ord(character) == 127 for character in source):
+        raise ValueError(f"{field} must be one safe path segment")
+    raw = source.strip()
+    if not raw:
+        raise ValueError(f"{field} is required")
+    current = raw
+    for _ in range(8):
+        if (
+            current in {".", ".."}
+            or any(character in current for character in "/\\?#")
+            or any(ord(character) < 32 or ord(character) == 127 for character in current)
+        ):
+            raise ValueError(f"{field} must be one safe path segment")
+        decoded = unquote(current, errors="strict")
+        if decoded == current:
+            return raw
+        current = decoded
+    if (
+        current in {".", ".."}
+        or any(character in current for character in "/\\?#")
+        or any(ord(character) < 32 or ord(character) == 127 for character in current)
+    ):
+        raise ValueError(f"{field} must be one safe path segment")
+    if _ENCODED_OCTET.search(current):
+        raise ValueError(f"{field} has excessive encoding")
+    return raw

package/src/qingflow_mcp/response_trim.py

@@ -53,7 +53,7 @@ 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"}
+_KEEP_OK_TOOLS = {"builder:app_form_validate_formula", "builder:app_form_validate_code_block", "builder:app_flow_validate"}
 
 
 def trim_public_response(tool_name: str | None, payload: dict[str, Any]) -> dict[str, Any]:
@@ -313,6 +313,9 @@ def _trim_workspace_list(payload: JSONObject) -> None:
     page = payload.get("page")
     if isinstance(page, dict):
         _trim_item_list(page, "list", allowed=("wsId", "workspaceName", "remark"))
+    selected = payload.get("selected_workspace")
+    if isinstance(selected, dict):
+        payload["selected_workspace"] = _pick(selected, allowed=("wsId", "workspaceName", "remark"))
 
 
 def _trim_workspace_get(payload: JSONObject) -> None:
@@ -326,7 +329,7 @@ def _trim_workspace_get(payload: JSONObject) -> None:
 
 def _trim_app_list_like(payload: JSONObject) -> None:
     payload.pop("apps", None)
-    _trim_item_list(payload, "items", allowed=("app_key", "app_name", "package_name"))
+    _trim_item_list(payload, "items", allowed=("app_key", "app_name", "package_name", "uri"))
 
 
 def _trim_app_get(payload: JSONObject) -> None:
@@ -334,7 +337,7 @@ def _trim_app_get(payload: JSONObject) -> None:
     _trim_nested_item_list(
         payload,
         ("data", "accessible_views"),
-        allowed=("view_id", "name", "analysis_supported", "list_supported", "kind"),
+        allowed=("view_id", "name", "analysis_supported", "list_supported", "kind", "uri"),
     )
 
 
@@ -1107,6 +1110,51 @@ def _trim_app_form_apply(payload: JSONObject) -> None:
         payload.setdefault("details", {})["diff"] = _summarize_form_diff(details_diff)
 
 
+#: app_flow_apply 的 semanticLint 逐条放行上限（#162 D6）：diffSummary 是
+#: 「后端认为改了什么」的唯一依据、semanticLint 是驳回原因，两者是 agent
+#: 闭环修正的输入；超过 cap 加 semantic_lint_truncated 标记。
+FLOW_APPLY_SEMANTIC_LINT_LIMIT = 20
+
+
+def _trim_flow_apply(payload: JSONObject) -> None:
+    """app_flow_apply 专属裁剪：diffSummary 全量保留、semanticLint 保留前
+    FLOW_APPLY_SEMANTIC_LINT 条（每条只留 code/message/severity/path）；
+    appliedSpec/apply_result 大对象仍被通用裁剪（verification 布尔已足够）。
+
+    必须在 _trim_builder_envelope 压缩 details 前先摘出关键明细（通用裁剪
+    会把 list 形明细全裁），调用后回填。"""
+    details = payload.get("details")
+    diff_summary = details.get("diffSummary") if isinstance(details, dict) else None
+    semantic_lint = details.get("semanticLint") if isinstance(details, dict) else None
+    _trim_builder_envelope(payload)
+    preserved: JSONObject = {}
+    if isinstance(diff_summary, dict) and diff_summary:
+        preserved["diffSummary"] = diff_summary
+    if isinstance(semantic_lint, list):
+        projected = [
+            {
+                "code": item.get("code"),
+                "message": item.get("message"),
+                "severity": item.get("severity"),
+                "path": item.get("path"),
+            }
+            for item in semantic_lint
+            if isinstance(item, dict)
+        ]
+        if projected:
+            if len(projected) > FLOW_APPLY_SEMANTIC_LINT_LIMIT:
+                preserved["semanticLint"] = projected[:FLOW_APPLY_SEMANTIC_LINT_LIMIT]
+                preserved["semantic_lint_truncated"] = True
+            else:
+                preserved["semanticLint"] = projected
+    if preserved:
+        merged = payload.get("details")
+        if not isinstance(merged, dict):
+            merged = {}
+            payload["details"] = merged
+        merged.update(preserved)
+
+
 def _trim_form_diff(payload: JSONObject) -> None:
     diff = payload.get("diff")
     if isinstance(diff, dict):
@@ -1148,7 +1196,6 @@ 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)
@@ -1223,6 +1270,7 @@ _register_policy(
     _trim_directory,
 )
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("feedback_submit",), _trim_feedback)
+_register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("get_login_link",), _trim_login_link)
 _register_policy(
     (USER_DOMAIN,),
     (
@@ -1259,12 +1307,14 @@ _register_policy(
         "app_get_flow",
         "app_flow_get_schema",
         "app_flow_get",
+        "app_flow_validate",
+        "app_flow_list_versions",
+        "app_flow_restore_version",
         "app_get_charts",
         "app_get_buttons",
         "app_get_associated_resources",
         "app_schema_apply",
         "app_layout_apply",
-        "app_flow_apply",
         "app_views_apply",
         "app_charts_apply",
         "portal_apply",
@@ -1274,3 +1324,4 @@ _register_policy(
     _trim_builder_list_like,
 )
 _register_policy((BUILDER_DOMAIN,), ("app_form_apply",), _trim_app_form_apply)
+_register_policy((BUILDER_DOMAIN,), ("app_flow_apply",), _trim_flow_apply)

package/src/qingflow_mcp/server.py

@@ -7,6 +7,7 @@ from mcp.server.fastmcp import FastMCP
 from .backend_client import BackendClient
 from .session_store import SessionStore
 from .tools.app_tools import AppTools
+from .tools.data_tools import DataTools
 from .tools.auth_tools import AuthTools
 from .tools.code_block_tools import CodeBlockTools
 from .tools.feedback_tools import FeedbackTools
@@ -249,6 +250,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     TaskContextTools(sessions, backend).register(server)
     RoleTools(sessions, backend).register(server)
     AppTools(sessions, backend).register(server)
+    DataTools(sessions, backend).register(server)
     QingbiReportTools(sessions, backend).register(server)
     PackageTools(sessions, backend).register(server)
     NavigationTools(sessions, backend).register(server)

package/src/qingflow_mcp/server_app_builder.py

@@ -9,6 +9,7 @@ from .config import DEFAULT_PROFILE
 from .response_trim import BUILDER_SERVER_METHOD_MAP, trim_error_response, trim_public_response, wrap_trimmed_methods
 from .session_store import SessionStore
 from .tools.ai_builder_tools import AiBuilderTools
+from .tools.login_link_tools import LOGIN_LINK_DESCRIPTION, LoginLinkTools
 from .tools.auth_tools import AuthTools
 from .tools.feedback_tools import FeedbackTools
 from .tools.file_tools import FileTools
@@ -39,8 +40,18 @@ def build_builder_server() -> FastMCP:
             "Use workspace_icon_catalog_get before creating app packages or portals when supported icon/color candidates are needed; those resources require explicit non-template icon + color. AppForm-created apps derive a stable default icon and color from spec.appName. "
             "app_form_schema plus app_form_get for versioned form work; query app_form_schema with schema_kind=formula before writing defaultType=3 formulas, and use being_draft=true only for editing and the published default for relation or record consumers; use app_get as the default non-form app map read, then app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_get_charts/portal_list/portal_get/view_get/chart_get for focused compatibility or non-form reads, "
             "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
-            "then app_form_apply for complete app form targets, explicit app_delete for application deletion, and app_flow_apply/app_views_apply/app_associated_resources_apply/app_charts_apply/portal_apply/portal_delete for non-form patches. app_custom_buttons_apply is maintenance-only for explicit standalone button work outside normal view design. These apply/delete tools perform validation, normalization, writes, and readback verification where applicable. AppForm publishes only after a draft change or when the published form lags behind; views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, portal delete separates DELETE execution from readback verification, portal pc layout is a 24-column grid and mobile is a 6-column grid so omit position or use layout_preset when unsure, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "then app_form_apply for complete app form targets, explicit app_delete for application deletion, and app_flow_apply/app_views_apply/app_associated_resources_apply/app_charts_apply/portal_apply/portal_delete for non-form patches. app_custom_buttons_apply is maintenance-only for explicit standalone button work outside normal view design. These apply/delete tools perform validation, normalization, writes, and readback verification where applicable. AppForm publishes only after a draft change or when the published form lags behind; views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, portal delete separates DELETE execution from readback verification, portal pc layout is a 24-column grid and mobile is a 6-column grid so omit position or use layout_preset when unsure, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use app_flow_validate as the precheck before writing (it validates the drafted WorkflowSpec offline and never writes), while publish=false only guarantees draft/base-info updates and is a real draft write, not a precheck. "
             "Builder apply/write outputs include schema_version, operation, summary, and resources[]; use resources[].id/key/name/ids/parent as the stable UI and agent display entry, and keep legacy fields such as field_diff/views_diff/chart_results only for compatibility or troubleshooting. "
+            "创建、修改或安装轻流资源后，最终回复主动提供主要结果的可点击页面入口，无需等待用户再次索要。"
+            "采用“完成结果 + 查看入口”，文案使用“在轻流中查看应用／应用包／视图”，不默认称为“继续编辑”。"
+            "默认只交付用户请求的主要结果：安装方案默认提供应用包入口；直接创建或修改应用、视图时提供对应入口；用户明确要求多个主要对象时分别提供。"
+            "使用业务结果中的稳定 `uri`，按 URI 去重，不为全部子资源预签票据；主要对象没有可靠 URI 时说明限制，不猜地址，也不替换为不相关页面。"
+            "部分成功时仅交付已确认成功且可定位的主要结果，保留失败或未验证说明。"
+            "纯数据问答、中间读取、失败资源和删除操作不自动签发；用户明确要求不提供链接时遵从。用户明确要求查看或打开页面时也使用已确认的路径。"
+            "目标浏览器登录态未知时，临近交付用资源 URI 的同源 pathname 调用 get_login_link，为每个实际展示的入口分别签发，使用返回的完整 URL，不额外追问登录态。"
+            "只有已有用户确认同一浏览器、网页域名、账号和工作区已登录且无失效信号的事实时，才直接交付稳定 URI；调用过票据工具、自动化浏览器已登录或之前签发过票据均不能证明用户浏览器已登录，已消费链接不可复用。"
+            "用户未要求打开时不提前打开或消费链接；浏览器不可用时提供可点击链接，不假称已经打开。"
+            "签发失败时说明免登录链接未生成，提供标注“需登录”的稳定 URI 作为备用入口，不重做业务操作。机器结果继续保留稳定 URI，临时登录链接仅用于面向用户交付。 "
             "For existing object parameter replacement, prefer patch_views, patch_buttons, patch_resources, and patch_charts with set/unset; the tool reads current config and full-saves internally, while upsert_* is for creation or full target configuration and should not be used as an incomplete partial update. "
             "For builder delete/remove apply results, separate delete execution from readback verification: after DELETE is sent, resources expose delete_executed, readback_status, and safe_to_retry_delete=false. If readback_status is unavailable or still_exists, do not blindly repeat the delete; confirm later with app_get/view_get/chart_get or the relevant apply readback. Views/buttons use single-item readback; associated resources use one app-level resource-pool readback because there is no confirmed single-item GET. "
             "For builder write/apply results, separate write execution from final readback verification: status=partial_success with write_executed=true and safe_to_retry=false means the write was sent or succeeded, while final readback, publish verification, or metadata confirmation is pending or permission-restricted. Report it as written but unverified; do not repeat the same write blindly. "
@@ -52,7 +63,9 @@ def build_builder_server() -> FastMCP:
             "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, and view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key because the tool resolves those to the internal id. Before creating an associated resource, read app_get.associated_resources and reuse an existing matching target_app_key + view_key/chart_key through patch_resources; client_key only works inside one apply call and is not persisted. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
             "For code_block fields with output bindings, always use qf_output assignment rather than const/let qf_output, and use app_repair_code_blocks when an existing form hangs because output-bound fields stay loading. "
             "Use package_apply to manage package metadata, visibility, grouping, and ordering, and app_publish_verify for explicit final publish verification. "
-            "For workflow edits, use app_flow_get_schema/app_flow_get when raw WorkflowSpec shape is needed, then app_flow_apply with spec for full replacement or patch_nodes for targeted node edits. Declare node assignees and editable fields explicitly. "
+            "For workflow edits, use app_flow_get_schema/app_flow_get when raw WorkflowSpec shape is needed, then app_flow_validate on the drafted spec as a write-free precheck, then app_flow_apply with spec for full replacement or patch_nodes for targeted node edits. Declare node assignees and editable fields explicitly. Workflow node ids must round-trip: nodes[].id is the numeric audit_node_id string returned by app_flow_get, pass ids back unchanged and never invent them; a spec that drops existing nodes triggers a destructive two-phase apply — the first call returns status=confirmation_required with a preview blueprint, unrebuildable attachment warnings (eSign/print/chart/email/SMS/webhook), and a one-time confirm_ticket; re-invoke app_flow_apply with the same spec plus confirm_ticket to execute, or re-fetch the spec and reuse the original node ids if the intent was update. reason_code SPEC_CHANGED means the spec differed from the preview, BASELINE_DRIFTED means the draft changed underneath (re-fetch first). "            "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
+
+            "For workflow edits, use app_flow_get_schema/app_flow_get when raw WorkflowSpec shape is needed, then app_flow_validate on the drafted spec as a write-free precheck, then app_flow_apply with spec for full replacement or patch_nodes for targeted node edits. Version recovery goes through app_flow_list_versions to discover snapshots (version_id/snapshot_type/time), optional app_flow_get(version_id=...) to inspect a target, then app_flow_restore_version to roll the draft spec back; restore is a draft-domain write under the same maintenance gate and reports readback verification against the target snapshot. Declare node assignees and editable fields explicitly. "
             "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
             "Do not handcraft internal solution payloads or rely on build_id/stage/repair. "
             "If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, first summarize the gap, ask whether to submit feedback, and call feedback_submit only after explicit user confirmation."
@@ -64,6 +77,7 @@ def build_builder_server() -> FastMCP:
     workspace = wrap_trimmed_methods(WorkspaceTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
     files = wrap_trimmed_methods(FileTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
     ai_builder = wrap_trimmed_methods(AiBuilderTools(sessions, backend), BUILDER_SERVER_METHOD_MAP)
+    login_link = LoginLinkTools(sessions, backend)
     feedback = FeedbackTools(backend, mcp_side="App Builder MCP")
 
     @server.tool()
@@ -90,6 +104,10 @@ def build_builder_server() -> FastMCP:
     def auth_logout(profile: str = DEFAULT_PROFILE, forget_persisted: bool = False) -> dict:
         return auth.auth_logout(profile=profile, forget_persisted=forget_persisted)
 
+    @server.tool(description=LOGIN_LINK_DESCRIPTION)
+    def get_login_link(profile: str = DEFAULT_PROFILE, redirect_path: str = "") -> dict:
+        return login_link.get_login_link(profile=profile, redirect_path=redirect_path)
+
     @server.tool()
     def workspace_list(
         profile: str = DEFAULT_PROFILE,
@@ -466,6 +484,41 @@ def build_builder_server() -> FastMCP:
     def app_flow_get_schema(profile: str = DEFAULT_PROFILE, schema_version: str = "") -> dict:
         return ai_builder.app_flow_get_schema(profile=profile, schema_version=schema_version or None)
 
+    @server.tool()
+    def app_flow_validate(
+        profile: str = DEFAULT_PROFILE,
+        spec: dict | None = None,
+        schema_version: str = "",
+    ) -> dict:
+        return ai_builder.app_flow_validate(
+            profile=profile,
+            spec=spec or {},
+            schema_version=schema_version or None,
+        )
+
+    @server.tool()
+    def app_flow_list_versions(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+    ) -> dict:
+        return ai_builder.app_flow_list_versions(profile=profile, app_key=app_key)
+
+    @server.tool()
+    def app_flow_restore_version(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        version_id: str = "",
+        idempotency_key: str = "",
+        schema_version: str = "",
+    ) -> dict:
+        return ai_builder.app_flow_restore_version(
+            profile=profile,
+            app_key=app_key,
+            version_id=version_id,
+            idempotency_key=idempotency_key or None,
+            schema_version=schema_version or None,
+        )
+
     @server.tool()
     def app_flow_apply(
         profile: str = DEFAULT_PROFILE,
@@ -475,6 +528,7 @@ def build_builder_server() -> FastMCP:
         idempotency_key: str = "",
         schema_version: str = "",
         patch_nodes: list[dict] | None = None,
+        confirm_ticket: str = "",
     ) -> dict:
         return ai_builder.app_flow_apply(
             profile=profile,
@@ -484,6 +538,7 @@ def build_builder_server() -> FastMCP:
             idempotency_key=idempotency_key or None,
             schema_version=schema_version or None,
             patch_nodes=patch_nodes,
+            confirm_ticket=confirm_ticket or None,
         )
 
     @server.tool()

package/src/qingflow_mcp/server_app_user.py

@@ -10,6 +10,7 @@ from .config import DEFAULT_PROFILE
 from .response_trim import USER_SERVER_METHOD_MAP, trim_error_response, trim_public_response, wrap_trimmed_methods
 from .session_store import SessionStore
 from .tools.app_tools import AppTools
+from .tools.data_tools import DataTools
 from .tools.auth_tools import AuthTools
 from .tools.code_block_tools import CodeBlockTools
 from .tools.directory_tools import DirectoryTools
@@ -33,12 +34,15 @@ def build_user_server(*, stateless_http: bool = False) -> FastMCP:
 
 ## 页面交接
 
-用户需要查看结果、继续编辑、处理业务或进入工作区页面时，使用 `get_login_link`；纯数据查询不自动签发链接。
+创建、修改或安装轻流资源后，最终回复主动提供主要结果的可点击页面入口，无需等待用户再次索要。采用“完成结果 + 查看入口”，文案使用“在轻流中查看应用／应用包／视图”，不默认称为“继续编辑”。用户明确要求查看或打开页面时也适用以下规则。
+默认只交付用户请求的主要结果：安装方案默认提供应用包入口；直接创建或修改应用、视图时提供对应入口；用户明确要求多个主要对象时分别提供。使用业务结果中的稳定 `uri`，按 URI 去重，不为全部子资源预签票据。
+主要对象没有可靠 URI 时说明限制，不猜地址，也不替换为不相关页面。部分成功时仅交付已确认成功且可定位的主要结果，保留失败或未验证说明。纯数据问答、中间读取、失败资源和删除操作不自动签发；用户明确要求不提供链接时遵从。
 目标路径由业务工具或领域 Skill 根据真实前端路由确定，不由票据工具根据业务标识推导。
 已知目标传可选 `redirect_path`；明确指定页面但路径未知时继续定位或说明限制，不猜测，也不静默改为首页。
 搜索未命中时继续搜索 `login` 或查看服务工具列表，不擅自打开固定正式站点；鉴权或工具失败时如实说明。
-临近交付时再签发，使用返回的完整 URL。要求“给我链接”时仅交付，不提前消费；要求“打开”时才调用浏览器。
-浏览器不可用时提供可点击链接；用“查看记录”“继续编辑”等文案，不展示工作区数字 ID 或原始 JSON。
+目标浏览器登录态未知时，默认用资源 URI 的同源 pathname 调用 `get_login_link`，为每个实际展示的入口分别签发，不额外追问登录态；只有已有用户确认同一浏览器、网页域名、账号和工作区已登录且无失效信号的事实时，才直接交付稳定 URI。调用过票据工具、自动化浏览器已登录或之前签发过票据均不能证明用户浏览器已登录，已消费链接也不能复用。
+临近交付时再签发，使用返回的完整 URL。用户未要求打开时仅交付，不提前消费；要求“打开”时才调用浏览器。签发失败时说明免登录链接未生成，并提供标注“需登录”的稳定 URI 作为备用入口，不重做业务操作。机器结果继续保留稳定 URI，临时登录链接仅用于面向用户交付。
+浏览器不可用时提供可点击链接，不假称已经打开，不展示工作区数字 ID 或原始 JSON。
 链接约 5 分钟内一次性有效，不能作为长期书签；安全验证及原有业务权限不变。
 
 ## App Discovery
@@ -239,6 +243,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     backend = BackendClient()
     auth = wrap_trimmed_methods(AuthTools(sessions, backend), USER_SERVER_METHOD_MAP)
     apps = wrap_trimmed_methods(AppTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    data_tools = wrap_trimmed_methods(DataTools(sessions, backend), USER_SERVER_METHOD_MAP)
     workspace = wrap_trimmed_methods(WorkspaceTools(sessions, backend), USER_SERVER_METHOD_MAP)
     file_tools = wrap_trimmed_methods(FileTools(sessions, backend), USER_SERVER_METHOD_MAP)
     imports = wrap_trimmed_methods(ImportTools(sessions, backend), USER_SERVER_METHOD_MAP)
@@ -392,6 +397,8 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
         return apps.app_get(profile=profile, app_key=app_key)
 
+    data_tools.register(server)
+
     @server.tool()
     def portal_list(profile: str = DEFAULT_PROFILE) -> dict:
         return resources.portal_list(profile=profile)