WQBuddy v1.1.3 — WorldQuant BRAIN 工具与 Alpha Miner Agent

项目仓库: https://github.com/sebrinass/wq-buddy npm: https://www.npmjs.com/package/wq-buddy

v1.1.2 修复：sync 状态映射/时间戳修正、L2/L3 失败自动重试、evolve_errors 反馈 Agent、update-status 支持 alpha_id。

一、安装

第 1 步：安装 npm 包

npm install -g wq-buddy

第 2 步：创建配置文件 ~/.wq-buddy/config.json

{
  "version": "v1.1.3",
  "credentials": {
    "username": "你的BRAIN账号",
    "password": "你的BRAIN密码"
  },
  "default_settings": {
    "instrument_type": "EQUITY",
    "region": "USA",
    "universe": "TOP3000",
    "delay": 1,
    "decay": 0,
    "neutralization": "INDUSTRY",
    "truncation": 0.08,
    "pasteurization": "ON",
    "unit_handling": "VERIFY",
    "nan_handling": "OFF",
    "language": "FASTEXPR"
  },
  "database": { "type": "sqlite", "path": "alpha_workbench.db" },
  "batch_settings": { "sleep_between_requests": 10, "max_retries": 3, "timeout_seconds": 300 },
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKey": "<YOUR_OPENAI_API_KEY>",
    "baseURL": "https://api.openai.com/v1",
    "maxTokens": 2000,
    "temperature": 0.3
  },
  "embedding": {
    "enabled": false,
    "base_url": "https://api.openai.com/v1",
    "api_key": "<YOUR_OPENAI_API_KEY>",
    "model": "text-embedding-3-small",
    "timeout_ms": 90000,
    "cache_ttl_ms": 1800000,
    "cache_size": 500,
    "rrf_k": 60
  }
}

• llm（可选）：provider 支持 openai/deepseek/anthropic/ollama，不配置时 evolve-engine 降级为纯规则诊断（L0 + 质量门独立运行，不依赖 LLM）
• embedding（可选）：用于经验匹配语义检索 + Alpha 向量空间。需兼容 OpenAI /v1/embeddings 接口（Ollama/Jina/OpenAI 等均可），不配置时自动降级为纯程序模式（向量空间不启用）

第 3 步：设置文件权限（保护密码）

chmod 600 ~/.wq-buddy/config.json

config.json 包含明文密码，必须设置权限为仅用户可读写。

第 4 步：注册运行时

OpenClaw：在 ~/.openclaw/openclaw.json 的 plugins.load.paths 中添加 npm 全局安装路径（通常为 ~/.npm-global/lib/node_modules/wq-buddy），然后重启 Gateway：

openclaw gateway restart

Hermes：无插件加载机制，通过 terminal 工具直接调用 wq CLI（所有 18 个命令原生可用）。Hermes 只自动加载工作目录下的 AGENTS.md，需将 npm 包内的 agent/AGENTS.md symlink 到工作目录：

ln -s $(npm root -g)/wq-buddy/agent/AGENTS.md ./AGENTS.md

Hermes 不会自动加载 SOUL.md / SAFETY.md / TOOLS.md（OpenClaw 会按 SOUL → SAFETY → TOOLS 顺序加载）。需把这三个文件的关键内容合并进工作目录的 AGENTS.md，或在该 AGENTS.md 顶部加"启动必读"清单显式 Read。

二、CLI 命令清单（20 个命令）

入口 wq + 子命令。OpenClaw 和 Hermes 下均原生可用。

模式 A：CLI 直接调用（轻量任务）

适合单条回测、字段搜索、状态查询。不占额外上下文。

L0 诊断在回测成功后也会自动触发，结果写入 alpha_diagnosis 表，并通过 alphaResult.diagnosis_patterns / diagnosis_suggested_fix 字段返回。回测返回值同时顺路捎带 evolve-engine 洞察摘要（evolve_insights / l1_triggered / l2_triggered / l3_triggered / insights_as_of，详见第四节）。wq diagnose 命令用于主动对历史 alpha 跑完整深度诊断（含 LLM 归因）。

模式 B：spawn Alpha Miner Agent（专业任务）

适合字段勘探、批量回测（≥5 条）、策略迭代、提交全流程。需要构建携带完整领域知识的专业 Agent。

Agent 知识文件（npm 包内 agent/ 目录，spawn 时注入）：

1. 工作空间规则：agent/AGENTS.md —— 启动顺序 SOUL → SAFETY → TOOLS → knowledge/wiki
2. 身份与价值观：agent/SOUL.md —— Alpha Miner 是谁、挖矿6步标准流程
3. 安全红线：agent/SAFETY.md —— 15 条安全红线
4. 工具清单：agent/TOOLS.md —— 14 个工具速查 + 6 项字段测试 + 回测参数速查
5. 领域知识库：agent/knowledge/wiki/ —— 字段分析/策略模式/优化诊断/平台资源/术语表/研究技巧/面试指南七大知识域
6. 17 类想法模板：agent/knowledge/wiki/idea-templates/

{npm_global} 路径通过 npm root -g 获取。

子 Agent 分流：回测 ≥10 条时 OpenClaw 用 sessions_spawn 开子 Agent；Hermes 用 delegate_task 替代，需在 task 描述里显式指定读 AGENTS.md。子 Agent 严格按父 Agent 给的回测任务执行，不擅自改配置。

三、决策路由

用户请求 Alpha 相关任务
│
├─ 单条表达式回测 → CLI: wq backtest "expr"（返回结果含可执行改进建议，详见 [单条优化工作流](workflows/single-alpha-optimization.md)）
├─ 搜索一两个字段 → CLI: wq search "keyword"
├─ 快速查看统计 → CLI: wq stats
├─ 查运算符/数据集/竞赛清单 → CLI: wq operators / datasets / competitions
├─ 检查 Alpha 是否可提交 → CLI: wq check <id>
├─ 提交 Alpha → CLI: wq submit <id> --yes
├─ 同步平台 Alpha 到本地 → CLI: wq sync
├─ 同步提交状态 → CLI: wq update-status <id> <状态>
├─ 列出/查相关性/查用户 → CLI: wq list / correlations / user
├─ 导出 CSV → CLI: wq export
├─ 深度诊断某条 alpha → CLI: wq diagnose --alpha <id> [--no-llm] [--json]
├─ 仅对表达式跑反模式检测 → CLI: wq diagnose --expression "rank(close)" --no-llm

└─ 以下场景 → spawn Alpha Miner Agent：
   ├─ 批量回测（≥5 条表达式）
   ├─ 字段特性勘探（6 项分析）
   ├─ 优化诊断（Sharpe/Turnover/Fitness 不达标，看 L0 诊断建议 + `wq diagnose` 深度归因）
   ├─ 策略设计（从想法到可提交 Alpha 全流程，套用 17 类想法模板）
   └─ 提交全流程闭环（待check→可提交→已提交）

四、evolve-engine 操作指引

1. 回测后看什么

每条回测完自动诊断，返回值多了以下字段：

要查完整报告：wq insights

2. 检查时机矩阵

顺路捎带字段解决"回测当下有没有新洞察"，检查时机矩阵解决"什么时候该主动翻完整报告"，两者互补。Hermes 下顺路捎带原生可用——wq backtest 的 stdout 即返回值，--json 模式更结构化，Agent 解析 stdout 即可拿到洞察摘要，无需额外适配。

五、Web UI

WQBuddy 自带本地 Web UI（http://localhost:9876），用于浏览 SQLite 数据。仅供本地使用。

启动：npm run db-viewer（源码）或全局安装后运行 wq 包内的 dist/db-viewer/server.js。

登录：与 CLI 凭证打通，任意一边登录后另一边自动免密。

六、知识库（wiki）

npm 包内 agent/knowledge/wiki/ 目录，工具模式下可主动 Read 查阅：字段分析、策略模式、17类想法模板、优化诊断、质量门禁、平台资源、术语表/研究技巧/面试指南等。

以上知识库在 Agent 模式下由 Alpha Miner 自动加载和维护，工具模式下可按需 Read。 想要完整的领域知识加持、经验自动沉淀、批量回测子 Agent 分流？切到 Agent 模式（见第二节模式 B），让专业 Agent 替你跑完整闭环。