适用版本 V3 WindowsmacOSLinux
本篇说明
这是 kh 命令的查阅手册，按命令分节列出常用参数，少数不常用的参数（如 tool parquet-cache 的 --root、data conflicts 的各项）以 --help 为准。第一次使用请先看 2.2 命令行模式与 AI 智能策略研究。每个命令都可以加 --help 查看本机版本的帮助。
- 没有全局参数：
--json、-q、--data-root等都写在子命令后面。kh --json …会报错；查版本用kh version。 - 除
init、version、doctor、gui、bridge外，其他命令要先运行过kh init（或在图形界面里保存过设置）。 - 输出前缀：
OK成功、ERR出错、WARN提醒、>信息。设置环境变量NO_COLOR或把输出重定向到文件时不带颜色。 - 退出码：参数写错为 2；
run、data、result show/report、bridge出错为 1；web启动失败（端口被占用、配置文件不对）和 Linux 上的gui为 2。注意config、strategy、tool以及data export/repair/update-pool出错时退出码仍是 0，脚本里请检查输出文字。tool trade-day输出的ERR只表示「不是交易日」，不是出错。
1 命令一览
kh
├─ init 首次配置向导
├─ config show / set / reset
├─ run <配置.kh> 执行回测
├─ web [配置.kh] 启动网页回测工作台
├─ data list / stats / info / download / scan / reindex /
│ export / repair / update-pool / sync / source test / conflicts
├─ result list / show / report / compare / clean
├─ strategy list / create / validate / info
├─ tool trade-day / pool / parquet-cache
├─ bridge serve / status（服务端仅 Windows）
├─ doctor 环境诊断
├─ version 版本信息
└─ gui 启动图形界面（Windows、macOS）2 init、config、doctor、version、gui
kh init
交互式配置：回测数据源（Windows）、数据目录、策略目录、Tushare / BaoStock / HTTP 桥接、无风险利率，最后一步才保存。步骤和默认值见 2.2 第 4.2 节。重新运行会从默认值开始，覆盖原配置。Windows 默认放在 D 盘，没有 D 盘时默认放在用户目录下。
kh config
| 命令 | 作用 |
|---|---|
kh config / kh config show | 列出全部配置项（中文名和值），密钥打码显示，最后显示配置文件路径 |
kh config set <键> <值> | 修改一项，先做取值检查 |
kh config reset | 确认后把所有项恢复默认（路径、Token 都会清空） |
布尔值写 true 或 false。注意：true/1/yes/on/y 以外的任何文字都会被存成 false，而且不报错。常用的键见第 9 节。
kh doctor / kh version / kh gui
doctor：检查 Python 依赖、数据目录、数据源配置、策略目录，最后给出「总计: N 通过, M 警告」。Windows 上没开 miniQMT 时会有一条「历史行情导入源 miniqmt 未就绪」，只影响 miniQMT 下载；macOS、Linux 上这条警告总会出现，可以忽略。version：显示版本号、构建日期和平台。gui：启动图形界面。Linux 上提示不支持。
3 kh run
kh run [选项] 配置.kh| 参数 | 说明 |
|---|---|
配置.kh | 必填。先按给的路径找；找不到时到策略目录里找，.kh 可以省略 |
-s, --strategy 路径 | 换用另一个策略 .py |
--start / --end YYYYMMDD | 覆盖回测区间 |
-c, --capital 金额 | 覆盖初始资金（须大于 0） |
--stocks 代码,代码 | 整个替换股票池 |
-p, --period | 覆盖周期：tick/1m/5m/1d |
-q, --quiet | 静默，连结果摘要也不显示 |
-v, --verbose | 输出调试级日志 |
--report | 跑完生成 HTML 报告（设置 auto_report=true 时不加也会生成） |
--no-open | 不自动打开浏览器；单独加不会生成报告，要和 --report 一起用（或 .kh 里开了自动生成报告） |
--json | 静默运行，输出一行 JSON（值为字符串；出错时 JSON 前会先有一行 ERR，加了 --report 时 JSON 后还有一行「OK HTML 报告」）；配置解析失败、配置校验失败、回测执行失败时输出 {"error": …}；找不到 .kh 文件时只输出 ERR 文字，没有 JSON。两种情况退出码都是 1。.kh 请写完整路径 |
--data-root 目录 | 本次用另一个 DuckDB 数据目录，不改全局设置 |
--memory-profile | 本次内存档位：auto / standard / low / ultra_low。不写时先看 .kh 里的设置，再看全局的 performance_preset，见 1.12 |
--no-auto-dynamic-load | 低内存档位下也不自动分段载入 |
--allow-provisional | 研究模式选项，对教程中的数据源没有作用 |
kh run 【1-MA策略案例】双均线精简_使用khMA函数.kh --stocks 000300.SH --start 20251201 --end 20260930 --report
kh run D:\CLIstrategies\my.kh --json 2>$null覆盖项不会修改 .kh 文件本身。回测日志输出到 stderr，结果摘要输出到 stdout。
4 kh web
kh web [配置.kh] [--host 地址] [--port 端口] [--no-open]配置.kh：可选，启动时导入为项目并自动选中。--host：默认127.0.0.1（只限本机）；0.0.0.0允许局域网访问，自动生成访问密钥。--port：默认 8766。端口被占用时报错退出。- 前台运行，Ctrl+C 停止。详见 2.6。
5 kh data
data list / stats / info
| 命令 | 作用 |
|---|---|
kh data list [--market SH|SZ|BJ] [--period 1d|1m|5m|tick] | 列出库里的证券。全新的空库会报 metadata.db 不存在，下载一次数据后正常 |
kh data stats | 各市场的证券数、文件数、磁盘占用 |
kh data info 代码 | 一只证券的文件位置和各周期条数、起止时间。代码必须带后缀 |
data download
kh data download --source 数据源 --stocks … / --pool … / --file …（至少一个，可组合，会合并去重） [选项]| 参数 | 说明 |
|---|---|
--source | 必填：tx（即 tencent）、baostock、tushare、ths（同花顺）、http（HTTP 桥接）；Windows 另有 miniqmt（别名 xtdata） |
--stocks | 代码，逗号分隔。6 位数字会自动补后缀，可转债请自己写后缀 |
--pool | 预设股票池 id，可逗号组合，见第 10 节 |
--file | CSV 文件（UTF-8），自动找代码列，找不到用第一列 |
--period | 周期，可多选，默认 1d。实际可用的见下表 |
--start / --end | 默认 2020-01-01 到今天（同花顺默认近 3 年；tx 分钟线默认取接口能给的全部） |
--adj | 复权，可多选：none,front,back,front_ratio,back_ratio。tx 默认 none，其他默认 front |
--force | 强制按区间重新下载、覆盖已有数据 |
--skip-benchmark | 不自动补沪深 300 基准（默认每次都会先补） |
--data-root 目录 | 下载到另一个目录，仅 tx、同花顺支持 |
--workers N | 并发数，默认 2，仅 miniQMT、BaoStock 使用 |
--allow-gaps | 仅 tx 分钟线：超出保留期时只下能拿到的部分，不能与 --force 同用 |
--repair-volume-units | 仅 tx：核验并修复旧库里以「股」为单位的成交量（先备份） |
--db-write-mode | auto（默认）/ normal / short-lock，一般不用改 |
--direct-range、--empty-data-policy、--summary-json | 主要供 miniQMT 下载使用（--summary-json 对 tx 也有效，写入下载记录） |
| 数据源 | 周期 | 复权 | 前提 |
|---|---|---|---|
| tx | 1d 1m 5m | 5 种 | 无 |
| baostock | 1d 5m | none front back | 无 |
| tushare | 1d 1m 5m | none front back | tushare_token 及积分权限 |
| ths | 1d | none front back | ths_api_key |
| http | 1d 1m 5m tick | 5 种 | http_base_url、http_api_key |
| miniqmt | 1d 1m 5m tick | 5 种 | Windows，miniQMT 已登录 |
kh data download --source tx --stocks 000300.SH,000001.SH --start 20251001 --adj front
kh data download --source baostock --pool hs300
kh data download --source http --stocks 000001.SZ --period 1d,5m --adj none,front各数据源的详细说明见 2.3。
data scan / sync / update-pool
| 命令 | 参数和说明 |
|---|---|
kh data scan | 按交易日检查缺口。--period（单个，默认 1d）、--stocks、--start（默认 20200101）、--end、--fix（补缺；有股票补缺失败时退出码为 1）、--source（补缺用的数据源；用 tx 补缺只补不复权，其他源补前复权）、--allow-gaps。有缺口退出码仍为 0，有扫描失败为 1 |
kh data sync | 给库里全部证券补今天的数据。--period（可多选）、--source、--schedule HH:MM（前台常驻，工作日定时执行）、--allow-gaps。复权固定：tx 不复权，其他前复权 |
kh data update-pool | 更新预设板块成分股列表。默认优先用 miniQMT，取不到改用 BaoStock；写了 --source miniqmt 而 miniQMT 没开时直接报错退出（退出码 1） |
不写 --source 时的自动选择顺序：配置了 Tushare Token → tushare；启用了 BaoStock → baostock；Windows 安装版（自带 xtquant）→ miniqmt，miniQMT 没开会直接报错；否则 baostock。tx、同花顺不会被自动选中。详见 2.3。
data export / reindex / repair
| 命令 | 参数和说明 |
|---|---|
kh data export 代码 | --period（默认 1d）、--start、--end、--output（默认当前目录 代码_周期.csv）。导出行情列（不含 dividend_type、update_time），第一列是无表头的行号。代码必须带后缀 |
kh data reindex | 核对数据文件和索引是否一致，默认只预览；--fix 备份后补登记；--workers（1～16，默认 8） |
kh data repair | 处理异常退出留下的 WAL 文件。--db-path、--memory-limit（默认 256MB）。修复时（成功也一样）会把原文件备份到数据目录下的 _wal_repair_quarantine_时间 文件夹、原位置换成空库；命令总是显示「OK 修复完成」，运行前请先关闭软件，运行后检查有没有这个文件夹 |
data source test / conflicts
kh data source test --source 数据源：检查数据源能否使用。tx 和同花顺会真的联网取一次数据；tushare 只检查有没有配置 Token，不验证 Token 是否有效；baostock 只检查组件是否齐全。kh data conflicts list / export / resolve：跨数据源冲突记录。当前版本的数据源不会产生冲突记录，执行后只会提示「当前没有跨来源冲突记录」。
6 kh result
| 命令 | 参数和说明 |
|---|---|
kh result list | 默认最近 20 个；--all 全部；--strategy 名字 按策略名过滤（不加 --all 时只在最近 20 个里过滤；过滤后的序号不能用于 --id）；--json（收益、回撤是 "+1.23%" 这样的字符串） |
kh result show [文件夹名] | 默认最近一次；--id N 为 list 的第 N 个；--json（数值为数字） |
kh result report [文件夹名] | 生成 HTML 报告。--id、--index（生成全部结果的索引页）、--no-open、--output 路径、--data-root 目录 |
kh result compare | --last N，对比最近 N 次（默认 3） |
kh result clean | --keep N 保留最近 N 个（默认 10），其余直接删除不确认；--dry-run 只预览 |
序号按结果文件夹的修改时间排列。详见 2.2 第 4 节。
7 kh strategy
| 命令 | 说明 |
|---|---|
kh strategy list [--dir 目录] | 列出策略目录里的 .py 和同名 .kh |
kh strategy create 名称 [--dir 目录] | 生成空白策略 名称.py 和配置 名称.kh |
kh strategy validate 路径.py | 执行策略文件后检查必需和可选的回调函数。要写 .py 的路径 |
kh strategy info 路径.py | 静态查看函数、import 和有没有配套 .kh |
8 kh tool、kh bridge
| 命令 | 说明 |
|---|---|
kh tool pool [id] | 不带 id 列出全部预设股票池；带 id 打印该池全部代码 |
kh tool trade-day [日期] | 判断是否交易日；--range-start 和 --range-end 同时给时列出区间内的交易日。它按法定节假日推算，个别调休日可能与交易所日历不一致，以交易所公告为准 |
kh tool parquet-cache stats / list | 查看 Parquet 缓存（见 1.12）。--root 指定缓存目录 |
kh tool parquet-cache check / build 配置.kh | 检查能否命中 / 构建缓存。build 可加 --batch-size --workers --compression --force |
kh tool parquet-cache use-readonly 配置.kh | 生成一个使用只读缓存的 .kh 副本；--in-place 直接改原文件 |
kh tool parquet-cache clean | 清理缓存，不加 --yes 只预览；--older-than-days N |
kh bridge serve | Windows + miniQMT 上开 HTTP 桥接服务。--host（默认 127.0.0.1，局域网用 0.0.0.0）、--port（默认 8001）、--api-key、--qmt-path。见 2.3 第 4 节 |
kh bridge status | 检查桥接服务是否在运行。--url，或 --port（未配置地址时使用） |
Parquet 缓存这组命令的输出是英文的。
9 常用配置项（kh config set）
| 键 | 取值 | 默认 | 说明 |
|---|---|---|---|
duckdb_data_path | 目录 | 空 | 数据目录（不检查是否存在） |
strategy_dir | 目录 | 空 | 策略目录 |
backtest_data_source | duckdb / miniqmt | duckdb | 回测数据源；Web 回测只支持 duckdb |
tushare_token | 字符串 | 空 | Tushare Token（只是编码保存，不是加密） |
tushare_api_url、tushare_use_proxy、tushare_proxy_url | 空 / false / 空 | Tushare 镜像地址和代理 | |
ths_api_key | 字符串 | 空 | 同花顺 API Key |
http_base_url、http_api_key | URL、字符串 | 空 | HTTP 桥接服务地址和 Key |
baostock_enabled | 布尔 | false（kh init 默认开启） | 影响 scan / sync 的自动选源 |
qmt_path、client_path | 目录 | 空 | Windows：miniQMT 的数据目录和客户端路径 |
risk_free_rate | 0～1 | 0.03 | 无风险利率 |
volume_limit_enabled、participation_rate、allow_partial_fill | 布尔、0～1、布尔 | false、0.1、true | 成交量限制（见 1.12） |
auto_report | 布尔 | false | 为 true 时 kh run 总是生成报告 |
check_data_integrity_mode | auto/full/off | auto | 回测前数据检查（命令行 kh run 不执行） |
performance_preset | balanced/performance/low_memory | balanced | 数据加载模式，会连带重置详细性能项 |
performance_framework_history_preload_days | 0～2000 | 300 | 历史预热天数（自然日） |
performance_duckdb_parallel_read_workers | 1～64 | 4 | 并行读取线程 |
performance_parquet_cache_pack | off/read_only/build_then_read | off | Parquet 缓存模式 |
完整列表以 kh config show 为准。配置文件位置：Windows %USERPROFILE%\.khquant\settings.json，Linux ~/.khquant/settings.json，macOS ~/Library/Application Support/khQuant/settings.json。图形界面、命令行和 Web 共用这个文件，请用 kh config 或界面修改，不要手动编辑。
10 预设股票池（--pool）
| id | 名称 | id | 名称 |
|---|---|---|---|
sz50 | 上证50 | sza | 深证A股（仅命令行） |
hs300 | 沪深300 | etf | 沪深ETF |
zz500 | 中证500 | fund | 沪深场内基金（含ETF/LOF） |
gem | 创业板 | t0etf | T0型ETF |
star | 科创板 | t0stock | T0股票型ETF |
a | 沪深A股 | bond | 沪深转债（仅命令行） |
sha | 上证A股 | index | 常用指数 |
id 不分大小写，可以逗号组合，如 --pool hs300,zz500。图形界面和 Web 里的「自选清单」在命令行里没有对应 id。用 kh data update-pool 更新过的成分股列表优先于安装包自带的。
11 环境变量
| 变量 | 作用 |
|---|---|
NO_COLOR | 关闭输出颜色 |
HITHINK_FINANCE_API_KEY / THS_API_KEY | 同花顺 API Key，优先于配置文件 |
KHQUANT_WEB_ACCESS_KEY | kh web 的访问密钥，设了以后总是要求密钥 |
KHQUANT_WEB_ALLOWED_HOSTS | Web 允许访问的域名，逗号分隔（反向代理时用） |
KHQUANT_CLOUDFLARED_PATH | cloudflared 程序路径，所有平台都优先用它（Linux 或源码运行时必须设置或放进 PATH） |
KHQUANT_MARKET_TZ | 仅 Linux：行情时间所用时区，默认 Asia/Shanghai |
KHQUANT_DUCKDB_LOCK_WAIT_SECONDS | 下载时等待数据库占用解除的最长秒数，默认 600 |
KHQUANT_WEB_STATE_DIR | Web 项目和日志的存放目录 |
软件启动时会自动把 PYTHONHASHSEED 固定为 0，保证结果可复现，不需要自己设置。
▶ 本节视频：附录 A · 回测结果的存放与管理
12 回测结果的存放与管理
图形界面、kh 命令和 Web 工作台的回测结果存在同一个目录，三边看到的是同一批结果。命令行查看、对比、生成报告见 2.2 第 5.1 节；界面里「回测历史管理」窗口的基本用法见 1.9。
12.1 结果存在哪里
| 平台 | 位置 |
|---|---|
| Windows | %LOCALAPPDATA%\KhQuant\backtest_results |
| macOS | ~/Library/Application Support/khQuant/backtest_results |
| Linux | ~/khquant/backtest_results |
- V3.4.0 以前的 Windows 安装版把结果写在安装目录里，新版仍会读取那里的旧结果，不会移动它们。
- V2 的结果在另一个目录（
%LOCALAPPDATA%\KhQuantOS\backtest_results），V3 不会读取。想在 V3 里看，把对应的结果文件夹复制到 V3 的结果目录。
12.2 一个结果文件夹里有什么
文件夹名形如 strategy_b429b43e-123a4b5c_20250101_20260930_20261003_194513：依次是策略编码（由策略文件名算出）、防重名后缀、回测起止日期和运行时间。同一个策略改参数跑多次，文件夹名只有后缀和运行时间不同。
从 Web 工作台发起的回测，文件夹名末尾还会多一段 _run_编号。
| 文件 | 内容 |
|---|---|
summary.csv | 汇总指标：初始资金、最终资金、总收益、年化收益、最大回撤（百分数）、交易天数 |
daily_stats.csv | 每日总资产、现金、持仓市值、当日收益、基准收盘价和净值、持仓明细 |
trades.csv | 每笔成交：时间、代码、方向、价格、数量、金额、佣金、印花税、过户费、流量费、成交后的资产 |
benchmark.csv | 基准每日收盘价（从回测开始日前几天开始） |
config.csv | 基本信息：区间、资金、基准、策略文件、股票池、周期、复权、数据目录、运行耗时、内存档位 |
full_*.kh | 这次实际运行的完整配置，包括交易成本、触发方式等。界面跑的叫 full_temp_running_config.kh，命令行跑的叫 full__tmp_…kh |
策略名.py | 运行时策略代码的副本 |
策略名.kh | 策略文件旁边同名 .kh 的副本（有才复制，不一定是本次用的配置） |
report.html | HTML 报告，见 2.2 第 5.2 节（界面回测默认不生成） |
duckdb_lock_skips.csv | 只在有行情因数据库被占用而跳过时出现 |
run_meta.json | 只在 Web 发起的回测里出现 |
config.csv 不记录交易成本和触发方式，要完整复现一次回测，以 full_*.kh 为准。回测中途停止或出错时，文件夹里可能缺 summary.csv，这就是「不完整结果」。
12.3 在图形界面里管理
「回测历史管理」窗口的列、按钮和基本操作见 1.9。补充几点：
- 搜索和筛选不叠加：搜索框匹配策略名称和起止日期；「筛选」按创建时间看最近 7、30、90 天（「自定义日期」目前不起作用）。两者后操作的那个生效。
- 删除要小心：「删除选中」会删掉所有勾选过的行，包括被搜索、筛选暂时隐藏的行。删除直接删文件夹，不进回收站。
- 「还原」会覆盖文件：它把结果里的策略
.py（和同名.kh）复制回原来的路径并覆盖，再把配置填回主界面。还原前确认原路径的策略不需要保留。 - 还原读取的是本次运行保存的
full_*.kh，命令行跑出的结果同样适用（命令行上改过的区间、资金也在里面）。 - 「报告」打开的是和回测刚结束时一样的报告窗口（见 1.10），不是 HTML 报告。
12.4 清理和备份
| 方式 | 删什么 | 注意 |
|---|---|---|
| 界面行内「删除」 | 这一条 | 有确认框 |
| 界面「删除选中」 | 所有勾选行 | 隐藏的勾选行也会删 |
| Web 历史结果页删除 | 这一条 | 远程访问也能删 |
kh result clean --keep N | 最近 N 个以外的全部 | 没有确认，先 --dry-run |
| 手动删文件夹 | 任意 | 三端下次刷新都会消失 |
以上方式删除后都无法恢复。重要的结果请先把整个文件夹复制到别处保存。
问：V2 的回测历史怎么带到 V3？
答：把 %LOCALAPPDATA%\KhQuantOS\backtest_results 里需要的结果文件夹复制到 %LOCALAPPDATA%\KhQuant\backtest_results。
问：某条结果的收益显示 - 或「不完整」？
答：这次回测没有正常结束，缺少汇总文件。可以删除后重新跑。图形界面默认隐藏这类结果，勾选「显示不完整结果」才看得到。
本篇基于 V3.4.1.10 编写，帮助文本和默认值以实际运行为准。