CLI命令行界面功能需使用V3.3.0及以上版本，内测用户需先升级至最新版本。
在使用该功能前，推荐大家都先按照下边的视频操作，将极大提升上手效率。

第二部分 · 命令详解
– 命令总览
– kh init — 初始化配置
– kh config — 全局配置管理
– kh run — 执行回测
– kh data — 数据库管理
– kh result — 回测结果管理
– kh strategy — 策略管理
– kh tool — 小工具
– kh doctor — 环境诊断
– kh version — 版本信息
– kh gui — 启动图形界面

第三部分 · 附录
– 配置项一览
– 预设股票池
– 数据源对比
– .kh 配置文件格式
– 股票代码格式
– 常见问题

第一部分 · 快速入门

什么是 KhQuant CLI

KhQuant CLI 是看海量化回测平台的命令行工具，让你无需打开 GUI 即可完成以下所有操作：

初始化配置 — 一次交互式向导搞定数据源、路径、Token 等基本设置
下载数据 — 从 xtdata / BaoStock / Tushare 批量下载 K 线和 Tick 数据到本地 DuckDB
运行回测 — 指定 .kh 配置文件一键回测，支持参数覆盖
查看结果 — 列出历史回测、查看摘要、对比多次回测、生成交互式 HTML 报告
管理策略 — 列出、创建、校验、分析策略文件
实用工具 — 交易日查询、预设股票池查看
环境诊断 — 一键检查 Python 版本、依赖、数据源、配置状态

入口文件为项目根目录下的 kh.py，配套有 kh.bat（Windows 快捷方式）。

运行方式

安装包用户

如果你已安装了看海量化回测平台安装包，安装程序会自动配置系统 PATH，可以在任意路径直接使用：

kh <command> [options]

源码用户

如果你使用的是源码运行，先切到源码根目录（与 kh.py、kh.bat 同级）：

cd i:\qmt5\code

推荐先执行一次配置脚本（最简、最稳）：

powershell -NoProfile -ExecutionPolicy Bypass -File .\setup_kh_profile.ps1

执行后即可直接使用 kh 命令。
如果仍提示找不到 kh，可使用：

临时方式（当前目录立即可用）：.\kh <command> [options]
兜底方式（不依赖 bat）：python kh.py <command> [options]

注意（PowerShell）：若只想临时运行，可直接用 .\kh，例如 .\kh init。
注意（通用）：本文档统一使用 kh 格式；源码用户可用 python kh.py 等价替代。

5 分钟上手流程

以下是一个从零开始的完整流程，帮你快速体验 CLI 的核心功能。

第 1 步：环境检查

先确认运行环境是否正常：

kh doctor

运行结果：

  看海量化回测平台 v3.2.12 环境诊断
  ══════════════════════════════════════════
  OK Python 3.11.9
  OK PyQt5
  OK numpy 2.2.6
  OK pandas 2.3.1
  OK duckdb 1.4.3
  OK matplotlib 3.10.0
  OK Pillow 11.3.0
  OK holidays 0.69
  OK requests 2.32.4
  OK psutil 6.1.1
  OK xtquant (可选)
  OK baostock (可选)
  OK schedule (可选)
  ──────────────────────────────────────────
  OK DuckDB 数据目录: D:\khData (5800 只)
  OK Tushare Token 已配置
  OK BaoStock 已启用
  OK 策略目录: D:\CLIstrategies (12 个策略)
  OK 回测历史: 1979 次
  ══════════════════════════════════════════
  总计: 17 通过, 0 警告

全部 OK 即可继续。如果有 ERR 或 WARN，按提示安装缺失依赖。

第 2 步：首次初始化

运行交互式初始化向导，配置数据源和基本参数：

kh init

运行结果（交互式，按提示输入）：

  ╔══════════════════════════════════════════╗
  ║   看海量化回测平台 CLI 初始化向导          ║
  ╚══════════════════════════════════════════╝

  ── 步骤 1/5: 回测数据源 ────────────────────

  请选择回测数据源:
    [1] DuckDB 本地数据库 (推荐，离线快速)
    [2] miniQMT (需 QMT 客户端运行)
  > 1

  ── 步骤 2/5: 数据路径 ──────────────────────

  请输入 DuckDB 数据根目录 (包含 SH/SZ/BJ 子目录):
  > D:\khData
  OK 目录有效，发现 5800 只股票数据

  ── 步骤 3/5: 策略目录 ──────────────────────

  请设置策略文件存放目录:
  WARN 建议使用独立目录，不要放在程序安装目录或源码目录下
  > 示例: D:\CLIstrategies

  > D:\CLIstrategies
  OK 已复制 20 个内置示例到策略目录
  > 策略 12 个, 配置 8 个 → D:\CLIstrategies

  ── 步骤 4/5: 数据源配置 (可选) ─────────────

  是否配置 Tushare? (用于从 Tushare 下载数据) [y/N] n
  是否启用 BaoStock? (免费数据源，无需 Token) [Y/n] y
  OK BaoStock 可用

  ── 步骤 5/5: 其他参数 ──────────────────────

  无风险利率 (默认 0.03): 0.03

  ==============================================
  OK 配置已保存到 C:\Users\KH\.khquant\settings.json

  配置摘要:
  > 回测数据源:  DuckDB
  > 数据目录:    D:\khData
  > 策略目录:    D:\CLIstrategies
  > Tushare:     未配置
  > BaoStock:    已启用

  现在可以使用 kh 命令了。试试:
    kh data stats        查看数据库概况
    kh strategy list     查看可用策略
    kh run <config.kh>   运行回测
  ==============================================

第 3 步：下载数据

以免费的 BaoStock 为例，下载平安银行（000001.SZ）的日线数据（默认从 2020-01-01 至今）：

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

运行结果：

  > 数据源: baostock | 股票: 1 只 | 周期: 1d
  > 复权: front | 覆写: 否

  [██████████████████████████████] 100.0%  1/1  000001.SZ
  OK 下载完成: 成功 1/1

下载完成后查看该股票的数据详情：

kh data info 000001.SZ

运行结果：

  > 股票: 000001.SZ
  > 文件: D:\khData\SZ\000001.db (2.5 MB)
  ─────────────────────────────────────────────────────────
  周期  记录数  开始日期             结束日期
  ─────────────────────────────────────────────────────────
  1d    1520  2020-01-02 00:00:00  2026-04-14 00:00:00
  1m    0     -                    -
  5m    0     -                    -
  tick  0     -                    -
  ─────────────────────────────────────────────────────────

第 4 步：运行回测

kh init 已将内置示例策略复制到策略目录中，可以直接运行。以双均线策略为例：

kh run D:\CLIstrategies\【1-MA策略案例】双均线精简_使用khMA函数.kh --report

运行结果（示意）：

  > 策略: 【1-MA策略案例】双均线精简_使用khMA函数.py
  > 区间: 20250101 ~ 20250703
  > 资金: 1,000,000 | 股票: 1 只

  ══════════════════════════════════════════════════
  回测结果
  ──────────────────────────────────────────────────
  交易天数:    118 天
  初始资金:    1,000,000.00
  最终资金:    1,015,230.00
  总收益率:    +1.52%
  年化收益率:  +3.12%
  最大回撤:    3.15%
  ══════════════════════════════════════════════════
  ✔ HTML 报告已生成并在浏览器中打开

由于 --report 参数，回测完成后会自动生成交互式 HTML 报告并打开浏览器。
为避免输出直接构成投资建议，当前代码中加入了随机因子处理，因此同一策略与参数在不同次运行中，结果可能出现小幅差异。
在实际策略研究、参数对比或复现实验时，建议去掉或固定随机性相关代码；实际收益数据以当次运行结果为准。

第 5 步：查看结果

如果你想回看可视化的回测结果（净值曲线、回撤、月度热力图、交易明细等），可以执行这一步。

kh result show

显示最近一次回测的绩效摘要。生成交互式 HTML 报告并自动打开浏览器：

kh result report

浏览器将自动打开报告页面，包含净值曲线、回撤图、月度热力图、交易明细等图表。

第二部分 · 命令详解

命令总览

kh <command> [options]

命令:
  init                首次使用引导配置
  config              查看/修改全局配置
  run                 执行回测
  data                数据库管理（9 个子命令）
  result              回测结果管理（5 个子命令）
  strategy            策略管理（4 个子命令）
  tool                小工具（2 个子命令）
  doctor              环境诊断
  version             版本信息
  gui                 启动 GUI 界面

初始化要求： 除 init、version、doctor、gui 外，其余命令均需先完成 kh init 初始化，否则会报错：

ERR 尚未初始化，请先运行: kh init

查看帮助： 每个命令都支持 --help：

kh --help
kh data --help
kh result --help
kh strategy --help

kh init — 初始化配置

交互式 5 步引导，配置平台运行所需的基本参数。

kh init

引导步骤

步骤	内容	说明
1/5	回测数据源	`[1]` DuckDB 本地数据库（推荐） / `[2]` miniQMT
2/5	数据路径	DuckDB → 数据根目录（含 SH/SZ/BJ 子目录）；miniQMT → userdata_mini 路径
3/5	策略目录	设置策略文件存放目录（建议独立目录，不要放在程序安装目录或源码目录下）
4/5	数据源配置	可选配置 Tushare Token（自动 base64 加密存储）和 BaoStock
5/5	其他参数	无风险利率（默认 0.03）

行为细节

选择 DuckDB 时，向导会自动扫描目录下的 .db 文件数量并报告
策略目录设置完成后，会自动将 strategies/ 下的内置示例（.py + .kh）复制到目标目录（已有同名文件不覆盖），并提示复制数量
如果策略目录指向了程序安装目录或源码目录，会发出警告并二次确认
输入 Tushare Token 后会尝试在线验证连接
选择 BaoStock 时会检测 baostock 库是否已安装
所有步骤均可直接按回车使用默认值
按 Ctrl+C 随时取消
配置保存到 ~/.khquant/settings.json（即 C:\Users\<用户名>\.khquant\settings.json）

重新初始化

直接再次运行 kh init 即可覆盖之前的配置。

kh config — 全局配置管理

管理 ~/.khquant/settings.json 中的全局配置项。有 3 个子命令：show、set、reset。

kh config show — 查看当前配置

kh config show

输出示例：

  > 回测数据源          : duckdb
  > DuckDB 路径         : D:\khData
  > 策略目录            : D:\CLIstrategies
  > miniQMT 数据路径    : 未配置
  > miniQMT 客户端路径  : 未配置
  > Tushare Token       : 已配置 (token: abc1****xyz9)
  > Tushare API URL     : https://api.tushare.pro
  > Tushare 代理        : false
  > Tushare 代理地址    : 未配置
  > BaoStock            : true
  > 无风险利率          : 0.03
  > 成交量限制          : false
  > 参与率              : 0.1
  > 允许部分成交        : true
  > 自动生成报告        : false

  > 配置文件: C:\Users\KH\.khquant\settings.json

现在会完整显示所有配置项（按默认配置顺序），不会只显示部分字段
Tushare Token 以脱敏形式显示（首尾各 4 位，中间用 **** 替代）
未配置的项会显示为 未配置

kh config set — 修改配置项

kh config set <key> <value>

示例：

# 切换数据源为 DuckDB
kh config set backtest_data_source duckdb

# 设置 DuckDB 数据路径
kh config set duckdb_data_path D:\khData

# 设置策略目录
kh config set strategy_dir D:\CLIstrategies

# 设置 Tushare Token（自动 base64 编码存储，原文输入即可）
kh config set tushare_token your_token_here

# 启用 BaoStock
kh config set baostock_enabled true

# 设置无风险利率为 2.5%
kh config set risk_free_rate 0.025

# 启用成交量限制
kh config set volume_limit_enabled true

# 设置参与率为 20%
kh config set participation_rate 0.2

# 启用回测后自动生成 HTML 报告
kh config set auto_report true

值域校验： 以下配置项有范围限制，超出范围会被拒绝：

配置项	类型	有效范围
`risk_free_rate`	float	0.0 ~ 1.0
`participation_rate`	float	0.0 ~ 1.0
`backtest_data_source`	string	`duckdb` 或 `miniqmt`

布尔类型配置项 接受 true/false/1/0/yes/no（大小写不敏感）。

错误处理： 输入未知配置项名称时，会列出所有可用配置项。

kh config reset — 重置为默认配置

kh config reset

需要交互确认，输入 y 后所有配置项恢复为默认值。

kh run — 执行回测

kh run <config.kh> [options]

参数

参数	简写	说明	默认
`config`	—	`.kh` 配置文件路径（必需）	—
`--strategy`	`-s`	策略 .py 路径（覆盖配置文件中的值）	配置文件中的值
`--start`	—	开始日期 YYYYMMDD	配置文件中的值
`--end`	—	结束日期 YYYYMMDD	配置文件中的值
`--capital`	`-c`	初始资金	配置文件中的值
`--stocks`	—	股票池，逗号分隔	配置文件中的值
`--period`	`-p`	K 线周期: tick/1m/5m/1d	配置文件中的值
`--quiet`	`-q`	静默模式，不输出过程信息	否
`--verbose`	`-v`	详细输出（DEBUG 级别日志）	否
`--report`	—	回测完成后自动生成 HTML 报告	否
`--no-open`	—	生成报告后不自动打开浏览器	否
`--json`	—	以 JSON 格式输出回测摘要	否

使用示例

# 基本用法
kh run configs/my_strategy.kh

# 覆盖日期区间和资金
kh run configs/my_strategy.kh --start 20240101 --end 20241231 --capital 500000

# 替换策略文件
kh run configs/my_strategy.kh -s D:\CLIstrategies\MACD.py

# 覆盖股票池和周期
kh run configs/my_strategy.kh --stocks 000001.SZ,600000.SH -p 5m

# 静默运行 + 自动报告
kh run configs/my_strategy.kh -q --report --no-open

# JSON 输出（适合脚本自动化）
kh run configs/my_strategy.kh --json

参数覆盖机制

当通过 CLI 参数覆盖配置时，系统会：
1. 加载 .kh 配置文件
2. 用 CLI 参数覆盖对应字段
3. 写入临时配置文件 _tmp_<原文件名> 供框架读取
4. 回测完成后（无论成功或失败）自动删除临时文件
5. 启动前还会清理同目录下残留的旧临时文件

回测结果输出

回测成功后自动打印结果摘要：

  ══════════════════════════════════════════════════
  回测结果
  ──────────────────────────────────────────────────
  交易天数:    120 天
  初始资金:    1,000,000.00
  最终资金:    1,150,000.00
  总收益率:    +15.00%
  年化收益率:  +18.75%
  最大回撤:    5.20%
  ══════════════════════════════════════════════════

结果波动说明（随机因子）

为避免输出直接构成投资建议，当前代码中加入了随机因子处理。
因此同一策略、同一参数在不同次运行中，结果可能出现小幅差异。

这属于设计行为，不代表程序异常
做策略研究、参数对比或复现实验时，建议去掉/固定随机性相关代码后再测试
对外展示结论时，建议注明是否已移除随机因子

JSON 输出格式

使用 --json 时，stdout 输出 JSON 对象：

{
  "trade_days": "120",
  "init_capital": "1000000.0",
  "final_capital": "1150000.0",
  "total_return": "15.0",
  "annual_return": "18.75",
  "max_drawdown": "5.2"
}

回测失败时输出：

{"error": "回测执行失败"}

自动报告

生成 HTML 报告有两种触发方式：
– 命令行参数 --report
– 全局配置 auto_report 设为 true（kh config set auto_report true）

数据源检查

如果全局配置的数据源不是 DuckDB（即 miniQMT），CLI 会在回测前自动检查 xtquant 是否可连接，不可用则报错退出。

异常处理

错误类型	场景	提示
`FileNotFoundError`	策略文件或数据文件缺失	文件未找到: …
`JSONDecodeError`	.kh 配置文件不是合法 JSON	配置文件格式错误: …
`ImportError`	khFrame 框架模块缺失	模块导入失败: …
其他异常	回测运行时错误	回测执行失败: …（附完整 traceback）

技术细节： 回测完成后使用 os._exit() 强制退出进程，因为 xtquant 的后台线程会阻止 sys.exit() 正常退出。

kh data — 数据库管理

数据库管理是 CLI 功能最丰富的模块，包含 9 个子命令，覆盖数据的查询、下载、维护全流程。

kh data <子命令>

子命令:
  list         列出已有股票数据
  stats        数据库统计概览
  info         查看单只股票详情
  download     从指定数据源下载数据
  scan         扫描数据缺口
  export       导出为 CSV
  repair       WAL 修复
  update-pool  更新预设板块成分股列表
  sync         同步当日数据

kh data list — 列出已有数据

kh data list [--market SH|SZ|BJ] [--period 1d|1m|5m|tick]

参数	说明
`--market`	按市场过滤: SH（上海）、SZ（深圳）、BJ（北京）
`--period`	按 K 线周期过滤

示例：

# 列出所有股票
kh data list

# 只看上证股票
kh data list --market SH

# 只看有 5 分钟数据的股票
kh data list --period 5m

kh data stats — 数据库统计概览

kh data stats

显示各市场股票数、磁盘占用、最后更新时间。输出示例：

  > DuckDB 数据目录: I:/khData
  ══════════════════════════════════════════════════
  ──────────────────────────────────
  市场  股票数  磁盘占用
  ──────────────────────────────────
  SH    2100    12.3 GB
  SZ    3500    18.7 GB
  BJ    200     1.1 GB
  ──────────────────────────────────
  合计: 5800 只 | 磁盘: 32.1 GB
  > 最后更新: 2026-04-14 15:30

kh data info — 查看单只股票详情

kh data info <code>

查看指定股票在数据库中各周期的记录数和日期范围。

示例：

kh data info 000001.SZ

输出示例：

  > 股票: 000001.SZ
  > 文件: I:/khData/SZ/000001.db (45.2 MB)
  ──────────────────────────────────
  周期  记录数    开始日期      结束日期
  ──────────────────────────────────
  1d    1200     2020-01-02   2026-04-14
  1m    288000   2023-01-03   2026-04-14
  5m    57600    2023-01-03   2026-04-14
  tick  0        -            -
  ──────────────────────────────────

kh data download — 下载数据

从指定数据源下载行情数据到本地 DuckDB，支持多股票并行下载。

kh data download --source <source> [options]

参数	说明	默认
`--source`	必需。数据源: `xtdata`、`baostock`、`tushare`	—
`--stocks`	股票代码，逗号分隔	—
`--pool`	预设股票池名称，逗号分隔（见预设股票池）	—
`--file`	股票列表文件路径（CSV，支持多种格式）	—
`--period`	K 线周期，逗号分隔: `1d,1m,5m,tick`	`1d`
`--start`	开始日期 YYYYMMDD	`20200101`
`--end`	结束日期 YYYYMMDD	今天
`--adj`	复权类型，逗号分隔: `none,front,back,front_ratio,back_ratio`	`front`
`--force`	强制覆写已有数据	否
`--workers`	并行进程数	`2`

--stocks、--pool、--file 至少需提供一个，可组合使用（自动去重）。

示例：

# 下载沪深 300 日线数据
kh data download --source baostock --pool hs300 --period 1d

# 下载指定股票的多周期数据
kh data download --source tushare --stocks 000001.SZ,600000.SH --period 1d,5m

# 从 CSV 文件读取股票列表，用 xtdata 下载 tick 数据
kh data download --source xtdata --file stocks.csv --period tick --workers 4

# 下载前复权 + 后复权数据
kh data download --source tushare --pool sz50 --adj front,back

# 指定日期范围
kh data download --source baostock --pool hs300 --period 1d --start 20240101 --end 20241231

各数据源支持的周期和复权：

数据源	支持周期	支持复权	前置要求
`xtdata`	1d, 1m, 5m, tick	none, front, back, front_ratio, back_ratio	QMT 客户端运行
`baostock`	1d, 5m	none, front, back	`pip install baostock`
`tushare`	1d, 1m, 5m	none, front, back	Tushare Token

兼容性校验： CLI 会在下载前自动检查周期和复权类型是否被所选数据源支持，不兼容时报错并退出。

网络重试： Tushare 下载失败时自动重试 3 次（指数退避: 2s → 4s → 8s）。

CSV 文件格式： 支持多种格式的 CSV 文件：
– 自动识别表头：代码、code、stock_code、ts_code、证券代码 等列名
– 如果表头不含上述列名，默认使用第一列
– 纯数字代码会自动补充市场后缀（6/5 开头 → SH，0/3 开头 → SZ，4/8 开头 → BJ）

进度显示： 下载过程中显示实时进度条：

  [████████████░░░░░░░░░░░░░░░░░░]  40.0%  120/300  600000.SH

kh data scan — 扫描数据缺口

扫描数据库中的缺失交易日，可选自动补充。

kh data scan [options]

参数	说明	默认
`--period`	扫描的 K 线周期	`1d`
`--stocks`	只扫描指定股票（逗号分隔）	全部
`--start`	扫描起始日期	`20200101`
`--end`	扫描结束日期	今天
`--fix`	自动补充缺失数据	否
`--source`	补充数据时使用的数据源	自动选择

示例：

# 只扫描 000001 和 000002 的日线完整性
kh data scan --period 1d --stocks 000001,000002

# 扫描并自动补充 000001 和 000002 的缺口
kh data scan --period 1d --stocks 000001,000002 --fix --source baostock

自动数据源选择： 未指定 --source 时，按优先级自动选择：Tushare（已配置 Token）→ BaoStock（已启用）→ xtdata。

安全检查： 使用 --fix 时，会先验证指定数据源是否可用。如果 xtquant 未安装、Tushare Token 未配置或 baostock 未安装，会给出具体错误提示。

kh data export — 导出为 CSV

kh data export <code> [options]

参数	说明	默认
`code`	股票代码（必需）	—
`--period`	K 线周期	`1d`
`--start`	开始日期	全部
`--end`	结束日期	全部
`--output`	输出文件路径	`<code>_<period>.csv`

示例：

# 导出日线数据
kh data export 000001.SZ --period 1d --start 20240101 --output 平安银行.csv

CSV 使用 utf-8-sig 编码（Excel 兼容）。

kh data repair — WAL 修复

修复 DuckDB Write-Ahead Log（WAL）损坏问题。

kh data repair [--db-path PATH] [--memory-limit SIZE]

参数	说明	默认
`--db-path`	数据目录	全局配置中的 `duckdb_data_path`
`--memory-limit`	修复时内存限制	`256MB`

当 DuckDB 文件出现 IO Error 或数据库打开失败时，可尝试此命令修复。

kh data update-pool — 更新成分股列表

更新预设板块（沪深 300、上证 50 等）的成分股列表文件。

kh data update-pool

需要 xtquant (miniQMT)。 此命令会调用 xtquant 获取最新成分股数据并保存到 data/ 目录。

kh data sync — 同步当日数据

同步数据库中已有股票的当日数据，支持定时执行。

kh data sync [--period PERIOD] [--schedule TIME]

参数	说明	默认
`--period`	同步的周期，逗号分隔	`1d`
`--schedule`	定时执行时间（如 `15:30`）	立即执行

示例：

# 立即同步日线
kh data sync

# 同步多周期
kh data sync --period 1d,5m

# 每个交易日 15:30 自动同步
kh data sync --schedule 15:30

立即同步模式：
1. 检查今天是否为交易日（非交易日自动跳过）
2. 获取数据库中所有已有股票
3. 使用自动选择的数据源下载当日数据

定时模式：
– 每周一至周五的指定时间自动执行
– 按 Ctrl+C 退出
– 需要 schedule 库：pip install schedule

kh result — 回测结果管理

管理 backtest_results/ 目录下的回测结果，包含 5 个子命令。

kh result <子命令>

子命令:
  list     列出所有回测
  show     查看回测摘要
  report   生成 HTML 报告
  compare  对比多次回测
  clean    清理旧回测

kh result list — 列出所有回测

kh result list [--all] [--strategy NAME] [--json]

参数	说明	默认
`--all`	显示全部结果（默认只显示最近 20 条）	否
`--strategy`	按策略名过滤（模糊匹配，大小写不敏感）	—
`--json`	以 JSON 格式输出	否

示例：

# 查看最近 20 次回测
kh result list

# 按策略名过滤
kh result list --strategy RSI

# 显示全部
kh result list --all

# JSON 输出
kh result list --json

列表按时间倒序排列，每行展示序号、策略名、回测区间、总收益率、最大回撤、运行时间。

kh result show — 查看回测摘要

kh result show [dir] [--id NUM] [--json]

参数	说明
`dir`	回测结果目录名或完整路径（可选）
`--id`	按 `result list` 中的序号指定
`--json`	以 JSON 格式输出

不指定参数时默认显示最近一次回测。

示例：

# 最近一次回测
kh result show

# 按序号查看
kh result show --id 3

# JSON 输出
kh result show --id 1 --json

输出示例：

  > 回测: strategy_00582727_20250101_20251120
  > 策略: RSI策略.py
  > 区间: 20250101 ~ 20251120

  ══════════════════════════════════════════════════
  绩效指标
  ──────────────────────────────────────────────────
  初始资金:      1,000,000.00
  最终资金:      1,150,000.00
  总收益率:      +15.00%
  年化收益率:    +18.75%
  最大回撤:      5.20%
  交易天数:      120 天
  ══════════════════════════════════════════════════
  kh result report --id 3  生成 HTML 详细报告

配色约定：采用 A 股常用配色——总收益率 与 年化收益率 正值显示为红色，负值显示为绿色。

kh result report — 生成 HTML 报告

kh result report [dir] [--id NUM] [--index] [--no-open] [--output PATH]

参数	说明
`dir`	回测结果目录（可选）
`--id`	按序号指定
`--index`	生成所有回测的索引页
`--no-open`	不自动打开浏览器
`--output`	自定义输出路径

示例：

# 生成最新回测的报告并打开浏览器
kh result report

# 按序号指定
kh result report --id 1

# 生成索引页（所有回测的汇总页面）
kh result report --index

# 指定输出路径，不自动打开
kh result report --id 1 --output report.html --no-open

HTML 报告包含：
– 绩效概览卡片 — 初始/最终资金、总收益率、年化收益率、最大回撤、夏普比率、波动率、胜率、盈亏比、交易天数
– 主图 — 四行联动图表：策略净值曲线（叠加基准）、回撤区域图、日盈亏柱状图、买卖成交量
– 收益分布直方图 — 日收益率频率分布
– 月度收益热力图 — 按年月展示月度收益率的颜色矩阵
– 交易记录表 — 完整的买卖交易明细，支持点击表头排序
– 日收益表 — 每日总资产、持仓市值、可用资金、日收益率
– 个股分析 — 每只股票的独立 K 线图（叠加买卖点标注）、买卖统计、净盈亏
– 日内 K 线弹窗 — 点击日 K 线可弹出该日的 5 分钟/1 分钟 K 线图（需有日内数据）

索引页 — 使用 --index 生成的页面汇总所有回测结果，包含策略名、区间、收益率、回撤等指标，已生成报告的可直接跳转查看。

报告使用 ECharts 5.x 渲染图表（CDN 加载），需要网络连接才能正常显示图表。

kh result compare — 对比多次回测

kh result compare [--last N]

参数	说明	默认
`--last`	对比最近 N 次回测	`3`

至少需要 2 次回测结果才能对比。输出对比表格：

  ──────────────────────────────────────────
  指标        回测1       回测2       回测3
  ──────────────────────────────────────────
  策略        RSI策略     MACD       双均线
  总收益率    +15.00%    +8.50%     +12.30%
  年化收益率  +18.75%    +10.62%    +15.37%
  最大回撤    5.20%      8.10%      6.50%
  交易天数    120        120        120
  ──────────────────────────────────────────

kh result clean — 清理旧回测

kh result clean [--keep N] [--dry-run]

参数	说明	默认
`--keep`	保留最近 N 次	`10`
`--dry-run`	预览模式，仅显示将删除的目录	否

示例：

# 预览将删除哪些回测
kh result clean --keep 5 --dry-run

# 执行清理，保留最近 5 次
kh result clean --keep 5

kh strategy — 策略管理

管理策略文件，包含 4 个子命令。

kh strategy <子命令>

子命令:
  list       列出可用策略
  create     创建策略模板
  validate   校验策略文件
  info       查看策略信息

kh strategy list — 列出可用策略

kh strategy list [--dir DIR]

参数	说明
`--dir`	指定策略目录（默认使用 `kh init` 配置的策略目录）

输出示例：

  > D:\CLIstrategies/ (3 个策略)
  ────────────────────────────────────────────────────────────────────────────
  #   策略文件                                         配套.kh
  ────────────────────────────────────────────────────────────────────────────
  1   【1-MA策略案例】双均线精简_使用khMA函数.py       【1-MA策略案例】双均线精简_使用khMA函数.kh
  2   【2-RSI策略案例】RSI策略.py                      【2-RSI策略案例】RSI策略.kh
  3   MACD.py                                          -
  ────────────────────────────────────────────────────────────────────────────

未配置策略目录时，会回退到程序内置的 strategies/ 目录，并提示运行 kh init 设置独立策略目录。

自动跳过以 _ 或 . 开头的文件
配套.kh 列显示同名的 .kh 配置文件名；若无配套文件则显示 -

kh strategy create — 创建策略模板

kh strategy create <name> [--dir DIR]

参数	说明
`name`	策略名称（用作文件名）
`--dir`	输出目录（默认使用 `kh init` 配置的策略目录）

生成两个文件：
– <name>.py — 策略代码模板
– <name>.kh — 配套配置文件

策略模板结构：

# coding: utf-8
"""策略: <name>"""
from khQuantImport import *

def init():
    """初始化策略状态 - 设置全局变量、参数等"""
    pass

def khPreMarket(data):
    """盘前准备 - 返回信号列表"""
    return []

def khHandlebar(data):
    """每根K线触发（主策略逻辑）
    Args:
        data: 包含行情数据的字典，特殊 key:
            - "__current_time__": {date, time, datetime, timestamp}
            - 股票代码作为 key，值为 OHLCV 数据
    Returns:
        信号列表: [{code, action, price, volume, reason}, ...]
    """
    return []

def khPostMarket(data):
    """盘后清理 - 返回信号列表"""
    return []

配套配置文件（.kh）默认内容：

{
  "strategy_file": "<name>.py",
  "backtest": {
    "start_time": "20240101",
    "end_time": "20241231",
    "init_capital": 1000000,
    "period": "1d"
  },
  "data": {
    "kline_period": "1d",
    "stock_list": ["000001.SZ"]
  }
}

安全检查： 如果目标文件已存在，会拒绝覆盖并报错。

kh strategy validate — 校验策略文件

校验策略文件是否符合框架要求。注意：此命令会实际加载并执行模块（非纯静态分析）。

kh strategy validate <path>

检查项目：

函数	级别	说明
`khHandlebar`	必需	主策略逻辑，缺失则无法运行
`init`	推荐	初始化函数，缺失会 WARN
`khPreMarket`	可选	盘前回调
`khPostMarket`	可选	盘后回调

示例：

kh strategy validate D:\CLIstrategies\RSI策略.py

输出：

  OK khHandlebar  (必需)
  OK init         (推荐)
  OK khPreMarket  (可选)
  OK khPostMarket (可选)

kh strategy info — 查看策略信息

纯静态分析（AST 解析），不执行代码。展示：
– 定义的所有函数（标注标准回调函数）
– import 依赖列表
– 是否有配套 .kh 配置文件

kh strategy info <path>

示例：

kh strategy info D:\CLIstrategies\RSI策略.py

输出：

  > 策略文件: RSI策略.py

  > 函数列表:
    init [回调]
    khHandlebar [回调]

  > 导入模块:
    khQuantImport

  OK 配套配置: RSI策略.kh

validate vs info 的区别： validate 会实际加载代码（可能触发 import 错误），info 只做 AST 静态解析，更安全。

kh tool — 小工具

kh tool <子命令>

子命令:
  trade-day   查询交易日
  pool        查看预设股票池

kh tool trade-day — 查询交易日

kh tool trade-day [DATE] [--range-start START --range-end END]

参数	说明
`date`	日期 YYYYMMDD（默认今天）
`--range-start`	区间起始日期
`--range-end`	区间结束日期

示例：

# 查询今天
kh tool trade-day

# 查询指定日期
kh tool trade-day 20260501

# 列出区间内所有交易日
kh tool trade-day --range-start 20260401 --range-end 20260430

输出示例（单日查询）：

  OK 20260414 (周二) 是交易日

输出示例（区间查询）：

  > 交易日: 20260401 ~ 20260430 (共 22 天)
    2026-04-01 (周三)
    2026-04-02 (周四)
    ...

交易日判断规则：非周末且非中国法定节假日（使用 holidays.China() 库）。

kh tool pool — 查看预设股票池

kh tool pool [NAME] [--all]

参数	说明
`name`	股票池名称
`--all`	列出所有可用股票池

示例：

# 列出所有可用股票池
kh tool pool --all

# 查看沪深 300 成分股
kh tool pool hs300

不带参数时默认列出所有池。查看具体池时，每行显示 6 只股票代码。

kh doctor — 环境诊断

全面检查运行环境，无需初始化即可运行。

kh doctor

检查内容：

类别	检查项
Python	版本号
核心依赖 (9 项)	PyQt5, numpy, pandas, duckdb, matplotlib, Pillow, holidays, requests, psutil
可选依赖 (3 项)	xtquant（miniQMT）, baostock, schedule（定时同步）
数据源	DuckDB 目录有效性及 `.db` 文件数
配置	Tushare Token（存在性 + base64 格式校验）、BaoStock 启用状态
路径	QMT 路径是否存在
策略目录	策略目录是否配置、是否存在、策略文件数量
回测历史	`backtest_results/` 下的回测结果目录数量

输出状态标记：
– OK — 检查通过（绿色）
– WARN — 警告，不影响核心功能（黄色）
– ERR — 错误，缺少必要依赖（红色）

注意： PyQt5 缺失时只会 WARN（CLI 不需要，但 GUI 需要）。

kh version — 版本信息

kh version

输出示例：

  看海量化回测平台 v3.2.12 (2026-04-14)

无需初始化即可运行。

kh gui — 启动图形界面

kh gui

源码模式下等价于运行 python GUIkhQuant.py；打包模式下会启动 看海量化回测平台.exe。

无需初始化即可运行。

第三部分 · 附录

配置项一览

配置文件路径：~/.khquant/settings.json

配置项	类型	默认值	说明
`backtest_data_source`	string	`"duckdb"`	回测数据源: `duckdb` 或 `miniqmt`
`duckdb_data_path`	string	`""`	DuckDB 数据根目录
`strategy_dir`	string	`""`	策略文件存放目录（建议独立目录）
`qmt_path`	string	`""`	miniQMT userdata_mini 路径
`client_path`	string	`""`	miniQMT 客户端路径
`tushare_token`	string	`""`	Tushare Token（base64 编码存储）
`tushare_api_url`	string	`"https://api.tushare.pro"`	Tushare API 地址
`tushare_use_proxy`	bool	`false`	是否使用 Tushare 代理
`tushare_proxy_url`	string	`""`	Tushare 代理地址
`baostock_enabled`	bool	`false`	是否启用 BaoStock
`risk_free_rate`	float	`0.03`	无风险利率（0.0~1.0）
`volume_limit_enabled`	bool	`false`	是否启用成交量限制
`participation_rate`	float	`0.1`	成交量参与率（0.0~1.0）
`allow_partial_fill`	bool	`true`	是否允许部分成交
`auto_report`	bool	`false`	回测后自动生成 HTML 报告

预设股票池

可用于 --pool 参数和 kh tool pool 命令。

名称	描述	CSV 文件
`a`	沪深A股	沪深A股_股票列表.csv
`sha`	上证A股	上证A股_股票列表.csv
`sza`	深证A股	深证A股_股票列表.csv
`hs300`	沪深300	沪深300成分股_股票列表.csv
`sz50`	上证50	上证50成分股_股票列表.csv
`zz500`	中证500	中证500成分股_股票列表.csv
`gem`	创业板	创业板_股票列表.csv
`star`	科创板	科创板_股票列表.csv
`etf`	沪深ETF	沪深ETF_股票列表.csv
`t0etf`	T0型ETF	T0型ETF_股票列表.csv
`t0stock`	T0股票型ETF	T0股票型ETF_股票列表.csv
`bond`	沪深转债	沪深转债_股票列表.csv
`index`	常用指数	常用指数_股票列表.csv

股票池文件位于 data/ 目录。如果文件不存在，运行 kh data update-pool 更新（需要 xtquant）。

数据源对比

特性	xtdata (miniQMT)	Tushare	BaoStock
费用	券商开户免费	积分制（基础免费）	完全免费
日线	✅	✅	✅
1 分钟线	✅	✅	❌
5 分钟线	✅	✅	✅
Tick 数据	✅	❌	❌
复权类型	前/后/前比例/后比例	前/后	前/后
实时数据	✅	❌	❌
安装要求	QMT 客户端运行	pip install tushare	pip install baostock
网络重试	worker 内部处理	自动 3 次指数退避	worker 内部处理

.kh 配置文件格式

.kh 文件是 JSON 格式的回测配置文件。

{
  "strategy_file": "RSI策略.py",
  "backtest": {
    "start_time": "20240101",
    "end_time": "20241231",
    "init_capital": 1000000,
    "period": "1d",
    "trade_cost": {
      "commission_rate": 0.0003,
      "stamp_tax_rate": 0.001,
      "min_commission": 5.0,
      "slippage": {
        "type": "ratio",
        "ratio": 0.001
      }
    }
  },
  "data": {
    "kline_period": "1d",
    "stock_list": ["000001.SZ", "600000.SH"],
    "dividend_type": "front"
  },
  "risk": {
    "max_position_ratio": 1.0,
    "single_stock_ratio": 0.3
  }
}

核心字段：

字段	说明
`strategy_file`	策略 .py 文件路径（相对于项目根目录）
`backtest.start_time`	回测开始日期 YYYYMMDD
`backtest.end_time`	回测结束日期 YYYYMMDD
`backtest.init_capital`	初始资金（元）
`data.kline_period`	K 线周期: `tick`, `1m`, `5m`, `1d`
`data.stock_list`	股票池（代码数组）
`backtest.trade_cost.commission_rate`	佣金率（默认万三）
`backtest.trade_cost.stamp_tax_rate`	印花税率（默认千一）
`backtest.trade_cost.slippage.type`	滑点类型: `tick`（绝对值）或 `ratio`（百分比）

股票代码格式

标准格式为 代码.市场后缀：

市场	后缀	代码前缀	示例
上海	`.SH`	6, 5 开头	`600000.SH`
深圳	`.SZ`	0, 3 开头	`000001.SZ`
北京	`.BJ`	4, 8 开头	`430047.BJ`

输入纯数字时 CLI 会自动补充后缀。

常见问题

Q: 提示 “尚未初始化”

ERR 尚未初始化，请先运行: kh init

运行 kh init 完成首次配置。

Q: PowerShell 提示 “无法将 kh 识别为命令”

常见报错：

kh : 无法将“kh”项识别为 cmdlet、函数、脚本文件或可运行程序的名称

处理方式：

临时运行：在项目根目录执行 .\kh init
推荐方式：执行 .\setup_kh_profile.ps1（若受执行策略限制，用 powershell -ExecutionPolicy Bypass -File .\setup_kh_profile.ps1）
长期方案：把 kh.bat 所在目录加入用户 PATH（见上文“源码模式一键加入用户 PATH（通用写法）”）
兼容写法：直接用 python kh.py <command>

Q: xtquant 无法连接

ERR xtquant 无法连接，请确认 QMT 客户端已启动并登录

确保 QMT 客户端正在运行且已登录
如果只使用 DuckDB 本地数据：kh config set backtest_data_source duckdb

Q: 回测进程不退出

回测完成后进程可能因 xtquant 后台线程而挂起。CLI 已内置 os._exit() 强制退出机制，正常使用无需关注。

Q: 定时同步提示缺少 schedule 库

pip install schedule

Q: 如何在脚本中自动化回测？

使用 --json 参数获取结构化输出：

kh run configs/my.kh --json 2>nul

Q: 提示 “DuckDB 数据库被其他进程占用”

ERR DuckDB 数据库被其他进程占用，无法打开
> 被锁文件: D:\khData\metadata.db
> 占用进程: python.exe (PID 12345)

> 请先关闭占用程序（如 GUI、数据查看器），或手动结束进程:
    taskkill /pid 12345 /f

DuckDB 是单进程独占数据库，同一时刻只能有一个进程打开。关闭正在占用的程序（如 GUI、数据查看器），或按提示中的 taskkill 命令结束进程后重试。

Q: 数据库文件损坏怎么办？

kh data repair

Q: 如何查看所有可用命令和选项？

kh --help              # 显示所有顶级命令: init, config, run, data, result, strategy, tool, doctor, version, gui
kh data --help         # 数据库管理子命令: list, stats, info, download, scan, export, repair, update-pool, sync
kh result --help       # 回测结果子命令: list, show, report, compare, clean
kh strategy --help     # 策略管理子命令: list, create, validate, info
kh tool --help         # 小工具子命令: trade-day, pool