3.3 khQuant 的 Skill 介绍

本篇重点：本篇介绍 khQuant Skill 是什么、里面有什么，以及 V3 和 V2 用户各自怎么用它让 AI 少犯错。

1 Skill 是什么

1.1 一句话说清楚

Claude Code、Codex、Cursor、DeepSeek harness、WorkBuddy 这类 AI 编码助手（其他 AI 编码助手也都兼容），能读文件、写文件、在终端里运行命令。但它们对 khQuant 一无所知：不知道有哪些 kh 命令，不知道 khHandlebar 要返回什么，也不知道 .kh 配置文件长什么样。不知道的时候，AI 往往会「合理地猜」，猜出来的参数和函数名看上去很像真的，跑起来才报错。

Skill 就是解决这个问题的：它是一个文件夹，里面有一份入口说明 SKILL.md 和若干份参考文档。AI 工具启动时会登记这个文件夹，当你说到「回测」「下载股票数据」「写个 MACD 策略」之类的话，AI 就先读 Skill，再按里面写的真实命令和 API 做事。

可以把它理解为：你请了一位懂编程、但没用过 khQuant 的助手，Skill 是你塞给他的那本操作手册，外加「哪些事可以直接做、哪些事要先问我」的规矩。

1.2 没有 Skill 时 AI 常犯的错

下面这些错误，在不给参考资料、直接让 AI「写一个 khQuant 双均线策略」时很常见。Skill 的参考文档里都有对应的规定：

• 编造函数和参数：写出 khQuant 里不存在的函数，或给 kh run 加上不存在的选项。
• 信号列表用错方法：generate_signal 返回的是列表，要用 signals.extend() 合并；写成 signals.append() 会把列表套进列表，信号不执行。
• 股票代码不带后缀：写 "000001" 而不是 "000001.SZ"，结果取不到数据。
• 周期对不上：配置是日线触发，代码里却用 khHistory(..., '1m') 取分钟数据。
• 引入未来数据：自己从数据库读到「今天」的收盘价再判断今天的买卖。
• 数量单位搞错：信号里的 volume 单位是「股」，不是「手」。

1.3 它是怎么起作用的

Skill 不是程序，不会在后台运行，也不改 khQuant 软件本身。它的作用过程是这样的：

1. 登记：AI 工具启动时，读到 SKILL.md 开头的一段描述。这段描述列出了一批触发词，比如「回测」「kh命令」「双均线」「MACD」「khHistory」「.kh配置文件」等。
2. 触发：你的话里出现这些词时，AI 判断该用这个 Skill，读入 SKILL.md 正文。你也可以点名使用：Claude Code 里输入 /khquant，Codex 里输入 $khquant。
3. 按需加载：SKILL.md 里有一张「你想做什么 → 读哪份参考文件」的对照表。比如你说「写策略」，AI 去读 strategy-development.md；说「报错了」，去读 troubleshooting.md。用不到的文件不读，省下对话篇幅。
4. 执行：AI 按参考文件里的命令格式和 API 写代码、跑命令，并遵守 SKILL.md 规定的安全规则（第 4 节）。

1.4 和旧「提示词工程」的关系

以前的教程提供过两段很长的「提示词工程」（V2 版、V3 版各一段），用法是开一个新对话，把整段文字粘贴给 AI，再描述策略。这个办法有效，但有几个问题：每次都要粘贴上万字；内容写死在网页里，软件更新后容易过时；而且只管写代码，不管下数据、跑回测。

Skill 把同样的知识拆成了按场景组织的文件，并补上了命令行操作、结果解读、排错这些内容，跟着软件版本一起更新。旧的提示词工程不再维护，本篇取代那两篇教程。V2 用户原来「粘贴提示词」的用法，换成第 5 节的「上传参考文档」即可，思路不变，资料更新。

2 Skill 装在哪

Skill 本体是仓库里的 skills/khquant 文件夹。取得方式二选一：git clone https://github.com/khscience/khquant-skill.git，或在 GitHub 页面点 Code → Download ZIP 后解压。然后把 skills/khquant 整个文件夹复制到对应工具的 Skill 目录：

DeepSeek harness、WorkBuddy 等其他 AI 编码助手也都兼容：按各工具说明放进它的 Skill 目录，或者把 SKILL.md 当作项目说明交给它。

复制好后重启 AI 工具。最省事的办法是直接让 AI 自己装：告诉它仓库地址，让它把 skills/khquant 装到它自己的用户级 Skill 目录，并告诉你装在了哪里。

逐步的安装命令（Windows PowerShell、macOS / Linux）、用 API 中转站接入 Codex、第一次对话怎么说，都在 2.2 命令行模式与 AI 智能策略研究里，这里不重复。各工具的 Skill 目录可能随它们的版本变化，以工具当前的说明为准。

3 Skill 里面有什么

3.1 目录结构

仓库里的完整目录：

khquant-skill/
├── README.md                  仓库说明：安装方法、版本记录
├── LICENSE                    MIT 许可
└── skills/khquant/            ← 真正要复制的就是这个文件夹
    ├── SKILL.md               入口：触发词、执行规则、场景对照表
    ├── agents/openai.yaml     Codex 界面里显示的名称、简介和默认提示
    └── references/            9 份参考文档
        ├── setup.md
        ├── data-management.md
        ├── strategy-development.md
        ├── backtesting.md
        ├── web-backtesting.md
        ├── results-analysis.md
        ├── troubleshooting.md
        ├── command-reference.md
        └── pools-and-codes.md

3.2 SKILL.md：入口和规矩

SKILL.md 是 AI 最先读的文件，主要写了四件事：

• 什么时候用：开头的触发词列表。
• 执行规则：命令分三档（查询类直接执行、修改类确认后执行、危险类必须明确同意）；每条命令执行前先写一行 $ kh … 给你看；不碰 Token 和 API Key。
• 先检查再动手：第一次使用时先运行 kh version 确认是 V3，再运行 kh doctor 检查环境；发现是 V2 或找不到 kh 命令就停下，提示你去安装。
• 场景对照表和常用流程：新用户上手、日常回测、网页回测、各数据源的能力边界、结果怎么解读。

3.3 九份参考文档

3.4 strategy-development.md：最新最全的策略 API 说明

这份文件是 Skill 里最长的一份，也是写策略时最该交给 AI 的一份。它把原来散在几篇教程里的内容集中到了一起：

• 策略文件结构：from khQuantImport import * 统一导入；init、khHandlebar、khPreMarket、khPostMarket 四个回调的签名、调用时机和返回值。
• data 字典：当前时间、账户、持仓、股票池、每只股票的行情分别放在哪个键里。
• 交易信号格式：code、action、price、volume 等字段。
• 取数函数：khGet、khPrice、khIndex、khHas、khAddExtraFields、khHistory、khDuckDB、khMA，每个都有签名、参数表和示例。
• 高性能指标模式：先用 khDuckWrite 把指标写进数据库，策略里用 khAddExtraFields + khIndex 零读盘取值。
• 交易辅助：generate_signal（按资金比例或股数生成信号）、挂单查询和撤单函数、calculate_max_buy_volume、几个辅助类。
• 时间工具：is_trade_day、get_trade_days_count 等。
• MyTT 指标库：均线、MACD、KDJ、RSI、布林带、ATR 等指标和 CROSS、REF、HHV 等工具函数的清单。
• .kh 配置结构：各配置节的字段、触发方式和数据周期怎么搭配、日内多次触发、复权方式、滑点算法、T+0 判定。
• 完整策略模板、编程规范和常见错误表：AI 写完代码后可以对照自查。

V2 和 V3 的策略接口完全相同，所以这份文件 V2 用户同样可以拿来用。文件里出现的 kh strategy create、kh strategy validate 等命令只在 V3 有，V2 用户忽略即可。

这份文件以 API 为主，有几处细节没有展开：信号的可选字段（order_type、time_in_force 等）、日志里带 [TRADE] 的消息会在界面上高亮、盘前/盘后信号如何转成挂单。另外这份文件有几处说法不准，请以本教程为准：把 init 标成「推荐」，实际必须写，并且要带 stock_codes, init_data 两个参数；写 current_time 支持「YYYYMMDDHHMMSS」连写，实际会抛 ValueError，请传 khGet(data, "date_num") 或 khGet(data, "datetime_str")；信号的 volume 没写单位，单位是股。这些在 3.1 框架介绍和 3.2 策略工具箱里讲得更细；需要时可以把那两篇的相关段落一起贴给 AI。