macOS 端使用教程 - khQuant看海量化交易平台

概述

继成功兼容 Linux 之后，看海量化（KhQuant）从 v3.3.3 起正式兼容 macOS，至此完成了 Windows、macOS、Linux 三端的跨平台拼图。

与 Linux 端定位为轻量纯 CLI 不同，macOS 端面向的是桌面研发场景，因此保留了完整的图形界面（PyQt5 GUI），并针对 Mac 系统特性做了深度适配。三端共用同一套策略代码与 .kh 配置文件，可自# 第六章：macOS 适配与使用教程

概述

继成功兼容 Linux 之后，看海量化（KhQuant）从 v3.3.3 起正式兼容 macOS，至此完成了 Windows、macOS、Linux 三端的跨平台拼图。

与 Linux 端定位为轻量纯 CLI 不同，macOS 端面向的是桌面研发场景，因此保留了完整的图形界面（PyQt5 GUI），并针对 Mac 系统特性做了深度适配。三端共用同一套策略代码与 .kh 配置文件，可自由迁移数据库，并获得完全一致的回测结果。

本章将讲清两件事：macOS 端做了哪些适配，以及适配之后如何在 Mac 上把看海量化用起来。

重要说明：macOS 版软件的绝大部分操作与 Windows 版完全一致（界面布局、配置加载、策略编写、回测运行、报告查看等），因此通用功能可直接参考本手册及官网的现有教程，无需重复学习。macOS 平台特有的使用方法（如系统路径、命令行工具安装、数据获取与跨平台同步等差异点），将在本篇及后续文章中专篇论述。

适用版本：v3.3.3 及以上。本章内容不影响 Windows 与 Linux 用户的既有使用方式。

一、为什么要在 macOS 上保留 GUI

在做 Linux 兼容时，出于服务器部署、轻量化与依赖隔离的考虑，我们没有启用 GUI。但 macOS 用户的使用场景完全不同：Mac 用户绝大多数是在桌面环境（MacBook 屏幕或外接高分屏）下进行策略开发与定量研究。如果只提供命令行，对日常高频的”策略调整 → 历史回测 → 图表分析”迭代不够便捷。

为给 macOS 用户提供更好的研发体验，跨平台适配遵循了三个核心原则：

逻辑 100% 同构：三端共用底层策略生命周期（init / khPreMarket / khHandlebar）与 .kh 配置文件。在任一平台上编写、调试的策略，均可在其他平台无缝运行，回测逻辑与计算结果完全一致。
适配 macOS 平台特性：针对 macOS 系统环境，在界面字体、高分辨率（Retina）DPI 适配、标准系统路径（数据与日志默认存入 ~/Library/Application Support/）以及启动窗口置顶激活机制上做了专属优化。
清晰划分功能边界：受限于国内券商接口生态，miniQMT 客户端与原生交易接口（xtquant）依旧是 Windows 专属。在 macOS 界面中主动精简了这些暂不支持的功能入口，保持界面清爽专注，避免误导。

二、macOS 版功能对比：能做什么，不能做什么

在 macOS 终端中运行 kh doctor 或 kh version，可查看当前系统状态，会输出类似：平台: macOS | 能力: GUI, DuckDB, BaoStock, Tushare。

下表整理了三大平台的功能支持情况，便于你在部署前对照：

维度	Windows 桌面版	macOS 桌面版	Linux 服务器版
图形界面 (PyQt5 GUI)	支持（全功能）	支持（针对 Mac 适配）	不支持（无 GUI）
命令行工具 (CLI)	支持（`kh` 命令）	支持（`kh` 命令）	支持（`kh` 命令）
券商交易接口 (xtquant)	支持（需 miniQMT）	不支持	不支持
miniQMT 客户端唤起	支持	不支持	不支持
本地 DuckDB 存储	支持	支持	支持
外接科学数据源	BaoStock / Tushare / xtdata	BaoStock / Tushare	BaoStock / Tushare
内置编辑器及调试	支持（外嵌 VSCode）	不支持（用系统 VS Code）	不支持
自动检查与更新	支持（一键下载 exe）	不支持（走 git/pipx）	不支持

一句话总结：macOS 端除了用不了 miniQMT/xtquant（数据源与实盘接口）、不内置 VSCode 调试这两点之外，GUI、DuckDB、第三方数据源、回测与报告等核心能力与 Windows 端完全一致。

三、macOS 深度适配：主体功能与数据管理

为让看海量化在 macOS 上运行得更高效，我们对界面与底层数据流做了深度适配与裁剪。

1. 视觉与主体功能完全一致

我们为 macOS 适配了标准的浅色（白色）软件主题，使之与 Mac 系统原生视觉风格保持一致。界面之下，主体功能得到 100% 保留与对齐：

DuckDB 数据库支持：使用与 Windows 端相同的本地高并发 DuckDB 存储引擎，保证高效的数据读写。

T+0 交易适配：完整支持 T+0 交易规则（如符合日内 T+0 的 ETF 基金交易），提供精确的持仓与资金占用计算。
回测报告生成：支持无头模式（headless）下图表的正确渲染。回测结束后，自动生成包含资金曲线、交易分布及多维风险指标的 HTML 报告。

2. 精简后的数据管理界面

由于 miniQMT 客户端无法在 macOS 平台运行，本着精简、清晰的原则，在 macOS 桌面端中：

隐藏并禁用了 miniQMT 的客户端启动、设置与自动调用接口。
移除了 Windows 专属的”从 miniQMT/xtdata 导入数据”模块，界面上仅保留本地 DuckDB 数据管理器，降低界面冗余，提升上手直观性。

3. 完整保留的 CLI 命令行功能

看海量化强大的命令行工具（CLI）在 macOS 下得到了完整保留，可在终端中完成所有策略回测、数据管理与参数调优。

全局 kh 命令一键安装：在 macOS GUI 工具栏中提供了「安装命令行工具」按钮。点击后，系统会自动在 /usr/local/bin/kh 创建软链接，指向内置核心程序。此后只需在 Mac 终端输入 kh run configs/demo.kh 即可跑回测。
完美的 ANSI 颜色与输出支持：macOS 终端原生支持 ANSI 颜色，回测过程中的日志、对齐报表及命令行交互体验良好。

四、安装指南：如何在 Mac 上装好看海量化

下载地址：macOS 版安装包（DMG）请前往官网下载页获取 👉 https://khsci.com/khQuant/beta/

注意：支持 macOS 系统的版本目前仅对内测用户开放。如尚未加入内测，可关注公众号「看海的城堡」了解开通方式。

1. 方式 A：标准 DMG 安装包（推荐普通用户）

获得 khQuant_Mac_V3.3.3.dmg 安装包后双击打开。
将 khQuant.app 图标拖拽至 Applications（应用程序）文件夹快捷方式中。
首次启动如果弹出”无法验证开发者”的系统拦截，请前往 Mac 系统设置 → 隐私与安全性，点击”仍要打开”即可。
启动后，在”设置”中完成初始目录（数据、策略、回测结果）的配置。

2. 方式 B：源码运行（适合开发者与内测用户）

# 1. 克隆或下载代码到本地目录后进入
cd /path/to/khQuant/code

# 2. 安装跨平台依赖（确保使用的是 Python 3.10+）
pip3 install -r requirements.txt

# 3. 运行主界面
python3 GUIkhQuant.py

提示：Mac 系统下运行源码需本机已正确安装 PyQt5。

五、快速上手：在 Mac 上跑通第一个回测

安装完成后，按以下流程即可在 Mac 上完成从准备数据到查看报告的完整闭环。

第一步：完成初始目录配置

首次启动后进入”设置”，确认数据目录、策略目录、回测结果目录已配置。macOS 端默认会指向标准系统路径 ~/Library/Application Support/khQuant/，一般保持默认即可。

第二步：准备历史数据

由于 macOS 没有 xtdata 数据源，需先通过第三方数据源把行情拉到本地 DuckDB。可在 GUI 的数据管理界面操作，或在终端使用 CLI：

kh data download --source baostock --stocks 000001.SZ --period 1d --start 20240101

BaoStock 免 token、不限流，是 macOS 端推荐的免费数据源。Tushare 亦受支持。

第三步：加载配置与策略

在主界面点击「加载配置」，选择一个 .kh 配置文件（如随源码附带的示例配置）。
源码下载到本地后路径可能变化，需在「策略文件路径」处点击「…」浏览，重新指定要运行的 .py 策略文件。
在「股票池设置」中填入要回测的标的代码（如 513050.SH）。

第四步：运行回测并查看报告

确认起止时间、初始资金等参数符合预期。
点击「运行回测」，观察日志输出等待完成。
回测结束后自动生成 HTML 报告，可在 Mac 上用浏览器直接打开，查看资金曲线、交易明细与关键指标。

也可在终端用 kh run configs/your_config.kh 跑回测，与 GUI 完全等价。CLI 的完整用法（示例策略、参数、报告查看等）见官网 CLI 命令行工具指南，三端通用。

六、macOS 端的回测数据获取路径

在没有 miniQMT 数据源的情况下，macOS 用户依然可以通过以下几种方式轻松获取和同步行情数据：

免费第三方数据源直连：通过 BaoStock（免 token、不限流）和 Tushare，将历史日线、分钟线直接下载到本地 DuckDB。
baostock_proxy 自动代理：针对部分企业、学校或特殊网络环境下 TCP 端口受阻的问题，新版本增加了一层 socket 拦截代理。直连失败时会自动通过本机的 HTTP/HTTPS 代理建立连接，确保行情下载顺畅。
跨平台数据无缝同步：如果你在 Windows 上已积累了丰富的 DuckDB 本地数据库，可直接将 Windows 下的数据目录拷贝到 Mac 的默认数据路径（~/Library/Application Support/khQuant/stock_data）。两端数据格式 100% 兼容，无需任何格式转换。

七、跨平台协作工作流：Windows + Mac + Linux 协同回测

随着 macOS 版图形界面的加入，看海量化实现了真正的跨平台。以代码库（Git）为中心、各系统发挥所长，可以构建一套标准、高效的分布式策略回测研发工作流：

本地研发验证端（MacBook 随身机）：在移动办公、差旅或日常使用中运行 Mac 桌面版。用熟悉的编辑器，通过 BaoStock 等第三方数据或拷贝的小样本 DuckDB 数据，进行策略编写、逻辑验证与单次快速回测，并在 Mac 屏幕上查看 HTML 高清交互式报告。
算力加速端（Linux 云服务器）：通过 Git 把策略同步到 Linux 服务器。Linux CLI 版极度轻量，可利用云端多核 CPU，通过 Shell 脚本或 Crontab 调度，对策略做大批量、多进程的参数网格寻优（Grid Search）。
全量回测中心（Windows 数据中心）：利用 Windows 端独有的 miniQMT/xtdata 高速行情接收能力，持续构建最完整、最高频的本地 DuckDB 数据库（如 Tick、全股票池 1 分钟 K 线），并借助强大硬件做全量股票池、超长时间跨度的极限压力回测。

这种协同方式（Windows 跑全量极速回测与行情增量更新、Mac 做本地轻量研究与策略开发、Linux 做参数寻优）能最大化利用设备性能，让量化研发流程更高效、科学。

八、常见问题

Q：首次启动提示”无法验证开发者”打不开？
A：这是 macOS Gatekeeper 的正常拦截。前往 系统设置 → 隐私与安全性，找到对应提示点击”仍要打开”即可。

Q：kh doctor 显示 xtdata / miniQMT 不可用？
A：在 macOS 上这是正常现象，不是 bug。miniQMT 仅 Windows 可用。确保 .kh 配置与数据下载都使用 BaoStock / Tushare 即可。

Q：Windows 上下载的数据能直接拿到 Mac 用吗？
A：可以。两端 DuckDB 数据格式 100% 兼容，把数据目录拷到 ~/Library/Application Support/khQuant/stock_data 即可，无需转换。

Q：终端里输入 kh 提示 command not found？
A：在 macOS GUI 工具栏点击「安装命令行工具」，系统会在 /usr/local/bin/kh 建立软链接；之后重开终端即可使用。

附录：资源链接

看海量化官方网站：https://khsci.com/khQuant/
CLI 命令行工具指南：https://khsci.com/khQuant/cli/
由迁移数据库，并获得完全一致的回测结果。