team/dev/: vista-3.0.21.post260331 metadata and description

A versatile quantitative investment research and trading framework.

description_content_type	text/markdown
metadata_version	2.3
requires_dist	czsc>=0.9.68 polars>=1.0.0 chan-factor-rs pydantic>=2.6.0 tomlkit>=0.13.0 python-dotenv>=1.0.0 rich>=13.0.0 typer>=0.9 loguru>=0.7.0 clickhouse-connect>=0.6.0 duckdb>=0.9.0 faiss-cpu>=1.13.0 joblib>=1.5.2 psutil>=7.1.3 chanfactor>=0.1.6 claude-agent-sdk>=0.1.48
requires_python	>=3.11

Because this project isn't in the mirror_whitelist, no releases from root/pypi are included.

File	Tox results	History
vista-3.0.21.post260331-py3-none-any.whl Size 418 KB Type Python Wheel Python 3		Uploaded to team/dev by team 2026-03-31 07:39:23

Vista — 量化因子管理与策略建模框架

Vista（前瞻视野）：面向量价因子的系统化挖掘、计算、评估与策略建模工程。项目聚焦趋势预测与长期推演，提供从 标准化数据 → 因子构建 → 性能评价 → 策略建模 → 集成学习 的端到端流程。

设计理念

Vista 的设计围绕以下核心原则：

全链路覆盖：从数据标准化、算子库、并行计算引擎、因子评估、数据库化管理、策略建模到集成学习，覆盖因子研究的完整生命周期。
统一抽象与可扩展性：通过 BaseEngine、BaseStrategyModel、BasePredictor 三个基类，分别为因子计算、策略建模、集成学习建立统一的骨架（模板方法模式），子类只需实现核心逻辑。
工程可靠性：智能资源分配、内存监控与分批处理、并行失败自动回退单线程、防未来信息审计、完整的性能统计与告警机制。
配置驱动：Pydantic 数据模型贯穿全栈，支持 Python API 和 TOML 配置两种使用方式，确保可复现性。
插件化设计：用户自定义策略模型自动发现与加载（~/.vista/models/）、算子库可插拔扩展。

安装

环境要求：Python ≥ 3.11

Vista 支持按需安装不同的功能模块，您可以根据实际需求选择安装方式。

安装方式对比

方式	推荐度	适用场景
uv	⭐⭐⭐⭐⭐	日常开发、生产环境
pip	⭐⭐⭐	快速体验、无 uv 环境

1. 最小化安装（核心功能）

只安装因子计算引擎、策略建模、因子数据库等核心功能。

uv 方式：

# 方式1：从源码安装（推荐开发者）
git clone https://github.com/your-org/vista.git
cd vista
uv sync

# 方式2：从 PyPI 安装（需要先配置私有源）
uv add vista \
  --index-url https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

pip 方式：

# 从源码安装
git clone https://github.com/your-org/vista.git
cd vista
pip install -e .

# 或从 PyPI 安装
pip install vista \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

包含功能：

✅ 因子计算引擎（时序/截面/事件驱动）
✅ 算子库（TA-Lib + 自定义）
✅ 策略建模（排序法、直接暴露法、组合优化等）
✅ 因子数据库（ClickHouse + DuckDB）
✅ 向量计算（FAISS + Joblib）
✅ CLI 工具（vista-factor）

2. 按需安装功能模块

根据实际需求选择安装对应的功能模块。

2.1 集成学习模块

包含 AutoGluon 和 QLIB 两个集成学习框架。

uv 方式：

# 从源码安装
uv sync --group ensemble

pip 方式：

pip install "vista[ensemble]" \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

包含功能：

✅ AutoGluon 集成预测
✅ QLIB 集成预测
✅ WalkForward 滚动窗口验证
✅ CLI 工具（vista-ensemble）

2.2 优化求解器模块

包含 CVXPY 及其多个求解器（SCS、ECOS、OSQP、MOSEK）。

uv 方式：

uv sync --group optimization

pip 方式：

pip install "vista[optimization]" \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

包含功能：

✅ 二次规划优化求解
✅ 组合优化策略
✅ 因子暴露优化
✅ 多种求解器支持

2.3 AI 智能体模块

包含 Agno 和 Claude Agent SDK（支持 Windows）。

uv 方式：

uv sync --group agents

pip 方式：

pip install "vista[agents]" \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

包含功能：

✅ Claude 因子审核智能体
✅ Claude 因子构建智能体
✅ Agno 智能体框架
⚠️ 注意：claude-agent-sdk 版本限制为 <0.1.49（Windows 兼容性）

2.4 AI 智能体模块

包含 Streamlit Web UI。

uv 方式：

uv sync --group web

pip 方式：

pip install "vista[web]" \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

包含功能：

✅ Streamlit Web UI
✅ 多页面应用（因子审核、回测报告、多因子策略）
✅ 可视化分析界面

启动 Web UI：

uv run vista-ui                    # 默认端口 8588
uv run vista-ui --port 8501        # 自定义端口

3. 完整安装（所有功能）

安装所有功能模块和开发工具。

uv 方式：

# 从源码安装（推荐）
git clone https://github.com/your-org/vista.git
cd vista
uv sync --all-groups

pip 方式：

# 安装所有可选依赖
pip install "vista[ensemble,optimization,agents,web]" \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

包含功能：

✅ 所有核心功能（包含数据库和向量计算）
✅ 所有可选功能模块（ensemble、optimization、agents、web）
✅ 开发工具（ruff、basedpyright、pytest、pytest-cov、pre-commit 等）

4. 开发环境安装

用于项目开发和贡献。

uv 方式：

# 完整开发环境
uv sync --all-groups

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate     # Windows

开发工具验证：

# 安装提交前钩子
uv run pre-commit install

# 运行测试与覆盖率
uv run pytest --cov=vista --cov-report=term-missing

# 代码质量
uv run ruff format .
uv run ruff check . --fix
uv run basedpyright

5. 功能模块组合安装

可以同时安装多个功能模块：

uv 方式：

# 核心 + 集成学习 + AI 智能体
uv sync --group ensemble --group agents

# 核心 + 集成学习 + Web 服务
uv sync --group ensemble --group web

# 核心 + 优化求解器 + AI 智能体
uv sync --group optimization --group agents

pip 方式：

# 核心 + 集成学习 + AI 智能体
pip install "vista[ensemble,agents]" \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

# 核心 + 集成学习 + Web 服务
pip install "vista[ensemble,web]" \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

# 核心 + 优化求解器 + AI 智能体
pip install "vista[optimization,agents]" \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

6. PyPI 源配置

Vista 配置了三级源，按优先级自动回退：

主源：阿里云镜像（速度快）
备用源：PyPI 官方（兜底，确保包版本最新）
私有源：zbczsc 开发团队（chanfactor 等私有包）

手动指定源：

# 临时使用清华镜像
uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple/

# 临时使用 PyPI 官方源
uv sync --index-url https://pypi.org/simple/

7. 验证安装

安装完成后，可以通过以下方式验证：

# 检查版本
uv run python -c "import vista; print(vista.__version__)"

# 测试核心功能
uv run python -c "from vista.engines import TimeSeriesEngine; print('✅ 引擎模块正常')"

# 测试 CLI 工具
uv run vista-factor --help
uv run vista-ensemble --help
uv run vista-ui --help

# 运行测试
uv run pytest tests/engines/test_engines.py -v

8. 常见问题

Q: 如何选择安装方式？

日常开发：推荐 uv sync（从源码）
快速体验：使用 pip install（从 PyPI）
生产环境：使用 uv sync --frozen（锁定版本）

Q: 最小化安装包含哪些功能？

A: 包含因子计算引擎、策略建模、因子数据库、CLI 工具等核心功能，不包含集成学习、AI 智能体等高级功能。

Q: 如何减少安装体积？

A: 只安装需要的功能模块，例如：

# 只安装核心功能
uv sync

# 只添加需要的模块
uv sync --group ensemble  # 集成学习
uv sync --group web        # Web 服务

Q: Windows 平台使用 AI 智能体模块有限制吗？

A: 是的。claude-agent-sdk 版本限制为 <0.1.49（Windows 兼容性），当前使用 0.1.48 版本，所有功能正常。

Q: 如何更新到最新版本？

# uv 方式
uv sync --upgrade

# pip 方式
pip install --upgrade vista \
  -i https://mirrors.aliyun.com/pypi/simple/ \
  --extra-index-url https://pypi.zbczsc.com/team/dev/+simple/

项目结构

vista/
├── engines.py              # 因子计算引擎（时序/截面/事件驱动）
├── operates.py             # TA-Lib 及自定义算子库
├── cs_operators.py         # 横截面算子库
├── fix_params_operates.py  # 固定参数预配置算子
├── data.py                 # 数据处理工具
├── factor_db/              # 因子数据库（ClickHouse 存储与管理）
│   ├── manager.py          #   数据库连接管理器（单例 + 线程安全）
│   ├── models.py           #   Pydantic 数据模型
│   ├── services.py         #   业务逻辑 CRUD 服务层
│   ├── enmus.py            #   枚举定义（ComputeEngine, EvaluateStatus）
│   ├── analyze.py          #   因子分析工具
│   └── cli.py              #   命令行工具 vista-factor
├── models/                 # 策略建模算法
│   ├── base.py             #   策略基类 BaseStrategyModel
│   ├── sorting.py          #   排序法 CSSorting
│   ├── direct_exposure.py  #   直接暴露法 DirectExposure
│   ├── max_expected_returns.py  # 组合优化 MaxExpectedReturns
│   ├── max_factor_exposure.py   # 因子暴露优化 MaxFactorExposure
│   ├── event.py            #   事件驱动 EventDriven
│   ├── backtest.py         #   回测管道 FactorBacktestPipeline
│   └── user.py             #   用户自定义策略自动加载
├── ensemble/               # 集成学习模块
│   ├── base.py             #   BasePredictor 基类（WalkForward 框架）
│   ├── configs.py          #   统一配置类（WalkForward/Autogluon/Qlib/CLI）
│   ├── preprocessor.py     #   数据预处理器（窗口级，防数据泄露）
│   ├── result.py           #   结果类 EnsembleResult
│   ├── workflow.py         #   工作流编排
│   ├── cli.py              #   命令行工具 vista-ensemble
│   └── predictors/
│       ├── autogluon.py    #     AutoGluon 预测器
│       └── qlib.py         #     QLIB 预测器
├── evaluate/               # 因子评估
│   ├── ic.py               #   截面 IC / 分组单调性分析
│   ├── models.py           #   模型评估（多策略批量回测）
│   └── utils.py            #   评估工具与时段划分
├── utils/                  # 工具库
│   ├── detect_future_info.py  # 防未来信息审计
│   ├── detect_factor.py    #   因子检测与验证
│   ├── event_analysis.py   #   事件因子分析
│   ├── returns_analysis.py #   收益差异分析
│   ├── norm.py             #   因子标准化（去极值/Z-score）
│   ├── duckdb_factors.py   #   DuckDB 因子查询
│   ├── duckdb_returns.py   #   DuckDB 收益计算
│   ├── faiss_with_labels.py #  FAISS 向量检索
│   └── ...
├── ui/                     # Web 界面（Streamlit）
│   ├── app.py              #   多页面应用主入口
│   └── pages/              #   人工因子审核/报告管理/多因子策略
├── agents/                 # AI 智能体
│   ├── claude_factor_review.py  # Claude 因子审核
│   └── ts_vpf_miner.py    #   时序因子挖掘
tests/                      # 单元测试
docs/                       # 文档

数据规范

标准 K 线格式

所有因子计算基于统一的标准 K 线 DataFrame，必须包含以下列：

列名	类型	说明
`dt`	datetime	K 线时间戳
`symbol`	str	品种代码
`open`	float	开盘价
`close`	float	收盘价
`high`	float	最高价
`low`	float	最低价
`vol`	float	成交量
`amount`	float	成交金额

因子列命名规范

因子列统一以 F# 前缀命名，格式为 F#{因子名}#{后缀}。

F#SMA60#DEFAULT      # 60日均线偏离因子
F#RSI14#v2           # RSI因子第2版
F#MOM_EVENT#DEFAULT  # 动量事件因子

因子数据类型为 float64，支持 NaN 值。

核心模块详解

1. 因子计算引擎（engines）

三种引擎继承自 BaseEngine，实现 validate → prepare → compute 的模板方法：

引擎	类名	枚举值	特点
时序引擎	`TimeSeriesEngine`	`ComputeEngine.TSE`	按品种并行计算，自动内存监控，失败回退单线程
截面引擎	`CrossSectionEngine`	`ComputeEngine.CSE`	按日期截面计算，整体执行因子函数
事件驱动引擎	`EventDrivenEngine`	`ComputeEngine.EDE`	继承时序引擎，额外校验输出值为 {0, 1, -1}

使用示例：

from vista.engines import TimeSeriesEngine
from vista.factor_db.models import FactorDescribe, ComputeEngine

# 1. 定义因子
factor = FactorDescribe(
    factor_name="SMA60",
    factor_code="""
def SMA60(df, **kwargs):
    df['F#SMA60#DEFAULT'] = df['close'] / df['close'].rolling(60).mean() - 1
    return df
""",
    compute_engine=ComputeEngine.TSE
)

# 2. 准备数据（标准K线 DataFrame）
data = {'klines': klines_df}

# 3. 计算因子（引擎初始化时自动执行）
engine = TimeSeriesEngine(data=data, factor=factor, timeout=30, verbose=True)

# 4. 获取结果
results = engine.results          # 包含因子列的 DataFrame
print(f"耗时: {engine.elapsed:.2f}s")
print(f"内存增量: {engine.memory_usage:.2f}MB")
print(f"告警: {engine.warnings}")

也可以通过 FactorDescribe.compute() 方法一步完成：

results = factor.compute(data=data, timeout=30)

2. 算子库（operates / cs_operators）

提供丰富的算子原语，供因子代码中调用组合：

TA-Lib 算子：SMA、EMA、RSI、MACD、ATR、BBANDS、ADX、OBV 等 100+ 技术指标
自定义算子：log、divide、sqrt、sigmoid、adv、std、skew、kurt、rank、ts_rank、delay、delta 等
横截面算子：winsorize（去极值）、rank（排序百分位）、normalize（标准化）、zscore、neutralize（中性化）、regression（回归残差）
固定参数算子：预配置好参数的常用算子组合（如 ADX 的 5d/21d/55d/144d 等变体），每个算子附带分类标签

3. 因子数据库（factor_db）

基于 ClickHouse 的因子元数据管理系统，采用三层架构：

Manager层（manager.py）    ← 单例连接 + 线程安全 + 自动建表
    ↓
Service层（services.py）   ← CRUD 业务逻辑
    ↓
Model层（models.py）       ← Pydantic Schema 定义

核心数据模型：

FactorDescribe：因子描述（名称、代码、引擎类型、描述、标签）
FactorEvaluate：因子评估记录（方法、结果、状态、耗时、内存）
FactorTag：因子标签（分类体系）

Python API：

from vista.factor_db import get_manager, add_factor, list_factors, get_factor

# 获取数据库管理器（自动读取 CLICKHOUSE_DSN 环境变量）
manager = get_manager()

# 添加因子
add_factor(manager, factor_describe)

# 查询因子
factors = list_factors(manager, tag="momentum", limit=10)
factor = get_factor(manager, "F#SMA60#DEFAULT")

CLI 工具（vista-factor）：

vista-factor ls                              # 列出因子
vista-factor ls --tag=momentum --limit=10    # 按标签过滤
vista-factor info F#SMA60#DEFAULT            # 查看因子详情及代码
vista-factor rm F#OLD_FACTOR                 # 删除因子
vista-factor tag add F#SMA60#DEFAULT trend   # 添加标签
vista-factor tag ls                          # 列出所有标签
vista-factor eval ls F#SMA60#DEFAULT         # 查看评估历史
vista-factor eval ranked --metric="IC"       # 按指标排名
vista-factor db stats                        # 数据库统计
vista-factor db cleanup                      # 清理已删除因子

4. 策略建模（models）

六种策略算法继承自 BaseStrategyModel，统一实现 prepare → compute → run 流程：

策略	类名	权重类型	适用场景
排序法	`CSSorting`	截面(cs)	多空组合构建，等权/按名次加权
直接暴露法	`DirectExposure`	截面(cs)	因子标准化直接映射权重
组合优化法	`MaxExpectedReturns`	截面(cs)	二次规划最大化预期收益
因子暴露优化	`MaxFactorExposure`	截面(cs)	目标因子暴露约束优化
事件驱动	`EventDriven`	时序(ts)	事件信号开平仓
用户自定义	继承 `BaseStrategyModel`	自定义	放置于 `~/.vista/models/` 自动加载

使用示例：

from vista.models import CSSorting, DirectExposure, MaxExpectedReturns, MaxFactorExposure, EventDriven

# 排序法：选择因子值排名前20%做多，后20%做空
model = CSSorting(df, factor='F#SMA60#DEFAULT', top_pct=0.2, bottom_pct=0.2,
                  weighting_method='equal')  # 'equal' 或 'rank_weighted'
weights = model.run()

# 直接暴露法：因子标准化后映射为权重
model = DirectExposure(df, factor='F#SMA60#DEFAULT',
                       normalize_method='zscore', leverage=1.0)
weights = model.run()

# 组合优化法：二次规划最大化预期收益
model = MaxExpectedReturns(df, factor='F#SMA60#DEFAULT',
                           risk_aversion=1.0,
                           weight_bounds=(-0.8, 0.8),
                           solver_config={'solver': 'ECOS'})
weights = model.run()

# 因子暴露优化：最大化因子暴露，控制风险
model = MaxFactorExposure(df, factor='F#SMA60#DEFAULT',
                          target_exposure=0.3, leverage=1.6,
                          solver_config={'solver': 'ECOS'})
weights = model.run()

# 事件驱动：基于事件信号开平仓
model = EventDriven(df, factor='F#EVENT#DEFAULT',
                    timeout_bars=1, stoploss_bp=100)
weights = model.run()

批量回测管道：

from vista.models import run_factor_backtest

# 批量运行多种策略并生成回测报告
results = run_factor_backtest(df, factor='F#SMA60#DEFAULT',
    models=[
        {"name": "sort_equal", "model": "CSSorting", "kwargs": {"top_pct": 0.2}},
        {"name": "exposure", "model": "DirectExposure", "kwargs": {"leverage": 1.5}},
    ])

5. 集成学习（ensemble）

基于 WalkForward 滚动窗口的集成预测框架，BasePredictor 提供完整流程，子类只需实现 fit 和 predict：

预测器	框架	特点
`AutogluonPredictor`	AutoGluon	自动机器学习，多模型自动集成
`QlibPredictor`	QLIB	量化专用框架，支持 LightGBM/XGBoost/DNN

Python API：

from vista.ensemble import AutogluonPredictor, WalkForwardConfig, AutogluonConfig

# 配置 WalkForward 滚动窗口
wf_config = WalkForwardConfig(
    train_end_dates=['2024-01-01', '2025-01-01'],
    max_train_days=365,
    min_train_days=180,
    gap_days=0        # 防未来信息泄露
)

# 配置 Autogluon
ag_config = AutogluonConfig(presets='medium_quality', time_limit=1800)

# 创建预测器
predictor = AutogluonPredictor(
    df=df,
    factor_cols=['F#Factor1', 'F#Factor2'],
    label_col='n1b',
    walk_forward_config=wf_config,
    autogluon_config=ag_config,
    enable_internal_preprocess=True    # 窗口级预处理，防数据泄露
)

# 执行训练预测
results = predictor.run_walk_forward()
predictions = results.predictions

TOML 配置驱动：

from vista.ensemble import EnsembleConfig

config = EnsembleConfig.from_toml("ensemble.toml")
predictor = config.create_predictor(df, factor_cols=["f1", "f2"], label_col="n1b")
results = predictor.run_walk_forward()

CLI 工具（vista-ensemble）：

vista-ensemble init autogluon -o config.toml  # 生成配置模板
vista-ensemble validate config.toml            # 验证配置
vista-ensemble run config.toml --verbose       # 运行训练

6. 因子评估（evaluate）

from vista.evaluate import cross_sectional_ic, group_monotonicity, calculate_ic_performance

# 计算截面 IC（逐日因子与收益的相关性）
df_ic = cross_sectional_ic(df, factor='F#SMA60#DEFAULT', target='n1b')

# 因子分组收益单调性（分10组，看收益是否随因子值单调变化）
mono_score = group_monotonicity(df, factor='F#SMA60#DEFAULT', target='n1b', groups=10)

# 综合性能指标（IC均值、ICIR、夏普比率等）
perf = calculate_ic_performance(df, factor='F#SMA60#DEFAULT', target='n1b')

7. 工具库（utils）

工具	功能
`detect_future_info()`	自动检测因子是否使用了未来信息
`detect_factor()`	因子有效性检测与验证
`normalize_factor()`	因子标准化（去极值/Z-score）
`analyze_returns_diff()`	收益差异归因分析
事件分析系列	事件因子相关性、时序相关性、符号一致性、因子对比
DuckDB 工具	高性能因子查询与收益计算
FAISS 检索	带标签的因子向量相似性检索

8. Web 界面（UI）

基于 Streamlit 的多页面应用，提供可视化的因子分析和策略回测界面：

uv run --no-sync vista-ui                  # 默认端口 8588
uv run --no-sync vista-ui --port 8501      # 自定义端口

页面包括：人工因子审核、因子回测报告预览、HTML 报告管理、多因子策略回测。

9. AI 智能体（agents）

因子审核智能体：基于 Claude 的因子逻辑审核与质量评估
时序因子挖掘：LLM 驱动的量价因子自动生成（结合研报知识与算子库）

端到端工作流

标准K线数据 ──→ 因子计算引擎 ──→ 因子评估 ──→ 因子入库 ──→ 策略建模 ──→ 回测分析
                  │                  │                          │
            算子库组合          IC/分组单调性              多策略对比
          或 AI 智能体生成      性能指标统计             集成学习融合

数据准备：按标准 K 线格式加载数据，确保必备列完整
因子构造：选择算子组合编写因子函数，或使用 AI 智能体自动生成
引擎计算：通过时序/截面/事件驱动引擎并行计算因子值
性能评估：计算截面 IC、分组单调性、ICIR、夏普比率等指标
因子管理：将因子元数据、代码、评估结果写入 ClickHouse 数据库
策略建模：选择排序法/直接暴露/组合优化等策略，产出权重表
集成学习：多因子 WalkForward 训练，使用 AutoGluon/QLIB 集成模型
回测分析：批量回测、HTML 报告生成、UI 可视化分析

开发指南

本项目使用 uv 进行统一的开发管理，所有命令应通过 uv run 执行。

# 环境初始化
uv sync                          # 安装核心依赖和默认开发工具
source .venv/bin/activate        # 激活虚拟环境

# 测试
uv run pytest                    # 运行全部测试
uv run pytest tests/test_engines.py -v   # 运行指定测试

# 代码质量
uv run pre-commit install        # 安装提交前钩子
uv run ruff format .             # 代码格式化（行长 120）
uv run ruff check . --fix        # lint、导入排序、复杂度检查与自动修复
uv run basedpyright              # 类型检查
uv run pytest --cov=vista --cov-report=term-missing   # 测试覆盖率

环境变量（参考 .env.example）：

CLICKHOUSE_DSN=clickhouse://default:@localhost:9000/factor_db   # 因子数据库
LOG_LEVEL=INFO                                                   # 日志级别

核心依赖

依赖优化成果

经过系统性依赖清理，Vista 实现了极致精简：

指标	优化前	优化后	变化
核心依赖	39个	16个	-59%
总依赖数	59个	26个	-56%
功能分组	1个	4个	+300%

核心依赖（16个）

类别	依赖包	用途
数据处理	czsc	量化框架
配置管理	pydantic, tomlkit, python-dotenv	配置与环境
CLI 工具	rich, typer	命令行界面
日志	loguru	日志系统
数据库	clickhouse-connect, duckdb	因子数据库与高性能查询
向量计算	faiss-cpu, joblib	向量检索与并行计算
系统工具	psutil, chanfactor	资源监控与因子计算

功能依赖组（可选）

功能组	依赖包	说明
ensemble	autogluon, pyqlib	集成学习（AutoGluon + QLIB）
optimization	cvxpy, scs, ecos, osqp, mosek	优化求解器
agents	agno, claude-agent-sdk	AI 智能体
web	streamlit	Web 服务
dev	pytest, pytest-cov, ruff, basedpyright, pre-commit, jupyter	开发工具

注意：

数据库（clickhouse-connect, duckdb）和 向量计算（faiss-cpu, joblib）已包含在核心依赖中

依赖说明

核心依赖：包含因子计算、策略建模、因子数据库等基础功能
功能依赖组：按需安装，灵活选择功能模块
开发工具：用于测试、代码格式化、类型检查等
平台兼容：100% Windows 平台支持（claude-agent-sdk 版本限制为 <0.1.49）

依赖版本策略

最小化原则：只安装必需的依赖
版本限制：关键依赖设置合理的版本范围
平台兼容：确保所有依赖在目标平台可用
定期审计：定期清理未使用依赖

详见：DEPENDENCY_OPTIMIZATION_CORRECT.md

devpi

team/dev/: vista-3.0.21.post260331 metadata and description

Vista — 量化因子管理与策略建模框架

设计理念

安装

安装方式对比

1. 最小化安装（核心功能）

2. 按需安装功能模块

2.1 集成学习模块

2.2 优化求解器模块

2.3 AI 智能体模块

2.4 AI 智能体模块

3. 完整安装（所有功能）

4. 开发环境安装

5. 功能模块组合安装

6. PyPI 源配置

7. 验证安装

8. 常见问题

Q: 如何选择安装方式？

Q: 最小化安装包含哪些功能？

Q: 如何减少安装体积？

Q: Windows 平台使用 AI 智能体模块有限制吗？

Q: 如何更新到最新版本？

项目结构

数据规范

标准 K 线格式

因子列命名规范

核心模块详解

1. 因子计算引擎（engines）

2. 算子库（operates / cs_operators）

3. 因子数据库（factor_db）

4. 策略建模（models）

5. 集成学习（ensemble）

6. 因子评估（evaluate）

7. 工具库（utils）

8. Web 界面（UI）

9. AI 智能体（agents）

端到端工作流

开发指南

核心依赖

依赖优化成果

核心依赖（16个）

功能依赖组（可选）

依赖说明

依赖版本策略

更多文档

参考资料