binance-historical 是一个用于下载币安历史K线（candles）的 CLI 工具，支持现货、USDⓈ-M 和 COIN-M 期货，可处理多交易对，输出 JSON 或 CSV。
用途与主要能力：按市场、精确交易对、时间间隔、起止时间和输出目录下载历史K线。未指定衍生品时默认使用现货（Spot）。期货代码为合约标识，如 USDⓈ-M 用 BTCUSDT，COIN-M 用 BTCUSD_PERP；带日期合约需使用其确切交易所符号，不能替换为标的交易对。支持多个交易对（如 --pairs BTCUSDT,ETHUSDT）。默认只下载已收盘K线，仅在需要未完成K线时用 --include-open。日期不带时间按 UTC 午夜处理；--end 为排他端点，便于相邻导出无重复拼接。
使用方式：技能只安装说明而非可执行文件；检出源码目录内用 pnpm install --frozen-lockfile 安装锁定依赖，pnpm run build 构建，并以 node build/index.js 替代命令。目录外用 npm install -g binance-historical 安装可执行文件。可用 binance-historical --version 与 binance-historical describe --json 查看已安装契约（后者是市场、间隔、字段、默认值和退出码的权威来源）；若安装版本缺少 describe，应换用更新版本或当前源码构建。执行时始终加 --non-interactive --json 并指定输出目录，--format 选择文件编码，--json 选择命令报告；价格与成交量保持为十进制字符串。示例：binance-historical download --pair BTCUSDT --interval 1h --start 2024-01-01 --end 2024-02-01 --output ./data --format csv --non-interactive --json。
结果与续传：退出码为 0 且 status 为 success 表示操作完成，应报告输出路径、数量及失败交易对。空结果是有效导出，不代表币安必有该期数据。中断且结果 resumable 为 true 时，保持原市场、符号、日期、格式、输出路径和开收盘策略，重跑同命令并加 --resume；检查点保留原始参考时刻，不会把导出延长到当前时间。下载器自行重试临时网络错误；持续错误时据错误码与消息决定续传、修正符号或报告市场不可用。遇到封禁和检查点损坏应停止。仅在需要替换已有导出时用 --overwrite，且与 --resume 互斥。未完成前应保留 .part 与 .checkpoint.json 文件。