WQBuddy

Provides CLI tools (wq) and a specialized Alpha Miner sub-agent for WorldQuant BRAIN, with v1.1.0 evolve-engine (L0 diagnosis / 8 hard gates / 8-dimension penalty / safety / LLM). Use for backtesting alpha expressions, searching BRAIN data fields, analyzing field characteristics, browsing datasets, querying operators, checking competition progress, and submitting alphas. For simple single-expression backtests, use CLI directly. For complex workflows (field exploration, batch backtesting, strategy iteration, submission management), spawn the Alpha Miner agent which has its own domain knowledge base. Each backtest auto-runs L0 diagnosis (12 failure patterns + suggested_fix), piggybacks L1/L2/L3 insights, and runs the 8 hard gates + 8-dimension penalty check before submission. Also includes a local Web UI (npm run db-viewer or run dist/db-viewer/server.js) for browsing the SQLite database (alphas / field tests / data fields / batches) with auto-login sharing credentials with the CLI.

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 包

bash

npm install -g wq-buddy

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

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 步：设置文件权限（保护密码）

bash

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

bash

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 时注入）：

1. 工作空间规则：agent/AGENTS.md —— 启动顺序 SOUL → SAFETY → TOOLS → MEMORY → knowledge/wiki
2. 身份与价值观：agent/SOUL.md —— Alpha Miner 是谁、挖矿6步标准流程
3. 安全红线：agent/SAFETY.md —— 15 条安全红线
4. 工具清单：agent/TOOLS.md —— 14 个工具速查 + 6 项字段测试 + 回测参数速查
5. 经验记忆：agent/MEMORY.md —— 经验沉淀区
6. 领域知识库：agent/knowledge/wiki/ —— 字段分析/策略模式/优化诊断/平台资源四大知识域
7. 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 分担，自己保持响应

---

三、决策路由

text

用户请求 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 步流程

text

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。

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

详细使用、功能列表、设计原则见 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 命令：

text

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 工作目录：

bash

# 在 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 直接调用，无代码改动。