Wickworks

wickworks

这是一款简单得不能再简单的 OHLC 分析器。你通过 HTTP 把 K 线数据发给它，它就会返回指标和 SMC 对象。产品就这些。没有数据库、队列、状态、主观看法，没有“AI 驱动信号”，也不会诱导你订阅每月 97 美元的 Discord。只有基础数据。

市面上那些带着江湖术士气息的 TA SaaS 都想告诉你什么时候买入。Wickworks 会告诉你订单块位于 1.0832，RSI 为 71.4。“这意味着什么？”——这部分由你的策略来决定，而且策略应该写在你的代码里，而不是被锁在别人的付费墙后面。

它基于 pandas_ta 和 smartmoneyconcepts 构建，封装在 FastAPI 服务中，并通过 370 项测试严格验证：将我们的输出与真实 EURUSD 跳动数据上的闭式解参考值进行对比。如果数学计算出现错误，测试套件会在容器构建前发出警报。

目录

• 包含内容
• 快速开始
• API
  • GET /health
  • GET /metadata
  • POST / — 计算
  • The indicators object
  • 概念
  • 可用指标
  • 请求字段
  • 响应
  • 错误
• MCP
• Agent 集成
• 配置
• 架构
• 开发
• 测试理念
• 许可证

包含内容

类别	基础指标
趋势	SMA/EMA + 另外 15 种移动平均线、斜率、唐奇安通道、一目均衡表
动量	RSI、MACD、随机指标、StochRSI、ADX、MFI、CCI、威廉指标 %R、ROC、MOM、TSI、TRIX、UO、Fisher
波动率	ATR、NATR、布林带、肯特纳通道、挤压
成交量	VWAP（锚定）、VWMA、OBV、AD、ADOSC、CMF、KVO
SMC	订单块、公允价值缺口、BOS/CHoCH、摆动结构、支撑/阻力位、流动性、回撤、交易时段、上一周期高点/低点
摘要	仓位、斜率、动量、成交量状态、近期区间——基于原始序列预先计算的投影

所有 JSON 字段名称均采用 camelCase。输出可安全处理 NaN——NaN 会转换为 null，绝不会输出会导致下游解析器崩溃的字面量 NaN。NumPy/Pandas 标量和数组都能正确序列化（不会泄漏 numpy.float64(...)）。K 线使用 UTC，计算使用 UTC，容器运行于 TZ=UTC——时区问题由你负责，与我们无关。

快速开始

docker run --rm -p 8000:8000 psyb0t/wickworks:latest

就这样。服务会在 :8000 监听。

docker compose

services:
  wickworks:
    image: psyb0t/wickworks:latest
    ports: ["8000:8000"]
    environment:
      LOG_LEVEL: INFO
      MAX_BARS: "5000"
      MIN_BARS: "50"

本地开发容器

make run         # build the dev image and run uvicorn on :8000

API

三个端点。全部功能就是这些。

GET /health

curl -s http://localhost:8000/health

{ "ok": true, "version": "0.7.1" }

GET /metadata

返回带版本号的目录，其中包含每个输出路径的标签、描述、单位、类别和解读说明。使用方可以缓存与所报告的 Wickworks 版本对应的目录。

POST / — 计算

发送 OHLC(V) 柱线和你需要的指标。返回且仅返回你请求的内容——响应键与发送的键一致。不会“顺便塞给你 40 个你没要的指标”。

curl -s -X POST http://localhost:8000/ \
  -H 'Content-Type: application/json' \
  -d '{
    "symbol": "EURUSD",
    "timeframe": "H1",
    "bars": [
      { "time": 1700000000, "open": 1.0832, "high": 1.0851, "low": 1.0828, "close": 1.0844, "volume": 1247 },
      ...
    ],
    "indicators": {
      "rsi":         true,
      "rsi21":       { "type": "rsi",   "length": 21 },
      "stochFast":   { "type": "stoch", "k": 5,  "d": 3, "smoothK": 3 },
      "stochSlow":   { "type": "stoch", "k": 21, "d": 7, "smoothK": 5 },
      "macd":        true,
      "orderBlocks": true,
      "fvg":         true
    }
  }'

indicators 对象——核心所在

每个条目都将一个输出名称（键）映射到一个规格：

• true — 使用默认参数运行指标；键同时作为类型。
• { ...params } — 参数对象；若缺少 type，则使用键作为类型。
• { "type": "<name>", ...params } — 使用自定义输出名称运行已知指标。这样就能叠加同一指标的多个实例（例如，使用不同参数的四个随机指标，或不同周期的三个 EMA）。

"indicators": {
  "rsi":    true,
  "rsi21":  { "type": "rsi",   "length": 21 },
  "stochA": { "type": "stoch", "k": 5,  "d": 3 },
  "stochB": { "type": "stoch", "k": 21, "d": 7 }
}

响应包含 rsi、rsi21、stochA、stochB，仅此而已。JSON 对象无法创建重复的输出名称——使用此 API 时，即使你想犯错，也无从下手。

概念

以下输出对应一些常见的交易思路。如果你用过 TradingView 风格的图表工具，大多会对这些概念很熟悉；如果没有，下面的简要说明也足以帮你选出合适的输出。

序列与事件。 序列_输出针对每根输入柱线提供一个值（预热位置为 null）——这是可以绘制成图表的连续数值。事件_输出则是稀疏的对象数组，用于标记刚刚发生的情况（摆动、区块、结构突破）。序列告诉你_状态；事件告诉你_发生了什么。

仅提供基础数据——不提供信号。 Wickworks 不会输出解释性信号（不检测背离、不提供均线交叉事件，也没有“买入／卖出”标签）。所有返回内容要么是原始指标序列，要么是结构事实（某根柱线形成了订单块、价格收盘价突破了该摆动点），要么是基于这些数据预先生成的摘要——绝不会判断你该怎么做。如果你需要背离、MACD 交叉事件、金叉／死叉或其他派生信号，请在自己的使用方中构建这一层。

每个指标都在回答以下四个问题中的一部分：

1. 趋势是什么？ → 移动平均线、ADX、超级趋势、一目均衡表。
2. 动能是否支持趋势？ → RSI、MACD、随机指标、MFI。
3. 还有多少空间？ → ATR、布林带、唐奇安通道、肯特纳通道。
4. 成交量是否支持趋势？ → OBV、CMF、A/D、KVO、VWAP。

TradingView 上找不到的自定义事件构造：

• srLevels 最多使用最新的 500 根柱线；不同触碰之间固定间隔五根柱线，并要求在半个 ATR 范围内至少测试两次。它会返回价格两侧最近的至多三个水平位。
• 订单块和 FVG 展示不同的状态。订单块包含缓解状态和时间信息，使用方可以据此选择自己的时效规则。FVG 输出只包含尚未得到缓解的缺口。
• BOS 与 CHoCH 是由配置的 Smart Money Concepts 摆动算法生成的分类。BOS 表示同方向的结构突破；CHoCH 表示反方向的结构突破。这两个标签都不能证明趋势会延续或反转。

可用指标

需要用于工具／验证器的正式契约？请参阅 schema.json——完整的 JSON Schema Draft 2020-12。以下参考内容是面向读者的版本：分类 + 各指标简介 + 参数表 + 返回形状 + 示例。

大多数输出共用三种序列形状：

• Series — 每根柱线一个值（number | null），与输入 bars 一一对应。预热位置为 null。
• FlagSeries — 每根柱线一个 0/1 整数。
• DirectionSeries — 每根柱线一个 -1/+1 整数（1 = 看涨／做多，-1 = 看跌／做空）。

以下指标按它们向交易者传达的信息分类，而不是按参数形状分类。每个小节开头都会用一段话介绍该类别，然后逐一列出其中的所有指标，并简要说明“它是什么／何时使用”。

---

移动平均线 — 趋势偏向与动态价位

平滑后的价格线。每种类型在响应速度与滞后之间的取舍各不相同——根据你希望曲线对新 K 线反应多快来选择。交易用途：确定主导方向（价格高于/低于 MA = 看涨/看跌偏向），识别市场反复触及的动态支撑位/阻力位，触发交叉信号（快 MA 上穿慢 MA = 趋势转变）。

所有类型都接受单个 length 参数，并返回一个 Series。

type	默认值	输入	说明
ema	21	close	指数 MA — 近期 K 线权重更高。标准趋势过滤器。大多数策略默认使用的趋势 MA。
sma	50	close	简单 MA — 等权平均。较慢、平滑、经典。50/200-SMA 交叉构成“黄金交叉” / “死亡交叉”。
hma	14	close	Hull MA — 滞后低、平滑。在相同周期下，反应速度快于 EMA，噪声却更少。
wma	14	close	加权 MA — 线性权重。滞后程度介于 SMA 和 EMA 之间。
dema	10	close	双重 EMA — 通过校正项减少 EMA 的滞后。
tema	10	close	三重 EMA — 滞后更低，但在盘整行情中更容易出现反复假信号。
t3	10	close	Tillson T3 — 像 SMA 一样平滑，像 EMA 一样快速。输出曲线状，有些交易者认为这样更清晰。
kama	10	close	Kaufman 自适应 MA — 趋势中加快，盘整中放慢。可自动调整。
alma	10	close	Arnaud Legoux MA — 高斯加权。兼顾低噪声与低滞后。
linreg	14	close	线性回归 MA — 对窗口内数据拟合最佳直线，并计算其“当前”值。基于统计方法的平滑。
jma	7	close	Jurik MA — 专有平滑算法，滞后极低。曲线观感出色。
zlma	10	close	零滞后 MA — 对 EMA 进行误差校正，试图完全消除滞后。
rma	10	close	Wilder 平滑 — 用于 RSI/ATR 内部。平滑力度大、速度慢。适合需要指标内部平滑语义的场景。
fwma	10	close	斐波那契加权 MA — 根据斐波那契数列赋予权重。
swma	10	close	对称加权 MA — 窗口中间位置的权重最高。
sinwma	14	close	正弦加权 MA — 使用正弦曲线赋予权重。非常平滑。
trima	10	close	三角 MA — 对 SMA 进行二次平滑。比 SMA 更平滑，但滞后更大。
vwma	10	close + vol	成交量加权 MA — 成交量大的 K 线权重更高。更接近实际交易兴趣所在的位置。

"ema":   true,
"ema50": { "type": "ema", "length": 50 }

vwap — 以交易时段为锚点的 VWAP

成交量加权平均价，在配置的每日、每周或每月锚点重置。与滚动平均值不同，VWAP 从该固定边界开始累积。sessionOffset 会将 UTC 锚点按固定时长偏移。它不会应用交易所日历或夏令时变更。

参数	类型	默认值	描述
anchor	"D" | "W" | "M"	"D"	交易时段重置频率
sessionOffset	string | number	"0s"	交易时段开始时间相对于 UTC 午夜的偏移量。采用 Go 风格（"-5h"、"1h30m"）或秒数。

返回值： Series。

---

动量振荡指标 — 速度与衰竭

衡量价格变化的_速率_，而非价格本身的水平。大多数指标的取值有界（0–100 或以零为中心），因此读数可直接在不同标的和时间框架之间进行比较。交易者的用法：寻找超买／超卖极值（均值回归机会），留意与价格的背离（动量减弱但价格继续延伸 = 反转提示），将零轴／中线交叉作为动量转变的触发信号。

基于周期的单线振荡指标

规格相同：一个 length 参数，返回一个 Series。

type	默认值	输入	范围	含义
rsi	14	close	0–100	相对强弱指数。 经典动量振荡指标。>70 为超买，<30 为超卖。取值有界、研究充分，是下游进行动量与价格分析的典型输入。
mfi	14	h/l/c + vol	0–100	资金流量指数 — 按成交量加权的 RSI。信号更严格：要求价格_和_成交量一致。
willr	14	h/l/c	-100..0	威廉指标 %R。 反向随机指标。-20 ≈ 超买，-80 ≈ 超卖。反转较快。
cci	14	(h+l+c)/3	无界	商品通道指数。 以标准化单位衡量价格相对移动平均线的偏离。±100 是常用阈值。（内部实现 — pandas_ta 有一个已知错误。）
roc	10	close	%	变化率。 N 根 K 线内的百分比变动。最直接的动量数值 — 不做平滑或标准化处理。
mom	10	close	价格单位	绝对动量： close - close.shift(length)。以原始价格单位表示的 ROC。

cci 接受一个额外的 c 参数（大于 0 的数字，默认值为 0.015）— 经典 Lambert 公式中的常数缩放因子。

uo — Ultimate Oscillator

Williams 将短期、中期和长期三个时间周期结合为一条 0–100 的曲线。其设计专门用于减少单周期振荡指标在区间震荡市场中产生的虚假信号。关注背离和 30/70 极值——与 RSI 相同，但内置了多周期确认。

Param	Type	Default	Description
fast	integer ≥ 1	7	短周期
medium	integer ≥ 1	14	中周期
slow	integer ≥ 1	28	长周期

返回： Series（0–100）。

stoch — 随机振荡指标

“收盘价在近期最高价至最低价区间中的什么位置？”返回 %K（原始位置）和 %D（平滑后的 %K）。经典信号：%K 上穿或下穿 %D 是触发信号；两条线均高于 80 表示超买区，低于 20 表示超卖区。与 RSI 类似，但反应更灵敏——信号出现得更频繁，误报也更多。

Param	Type	Default	Description
k	integer ≥ 1	14	原始 %K 的回溯周期
d	integer ≥ 1	3	%D 平滑周期
smoothK	integer ≥ 1	3	%K 平滑周期

返回： { k, d }——每项均为 Series（0–100）。

stochrsi — RSI 随机指标

将随机指标公式应用于 RSI 值，而非价格。其敏感度加倍——信号出现频率远高于普通随机指标，尤其适合捕捉区间震荡行情中的转折点。请搭配趋势过滤器使用；单独使用时交易过于频繁。

Param	Type	Default	Description
length	integer ≥ 1	14	RSI 上随机指标的回溯周期
rsiLength	integer ≥ 1	14	RSI 周期（随机指标的输入）
k	integer ≥ 1	3	%K 平滑周期
d	integer ≥ 1	3	%D 平滑周期

返回： { k, d }——每项均为 Series（0–1，而非 0–100）。

macd — 移动平均收敛发散指标

快速 EMA 与慢速 EMA 之差，再加上对该差值进行平滑处理的信号线。包含三个观察维度：macd 线（原始动量）、signal 线（平滑后的动量）和 hist（macd − signal——大多数交易者实际关注的指标）。hist 穿越零线表示动量方向改变；hist 与价格出现背离表示动量衰竭。

Param	Type	Default	Description
fast	integer ≥ 1	12	快速 EMA
slow	integer ≥ 1	26	慢速 EMA
signal	integer ≥ 1	9	对（fast − slow）进行平滑处理的信号线 EMA

返回： { macd, signal, hist }——每项均为 Series。hist = macd - signal。

tsi / trix / fisher — 带信号线的动量指标

它们返回相同的结构：{ <name>: Series, signal: Series }。关注零轴交叉以及指标值与信号线的交叉，与 MACD 相同。

tsi — 真实强度指数。对价格动量进行双重平滑（基于收盘价）。比 MACD 更平滑，反转更慢，因此假信号更少，但滞后更大。

参数	类型	默认值
fast	integer ≥ 1	13
slow	integer ≥ 1	25
signal	integer ≥ 1	13

trix — 三重平滑指数变动率（ROC）。按设计，它会滤除周期短于其 length 的波动，因此反映的是较长期的动量，适合用于更高时间周期的趋势确认，而非剥头皮交易。

参数	类型	默认值	描述
length	integer ≥ 1	30	三重平滑的 EMA 链长度
signal	integer ≥ 1	9	trix 的信号线 EMA

fisher — Ehlers Fisher 变换。将价格重塑为类似高斯分布的形态，使极值更加突出，也比 RSI 更容易发现转折点。

参数	类型	默认值
length	integer ≥ 1	9
signal	integer ≥ 1	1

---

趋势强度与方向交叉

这些指标不告诉你价格水平，而是告诉你市场当前的趋势强度，或哪一方占据主导。将它们与基于价格的指标搭配使用：趋势强度指标可以告诉你是否应该相信趋势信号。

adx — ADX + DMI

平均方向指数仅衡量趋势强度，不衡量方向。adx 在一方明显占优时上升（无论是哪一方）。+DI 和 -DI 线表示方向性压力分量：+DI > -DI 表示多头占优，反之亦然。经验法则：adx > 25 = 市场适合进行趋势交易，应跟随信号；adx < 20 = 震荡，应避免趋势策略，优先考虑均值回归。

参数	类型	默认值
length	integer ≥ 1	14

返回： { adx, diPlus, diMinus } — 每个值都是 Series。

aroon

比较“距离最高点已有多少根 K 线？”与“距离最低点已有多少根 K 线？”，并将结果归一化到 0–100。up 接近 100 = 近期行情持续创出新高（强劲上升趋势）；down 接近 100 = 近期行情持续创出新低（强劲下降趋势）。oscillator = up - down 是同一 -100..+100 刻度上的净方向读数。

参数	类型	默认值
length	integer ≥ 1	14

返回： { up, down, oscillator } — up/down 的范围为 0–100；oscillator 的范围为 -100..+100。

vortex

两条线分别衡量正向（plus）和负向（minus）真实波幅运动。它是纯粹的趋势反转检测器：plus 上穿 minus = 看涨转变；反之则为看跌转变。这里没有超买或超卖的概念。

参数	类型	默认值
length	integer ≥ 1	14

返回： { plus, minus } — 每个值都是 Series。

---

波动率

衡量价格走势的_幅度_，而非方向。这些指标本身不会生成买入／卖出信号，而是用于设置止损（止损距离不要小于 1–2 ATR）、仓位管理（仓位大小与波动率成反比，使每笔交易承担相同的金额风险），以及市场状态识别（波动率上升 = 突破行情；波动率收缩 = 盘整，留意挤压）。

type	默认值	输入	量纲	说明
atr	14	h/l/c	价格单位	平均真实波幅 — N 根 K 线的平均波幅，以原始价格单位表示。通用的止损距离单位。
natr	14	h/l/c	占价格的百分比	标准化 ATR — ATR 占收盘价的百分比。信息相同，但可用于比较不同价格水平的标的。

---

成交量／资金流

基于成交量的指标线会将价格变动与调用方选择的活跃度序列进行比较。它们可以显示活跃度是否随价格变动而扩大或收缩，但无法识别参与者，也不能证明突破真实有效。

obv 和 ad — 无参数累积指标线

无参数。**返回值：**序列。

• obv — 能量潮。上涨 K 线增加成交量，下跌 K 线减少成交量，并计算累积总量。当 OBV 与价格背离（价格上涨，OBV 持平或下跌）时，说明这波行情缺乏成交量支撑，是警示信号。
• ad — 聚散指标。根据收盘价在 K 线区间内的位置进行加权（收盘价接近最高价 = 主要为买入；收盘价接近最低价 = 主要为卖出）。累积计算。K 线区间较长时，比 OBV 更精确。

cmf — Chaikin 资金流量

将 A/D 公式规范化到滚动窗口内，而不是无限累积。返回 -1..+1：正值 = 窗口内净累积压力，负值 = 派发。可将零线用作市场状态过滤条件 — 仅在 CMF 为正时做多。

参数	类型	默认值
length	integer ≥ 1	20

**返回值：**序列。

adosc — Chaikin A/D 振荡器

基于 A/D 线构建的 MACD 式振荡器 — A/D 线的快速 EMA 减去慢速 EMA。用于检测累积动能（加速）的变化，而不仅仅是方向。穿越零线表示成交量压力的市场状态发生变化。

参数	类型	默认值	说明
fast	integer ≥ 1	3	对 A/D 线计算快速 EMA
slow	integer ≥ 1	10	对 A/D 线计算慢速 EMA

返回值：{ kvo, signal } — 每项均为一个序列。

kvo — Klinger 成交量振荡器

带信号线的成交量力度指标。旨在发现长期反转，同时对短期波动保持敏感 — 双周期结构（快速／慢速）使其既可用作主要信号，也可用作确认叠加指标。需要成交量 K 线。

参数	类型	默认值
fast	integer ≥ 1	34
slow	integer ≥ 1	55
signal	integer ≥ 1	13

返回值：{ kvo, signal } — 每项均为一个序列。

---

布林带与通道 — 动态价格包络线

包围价格走势的线。交易者有三种用途：均值回归边界（触及上轨 = 向上延伸，可能是反向交易的候选；触及下轨 = 向下延伸）、突破触发条件（收盘价_位于_带外 = 波动率市场状态发生变化），以及挤压检测（带宽收窄 = 扩张前的压缩）。以下三种指标采用不同的计算方法（标准差、ATR 或原始区间），但作用相同。

bbands — 布林带

SMA ± N 个标准差。带宽会根据近期波动率自动调整。理论上，经典的 2σ 触及范围包含约 95% 的 K 线；但实际上，在强势趋势中，价格会_沿着带宽运行_，因此不要在趋势中盲目地在触及带宽时反向交易。

参数	类型	默认值	描述
length	integer ≥ 1	20	SMA 窗口
std	number > 0	2.0	标准差带宽

返回： { upper, middle, lower } — 每个值都是一个 Series。

kc — 肯特纳通道

类似布林带，但使用 ATR 而非标准差来计算带宽。反应更平滑，不会对单根异常 K 线做出过于剧烈的反应。常与 bbands 搭配用作挤压检测器（见下方的 squeeze）。

参数	类型	默认值	描述
length	integer ≥ 1	20	EMA / ATR 窗口
scalar	number > 0	2.0	ATR 乘数

返回： { upper, middle, lower } — 每个值都是一个 Series。

donchian — 唐奇安通道

计算过去 N 根 K 线的最高价（high）和最低价（low）的滚动最大值与最小值。这是最初的“海龟交易者”通道：突破上轨 = 创下 N 根 K 线新高 = 趋势做多信号；跌破下轨 = 创下 N 根 K 线新低 = 趋势做空信号。极其简单，却在趋势性品种上出奇有效。

参数	类型	默认值
length	integer ≥ 1	20

返回： { upper, middle, lower } — upper/lower 是滚动最大值/最小值；middle 是二者的中点。

---

趋势跟踪信号

随趋势改变方向的单线趋势过滤器。用途有两种：趋势过滤器（仅在看涨时做多，仅在看跌时做空）和移动止损（趋势反转时，线的值_就是_退出位置）。选择一种即可——它们都是同一思路的不同变体，在滞后与频繁反转之间各有取舍。

supertrend

基于 ATR 的跟踪带。价格在带上方时，带位于下方，充当移动止损支撑线；价格收盘价穿过该带时，带会跳到另一侧并反转方向。默认的 7×3.0 ATR 是经典的“TradingView Supertrend”设置。

参数	类型	默认值	描述
length	integer ≥ 1	7	ATR 周期
multiplier	number > 0	3.0	ATR 乘数

返回： { value, direction, long, short } — value 是跟踪带（Series）；direction 是 DirectionSeries；long/short 仅在对应方向的区段携带带值，其他情况下为 null（便于绘制两条颜色不同的序列）。

psar — 抛物线 SAR

Wilder 的“止损反转”指标：在趋势中，点会加速靠近价格；触及时则翻转到另一侧。它是移动止损指标中最紧密的：点会快速靠近价格。在明确的趋势中表现出色；在震荡行情中则会灾难性地频繁反转。

参数	类型	默认值	描述
af	number > 0	0.02	每根 K 线的加速步长
max	number > 0	0.2	最大加速因子

返回： { long, short, af, reversal } — long/short 是对应区段的 SAR 值（Series，另一侧为 null）；af 是当前加速值（Series）；reversal 是 FlagSeries（1 = 本根 K 线趋势反转）。

chandelierExit

基于 ATR 的移动止损，以回看窗口内的最高价（多头）或最低价（空头）为基准。与 supertrend 相比，它离价格_更远_——止损范围更宽，反转更少。适合波段交易，让趋势有更大的发展空间。

参数	类型	默认值	描述
length	integer ≥ 1	22	最高价/最低价回看周期
atrLength	integer ≥ 1	22	ATR 周期
multiplier	number > 0	2.0	ATR 倍数

返回： { long, short, direction } — long/short 是该方向的退出价位（Series，否则为 null）；direction 是 DirectionSeries。

ichimoku

由五条线组成的日本趋势系统。“云”（位于 spanA 和 spanB 之间，并向未来投射 kijun 根 K 线）是主要参考信号：价格在云上方 = 看涨行情；价格在云内 = 中性/震荡，没有高确信度交易机会；价格在云下方 = 看跌行情。tenkan（快线）和 kijun（慢线）是用于触发交叉信号的中间价线；chikou 是向后平移的收盘价，用于结合历史价格确认信号。

参数	类型	默认值	描述
tenkan	integer ≥ 1	9	转换线——最高价/最低价的快速中间价线
kijun	integer ≥ 1	26	基准线——慢速中间价线
senkou	integer ≥ 1	52	先行带 B 周期

返回： { spanA, spanB, tenkan, kijun, chikou } — 所有值均为价格单位的 Series。spanA/spanB 向前投射 kijun 根 K 线（云位于未来）；chikou 是向后平移 kijun 根 K 线的收盘价。

---

压缩 / 行情状态

squeeze — TTM 挤压指标

检测 布林带是否完全位于肯特纳通道内——也就是说，已实现波动率（BB 宽度）是否低于平均波动率（KC 宽度）。市场正在压缩、蓄势。历史上，挤压释放往往先于大幅定向行情：当 off 触发时（挤压刚在当前 K 线释放），根据 value 指示的方向交易突破。

标志字段构成逐根 K 线的状态机：

• on — 当前 K 线挤压激活（BB 在 KC 内）。市场正在蓄势。
• off — 当前 K 线挤压刚刚释放（BB 脱离 KC）。触发 K 线。
• no — 无挤压（默认状态）。

参数	类型	默认值
bbLength	integer ≥ 1	20
bbStd	number > 0	2.0
kcLength	integer ≥ 1	20
kcScalar	number > 0	1.5

返回： { value, on, off, no } — value 是带符号的动量值（Series，正值 = 挤压期间/之后的看涨动量，负值 = 看跌动量）；on/off/no 是 FlagSeries。

SMC 基本概念

Smart Money Concepts 是一种价格行为框架，根据 OHLCV 形态标记区域、水平位和结构变化。Wickworks 会报告配置的算法检测到的内容。它不会观察机构订单，也无法证明某个水平位会引发价格反应。

以下是你会在下方输出中看到的核心 SMC 概念：

• Order block 是算法检测到的区域，位于符合条件的走势出现前最后一根方向相反的蜡烛附近。一些 SMC 方法会关注之后的回测，但计算过程不会观察订单或预测价格反应。
• Fair Value Gap (FVG) 是一种三根蜡烛的形态，其中第一根和第三根的影线没有重叠。输出会记录检测到的缺口及其缓解状态，但不会预测价格是否会再次回到该处。
• 缓解描述价格之后回到某个区域的情况。Order block 会保留缓解字段。FVG 输出仅包含仍未缓解的缺口。
• Swing high/low — 价格结构中的局部转折点。SMC 趋势识别基于波段序列（HH/HL = 上升趋势，LH/LL = 下降趋势）。
• BOS (Break of Structure) 表示在配置的算法下，价格沿同一方向突破波段水平位。
• CHoCH (Change of Character) 表示在配置的算法下，价格向相反方向突破。这并不能证明趋势发生反转。
• Liquidity — 假定的止损订单聚集区，位于相等高点上方或相等低点下方。价格往往会在反转前“猎取流动性”。

共享对象结构

价格区域（用于 orderBlocks 和 fvg）：

{
  "type": "bullish|bearish",
  "top": 1.0892,
  "bottom": 1.0871,
  "candleIdx": 312,
  "time": 1700123400,
  "originAt": 1700123400,
  "confirmedAt": 1700127000,
  "observedAsOf": 1700200000,
  "distancePct": 0.082
}

字段	类型	描述
type	"bullish" or "bearish"	区域方向。看涨表示支撑；看跌表示阻力。
top	number	区域的价格上界。
bottom	number	区域的价格下界。
candleIdx	integer ≥ 0	已提交 K 线中起始 K 线的从零开始的索引。
time	integer	起始 K 线时间，以 UTC 秒为单位。
originAt	integer	起始 K 线时间，以 UTC 秒为单位。
confirmedAt	integer	首次可以确认该区域的 K 线时间。
observedAsOf	integer	用于构建快照的最后一根已提交 K 线的时间。
distancePct	number	参考边界与当前价格之间的绝对距离除以价格。

orderBlocks 还会返回 mitigatedWickAt、mitigatedCloseAt、 mitigatedWick、mitigatedClose、touchCount 和 touchEvents。FVG 输出仅包含未缓解的缺口，因此不会返回这些字段。

BosChochEvent、SwingLevel、SrLevel、RecentRange：

| 输出 | 对象结构 | | -------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------ | ---------------------- | | bosChoch 事件 | { event: "BOS" | "CHoCH", direction: "bullish" | "bearish", level: number | null, time: integer } | | swingLevels 事件 | { type: "high" | "low", level: number, time: integer } | | srLevels 事件 | { level: number, type: "support" | "resistance", distancePct: number, touches: integer ≥ 2 } | | recentRange | { high: number, low: number, periodHigh: number, periodLow: number } |

SmcEvent（用于 liquidity、previousHighLow、sessions、retracements）：稀疏对象，始终包含 idx 和 time；其余字段按底层 smartmoneyconcepts 库的原样转发（剔除值为 null 的字段以缩小载荷）。

输出

orderBlocks

已提交历史中的订单块，包括影线和收盘价缓解状态、缓解时间及触碰事件。由使用方决定是否仅显示新鲜区域。

• **参数：**无。
• **返回：**OrderBlock 数组，最多 40 个，按 |distancePct| 升序排序（最接近当前价格的在前）。

fvg（别名 fvgs）

未缓解的公允价值缺口。它们采用共享价格区域结构。一些 SMC 方法会关注之后对缺口的回访，但 Wickworks 不会预测缺口是否会被填补或是否会反转。

• **参数：**无。
• **返回：**OrderBlock 结构的对象数组，最多 15 个，按距离升序排序。

bosChoch

由已配置的摆动算法分类为 BOS 或 CHoCH 的近期结构事件。使用方可以将事件序列与自定义趋势定义和确认规则结合使用。

• **参数：**无。
• **返回：**BosChochEvent 数组，最多 10 个，扫描最近 50 根 K 线。

swingLevels

结构分析阶段最近确认的摆动高点和低点。SMC 用于定义趋势的原始输入。适合用于绘制结构，或在此基础上构建你自己的突破检测逻辑。

• 参数： 无。
• 返回： SwingLevel 数组，最多 10 个，扫描最近 50 根 K 线。

srLevels

内部构建的支撑位 / 阻力位。构建时最多使用最近 500 根 K 线，从 7 根 K 线摆动检测器（sw7）获取拐点，要求至少有两次触及且间距至少为 5 根 K 线，并且两条返回水平之间至少间隔 3 个 ATR；返回价格两侧各最多 3 条水平，按接近程度排序。

• 参数： 无。
• 返回： SrLevel 数组，最多 3 条支撑位 + 3 条阻力位。

recentRange

图表区间的简要摘要：最近 20 根 K 线与提交的完整历史数据的对比。可快速了解“当前价格是否接近近期高点 / 低点”。

• 参数： 无。
• 返回： RecentRange 对象（{ high, low, periodHigh, periodLow }）。

liquidity

根据配置的区间容差，从摆动水平中检测相等高点和相等低点簇。一些 SMC 方法将其称为流动性区域，但 Wickworks 不会观测订单，也不会预测流动性扫荡或反转。

参数	类型	默认值	说明
swingLength	integer ≥ 1	10	摆动检测窗口
rangePercent	number > 0	0.01	相等高点 / 相等低点分组的最大距离百分比

返回： SmcEvent 数组。

previousHighLow

来自刚结束的固定 UTC 聚合周期的高点和低点标记。这不是按交易所交易时段计算的。

参数	类型	默认值	说明
timeFrame	string	"1D"	尽管名称沿用旧称，此参数选择的是前一区间的聚合周期，而不是图表的 timeframe。它使用固定的 UTC 对齐周期，不按交易所交易时段计算。规范值：15m、30m、1H、4H、1D、1W、1M。也接受 VoidAlpha 现有的 15min、30min、1h、4h、1d、1w 和 1ME 写法。每周从星期一开始，到星期日结束。

返回： SmcEvent 数组。

sessions

标记固定 UTC 时钟时段内的 K 线。命名时段不使用交易所日历，也不会根据节假日或夏令时进行调整。

参数	类型	默认值	说明
session	string	"London"	命名的 UTC 时段。其他时段请使用 "Custom"。
startTime	"HH:MM" | null	null	"Custom" 时必填的 UTC 开始时间；命名时段不接受此参数。
endTime	"HH:MM" | null	null	"Custom" 时必填的 UTC 结束时间；命名时段不接受此参数。

返回： SmcEvent 数组。

retracements

相对于最近摆动的斐波那契回撤事件。交易者可将其用于活跃波段上的标准斐波那契水平（38.2 / 50 / 61.8），无需手动选择摆动端点，即可自动计算。

参数	类型	默认值	说明
swingLength	integer ≥ 1	10	摆动检测窗口

返回： SmcEvent 数组。

分析摘要

这些输出是最后一根 K 线快照，由一次共享分析流程计算得出。每个请求会运行一次该流程并存储结果；下面的每个输出只会读取缓存结果中的相应部分。请求全部六项的开销与请求一项相同——如果你已经需要其中任意一项，其余几乎不增加开销。

当你想一次性查看图表的结构化“当前状态”，又不想订阅完整的 Series 输出并自行读取最后一个值时，可以使用这些输出。

它们均无需参数。

输出	返回值	交易者用途
price	number — 最后一根 K 线的收盘价（普通标量，不是对象）	用于距离／价位计算的参考价格。
levels	{ ema21, sma50, sma100, sma200, atr, vwap, donchianUpper, donchianLower, donchianMid } — 每项均为 number | null	标准移动平均线 + ATR + VWAP + 唐奇安通道的快照。“当前价位在哪里”的视图。
momentum	{ rsi, mfi, macdHist, macdLine, macdSignal, adx, stochK, stochD } — 每项均为 number | null	一目了然地查看常用振荡指标的动能评分卡。
volume	{ volRatio: number|null, obv: number|null, isSpike: boolean } — 当 volRatio > 2.0 时，isSpike 为 true	快速检查“当前 K 线的成交量是否激增”。volRatio 为当前成交量／近期平均成交量。
position	对象 — 键来自 {ema21, sma50, sma100, sma200, vwap}，每项均为 "above" | "below"。仅显示其移动平均线可计算的键。	偏向图：当前价格高于还是低于各主要参考线？
slope	对象 — 键与 position 相同，每项均为 "up" | "down"。表示最近 10 根 K 线的方向。	各条线本身是在上升还是下降？与 position 结合即可全面判断市场状态。

请求字段

字段	类型	默认值	必填	描述
bars	array of Bar	—	是	按时间顺序排列的 OHLC(V) 柱。len(bars) <= MAX_BARS（默认值为 5000）。
indicators	object	—	是	outputKey → spec 映射。至少包含 1 个条目。
symbol	string	""	否	调用方提供的标的标签，将原样回传。
timeframe	string	""	否	不透明的图表柱间隔标签，例如 H4。Wickworks 会回传此值并将其附加到摘要中，但不会解析它，也不会用它对柱进行分组。计算使用提交的值和时间戳。

柱的结构：

字段	类型	默认值	必填	描述
time	integer	—	是	UTC Unix 秒
open、high、low、close	number	—	是	OHLC 价格
volume	number ≥ 0	必填	是	调用方选择的活动量或成交量序列。Wickworks 不会解释供应商特定的成交量类型。

每个 indicators 条目的 spec 值：

• true — 使用默认参数运行由输出键命名的指标。
• { ...params } — 参数对象。若缺少 type，则使用输出键作为默认值。包含 "type" 可在自定义输出名称下运行已知指标。

响应

{
  "symbol": "EURUSD",
  "timeframe": "H1",
  "candles": 500,

  "rsi": [null, null, 71.4],
  "rsi21": [null, null, 64.2],
  "stochFast": { "k": [78.4], "d": [72.1] },
  "macd": { "macd": [0.00124], "signal": [0.00098], "hist": [0.00026] },
  "orderBlocks": [
    {
      "type": "bullish",
      "top": 1.0892,
      "bottom": 1.0871,
      "candleIdx": 312,
      "time": 1700123400,
      "distancePct": 0.082
    }
  ],
  "fvg": [
    {
      "type": "bearish",
      "top": 1.0945,
      "bottom": 1.0938,
      "candleIdx": 401,
      "time": 1700152800,
      "distancePct": 0.063
    }
  ],
  "bosChoch": [
    {
      "event": "BOS",
      "direction": "bullish",
      "level": 1.0918,
      "time": 1700125200
    }
  ]
}

字段	类型	描述
symbol	string	回传请求字段
timeframe	string	回传请求字段
candles	integer ≥ 0	已处理的柱数
(arbitrary)	不定	indicators 中每个输出键对应一个条目。值的结构由所请求指标的返回值决定。

仅包含你请求的键，以及 symbol、timeframe 和 candles。Series 输出中的预热位置为 null，绝不会是 NaN。

错误

状态	原因
400	bars 为空、indicators 为空、未知的指标 type、指标规格格式错误，或一个或多个请求的指标所需的 bars 数量不足（结构化响应正文 — 见下文）
413	len(bars) > MAX_BARS
422	bar 负载未通过 Pydantic 架构验证（缺少必填字段、类型错误等）
500	内部计算错误（理论上不应发生 — 请使用请求正文提交 issue）

当你请求的指标所需 bars 数量超过已发送数量时（例如，100 个 bars，却请求 sma 的 length=200），请求会在开始处理前被拒绝 — 不会静默返回全为 null 的序列。响应会一次列出所有数据不足的指标，让你可以在一次往返中修正整个调用：

{
  "detail": {
    "error": "insufficient_bars",
    "message": "insufficient bars: have 30, but: slowSma (type=sma) needs 200, longRsi (type=rsi) needs 51",
    "available": 30,
    "deficits": [
      {
        "outputKey": "slowSma",
        "type": "sma",
        "required": 200,
        "available": 30
      },
      { "outputKey": "longRsi", "type": "rsi", "required": 51, "available": 30 }
    ]
  }
}

每个指标的要求根据其参数（length、slow、signal 等）推导 — 并非全局下限。SMC 支持的输出（orderBlocks、fvgs、bosChoch、汇总等）共用 MIN_BARS 基准下限（默认为 50），因为分析流水线需要足够的历史数据。

MCP

POST / 的所有功能也可通过 Model Context Protocol 使用 — wickworks 会在同一进程中于 /mcp 挂载可流式传输的 HTTP MCP 服务，因此 Agent 无需 REST 客户端，即可通过 JSON-RPC 驱动它。它是无状态的（stateless_http=True — 无需 initialize 握手，返回 JSON 响应而非 SSE），其工具与 REST 接口一一对应：

工具	参数	对应接口
health	—	GET /health
list_indicators	—	已注册的指标类型（compute 接受的键）
metadata	—	GET /metadata
compute	bars、indicators、timeframe?、symbol?	POST /（返回相同的封装结构）

# Native remote MCP (Claude Code, Cursor, … — no bridge needed)
claude mcp add --transport http wickworks http://localhost:8000/mcp

# Raw JSON-RPC — stateless, call tools/call directly
curl -s http://localhost:8000/mcp/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"compute","arguments":{
         "bars":[/* ...OHLC... */],"indicators":{"rsi":true}}}}'

MCP 传输层禁用了 DNS 重绑定 Host 检查，因此该端点可在任何主机名／反向代理后正常工作 — 请在代理处设置访问控制，而非在应用中设置。对于只支持本地 stdio 服务的 MCP 客户端，@psyb0t/wickworks OpenClaw 插件可作为轻量级 stdio↔HTTP 桥接，连接到 /mcp/。

Agent 集成

skill 适用于任何能够读取 .agents/skills/ 的 Agent（例如 peen），并且可以原生安装到以下客户端中。

Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install wickworks@psyb0t

Claude Code 会提示你输入 wickworks URL；如果 wickworks 前方的反向代理需要身份验证，也会提示你输入 bearer token — 该 token 会存储在你的操作系统密钥链中。

Codex

codex plugin marketplace add psyb0t/agents
codex plugin add wickworks@psyb0t

通过 marketplace 安装后，该 skill 会以 $wickworks:wickworks 的形式调用。Codex 也会自动识别任何包含 .agents/skills/ 的仓库中的 skill，无需安装 — 在这些仓库中，它会以 $wickworks 的形式调用。

OpenClaw

每次发布时，都会将该 skill 发布到 ClawHub：

openclaw skills install @psyb0t/wickworks

对于使用本地 stdio 的 MCP 客户端，@psyb0t/wickworks 插件可桥接到 wickworks 的 /mcp 端点：

openclaw plugins install clawhub:@psyb0t/wickworks

然后设置 WICKWORKS_URL（如果 wickworks 前方的反向代理需要 token，也请设置 WICKWORKS_TOKEN）。

配置

所有配置均由环境变量驱动。默认值合理，首次运行无需调整。

变量	默认值	描述
LOG_LEVEL	INFO	Python 标准日志级别。
MAX_BARS	5000	拒绝包含超过此数量的 K 线的请求（HTTP 413）。
MIN_BARS	50	SMC 支持的输出（orderBlocks、fvgs、摘要等）的基准下限，也是未在各指标要求表中明确列出的指标的后备要求。序列指标（sma、rsi、macd 等）会根据参数计算自身的最小值。
WORKERS	2	uvicorn 工作进程数。

架构

┌─────────────┐    ┌──────────────────────┐    ┌─────────────────┐
│  Your app   │───▶│  POST /              │───▶│  primitives     │
│  (any lang) │    │  bars in, JSON out   │    │  (camelCase)    │
└─────────────┘    └──────────────────────┘    └─────────────────┘
                              │
                              ▼
                   ┌──────────────────────┐
                   │  pandas_ta + SMC     │
                   │  swing structure     │
                   │  S/R · summaries     │
                   └──────────────────────┘

无状态。无数据库。无队列。无外部调用。输入 K 线，输出 JSON。通过增加副本进行水平扩展。两个副本处理相同输入时，结果具有确定性——每次都是相同的 K 线、相同的字节。测试套件会对此进行验证。

开发

make help          # list all targets
make run           # production-style uvicorn in the dev container
make test          # full suite (unit + docker integration)
make test-unit     # in-process only — fast feedback loop
make test-docker   # docker-in-docker integration tests
make lint          # flake8 + mypy
make format        # isort + black
make check         # lint + tests

包管理 — 供应链防御

Wickworks 使用 uv 的 exclude-newer，拒绝安装在固定日期之后发布的任何包版本。每当包变更相关的 make 目标运行时，日期都会自动更新为今天，因此你不会意外拉取仍处于检测窗口中的新发布恶意版本。

make pkg-add PKG=foo==1.2.3   # bump exclude-newer, then uv add
make pkg-remove PKG=foo       # bump exclude-newer, then uv remove
make pkg-update PKG=foo       # bump exclude-newer, then uv lock --upgrade-package
make pkg-lock                 # refresh the lock using the current exclude-newer cutoff
make pkg-upgrade              # bump exclude-newer + lock --upgrade everything

除非你清楚自己在做什么，否则不要手动编辑 [tool.uv].exclude-newer。更新时同步调整日期的模式正是关键所在。

可选的 ta 扩展

pandas-ta 和 smartmoneyconcepts 固定了相互冲突的传递依赖。Dockerfile 会在不进行依赖解析的情况下安装它们。它们有意未列入 [project.dependencies]。

测试理念

测试套件就是证据。分为三类：

1. 闭式数学差异对比 — 对于每种标准指标（RSI、MACD、ATR、Bollinger、Stochastic、Aroon、CCI、Williams %R、ROC、MOM、OBV、Donchian、VWMA、EMA、SMA、MACD…），测试套件都会用纯 numpy/pandas 从头实现公式，并将最后一根 K 线的值与 wickworks 在真实 EURUSD H1 数据上的输出进行差异对比。容差：rtol=1e-5。如果 pandas_ta 或我们的接线出现偏差，差异对比会在容器发布前发现问题。
2. smc_fast 一致性 — wickworks 提供了 smartmoneyconcepts 的 numba 加速移植版。八项一致性测试证明，快速路径在相同输入下会生成与上游库逐字节一致的结果。
3. 流水线契约测试 — 确定性（相同 K 线 → 相同字节）、追加稳定性（新增 K 线时，因果指标不会改变历史值）、预热区间的 None 数量、指标隔离（同时请求两个指标 == 分别请求）、HTTP 错误路径、成交量字段契约。

运行 make test-unit 执行快速测试循环，目前包含 370 项测试。运行 make test 执行完整的 377 项测试套件，其中包括七项 docker-in-docker 集成测试。

许可证

WTFPL — 详见 LICENSE。想怎么做就怎么做。