quantdb-sdk 0.4.3__tar.gz → 0.4.5__tar.gz

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/CHANGELOG.md

@@ -3,6 +3,31 @@
 所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## \[0.4.5] - 2026-10-18
+
+### Added
+
+- 本地 MCP 可调用 `quantdb-sdk` 执行单文件/全市场日分区下载与数据集增量同步，并查询、取消后台任务。远程 MCP 提供用户电脑可执行的 SDK 下载方案。
+- `quantdb download <dataset> --trade-date YYYYMMDD --save-dir <root> --json`：下载 Parquet 并输出保存路径、大小；V1 逐股票文件使用 `--symbol`。V2 下载包含全市场，不做单股票裁切。
+- `quantdb sync <dataset> --json`：复用 SDK release cursor/Manifest 同步并返回精简摘要。
+- `python -m quantdb_sdk.mcp_download`：供本地 MCP 子进程使用的 JSON stdin/stdout 执行入口，凭据不进入进程参数或返回值。
+
+## \[0.4.4] - 2026-10-11
+
+### Fixed
+
+- **`get_usage()` / `a_get_usage()` 漏算流量包额度**：旧实现用 `remaining = traffic_limit + credit_limit + purchased_traffic - used_traffic`，**完全没算流量包**，导致持有流量包的用户剩余流量被低估（少报的量正好等于流量包余额），`is_active` 也会在仍有流量包可用时被误判为 `False`。
+
+  修正后的口径与后端下载预扣一致：可用总额度 = 套餐额度（`traffic_limit + credit_limit + purchased_traffic`）+ 流量包总额；可用剩余 = (套餐额度 − 已用) + 流量包剩余。因用量接口返回的 `package_traffic` 是流量包**剩余量**，总额从 `GET /api/v1/subscription/traffic-packages` 台账累加；台账接口不可用时退化为「总额 = 剩余」，保证 `get_usage()` 在旧版服务端上依然可用。
+
+### Added
+
+- **`get_usage()` / `a_get_usage()` 新增额度明细字段**（原有字段全部保留，取值已修正）：
+  - 合计：`total_gb` / `used_gb` / `remaining_gb`
+  - 套餐额度：`plan_total_gb` / `plan_used_gb` / `plan_remaining_gb`
+  - 流量包额度：`package_total_gb` / `package_used_gb` / `package_remaining_gb`
+- **`quantdb usage` CLI** 改为分行展示套餐 / 流量包 / 合计的已用、总额与剩余，不再只显示一个总额。
+
 ## \[0.4.3] - 2026-10-05
 
 ### Changed

{quantdb_sdk-0.4.3/quantdb_sdk.egg-info → quantdb_sdk-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.4.3
+Version: 0.4.5
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantdb-sdk"
-version = "0.4.3"
+version = "0.4.5"
 description = "QuantDB 量化数据平台官方 Python SDK"
 readme = "README.md"
 license = {text = "MIT"}

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/quantdb_sdk/__init__.py

@@ -5,7 +5,7 @@ try:
     # 注意：此处用 PyPI 包名（连字符）查找版本号，不是模块名（下划线）
     __version__ = version("quantdb-sdk")
 except ImportError:
-    __version__ = "0.4.3"
+    __version__ = "0.4.5"
 
 from . import layout
 from ._utils import scan_local_directory

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/quantdb_sdk/__main__.py

@@ -13,6 +13,7 @@
 """
 
 import argparse
+import json
 import os
 import sys
 from typing import Optional
@@ -105,6 +106,14 @@ def main() -> int:
     sync_parser.add_argument("--save-dir", default=None,
                              help="本地同步根目录（默认读 QUANTDB_DATA_DIR，未设置时用默认下载目录）")
     sync_parser.add_argument("--after-release", default=None, help="覆盖本地 release cursor（一般无需传入）")
+    sync_parser.add_argument("--json", action="store_true", help="输出精简 JSON 摘要（适合 MCP 下载方案）")
+
+    download_parser = subparsers.add_parser("download", help="下载单个 Parquet 文件或全市场日分区")
+    download_parser.add_argument("dataset", help="数据集，如 daily_forward、balance")
+    download_parser.add_argument("--symbol", default=None, help="仅逐股票 V1 文件填写；V2 分区包含全市场")
+    download_parser.add_argument("--trade-date", default=None, help="V2 必填：YYYY-MM-DD 或 YYYYMMDD")
+    download_parser.add_argument("--save-dir", default=None, help="本地数据根目录")
+    download_parser.add_argument("--json", action="store_true", help="输出 JSON 保存路径和文件大小")
 
     args = parser.parse_args()
 
@@ -123,6 +132,21 @@ def main() -> int:
         parser.error(f"请先设置 API Key 环境变量 {args.api_key_env}")
 
     try:
+        if args.command == "download" or (args.command == "sync" and args.json):
+            from .mcp_download import execute_download
+
+            result = execute_download({
+                "operation": args.command, "dataset": args.dataset,
+                "symbol": getattr(args, "symbol", None),
+                "trade_date": getattr(args, "trade_date", None), "save_dir": args.save_dir,
+                "after_release": getattr(args, "after_release", None),
+            }, args.api_host, api_key)
+            if args.json:
+                print(json.dumps(result, ensure_ascii=False))
+            else:
+                print(f"下载完成: {result['path']} ({result['size_bytes']} bytes)")
+            return 0
+
         client = QuantDBClient(api_host=args.api_host, api_key=api_key)
 
         if args.command == "check":
@@ -135,9 +159,12 @@ def main() -> int:
         if args.command == "usage":
             usage = client.get_usage()
             print(f"账户用量:")
-            print(f"  已用: {usage['used_gb']:.2f} GB")
-            print(f"  限额: {usage['limit_gb']:.1f} GB")
-            print(f"  剩余: {usage['remaining_gb']:.2f} GB")
+            print(f"  套餐:   已用 {usage['plan_used_gb']:.2f} GB / {usage['plan_total_gb']:.2f} GB"
+                  f"（剩余 {usage['plan_remaining_gb']:.2f} GB）")
+            print(f"  流量包: 已用 {usage['package_used_gb']:.2f} GB / {usage['package_total_gb']:.2f} GB"
+                  f"（剩余 {usage['package_remaining_gb']:.2f} GB）")
+            print(f"  合计:   已用 {usage['used_gb']:.2f} GB / {usage['total_gb']:.2f} GB"
+                  f"（剩余 {usage['remaining_gb']:.2f} GB）")
             print(f"  余额: ¥{usage['balance_yuan']:.2f}")
             sub = usage.get("subscription", {})
             print(f"  订阅: {sub.get('status', 'none')}")

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/quantdb_sdk/_utils.py

@@ -96,6 +96,9 @@ def safe_join(root: str, relative_path: str) -> str:
     target = os.path.abspath(os.path.join(root_abs, *parts))
     if os.path.commonpath([root_abs, target]) != root_abs:
         raise ValueError("发布清单路径超出同步目录")
+    root_real = os.path.realpath(root_abs)
+    if os.path.commonpath([root_real, os.path.realpath(target)]) != root_real:
+        raise ValueError("发布清单路径通过符号链接超出同步目录")
     return target
 
 

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/quantdb_sdk/async_client.py

@@ -28,7 +28,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.4.3"
+_USER_AGENT = "QuantDB-Python-SDK/0.4.5"
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:
@@ -287,21 +287,56 @@ class AsyncQuantDBClient:
         return await self._get("/api/v1/auth/me")
 
     async def a_get_usage(self) -> Dict[str, Any]:
+        """获取当前账户流量与订阅使用情况（异步版，字段含义见 ``QuantDBClient.get_usage``）。"""
         data = await self._get("/api/v1/auth/usage")
         used = data.get("used_traffic", 0)
         limit = data.get("traffic_limit", 0)
         credit = data.get("credit_limit", 0)
         purchased = data.get("purchased_traffic", 0)
+        package_remaining = data.get("package_traffic", 0)
         subscription = data.get("subscription", {}) or {}
+
+        plan_total = limit + credit + purchased
+        plan_remaining = max(0, plan_total - used)
+
+        # 流量包总额只能从台账取（用量接口只给剩余量）。台账接口不可用时退化为
+        # 「总额 = 剩余」，保证 a_get_usage 在旧版服务端上依然可用。
+        package_total = package_remaining
+        try:
+            ledger = await self._get("/api/v1/subscription/traffic-packages")
+            active = [
+                p for p in (ledger.get("packages") or [])
+                if str(p.get("status", "")).lower() == "active"
+            ]
+            if active:
+                package_total = sum(int(p.get("quota_bytes") or 0) for p in active)
+        except QuantDBError:
+            pass
+
+        package_used = max(0, package_total - package_remaining)
+        total = plan_total + package_total
+        remaining = plan_remaining + package_remaining
+
         return {
+            # 合计
+            "total_gb": bytes_to_gb(total),
             "used_gb": bytes_to_gb(used),
+            "remaining_gb": bytes_to_gb(remaining),
+            # 套餐额度（月度重置）
+            "plan_total_gb": bytes_to_gb(plan_total),
+            "plan_used_gb": bytes_to_gb(used),
+            "plan_remaining_gb": bytes_to_gb(plan_remaining),
+            # 流量包额度（一年有效、可叠加）
+            "package_total_gb": bytes_to_gb(package_total),
+            "package_used_gb": bytes_to_gb(package_used),
+            "package_remaining_gb": bytes_to_gb(package_remaining),
+            # 兼容旧字段
             "limit_gb": bytes_to_gb(limit),
             "credit_gb": bytes_to_gb(credit),
             "purchased_gb": bytes_to_gb(purchased),
-            "remaining_gb": max(0.0, bytes_to_gb(limit + credit + purchased - used)),
             "balance_yuan": data.get("balance_yuan", 0.0),
             "subscription": subscription,
-            "is_active": subscription.get("status") == "active" and used < limit + credit + purchased,
+            "is_active": subscription.get("status") == "active" and remaining > 0,
         }
 
     async def a_register(self, username: str, email: str, password: str) -> Dict[str, Any]:

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/quantdb_sdk/client.py

@@ -32,7 +32,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.4.3"
+_USER_AGENT = "QuantDB-Python-SDK/0.4.5"
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:
@@ -325,22 +325,72 @@ class QuantDBClient:
         return self._get("/api/v1/auth/me")
 
     def get_usage(self) -> Dict[str, Any]:
-        """获取当前账户流量与订阅使用情况。"""
+        """获取当前账户流量与订阅使用情况。
+
+        额度模型（与后端下载预扣逻辑一致）：
+
+        - **套餐额度**（月度重置）：``traffic_limit + credit_limit + purchased_traffic``，
+          下载时优先从该额度池扣减，已用量即 ``used_traffic``；
+        - **流量包额度**（一年有效、可叠加）：台账 ``traffic_packages``。
+          接口返回的 ``package_traffic`` 是流量包**剩余量**，总额需从台账累加。
+
+        因此：可用总额度 = 套餐额度 + 流量包总额；
+        可用剩余 = (套餐额度 - 已用) + 流量包剩余。
+
+        Returns:
+            用量字典，包含合计（``total_gb``/``used_gb``/``remaining_gb``）、
+            套餐额度（``plan_*``）、流量包额度（``package_*``）三组字段，
+            以及兼容旧版的 ``limit_gb``/``credit_gb``/``purchased_gb``。
+        """
         data = self._get("/api/v1/auth/usage")
         used = data.get("used_traffic", 0)
         limit = data.get("traffic_limit", 0)
         credit = data.get("credit_limit", 0)
         purchased = data.get("purchased_traffic", 0)
+        package_remaining = data.get("package_traffic", 0)
         subscription = data.get("subscription", {}) or {}
+
+        plan_total = limit + credit + purchased
+        plan_remaining = max(0, plan_total - used)
+
+        # 流量包总额只能从台账取（用量接口只给剩余量）。台账接口不可用时退化为
+        # 「总额 = 剩余」，保证 get_usage 在旧版服务端上依然可用。
+        package_total = package_remaining
+        try:
+            ledger = self._get("/api/v1/subscription/traffic-packages")
+            active = [
+                p for p in (ledger.get("packages") or [])
+                if str(p.get("status", "")).lower() == "active"
+            ]
+            if active:
+                package_total = sum(int(p.get("quota_bytes") or 0) for p in active)
+        except QuantDBError:
+            pass
+
+        package_used = max(0, package_total - package_remaining)
+        total = plan_total + package_total
+        remaining = plan_remaining + package_remaining
+
         return {
+            # 合计
+            "total_gb": bytes_to_gb(total),
             "used_gb": bytes_to_gb(used),
+            "remaining_gb": bytes_to_gb(remaining),
+            # 套餐额度（月度重置）
+            "plan_total_gb": bytes_to_gb(plan_total),
+            "plan_used_gb": bytes_to_gb(used),
+            "plan_remaining_gb": bytes_to_gb(plan_remaining),
+            # 流量包额度（一年有效、可叠加）
+            "package_total_gb": bytes_to_gb(package_total),
+            "package_used_gb": bytes_to_gb(package_used),
+            "package_remaining_gb": bytes_to_gb(package_remaining),
+            # 兼容旧字段
             "limit_gb": bytes_to_gb(limit),
             "credit_gb": bytes_to_gb(credit),
             "purchased_gb": bytes_to_gb(purchased),
-            "remaining_gb": max(0.0, bytes_to_gb(limit + credit + purchased - used)),
             "balance_yuan": data.get("balance_yuan", 0.0),
             "subscription": subscription,
-            "is_active": subscription.get("status") == "active" and used < limit + credit + purchased,
+            "is_active": subscription.get("status") == "active" and remaining > 0,
         }
 
     def register(self, username: str, email: str, password: str) -> Dict[str, Any]:

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/quantdb_sdk/examples/demo_01_connect_basics.py

@@ -30,7 +30,12 @@ def main() -> None:
     print("账户:", me.get("username"), "| ID:", me.get("id"))
 
     usage = client.get_usage()
-    print(f"流量: 已用 {usage['used_gb']:.2f} GB / 限额 {usage['limit_gb']:.1f} GB / 剩余 {usage['remaining_gb']:.2f} GB")
+    print(f"套餐: 已用 {usage['plan_used_gb']:.2f} GB / {usage['plan_total_gb']:.2f} GB"
+          f" / 剩余 {usage['plan_remaining_gb']:.2f} GB")
+    print(f"流量包: 已用 {usage['package_used_gb']:.2f} GB / {usage['package_total_gb']:.2f} GB"
+          f" / 剩余 {usage['package_remaining_gb']:.2f} GB")
+    print(f"合计: 已用 {usage['used_gb']:.2f} GB / {usage['total_gb']:.2f} GB"
+          f" / 剩余 {usage['remaining_gb']:.2f} GB")
     print("订阅:", usage.get("subscription", {}).get("status", "none"))
 
     stocks = client.query_stock_list(keyword=args.keyword, limit=5)

quantdb_sdk-0.4.5/quantdb_sdk/mcp_download.py

@@ -0,0 +1,111 @@
+"""SDK download runner used by the local MCP process (JSON over stdin/stdout).
+
+Credentials travel over stdin, never in process arguments or returned results.
+All network transfers, traffic accounting and release cursors use QuantDBClient.
+"""
+
+import contextlib
+import json
+import os
+import re
+import sys
+from datetime import datetime
+from typing import Any, Dict
+
+from .client import QuantDBClient
+from .errors import ValidationError
+from .layout import CATEGORY_DIRS, V2_DAILY_PARTITION, data_root
+from ._utils import SYNC_DATASET_CATEGORIES
+
+PARTITIONED = V2_DAILY_PARTITION | {"min1_kline", "min5_kline", "tick_data", "etf_kline"}
+STATIC = {"sector_concept", "instrument_detail", "trading_calendar", "convertible_bond", "etf_pcf"}
+
+
+def validate_request(request: Dict[str, Any]) -> Dict[str, Any]:
+    operation = request.get("operation", "download")
+    dataset = request.get("dataset", "")
+    if operation not in {"download", "sync"} or dataset not in SYNC_DATASET_CATEGORIES:
+        raise ValidationError("Unknown operation or dataset")
+    result = {"operation": operation, "dataset": dataset}
+    for key in ("symbol", "trade_date", "save_dir"):
+        value = request.get(key) or ""
+        if not isinstance(value, str) or len(value) > 4096:
+            raise ValidationError("Invalid download parameter")
+        result[key] = value.strip()
+    if operation == "sync":
+        if result["symbol"] or result["trade_date"]:
+            raise ValidationError("Dataset sync does not accept symbol or trade_date")
+        return result
+    if dataset in PARTITIONED:
+        if result["symbol"]:
+            raise ValidationError("V2 downloads contain the entire market partition; omit symbol")
+        date = result["trade_date"].replace("-", "")
+        if not re.fullmatch(r"\d{8}", date):
+            raise ValidationError("V2 downloads require trade_date (YYYY-MM-DD or YYYYMMDD)")
+        try:
+            datetime.strptime(date, "%Y%m%d")
+        except ValueError as exc:
+            raise ValidationError("Invalid trade_date") from exc
+        result["trade_date"] = date
+    else:
+        if result["trade_date"]:
+            raise ValidationError("This dataset does not accept trade_date")
+        if dataset in STATIC:
+            if result["symbol"]:
+                raise ValidationError("This dataset is a whole-market static file; omit symbol")
+        elif not re.fullmatch(r"[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)*", result["symbol"]):
+            raise ValidationError("A valid symbol is required for this dataset")
+        result["symbol"] = result["symbol"].upper()
+    return result
+
+
+def execute_download(request: Dict[str, Any], api_host: str, api_key: str) -> Dict[str, Any]:
+    spec = validate_request(request)
+    if not api_key:
+        raise ValidationError("QUANTDB_API_KEY is required")
+    root = os.path.realpath(os.path.abspath(spec["save_dir"] or data_root()))
+    client = QuantDBClient(api_host=api_host, api_key=api_key)
+    try:
+        if spec["operation"] == "sync":
+            result = client.data.sync(spec["dataset"], save_dir=root, after_release=request.get("after_release"))
+            return {
+                "operation": "sync", "dataset": spec["dataset"], "save_dir": root,
+                "downloaded_count": len(result["downloaded"]),
+                "matched_count": len(result.get("matched", [])),
+                "release_id": result.get("release_id"), "layout": result.get("layout"),
+            }
+        dataset = spec["dataset"]
+        target = os.path.join(root, CATEGORY_DIRS[SYNC_DATASET_CATEGORIES[dataset]], dataset)
+        if spec["trade_date"]:
+            target = os.path.join(target, "dt=" + spec["trade_date"])
+        # Resolve symlinks before creating files, including existing subdirectories.
+        if os.path.commonpath([root, os.path.realpath(target)]) != root:
+            raise ValidationError("Download destination escapes save_dir")
+        path = client.data.download(
+            dataset, symbol=spec["symbol"] or None, trade_date=spec["trade_date"] or None,
+            save_dir=target, layout="v2" if dataset in PARTITIONED else "v1",
+        )
+        return {"operation": "download", "dataset": dataset, "save_dir": root,
+                "path": path, "size_bytes": os.path.getsize(path), "downloaded_count": 1}
+    finally:
+        client.session.close()
+
+
+def main() -> int:
+    try:
+        raw = sys.stdin.read(65537)
+        if len(raw) > 65536:
+            raise ValidationError("Request too large")
+        request = json.loads(raw)
+        # SDK/HTTP diagnostics must not leak credentials or signed URLs into MCP.
+        with open(os.devnull, "w") as sink, contextlib.redirect_stdout(sink), contextlib.redirect_stderr(sink):
+            result = execute_download(request, request["api_host"], request["api_key"])
+        print(json.dumps({"result": result}, ensure_ascii=True))
+        return 0
+    except Exception as exc:
+        print(json.dumps({"error": {"type": type(exc).__name__, "message": "SDK download failed; check credentials, access, quota, dataset and local disk."}}))
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5/quantdb_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.4.3
+Version: 0.4.5
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/quantdb_sdk.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ quantdb_sdk/client.py
 quantdb_sdk/errors.py
 quantdb_sdk/hub.py
 quantdb_sdk/layout.py
+quantdb_sdk/mcp_download.py
 quantdb_sdk/py.typed
 quantdb_sdk.egg-info/PKG-INFO
 quantdb_sdk.egg-info/SOURCES.txt
@@ -31,6 +32,7 @@ tests/test_client.py
 tests/test_data_hub.py
 tests/test_hub_models.py
 tests/test_layout.py
+tests/test_mcp_download.py
 tests/test_technical_indicators.py
 tests/test_update_pipeline.py
 tests/test_utils.py

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/tests/test_async_client.py

@@ -144,6 +144,8 @@ async def test_a_insufficient_traffic_error():
 @pytest.mark.asyncio
 @respx.mock
 async def test_a_get_usage_with_subscription():
+    # a_get_usage also queries the traffic-package ledger since SDK 0.4.4.
+    respx.get(f"{API_HOST}/api/v1/subscription/traffic-packages").mock(return_value=httpx.Response(200, json={"packages": []}))
     respx.get(f"{API_HOST}/api/v1/auth/usage").mock(
         return_value=httpx.Response(
             200,

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.5}/tests/test_client.py

@@ -213,6 +213,8 @@ def test_insufficient_traffic_error():
 
 @responses.activate
 def test_get_usage_with_subscription():
+    # get_usage also queries the traffic-package ledger since SDK 0.4.4.
+    responses.get(f"{API_HOST}/api/v1/subscription/traffic-packages", json={"packages": []}, status=200)
     responses.get(
         f"{API_HOST}/api/v1/auth/usage",
         json={

quantdb_sdk-0.4.5/tests/test_mcp_download.py

@@ -0,0 +1,134 @@
+"""MCP download runner reuses real SDK transfer and release-sync behavior."""
+
+import hashlib
+import json
+import sys
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+import responses
+
+from quantdb_sdk.errors import ValidationError
+from quantdb_sdk.mcp_download import execute_download, main, validate_request
+
+HOST = "http://localhost:5000"
+
+
+@responses.activate
+def test_download_partition_preserves_dates_and_forwards_key(tmp_path):
+    def download(request):
+        params = parse_qs(urlparse(request.url).query)
+        assert request.headers["X-API-Key"] == "local-secret"
+        assert params["layout"] == ["v2"]
+        assert "symbol" not in params
+        return 200, {"Content-Disposition": 'attachment; filename="data.parquet"'}, params["trade_date"][0].encode()
+
+    responses.add_callback(responses.GET, HOST + "/api/v1/data/download", callback=download)
+    paths = []
+    for date in ("2026-10-15", "20261016"):
+        result = execute_download({"dataset": "min1_kline", "trade_date": date, "save_dir": str(tmp_path)}, HOST, "local-secret")
+        paths.append(result["path"])
+        assert result["downloaded_count"] == 1
+        assert result["size_bytes"] == 8
+    assert paths[0] != paths[1]
+    assert (tmp_path / "1_kline_data/min1_kline/dt=20261016/data.parquet").read_bytes() == b"20261016"
+
+
+@responses.activate
+def test_download_v1_and_static_files(tmp_path):
+    def download(request):
+        params = parse_qs(urlparse(request.url).query)
+        assert params["layout"] == ["v1"]
+        if params["sub_category"] == ["balance"]:
+            assert params["symbol"] == ["600519.SH"]
+        else:
+            assert "symbol" not in params
+        return 200, {}, b"file"
+    responses.add_callback(responses.GET, HOST + "/api/v1/data/download", callback=download)
+    result = execute_download({"dataset": "balance", "symbol": "600519.sh", "save_dir": str(tmp_path)}, HOST, "key")
+    assert result["path"].endswith("balance_600519.SH.parquet")
+    result = execute_download({"dataset": "sector_concept", "save_dir": str(tmp_path)}, HOST, "key")
+    assert result["path"].endswith("sector_concept.parquet")
+
+
+@responses.activate
+def test_sync_uses_sdk_cursor_and_skips_existing_content(tmp_path):
+    payload = b"partition"
+    key = "1_kline_data/daily_forward/dt=20261016/data.parquet"
+    calls = []
+    def releases(request):
+        calls.append(parse_qs(urlparse(request.url).query, keep_blank_values=True).get("after_release"))
+        return 200, {}, json.dumps({"releases": [{"release_id": "20261016.1", "objects": [
+            {"key": key, "size": len(payload), "sha256": hashlib.sha256(payload).hexdigest()}
+        ]}]})
+    responses.add_callback(responses.GET, HOST + "/api/v1/data/releases", callback=releases)
+    responses.get(HOST + "/api/v1/data/download", body=payload, status=200)
+    spec = {"operation": "sync", "dataset": "daily_forward", "save_dir": str(tmp_path)}
+    first = execute_download(spec, HOST, "key")
+    second = execute_download(spec, HOST, "key")
+    assert first["downloaded_count"] == 1
+    assert second["downloaded_count"] == 0
+    assert calls == [[""], ["20261016.1"]]
+    assert (tmp_path / key).read_bytes() == payload
+    assert "downloaded" not in first  # bounded MCP summary, even for huge syncs
+
+
+@pytest.mark.parametrize("spec", [
+    {"dataset": "unknown"},
+    {"dataset": "daily_forward"},
+    {"dataset": "daily_forward", "trade_date": "20260230"},
+    {"dataset": "daily_forward", "trade_date": "20261016", "symbol": "600519.SH"},
+    {"dataset": "balance", "symbol": "../../outside"},
+    {"dataset": "balance", "symbol": "600519.SH", "trade_date": "20261016"},
+    {"dataset": "sector_concept", "symbol": "600519.SH"},
+    {"operation": "sync", "dataset": "balance", "symbol": "600519.SH"},
+])
+def test_validation_prevents_ambiguous_or_unsafe_requests(spec):
+    with pytest.raises(ValidationError):
+        validate_request(spec)
+
+
+@responses.activate
+def test_worker_never_returns_upstream_secrets(tmp_path, monkeypatch, capsys):
+    responses.get(HOST + "/api/v1/data/download", json={"detail": "local-secret https://signed.example?sign=secret"}, status=403)
+    request = {"dataset": "balance", "symbol": "600519.SH", "save_dir": str(tmp_path), "api_host": HOST, "api_key": "local-secret"}
+    import io
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps(request)))
+    assert main() == 1
+    output = capsys.readouterr()
+    assert "local-secret" not in output.out + output.err
+    assert "signed.example" not in output.out + output.err
+    assert json.loads(output.out)["error"]["type"]
+
+
+def test_cli_download_and_sync_json_delegate_sdk(monkeypatch, capsys, tmp_path):
+    from quantdb_sdk.__main__ import main as cli
+    from unittest.mock import patch
+    monkeypatch.setenv("QUANTDB_API_KEY", "cli-secret")
+    for operation in ("download", "sync"):
+        args = ["quantdb", operation, "balance", "--save-dir", str(tmp_path), "--json"]
+        if operation == "download":
+            args += ["--symbol", "600519.SH"]
+        else:
+            args += ["--after-release", "cursor"]
+        monkeypatch.setattr(sys, "argv", args)
+        with patch("quantdb_sdk.mcp_download.execute_download", return_value={"downloaded_count": 1}) as execute:
+            assert cli() == 0
+            assert execute.call_args.args[0]["operation"] == operation
+            if operation == "sync":
+                assert execute.call_args.args[0]["after_release"] == "cursor"
+        assert json.loads(capsys.readouterr().out)["downloaded_count"] == 1
+
+
+def test_sync_destination_rejects_symlink_escape(tmp_path):
+    from quantdb_sdk._utils import safe_join
+    outside = tmp_path / "outside"
+    root = tmp_path / "root"
+    outside.mkdir()
+    root.mkdir()
+    try:
+        (root / "linked").symlink_to(outside, target_is_directory=True)
+    except OSError:
+        pytest.skip("symlinks are unavailable on this platform")
+    with pytest.raises(ValueError, match="符号链接"):
+        safe_join(str(root), "linked/data.parquet")