cfquant 0.2.0__tar.gz → 0.2.1__tar.gz

{cfquant-0.2.0 → cfquant-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cfquant
-Version: 0.2.0
+Version: 0.2.1
 Summary: QMT local bridge and xtquant-compatible Python client.
 License: MIT
 Requires-Python: >=3.8
@@ -27,6 +27,7 @@ Requires-Dist: pyzmq>=25; extra == "zmq"
   <a href="https://github.com/95ge/cfquant/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/95ge/cfquant?style=flat&logo=github&label=Issues" /></a>
   <a href="https://github.com/95ge/cfquant/commits/main"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/95ge/cfquant?style=flat&logo=git&label=Last%20commit" /></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat" /></a>
+  <a href="https://pypi.org/project/cfquant/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/cfquant?style=flat&logo=pypi&logoColor=white" /></a>
   <img alt="Python 3.8 to 3.12" src="https://img.shields.io/badge/Python-3.8--3.12-blue?style=flat&logo=python&logoColor=white" />
 </p>
 
@@ -50,22 +51,80 @@ Requires-Dist: pyzmq>=25; extra == "zmq"
 - 已安装并登录大 QMT
 - Python `3.8` - `3.12`，生产环境优先使用 `3.10` 或 `3.12`
 
-### 启动步骤
+### 安装方式
+
+#### 方式一：源码包部署（推荐）
+
+新用户和生产环境优先使用源码包部署。原因很简单：cfquant 的 Web 控制台、QMT 入口脚本和本地配置是一起工作的，源码包保留完整项目目录，后续在网页里检查更新、更新 Web、回滚版本、提示 QMT 入口脚本变更都更方便。
 
 1. 将项目解压到固定目录，例如 `D:\cfquant`。
 2. 在项目目录安装依赖：
 
    ```powershell
    cd D:\cfquant
-   pip install -r requirements.txt
+   python -m pip install -r requirements.txt
    ```
 
-3. 运行 `启动cfquant.bat`。
-4. 打开 <http://127.0.0.1:8765/>，按网页中的“新手初始化向导”完成账号、模式和 QMT 目录配置。
-5. 在 QMT 中加载对应的入口脚本，回到网页验证资金、持仓、委托和行情。
+3. 运行 `start_cfquant.bat`。
+
+启动后打开 <http://127.0.0.1:8765/>，按网页中的“新手初始化向导”完成账号、模式和 QMT 目录配置。然后在 QMT 中加载对应的入口脚本，回到网页验证资金、持仓、委托和行情。
+
+重点：
+
+- 源码部署后，网页里的“版本/更新”功能会按完整项目目录更新，适合从官网或 GitHub 拉取新版本。
+- 更新时会尽量保留本地配置、数据库、日志和运行目录，便于日常升级和回滚。
+- 如果新版本修改了 `qmt_scripts/` 里的入口脚本，网页会提示你重新更新 QMT 侧脚本并重启对应 QMT 策略。
+- 建议把源码目录固定下来，例如 `D:\cfquant`，不要频繁挪动目录。
 
 新用户建议先使用**通用模式**。一个 QMT 加载一个入口脚本即可完成大多数部署。
 
+#### 方式二：PyPI 安装（仅推荐库调用或临时体验）
+
+PyPI 适合外部 Python 策略只安装 `cfquant` 库，或者临时体验命令行启动方式；不建议把它作为完整 Web 部署的主要方式。pip 安装后的项目文件位于当前 Python 环境的 `site-packages`，网页里的项目更新、源码回滚和入口脚本同步不如源码包部署直观。
+
+```powershell
+python -m pip install -U cfquant
+```
+
+After installation, you can start the local Web Console:
+
+```powershell
+cfquant --open-browser
+```
+
+如果使用 pip 安装，QMT 侧仍需要加载入口脚本。查看 pip 包内置的 QMT 入口脚本目录：
+
+```powershell
+cfquant qmt-scripts
+```
+
+在 Windows 资源管理器中打开脚本目录：
+
+```powershell
+cfquant qmt-scripts --open
+```
+
+把入口脚本复制到 QMT 可加载目录：
+
+```powershell
+cfquant qmt-scripts --output D:\QMT\cfquant
+```
+
+后续升级 pip 包需要回到命令行执行：
+
+```powershell
+python -m pip install -U cfquant
+cfquant qmt-scripts --output D:\QMT\cfquant --force
+```
+
+升级后建议重启本地 `cfquant` 服务，并在 QMT 中重新加载入口脚本，确保 Web、本地 Python 库和 QMT 侧入口属于同一版本。
+
+验证安装版本和脚本目录：
+
+```powershell
+cfquant version
+```
+
 ## 模式选择
 
 | 模式 | QMT 入口 | 适用场景 |
@@ -78,7 +137,7 @@ Requires-Dist: pyzmq>=25; extra == "zmq"
 
 ## Python 接入
 
-从 PyPI 安装：
+从 PyPI 安装并在外部策略中调用：
 
 ```powershell
 pip install cfquant
@@ -95,22 +154,23 @@ print(tick)
 
 `cfquant` 默认使用 `transport=auto`，通常不需要手动配置通信通道。完整导入方式、路由规则和特殊部署方式见[外部 Python 接入](docs/外部Python接入.md)。
 
-## Web 控制台
+## Web Console
 
-Web 控制台提供账号绑定、资金持仓、委托成交、下单撤单、行情订阅、接口调试、部署教程和更新管理。
+The Web Console provides account binding, cash and positions, order fills, order placement and cancellation, market subscriptions, API debugging, deployment guides, and update management.
 
-常用脚本：
+Common scripts:
 
 ```text
-启动cfquant.bat        启动
-停止cfquant.bat        停止
-重启cfquant.bat        重启
+start_cfquant.bat       Start
+stop_cfquant.bat        Stop
+restart_cfquant.bat     Restart
 ```
 
 ## 文档
 
 | 需求 | 文档 |
 |---|---|
+| QMT 综合部署教程 | [QMT 部署教程](docs/QMT部署教程.md) |
 | 通用模式部署 | [通用模式部署指南](docs/通用模式部署指南.md) |
 | 极致模式部署 | [极致模式部署指南](docs/极致模式部署指南.md) |
 | 高级模式部署 | [高级模式部署指南](docs/高级模式部署指南.md) |
@@ -122,7 +182,7 @@ Web 控制台提供账号绑定、资金持仓、委托成交、下单撤单、
 | 日志、更新和回滚 | [运维与更新](docs/运维与更新.md) |
 | 版本变化 | [版本日志](docs/版本日志.md) |
 
-更详细的图文教程也可以直接在 Web 控制台的“教程”页面查看。
+More detailed tutorials are also available on the Web Console "Tutorials" page.
 
 ## Star History
 

{cfquant-0.2.0 → cfquant-0.2.1}/README.md

@@ -6,6 +6,7 @@
   <a href="https://github.com/95ge/cfquant/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/95ge/cfquant?style=flat&logo=github&label=Issues" /></a>
   <a href="https://github.com/95ge/cfquant/commits/main"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/95ge/cfquant?style=flat&logo=git&label=Last%20commit" /></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat" /></a>
+  <a href="https://pypi.org/project/cfquant/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/cfquant?style=flat&logo=pypi&logoColor=white" /></a>
   <img alt="Python 3.8 to 3.12" src="https://img.shields.io/badge/Python-3.8--3.12-blue?style=flat&logo=python&logoColor=white" />
 </p>
 
@@ -29,22 +30,80 @@
 - 已安装并登录大 QMT
 - Python `3.8` - `3.12`，生产环境优先使用 `3.10` 或 `3.12`
 
-### 启动步骤
+### 安装方式
+
+#### 方式一：源码包部署（推荐）
+
+新用户和生产环境优先使用源码包部署。原因很简单：cfquant 的 Web 控制台、QMT 入口脚本和本地配置是一起工作的，源码包保留完整项目目录，后续在网页里检查更新、更新 Web、回滚版本、提示 QMT 入口脚本变更都更方便。
 
 1. 将项目解压到固定目录，例如 `D:\cfquant`。
 2. 在项目目录安装依赖：
 
    ```powershell
    cd D:\cfquant
-   pip install -r requirements.txt
+   python -m pip install -r requirements.txt
    ```
 
-3. 运行 `启动cfquant.bat`。
-4. 打开 <http://127.0.0.1:8765/>，按网页中的“新手初始化向导”完成账号、模式和 QMT 目录配置。
-5. 在 QMT 中加载对应的入口脚本，回到网页验证资金、持仓、委托和行情。
+3. 运行 `start_cfquant.bat`。
+
+启动后打开 <http://127.0.0.1:8765/>，按网页中的“新手初始化向导”完成账号、模式和 QMT 目录配置。然后在 QMT 中加载对应的入口脚本，回到网页验证资金、持仓、委托和行情。
+
+重点：
+
+- 源码部署后，网页里的“版本/更新”功能会按完整项目目录更新，适合从官网或 GitHub 拉取新版本。
+- 更新时会尽量保留本地配置、数据库、日志和运行目录，便于日常升级和回滚。
+- 如果新版本修改了 `qmt_scripts/` 里的入口脚本，网页会提示你重新更新 QMT 侧脚本并重启对应 QMT 策略。
+- 建议把源码目录固定下来，例如 `D:\cfquant`，不要频繁挪动目录。
 
 新用户建议先使用**通用模式**。一个 QMT 加载一个入口脚本即可完成大多数部署。
 
+#### 方式二：PyPI 安装（仅推荐库调用或临时体验）
+
+PyPI 适合外部 Python 策略只安装 `cfquant` 库，或者临时体验命令行启动方式；不建议把它作为完整 Web 部署的主要方式。pip 安装后的项目文件位于当前 Python 环境的 `site-packages`，网页里的项目更新、源码回滚和入口脚本同步不如源码包部署直观。
+
+```powershell
+python -m pip install -U cfquant
+```
+
+After installation, you can start the local Web Console:
+
+```powershell
+cfquant --open-browser
+```
+
+如果使用 pip 安装，QMT 侧仍需要加载入口脚本。查看 pip 包内置的 QMT 入口脚本目录：
+
+```powershell
+cfquant qmt-scripts
+```
+
+在 Windows 资源管理器中打开脚本目录：
+
+```powershell
+cfquant qmt-scripts --open
+```
+
+把入口脚本复制到 QMT 可加载目录：
+
+```powershell
+cfquant qmt-scripts --output D:\QMT\cfquant
+```
+
+后续升级 pip 包需要回到命令行执行：
+
+```powershell
+python -m pip install -U cfquant
+cfquant qmt-scripts --output D:\QMT\cfquant --force
+```
+
+升级后建议重启本地 `cfquant` 服务，并在 QMT 中重新加载入口脚本，确保 Web、本地 Python 库和 QMT 侧入口属于同一版本。
+
+验证安装版本和脚本目录：
+
+```powershell
+cfquant version
+```
+
 ## 模式选择
 
 | 模式 | QMT 入口 | 适用场景 |
@@ -57,7 +116,7 @@
 
 ## Python 接入
 
-从 PyPI 安装：
+从 PyPI 安装并在外部策略中调用：
 
 ```powershell
 pip install cfquant
@@ -74,22 +133,23 @@ print(tick)
 
 `cfquant` 默认使用 `transport=auto`，通常不需要手动配置通信通道。完整导入方式、路由规则和特殊部署方式见[外部 Python 接入](docs/外部Python接入.md)。
 
-## Web 控制台
+## Web Console
 
-Web 控制台提供账号绑定、资金持仓、委托成交、下单撤单、行情订阅、接口调试、部署教程和更新管理。
+The Web Console provides account binding, cash and positions, order fills, order placement and cancellation, market subscriptions, API debugging, deployment guides, and update management.
 
-常用脚本：
+Common scripts:
 
 ```text
-启动cfquant.bat        启动
-停止cfquant.bat        停止
-重启cfquant.bat        重启
+start_cfquant.bat       Start
+stop_cfquant.bat        Stop
+restart_cfquant.bat     Restart
 ```
 
 ## 文档
 
 | 需求 | 文档 |
 |---|---|
+| QMT 综合部署教程 | [QMT 部署教程](docs/QMT部署教程.md) |
 | 通用模式部署 | [通用模式部署指南](docs/通用模式部署指南.md) |
 | 极致模式部署 | [极致模式部署指南](docs/极致模式部署指南.md) |
 | 高级模式部署 | [高级模式部署指南](docs/高级模式部署指南.md) |
@@ -101,7 +161,7 @@ Web 控制台提供账号绑定、资金持仓、委托成交、下单撤单、
 | 日志、更新和回滚 | [运维与更新](docs/运维与更新.md) |
 | 版本变化 | [版本日志](docs/版本日志.md) |
 
-更详细的图文教程也可以直接在 Web 控制台的“教程”页面查看。
+More detailed tutorials are also available on the Web Console "Tutorials" page.
 
 ## Star History
 

{cfquant-0.2.0 → cfquant-0.2.1}/cfquant/cli.py

@@ -7,6 +7,7 @@ import argparse
 import os
 import shutil
 import socket
+import subprocess
 import sys
 import threading
 import time
@@ -31,13 +32,40 @@ QMT_SCRIPT_FILES = (
 )
 
 
+def _configure_console_encoding():
+    """Keep Chinese CLI output readable on Windows and redirected consoles."""
+    os.environ.setdefault("PYTHONUTF8", "1")
+    os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name, None)
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+
 def _package_version():
+    project_file = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    try:
+        for line in project_file.read_text(encoding="utf-8").splitlines():
+            if line.strip().startswith("version"):
+                name, value = line.split("=", 1)
+                if name.strip() == "version":
+                    return value.strip().strip('"').strip("'")
+    except Exception:
+        pass
+
     try:
         from importlib import metadata
 
-        return metadata.version("cfquant")
+        dist = metadata.distribution("cfquant")
+        return dist.version
     except Exception:
-        return "unknown"
+        pass
+    return "unknown"
 
 
 def _port(value):
@@ -79,37 +107,40 @@ def _serve_parser(prog="cfquant"):
     help_command = "%s serve --help" % prog if prog == "cfquant" else "%s --help" % prog
     if prog == "cfquant":
         epilog = (
-            "Commands:\n"
-            "  cfquant pipe-hub [options]             Start only the named-pipe hub.\n"
-            "  cfquant qmt-scripts --output DIRECTORY Export bundled QMT entry scripts.\n"
-            "  cfquant version                         Show installed package details.\n"
-            "Use '%s' for dashboard options." % help_command
+            "常用命令:\n"
+            "  cfquant                                启动本地 Web 控制台。\n"
+            "  cfquant qmt-scripts                    查看已安装的 QMT 入口脚本目录。\n"
+            "  cfquant qmt-scripts --open             在资源管理器中打开 QMT 入口脚本目录。\n"
+            "  cfquant qmt-scripts --output DIRECTORY 导出 QMT 入口脚本到指定目录。\n"
+            "  cfquant pipe-hub [options]             只启动 named-pipe hub。\n"
+            "  cfquant version                        显示安装版本和目录。\n"
+            "使用 '%s' 查看 Web 启动参数。" % help_command
         )
     else:
-        epilog = "Use '%s' for dashboard options." % help_command
+        epilog = "使用 '%s' 查看 Web 启动参数。" % help_command
     parser = argparse.ArgumentParser(
         prog=prog,
-        description="Start the cfquant local web dashboard.",
+        description="启动 cfquant 本地 Web 控制台。",
         epilog=epilog,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    parser.add_argument("--host", help="Web bind address. Defaults to localhost or saved configuration.")
-    parser.add_argument("--port", type=_port, help="Web listen port. Defaults to saved configuration or 8765.")
+    parser.add_argument("--host", help="Web 绑定地址。默认使用本机地址或已保存配置。")
+    parser.add_argument("--port", type=_port, help="Web 监听端口。默认使用已保存配置或 8765。")
     parser.add_argument(
         "--home",
         "--state-dir",
         dest="home",
-        help="Writable cfquant state directory for runtime data, configuration, and logs.",
+        help="cfquant 可写运行目录，用于保存配置、数据库、日志和状态文件。",
     )
-    parser.add_argument("--runtime-dir", help="Override the runtime subdirectory.")
-    parser.add_argument("--log-dir", help="Override the log directory.")
-    parser.add_argument("--config", help="Path to the web configuration JSON file.")
-    parser.add_argument("--pipe-name", help=r"Override the QMT named pipe, e.g. \\.\pipe\cfquant_pipe_hub.")
-    parser.add_argument("--lttx-host", help="LTtx host. Defaults to 127.0.0.1.")
-    parser.add_argument("--lttx-port", type=_port, help="LTtx port. Defaults to 2049.")
-    parser.add_argument("--account-id", help="Default account ID before the web setup wizard is completed.")
-    parser.add_argument("--open-browser", action="store_true", help="Open the dashboard in the default browser after it is ready.")
-    parser.add_argument("--dry-run", action="store_true", help="Print the effective startup settings without starting services.")
+    parser.add_argument("--runtime-dir", help="覆盖 runtime 子目录。")
+    parser.add_argument("--log-dir", help="覆盖日志目录。")
+    parser.add_argument("--config", help="Web 配置 JSON 文件路径。")
+    parser.add_argument("--pipe-name", help=r"覆盖 QMT named pipe 名称，例如 \\.\pipe\cfquant_pipe_hub。")
+    parser.add_argument("--lttx-host", help="LTtx 地址。默认 127.0.0.1。")
+    parser.add_argument("--lttx-port", type=_port, help="LTtx 端口。默认 2049。")
+    parser.add_argument("--account-id", help="Web 初始化完成前使用的默认资金账号。")
+    parser.add_argument("--open-browser", action="store_true", help="服务就绪后自动打开浏览器。")
+    parser.add_argument("--dry-run", action="store_true", help="只打印启动参数，不启动服务。")
     parser.add_argument("--version", action="version", version=_version_text())
     return parser
 
@@ -127,6 +158,41 @@ def _browser_url(host, port):
     return "http://%s:%s/" % (host, port)
 
 
+def _resolve_web_address(args):
+    host = args.host or os.environ.get("CFQUANT_WEB_HOST")
+    port = args.port
+    if host and port is not None:
+        return host, port
+
+    try:
+        from cfquant_web_server import WEB_CONFIG, normalize_web_port
+
+        if not host:
+            host = "0.0.0.0" if WEB_CONFIG.allow_remote() else "127.0.0.1"
+        if port is None:
+            port = normalize_web_port(
+                os.environ.get("CFQUANT_WEB_PORT"),
+                default=WEB_CONFIG.web_port(),
+            )
+    except Exception:
+        if not host:
+            host = "127.0.0.1"
+        if port is None:
+            port = 8765
+    return host, port
+
+
+def _print_startup_banner(args):
+    host, port = _resolve_web_address(args)
+    command = "cfquant"
+    print("cfquant 本地服务启动中...")
+    print("包版本: %s | 核心版本: %s | Web版本: %s" % (_package_version(), CORE_VERSION, WEB_VERSION))
+    print("Web 控制台: %s" % _browser_url(host, port))
+    print("QMT 入口脚本目录: %s" % _qmt_scripts_source_dir())
+    print("查看脚本目录: %s qmt-scripts --show" % command)
+    print(r"导出 QMT 入口脚本: %s qmt-scripts --output D:\QMT\cfquant" % command)
+
+
 def _wait_and_open_browser(host, port):
     connect_host = str(host or "").strip()
     if not connect_host or connect_host in ("0.0.0.0", "::"):
@@ -143,11 +209,14 @@ def _wait_and_open_browser(host, port):
 
 
 def _serve(argv, prog="cfquant"):
+    _configure_console_encoding()
     parser = _serve_parser(prog)
     args = parser.parse_args(argv)
     _apply_web_environment(args)
     if args.dry_run:
+        print("cfquant 启动参数预览")
         print("cfquant package=%s core=%s web=%s" % (_package_version(), CORE_VERSION, WEB_VERSION))
+        print("QMT 入口脚本目录=%s" % _qmt_scripts_source_dir())
         for key in (
             "CFQUANT_HOME",
             "CFQUANT_RUNTIME_DIR",
@@ -169,18 +238,9 @@ def _serve(argv, prog="cfquant"):
         server_args.extend(["--host", args.host])
     if args.port:
         server_args.extend(["--port", str(args.port)])
+    _print_startup_banner(args)
     if args.open_browser:
-        from cfquant_web_server import WEB_CONFIG, normalize_web_port
-
-        host = args.host or os.environ.get("CFQUANT_WEB_HOST")
-        if not host:
-            host = "0.0.0.0" if WEB_CONFIG.allow_remote() else "127.0.0.1"
-        port = args.port
-        if port is None:
-            port = normalize_web_port(
-                os.environ.get("CFQUANT_WEB_PORT"),
-                default=WEB_CONFIG.web_port(),
-            )
+        host, port = _resolve_web_address(args)
         thread = threading.Thread(target=_wait_and_open_browser, args=(host, port))
         thread.daemon = True
         thread.start()
@@ -196,27 +256,66 @@ def _qmt_scripts_source_dir():
 def _qmt_scripts_parser():
     parser = argparse.ArgumentParser(
         prog="cfquant qmt-scripts",
-        description="Export the QMT entry scripts bundled with this cfquant installation.",
+        description="查看、打开或导出当前 cfquant 安装包内置的 QMT 入口脚本。",
     )
-    parser.add_argument("--output", "-o", required=True, help="Destination directory for QMT scripts.")
-    parser.add_argument("--force", action="store_true", help="Overwrite existing files in the destination.")
+    parser.add_argument("--show", action="store_true", help="显示当前安装包内置的 QMT 脚本目录。")
+    parser.add_argument("--list", dest="list_files", action="store_true", help="列出内置 QMT 脚本文件。")
+    parser.add_argument("--open", dest="open_dir", action="store_true", help="在系统文件管理器中打开 QMT 脚本目录。")
+    parser.add_argument("--output", "-o", help="把 QMT 脚本导出到指定目录。")
+    parser.add_argument("--force", action="store_true", help="导出时覆盖目标目录中的同名文件。")
     return parser
 
 
+def _validate_qmt_scripts(source_dir):
+    missing = [name for name in QMT_SCRIPT_FILES if not (source_dir / name).is_file()]
+    if missing:
+        raise RuntimeError("当前 cfquant 安装包缺少 QMT 脚本: %s" % ", ".join(missing))
+
+
+def _print_qmt_scripts_info(source_dir, list_files=False):
+    print("QMT 入口脚本目录: %s" % source_dir)
+    print("查看目录: cfquant qmt-scripts --open")
+    print(r"导出命令: cfquant qmt-scripts --output D:\QMT\cfquant")
+    if list_files:
+        print("内置脚本文件:")
+        for relative_name in QMT_SCRIPT_FILES:
+            print("  %s" % relative_name)
+
+
+def _open_directory(path):
+    if os.name == "nt" and hasattr(os, "startfile"):
+        os.startfile(str(path))  # pylint: disable=no-member
+        return
+    command = "open" if sys.platform == "darwin" else "xdg-open"
+    if shutil.which(command) is None:
+        raise RuntimeError("当前系统未找到可用的文件管理器打开命令: %s" % command)
+    subprocess.Popen([command, str(path)])
+
+
 def _export_qmt_scripts(argv):
     parser = _qmt_scripts_parser()
     args = parser.parse_args(argv)
+    source_dir = _qmt_scripts_source_dir()
+    _validate_qmt_scripts(source_dir)
+
+    if not args.output and not args.show and not args.list_files and not args.open_dir:
+        args.show = True
+        args.list_files = True
+
+    if args.show or args.list_files:
+        _print_qmt_scripts_info(source_dir, list_files=args.list_files)
+    if args.open_dir:
+        _open_directory(source_dir)
+        print("已打开 QMT 入口脚本目录: %s" % source_dir)
+    if not args.output:
+        return 0
+
     output_dir = Path(_path(args.output))
     if output_dir.exists() and not output_dir.is_dir():
-        parser.error("output path is not a directory: %s" % output_dir)
-
-    source_dir = _qmt_scripts_source_dir()
-    missing = [name for name in QMT_SCRIPT_FILES if not (source_dir / name).is_file()]
-    if missing:
-        raise RuntimeError("installed cfquant package is missing QMT scripts: %s" % ", ".join(missing))
+        parser.error("输出路径不是目录: %s" % output_dir)
     existing = [name for name in QMT_SCRIPT_FILES if (output_dir / name).exists()]
     if existing and not args.force:
-        parser.error("destination already has files; use --force to replace: %s" % ", ".join(existing))
+        parser.error("目标目录已存在同名文件；如需覆盖请加 --force: %s" % ", ".join(existing))
 
     output_dir.mkdir(parents=True, exist_ok=True)
     for relative_name in QMT_SCRIPT_FILES:
@@ -224,7 +323,7 @@ def _export_qmt_scripts(argv):
         target = output_dir / relative_name
         target.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(str(source), str(target))
-    print("Exported %s QMT files to %s" % (len(QMT_SCRIPT_FILES), output_dir))
+    print("已导出 %s 个 QMT 入口脚本到: %s" % (len(QMT_SCRIPT_FILES), output_dir))
     return 0
 
 
@@ -232,8 +331,10 @@ def _print_version():
     package_root = Path(__file__).resolve().parent
     qmt_scripts_dir = _qmt_scripts_source_dir()
     print(_version_text())
-    print("package_root %s" % package_root)
-    print("qmt_scripts %s" % qmt_scripts_dir)
+    print("cfquant 包目录 %s" % package_root)
+    print("QMT 入口脚本目录 %s" % qmt_scripts_dir)
+    print("打开脚本目录 cfquant qmt-scripts --open")
+    print(r"导出脚本目录 cfquant qmt-scripts --output D:\QMT\cfquant")
     return 0
 
 
@@ -243,6 +344,7 @@ def web_main(argv=None):
 
 
 def main(argv=None):
+    _configure_console_encoding()
     argv = list(sys.argv[1:] if argv is None else argv)
     if not argv:
         return _serve([])

cfquant-0.2.1/cfquant/version.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+"""cfquant core version metadata."""
+
+__version__ = "core_20260904_02"
+WEB_VERSION = "web_20260904_11"

{cfquant-0.2.0 → cfquant-0.2.1}/cfquant.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cfquant
-Version: 0.2.0
+Version: 0.2.1
 Summary: QMT local bridge and xtquant-compatible Python client.
 License: MIT
 Requires-Python: >=3.8
@@ -27,6 +27,7 @@ Requires-Dist: pyzmq>=25; extra == "zmq"
   <a href="https://github.com/95ge/cfquant/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/95ge/cfquant?style=flat&logo=github&label=Issues" /></a>
   <a href="https://github.com/95ge/cfquant/commits/main"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/95ge/cfquant?style=flat&logo=git&label=Last%20commit" /></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat" /></a>
+  <a href="https://pypi.org/project/cfquant/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/cfquant?style=flat&logo=pypi&logoColor=white" /></a>
   <img alt="Python 3.8 to 3.12" src="https://img.shields.io/badge/Python-3.8--3.12-blue?style=flat&logo=python&logoColor=white" />
 </p>
 
@@ -50,22 +51,80 @@ Requires-Dist: pyzmq>=25; extra == "zmq"
 - 已安装并登录大 QMT
 - Python `3.8` - `3.12`，生产环境优先使用 `3.10` 或 `3.12`
 
-### 启动步骤
+### 安装方式
+
+#### 方式一：源码包部署（推荐）
+
+新用户和生产环境优先使用源码包部署。原因很简单：cfquant 的 Web 控制台、QMT 入口脚本和本地配置是一起工作的，源码包保留完整项目目录，后续在网页里检查更新、更新 Web、回滚版本、提示 QMT 入口脚本变更都更方便。
 
 1. 将项目解压到固定目录，例如 `D:\cfquant`。
 2. 在项目目录安装依赖：
 
    ```powershell
    cd D:\cfquant
-   pip install -r requirements.txt
+   python -m pip install -r requirements.txt
    ```
 
-3. 运行 `启动cfquant.bat`。
-4. 打开 <http://127.0.0.1:8765/>，按网页中的“新手初始化向导”完成账号、模式和 QMT 目录配置。
-5. 在 QMT 中加载对应的入口脚本，回到网页验证资金、持仓、委托和行情。
+3. 运行 `start_cfquant.bat`。
+
+启动后打开 <http://127.0.0.1:8765/>，按网页中的“新手初始化向导”完成账号、模式和 QMT 目录配置。然后在 QMT 中加载对应的入口脚本，回到网页验证资金、持仓、委托和行情。
+
+重点：
+
+- 源码部署后，网页里的“版本/更新”功能会按完整项目目录更新，适合从官网或 GitHub 拉取新版本。
+- 更新时会尽量保留本地配置、数据库、日志和运行目录，便于日常升级和回滚。
+- 如果新版本修改了 `qmt_scripts/` 里的入口脚本，网页会提示你重新更新 QMT 侧脚本并重启对应 QMT 策略。
+- 建议把源码目录固定下来，例如 `D:\cfquant`，不要频繁挪动目录。
 
 新用户建议先使用**通用模式**。一个 QMT 加载一个入口脚本即可完成大多数部署。
 
+#### 方式二：PyPI 安装（仅推荐库调用或临时体验）
+
+PyPI 适合外部 Python 策略只安装 `cfquant` 库，或者临时体验命令行启动方式；不建议把它作为完整 Web 部署的主要方式。pip 安装后的项目文件位于当前 Python 环境的 `site-packages`，网页里的项目更新、源码回滚和入口脚本同步不如源码包部署直观。
+
+```powershell
+python -m pip install -U cfquant
+```
+
+After installation, you can start the local Web Console:
+
+```powershell
+cfquant --open-browser
+```
+
+如果使用 pip 安装，QMT 侧仍需要加载入口脚本。查看 pip 包内置的 QMT 入口脚本目录：
+
+```powershell
+cfquant qmt-scripts
+```
+
+在 Windows 资源管理器中打开脚本目录：
+
+```powershell
+cfquant qmt-scripts --open
+```
+
+把入口脚本复制到 QMT 可加载目录：
+
+```powershell
+cfquant qmt-scripts --output D:\QMT\cfquant
+```
+
+后续升级 pip 包需要回到命令行执行：
+
+```powershell
+python -m pip install -U cfquant
+cfquant qmt-scripts --output D:\QMT\cfquant --force
+```
+
+升级后建议重启本地 `cfquant` 服务，并在 QMT 中重新加载入口脚本，确保 Web、本地 Python 库和 QMT 侧入口属于同一版本。
+
+验证安装版本和脚本目录：
+
+```powershell
+cfquant version
+```
+
 ## 模式选择
 
 | 模式 | QMT 入口 | 适用场景 |
@@ -78,7 +137,7 @@ Requires-Dist: pyzmq>=25; extra == "zmq"
 
 ## Python 接入
 
-从 PyPI 安装：
+从 PyPI 安装并在外部策略中调用：
 
 ```powershell
 pip install cfquant
@@ -95,22 +154,23 @@ print(tick)
 
 `cfquant` 默认使用 `transport=auto`，通常不需要手动配置通信通道。完整导入方式、路由规则和特殊部署方式见[外部 Python 接入](docs/外部Python接入.md)。
 
-## Web 控制台
+## Web Console
 
-Web 控制台提供账号绑定、资金持仓、委托成交、下单撤单、行情订阅、接口调试、部署教程和更新管理。
+The Web Console provides account binding, cash and positions, order fills, order placement and cancellation, market subscriptions, API debugging, deployment guides, and update management.
 
-常用脚本：
+Common scripts:
 
 ```text
-启动cfquant.bat        启动
-停止cfquant.bat        停止
-重启cfquant.bat        重启
+start_cfquant.bat       Start
+stop_cfquant.bat        Stop
+restart_cfquant.bat     Restart
 ```
 
 ## 文档
 
 | 需求 | 文档 |
 |---|---|
+| QMT 综合部署教程 | [QMT 部署教程](docs/QMT部署教程.md) |
 | 通用模式部署 | [通用模式部署指南](docs/通用模式部署指南.md) |
 | 极致模式部署 | [极致模式部署指南](docs/极致模式部署指南.md) |
 | 高级模式部署 | [高级模式部署指南](docs/高级模式部署指南.md) |
@@ -122,7 +182,7 @@ Web 控制台提供账号绑定、资金持仓、委托成交、下单撤单、
 | 日志、更新和回滚 | [运维与更新](docs/运维与更新.md) |
 | 版本变化 | [版本日志](docs/版本日志.md) |
 
-更详细的图文教程也可以直接在 Web 控制台的“教程”页面查看。
+More detailed tutorials are also available on the Web Console "Tutorials" page.
 
 ## Star History
 

{cfquant-0.2.0 → cfquant-0.2.1}/cfquant.egg-info/SOURCES.txt

@@ -82,14 +82,4 @@ web_dashboard/image/qmt_deploy/image-6.png
 web_dashboard/image/qmt_deploy/image-7.png
 web_dashboard/image/qmt_deploy/image-8.png
 web_dashboard/image/qmt_deploy/image-9.png
-web_dashboard/image/通用模式部署指南/image-1.png
-web_dashboard/image/通用模式部署指南/image-2.png
-web_dashboard/image/通用模式部署指南/image-3.png
-web_dashboard/image/通用模式部署指南/image.png
-web_dashboard/image/部署指南/1783479325179.png
-web_dashboard/image/部署指南/1783479745262.png
-web_dashboard/image/部署指南/1783480178700.png
-web_dashboard/image/部署指南/1783480428759.png
-web_dashboard/image/部署指南/1783489807217.png
-web_dashboard/image/部署指南/1783490503491.png
 web_dashboard/vendor/mermaid.min.js

{cfquant-0.2.0 → cfquant-0.2.1}/cfquant_web_server.py

@@ -7992,7 +7992,7 @@ def stop_lttx_server(full_exit=False):
         return {
             "stopped": False,
             "blocked": True,
-            "reason": "LTtx 会在 Web 重启和定时重启期间保持运行；请使用 停止cfquant.bat 完整退出时再停止 LTtx。",
+            "reason": "LTtx 会在 Web 重启和定时重启期间保持运行；请使用 stop_cfquant.bat 完整退出时再停止 LTtx。",
             "status": before,
         }
     if not before["running"]:

{cfquant-0.2.0 → cfquant-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cfquant"
-version = "0.2.0"
+version = "0.2.1"
 description = "QMT local bridge and xtquant-compatible Python client."
 license = {text = "MIT"}
 readme = "README.md"

{cfquant-0.2.0 → cfquant-0.2.1}/web_dashboard/app.js

@@ -1,4 +1,4 @@
-const FRONTEND_VERSION = 'web_20260904_09';
+const FRONTEND_VERSION = 'web_20260904_11';
 
 const state = {
   accountId: '',
@@ -6851,7 +6851,7 @@ function renderLttxStatus(data) {
   } else if (!data) {
     runtime.textContent = 'LTtx 状态未知';
   } else {
-    runtime.textContent = `LTtx 未运行，cfquant Python 库自动发现不可用；可通过网页或 cfquant\\启动cfquant.bat 启动。`;
+    runtime.textContent = `LTtx 未运行，cfquant Python 库自动发现不可用；可通过网页或 cfquant\\start_cfquant.bat 启动。`;
   }
 }
 

{cfquant-0.2.0 → cfquant-0.2.1}/web_dashboard/index.html

@@ -5,7 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>cfquant 控制台</title>
   <link rel="icon" type="image/svg+xml" href="/favicon.svg">
-  <link rel="stylesheet" href="/styles.css?v=web_20260904_09">
+  <link rel="stylesheet" href="/styles.css?v=web_20260904_11">
 </head>
 <body>
   <div id="webAuthOverlay" class="auth-overlay hidden" aria-live="polite">
@@ -1439,7 +1439,7 @@
                   <div class="guide-section">
                     <h3>快速开始</h3>
                     <ol class="guide-list detailed">
-                      <li><strong>启动服务。</strong>运行 <code>启动cfquant.bat</code>，或执行 <code>cfquant --open-browser</code>。</li>
+                      <li><strong>启动服务。</strong>运行 <code>start_cfquant.bat</code>，或执行 <code>cfquant --open-browser</code>。</li>
                       <li><strong>完成初始化。</strong>填写资金账号、账户类型、QMT <code>bin.x64</code> 目录和运行模式。</li>
                       <li><strong>部署 QMT。</strong>按“QMT 部署教程”复制核心包和入口脚本。</li>
                       <li><strong>启动脚本。</strong>通用模式启动一个入口；高级模式分别启动普通端和极速交易端。</li>
@@ -1535,7 +1535,7 @@ configure(transport="ctypes", pipe_name=r"\\.\pipe\cfquant_pipe_hub")
                     <div class="deploy-primer-grid">
                       <div>
                         <strong>1. 先启动本地服务</strong>
-                        <span>通过 <code>启动cfquant.bat</code> 或 <code>cfquant --open-browser</code> 打开 Web 控制台，默认地址是 <code>http://127.0.0.1:8765/</code>。</span>
+                        <span>通过 <code>start_cfquant.bat</code> 或 <code>cfquant --open-browser</code> 打开 Web 控制台，默认地址是 <code>http://127.0.0.1:8765/</code>。</span>
                       </div>
                       <div>
                         <strong>2. 再准备 QMT 环境</strong>
@@ -2312,6 +2312,6 @@ configure(transport="ctypes", pipe_name=r"\\.\pipe\cfquant_pipe_hub")
   </div>
 
   <script src="/vendor/mermaid.min.js?v=10.9.1"></script>
-  <script src="/app.js?v=web_20260904_09"></script>
+  <script src="/app.js?v=web_20260904_11"></script>
 </body>
 </html>

cfquant-0.2.0/cfquant/version.py

@@ -1,5 +0,0 @@
-# -*- coding: utf-8 -*-
-"""cfquant core version metadata."""
-
-__version__ = "core_20260904_01"
-WEB_VERSION = "web_20260904_09"