kline-structure-chart

A股 / 港股 / 美股 K 线数学结构识别与风控研究技能，给 Claude Code、Codex 等 AI 助手使用

中文 | English | 项目主页

English TL;DR: An Agent Skill for Claude Code, Codex, Cursor, Gemini CLI and other AI agents. Ask in plain language ("analyze NVDA") and the agent runs deterministic Python on real market data (A-shares, Hong Kong, US) to produce K-line structure, a triple-barrier risk plan, a direction-free 15-day normal volatility range and a no-lookahead backtest, as JSON + PNG + offline HTML. For research only, not investment advice. Full English docs: README.en.md.

kline-structure-chart 是一个符合 Agent Skills 开放规范 的金融量化与 K 线数学结构分析技能包。装进 Claude Code、Codex、Hermes Agent、Cursor、Gemini CLI、OpenCode 等 AI 助手之后，你只需用自然语言提问（例如："帮我看看中际旭创的 K 线结构和支撑压力，账户 50 万"），助手就会自动完成从真实行情拉取 → 确定性数学结构识别 → 三重屏障风控与正常波动范围 → 离线交互看板与高清图生成 → 回复契约校验的完整投研闭环。

中际旭创 300308.SZ 离线交互看板录屏（数据截至 2026-10-15）：拖动时间回放，每个历史截面只用当时数据，白线是之后的真实收盘；再演示图层开关与副图切换。看板是技能原样输出的 HTML，可在项目主页在线打开。

快速了解

它能做什么

• 三市场覆盖：A 股（沪深北个股、ETF、指数）、港股、美股，自动配对大盘基准（沪深300 / 恒生指数 / SPY），先看大盘、再看个股。
• K 线数学结构识别：因果拐点、轨道拟合、主+备选 ABC 浪型与推动 5 浪、8 类标准情景、蜡烛 / 双底双顶 / RSI 背离、SMC（FVG / 订单块 / BOS）、成交分布（Volume Profile）。
• 三重屏障风控计划：入场区、止损、TP1/TP2、移动保本、持仓防守，给了账户净值就按单笔风险比例算股数；大盘极弱时一票否决做多。
• 15 日正常波动范围：以最新收盘价为中心的 50% / 80% 区间，只描述波动幅度、不判断方向，附样本外覆盖率与独立样本数。
• 无前视回测：每个历史决策日只用当日及之前的数据重跑线上同一条流水线；成交胜率附 Wilson 95% 区间与样本量。
• 同源产物：*_result.json（稳定契约）、1920×1160 PNG 结构图、离线交互 HTML 看板与中文 Markdown 报告出自同一份计算结果；lint_response.py 拦截助手回复里编造的价格和概率话术。

能带来什么

• 不让大模型看图猜价：所有点位都由 Python 从真实 OHLCV 序列计算，助手只转述 JSON 里的数字。
• 可复现、可审计：同一份数据、同一截止日得到同样的结果；--days 只改显示根数，不改任何结论；离线测试全部使用录制下来的真实行情回放。
• 不夸大：不输出上涨概率，规则分不叫胜率；取不到行情就以 [DATA_UNAVAILABLE] 退出，不估算、不补数。
• 一句话驱动：用自然语言提问，助手自动查代码、跑脚本、按回复契约组织答案。

30 秒上手

macOS / Linux 一行安装（会自动注册到已安装的 Claude Code、Codex 等助手）：

curl -fsSL https://raw.githubusercontent.com/xiongcp/stock-skill/main/install.sh | bash

装好后新开一个会话，问"帮我分析 300308.SZ"或"看看腾讯 00700.HK 的 K 线结构，带回测"。Windows、Claude Code 插件市场、npx skills、让 AI 助手代装和不用 uv 的方式见第 3 节，直接用命令行见第 5 节。

仅供研究与学习，不构成投资建议，也不会替你下单。

0. 我们究竟解决什么问题？（为什么不能让大模型直接看图猜 K 线）

在传统的大模型看图或直接对话问股中，普遍存在四大致命痛点：

1. 视觉幻觉与价格编造：让多模态模型（VLM）直接看 K 线截图识别形态或支撑阻力位，极易读错坐标轴、编造不存在的价格或画错趋势线。
2. 前视偏差（Lookahead Bias）与事后诸葛亮：传统 ZigZag 拐点、双底/双顶、ABC 浪型往往在事后用未来 K 线重绘历史极值，回测看似完美，实盘完全无法复现。
3. 把主观打分伪装成"上涨概率"：许多工具将几个指标的简单加权分直接宣称为"上涨概率 75%"，既无历史样本支撑，也未经样本外校准检验。
4. 忽视大盘环境与微观交易制度：在大盘空头崩跌时仍激进推荐个股突破追高；或忽略 A 股 T+1、科创/创业板及双创 ETF ±20% 涨跌幅、港股动态价位表与双边印花税、美股盘前盘后与 VIX 波动放大等真实交易约束。

为此，kline-structure-chart 建立了六大工程铁律（Hard Invariants）与确定性结构 + 风控两层架构：

flowchart TD
    A["用户自然语言提问 / CLI 调用<br/>（如：分析中际旭创 / 00700.HK / NVDA.US）"] --> B["0. 名称解析与多市场真实行情网关<br/>resolve_symbol.py · data_gateway.py"]
    B --> C["盘中未收盘K线剥离 + 点位时间前复权(PIT) + 大盘基准配对<br/>market_rules.py（A股沪深300 / 港股恒指 / 美股SPY）"]
    C --> D["确定性数学结构与多周期规则层<br/>单边因果NW核平滑 · 因果ZigZag · 轨道候选打分拟合<br/>主+备选ABC浪型 · 推动5浪硬规则 · 8类标准情景筛选<br/>蜡烛/双底双顶/RSI背离 · SMC(FVG/OB/BOS) · Volume Profile"]
    D --> F["Triple-Barrier 风控与正常波动范围<br/>risk.py · forecast.py · evaluation.py<br/>左右侧入场区/盘中硬止损/+0.90R移动保本/持仓防守/港美做空<br/>鞅中心15日50%&amp;80%区间 + 线上计划逐日无前视回测"]
    D --> G["v6 稳定契约：*_result.json<br/>（contract_v6.py 投影，assets/analysis.schema.json 全量校验）"]
    F --> G
    G --> H1["*_preview.png<br/>1920×1160 高清结构图"]
    G --> H2["*_dashboard.html<br/>离线交互看板（另读 *_chart_data.json）"]
    G --> H3["*_report.md<br/>中文报告"]
    G --> H4["lint_response.py<br/>回复守门"]

核心架构与六大不可变铁律

1. 数据真实性（Data Authenticity）优先于一切：只使用新浪、Yahoo、腾讯实时/录制真实行情或用户提供的本地真实行情文件。取不到行情时立即以 [DATA_UNAVAILABLE] 非零退出（退出码 3），严禁回退、估算、补数或生成任何合成行情。当日未收盘 K 线（按交易所时区与半日市/提前收市规则判定）严格拆出，绝不混入已收盘序列。
2. 100% 算图分离（Compute-Render Separation）：所有均线、指标、拐点、轨道、ABC 浪型、SMC、Volume Profile、三重屏障点位、15 日正常波动范围全部由 Python 从 OHLCV 序列计算一次并写入 JSON；PNG 与 HTML 渲染器只读取同一份计算结果，严禁调用视觉模型看图猜数或调用图像生成模型画 K 线。
3. 先大盘、后个股（Market-First Hierarchy）：分析任何个股或 ETF 前必须同步加载对应市场大盘基准（A 股 000300.SH、港股 HSI.HK、美股 SPY.US），计算大盘状态分与 20 日相对强弱（RS Line）。大盘极弱（状态分 < 35）或缺失基准时，独立风控官自动触发一票否决（verdict.risk_veto = true）。
4. 严格单边因果与零前视泄漏（Zero Lookahead Bias）：核平滑采用单边因果 Nadaraya-Watson；每个波段拐点同时记录极值发生日 day 与反向达标确认日 confirmed_at_day；点位复权（PIT）只消费截至当时已生效的分红送转；回测与历史回放截面按当时截止日重算大盘状态与复权，并经追加 5 倍极端未来价格冲击的因果回放审计验证零泄漏。
5. 跨展示窗口不变性（Cross-Window Invariance）：--days N（60~500）只改变主图展示根数，底层取数固定 760 根、指标在固定 420 根历史上预热、结构在固定 120 根窗口上识别，切换展示天数绝不改变任何指标数值、结构分类或交易点位。
6. 概率与术语边界铁律：规则分（rule_score）是确定性条件加权分，绝不称为"胜率"或"上涨概率"；不输出任何概率、胜率或频率数字，唯一例外是回测成交胜率（附 Wilson 95% 区间与样本量），它只是已发生成交的统计，不是未来上涨概率。

本技能只做规则化技术分析与量化研究验证，不构成任何投资建议，也不会替你下单。

1. 能分析什么（三市场全品种覆盖与真实图例展示）

证券简称、A 股 ST/*ST 风险警示标识和港股每手股数（Board Lot）会自动从腾讯行情快照获取；常见科创/创业板 20% 涨跌幅 ETF、A 股跨境/债券/黄金/货币 T+0 ETF 以及港交所豁免印花税的 ETF/ETP 代码段均支持自动识别。

三市场真实行情生成的高清结构推演图展示

以下三张 1920×1160 结构图全部由本技能脚本基于真实行情自动生成（数据截至 2026-10-15，完整报告、JSON 与离线交互看板见 examples/）：

(1) A 股示例：中际旭创（300308.SZ · 创业板 · 红涨绿跌 · 扩散喇叭形 + 跌破下轨 + 三情景推演 + 15 日正常波动范围）

右上角红框是风控否决：大盘环境评分低于 35，且收盘跌破结构下轨，个股不给做多评级。

(2) 港股示例：腾讯控股（00700.HK · 红涨绿跌 · 破位下行与 C 浪末端反转推演）

(3) 美股示例：英伟达（NVDA.US · 绿涨红跌 · 超跌反弹与破位下行推演）

2. 环境要求

• macOS、Linux 或 Windows（Windows 安装脚本尚未实测，见第 10 节）。
• git，以及 Python ≥ 3.12 + Pillow（Pillow 只用来画 PNG；全部指标、形态、风控与回测计算只用 Python 标准库）。
• uv：推荐，但不是必需。一键安装脚本依赖它；不想装 uv 时按 3.4「不用 uv 的手动安装」用 venv + pip。
• 网络：安装时需要访问 GitHub 与 PyPI；每次分析需要访问新浪、Yahoo、腾讯的行情接口。没有网络的沙箱环境无法使用（会直接报 [DATA_UNAVAILABLE]）。
• 中文字体（画 PNG 用）：macOS 与 Windows 自带；Linux 需要文泉驿或 Noto CJK，安装脚本发现缺字体时会打印对应发行版的安装命令（不会自动 sudo）。

为什么推荐 uv（但不是必需）

技能本身只是一份说明（SKILL.md）加一组 Python 脚本，agent 按 SKILL.md 里的命令运行脚本，所以电脑上必须有能运行这些脚本的 Python 和 Pillow。uv 解决的是"让这件事在任何机器上都一次成功"：

• 自动拿到对的 Python：脚本要求 Python ≥ 3.12，而 macOS 自带的是 3.9、不少 Linux 发行版是 3.10/3.11。uv 会在用户目录下载 Python 3.12，不需要 sudo，也不碰系统 Python。
• 版本锁定、结果可复现：uv sync --frozen 严格按 uv.lock 安装，每台机器得到同一个 Pillow 版本，PNG 渲染一致。
• 不污染系统环境：依赖装在技能目录的 .venv 里；直接 pip install 到系统 Python 在新版 macOS（Homebrew）和 Debian/Ubuntu 上会被 PEP 668（externally-managed-environment）拒绝。

"agent 遇到错误会自己安装"大多数时候成立，但不可靠：agent 可能把依赖装进系统 Python（被拒绝或污染环境）、用了过低的 Python 版本、在禁止联网或禁止写系统目录的沙箱里反复失败，轻量模型尤其容易卡住。所以 SKILL.md 现在写明了确定的兜底路径：有 uv 用 uv run python；没有 uv 就在技能目录建 .venv 并 pip install -r requirements.txt，然后用 .venv/bin/python。scripts/doctor.py 也不再把"没装 uv"判为失败。

3. 安装

3.0 让 AI 助手在对话里帮你安装（最省事）

不想自己敲命令时，把下面这句话直接发给你正在用的 AI 助手（Claude Code、Codex、Gemini CLI、Cursor、OpenCode、Hermes Agent 等能执行命令的助手）：

请按 https://raw.githubusercontent.com/xiongcp/stock-skill/main/INSTALL_FOR_AGENTS.md 的步骤，把 kline-structure-chart 技能安装到你自己的技能目录；需要安装 uv 或其他软件前先问我，完成后把 doctor 自检结果告诉我。

助手会读取 INSTALL_FOR_AGENTS.md：判断自己该装到哪个技能目录 → 检查 git / Python / uv → 有 uv 就运行一键脚本，没有 uv 且你不同意安装时改用 venv + pip → 运行 doctor → 告诉你结果和下一步。指引里写明了安全边界：不用 sudo、不覆盖已有目录、安装任何软件前先征求你的同意、不索要任何账号密码。

助手无法访问网址时，把 INSTALL_FOR_AGENTS.md 的全文复制给它即可。装完后新开一个会话，技能才会被加载。

3.1 一行命令安装

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/xiongcp/stock-skill/main/install.sh | bash

Windows（PowerShell）：

irm https://raw.githubusercontent.com/xiongcp/stock-skill/main/install.ps1 | iex

脚本依次完成：

1. 检查 git 和 uv。缺 uv 时询问是否用官方安装器安装（加 --install-uv 则不询问直接安装）；不安装 uv 时（回答 N，或非交互环境未加 --install-uv）改用本机 Python 3.12+，依次查找 python3.13、python3.12、python3（Windows：py -3.13、py -3.12、python），都低于 3.12 才退出并提示安装 Python 3.12+ 或加 --install-uv。
2. 把代码克隆到 ~/.local/share/stock-skill；已存在时执行 git pull --ff-only，所以重复执行同一条命令就是更新。
3. 执行 uv sync --frozen --python 3.12，按 uv.lock 安装依赖；不用 uv 时改为在技能目录 python -m venv .venv 并 .venv/bin/pip install -r requirements.txt（版本与 uv.lock 一致）。
4. Linux 下检查中文字体。
5. 自动探测已安装的 claude、codex、gemini、cursor-agent、opencode，把技能目录软链到对应的技能目录（见下表）。目标位置已有同名的普通目录时先备份为 *.bak.<时间>。
6. 运行离线快速自检（文档契约与工具测试；不用 uv 时跳过，因为 pytest 不在 requirements.txt 里）和环境自检 doctor（不用 uv 时用 .venv/bin/python 运行），最后打印下一步。

目录约定与 vercel-labs/skills 一致。一个都没探测到时，默认注册到 Claude Code 和 ~/.agents/skills/。

安装完成后新开一个会话，试问"帮我分析 300308.SZ"或"看看中际旭创的 K 线"。

3.2 安装选项

通过管道运行时用 bash -s -- 传参，