┌──────────────┐    ┌──────────────────────┐    ┌────────────────────┐
│   浏览器      │    │  本仓库（Python）      │    │  WorldQuant BRAIN  │
│  Web 界面     │───▶│  FastAPI (8090)      │───▶│  api.worldquant    │
│  或 AI Agent  │    │  + WebSocket 进度     │    │  brain.com         │
└──────────────┘    │  + MCP Server (stdio) │    └────────────────────┘
                    │  + SQLite 本地存储     │
                    └──────────────────────┘
                         │
                    data/alpha_machine.db
                    （首次运行自动创建）

run_web.py   → Web 指挥中心（浏览器操作）
run_mcp.py   → MCP Server（AI Agent 对接，stdio 默认）

python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
pip install -r requirements.txt

# 方式 A：环境变量（推荐，临时生效）
export WQ_USERNAME="你的BRAIN账号"
export WQ_PASSWORD="你的密码"
python run_web.py

# 方式 B：系统 keyring（持久，与千寻 GUI 共享）
python -c "import keyring; keyring.set_password('alpha-machine', 'wq_username', '你的账号'); keyring.set_password('alpha-machine', '你的账号', '你的密码')"

python run_web.py                # Web 界面 → http://127.0.0.1:8090
python run_mcp.py                # MCP Server（stdio，等待 agent 连接）

# 自定义端口 / 指定已有数据库
QW_PORT=9000 python run_web.py
QIANXUN_DB=/path/to/alpha_machine.db python run_mcp.py

{
  "mcpServers": {
    "qianxun": {
      "command": "python",
      "args": ["C:/path/to/qianxun-web-engine/run_mcp.py"],
      "env": {
        "WQ_USERNAME": "你的账号",
        "WQ_PASSWORD": "你的密码"
      }
    }
  }
}

{
  "settings": {
    "instrumentType": "EQUITY",
    "region": "USA",
    "universe": "TOP3000",
    "delay": 1,
    "decay": 4,
    "neutralization": "INDUSTRY",
    "truncation": 0.08,
    "pasteurization": "ON",
    "unitHandling": "VERIFY",
    "nanHandling": "OFF",
    "language": "FASTEXPR",
    "visualization": "OFF"
  },
  "expressions": [
    {"expression": "rank(ts_delta(close, 5))", "decay": 4},
    {"expression": "-rank(ts_delta(close, 5))", "decay": 4}
  ]
}

1. qianxun_login                     # 确认连接和账号
2. 生成表达式，写入 /tmp/batch1.json
3. qianxun_submit("/tmp/batch1.json", concurrent=3)
   → 返回 {"ok": true, "batch_no": "B128", ...}
4. qianxun_wait("B128")              # 阻塞直到跑完（内部自动轮询）
5. qianxun_analyze("B128")           # 拿到每个 alpha 的指标
6. qianxun_radar("B128", passed=8, total=8)  # 检查提交门槛

curl -X POST http://127.0.0.1:8090/api/batches \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {"region": "USA", "decay": 4, "neutralization": "INDUSTRY"},
    "expressions": [{"expression": "rank(ts_delta(close, 5))"}],
    "producer": "my-agent",
    "batch_size": 8,
    "no_backfill": false
  }'

# 需要 websockets 库
import asyncio, json, websockets

async def watch():
    async with websockets.connect("ws://127.0.0.1:8090/ws/progress") as ws:
        while True:
            msg = json.loads(await ws.recv())
            print(msg)  # {type: "batch"|"sim"|"done", batch_no, alpha_id, ...}

asyncio.run(watch())