WQBuddy

SKILL.md

---
name: wq-buddy
description: "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."
metadata:
  openclaw:
    emoji: "📊"
    requires:
      bins: ["wq"]
      config:
        - path: "~/.wq-buddy/config.json"
          access: "read-write"
          purpose: "存储BRAIN平台登录凭据、默认回测参数和 LLM 配置。平台仅支持Cookie会话认证，不支持OAuth/API Key。Token缓存4小时自动刷新。"
        - path: "~/.openclaw/openclaw.json"
          access: "read-write"
          purpose: "添加插件路径并重启Gateway"
      filesystem:
        - path: "~/.wq-buddy/alpha_workbench.db"
          access: "read-write"
          purpose: "存储Alpha回测结果、字段分析、L0诊断结果（alpha_diagnosis表）"
        - path: "~/.wq-buddy/.wq_token.json"
          access: "read-write"
          purpose: "缓存BRAIN平台登录会话Token（有效期4小时），自动刷新"
      credentials:
        - name: "BRAIN账号"
          type: "username_password"
          storage: "file"
          path: "~/.wq-buddy/config.json"
          purpose: "WorldQuant BRAIN平台登录凭据"
          note: "平台不支持OAuth/API Key，仅支持Cookie会话认证"
      install:
        - id: npm
          kind: node
          package: "wq-buddy"
          label: "Install via npm"
        - id: clawhub
          kind: clawhub
          slug: wq-buddy
          label: "Install via ClawHub"
---

# 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 分担，自己保持响应

---

## 三、决策路由

```
用户请求 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`。

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

详细使用、功能列表、设计原则见 [WEBUI.md](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 工作目录：

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