千寻 web 引擎 · qianxun-web-engine

WorldQuant BRAIN alpha 批量挖掘的 Web 指挥中心：表达式生成 → 批量回测 → 指标分析 → 提交，全流程可视化。

本仓库是「千寻 / AlphaMachine」项目的 web 引擎部分，只包含 Web 指挥中心运行所需的代码。 桌面端（PySide6 GUI、表达式工厂、CLI 流水线）不在本仓库内，见文末与桌面端的关系。

快速开始

1. 环境要求

• Python 3.10+（实测 3.13）

• 一个 WorldQuant BRAIN 账号

• 平台：除 /credits 页外不依赖 Windows 特有 API —— 全仓库只有 wq_web/workdaddy_proxy.py 用到了 Windows 路径（%APPDATA%）。也就是说 Linux / macOS 上除了积分签到页，其余功能可正常跑。

2. 安装

git clone https://github.com/onefreecomet/qianxun-web-engine.git
cd qianxun-web-engine
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. 配置 BRAIN 凭据（二选一）

方式一 · 环境变量（最简单）

export WQ_USERNAME="your@email.com"      # Windows: set WQ_USERNAME=...
export WQ_PASSWORD="your_password"

方式二 · 系统 keyring（不落明文，推荐长期使用）

import keyring
keyring.set_password("alpha-machine", "your@email.com", "your_password")

凭据读取顺序：环境变量优先，回退 keyring（service = alpha-machine）。 代码里不会出现任何明文凭据，也不会把凭据写进日志。

4. 启动

python run_web.py                  # 默认 8090
python run_web.py --port 9000      # 换端口
QW_PORT=9000 python run_web.py     # 或用环境变量

浏览器打开 http://127.0.0.1:8090。

桌面窗口模式（可选，套一层原生窗口，不想要浏览器标签页时用）

pip install pywebview              # requirements.txt 里是注释状态，按需安装
python run_native.py

Related MCP server: WorldQuant MCP

三个页面

指挥中心 /

• 总览指标：今日已提交、Osmosis Rank、Value Factor、累计 Base Payment、Signals

• AI 批次：提交批次、实时进度、单条模拟明细、断点续跑

• 设置与配额：并发批数 / 并发槽配置、提示词库、每日回测配额仪表

• Alpha 备忘录：按主题分组的 alpha 记录与备注

• Osmosis 分配器：按渗透分规划分配方案

• ARC 回测：Region-Agnostic 投递与结果查看

弹窗入口：已提交 Alpha 清单（支持排序 / 区域筛选 / 搜索 / 分页）、 每日 Base Payment 趋势、日渗透分变化趋势。

Alpha Simulator /simulator

• 多标签页，每个标签独立加载一个 alpha

• 表达式与 Simulation Settings 编辑（支持 Copy / Import）

• IS 指标：Sharpe / Turnover / Fitness / Returns / Drawdown / Margin，含按区域拆分的指标行

• Yearly Statistics：按年拆分的指标表

• PnL 曲线：本地绘制，支持「拉取 PnL」按需取数

• PnL 同步：批量同步已提交 alpha 的 PnL 到本地库、手动计算 Self / PPA 相关性

Credits 积分签到 /credits

⚠️ 这一页不是纯网页功能，它依赖本机安装过 WorkDaddy 桌面客户端。 没装的话该页拿不到数据（但页面仍能打开，其余页面完全不受影响）。

• 读出 WorkDaddy 里已登录的账号，展示积分余额、过期时间、今日用量

• 一键批量领取每日签到积分

• 两条取数通道：

两条通道都要求存在这个目录（Windows）：

%APPDATA%\WorkDaddy\
├── accounts\*.info      # 账号与登录凭据 —— 两条通道都要读
├── .api-token           # 主通道：daemon 本地 API 令牌
└── ui-port.json         # 主通道：daemon 监听端口

最小要求是「WorkDaddy 装过、且至少登录过一个账号」；想要完整功能（含今日用量） 则需要客户端正在运行。

已知限制

• 仅 Windows：数据目录定位写死了 %APPDATA%\WorkDaddy 与 ~/AppData/Roaming/WorkDaddy （见 wq_web/workdaddy_proxy.py 的 _candidate_data_dirs()），macOS / Linux 上该页不可用

• 需能直连官方接口：降级通道会访问 www.workbuddy.cn、www.codebuddy.cn 等域名

• 不自动续期 token：过期只报「登录身份过期」，需回 WorkDaddy 重新登录。 这是刻意的 —— 刷新 token 要 POST 官方 auth 接口并回写 .info，属于越界操作

• 不写 WorkDaddy 任何状态：只读它的配置，不改账号状态、不写它的签到缓存。 降级通道无每日缓存，重复点「领取」会重复打接口（官方对已签到返回 10001 今天已签到，幂等安全）

安全说明：access token 只在进程内存里拼请求头，不落盘、不打印、不写日志。

排障（页面状态由 GET /api/xgj/health 的字段决定）

curl http://127.0.0.1:8090/api/xgj/health    # 只读自查

对接 AI Agent（MCP，可选）

内置 MCP Server，可让支持 MCP 的 Agent 直接驱动挖掘流程：

python run_mcp.py                                        # stdio（推荐给桌面 Agent）
python run_mcp.py --transport sse                        # SSE，供远程调试
python run_mcp.py --transport streamable-http --port 8765

数据与存储

所有任务、模拟、alpha 指标、PnL、备忘录都存在一个 SQLite 库里。

数据库定位顺序（见 wq_engine/mcp_server.py 的 _latest_db()）：

1. 环境变量 QIANXUN_DB 指定的路径（存在即用）

2. 项目根与当前工作目录向上 5 级内，找 编号最大 的 dist_v*/AlphaMachine/data/alpha_machine.db

3. 都找不到 → 回退到 <项目根>/data/alpha_machine.db，自动建空库

新环境首次启动是空库，这是预期行为。 界面能正常打开，但批次列表、备忘录、 PnL 曲线、Signals 清单、配额历史都是空的 —— 数据不会随代码一起发布。 要把旧数据带过去，把 alpha_machine.db 拷到上面任一路径，或直接设 QIANXUN_DB。

目录结构

qianxun-web-engine/
├── run_web.py              # Web 入口（uvicorn，默认 8090）
├── run_native.py           # 桌面窗口模式入口（pywebview，可选）
├── run_mcp.py              # MCP Server 入口（stdio / sse / http）
├── requirements.txt
├── wq_web/                 # Web 层
│   ├── server.py           # FastAPI 应用：页面路由 + 全部 REST API
│   ├── workdaddy_proxy.py  # 积分签到：WorkDaddy 代理 + 官方接口直连
│   ├── run_web.py          # 备用启动脚本（读 QW_PORT）
│   ├── templates/          # 三个页面：index / simulator / credits
│   └── static/             # 对应三套 css + js
├── wq_engine/              # 引擎层（web 用到的部分）
│   ├── api/                # BRAIN REST 客户端、本地相关性算法、corr 池
│   ├── arc/                # ARC（Region-Agnostic）回测
│   ├── osmosis/            # Osmosis 分配方案
│   ├── scheduler/          # 并发调度、SUPER 通道、RA 公共逻辑
│   ├── storage/            # SQLite 持久化
│   ├── sync/               # PnL 同步
│   └── mcp_server.py       # MCP 工具定义
└── docs/screenshots/       # README 用的界面截图

外部依赖一览

排障

与桌面端的关系

本仓库是纯 web 引擎，只保留 Web 指挥中心运行所需的模块。 以下桌面端模块刻意不在本仓库内：

wq_engine/ui/（PySide6 界面）、wq_engine/cli.py、wq_engine/factories/（表达式工厂）、 wq_engine/inspiration/（灵感/表达式构建）、wq_engine/scoring.py（推荐评分）、 wq_engine/dedup.py（表达式去重）、wq_engine/report.py（报告导出）、 wq_engine/settings_registry.py 等。

因此：本仓库能跑起完整的 Web 界面与回测调度，但跑不起桌面 GUI，也没有 CLI 流水线。

更新记录

许可

MIT © 2026 onefreecomet