khQuant Skill 使用手册

本文面向希望在 Claude Code、Cursor 等 AI 编程工具中使用看海量化回测平台的用户。
khQuant Skill 的作用，是让 AI 更懂 kh 命令、策略文件、.kh 配置、数据管理、回测执行和结果分析，从而把自然语言需求更稳定地转成可执行的量化研究流程。

仓库地址：
https://github.com/khscience/khquant-skill

一、khQuant Skill 是什么

khQuant Skill 是一份为看海量化回测平台准备的 AI 技能包。它不是一个新的回测程序，也不是独立运行的软件，而是一组给 AI 编程工具读取的说明文件。
安装后，当你在 Claude Code 或 Cursor 中提出类似下面的问题时，AI 可以按 khQuant 的真实用法来回答和操作：

/khQuant 帮我创建一个双均线策略
/khQuant 下载沪深300日线数据
/khQuant 解释一下 kh run 的参数
/khQuant 帮我写一个 MACD 策略和对应的 .kh 配置文件
/khQuant 我的回测结果怎么看？

它主要解决三个问题：

减少 AI 胡编 API 的概率
Skill 中整理了 khQuant 的命令、策略回调函数、常用 API、.kh 配置结构和排错方法，AI 不需要凭空猜。
按需加载知识，而不是一次塞满上下文
普通长提示词通常需要每次重新复制，成本高、也容易干扰模型。Skill 会先加载入口说明，再根据问题读取对应的参考文档。
把操作边界写清楚
查询类命令、修改类命令、危险类命令有不同的安全等级。AI 在执行涉及数据下载、回测运行、清理结果等操作前，会按规则提示或请求确认。

二、适用版本与前提条件

当前公开版本信息：

Skill 版本：v1.0.1
主要匹配软件版本：khQuant v3.3.6.1
基础兼容范围：khQuant v3.x
不支持：khQuant v2

v1.0.1 已补充 khQuant v3.3.6+ 的新能力说明，包括：

performance_preset 三档性能预设
kh run --memory-profile
performance_framework_history_preload_days
kh tool parquet-cache
kh bridge serve/status
kh data download/sync --source http

如果你的 khQuant 版本低于 v3.3.6，Skill 仍可用于基础配置、数据管理、策略开发和普通回测；但涉及上述新参数时，建议先运行：

kh version
kh run --help
kh tool parquet-cache --help
kh bridge --help

确认本机版本是否支持对应命令。
使用前请确保：

已安装 Claude Code、Cursor 或其他支持 Skill/规则文件的 AI 编程工具；
已安装 khQuant v3.x；
命令行中可以正常运行 kh version；
Python 版本不低于 3.8；
能运行 kh doctor 检查环境。

三、安装与使用

3.1 下载 khQuant Skill

推荐使用 git clone，后续更新最方便：

git clone https://github.com/khscience/khquant-skill.git
cd khquant-skill

如果没有安装 Git，也可以直接下载 ZIP：

打开 https://github.com/khscience/khquant-skill
点击绿色 Code 按钮
选择 Download ZIP
解压到本地目录

3.2 交给 Agent 安装（推荐）

既然 Skill 本身就是给 AI 编程工具用的，最省事的安装方式不是手动敲复制命令，而是把仓库地址直接交给 Agent，让它根据你的系统环境安装。
你可以在 Claude Code、Cursor 或其他支持文件操作的 Agent 里输入：

请帮我安装 khQuant Skill。
仓库地址是：https://github.com/khscience/khquant-skill.git

如果当前环境是 Claude Code，请把仓库里的 skills/khquant 目录安装到我的 Claude Code 全局 skills 目录；
如果当前环境是 Cursor，请安装到 Cursor 的 skills 目录。
安装完成后，请告诉我是否需要重启客户端。

Agent 通常会自动完成这些步骤：

检查本机是否安装了 git；
clone 或更新 khquant-skill 仓库；
判断当前系统是 Windows、macOS 还是 Linux；
把 skills/khquant 复制到对应的 Skill 目录；
提醒你重启 Claude Code 或 Cursor。

常见目标目录如下，供你检查：

工具	macOS / Linux	Windows
Claude Code	`~/.claude/skills/khquant`	`%USERPROFILE%\.claude\skills\khquant`
Cursor	`~/.cursor/skills/khquant`	`%USERPROFILE%\.cursor\skills\khquant`

如果安装失败，可以把报错信息继续发给 Agent，让它修正路径、权限或 git 环境问题。

3.3 项目级安装（可选）

如果你只想在某一个项目里使用 khQuant Skill，而不是全局启用，可以让 Agent 执行项目级安装：

请把 khquant-skill 仓库里的 skills/khquant/SKILL.md 整理到当前项目的 AGENTS.md 中，
并把 references 目录复制到项目内合适的位置，方便后续按需读取。

这种方式适合团队项目、课程示例或你希望把规则随项目一起版本管理的场景。对于普通用户，优先使用上一节的全局安装方式即可。

3.4 推荐触发方式：`/khQuant`

最直接、最稳定的调用方式，是在对话开头使用：

/khQuant

例如：

/khQuant 帮我检查当前环境，看看 khQuant 是否配置正常

/khQuant 帮我写一个 RSI 策略，并生成对应的 .kh 配置文件

/khQuant 我想下载沪深300成分股的日线数据，应该怎么做？

/khQuant 解释一下上一次回测结果里的年化收益率和最大回撤

使用 /khQuant 的好处是：不需要等待 AI 根据关键词猜测是否要启用 Skill，意图更明确。
除了显式调用外，当你提到“回测”“看海量化”“kh 命令”“双均线”“MACD”“RSI”“.kh 配置文件”等关键词时，支持 Skill 的工具也可能自动激活它。但在正式使用中，仍建议优先使用 /khQuant。

3.5 更新 Skill

后续仓库有更新时，也建议直接交给 Agent 处理。可以输入：

请帮我更新 khQuant Skill：
1. 进入之前 clone 的 khquant-skill 仓库，执行 git pull；
2. 把最新的 skills/khquant 同步到我当前使用的 AI 工具 Skill 目录；
3. 如果找不到旧仓库，就重新从 https://github.com/khscience/khquant-skill.git clone；
4. 完成后告诉我是否需要重启 Claude Code 或 Cursor。

这样可以避免手动处理不同系统下的路径差异。更新完成后，建议重启 AI 编程工具，让新的 Skill 内容生效。

后续内容说明

到这里，你已经知道 khQuant Skill 是什么、适配什么版本、如何安装，以及如何用 /khQuant 调用。
如果你的目标只是使用软件，上面的内容已经足够，后面可以不看。
后续章节作为教程附录，主要面向感兴趣的读者：它会解释 Skill 的目录结构、内部路由、安全分级、各 reference 文档分别解决什么问题，以及为什么这样设计。想了解原理、二次修改或参与扩展的用户，可以继续阅读。

附录一：目录结构

仓库结构如下：

khquant-skill/
├── README.md
├── LICENSE
└── skills/
    └── khquant/
        ├── SKILL.md
        └── references/
            ├── setup.md
            ├── data-management.md
            ├── strategy-development.md
            ├── backtesting.md
            ├── results-analysis.md
            ├── troubleshooting.md
            ├── command-reference.md
            └── pools-and-codes.md

其中：

文件	作用
`SKILL.md`	技能入口，包含触发说明、执行原则、场景路由和安全规则
`setup.md`	首次配置、`kh init`、`kh config`
`data-management.md`	数据源选择、数据下载、扫描、修复、同步
`strategy-development.md`	策略开发、回调函数、API、MyTT、`.kh` 配置
`backtesting.md`	回测运行、参数覆盖、报告生成、性能模式
`results-analysis.md`	回测结果查看、绩效指标解释、多次结果对比
`troubleshooting.md`	常见错误与修复方法
`command-reference.md`	`kh` 命令速查
`pools-and-codes.md`	股票代码格式、股票池简称、市场后缀

Skill 的核心思想是三层加载：

层级	文件	作用	加载时机
L1 触发层	`SKILL.md` 顶部元数据	告诉 AI 什么时候启用 Skill	工具判断阶段
L2 路由层	`SKILL.md` 主体	判断用户问题属于哪个场景	Skill 激活后
L3 知识层	`references/*.md`	各场景的详细说明	按需加载

例如用户问：

/khQuant 怎么下载沪深300日线数据？

AI 通常只需要读取 data-management.md 和必要的命令说明，不需要把策略开发、结果分析、排错文档全部塞进上下文。

附录二：SKILL.md 的关键内容

SKILL.md 是入口文件，主要包含四类内容：

元数据
执行原则
安全分级
场景路由

2.1 元数据

元数据描述 Skill 的名称、触发条件和允许使用的工具。典型内容包括：

name: khquant
description: 当用户提到“回测”“看海量化”“kh命令”“跑策略”“下载股票数据”“双均线”“MACD”“RSI策略”“.kh配置文件”等场景时使用。
version: 1.0.1
allowed-tools: [Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion]

这些关键词用于帮助 AI 判断是否需要启用 khQuant Skill。

2.2 安全分级

Skill 对 kh 命令按风险分为三类：

级别	命令类型	行为
自动执行	查询类命令，如 `kh version`、`kh doctor`、`kh config show`、`kh data info`、`kh result list/show`、`kh strategy list/info/validate`	可以直接运行并解释结果
确认后执行	修改或生成类命令，如 `kh data download`、`kh run`、`kh result report/compare`、`kh strategy create`、`kh config set/reset`、`kh tool parquet-cache build`	先展示将要执行的命令，再征求确认
必须明确授权	危险类命令，如 `kh result clean`、`kh tool parquet-cache clean`、`kh data repair`、可能覆盖配置的 `kh init`	必须说明风险并获得明确授权

这样可以避免 AI 把清理、修复、重置等高风险动作当成普通查询直接执行。

2.3 命令回显

Skill 要求每次执行命令前先展示命令，例如：

$ kh data info 000001.SZ

这样用户可以清楚知道 AI 实际准备做什么，便于学习和复核。

2.4 敏感信息处理

Tushare Token 等凭证不应由 AI 直接代填或代管。需要配置时，AI 应引导用户自己执行：

kh config set tushare_token

不要在公开对话、日志或截图里暴露真实 token。

附录三：场景路由

SKILL.md 会根据用户意图选择对应 reference 文档：

用户意图	典型关键词	参考文档
首次配置	第一次用、怎么开始、初始化、配置	`references/setup.md`
数据管理	下载数据、股票池、数据源、同步、数据缺口、BaoStock、Tushare	`references/data-management.md`
策略开发	写策略、创建策略、khHandlebar、khGet、khPrice、khIndex、MACD、RSI、`.kh`	`references/strategy-development.md`
回测执行	跑回测、运行策略、`kh run`、回测参数、性能设置	`references/backtesting.md`
结果分析	回测结果、收益率、报告、对比、最大回撤	`references/results-analysis.md`
故障排查	报错、ERR、失败、找不到、连不上	`references/troubleshooting.md`
命令查询	什么命令、参数、用法、帮助	`references/command-reference.md`
股票代码	股票代码、沪深300、市场后缀、股票池	`references/pools-and-codes.md`

如果无法判断用户意图，通常先运行：

kh doctor

了解环境状态，再追问用户想做什么。

附录四：常见工作流

4.1 新用户上手

一个典型的新用户流程：

kh version
kh doctor
kh init
kh data download --source baostock --stocks 000001.SZ --period 1d
kh strategy list
kh run <策略配置文件.kh> --report

AI 不只是执行命令，还会解释每一步在做什么，以及输出结果意味着什么。

4.2 日常回测

常见流程：

kh data info 000001.SZ
kh data download --source baostock --stocks 000001.SZ --period 1d
kh run my_strategy.kh --report
kh result show

如果需要对比多次回测：

kh result compare
kh result compare --last 5

4.3 数据管理

常见下载命令：

kh data download --source baostock --stocks 000001.SZ
kh data download --source baostock --stocks 000001.SZ,600000.SH
kh data download --source baostock --pool hs300 --period 1d
kh data download --source baostock --pool hs300 --period 1d --start 20100101 --adj front --workers 4

扫描和修复数据缺口：

kh data scan --period 1d
kh data scan --period 1d --fix --source baostock

v3.3.6+ 还支持桥接数据源：

kh bridge serve
kh bridge status
kh data download --source http --stocks 000001.SZ --period 1d
kh data sync --source http

4.4 策略开发

策略开发文档重点说明：

init(stock_list, data)
khHandlebar(data)
khPreMarket(data)
khPostMarket(data)
khGet
khPrice
khIndex
khHistory
khDuckDB
khMA
khAddExtraFields
generate_signal

一个典型策略至少需要：

def khHandlebar(data):
    signals = []
    # 读取行情、判断条件、生成信号
    return signals

交易信号通常形如：

{
    "code": "000001.SZ",
    "action": "buy",
    "price": 10.50,
    "volume": 100,
    "reason": "金叉买入"
}

实际开发中建议优先使用 generate_signal 来生成标准信号。

4.5 性能模式与缓存

v3.3.6+ 补充了更多性能相关能力。
回测时可使用：

kh run my_strategy.kh --memory-profile low
kh run my_strategy.kh --memory-profile balanced
kh run my_strategy.kh --memory-profile high

.kh 配置中可使用性能预设：

{
  "backtest": {
    "performance_preset": "balanced",
    "performance_framework_history_preload_days": 300
  }
}

Parquet 缓存包相关命令：

kh tool parquet-cache stats
kh tool parquet-cache list
kh tool parquet-cache check
kh tool parquet-cache build
kh tool parquet-cache use-readonly
kh tool parquet-cache clean

其中 clean 属于危险操作，应明确确认后再执行。

附录五：reference 文档概览

5.1 setup.md

覆盖：

kh init 五步初始化
数据源选择
数据路径设置
策略目录设置
Tushare / BaoStock 配置
kh config show/set/reset

配置文件通常位于：

~/.khquant/settings.json

5.2 data-management.md

覆盖：

xtdata / BaoStock / Tushare 能力差异
日线、分钟线、Tick 数据支持情况
前复权、后复权、比例复权支持情况
数据下载、扫描、修复和同步
DuckDB 数据库异常处理
http 桥接数据源

5.3 strategy-development.md

这是最重要、也最长的一份参考文档，覆盖：

策略文件结构
回调函数
data 字典结构
常用 API
信号格式
MyTT 指标库
.kh 配置结构
常见策略错误
高性能指标预加载模式

它直接决定 AI 能不能写出更接近真实可运行结构的策略。

5.4 backtesting.md

覆盖：

kh run 的参数覆盖规则
--report
--json
--quiet
--verbose
--no-open
回测产物目录
HTML 报告
性能预设与内存模式

5.5 results-analysis.md

覆盖：

总收益率
年化收益率
最大回撤
交易天数
月度收益
结果对比
旧结果清理

其中 kh result clean 属于不可逆清理操作，应先 --dry-run 预览。

5.6 troubleshooting.md

覆盖常见错误，例如：

找不到 kh 命令
PowerShell 参数歧义
xtquant 无法连接
DuckDB 被占用
数据库损坏
BaoStock 未安装
Tushare Token 未配置
回测进程卡住

5.7 command-reference.md

按命令大类整理：

kh init
kh config
kh run
kh data
kh result
kh strategy
kh tool
kh doctor
kh version
kh gui
kh bridge

适合在用户问“某个命令怎么用”“有哪些参数”时加载。

5.8 pools-and-codes.md

覆盖：

.SH / .SZ / .BJ 后缀
纯数字代码自动补全规则
BaoStock 内部代码格式转换
预设股票池简称

常见预设池包括：

a       沪深A股全部
sha     上证A股
sza     深证A股
hs300   沪深300
sz50    上证50
zz500   中证500
gem     创业板
star    科创板
etf     沪深ETF
t0etf   T0型ETF
t0stock T0股票型ETF
bond    沪深转债
index   常用指数

附录六：Skill 与长提示词的区别

维度	长提示词	Skill
加载方式	每次手动复制	按触发条件启用
上下文成本	每次都要占用大量上下文	按需加载相关 reference
维护方式	改完后要重新复制	修改 markdown 文件即可
工具调用	通常只提供文字指导	可配合 Bash、Read、Write、Edit 等工具
安全边界	依赖提示词约束	可以明确命令分级和确认流程
适合场景	一次性任务	长期维护的领域知识与工作流

对 khQuant 这种包含命令行、策略代码、配置文件、数据源、回测结果和排错流程的系统来说，Skill 比一段长提示词更适合长期维护。

附录七：二次开发

khQuant Skill 使用 MIT 协议开源。你可以：

修改 SKILL.md 的触发关键词；
调整安全分级；
增加自己团队常用的工作流；
在 references/ 中补充新的专题；
增加新的路由场景，例如因子库、机器学习模型、实盘接口说明等。

如果你做了通用性较强的改进，欢迎提交 Issue 或 Pull Request：
https://github.com/khscience/khquant-skill