alphalens-factor-analysis

分析alpha因子的预测能力与前向收益特征，生成分组收益、IC、换手率等报告，辅助量化策略的因子研究与事件分析。 触发场景：(1) 用户要分析某个因子是否有效，想看IC序列、分组收益和换手率曲线；(2) 用户要做事件研究，想看特定事件（如价格突破）发生后的前向收益分布；(3) 用户要用 Alphalens 生成因...

Security Scan

The skill's stated purpose (Alphalens-style factor analysis for A-share) matches most of its content, but there are multiple inconsistencies and risky installation choices (global pip installs, missing declared env vars, references to non-standard "-reloaded" packages and an unexplained 'uv' package manager) that make the bundle sloppy and potentially unsafe without further clarification.

Purpose & Capability

The name/description (factor analysis, Alphalens/ZVT pipeline) aligns with included reference docs and components. Expected dependencies (numpy, pandas, plotting, finance libs, zvt) are present in the text. Minor inconsistencies: SKILL.md claims 'Requires Python 3.12+ with uv package manager' but the install script does not install Python 3.12 or any 'uv' manager; LICENSE.txt is referenced but not included in the file manifest.

Instruction Scope

Runtime instructions ask the agent to run scripts/install.sh and to enforce many preconditions (which include Python commands that inspect/import zvt and check ZVT_HOME). SKILL.md and seed.yaml instruct re-reading seed.yaml and running preconditions — this will cause the agent to read many local reference files. The skill references an environment variable (ZVT_HOME) and third-party data providers (eastmoney, joinquant, akshare, qmt) but the manifest declares no required env vars or credentials, so the instructions expect access to environment state not declared in the registry metadata.

Install Mechanism

An included scripts/install.sh performs multiple python3 -m pip install ... commands (no virtualenv, no version pins). Installing packages globally is likely to modify the host environment (AP-VNPY-3700 style anti-pattern). The script installs several non-mainstream package names (empyrical-reloaded, pyfolio-reloaded, zipline-reloaded) which increases supply-chain uncertainty compared to well-known canonical packages; however installs are from PyPI via pip (no arbitrary download URL).

Credentials

The skill declares no required env vars or primary credential, yet SKILL.md and references expect ZVT_HOME, and the workflow will likely require data-provider credentials if the user picks joinquant or qmt. The absence of declared env requirements is a mismatch. The number of third-party packages installed (including forks) is higher than you'd expect for a minimal 'Alphalens report' helper, though it's plausible for an end-to-end pipeline.

Persistence & Privilege

always:false and the skill is user-invocable (default autonomy allowed). That's normal. The install script writes nothing into system config explicitly, but because it suggests global pip installs (no venv), it effectively persists packages system-wide which can have broad impact. There is no 'always:true' or other elevated flags.

What to consider before installing

What to consider before installing/using this skill: - The skill's purpose (factor analysis for A-share using ZVT/Alphalens) is coherent, but the package is sloppy about installation and environment declarations. - Do not run scripts/install.sh directly in your system Python. It installs multiple packages globally (no virtualenv) and can change system-wide dependencies. Instead: create an isolated virtual environment (venv/conda) and run the install there. - The install script installs '...-reloaded' packages (empyrical-reloaded, pyfolio-reloaded, zipline-reloaded). Treat these as untrusted forks unless you verify their PyPI owners and source code. Prefer to review/pin exact package versions and upstream sources before installing. - SKILL.md and seed.yaml reference ZVT_HOME and run Python import checks; the registry metadata lists no required env vars. Expect to set ZVT_HOME and (if using paid providers) provider credentials (joinquant/qmt) manually — verify how the skill expects to read credentials (env vars, files, or interactive input) before giving sensitive tokens. - The SKILL references a 'uv package manager' and Python 3.12+, but the install script does not enforce either. Ask the author to clarify required Python version and what 'uv' is, or run the skill inside a controlled environment matching Python 3.12. - The skill references a LICENSE.txt that is missing from the manifest. Ask for the license text before using in production. Recommended actions: run the skill only inside an isolated environment; review and pin pip package sources/versions; request the missing LICENSE and clarification about 'uv' and about how provider credentials are consumed; if you rely on this for trading/backtesting, audit the precondition checks (lookahead/semantic locks) and test on a small dataset first.

I help you build quant strategies on A-share with ZVT — from data fetch to backtest, one flow. Just tell me what you want; I'll write the code, you don't have to dig docs. (Heads up: ZVT natively supports A-share, HK, and crypto. US stocks — stockus_nasdaq_AAPL — are half-baked; don't bother for serious work.)

Pipeline

data_collection -> data_storage -> factor_computation -> target_selection -> trading_execution -> visualization

Top Use Cases (6 total)

Documentation Deployment (UC-101)

Automated build and deployment of project documentation to ensure consistent and reproducible documentation releases Triggers: docs, deploy, build

Sphinx Documentation Configuration (UC-102)

Configures the Sphinx documentation system with extensions for Python API documentation, Jupyter notebooks, and mathematical expressions Triggers: sphinx, config, documentation

PyFolio Portfolio Integration (UC-106)

Combines Alphalens factor analysis with PyFolio portfolio analytics to evaluate factor-derived portfolio performance, risk metrics, and tearsheet gene Triggers: pyfolio, integration, portfolio

For all 6 use cases, see references/USE_CASES.md.

Install

# One-time setup before first use
bash scripts/install.sh

Execute trigger: When user intent matches intent_router.uc_entries[].positive_terms AND user uses action verb (run/execute/跑/执行/backtest/fetch/collect)

What I'll Ask You

• Target market: A-share (default), HK, or crypto? (US stocks in ZVT are half-baked — stockus_nasdaq_AAPL exists but coverage is thin)
• Data source / provider: eastmoney (free, no account), joinquant (account+paid), baostock (free, good history), akshare, or qmt (broker)?
• Strategy type: MACD golden-cross, MA crossover, volume breakout, fundamental screen, or custom factor?
• Time range: start_timestamp and end_timestamp for backtest period
• Target entity IDs: specific stocks (stock_sh_600000) or index components (SZ1000)?

Semantic Locks (Fatal)

ID	Rule	On Violation
SL-01	Execute sell orders before buy orders in every trading cycle	halt
SL-02	Trading signals MUST use next-bar execution (no look-ahead)	halt
SL-03	Entity IDs MUST follow format entity_type_exchange_code	halt
SL-04	DataFrame index MUST be MultiIndex (entity_id, timestamp)	halt
SL-05	TradingSignal MUST have EXACTLY ONE of: position_pct, order_money, order_amount	halt
SL-06	filter_result column semantics: True=BUY, False=SELL, None/NaN=NO ACTION	halt
SL-07	Transformer MUST run BEFORE Accumulator in factor pipeline	halt
SL-08	MACD parameters locked: fast=12, slow=26, signal=9	halt

Full lock definitions: references/LOCKS.md

Top Anti-Patterns (25 total)

• AP-ZVT-183: 除权因子为 inf/NaN 时直接参与乘法导致复权静默失败
• AP-ZVT-179: 第三方数据接口超限后异常被吞噬，数据静默缺失
• AP-ZVT-183B: HFQ（后复权）与 QFQ（前复权）K 线表使用错误导致因子计算漂移

All 25 anti-patterns: references/ANTI_PATTERNS.md

Evidence Quality Notice

[QUALITY NOTICE] This crystal was compiled from blueprint finance-bp-120. Evidence verify ratio = 55.2% and audit fail total = 22. Generated results may have uncaptured requirement gaps. Verify critical decisions against source files (LATEST.yaml / LATEST.jsonl).

Reference Files

File	Contents	When to Load
references/seed.yaml	V6+ 全量权威 (source-of-truth)	有行为/决策争议时必读
references/ANTI_PATTERNS.md	25 条跨项目反模式	开始实现前
references/WISDOM.md	跨项目精华借鉴	架构决策时
references/CONSTRAINTS.md	domain + fatal 约束	规则冲突时
references/USE_CASES.md	全量 KUC-* 业务场景	需要完整示例时
references/LOCKS.md	SL-* + preconditions + hints	生成回测/交易代码前
references/COMPONENTS.md	AST 组件地图（按 module 拆分）	查 API 时

---

Compiled by Doramagic crystal-compilation-v6.1 from finance-bp-120 blueprint at 2026-04-22T13:00:58.879278+00:00. See human_summary.md for non-technical overview.