@qingflow-tech/qingflow-cli 1.1.48 → 1.1.50

package/skills/qingflow-common/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qingflow-common
-description: 解释轻流公共业务概念并选择 CLI 或 MCP 入口。用于能力比较、记录与任务操作、表单与流程搭建的任务分流，以及从 AI 对话进入页面查看结果、继续编辑、处理业务或进入工作区的场景。
+description: Explain shared Qingflow concepts, choose the CLI or MCP surface, and route resource work or page-link delivery to the relevant domain Skill.
 ---
 
 # Qingflow Common Concepts
@@ -19,7 +19,8 @@ Do not require both surfaces. If only one is installed, complete the workflow on
 ## Shared Concepts
 
 - **AppForm** is the versioned declarative definition for an application form: app metadata, fields, sections, layout, settings, and field configuration. The same JSON declaration is used by CLI and Qingflow MCP.
-- **Record** is runtime data written to an existing app. Use the record schema before an insert, update, import, or analysis workflow.
+- **Data** 是既有应用中的普通业务数据。查询、单条读取和直接增删改默认使用视图无关的 data 入口，并以当次 schema、字段能力和访问范围为准。
+- **Record** 用于详情页附件／图片、完整日志、导入、代码块，以及用户明确指定的 record 命令；不要把普通应用数据工作路由到 record。
 - **Task** is a workflow work item. Prefer task operations for approval, transfer, rollback, and assignee actions.
 - **Builder resource** is package, app, view, chart, portal, navigation, or workflow configuration. It is separate from record data.
 - **Schema version** is part of the public contract. Pin it for one AppForm or workflow operation and do not combine values from different versions.
@@ -30,11 +31,13 @@ Do not require both surfaces. If only one is installed, complete the workflow on
 | --- | --- | --- |
 | Form schema/read/apply/delete | `qingflow --json builder app-form ...` / `builder app delete` | `app_form_schema`, `app_form_get`, `app_form_apply`, `app_delete` |
 | AppForm static validation | `qingflow --json builder app-form validate --file ...` | Performed inside `app_form_apply`; no separate tool |
-| Record and task work | `qingflow --json record ...` / `task ...` | Qingflow MCP record and task tools |
+| 普通应用数据查询与直接增删改 | `qingflow --json data ...` | Qingflow MCP `data_query/get/insert/update/delete` |
+| 日志、附件、导入、代码块或用户指定的 record 命令 | `qingflow --json record ...` / `import ...` | Qingflow MCP 对应 record/import 专项工具 |
+| 待办与流程动作 | `qingflow --json task ...` | Qingflow MCP task tools |
 | 免登录打开网页或指定业务页面 | `qingflow --json auth login-link [--redirect-path PATH]` | `get_login_link` |
 | Package, view, portal, chart, workflow | `qingflow --json builder ...` | Qingflow MCP configuration tools |
 
-The operation names and payload schemas are defined by the public surface. Use the current Schema or tool input schema as the source of truth, not a legacy command name or backend payload.
+The operation names and payload schemas are defined by the public surface. Use the current Schema or tool input schema as the source of truth, not another command's shape or a backend payload.
 
 ## Package Boundaries
 
@@ -43,20 +46,10 @@ The operation names and payload schemas are defined by the public surface. Use t
 
 Each package includes this common Skill. The CLI package installs its CLI guidance; the MCP package installs every MCP domain Skill. The source of every packaged Skill is `qingflow-support/mcp-server/skills/`.
 
-## 从 AI 对话进入轻流页面
+## Deliver Qingflow Page Links
 
-用户需要查看结果、继续编辑、处理业务或进入工作区页面时，MCP 调用 `get_login_link`，CLI 调用 `qingflow --json auth login-link`。纯数据查询无需页面，不自动生成链接。
-
-- 目标路径使用用户提供或业务工具确认的站内路径，不根据应用、记录标识猜测地址。
-- 用户明确指定页面但路径未知时继续定位或说明限制，不猜测，也不静默替换成首页。搜索未命中时继续搜索 `login` 或查看服务工具列表，不擅自打开固定正式站点；失败时如实说明。
-
-- 默认使用当前会话及已选工作区；需要指定会话时使用 MCP 的 `profile` 或 CLI 的 `--profile`。
-- `redirect_path` 可选，默认空：省略时进入工作区首页；传入时仅支持以单个 `/` 开头的站内业务路径，可带 query/hash。不得传完整 URL、外部地址、认证入口或多层编码路径。
-- 示例：`get_login_link({})`；指定目标示例：`get_login_link({"redirect_path":"/index/app/123?view=abc"})`。示例标识仅作格式展示，实际目标必须来自用户提供或已经确认的页面信息，不得编造应用、记录标识。
-- 临近交付时再生成，使用返回的 `url`，文案贴合“查看记录”“继续编辑”等上下文，不展示工作区数字 ID 或原始 JSON。
-- CLI 示例：`qingflow --json auth login-link`；指定目标使用 `qingflow --profile default --json auth login-link --redirect-path "/index/app/123?view=abc"`，同样不得编造实际路径。
-- 链接短时有效且仅可使用一次，失效后重新获取，不修改或拼造链接；只交付给请求用户，不写入公共文档或日志。
-- 用户要求“给我链接”时仅交付，不提前消费；要求“打开”时才使用可用浏览器打开。浏览器不可用时提供可点击链接，不假称已经打开。
+- After creating, changing, or installing resources, finish with the result and a clickable entry for each requested primary result. Use confirmed stable `uri` values, deduplicate them, and link only confirmed successes. Do not auto-issue links for data-only answers, intermediate reads, failed or deleted resources, or when the user declines links.
+- When browser login is unknown, issue one fresh link per displayed destination near delivery through the installed surface. Never guess, replace, open, or consume a destination unless authorized. If issuance fails, keep the business result and offer the stable URI as requiring login when available. Follow the CLI Skill or MCP tool description for signing details.
 
 ## Route Next
 

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b1099"
+_FALLBACK_VERSION = "0.2.0b1101"
 
 
 def _resolve_local_pyproject_version() -> str | None:

package/src/qingflow_mcp/backend_client.py

@@ -1,4 +1,5 @@
 from __future__ import annotations
+import os
 
 from dataclasses import dataclass
 from threading import Event
@@ -9,7 +10,14 @@ from uuid import uuid4
 
 import httpx
 
-from .config import DEFAULT_USER_AGENT, get_default_qf_version, get_timeout_seconds, normalize_base_url
+from .config import (
+    DEFAULT_USER_AGENT,
+    get_default_qf_version,
+    get_http_retry_attempts,
+    get_http_retry_base_seconds,
+    get_timeout_seconds,
+    normalize_base_url,
+)
 from .errors import QingflowApiError
 from .json_types import JSONObject, JSONScalar, JSONValue
 
@@ -65,6 +73,7 @@ class BackendClient:
         params: JSONObject | None = None,
         json_body: JSONValue = None,
         unwrap: bool = True,
+        unwrap_inner_envelope: bool = True,
         qf_version: str | None = None,
         ) -> JSONValue:
         return self.public_request_with_meta(
@@ -74,6 +83,7 @@ class BackendClient:
             params=params,
             json_body=json_body,
             unwrap=unwrap,
+            unwrap_inner_envelope=unwrap_inner_envelope,
             qf_version=qf_version,
         ).data
 
@@ -86,6 +96,7 @@ class BackendClient:
         params: JSONObject | None = None,
         json_body: JSONValue = None,
         unwrap: bool = True,
+        unwrap_inner_envelope: bool = True,
         qf_version: str | None = None,
     ) -> BackendResponse:
         return self._request_with_meta(
@@ -95,6 +106,7 @@ class BackendClient:
             json_body=json_body,
             headers=self._base_headers(None, None, qf_version=qf_version),
             unwrap=unwrap,
+            unwrap_inner_envelope=unwrap_inner_envelope,
         )
 
     def public_request_with_headers(
@@ -106,6 +118,7 @@ class BackendClient:
         params: JSONObject | None = None,
         json_body: JSONValue = None,
         unwrap: bool = True,
+        unwrap_inner_envelope: bool = True,
         qf_version: str | None = None,
         headers: dict[str, str] | None = None,
     ) -> BackendResponse:
@@ -119,6 +132,7 @@ class BackendClient:
             json_body=json_body,
             headers=request_headers,
             unwrap=unwrap,
+            unwrap_inner_envelope=unwrap_inner_envelope,
         )
 
     def request(
@@ -130,6 +144,7 @@ class BackendClient:
         params: JSONObject | None = None,
         json_body: JSONValue = None,
         unwrap: bool = True,
+        unwrap_inner_envelope: bool = True,
     ) -> JSONValue:
         return self.request_with_meta(
             method,
@@ -138,6 +153,7 @@ class BackendClient:
             params=params,
             json_body=json_body,
             unwrap=unwrap,
+            unwrap_inner_envelope=unwrap_inner_envelope,
         ).data
 
     def request_with_meta(
@@ -149,6 +165,7 @@ class BackendClient:
         params: JSONObject | None = None,
         json_body: JSONValue = None,
         unwrap: bool = True,
+        unwrap_inner_envelope: bool = True,
     ) -> BackendResponse:
         return self._request_with_meta(
             method,
@@ -162,6 +179,7 @@ class BackendClient:
                 qf_version=context.qf_version,
             ),
             unwrap=unwrap,
+            unwrap_inner_envelope=unwrap_inner_envelope,
         )
 
     def stream_request(
@@ -353,6 +371,7 @@ class BackendClient:
         data: dict[str, Any] | None = None,
         files: dict[str, tuple[str, bytes, str | None]] | None = None,
         unwrap: bool = True,
+        unwrap_inner_envelope: bool = True,
     ) -> JSONValue:
         return self.request_multipart_with_meta(
             method,
@@ -361,6 +380,7 @@ class BackendClient:
             data=data,
             files=files,
             unwrap=unwrap,
+            unwrap_inner_envelope=unwrap_inner_envelope,
         ).data
 
     def request_multipart_with_meta(
@@ -372,6 +392,7 @@ class BackendClient:
         data: dict[str, Any] | None = None,
         files: dict[str, tuple[str, bytes, str | None]] | None = None,
         unwrap: bool = True,
+        unwrap_inner_envelope: bool = True,
     ) -> BackendResponse:
         headers = self._base_headers(
             context.token,
@@ -392,7 +413,12 @@ class BackendClient:
             )
         except httpx.RequestError as exc:
             raise QingflowApiError(category="network", message=str(exc), request_id=headers["Qf-Request-Id"])
-        parsed = self._parse_response(response, headers["Qf-Request-Id"], unwrap=unwrap)
+        parsed = self._parse_response(
+            response,
+            headers["Qf-Request-Id"],
+            unwrap=unwrap,
+            unwrap_inner_envelope=unwrap_inner_envelope,
+        )
         return BackendResponse(
             data=parsed,
             headers=dict(response.headers),
@@ -646,13 +672,26 @@ class BackendClient:
         json_body: JSONValue,
         headers: dict[str, str],
         unwrap: bool,
+        unwrap_inner_envelope: bool = True,
     ) -> BackendResponse:
-        attempts = 2 if method.upper() == "GET" else 1
+        # 评测沉淀的传输层重试回流（eval_replay_flow._http_json 同款）:
+        # 3 次尝试 + 线性退避(base × attempt,即 3s/6s),env 可配。
+        # GET/HEAD 任何网络错误可重试;写方法(POST/PUT/PATCH/DELETE)仅
+        # ConnectError/ConnectTimeout(请求确证未发出)可重试,避免双重写。
+        # HTTP 状态码/业务码错误由 _parse_response 抛出,不属网络错误,不重试。
+        normalized_method = method.upper()
+        attempts = get_http_retry_attempts()
+        retry_base_seconds = get_http_retry_base_seconds()
         last_error: QingflowApiError | None = None
-        for _ in range(attempts):
+        for attempt in range(1, attempts + 1):
             try:
-                response = self._client.request(method.upper(), url, params=params, json=json_body, headers=headers)
-                parsed = self._parse_response(response, headers["Qf-Request-Id"], unwrap=unwrap)
+                response = self._client.request(normalized_method, url, params=params, json=json_body, headers=headers)
+                parsed = self._parse_response(
+                    response,
+                    headers["Qf-Request-Id"],
+                    unwrap=unwrap,
+                    unwrap_inner_envelope=unwrap_inner_envelope,
+                )
                 return BackendResponse(
                     data=parsed,
                     headers=dict(response.headers),
@@ -661,7 +700,18 @@ class BackendClient:
                     qf_response_version=self._extract_response_qf_version(response.headers),
                 )
             except httpx.RequestError as exc:
-                last_error = QingflowApiError(category="network", message=str(exc), request_id=headers["Qf-Request-Id"])
+                retryable = normalized_method in {"GET", "HEAD"} or isinstance(
+                    exc, (httpx.ConnectError, httpx.ConnectTimeout)
+                )
+                last_error = QingflowApiError(
+                    category="network",
+                    message=str(exc),
+                    request_id=headers["Qf-Request-Id"],
+                    details={"retry_attempts": attempt},
+                )
+                if not retryable or attempt >= attempts:
+                    break
+                sleep(retry_base_seconds * attempt)
         assert last_error is not None
         raise last_error
 
@@ -695,7 +745,14 @@ class BackendClient:
         except httpx.RequestError as exc:
             raise QingflowApiError(category="network", message=str(exc), request_id=headers["Qf-Request-Id"])
 
-    def _parse_response(self, response: httpx.Response, request_id: str, *, unwrap: bool) -> JSONValue:
+    def _parse_response(
+        self,
+        response: httpx.Response,
+        request_id: str,
+        *,
+        unwrap: bool,
+        unwrap_inner_envelope: bool = True,
+    ) -> JSONValue:
         payload: JSONValue
         try:
             payload = response.json()
@@ -708,12 +765,25 @@ class BackendClient:
                 backend_code=self._extract_code(payload),
                 request_id=request_id,
                 http_status=response.status_code,
+                details=self._extract_error_details(payload),
             )
         if not unwrap:
             return payload
-        return self._unwrap_payload(payload, request_id, response.status_code)
+        return self._unwrap_payload(
+            payload,
+            request_id,
+            response.status_code,
+            unwrap_inner_envelope=unwrap_inner_envelope,
+        )
 
-    def _unwrap_payload(self, payload: JSONValue, request_id: str, http_status: int) -> JSONValue:
+    def _unwrap_payload(
+        self,
+        payload: JSONValue,
+        request_id: str,
+        http_status: int,
+        *,
+        unwrap_inner_envelope: bool = True,
+    ) -> JSONValue:
         if not isinstance(payload, dict):
             return payload
         if "success" in payload:
@@ -725,7 +795,12 @@ class BackendClient:
                     request_id=request_id,
                     http_status=http_status,
                 )
-            return self._extract_success_data(payload)
+            return self._guard_inner_envelope(
+                self._extract_success_data(payload),
+                request_id,
+                http_status,
+                unwrap_inner_envelope=unwrap_inner_envelope,
+            )
         code = self._extract_code(payload)
         if code not in (None, 0, "0"):
             raise QingflowApiError(
@@ -736,9 +811,44 @@ class BackendClient:
                 http_status=http_status,
             )
         if code in (0, "0"):
-            return self._extract_success_data(payload)
+            return self._guard_inner_envelope(
+                self._extract_success_data(payload),
+                request_id,
+                http_status,
+                unwrap_inner_envelope=unwrap_inner_envelope,
+            )
         return payload
 
+    def _guard_inner_envelope(
+        self,
+        extracted: JSONValue,
+        request_id: str,
+        http_status: int,
+        *,
+        unwrap_inner_envelope: bool,
+    ) -> JSONValue:
+        """双层信封防御：后端错误经 ResponseResult.failure(code, message, body) 转为
+        ``HTTP 200 + 外层 code=0 + data={code, message}`` 形态（内层错误对象被塞进 data）。
+
+        外层信封检查通过后，若提取出的业务 payload 本身携带错误 code，则视为业务失败
+        抛 QingflowApiError，而不是把错误对象当“业务数据”上抛（评测 r2 实测 219 个读面
+        gap 全为此形态）。逐调用方可传 ``unwrap_inner_envelope=False`` 豁免（当某 API 的
+        data.code 是合法业务字段时）。
+        """
+        if not unwrap_inner_envelope or not isinstance(extracted, dict):
+            return extracted
+        inner_code = self._extract_code(extracted)
+        if inner_code in (None, 0, "0"):
+            return extracted
+        raise QingflowApiError(
+            category="backend",
+            message=self._extract_message(extracted) or "Qingflow request failed (inner envelope)",
+            backend_code=inner_code,
+            request_id=request_id,
+            http_status=http_status,
+            details={"envelope": "inner"},
+        )
+
     def _extract_success_data(self, payload: JSONObject) -> JSONValue:
         for key in ("result", "data", "page", "obj"):
             if key in payload:
@@ -759,6 +869,23 @@ class BackendClient:
             return payload.get("code", payload.get("errCode"))
         return None
 
+    def _extract_error_details(self, payload: JSONValue) -> JSONObject | None:
+        """Best-effort extraction of the backend structured error body.
+
+        Qingflow ``ResponseResult.failure(code, message, data)`` serializes the structured error
+        into ``data`` (older/other endpoints may use ``result``), e.g. workflow-spec validation
+        bodies with ``code`` / ``path`` / ``suggestion`` and negotiation payloads like
+        ``currentSpec``. Keeping it on the error lets facades surface backend negotiation
+        contexts instead of swallowing them.
+        """
+        if not isinstance(payload, dict):
+            return None
+        for key in ("result", "data"):
+            body = payload.get(key)
+            if isinstance(body, dict):
+                return dict(body)
+        return None
+
     def _base_headers(
         self,
         token: str | None,
@@ -778,6 +905,9 @@ class BackendClient:
             headers["token"] = token
         if ws_id is not None:
             headers["wsId"] = str(ws_id)
+        # #147/r8: benchmark replay mode flag——backend skips authored topology overrides
+        if os.environ.get("EVAL_PRESERVE_TOPOLOGY", "").lower() in ("1", "true", "yes"):
+            headers["X-Preserve-Topology"] = "true"
         return headers
 
     def _resolve_qf_version(self, explicit_qf_version: str | None) -> tuple[str | None, str]: