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

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

v1.1.0 新增 evolve-engine 模块：每条回测完自动诊断、提交前质量门检查、安全红线硬约束、可选 LLM 增强（Zod schema 强校验结构化输出）。回测返回值顺路捎带自上次以来新增的 L1/L2/L3 洞察摘要，无需额外查询。

一、安装

第 1 步：安装 npm 包

npm install -g wq-buddy

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

{
  "version": "v1.1.0",
  "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 字段说明（v1.1.0 新增，可选）：

provider：openai / deepseek / anthropic / ollama，openai/deepseek/ollama 用 OpenAI 兼容格式，anthropic 用 Messages API
不配置 llm 字段时，createLLMClient 返回 null，evolve-engine 降级为纯规则诊断（不报错）
LLM 仅用于增强诊断建议，规则诊断（L0 + 质量门）独立运行，不依赖 LLM

embedding 字段说明（v1.1.0 新增，可选）：

用于 evolve-engine 经验匹配的语义检索增强，不配置时自动降级为纯程序模式
启用条件："enabled": true 且 base_url 和 model 均非空；缺任意一项则视为 enabled: false
服务地址需兼容 OpenAI /v1/embeddings 接口，例如 Ollama（http://localhost:11434/v1）、Jina AI、OpenAI 等
provider 无关（embedding 统一走 OpenAI 兼容格式），仅需配置 base_url / api_key / model

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

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

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

第 4 步：注册插件路径

在 ~/.openclaw/openclaw.json 的 plugins.load.paths 中添加 npm 全局安装路径（通常为 ~/.npm-global/lib/node_modules/wq-buddy）。

第 5 步：重启 Gateway

openclaw gateway restart

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

入口 wq + 子命令。

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

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

| 命令 | 简写 | 用途 | |------|------|------| | wq backtest "expr" | bt | 单条/批量回测，支持 --file --concurrency 1-3 --enable-duplicate-check 以及 --decay/--neutralization/--truncation/--region/--universe 参数覆盖 | | wq search "kw" | s | 搜索数据字段，支持 --dataset --limit | | wq analyze <field> | a | 字段特性分析（6项测试） | | wq stats | — | 回测统计报告 | | wq export [alpha\|field] | — | 导出 CSV | | wq docs | — | 内置运算符文档（6 大类快速参考） | | wq operators | op | 平台 API 获取运算符清单，支持 --category | | wq datasets | ds | 浏览平台数据集，支持 --category --region --universe | | wq competitions | cp | 用户竞赛进度 | | wq check <alphaId> | ck | 提交前检查 IS Checks（模式B，需登录） | | wq submit <alphaId> --yes | sm | 正式提交 Alpha（不可逆，需 --yes） | | wq correlations <alphaId> | cr | 查询 Alpha 相关性 | | wq list | ls | 列出本地/平台 Alpha，支持 --status --limit --offset | | wq user | ui | 当前用户信息 | | wq update-status <id> <状态> | us | 更新提交状态（已通过/已提交/提交失败） | | wq diagnose --alpha <id> | dg | 对指定 alpha 跑深度诊断（L0 规则 + L1 统计 + L2 聚类 + 单轮 LLM 归因 + 反模式检测），支持 --expression / --no-llm / --json | | wq insights | in | 输出 evolve-engine 整体洞察报告（L1/L2/L3/衰减/审计/反模式/知识检索），支持 --section / --since / --json / --search <kw>（diary-search 全文检索） | | wq help | — | 帮助 |

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

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

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

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

工作空间规则：agent/AGENTS.md —— 启动顺序 SOUL → SAFETY → TOOLS → MEMORY → knowledge/wiki
身份与价值观：agent/SOUL.md —— Alpha Miner 是谁、挖矿6步标准流程
安全红线：agent/SAFETY.md —— 15 条安全红线
工具清单：agent/TOOLS.md —— 14 个工具速查 + 6 项字段测试 + 回测参数速查
经验记忆：agent/MEMORY.md —— 经验沉淀区
领域知识库：agent/knowledge/wiki/ —— 字段分析/策略模式/优化诊断/平台资源四大知识域
11 类想法模板：agent/knowledge/wiki/idea-templates/

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

spawn 关键约束：

任务描述要明确具体，如"分析 fnd2_oper_income 字段，构建 3 条动量类 Alpha 并回测"
Alpha Miner 拥有独立 SQLite 记忆，每次会话后经验自动沉淀
回测 ≥10 条时 Agent 会 sessions_spawn 子 Agent 分担，自己保持响应

三、决策路由

用户请求 Alpha 相关任务
│
├─ 单条表达式回测 → CLI: wq backtest "expr"
├─ 搜索一两个字段 → CLI: wq search "keyword"
├─ 快速查看统计 → CLI: wq stats
├─ 查运算符/数据集/竞赛清单 → CLI: wq operators / datasets / competitions
├─ 检查 Alpha 是否可提交 → CLI: wq check <id>
├─ 提交 Alpha → CLI: wq submit <id> --yes
├─ 同步提交状态 → 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 全流程，套用 11 类想法模板）
   └─ 提交全流程闭环（可提交→确认→已通过）

四、evolve-engine 操作指引

1. 回测后看什么

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

| 字段 | 含义 | 怎么用 | |------|------|--------| | diagnosis_patterns | 命中的失败模式标签 | 看"哪里有问题" | | diagnosis_suggested_fix | 改进建议 | 按建议改表达式 | | evolve_insights | 新增的 L1/L2/L3 洞察摘要 | 一眼看出"有没有新经验产出" | | l1_triggered / l2_triggered / l3_triggered | 是否触发了统计/聚类/抽象 | 触发后应翻完整报告 | | insights_as_of | 摘要截止时间 | — |

要查完整报告：wq insights

2. 挖矿 6 步流程

1. 找灵感      ── 翻 agent/knowledge/wiki/idea-templates/（11类想法模板）
2. 抄模板      ── 选一个想法，复制基础/进阶/高级模板表达式
3. 摸数据底细  ── analyzeField 做6种字段测试
4. 模板+AI批量 ── 改字段/参数组合，alphaBatchSubmit 批量回测
5. 防过拟合    ── 看 diagnosis_patterns + suggested_fix
6. 提交前质量门 ── checkSubmission 自查，通过后 submitAlpha

3. 检查时机矩阵

| 触发时机 | 该查什么 | 命令 | |---|---|---| | 会话启动 | 最近失败模式 / 策略建议 / 衰减状态 | wq insights | | 回测完想知根因 | L0 诊断 + LLM 归因 + 反模式 | wq diagnose -a <id> | | 攒了一批失败想找规律 | L1 统计 + L2 聚类 + 反模式 Top | wq insights --section l1 / --section l2 | | 找历史类似案例 | 全文检索 | wq insights --search "<关键词>" | | 怀疑知识过时 | decay 状态 | wq insights --section decay |

顺路捎带字段解决"回测当下有没有新洞察"，检查时机矩阵解决"什么时候该主动翻完整报告"，两者互补。

五、14 个工具完整清单

对 Agent 暴露 14 个工具。

| 工具 | 用途 | CLI 对应 | |------|------|----------| | alphaBatchSubmit | 批量回测（confirmed 必填，concurrency 1-3） | wq backtest | | searchFields | 搜索字段（支持 dataset / limit） | wq search | | analyzeField | 字段 6 项测试（覆盖率/非零/频率/范围/方向/分布） | wq analyze | | alphaStats | 回测统计报告 | wq stats | | updateSubmitStatus | 更新提交状态（已通过/提交失败/已提交） | wq update-status | | updateCorrelation | 更新 Alpha 相关性数值 | — | | checkSubmission | 提交前 IS Checks 检查 | wq check | | submitAlpha | 提交 Alpha（confirmed 必填，仅单条） | wq submit | | getAlphaCorrelations | 查询 Alpha 相关性 | wq correlations | | listAlphas | 列出 Alpha（status/limit/offset） | wq list | | getUserInfo | 当前用户信息 | wq user | | getOperators | 平台运算符清单（含分类筛选） | wq operators | | listDatasets | 浏览数据集（category/region/universe） | wq datasets | | getCompetitions | 用户竞赛进度 | wq competitions |

工具 schema 用 TypeBox 定义，所有 BRAIN 平台调用前由 getAuthSession 自动处理登录。

六、Web UI

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

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

详细使用、功能列表、设计原则见 WEBUI.md。

七、Agent 行为指引（核心要点）

详细见 agent/AGENTS.md 和 agent/SOUL.md，关键约束：

覆盖率比 Sharpe 更值钱：99% 覆盖率的平庸字段比 40% 覆盖率的高 Sharpe 字段有用十倍
低相关性胜过一切：提交前必查相关性，不和已有 Alpha 撞车（self_correlation ≤ 0.7）
每个参数都要有原因：基本面信号配高 Decay（10-20），量价信号配低 Decay（3-10）
失败是数据：FAIL-LOW_SHARPE 比勉强通过的 Alpha 教更多，记录到 MEMORY.md
用户是基金经理：不擅自改配置重跑，不擅自提交，不编造 correlation
回测必须阻塞式：禁止后台执行 + 轮询，遇 429 由工具内部处理
提交必须 confirmed=true：禁止自动改提交状态，禁止批量提交
MEMORY/rules/ 只读：evolve-engine 不可修改规则文件，wiki/SAFETY.md 不可修改

八、Hermes 适配

WQBuddy 原生面向 OpenClaw（spawn Alpha Miner Agent + sessions_spawn 子 Agent）。Hermes 是另一套 Agent 运行时，加载机制不同，需做以下适配。

1. CLI 调用方式

Hermes 没有 WQBuddy 插件加载机制，通过 terminal 工具直接调用 wq CLI 命令：

terminal: wq backtest "rank(close)"
terminal: wq diagnose -a <alpha_id> --json
terminal: wq insights --section l1

所有 18 个 CLI 命令（见第二节）在 Hermes 下原生可用，前提是 wq-buddy 已 npm install -g 且 ~/.wq-buddy/config.json 配置完成。

2. AGENTS.md symlink

Hermes 只自动加载工作目录下的 AGENTS.md。把 npm 包内的 agent/AGENTS.md symlink 到 Hermes 工作目录：

# 在 Hermes 工作目录执行
ln -s {npm_global}/wq-buddy/agent/AGENTS.md ./AGENTS.md

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

3. SOUL / SAFETY / TOOLS / MEMORY 合并

Hermes 不会自动加载 SOUL.md / SAFETY.md / TOOLS.md / MEMORY.md（OpenClaw 会按 SOUL → SAFETY → TOOLS → MEMORY 顺序加载）。两种方案：

方案 A（推荐）：把上述四个文件的关键内容合并进 Hermes 工作目录的 AGENTS.md（或 Hermes 的 SOUL.md 若存在）
方案 B：在 AGENTS.md 顶部加一段"启动时必读"清单，显式 Read 这四个文件

合并时保留：SAFETY 的 15 条红线、TOOLS 的 14 个工具速查、SOUL 的 6 步流程、MEMORY 的经验沉淀区。

4. 子 Agent：delegate_task 替代 sessions_spawn

OpenClaw 用 sessions_spawn 开子 Agent 跑批量回测。Hermes 用 delegate_task 替代：

| 场景 | OpenClaw | Hermes | |------|----------|--------| | 回测 ≥10 条分流 | sessions_spawn 子 Agent | delegate_task 子 Agent | | 子 Agent 配置 | 继承父 Agent 知识库 | 需在 delegate_task 描述里显式指定读 AGENTS.md |

子 Agent 严格按父 Agent 给的回测任务执行，不擅自改配置。

5. 顺路捎带原生可用

顺路捎带方案（第四节小节 7）在 Hermes 下原生可用：wq backtest 的 stdout 即返回值，evolve_insights / l1_triggered / l2_triggered / l3_triggered / insights_as_of 字段直接出现在 CLI 输出的 JSON 里（--json 模式更结构化）。Hermes Agent 解析 stdout 即可拿到洞察摘要，无需额外适配。

Hermes 适配的核心工作量在"知识文件合并"（第 3 点），其余都是 CLI 直接调用，无代码改动。