KLineLens

对终端用户与开发者而言，KLineLens 强调两件事：数据自主权与策略可扩展性。

• 自选行情 API：通过环境变量切换 Yahoo Finance、TwelveData、Alpaca、Alpha Vantage 等 Provider；免费层可起步，需要更可靠成交量时再接入付费/限额更高的 key——不绑定单一vendor。
• 编码自己的策略：在统一策略接口上实现模块，注册后即可进入终端 UI 与 API 流程；内置 Playbook 与 0DTE 仅作参考实现，社区可贡献新策略与数据源（见 CUSTOM_STRATEGY.md、CONTRIBUTING.md）。

• 全周期结构：1m/5m 日内到 15m/1h/1d 波段；趋势/震荡/区间与置信度。
• 内置 0DTE：状态机驱动标的层交易计划，输出 underlying 级别计划，不依赖期权链报价。
• 可插拔策略：开发者以模块形式扩展，接入同一套分析与 UI。
• 突破确认：三因子降低假突破——收盘确认、RVOL ≥ 1.8、结果相对 ATR 阈值（详见引擎规范）。
• AI 解读（可选）：OpenAI / Google API 生成中英叙事。

市场结构

盘前盘后（Extended Hours）

多语言

完整中文界面与 AI 解读；英文界面与解读；可通过 i18n 扩展更多语言。

同一日极短周期期权计划，由状态机驱动，典型路径：

WAIT → WATCH → ARMED → ENTER → HOLD → TRIM → EXIT

输出为标的层交易计划（价位、目标、止损、阶段），无需接入期权链实时报价即可在 MVP 内使用。

建议：先用 Yahoo 跑通，再换 TwelveData 等改善 volume 相关指标。

MVP 采用 Monorepo + 三层：Web（Next.js）↔ API（FastAPI）↔ Core（纯 Python 分析包）。

┌─────────────────────────────────────────────┐
│              Next.js Frontend                │
│  Chart · Zones · Strategy · Timeline · AI  │
│  i18n · Settings · Watchlist                 │
└────────────────────┬────────────────────────┘
                     │ REST API + SSE
┌────────────────────▼────────────────────────┐
│              FastAPI Backend                │
│  Analysis Engine (Pure Python call)        │
│  Strategy Layer: Playbook | 0DTE | Custom   │
│  Provider Layer: Yahoo | TwelveData | …    │
└─────────────────────────────────────────────┘

目录结构（摘要）

KLineLens/
├── apps/web/          # Next.js
├── apps/api/          # FastAPI，routes / providers / cache
├── packages/core/     # 纯 Python：features, structure, behavior, …
├── docs/
├── infra/             # Docker 等
├── MASTER_SPEC.md
└── README.md

详情页典型请求

1. GET /v1/bars：经 TTL 缓存命中则不下游；未命中则 Provider 拉取 K 线。
2. POST /v1/analyze：Core analyze() 产出结构/行为/时间线/Playbook 等报告，前端渲染面板。

自动刷新

前端约每 60s 再次 POST /analyze；K 线可走缓存，时间线状态在 API 进程内对比前后报告决定是否 emit 事件。

存储要点（摘自架构说明）

• Bars：API 内存 TTL 缓存（如 60s）。
• Timeline state：MVP 内存字典（重启丢失）；远期可 Redis/DB。
• Signal evaluations：apps/api/data/klinelens.db SQLite 持久化。
• 前端 Evidence/Timeline：localStorage 按日 key 缓存。

MVP 验收要点

• 首页输入标的跳转详情页。
• 1m K 线 + 区域/信号展示。
• 行为概率、证据、时间线、Playbook 等面板可见。
• 设置语言全站生效。
• docker compose up 一键启动可用。

详细接口、状态机模式、前端接入与测试见仓库 CUSTOM_STRATEGY.md 与 ENGINE_SPEC.md。

前置：Docker Desktop 已安装并运行。

git clone https://github.com/songzhiyuan98/KLineLens.git
cd KLineLens
cp .env.example .env
# 编辑 .env：PROVIDER、各 API Key、CACHE_TTL、API_PORT、WEB_PORT 等

docker compose up -d --build
docker compose ps

浏览器打开 http://localhost:3000，输入标的（如 TSLA、QQQ、SPY）即可。

docker compose down          # 停止
git pull && docker compose up -d --build   # 更新

本地开发（无 Docker）

# 终端 1
cd apps/api && pip install -r requirements.txt
uvicorn src.main:app --reload --port 8000

# 终端 2
cd apps/web && npm install && npm run dev

环境变量全量说明见仓库 docs/CONFIG.md；部署细节见 docs/DEPLOYMENT.md。

欢迎 PR：Bug、功能、Provider、文档、测试、UI、自定义策略等。建议先查 Issues，较大改动先开 issue 讨论。

• 分支命名：feature/…、fix/…、docs/…
• 提交信息：Conventional Commits（feat:、fix: 等）
• 新增 Provider：实现 MarketDataProvider、注册 factory、更新 .env.example 与 docs/PROVIDER.md、补测试
• 规范：Python type hints 与 docstring；TS 显式类型；避免魔法数字；错误处理与测试覆盖

全文见仓库 CONTRIBUTING.md 与 CLAUDE.md。

• v0.8 — 盘前盘后、0DTE、自定义策略
• v0.7 — 响应式、多语言
• v0.6 — 终端风 UI、AI 解读
• v1.0 — WebSocket 流式、信号回测
• v1.1 — 深色模式、移动端
• v2.0 — 多周期联动、期权链整合

License：MIT — 个人或商业使用均可，需保留许可证声明。

仅供教育与信息参考。工具基于价量做技术分析，不构成投资建议。历史表现不代表未来。请自行研究并自担交易风险。