@qingflow-tech/qingflow-cli 1.1.47-beta.3 → 1.1.47-beta.5

package/README.md

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

package/skills/qingflow-cli/SKILL.md

@@ -130,12 +130,15 @@ qingflow --json auth whoami
 
 默认只交付用户请求的主要结果：安装方案默认提供应用包入口；直接创建或修改应用、视图时提供对应入口；用户明确要求多个主要对象时分别提供。使用业务结果中的稳定 `uri`，按 URI 去重，不为全部子资源预签票据。主要对象没有可靠 URI 时说明限制，不猜地址，也不替换为不相关页面。
 
+CLI 返回的稳定 `uri` 以 `QINGFLOW_BASE_URL` 为当前环境来源：去除末尾 API 路径后使用同一 HTTP(S) 域名；仅当该变量为空时回退 `https://qingflow.com`。若非空配置非法，保留 URI 不可用诊断，不自行替换或拼接其他环境地址。
+
 部分成功时仅交付已确认成功且可定位的主要结果，保留失败或未验证说明。纯数据问答、中间读取、失败资源和删除操作不自动签发；用户明确要求不提供链接时遵从。用户明确要求查看或打开页面时也使用已确认的路径。
 
-目标浏览器登录态未知时，临近交付取该 URI 的 pathname 执行：
+目标浏览器登录态未知时，临近交付取主要结果稳定 `uri` 的完整 pathname 执行，不得丢失应用包、应用或视图层级；视图任务不得退化成应用入口：
 
 ```bash
-qingflow auth login-link --redirect-path "/resources/ws/<WS_ID>/app/<APP_KEY>"
+qingflow auth login-link --redirect-path "<主要结果 uri 的完整 pathname>"
+# 自定义视图 pathname 示例：/resources/ws/<WS_ID>/app/<APP_KEY>/view/custom/<VIEW_KEY>
 ```
 
 对每个实际展示的入口分别签发，使用本次返回的完整 URL，不额外追问登录态，不复用已消费链接。只有已有用户确认同一浏览器、网页域名、账号和工作区已登录、没有失效信号的事实，才直接交付稳定 `uri`。CLI 已登录、自动化浏览器已登录或曾经成功签发票据都不能证明目标浏览器已登录。
@@ -471,10 +474,11 @@ qingflow auth logout --forget-persisted
 
 ```bash
 qingflow --json auth login-link
-qingflow --profile default --json auth login-link --redirect-path "/resources/ws/<WS_ID>/app/<APP_KEY>"
+qingflow --profile default --json auth login-link --redirect-path "<主要结果 uri 的完整 pathname>"
+# 自定义视图 pathname 示例：/resources/ws/<WS_ID>/app/<APP_KEY>/view/custom/<VIEW_KEY>
 ```
 
-- 默认使用当前会话和已选工作区；缺失时按实际错误恢复，不额外预查或重新登录。
+- 默认使用当前会话和已选工作区；缺失时按实际错误恢复，不额外预查或重新登录。pathname 必须保留主要对象的完整层级，视图任务不得改用应用 pathname。
 - `--redirect-path` 可选，仅接受已确认的站内业务路径，可包含 query/hash；不接受外域或认证入口。示例 ID 仅作格式展示，不得照抄或编造实际目标；省略时进入工作区首页。
 - 将返回的 `url` 作为可点击链接交付，不修改或拼造。链接短时有效且仅可使用一次，失效后重新获取，不写入公共文档或日志。
 - 命令不会自动打开浏览器；用户未要求打开时不提前打开或消费链接，明确要求打开时才调用浏览器。

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
@@ -31,7 +31,7 @@ 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 auth login-link [--redirect-path PATH]` | `get_login_link` |
+| Open a workspace or confirmed business page | `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.
@@ -43,29 +43,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 对话进入轻流页面
-
-创建、修改或安装轻流资源后，最终回复主动提供主要结果的可点击页面入口，无需等待用户再次索要。采用“完成结果 + 查看入口”，文案使用“在轻流中查看应用／应用包／视图”，不默认称为“继续编辑”。用户明确要求查看或打开页面时也适用以下规则。
-
-- 默认只交付用户请求的主要结果：安装方案默认提供应用包入口；直接创建或修改应用、视图时提供对应入口；用户明确要求多个主要对象时分别提供。使用业务结果中的稳定 `uri`，按 URI 去重，不为全部子资源预签票据。
-- 主要对象没有可靠 URI 时说明限制，不猜地址，也不替换为不相关页面。部分成功时仅交付已确认成功且可定位的主要结果，保留失败或未验证说明，不把链接当作整个任务成功的证明。
-- 纯数据问答、中间读取、失败资源和删除操作不自动签发；用户明确要求不提供链接时遵从。
-- MCP 调用 `get_login_link`；CLI 调用 `qingflow --json auth login-link --redirect-path <资源 pathname>`。
-
-- 目标路径使用用户提供或业务工具确认的站内路径，不根据应用、记录标识猜测地址。
-- 用户明确指定页面但路径未知时继续定位或说明限制，不猜测，也不静默替换成首页。搜索未命中时继续搜索 `login` 或查看服务工具列表，不擅自打开固定正式站点；失败时如实说明。
-
-- 默认使用当前会话及已选工作区；需要指定会话时使用 MCP 的 `profile` 或 CLI 的 `--profile`。
-- `redirect_path` 可选，默认空：省略时进入工作区首页；传入时仅支持以单个 `/` 开头的站内业务路径，可带 query/hash。不得传完整 URL、外部地址、认证入口或多层编码路径。
-- 示例：`get_login_link({})`；指定目标示例：`get_login_link({"redirect_path":"/index/app/123?view=abc"})`。示例标识仅作格式展示，实际目标必须来自用户提供或已经确认的页面信息，不得编造应用、记录标识。
-- 成功响应仅有 `url` 和毫秒整数 `expires_at`。临近交付时再签发，使用本次返回的完整链接作为主要点击入口，不展示工作区数字 ID 或原始 JSON。
-- CLI 示例：`qingflow --json auth login-link`；指定目标使用 `qingflow --profile default --json auth login-link --redirect-path "/index/app/123?view=abc"`，同样不得编造实际路径。
-- 目标浏览器状态未知时，默认按每个待交付资源分别签发新链接，不额外追问登录态。只有已有用户确认目标是同一浏览器、网页域名、账号和工作区且已登录、没有失效信号的事实，才直接交付稳定 `uri`。调用过票据工具、自动化浏览器已登录或之前签发过票据都不是该事实；已消费链接不可复用。
-- 链接约 5 分钟内只能兑换一次，不作为长期书签；过期或使用后重新调用，不修改票据或拼造链接；只交付给请求用户，不写入公共文档或日志。
-- 用户未要求打开时仅交付，不提前消费；要求“打开”时才使用可用浏览器打开。浏览器不可用时提供可点击链接，不假称已经打开。
-- 签发失败时说明免登录链接未生成，并提供标注“需登录”的稳定 `uri` 作为备用入口，不重做业务操作。机器结果继续保留稳定 URI，临时登录链接仅用于面向用户交付。
-- 必要的 MFA、密码安全验证仍执行，完成后先切换当前 MCP 工作区，再进入目标页面；业务权限仍由目标页面校验，不因链接而扩大。
-- 工具拒绝非法跳转参数；浏览器收到被篡改的非法目标时忽略目标并进入首页。网页域名由 MCP 配置 `QINGFLOW_MCP_WEB_BASE_URL` 决定，不从目标路径选择其他环境。
+## Deliver Qingflow Page Links
+
+- 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/cli/commands/__init__.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import argparse
 
-from . import app, auth, builder, chart, exports, imports, portal, record, task, view, workspace
+from . import app, auth, builder, chart, data, exports, imports, portal, record, task, view, workspace
 
 
 def register_all_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -13,6 +13,7 @@ def register_all_commands(subparsers: argparse._SubParsersAction[argparse.Argume
     view.register(subparsers)
     chart.register(subparsers)
     record.register(subparsers)
+    data.register(subparsers)
     imports.register(subparsers)
     exports.register(subparsers)
     task.register(subparsers)

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

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import argparse
+
+from ..context import CliContext
+from .common import load_list_arg, require_list_arg, require_object_arg, raise_config_error
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("data", help="视图无关的应用数据面")
+    commands = parser.add_subparsers(dest="data_command", required=True, metavar="{query,get,insert,update,delete}")
+
+    query = commands.add_parser("query", help="分页查询应用数据")
+    query.add_argument("--app-key", required=True)
+    query.add_argument("--columns-file")
+    query.add_argument("--where-file")
+    query.add_argument("--sort-file")
+    query.add_argument("--search", default="")
+    query.add_argument("--page", type=int, default=1)
+    query.add_argument("--page-size", type=int, default=100)
+    query.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
+    query.add_argument("--all", action="store_true", dest="all_pages")
+    query.add_argument("--output", choices=("json", "csv"), default="json")
+    query.set_defaults(handler=_handle_query, format_hint="data_query")
+
+    get = commands.add_parser("get", help="读取单条应用数据")
+    get.add_argument("--app-key", required=True)
+    get.add_argument("--record-id", required=True)
+    get.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
+    get.set_defaults(handler=_handle_get, format_hint="data_get")
+
+    insert = commands.add_parser("insert", help="新增应用数据")
+    insert.add_argument("--app-key", required=True)
+    insert.add_argument("--items-file", required=True)
+    insert.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
+    insert.set_defaults(handler=_handle_insert, format_hint="data_insert")
+
+    update = commands.add_parser("update", help="更新应用数据")
+    update.add_argument("--app-key", required=True)
+    update.add_argument("--record-id", required=True)
+    update.add_argument("--fields-file", required=True)
+    update.add_argument("--no-schema", action="store_false", dest="include_schema", default=True)
+    update.set_defaults(handler=_handle_update, format_hint="data_update")
+
+    delete = commands.add_parser("delete", help="删除应用数据")
+    delete.add_argument("--app-key", required=True)
+    delete.add_argument(
+        "--record-ids", action="append", default=[], metavar="ID[,ID...]",
+        help="待删除记录 ID；支持逗号分隔，也可重复传入",
+    )
+    delete.add_argument("--record-ids-file", help="附加的记录 ID JSON 数组文件")
+    delete.set_defaults(handler=_handle_delete, format_hint="data_delete")
+
+
+def _handle_query(args: argparse.Namespace, context: CliContext) -> dict:
+    if args.all_pages != (args.output == "csv"):
+        raise_config_error(
+            "--all 与 --output csv 必须同时使用。",
+            fix_hint="使用 `qingflow data query ... --all --output csv`，普通分页查询不要传这两个参数。",
+        )
+    return context.data.data_query(
+        profile=args.profile,
+        app_key=args.app_key,
+        columns=load_list_arg(args.columns_file, option_name="--columns-file"),
+        where=load_list_arg(args.where_file, option_name="--where-file"),
+        sort=load_list_arg(args.sort_file, option_name="--sort-file"),
+        search=args.search,
+        page=args.page,
+        page_size=args.page_size,
+        include_schema=args.include_schema,
+        all_pages=args.all_pages,
+        output=args.output,
+    )
+
+
+def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.data.data_get(
+        profile=args.profile, app_key=args.app_key, record_id=args.record_id, include_schema=args.include_schema
+    )
+
+
+def _handle_insert(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.data.data_insert(
+        profile=args.profile, app_key=args.app_key,
+        items=require_list_arg(args.items_file, option_name="--items-file"), include_schema=args.include_schema,
+    )
+
+
+def _handle_update(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.data.data_update(
+        profile=args.profile, app_key=args.app_key, record_id=args.record_id,
+        fields=require_object_arg(args.fields_file, option_name="--fields-file"), include_schema=args.include_schema,
+    )
+
+
+def _handle_delete(args: argparse.Namespace, context: CliContext) -> dict:
+    record_ids = [item.strip() for group in args.record_ids for item in group.split(",") if item.strip()]
+    record_ids.extend(load_list_arg(args.record_ids_file, option_name="--record-ids-file"))
+    if not record_ids:
+        raise_config_error(
+            "至少传入一个记录 ID。",
+            fix_hint="使用 `--record-ids ID[,ID...]`；也可附加 `--record-ids-file ids.json`。",
+        )
+    return context.data.data_delete(
+        profile=args.profile, app_key=args.app_key,
+        record_ids=record_ids,
+    )

package/src/qingflow_mcp/cli/context.py

@@ -11,6 +11,7 @@ from ..tools.ai_builder_tools import AiBuilderTools
 from ..tools.app_tools import AppTools
 from ..tools.auth_tools import AuthTools
 from ..tools.code_block_tools import CodeBlockTools
+from ..tools.data_tools import DataTools
 from ..tools.export_tools import ExportTools
 from ..tools.feedback_tools import FeedbackTools
 from ..tools.file_tools import FileTools
@@ -33,6 +34,7 @@ class CliContext:
     app: AppTools
     resource: ResourceReadTools
     record: RecordTools
+    data: DataTools
     code_block: CodeBlockTools
     imports: ImportTools
     exports: ExportTools
@@ -64,6 +66,7 @@ def build_cli_context() -> CliContext:
         app=AppTools(sessions, backend),
         resource=ResourceReadTools(sessions, backend),
         record=RecordTools(sessions, backend),
+        data=DataTools(sessions, backend),
         code_block=CodeBlockTools(sessions, backend),
         imports=ImportTools(sessions, backend),
         exports=ExportTools(sessions, backend),

package/src/qingflow_mcp/cli/main.py

@@ -2,11 +2,13 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 from typing import Any, Callable, TextIO
 
 from ..errors import QingflowApiError, backend_code_value_int, message_looks_like_invalid_token
 from ..public_surface import cli_public_tool_spec_from_namespace
+from ..resource_uri import cli_resource_base_url
 from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
 from ..tools.ai_builder_tools import _attach_builder_apply_envelope
 from ..version import get_cli_version, get_cli_version_info
@@ -94,7 +96,8 @@ def run(
         context = context_factory()
         if not bool(args.json):
             _emit_cli_effective_context_notice(args, context, stream=err)
-        result = handler(args, context)
+        with cli_resource_base_url(os.getenv("QINGFLOW_BASE_URL") or ""):
+            result = handler(args, context)
     except SystemExit as exc:
         return int(exc.code or 0)
     except RuntimeError as exc:

package/src/qingflow_mcp/public_surface.py

@@ -40,6 +40,11 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "workspace_select", ("workspace_select",), ("workspace", "select")),
     PublicToolSpec(USER_DOMAIN, "app_list", ("app_list",), ("app", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "app_get", ("app_get",), ("app", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "data_query", ("data_query",), ("data", "query"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "data_get", ("data_get",), ("data", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "data_insert", ("data_insert",), ("data", "insert"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "data_update", ("data_update",), ("data", "update"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "data_delete", ("data_delete",), ("data", "delete"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(USER_DOMAIN, "portal_list", ("portal_list",), ("portal", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "portal_get", ("portal_get",), ("portal", "get"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "view_get", ("view_get",), ("view", "get"), cli_show_effective_context=True),

package/src/qingflow_mcp/resource_uri.py

@@ -1,17 +1,24 @@
 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 get_web_base_url
+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)
@@ -24,6 +31,16 @@ class ResourcePath:
     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)
@@ -64,7 +81,7 @@ def build_resource_uri(
         path = f"/resources/ws/{workspace}/app/{app_segment}/view/{view_kind}/{view_segment}"
     else:
         raise ValueError("resource_type is not supported")
-    return f"{_normalize_web_origin(web_origin) if web_origin is not None else get_web_base_url()}{path}"
+    return f"{resolve_resource_web_origin(web_origin)}{path}"
 
 
 def parse_resource_path(value: str) -> ResourcePath:
@@ -142,6 +159,46 @@ def _normalize_web_origin(value: str) -> str:
     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="")

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_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
@@ -242,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)
@@ -395,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)

package/src/qingflow_mcp/tools/csv_export.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import csv
+import json
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+from ..json_types import JSONObject
+
+
+PageFetcher = Callable[[int, int], JSONObject]
+RowProjector = Callable[[JSONObject], list[str]]
+
+
+class CsvPageFailure(RuntimeError):
+    """后续分页返回结构化业务错误；已写文件保留为不完整结果。"""
+
+    def __init__(self, payload: JSONObject) -> None:
+        super().__init__(str(payload.get("message") or "分页请求失败"))
+        self.payload = payload
+
+
+class CsvShardWriter:
+    """视图无关的 UTF-8 BOM CSV 分片写入器。"""
+
+    def __init__(self, *, output_dir: Path, file_prefix: str, header: list[str], shard_rows: int) -> None:
+        self.output_dir = output_dir
+        self.file_prefix = file_prefix
+        self.header = header
+        self.shard_rows = shard_rows
+        self.files: list[JSONObject] = []
+        self.row_count = 0
+        self._part = 0
+        self._current_rows = 0
+        self._file: Any | None = None
+        self._writer: Any | None = None
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    def write(self, values: list[str]) -> None:
+        if self._current_rows >= self.shard_rows:
+            self.close_shard()
+        self._ensure_writer().writerow(values)
+        self._current_rows += 1
+        self.row_count += 1
+
+    def close_shard(self) -> None:
+        if self._file is None:
+            return
+        path = Path(self._file.name)
+        self._file.close()
+        self.files.append({"local_path": str(path), "row_count": self._current_rows, "part": len(self.files) + 1})
+        self._file = None
+        self._writer = None
+        self._current_rows = 0
+
+    def _ensure_writer(self) -> Any:
+        if self._writer is not None:
+            return self._writer
+        self._part += 1
+        path = self.output_dir / f"{self.file_prefix}-{self._part:04d}.csv"
+        self._file = path.open("w", newline="", encoding="utf-8-sig")
+        self._writer = csv.writer(self._file)
+        self._writer.writerow(self.header)
+        return self._writer
+
+
+def export_csv_pages(
+    *,
+    fetch_page: PageFetcher,
+    header: list[str],
+    project_row: RowProjector,
+    output_dir: Path,
+    file_prefix: str,
+    page_size: int,
+    shard_rows: int,
+    time_budget_seconds: float,
+) -> JSONObject:
+    """执行与业务权限无关的分页、CSV 分片和时间预算控制。"""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    deadline = time.monotonic() + time_budget_seconds
+    files: list[JSONObject] = []
+    row_count = 0
+    fetched_pages = 0
+    current_page = 1
+    file_handle: Any | None = None
+    writer: Any | None = None
+    current_rows = 0
+    part = 0
+    has_more = False
+    stopped_reason: str | None = None
+    page_error: JSONObject | None = None
+
+    def close_file() -> None:
+        nonlocal file_handle, writer, current_rows
+        if file_handle is None:
+            return
+        path = Path(file_handle.name)
+        file_handle.close()
+        files.append({"local_path": str(path), "row_count": current_rows, "part": len(files) + 1})
+        file_handle = None
+        writer = None
+        current_rows = 0
+
+    def get_writer() -> Any:
+        nonlocal file_handle, writer, part
+        if writer is not None:
+            return writer
+        part += 1
+        path = output_dir / f"{file_prefix}-{part:04d}.csv"
+        file_handle = path.open("w", newline="", encoding="utf-8-sig")
+        writer = csv.writer(file_handle)
+        writer.writerow(header)
+        return writer
+
+    try:
+        while True:
+            page = fetch_page(current_page, page_size)
+            records = page.get("records") if isinstance(page, dict) else None
+            container = records if isinstance(records, dict) else page
+            raw_items = container.get("items", container.get("list", [])) if isinstance(container, dict) else []
+            items = raw_items if isinstance(raw_items, list) else []
+            has_more = bool(container.get("has_more")) if isinstance(container, dict) else False
+            for item in items:
+                if not isinstance(item, dict):
+                    continue
+                if current_rows >= shard_rows:
+                    close_file()
+                get_writer().writerow(project_row(item))
+                current_rows += 1
+                row_count += 1
+            fetched_pages += 1
+            if not has_more:
+                break
+            if time.monotonic() >= deadline:
+                stopped_reason = "TIME_BUDGET_EXCEEDED"
+                break
+            current_page += 1
+    except CsvPageFailure as exception:
+        stopped_reason = "PAGE_FETCH_FAILED"
+        page_error = exception.payload
+    except Exception:
+        # 已落盘分片仍是有效的部分结果；调用方据此禁止形成完整性结论。
+        stopped_reason = "PAGE_FETCH_FAILED"
+    finally:
+        close_file()
+
+    complete = stopped_reason is None and not has_more
+    result: JSONObject = {
+        "files": files,
+        "row_count": row_count,
+        "complete": complete,
+        "truncated": not complete,
+        "safe_for_final_conclusion": complete,
+        "fetched_pages": fetched_pages,
+        "stopped_reason": stopped_reason,
+    }
+    if page_error is not None:
+        result["page_error"] = page_error
+    return result
+
+
+def csv_cell(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    return str(value)

package/src/qingflow_mcp/tools/data_tools.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from ..backend_client import BackendRequestContext
+from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError, raise_tool_error
+from ..json_types import JSONObject, JSONValue
+from .base import ToolBase
+from .csv_export import CsvPageFailure, csv_cell, export_csv_pages
+
+
+DATA_PAGE_SIZE = 1000
+DATA_CSV_SHARD_ROWS = 20_000
+DATA_UNBOUNDED_ROW_THRESHOLD = 50_000
+DATA_CSV_TIME_BUDGET_SECONDS = 55.0
+
+
+class DataTools(ToolBase):
+    """视图无关的应用数据面工具。"""
+
+    def register(self, mcp: FastMCP) -> None:
+        @mcp.tool()
+        def data_query(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            columns: list[int] | None = None,
+            where: list[dict] | None = None,
+            sort: list[dict] | None = None,
+            search: str = "",
+            page: int = 1,
+            page_size: int = 100,
+            include_schema: bool = True,
+            all_pages: bool = False,
+            output: str = "json",
+        ) -> JSONObject:
+            return self.data_query(
+                profile=profile, app_key=app_key, columns=columns or [], where=where or [], sort=sort or [],
+                search=search, page=page, page_size=page_size, include_schema=include_schema,
+                all_pages=all_pages, output=output,
+            )
+
+        @mcp.tool()
+        def data_get(
+            profile: str = DEFAULT_PROFILE, app_key: str = "", record_id: str = "", include_schema: bool = True
+        ) -> JSONObject:
+            return self.data_get(profile=profile, app_key=app_key, record_id=record_id, include_schema=include_schema)
+
+        @mcp.tool()
+        def data_insert(
+            profile: str = DEFAULT_PROFILE, app_key: str = "", items: list[dict] | None = None,
+            include_schema: bool = True,
+        ) -> JSONObject:
+            return self.data_insert(profile=profile, app_key=app_key, items=items or [], include_schema=include_schema)
+
+        @mcp.tool()
+        def data_update(
+            profile: str = DEFAULT_PROFILE, app_key: str = "", record_id: str = "",
+            fields: dict | None = None, include_schema: bool = True,
+        ) -> JSONObject:
+            return self.data_update(
+                profile=profile, app_key=app_key, record_id=record_id, fields=fields or {},
+                include_schema=include_schema,
+            )
+
+        @mcp.tool()
+        def data_delete(
+            profile: str = DEFAULT_PROFILE, app_key: str = "", record_ids: list[str | int] | None = None,
+        ) -> JSONObject:
+            return self.data_delete(profile=profile, app_key=app_key, record_ids=record_ids or [])
+
+    def data_query(
+        self, *, profile: str, app_key: str, columns: list[int], where: list[dict], sort: list[dict],
+        search: str = "", page: int = 1, page_size: int = 100, include_schema: bool = True,
+        all_pages: bool = False, output: str = "json",
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+        if all_pages and output != "csv":
+            raise_tool_error(QingflowApiError.config_error("all_pages 仅支持 output=csv"))
+
+        def runner(session_profile, context):
+            body: JSONObject = {
+                "page": page, "page_size": page_size, "columns": columns, "where": where, "sort": sort,
+                "search": search, "include_schema": include_schema,
+            }
+            if not all_pages:
+                return self._attach_context(
+                    self._request_data_plane(context, "POST", self._base_path(app_key) + "/query", json_body=body),
+                    profile, session_profile.selected_ws_id,
+                )
+            return self._export_all(
+                context=context, profile=profile, ws_id=session_profile.selected_ws_id, app_key=app_key,
+                body=body, has_scope=bool(where or search),
+            )
+
+        return self._run(profile, runner, tool_name="数据面查询")
+
+    def data_get(self, *, profile: str, app_key: str, record_id: str | int, include_schema: bool = True) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_record_id(record_id)
+        return self._run(
+            profile,
+            lambda session_profile, context: self._attach_context(
+                self._request_data_plane(
+                    context, "GET", f"{self._base_path(app_key)}/{record_id}",
+                    params={"include_schema": include_schema},
+                ), profile, session_profile.selected_ws_id,
+            ),
+            tool_name="数据面单条读取",
+        )
+
+    def data_insert(self, *, profile: str, app_key: str, items: list[dict], include_schema: bool = True) -> JSONObject:
+        self._require_app_key(app_key)
+        return self._write(profile, app_key, "POST", self._base_path(app_key), {"items": items, "include_schema": include_schema}, "数据面新增")
+
+    def data_update(
+        self, *, profile: str, app_key: str, record_id: str | int, fields: dict, include_schema: bool = True
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_record_id(record_id)
+        return self._write(
+            profile, app_key, "POST", f"{self._base_path(app_key)}/{record_id}/update",
+            {"fields": fields, "include_schema": include_schema}, "数据面更新",
+        )
+
+    def data_delete(self, *, profile: str, app_key: str, record_ids: list[str | int]) -> JSONObject:
+        self._require_app_key(app_key)
+        return self._write(profile, app_key, "POST", self._base_path(app_key) + "/delete", {"record_ids": record_ids}, "数据面删除")
+
+    def _write(self, profile: str, app_key: str, method: str, path: str, body: JSONObject, tool_name: str) -> JSONObject:
+        return self._run(
+            profile,
+            lambda session_profile, context: self._attach_context(
+                self._request_data_plane(context, method, path, json_body=body), profile, session_profile.selected_ws_id,
+            ),
+            tool_name=tool_name,
+        )
+
+    def _request_data_plane(
+        self, context: BackendRequestContext, method: str, path: str, *, params: JSONObject | None = None,
+        json_body: JSONValue = None,
+    ) -> JSONObject:
+        raw = self.backend.request(method, context, path, params=params, json_body=json_body, unwrap=False)
+        if not isinstance(raw, dict):
+            raise QingflowApiError(category="backend", message="数据面返回了非对象响应")
+        code = raw.get("code")
+        payload = raw.get("data")
+        result: JSONObject = dict(payload) if isinstance(payload, dict) else {}
+        success = code in (None, 0, 200, 20000) or str(code).lower() in {"success", "ok"}
+        result.setdefault("ok", success)
+        result.setdefault("status", "success" if success else "failed")
+        result.setdefault("hints", [])
+        if not success:
+            result.setdefault("message", str(raw.get("message") or raw.get("msg") or "数据面请求失败"))
+            result.setdefault("backend_code", code)
+        return result
+
+    def _export_all(
+        self, *, context: BackendRequestContext, profile: str, ws_id: int | None, app_key: str,
+        body: JSONObject, has_scope: bool,
+    ) -> JSONObject:
+        probe_body = dict(body)
+        probe_body.update({"page": 1, "page_size": 1, "include_schema": True})
+        probe = self._request_data_plane(context, "POST", self._base_path(app_key) + "/query", json_body=probe_body)
+        if probe.get("ok") is False:
+            # 探测请求没有产生文件，保留后端结构化错误，不把失败误报为空数据成功。
+            return self._attach_context(probe, profile, ws_id)
+        records = probe.get("records") if isinstance(probe.get("records"), dict) else {}
+        total = records.get("total") if isinstance(records, dict) else None
+        if isinstance(total, int) and total > DATA_UNBOUNDED_ROW_THRESHOLD and not has_scope:
+            return self._attach_context({
+                "ok": True, "status": "needs_scope", "app_key": app_key, "format": "csv", "row_count": 0,
+                "complete": False, "truncated": True, "safe_for_final_conclusion": False, "files": [],
+                "hints": probe.get("hints", []),
+                "scope": {"reported_total": total, "row_threshold": DATA_UNBOUNDED_ROW_THRESHOLD},
+            }, profile, ws_id)
+        schema = probe.get("schema") if isinstance(probe.get("schema"), dict) else {}
+        fields = schema.get("fields") if isinstance(schema, dict) else None
+        field_list = fields if isinstance(fields, list) else []
+        business_fields = [field for field in field_list if isinstance(field, dict) and field.get("field_id") is not None]
+        columns = [(str(field.get("field_id")), str(field.get("title") or field.get("field_id"))) for field in business_fields]
+        header = ["record_id"] + [f"{title}__field_{field_id}" for field_id, title in columns]
+        run_dir = Path.home() / ".qingflow" / "data-exports" / datetime.now().strftime("%Y%m%d-%H%M%S-%f")
+
+        def fetch_page(page: int, page_size: int) -> JSONObject:
+            request_body = dict(body)
+            request_body.update({"page": page, "page_size": page_size, "include_schema": page == 1})
+            response = self._request_data_plane(
+                context, "POST", self._base_path(app_key) + "/query", json_body=request_body
+            )
+            if response.get("ok") is False:
+                raise CsvPageFailure(response)
+            return response
+
+        def project_row(record: JSONObject) -> list[str]:
+            values = record.get("fields") if isinstance(record.get("fields"), dict) else record
+            return [str(record.get("record_id") or "")] + [csv_cell(values.get(field_id)) for field_id, _ in columns]
+
+        exported = export_csv_pages(
+            fetch_page=fetch_page, header=header, project_row=project_row, output_dir=run_dir,
+            file_prefix="records", page_size=DATA_PAGE_SIZE, shard_rows=DATA_CSV_SHARD_ROWS,
+            time_budget_seconds=DATA_CSV_TIME_BUDGET_SECONDS,
+        )
+        page_error = exported.pop("page_error", None)
+        result: JSONObject = {
+            "ok": True, "status": "success" if exported["complete"] else "partial", "app_key": app_key,
+            "format": "csv", "local_dir": str(run_dir), "fields": business_fields, "hints": probe.get("hints", []),
+            **exported,
+        }
+        if isinstance(page_error, dict):
+            # 后续页失败时保留已落盘分片，同时把后端稳定错误字段原样带回。
+            result["ok"] = False
+            for key in ("error_code", "message", "backend_code", "write_executed", "retry_safe", "field_errors"):
+                if key in page_error:
+                    result[key] = page_error[key]
+            if "hints" in page_error:
+                result["hints"] = page_error["hints"]
+        return self._attach_context(result, profile, ws_id)
+
+    @staticmethod
+    def _base_path(app_key: str) -> str:
+        return f"/app/{app_key}/data/v1/records"
+
+    @staticmethod
+    def _attach_context(result: JSONObject, profile: str, ws_id: int | None) -> JSONObject:
+        return {"profile": profile, "ws_id": ws_id, **result}
+
+    @staticmethod
+    def _require_app_key(app_key: str) -> None:
+        if not str(app_key or "").strip():
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+
+    @staticmethod
+    def _require_record_id(record_id: str | int) -> None:
+        if not str(record_id or "").strip():
+            raise_tool_error(QingflowApiError.config_error("record_id is required"))

package/src/qingflow_mcp/tools/login_link_tools.py

@@ -6,10 +6,10 @@ from urllib.parse import parse_qs, unquote, urlencode, urlsplit
 
 from mcp.server.fastmcp import FastMCP
 
-from ..config import DEFAULT_PROFILE, get_web_base_url
+from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError
 from ..json_types import JSONObject
-from ..resource_uri import parse_resource_path
+from ..resource_uri import parse_resource_path, resolve_resource_web_origin
 from .base import ToolBase
 
 LOGIN_LINK_DESCRIPTION = (
@@ -99,14 +99,14 @@ class LoginLinkTools(ToolBase):
                     )
             else:
                 target = validate_redirect_path(requested_target)
-            web_base_url = get_web_base_url()
+            web_base_url = resolve_resource_web_origin()
             result = self.backend.request(
                 "POST",
                 context,
                 "/mcp/auth/login-link",
                 json_body={"wsId": session_profile.selected_ws_id},
             )
-            # 后端仅提供票据，网页地址由 MCP 配置确定，避免工作区域名为空。
+            # 后端仅提供票据；CLI 使用 QINGFLOW_BASE_URL 对应网页环境，MCP 使用独立网页配置。
             try:
                 source_url = result.get("url") if isinstance(result, dict) else None
                 if not isinstance(source_url, str):

package/src/qingflow_mcp/tools/record_tools.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import csv
 import html
 import mimetypes
 import json
@@ -34,6 +33,7 @@ from ..list_type_labels import (
 )
 from .base import ToolBase
 from .directory_tools import _directory_has_more, _directory_items
+from .csv_export import CsvShardWriter
 
 
 DEFAULT_QUERY_PAGE_SIZE = 50
@@ -2263,57 +2263,22 @@ class RecordTools(ToolBase):
                 }
 
             run_dir = _record_access_run_dir()
-            run_dir.mkdir(parents=True, exist_ok=True)
             header = ["record_id"] + [str(field["column_name"]) for field in fields_payload]
-            files: list[JSONObject] = []
-            shard_part = 0
-            shard_rows = 0
-            row_count = 0
-            file_handle: Any | None = None
-            writer: Any | None = None
-
-            def close_shard() -> None:
-                nonlocal file_handle, writer, shard_rows
-                if file_handle is None:
-                    return
-                path = Path(file_handle.name)
-                file_handle.close()
-                files.append(
-                    {
-                        "local_path": str(path),
-                        "row_count": shard_rows,
-                        "part": len(files) + 1,
-                    }
-                )
-                file_handle = None
-                writer = None
-                shard_rows = 0
-
-            def ensure_writer() -> Any:
-                nonlocal file_handle, writer, shard_part
-                if writer is not None:
-                    return writer
-                shard_part += 1
-                path = run_dir / f"records-{shard_part:04d}.csv"
-                file_handle = path.open("w", newline="", encoding="utf-8-sig")
-                writer = csv.writer(file_handle)
-                writer.writerow(header)
-                return writer
+            shard_writer = CsvShardWriter(
+                output_dir=run_dir,
+                file_prefix="records",
+                header=header,
+                shard_rows=DEFAULT_RECORD_ACCESS_SHARD_ROWS,
+            )
 
             def write_record(apply_id: int | None, answer_list: list[JSONValue]) -> None:
-                nonlocal row_count, shard_rows
                 if apply_id is None:
                     return
-                if shard_rows >= DEFAULT_RECORD_ACCESS_SHARD_ROWS:
-                    close_shard()
-                csv_writer = ensure_writer()
                 values: list[str] = [_public_record_id_text(apply_id) or ""]
                 for field in selected_fields:
                     answer = _find_answer_for_field(answer_list, field)
                     values.append(_record_access_csv_cell(_normalize_answer_field_value_for_output(answer, field)))
-                csv_writer.writerow(values)
-                row_count += 1
-                shard_rows += 1
+                shard_writer.write(values)
 
             current_page = 1
             has_more = False
@@ -2353,7 +2318,7 @@ class RecordTools(ToolBase):
                         break
                     page = fetch_page(current_page, BACKEND_RECORD_ACCESS_PAGE_SIZE)
             finally:
-                close_shard()
+                shard_writer.close_shard()
 
             if stopped_reason == "TIME_BUDGET_EXCEEDED":
                 warnings.append(_record_access_time_budget_warning(reported_total=reported_total, fetched_pages=fetched_pages))
@@ -2378,11 +2343,11 @@ class RecordTools(ToolBase):
                 "view_id": view_route.view_id,
                 "format": "csv",
                 "local_dir": str(run_dir),
-                "row_count": row_count,
+                "row_count": shard_writer.row_count,
                 "complete": complete,
                 "truncated": not complete,
                 "safe_for_final_conclusion": safe_for_final_conclusion,
-                "files": files,
+                "files": shard_writer.files,
                 "fields": fields_payload,
                 "warnings": warnings,
                 "verification": verification_payload,