# TechKit Documentation

**High-performance technical analysis library for financial applications.**

```{image} https://img.shields.io/pypi/v/techkit.svg
:target: https://pypi.org/project/techkit/
:alt: PyPI Version
```

欢迎来到 TechKit 文档！TechKit 是一个现代化的技术分析库，专为金融应用设计，提供高性能、线程安全的技术指标计算能力。

## 什么是 TechKit？

TechKit 是一个**高性能、线程安全**的技术分析库，旨在替代传统的 TA-Lib。它提供了 **189 个技术指标**，支持实时流式数据处理和批量历史数据分析。

### 核心特性

- **189 个技术指标** - 完整兼容 TA-Lib 算法，并提供高级分析指标
- **高性能** - C++ 核心实现，支持 O(1) 增量更新
- **跨平台支持** - Python、Node.js、WebAssembly 和原生 C/C++
- **线程安全** - 零全局状态设计，每个实例完全独立
- **内存高效** - O(period) 内存占用，适合大规模数据处理
- **实时流式处理** - 支持逐条数据更新，无需等待完整数据集
- **易于使用** - 简洁的 API 设计，支持面向对象和函数式两种风格

### 适用场景

TechKit 适用于以下场景：

- **量化交易研究** - 快速计算大量技术指标，进行策略回测
- **实时交易系统** - 流式数据处理，低延迟指标计算
- **数据分析平台** - 批量处理历史数据，生成技术分析报告
- **Web 应用** - 浏览器端直接计算指标，无需后端服务
- **移动应用** - 轻量级、高性能的移动端技术分析

## 版本说明

TechKit 提供多种语言和平台的绑定，每个平台可能有不同的版本：

### Python 版本

- **包名**: `techkit`
- **当前版本**: 1.2.7
- **Python 要求**: Python 3.10+
- **依赖**: NumPy 1.21+
- **支持平台**: Linux (x86_64, aarch64), macOS (x86_64, arm64), Windows (AMD64)
- **指标数量**: 189 个（完整版）
- **安装**: `pip install techkit`

### Node.js 版本

TechKit 提供两个 Node.js 包，满足不同需求：

#### techkit (核心版)

- **包名**: `techkit`
- **当前版本**: 1.2.7
- **指标数量**: 158+ 个核心指标（TA-Lib 兼容）
- **WASM 大小**: ~200KB
- **特点**: 轻量级，包含最常用的技术指标
- **适用场景**: 大多数应用场景，需要常用指标
- **安装**: `npm install techkit`

#### techkit-full (完整版)

- **包名**: `techkit-full`
- **当前版本**: 1.2.7
- **指标数量**: 189 个（包含高级分析）
- **WASM 大小**: ~800KB
- **特点**: 完整功能，包含风险指标、波动率模型、模式识别等
- **适用场景**: 需要完整功能、高级分析、模式识别
- **安装**: `npm install techkit-full`

**版本对比**:

| 特性 | techkit | techkit-full |
|------|---------|--------------|
| 核心指标 (TA-Lib) | ✅ 158 | ✅ 158 |
| 高级分析 | ❌ | ✅ 31 |
| 风险指标 | ❌ | ✅ Sharpe, Sortino, VaR |
| 波动率模型 | ❌ | ✅ GARCH, EWMA |
| 模式识别 | ❌ | ✅ 谐波模式、图表模式 |
| 浏览器支持 | ✅ | ✅ |
| Node.js Native | ✅ | ✅ |

### 浏览器版本

两个 Node.js 包都支持浏览器环境：

- **techkit**: 通过 WebAssembly 在浏览器中运行
- **techkit-full**: 通过 WebAssembly 在浏览器中运行（功能更完整）

### C/C++ 版本

- **语言**: C (ABI) + C++11 (实现)
- **构建系统**: CMake
- **指标数量**: 189 个
- **特点**: 原生性能，无依赖

## 快速开始

选择您的平台查看快速开始指南：

::::{tab-set}
:::{tab-item} Python
```python
import techkit as tk
import numpy as np

# 创建指标实例
sma = tk.SMA(period=20)  # 20 周期简单移动平均
rsi = tk.RSI(period=14)  # 14 周期相对强弱指标

# 准备价格数据（示例）
prices = np.array([100.0, 101.5, 102.3, 101.8, 103.2, 104.1, 103.5, 105.0])

# 方式 1: 增量更新（适合实时数据流）
for price in prices:
    sma_result = sma.update(price)
    rsi_result = rsi.update(price)
    
    # 检查结果是否有效（指标需要一定数量的数据才能计算）
    if sma_result.valid:
        print(f"价格: {price:.2f}, SMA: {sma_result.value:.2f}, RSI: {rsi_result.value:.2f}")

# 方式 2: 批量计算（适合历史数据分析）
sma_values = tk.SMA(20).calculate(prices)
rsi_values = tk.RSI(14).calculate(prices)

# 结果中，NaN 表示该位置数据不足，无法计算指标
print("SMA 值:", sma_values)
print("RSI 值:", rsi_values)
```
:::

:::{tab-item} JavaScript/Node.js
```javascript
import { init, SMA, RSI } from 'techkit';

// 初始化（必须在使用前调用一次）
await init();

// 创建指标实例
const sma = new SMA(20);  // 20 周期简单移动平均
const rsi = new RSI(14);  // 14 周期相对强弱指标

// 准备价格数据
const prices = [100.0, 101.5, 102.3, 101.8, 103.2, 104.1, 103.5, 105.0];

// 方式 1: 增量更新（适合实时数据流）
for (const price of prices) {
    const smaResult = sma.update(price);
    const rsiResult = rsi.update(price);
    
    // 检查结果是否有效
    if (smaResult.valid) {
        console.log(`价格: ${price.toFixed(2)}, SMA: ${smaResult.value.toFixed(2)}, RSI: ${rsiResult.value.toFixed(2)}`);
    }
}

// 方式 2: 批量计算（适合历史数据分析）
const smaValues = sma.calculate(prices);
const rsiValues = rsi.calculate(prices);

console.log('SMA 值:', smaValues);
console.log('RSI 值:', rsiValues);

// 清理资源（重要！）
sma.dispose();
rsi.dispose();
```
:::

:::{tab-item} C++
```cpp
#include <techkit/techkit.hpp>
#include <iostream>
#include <vector>

int main() {
    // 创建指标实例（RAII - 自动管理资源）
    auto sma = techkit::Indicator::SMA(20);
    auto rsi = techkit::Indicator::RSI(14);
    
    // 准备价格数据
    std::vector<double> prices = {100.0, 101.5, 102.3, 101.8, 103.2, 104.1, 103.5, 105.0};
    
    // 增量更新
    for (size_t i = 0; i < prices.size(); ++i) {
        auto sma_r = sma.update(prices[i]);
        auto rsi_r = rsi.update(prices[i]);
        
        if (sma_r.valid) {
            std::cout << "价格: " << prices[i] 
                      << ", SMA: " << sma_r.value 
                      << ", RSI: " << rsi_r.value << std::endl;
        }
    }
    
    return 0;  // 指标自动释放
}
```
:::
::::

## 为什么选择 TechKit？

### 相比 TA-Lib 的优势

1. **增量更新支持** - TA-Lib 只能批量计算，TechKit 支持 O(1) 增量更新，适合实时数据流
2. **线程安全** - 零全局状态，多线程环境下无需加锁
3. **现代化 API** - 面向对象设计，更符合现代编程习惯
4. **跨平台** - 统一的 API，Python、Node.js、浏览器、C++ 都能使用
5. **完整文档** - 详细的中文文档，适合初学者

### 性能优势

- **C++ 核心** - 原生性能，比纯 Python/JavaScript 实现快 10-100 倍
- **内存高效** - O(period) 内存占用，而不是 O(n)
- **向量化计算** - 批量计算时充分利用 CPU SIMD 指令

### 使用场景示例

**场景 1: 实时交易系统**
```python
# 接收实时价格流，立即计算指标
for price in real_time_price_stream:
    rsi_result = rsi.update(price)
    if rsi_result.valid and rsi_result.value > 70:
        trigger_sell_signal()  # RSI 超买，触发卖出信号
```

**场景 2: 历史数据回测**
```python
# 一次性计算所有历史数据的指标
historical_prices = load_from_database()
sma_values = tk.SMA(20).calculate(historical_prices)
rsi_values = tk.RSI(14).calculate(historical_prices)
```

**场景 3: Web 应用**
```javascript
// 在浏览器中直接计算指标，无需后端
const sma = new SMA(20);
const result = sma.calculate(userPriceData);
updateChart(result);
```

## 文档导航

### 快速开始

如果您是第一次使用 TechKit，建议按以下顺序阅读：

1. **[安装指南](getting-started/installation.md)** - 了解如何安装和配置 TechKit
2. **[快速开始](getting-started/quickstart.md)** - 5 分钟上手，学习基本用法
3. **[示例代码](getting-started/examples.md)** - 查看实际应用场景的完整示例

### API 参考

根据您使用的语言选择对应的 API 文档：

- **[Python API](api/python-api.md)** - Python 绑定完整参考，适合 Python 用户
- **[Node.js API](api/nodejs-api.md)** - JavaScript/TypeScript API 参考，包含 techkit 和 techkit-full 说明
- **[C API](api/c-api.md)** - C 语言接口参考，适合 C/C++ 开发者
- **[C++ API](api/cpp-api.md)** - C++ 包装器参考，现代化 C++ 接口

### 指标参考

按类别查看所有可用的技术指标：

- **[重叠研究](indicators/overlap.md)** - 移动平均线、布林带等（17 个）
- **[动量指标](indicators/momentum.md)** - RSI、MACD、随机指标等（30 个）
- **[波动率指标](indicators/volatility.md)** - ATR、NATR 等（3 个）
- **[成交量指标](indicators/volume.md)** - OBV、AD 等（3 个）
- **[统计函数](indicators/statistics.md)** - 标准差、方差、线性回归等（9 个）
- **[模式识别](indicators/patterns.md)** - K 线形态识别（61 个）
- **[高级分析](indicators/advanced.md)** - 风险指标、波动率模型、谐波模式等（66 个）

### 开发文档

如果您想参与开发或从源码构建：

- **[构建指南](development/building.md)** - 从源码编译 TechKit
- **[贡献指南](development/contributing.md)** - 如何贡献代码
- **[更新日志](development/changelog.md)** - 版本更新历史

## 完整目录

```{toctree}
:maxdepth: 2
:caption: 快速开始

getting-started/index
getting-started/installation
getting-started/quickstart
getting-started/examples
```

```{toctree}
:maxdepth: 2
:caption: API 参考

api/index
api/python-api
api/nodejs-api
api/c-api
api/cpp-api
```

```{toctree}
:maxdepth: 2
:caption: 指标参考

indicators/index
indicators/overlap
indicators/momentum
indicators/volatility
indicators/volume
indicators/statistics
indicators/patterns
indicators/advanced
```

```{toctree}
:maxdepth: 2
:caption: 开发文档

development/index
development/building
development/contributing
development/changelog
```

```{toctree}
:maxdepth: 2
:caption: 联系我们

contact
```

## 索引和搜索

- {ref}`genindex` - 完整索引
- {ref}`search` - 搜索文档

## 获取帮助

- **文档网站**: [https://techkit-docs.netlify.app/](https://techkit-docs.netlify.app/)
- **GitHub 仓库**: [https://github.com/yiivon/techkit](https://github.com/yiivon/techkit)
- **问题反馈**: [GitHub Issues](https://github.com/yiivon/techkit/issues)

## 版本信息

- **文档版本**: 1.2.7
- **最后更新**: 2024-12
- **许可证**: MIT License