简体中文 | English

面向 A 股本地数据的因子研究工作台：把研报和因子想法变成标准因子代码，再完成计算、预处理、评估，最后在网页上查看结果。

研报 / 想法 -> FactorSpec -> compute() -> Parquet 因子值 -> 评估 -> Web 工作台

数据来自配套项目 zer0share，它负责 A 股数据的同步和查询。

项目还在早期阶段，适合作为研究工作台使用，还不是成熟的生产平台。

• 标准因子接口：FactorSpec + FactorFrame + compute()，输出统一为 trade_date, ts_code, value
• 存储：Parquet 按日期分区，DuckDB 作为注册表
• 预处理：截面去极值、标准化，以及行业 / 市值中性化
• 评估：IC、分组收益、换手、单调性、组合绩效
• Web 工作台：看板、因子主页、对比、因子族、后台任务
• factor-research skill：从研报中提取因子、审核、生成代码并归档

需要 Python 3.11+、uv，以及用 zer0share 同步好的本地数据。默认 zer0share 和本项目放在同级目录，位置不同的话，修改 pyproject.toml 的 [tool.uv.sources]。

git clone https://github.com/zer0quant/zer0factor.git
cd zer0factor
uv sync
cp config/settings.example.toml config/settings.toml   # 按需修改数据目录和日期区间

uv run python main.py compute-market-cap                  # 计算内置市值因子
uv run python main.py evaluate-factor log_total_market_cap
uv run python main.py show-summary                        # 查看评估结果

评估结果写在 data/evaluations/<run_id>/，指标口径见 docs/evaluation.md。

先在 zer0share 目录下同步行情并续建股票池（股票池不会随行情自动更新）：

uv run python main.py sync --stock
uv run python main.py build-universe

再回到本项目，一条命令完成日更（适合放进定时任务）：

uv run python main.py update-daily --notify             # 每个交易日：截止日检查 → 增量构建 → 增量评估 → 飞书摘要
uv run python main.py update-daily --full-eval --notify # 每月一次：评估改为全量对账

• 目标截止日取行情和股票池中较早的一个；股票池落后时照常更新到股票池的截止日，并发飞书提醒。
• 任一步失败即停止，退出码为 1。--dry-run 只列出计划，--skip-eval 只构建不评估。
• 也可以分步执行 check-freshness、compute-returns --incremental、build-factors --incremental、evaluate-factors --incremental，用法和增量评估与全量的差别见 docs/incremental-update.md。

cd web && npm install && npm run build && cd ..   # 首次使用：构建前端（需要 Node 18+）
uv run python main.py serve                       # 打开 http://127.0.0.1:8600

看板、因子主页的数字都来自 [web.standard] 定义的统一口径、并且评估到最新的那一次评估。页面说明、配置项和后台任务的用法见 docs/web-workbench.md。

因子看板：一行一个原始因子，指标取主版本各周期的中位数。

版本详情：核心指标、分组累计收益、分层收益、Rank IC 序列与衰减。

因子对比：指标并排比较，多头累计收益曲线叠加（可切换多头超额）。

所有命令都通过 uv run python main.py <命令> 执行，加 --help 查看完整参数。

class Ret20(Factor):
    spec = FactorSpec(name="ret20", inputs=["close"], min_window=20, frequency="1d", adjust="hfq")

    def compute(self, data: FactorFrame) -> pd.DataFrame:
        return to_factor_output(data.close / data.close.shift(20) - 1, self.spec.name)

因子代码只访问 FactorFrame，不要自己读文件、查 DuckDB 或调用 zer0share。字段契约见 docs/factor-contract.md。

• 因子契约：字段、输出格式、存储布局
• 因子评估：注册表、评估命令、产物和指标口径
• Web 工作台：页面说明、统一口径、后台任务、因子族
• 增量更新：日更命令、增量构建与增量评估
• factor-research skill：从研报到因子的完整流程
• TODO · 开发笔记 · 贡献指南

• 只支持本地 A 股数据和 zer0share。
• FactorFrame 还没有提供 ST、停牌、上市天数、精确涨停等字段。
• 使用 qfq 价格的因子族不支持增量构建；增量评估只支持单一持有期。
• API 还在实验阶段。

• 知乎：我用 Codex，把"投资研报到股票因子"的流程做成了一个 Skill / 我用 Codex + Alphalens，搭了一套适配 A 股的因子评估流水线
• 微信公众号「极客投研笔记」

本项目只用于研究和工程实验，不构成任何投资建议。

MIT，详见 LICENSE。