一、工具定位与运行方式
该工具用于按几何条件检索历史 K 线形态，并把命中位置标注在 K 线图上，同时统计形态之后若干根 K 线的历史表现。它解决的是“在一段历史里找出符合某种几何结构的 K 线组合”这个问题。
默认使用方式为导入本地 CSV，全程离线，不上传行情数据。在线版是单文件静态页面，打开后用浏览器加载 CSV；Windows 免安装版解压后双击运行，数据同样只保留在本机。两个版本的形态口径、参数与结果字段一致。
Windows 桌面版另提供可选的「在线取数」：登录官网账号后按代码与日期区间直接取日线，不需要自己准备文件。这是按次计额的增值服务，不用时保持 CSV 导入即可，工具不会发起网络请求。
- 输入：本地日线 CSV（默认），或桌面版在线取数得到的日线
- 处理：按选定形态与时间区间逐根扫描，记录命中位置
- 输出：K 线图标注、结果表格与可导出的 CSV
二、快速上手
首次使用建议先用一份小样本跑通流程，再导入完整历史数据。默认的 CSV 路径不涉及账号注册，也不需要联网。工具内置一份合成示例数据，打开即可先跑一次。
- 打开在线版页面，或解压后双击运行桌面版
- 点「选择本地 CSV 文件」或将文件拖入数据区，首行为列名
- 确认日期、开盘、最高、最低、收盘列已正确识别，必要时在「列名映射」中改列
- 选择标的、起止日期、形态库与观察根数 N；需要时展开「阈值参数」调整口径
- 点「开始检索」；切换标的、日期、形态、N 或阈值时也会自动重算
- 点结果行可在图表上定位该形态；滚轮缩放、按住拖动平移、双击复位
- 核对日期与价格无误后，导出结果 CSV 或图表 PNG
三、CSV 字段与格式要求
CSV 首行为列名，每行一根 K 线。必需字段为日期、开盘、最高、最低、收盘（date、open、high、low、close）；成交量为可选字段，缺失或非数字按 0 处理，只影响成交量柱，不参与形态判定。
列名支持常见中英文写法与别名，例如 日期/交易日期/date、开盘/开盘价/open、最高/high、最低/low、收盘/close、成交量/vol、代码/标的/symbol；载入后可在「列名映射」中手动改列。逗号、制表符、分号分隔均可自动识别，文件编码建议 UTF-8。
日期支持 2024-06-03、2024/6/3、2024.6.3、2024年6月3日、20240603；价格支持千分位逗号。每根 K 线的日期、开盘、最高、最低、收盘五个字段缺一不可。
date,open,high,low,close,volume,symbol
2024-06-03,100.00,101.20,99.50,100.80,1234567,DEMO-A
2024-06-04,100.80,102.10,100.20,101.90,1456000,DEMO-A- 开、高、低、收任一为空或非数字的行会被跳过
- 价格关系异常（最高低于开盘或收盘、最低高于开盘或收盘、最高低于最低）的行会被跳过
- 同一标的同一日期重复时，保留文件中靠后的一条
- 每个标的按日期升序排列；少于 3 根的标的不参与检索
- 载入后界面会提示跳过的行数，便于核对源文件
标的列为可选：没有该列时全部数据视为单一标的「全部数据」；有该列时按标的拆分，可下拉切换。Excel 导出的 GBK 文件如出现乱码，请先另存为 UTF-8 CSV。
四、在线取数（仅 Windows 桌面版）
手上没有数据文件时，桌面版可以直接用新湖数据服务取日线，省去下载与整理。这是按次计额的增值服务，需要登录官网账号；不想登录时，第三节的 CSV 方式一直可用，且完全离线。在线版的「在线取数」按钮为置灰状态，只提示仅桌面版支持，网页版请使用本地 CSV。
登录：左侧「数据来源」切到「在线取数」→ 点「扫码登录」，工具会生成一枚设备授权码并打开浏览器（也可点「复制授权码」后手动打开 diyky.com/device）→ 在浏览器里用微信登录官网账号，输入授权码并确认 → 回到工具，登录状态自动更新，显示账号与剩余额度。工具不保存密码，本机只保留一枚加密后的登录凭证用于下次自动登录，凭证过期会尝试续期，失败则提示重新登录；换电脑或重装系统需要重新登录。
取数：输入 6 位股票代码（000001 或带后缀的 000001.SZ，也支持 .SH / .BJ）→ 选择起止日期与复权口径（前复权 / 不复权 / 后复权，默认前复权）→ 点「取数并分析」，数据成功后直接进入图表并自动检索。
| 常见提示 | 含义与处理 |
|---|---|
| 请先登录官网账号后再取数 | 尚未登录或登录已失效，点「扫码登录」重新授权 |
| 本月免费额度已用完 | 免费额度用尽，下月重置或到官网购买；也可改回 CSV 导入 |
| 今日取数次数已达上限 | 单日次数保护，次日再试 |
| 股票代码无法识别 / 没有找到这个代码 | 检查是否为 6 位数字或带正确后缀 |
| 该区间只有 N 根有效交易日，不足 20 根 | 放宽起止日期，本次不扣额度 |
| 该区间没有可用数据 | 换一个日期区间：可能尚未上市、长期停牌或超出数据范围 |
| 查询区间过长 | 缩短到 10 年以内且不超过 5000 根 |
| 数据源暂时繁忙 / 数据暂未就绪 / 响应超时 | 服务侧临时问题，本次不扣额度，稍后重试 |
| 无法连接服务器 | 检查本机网络后重试；离线使用请切回「导入本地 CSV」 |
- 单次区间最长 10 年，且最多 5000 根日线，超出会提示缩短区间
- 区间内有效交易日不足 20 根时会明确提示根数并建议放宽日期，不画空图，这种情况不扣额度
- 每次成功取数计 1 次额度；失败、无数据、服务异常不扣额度
- 免费额度每月赠送，用完后可在官网购买；同时有单日次数上限，用于防止程序反复拉取
- 同一标的、同一区间、同一口径下，接口取数与把这批数据存成 CSV 再导入，形态命中数一致；前复权与不复权在除权日前后必然存在差异，对比时请保持口径一致
- 一个账号最多绑定 5 台设备；「退出登录」会同时通知服务器作废本机凭证并清除本机登录状态
切回「导入本地 CSV」后，工具不会再发起任何网络请求；只有点「扫码登录」或「取数并分析」时才会联网。除在线取数外，CSV 导入与检索全程离线。
五、支持的形态与判定口径
v0.1.2 的形态库包含 6 大类 10 种：十字星、锤子线 / 上吊线、看涨 / 看跌吞没、启明星 / 黄昏星、双底 / 双顶、向上 / 向下跳空缺口。下表为可复现的规则口径（括号内为默认阈值），阈值可在第六节调整。形态名称只描述几何关系，不代表因果规律，也不构成操作提示。
| 形态 | 判定口径（默认阈值） |
|---|---|
| 十字星 | 实体 ≤ 振幅 6%；上下影各 ≥ 振幅 15%；振幅 ≥ 收盘价 0.7% |
| 锤子线 / 上吊线 | 实体 ≤ 振幅 35%；下影 ≥ max(实体 × 2, 振幅 50%)；上影 ≤ 振幅 12%；振幅 ≥ 收盘价 0.4%。前 10 根趋势向下为锤子线，向上为上吊线，趋势不明标「锤子线（趋势中性）」 |
| 看涨 / 看跌吞没 | 前一根为反向实体且实体 ≥ 其收盘价 0.4%；后一根实体 > 前实体 × 1.25，且开盘、收盘完全覆盖前一根实体（看涨为阳包阴，看跌为阴包阳） |
| 启明星 / 黄昏星 | 三根组合：首根实体 ≥ 其收盘价 0.8%；中间实体 ≤ 首根实体 40%；末根实体 ≥ 首根实体 50%；末根收盘位于首根实体中部之上（启明星）或之下（黄昏星） |
| 双底 / 双顶 | ±3 根内的局部低点（双底）或局部高点（双顶）出现两次；两点价差 ≤ 较小值的 2.5%；中间颈线幅度 ≥ 较小值的 3%；两点间隔 6–80 根；双底前需有 ≥3% 的回落，双顶前需有 ≥3% 的回升 |
| 跳空缺口 | 当日最低 > 前日最高（向上）或当日最高 < 前日最低（向下），缺口幅度 ≥ 0.25% |
阈值与位置条件会直接影响命中数量；对比不同区间时请保持同一组参数，不要沿用旧结果。
六、阈值参数
界面「阈值参数」中可直接修改以下 6 项，修改后自动重新检索；「恢复默认阈值」可一键还原。
| 参数 | 默认值 | 可调范围 | 作用 |
|---|---|---|---|
| 十字星 实体 ≤ 振幅 | 6% | 1–20% | 越小越严格，十字星命中越少 |
| 锤子线 实体 ≤ 振幅 | 35% | 10–60% | 越小越严格 |
| 吞没实体放大 ≥ | 1.25 倍 | 1–3 倍 | 越大越严格 |
| 双底 / 双顶 价差 ≤ | 2.5% | 0.5–8% | 越小越严格 |
| 双底 / 双顶 颈线 ≥ | 3% | 1–10% | 越大越严格 |
| 跳空缺口 ≥ | 0.25% | 0.05–3% | 越大越严格 |
其余口径参数在 v0.1.2 中固定：十字星上下影 ≥ 振幅 15%、振幅 ≥ 收盘价 0.7%；锤子线下影 ≥ 实体 2 倍且 ≥ 振幅 50%、上影 ≤ 振幅 12%、振幅 ≥ 收盘价 0.4%；吞没前一根实体 ≥ 收盘价 0.4%；星线首根实体 ≥ 收盘价 0.8%；双底 / 双顶极点间隔 6–80 根、前置回落 / 回升 3%、局部极值窗口 ±3 根。
七、扫描参数与区间
检索条件决定扫描范围与统计口径，一次检索只用一组参数。结果应与参数一起保存，便于他人复现。
- 标的：CSV 无标的列时全部数据视为单一标的「全部数据」；有标的列时按标的拆分，可下拉切换
- 起始日期 / 结束日期：按形态完成日过滤，首尾均含边界；双底 / 双顶以第二个极点所在日期为准
- 形态库：全部形态，或只勾选部分形态
- 观察根数 N：形态之后统计的根数，可选 3 / 5 / 10，默认 5
- 阈值参数：见第六节，6 项可调，其余固定
区间外的数据仍作为前置趋势与统计参考，但不会出现在结果里。切换标的、日期、形态、N 或阈值会立即重算。
八、结果字段含义
结果表一行对应一次形态命中。字段描述的都是历史样本中已发生的数据，不含任何预测值。
| 字段 | 含义 |
|---|---|
| 日期 | 形态完成日 |
| 形态 / 类别 | 命中的形态名称（如 看涨吞没、双底）与所属类别 |
| 所处位置 | 近 60 根价格区间的位置（低位区 / 中位区 / 高位区）与前 10 根趋势（上升 / 下降 / 横盘震荡） |
| 形态日收盘 | 该日收盘价，作为后续统计基准 |
| 其后 N 根 | 收涨根数 / 样本根数，以及终值变化、最大上探、最大回撤；不足 N 根时标注「不足 N 根」 |
| 备注 | 规则触发说明，例如缺口幅度、覆盖关系 |
| 标的 | 数据所属标的 |
统计以形态日收盘 C0 为基准，取其后第 1…N 根：收涨根数为收盘高于 C0 的根数；终值变化为第 N 根收盘相对 C0 的变化；最大上探为期间最高价相对 C0 的最大上行幅度；最大回撤为期间最低价相对 C0 的最大下行幅度。以上均为历史样本描述，不代表未来表现。
九、导出方式
结果 CSV：导出当前检索条件下的命中记录，字段为 日期、形态、类别、所处位置、形态日收盘、其后 N 根、终值变化%、收涨根数、最大上探%、最大回撤%、备注、标的。文件为 UTF-8（带 BOM），Excel 可直接打开；不足 N 根的样本「终值变化%」留空。文件名形如「新湖K线形态识别_结果_DEMO-A_2024-06-03_2026-04-03.csv」。
图表 PNG：导出当前图表视野（缩放 / 平移后的可见区间）的 K 线、成交量、均线与形态标注，顶部附标题、数据区间、命中数与 N，按页面尺寸 2 倍输出。文件名形如「新湖K线形态识别_图表_DEMO-A_12个形态.png」。
- 桌面版导出文件写入「下载\新湖K线形态识别\」目录；在线版走浏览器默认下载目录
- 结果 CSV 不含原始 K 线全量数据，只含当前一次检索的命中记录，改条件后需重新导出
- 图表 PNG 不包含结果表格；视野外的形态不会出现在图片中，需要完整区间请先双击复位
十、边界说明
工具只做历史形态检索与呈现。它不荐股、不预测涨跌、不提供买卖信号、不承诺收益，也不构成买卖建议。形态命中的历史统计只描述过去样本，不保证未来重现。
示例数据仅用于演示格式与流程，不代表任何真实标的。使用者应自行确认数据来源与授权范围，并对自己的使用行为负责。
本文档已与 v0.1.2 实现逐项核对（形态口径、可调阈值、扫描参数、结果字段与导出口径）；后续版本如有调整，以工具内说明与更新记录为准。