Chan Structure Workstation · 缠论工作站

English · 简体中文

A deterministic, dependency-free Chan-theory (缠论) structure engine + multi-market trading workstation. Parse any OHLC series into fractals → strokes → segments → pivots → divergence → 1st/2nd/3rd class buy-sell points, see exactly where each concept lives on the chart, and run the same engine over A-shares, HK, US stocks and crypto.

Why this exists

Chan theory (缠中说禅 / "Chan Zhong Shuo Chan") is one of the most influential price-structure methodologies in the Chinese-speaking trading world — and one of the worst served by open-source tooling. Existing projects are either black-box screen-recorders, closed indicator packs, or one-off notebooks that break on the next data feed.

This project is the opposite: a small, readable, deterministic engine (≈900 lines, zero runtime dependencies) plus a full workstation around it.

Features

1. Structure engine (server/lib/chan.js)

• Inclusion handling (K-line merging) → fractals → strokes (笔) with the strict ≥5-merged-bar rule → segments (线段) → pivots (中枢, ZG/ZD, 9-stroke upgrade flag)
• Trend classification (trend / consolidation from pivot succession)
• Divergence (背驰) by comparing MACD histogram area + DIF extremes of same-direction moves (segment-level and stroke-level)
• Signals: 1B/2B/3B and 1S/2S/3S with the exact geometric conditions (new extreme + weaker momentum; pullback that does not break the prior low; pullback that does not re-enter the pivot)
• Multi-level suite (区间套): run every level from 1m to 1d and detect cross-level resonance
• Signal backtest: every buy/sell point type gets a hit rate, average forward return, profit factor and excess over a random-hold baseline — with an explicit small-sample warning
• Deterministic: same bars in → same structures out (covered by tests)

const { analyze } = require('./server/lib/chan');

const res = analyze(bars, { period: 'day' });
res.trend;      // { type: '上涨趋势', sub: '两个中枢不重叠且依次抬高' }
res.pivots;     // [{ zg, zd, i0, i1, count, upgraded, … }]
res.beichi;     // [{ kind: '段背驰', dir: -1, areaRatio: 0.55, … }]
res.signals;    // [{ type: '1B', price, barIdx, note, … }]
res.summary;    // human-readable narrative built from the actual numbers

Honest simplifications (documented in code and in the UI): segments use the 3-stroke fractal approximation rather than the full feature-sequence gap handling; pivots are stroke-level; divergence is numeric (area-ratio thresholds 0.92 / 0.85). See docs/MOBILE.md · docs/ARCHITECTURE.md.

2. Four markets, free data, graceful degradation

No API keys, no paid vendors; per-request timeout + retry + dedup + TTL cache. Details and ToS notes: docs/DATA_SOURCES.md.

3. Teaching annotations — theory → chart, one click

Every concept in the theory library has an "annotate it on the chart →" action. The chart dims everything else and draws exactly the structure the concept describes — with real dates, prices and MACD areas from the current chart.

3.5 Timing lab (算卦页新增)

Seven independent timing methods run side by side — 四柱·节气五行 / 梅花易数 / 六爻纳甲 / 建除十二神 / 日历周期因子 / 紫微斗数·流日 / 奇门遁甲·时家 — each returning a 0–100 "顺逆分" with readable reasons, plus a weighted composite, an agreement/spread read-out, and a per-method historical validation: for the selected symbol we recompute the score for the last N sessions and correlate it with next-session returns.

The verdict is deliberately blunt: on the shipped sample it usually says "no significant edge — use it as a discipline tool, not a signal source." 紫微斗数流日盘（十二宫＋十四主星＋四化）与奇门遁甲时家盘（阴阳遁·局数·三奇六仪·九星·八门·八神）都按同一标准接入：先排盘、再打分、最后必须过 /api/timing/validate 的逐日回测。方法卡（理论页 → 择时方法）对每一法都写明局限。

4. Trading radar, live refresh, editable watchlist

• Cross-market scan sorted by "signal freshness × type weight"
• Global live mode: quotes every 10s, structure every 20s, radar every 30s
• Add/remove symbols per market (search autocomplete); persisted to data/watchlist.json

4.4 108-lesson index + lore collection（108课全表 · 言论集）

• 108 课全表: all 108 lessons with number, theme (14 study-route groups), title only where verifiable from public indexes (50), and a one-line gist (24); unverified titles are left blank on purpose — no invented titles. Served by /api/chan-lessons.
• 言论集: 22 curated entries from 天涯论坛 / 新浪博客, each with source, era, kind, takeaway and the concept it maps to (e.g. "同一级别买点买入就在同一级别卖点卖出" → 级别). Clearly labelled as community paraphrase, not verbatim quotes: /api/chan-lore.

4.5 Metaphysics knowledge base (命理知识库)

A first-class module (not a footnote): 天干地支/四柱 · 紫微斗数 · 奇门遁甲 · 梅花易数 · 六爻纳甲, each with principle, the exact rules this codebase implements, where to look in the UI, the module/API/test file, and its documented pitfalls — plus a 14-book bibliography (缠论 / 干支 / 紫微 / 奇门 / 卦象 / 六爻) used purely as an index.

4.6 1-on-1 guided walkthrough

Every teaching annotation is now a stepper: step 1 lights up a, step 2 adds the pivot, step 3 adds b, then reference lines, then key points — with the matching sentence highlighted below the chart. This is the "teach me how to read my chart" mode rather than a wall of text.

5. Reading room (theory library) — quantified

40 concepts (operational definition, original meaning, recognition steps, common mistakes, where to look on this chart) · 14 "where is it?" Q&A · 108-lesson guide grouped into 14 themes · 5 practical workflows · ≈45,600 characters of original digest in this repo, plus a bibliography (the 780-page annotated edition, the 6-volume collection, the complete-works edition) and honest provenance notes. The theory page shows these counts as a live stats strip.

See docs/COMPETITIVE.md for the GitHub landscape (czsc 6.5k★, chan.py 2.3k★, chanlun-pro 1.1k★, and the 8k★ Zi Wei Dou Shu engine we benchmarked against) and exactly which gaps this project fills.

6. I Ching timing module (算卦择时)

Ganzhi (干支) calendar computed astronomically (24 solar terms from apparent solar longitude), Plum Blossom (梅花易数) casting seeded by symbol hash + live price bucket + time bucket + draw index, six-line Na Jia board (六亲/世应/六神/旬空), twelve-hour body-use analysis. Deterministic and reproducible; entertainment only, explicitly not investment advice.

7. Desktop + mobile

• Desktop: 6 pages, dark/light themes, canvas chart with wheel zoom / drag pan, deep-linkable (?m=A&c=600519&p=day&hl=a_A_b#structure)
• Mobile: /m/ with iOS and Android skins (?skin=ios / ?skin=android), touch chart (drag / pinch), bottom tab bar, safe-area handling, installable as a PWA

Quickstart

git clone https://github.com/JustinGongjj/chan-structure-workstation.git
cd chan-structure-workstation
npm start                 # → http://localhost:8931（桌面版）/ http://localhost:8931/m/（手机版）
# or: PORT=8931 node server/index.js
# or: ./start.sh

Requirements: Node.js ≥ 18. No npm install needed — the runtime has zero dependencies.

Docker

docker build -t chan-station .
docker run -p 8931:8931 -v "$PWD/data:/app/data" chan-station
# open http://localhost:8931  (mobile UI at /m/)

# 在线版：
#   电脑版  https://dsh-qzmkvbrntwlsdhfa.apps.gai.cn/
#   手机版  https://dsh-qzmkvbrntwlsdhfa.apps.gai.cn/m/   （iOS / Android 双皮肤，可"添加到主屏幕"）
#   下载    https://dsh-qzmkvbrntwlsdhfa.apps.gai.cn/downloads/

One-click deploy

• Hugging Face Space (Docker SDK): see space/ — duplicate it, port 8931
• Any VPS / Fly.io / Railway: docker run or node server/index.js behind HTTPS (required for PWA install)

缠关 · 108（独立闯关小游戏）

/game/ 是一个可以单独玩、单独测的小游戏：把 108 课变成 108 关，每关用实时行情生成一道题。

• 108 关 → 14 章（沿用 108 课的主题分组），难度四档：青铜 / 白银 / 黄金 / 王者。
• 答案不下发：出题只给截断前的 K 线 + 一张 HMAC token，判分在服务端重算。
• 进度存本地：星级、平均分、连击；关卡按顺序解锁。
• 设计细节见 docs/GAME.md。

手绘线 + AI 复核

在结构图上自己画线，然后让规则引擎把它和缠论结构对齐检查：

• 线按 市场:代码:周期 存在服务端（data/drawings.json，原子写），换设备/换浏览器都在。
• 点线可选中，Delete 删除；「清空」整表清掉；画完自动退出画线模式（手机上不会"停不下来"）。
• AI 复核（POST /api/drawings/verify）点一下直接弹窗（电脑端居中弹窗，手机端底部弹层）， 给出 0–100 一致度 + 逐条结论 + 改进步骤，可「重新复核」或 Esc/✕ 关闭。 引擎是确定性的规则层（server/lib/drawing.js，10 个单测），不是大模型猜。 每条结论都带可核对数值，例如"起点离最近的笔端点有 8 根、5.47% 的价格差"。 要接 LLM 做自然语言点评，只需把 findings 转成 prompt（当前不联网，保持可复现）。

API

All responses are { ok: true, … }; failures are { ok: false, error } with a 4xx/5xx status.

Testing

五层门禁，一条命令全跑：npm run check:all

npm test              # 只需单元测试（无网络）
npm run check:all     # 全量：单测 + 接口 + UI + 弹层 + 交互（需本机 8931 已在跑）

UI 五条用 chrome-headless-shell + CDP over WebSocket（Node 22 内置 WebSocket）， 加 --shots /tmp/out 可落截图。它们不是"跑通就行"，而是逐项断言可复现的症状—— 手机滚不动、弹层透明、标题零宽、算卦不换卦、切市场白屏都是这样被抓出来的。

中枢（画对了才算缠论）

中枢是缠论的骨架，之前实现有两处不符合定义，已修：

验证方式（不依赖浏览器）：

npm run check:pivot                    # ASCII 画图 + 6 项几何断言，六个市场逐个跑
node scripts/pivotviz.js USF ES day    # 指定市场/标的/周期

pivotviz 会打印一张文本 K 线图（· K 线、/\ 笔、= 中枢上下沿、░ 中枢内部）， 并断言：区间有效 / 每笔与区间相交 / 延伸笔终点在内 / 离开笔终点出界 / 进入笔反向 / 相邻中枢已合并 / 段序不倒置。 六个市场（A股、美股、港股、加密、国内期货、美期货）当前全部通过。

商品板块页

#sectors 页把 88 个期货品种按产业链分 8 组，一屏看清某条链的全貌：

每个品种卡片显示实时价与涨跌幅，点卡片直接跳到结构分析（自动带标的），再在图上画线。 API：GET /api/sectors（目录）、GET /api/sector?id=precious（板块快照）。

市场覆盖（实测可用品种数）

商品搜索：输入中文商品名直接命中多市场合约，例如

数据可靠性措施（都是实测踩出来的）：

1. 国内期货快照僵死：新浪 RB0 实时快照返回的是 2024-07-17 的值，与 K 线（3030）差 400 点。 现在国内期货报价统一用日线最新收盘重算，并在代码里注明原因。
2. 外盘残档：6A/6B/DX/PL/PA 等在新浪只有 2019 年的 12–13 根残档。 加了新鲜度校验（<60 根 或 最后一天 >90 天前 → 明确报错"该品种数据陈旧"）， 而不是给用户一张空图。
3. 贵金属交叉校验：接入 Gold-API（免费无 key）取 XAU/XAG 现货， 与 GC/SI 期货价对比，偏离 >3% 标记 stale。

可选 API Key（增强源）

本站默认零账号可用。若想再加一层保险，可申请免费 key 填进 .env.local：

echo 'TWELVEDATA_KEY=你的key' >> .env.local    # 重启服务生效

完整指南（含申请难度、额度、直达链接）：docs/API-KEYS.md

key 只在服务端使用，/api/keys 只返回"是否已配置"，永不把 key 下发到前端。 「数据源」页有可视化的配置状态（圆点变绿 = 已生效）。

数据源可达性巡检

npm run check:sources        # 30 个渠道实测，按可用性分级

当前运行时（2026-10-31 实测）的结论：

✅ 可直接用（免 key，17 个）

🔑 需 key / 账号（7 个）：Yahoo Finance（403）、Stooq（403，且有 JS 反爬挑战，不绕过）、Finnhub、Polygon、Twelve Data、Marketstack、FMP（均 401 需 key）。

⬜ 评估过但未接入：BaoStock（TCP 10030 不通）、AKShare（Python 库，上游已直连）、Stooq（JS 人机校验，不绕过）。 详见 docs/REJECTED-SOURCES.md（含复跑命令与替代方案）。

⛔ 域名层不可达（6 个）：

关于 TradingView：即使域名可达，其 scanner/data 接口属于非公开授权接口， 公开接入违反其 ToS。若要图形与数据，正路是用 TradingView Charting Library（免费申请）， 但这会替换掉本站自研的缠论绘图层（笔/中枢/买卖点都在 canvas 上自绘），得不偿失。

国内期货的快照接口常年返回几个月前的僵死数据，所以报价统一用日线最新收盘重算， 这一点在 sources.js 里显式注释，避免以后又被"看起来有数据"骗过去。

样式分层：设计 / 兼容 两份文件

framework7-bundle.min.css   ← 只当组件外观底座（无 F7 JS 运行时）
f7-compat.css               ← 唯一的"框架对抗层"，55 处 !important 全部集中在这里
mobile.css                  ← 本站设计，0 处 !important

npm run check:css 会解析 vendored 的 F7 CSS，找出所有可能命中我们 DOM 的规则， 按选择器特异性判断我们的声明是否真的能覆盖它。已确认为无害的冲突（例如 .page-title{width:100%}） 在脚本里带理由白名单，其余一律失败——所以"下次不小心又踩一条 F7 规则"不会再靠用户截图发现。

移动端体验细节

• 下拉刷新：html 上关掉了原生下拉（防误触整页重载），改成只在顶部、单指、纵向 >12px 时才接管的自绘刷新；松手阈值 64px，带"下拉刷新 / 松手刷新 / 刷新中"三态。
• 触感反馈：切 Tab、起卦、增删自选、toast 用 navigator.vibrate 轻震（不支持的设备静默跳过）。
• 无障碍：toast 为 role=status aria-live=polite；#view 为 role=main；prefers-reduced-motion 下关闭动画。
• 返回键：先关弹层，再回上一个 Tab，最后才是退出。

Covers inclusion-merge invariants, stroke/segment/pivot structural invariants, determinism of the full analysis, signal type validity, divergence sanity, graceful degradation on short data, ganzhi anchors (1949-10-01 甲子日, 2000-01-01 戊午日, 2024-02-10 甲辰日), solar-term counts and 立春 windows, six-line chart invariants, and casting determinism ("different symbol ⇒ different hexagram").

CI runs the same suite on Node 18/20/22: .github/workflows/ci.yml.

Project layout

server/
  index.js            HTTP server, routes, watchlist persistence
  lib/chan.js         Chan engine (merge → fractal → stroke → segment → pivot → signal)
  lib/sources.js      market data adapters + fallback chain + cache
  lib/ganzhi.js       ganzhi calendar, solar terms (astronomical), 建除, 旬空
  lib/divination.js   Plum Blossom casting + six-line board + reading
  lib/gua-data.js     64 hexagrams, 8 palaces, Na Jia tables
web/                  desktop UI (no build step): index.html, css, js/chart.js …
web/m/                mobile UI (iOS / Android skins) + service worker
web/js/highlight.js   shared "concept → chart annotation" builder (desktop + mobile)
test/                 node:test suites
docs/                 architecture, data sources, deploy, roadmap, launch playbook
space/                Hugging Face Space (Docker SDK)

二次复审流程（长期规矩）

每一次功能落地都走同一条流水线，不允许"自己测完就交付"：

1. 作者自测：实现 + 单测 + 把新断言写进 scripts/check:* 的某一层门禁（回归项必须固化成断言，不能只靠手点）。
2. 复核 agent 二次复审：另起一个独立 agent，只读代码、只跑命令、不改仓库，按"正确性 / 边界 / 契约 / 诚实性"四类出报告， 每条附带 file:line、影响、一行修法，并按 blocker / major / minor 分级。
3. 作者处置：blocker 与 major 必须修完并补断言；有意不修的写进报告与 README 的"已知限制"。
4. 全量门禁：npm run check:all 全绿才允许提交；提交信息里写清"本轮复核修了什么"。
5. 留痕：复审报告归档在 docs/reviews/（本轮：docs/reviews/drawing.md），更新日志里记一行。

这条流程本身就是被前几轮"改完没验、用户截图才发现"逼出来的： 滚动锁死、弹层透明、算卦不换卦、切市场白屏，都是二次复审/独立 QA 抓到的，不是自测发现的。

更新日志 / History

按时间倒序。每条都标注了"怎么验证"，避免同一类问题重复踩。

已知限制（明确写在前面，不粉饰）

• 线段用"三笔成段"近似，属于简化实现；背驰用 MACD 面积比的数值阈值（段 0.92 / 笔 0.85），不是原文的递归级别证明。
• 择时验证的结论是直给的：上证 r≈-0.08、BTC r≈+0.125（61.5% 但有多重比较警告）、NVDA r≈+0.07。没有稳定显著优势，当娱乐与观察用。
• 108 课只标注了 50 个可核实的课名，其余按主题聚合；言论集为转述，不含原文版权内容；书目索引不含正文。

Roadmap

• Deterministic engine + tests
• Multi-market adapters with fallback
• Teaching annotations (concept → chart)
• Mobile PWA with iOS / Android skins
• Signal backtest (hit rate / profit factor / edge vs baseline) and the timing-method lab
• 紫微斗数流日盘 + 奇门遁甲时家盘（农历排盘 → 统一打分 → 接入回测）
• English UI (i18n layer) — help wanted
• Python package (pip install chanx) wrapping the same rules with parity tests
• Publish computed structures as a Hugging Face Dataset (chan-structures) for reproducible research
• WebSocket streaming for intraday updates
• Strict feature-sequence segment implementation (gap handling) behind a flag

See docs/ROADMAP.md and docs/LAUNCH_PLAYBOOK.md.

Contributing

Issues, data-source adapters, translations and test cases are all welcome. Start with CONTRIBUTING.md and the good first issue label.

Maintainers of quant frameworks (vectorbt, backtrader, qlib, ccxt, pandas-ta, …) who want a Chan indicator module or data adapter built on this engine: open an issue — the engine is designed to be embedded.

Disclaimer

• Market data comes from third-party public endpoints and may be delayed, incomplete or unavailable. Interfaces change without notice; adapters are intentionally replaceable.
• Chan structure division has implementation-dependent variants. This project documents its own simplifications and does not claim to be the single correct reading.
• The I Ching module is traditional-culture entertainment. Nothing in this repository is investment advice. Trading involves substantial risk.

License

MIT © 2026 Chan Structure Workstation contributors. See LICENSE.