MQuant Strategy Development Assistant

---

name: matic-mquant-assistant

description: MQuant Python strategy development assistant. Generates runnable Python strategy code for MQuant platform.

metadata:

emoji: "")

references:

- reference/mquant_inside_python_document/python template.py

- reference/mquant_inside_python_document/mquant_api.py

- reference/mquant_inside_python_document/mquant_struct.py

---

# MQuant Strategy Development Assistant

Overview

This skill generates **runnable** Python strategy code for the MQuant quantitative trading platform.

**核心理念**：

**⚠️ 注意**：Matic平台**不支持回测**，策略验证需通过模拟盘或极小仓位实盘测试。

Reference Structure

reference/
├── mquantFAQ.md                    # 常见问题
├── mquant_inside_python_document/  # Python API文档
│   ├── python template.py          # Python策略模板
│   ├── mquant_api.py               # API接口定义
│   ├── mquant_struct.py            # 数据结构定义
│   ├── HTSACsvReader.py
│   └── HTSADbAccess.py
└── mquant_inside_python_strategy/  # Python策略示例
    ├── DualThrust/                 # DualThrust策略
    ├── 日频报单场景/               # 日频报单示例
    ├── 算法交易/                   # 算法交易示例
    ├── ETF轮动.py
    ├── Insight_Demo.py
    ├── R-Breaker.py
    ├── 两融接口调用示例.py
    ├── 交易数据下载.py
    ├── 增强网格策略.py
    ├── 定时撤单.py
    ├── 快捷参数多产品.py
    ├── 快捷参数示例.py
    ├── 横盘突破.py
    ├── 用户参数示例.py
    ├── 算法接口调用示例.py
    └── 调仓策略.py

Workflow

Step 0: User Environment Initialization (First Run)

**首次使用时，自动创建用户个人文档：**

检查以下文件是否存在，不存在则自动创建：

`

✓ COMMON_ERRORS.user.md (个人错误笔记)

✓ TRADING_RULES.user.md (个人交易规则)

✓ TRADING_PHILOSOPHY.user.md (个人交易理念)

`

**每个文件包含模板：**

**说明：**

---

Step 1: Directory Detection (Auto Scan)

Automatically locate the M-quant strategy directory:

全盘扫描 maticupdate.exe
    |
找到Matic安装目录，例如 D:\Matic\maticupdate.exe 或者其他形式
    |
在同级目录找 M-quant\ 文件夹
    |
在 M-quant\ 下找类似用户名的文件夹，比如：
    ├── userA\
    ├── userB\
    └── trader001\
    |
询问用户将策略代码保存到哪个目录

**Scan Rules:**

**Failure Handling:**

Step 2: Language Selection

询问用户选择编程语言：

请选择要生成的策略代码类型：
1. Python (推荐，快速开发、易于调试)
2. C++ (高性能，需要自行编译为DLL)

**⚠️ 重要提醒**：AI生成的代码请务必在Matic测试环境中充分调试验证后再用于实盘交易。

Step 3: Version Control

Auto-generate versioned filenames:

命名格式: `xxxxx_vN.py` （MQuant限制：py文件名不能超过11个字符）

首次生成:  duoma_v1.py      + duoma_v1.log      (version: 1)
再次生成:  duoma_v2.py      + duoma_v2.log      (version: 2)
第三次:   duoma_v3.py      + duoma_v3.log      (version: 3)

**命名规则**：

实际示例：

**Retention Rules:**

**Version Diff（版本对比）**

当生成新版本时，自动对比上一版本的变更：

===== VERSION DIFF: v1 → v2 =====
变更摘要举例：
+ 增加了止损逻辑（固定金额止损）
+ 修改了入场条件（由金叉改为量价齐升）
- 删除了冗余的日志输出
~ 调整了网格间距（由1%改为2%）

详细对比：
[可选：展示关键代码差异]

用户可通过对比快速了解迭代改进了什么。

Step 4: Strategy Parameter Wizard

在生成代码前，主动引导用户配置策略参数：

**询问方式**：

您选择了[策略名称]，请配置以下参数：
1. 交易标的：[股票代码/期货合约] 
2. [参数1]：[默认值]，建议范围[min-max]
3. [参数2]：[默认值]，建议范围[min-max]
...

**说明**：提供默认值和合理范围，用户可直接使用或自行调整。

Step 5: Code Generation

**生成原则：可运行 > 完美**

1. 基于模板生成策略代码，确保：

- 语法正确，可直接运行

- API调用符合Matic规范

- **必须包含日志写入功能**

- 包含基本的异常处理

**重要API限制（必须遵守）**：

2. 保存 `.py` 文件到选定目录

3. 同步保存 `.log` 文件（包含生成元数据）

**代码验证清单**：

**严格遵守文档定义（避免运行时错误）**：

生成代码时，必须严格按照 `mquant_api.py` 和 `mquant_struct.py` 中的定义，不得凭记忆或推测。

**API调用必须核对：**

| API | 文档定义 | 常见错误 |

|-----|----------|----------|

| subscribe | `subscribe(security, MarketDataType.XXX)` | 使用字符串'1d' ❌ |

| handle_tick | `handle_tick(context, tick, msg_type)` | 参数顺序错误 ❌ |

| handle_data | `handle_data(context, kline_data)` | 参数名错误 ❌ |

| order | `order(symbol, amount)` | 参数类型错误 ❌ |

| get_positions | `get_positions()` | 无参数 ✅ |

**结构体字段必须核对：**

| 结构体 | 正确字段 | 常见错误 |

|--------|----------|----------|

| Tick | `tick.code`, `tick.current` | `tick.last` ❌ |

| Tick | `tick.open`, `tick.high`, `tick.low` | - |

| Position | `pos.symbol`, `pos.amount` | `pos.code` ❌ |

| KLineDataPush | `kline.close`, `kline.high` | - |

**重要：get_positions() 返回类型**

`get_positions()` 返回 **字典** `dict<symbol, Position>`，不是列表！

**错误用法：**

positions = get_positions()
for pos in positions:  # ❌ 这样遍历得到的是symbol字符串
    if pos.symbol == g_security:  # ❌ 'str' object has no attribute 'symbol'

**正确用法：**

# 方法1: 使用get()从字典获取
positions = get_positions()
pos = positions.get(g_security)
amount = pos.amount if pos else 0

# 方法2: 遍历字典的值
positions = get_positions()
for symbol, pos in positions.items():
    if symbol == g_security:
        amount = pos.amount

**替代方案：**

如需列表，使用 `get_positions_ex()` 返回 `list<Position>`

**生成前必读：**

1. 查阅 `reference/mquant_inside_python_document/mquant_api.py` 确认API签名

2. 查阅 `reference/mquant_inside_python_document/mquant_struct.py` 确认字段名

3. 不确定的API或字段，禁止在代码中使用

**Generated code must include:**

from mquant_api import *
from mquant_struct import *
import os
from datetime import datetime


LOG_FILE = None

def write_log(level, msg):
    """Write log to .log file, synced with Matic log window"""
    global LOG_FILE
    if LOG_FILE is None:
        current_file = os.path.abspath(__file__)
        base_name = os.path.splitext(current_file)[0]
        LOG_FILE = base_name + '.log'
    
    timestamp = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
    log_line = f"[{timestamp}] [{level}] {msg}\n"
    
    try:
        with open(LOG_FILE, 'a', encoding='utf-8') as f:
            f.write(log_line)
    except:
        pass  # Write failure should not affect strategy execution

**详细日志记录要求（便于问题排查）：**

所有策略必须记录以下信息到日志：

**1. 初始化阶段：**

**2. 行情数据阶段：**

**3. 判断逻辑阶段：**

**4. 交易执行阶段：**

**示例日志格式：**

def handle_tick(context, tick, msg_type):
    # 1. 记录原始数据
    write_log('DEBUG', f'Tick received: code={tick.code}, price={tick.current}')
    
    # 2. 计算逻辑
    current_price = tick.current
    grid_idx = calculate_grid(current_price)
    write_log('DEBUG', f'Calculated: price={current_price}, grid_idx={grid_idx}, last_idx={g_last_idx}')
    
    # 3. 判断逻辑
    if grid_idx < g_last_idx:
        write_log('INFO', f'Trigger BUY: idx {g_last_idx}->{grid_idx}, price={current_price}')
        # 4. 执行结果
        result = order(g_security, g_amount)
        write_log('INFO', f'Order result: {result}')
    else:
        write_log('DEBUG', f'No trade: idx={grid_idx}, last_idx={g_last_idx}, condition=False')

**日志级别规范：**

**排查问题时的日志检查点：**

1. 行情数据是否接收？→ 检查DEBUG日志的tick/kline数据

2. 计算是否正确？→ 检查计算的索引、均线值等

3. 判断条件是否满足？→ 检查条件判断的True/False

4. 交易是否执行？→ 检查order()调用和返回值

API Quick Reference

Market Data

- `MarketDataType.TICK` - Tick行情 (handle_tick)

- `MarketDataType.KLINE_1M` - 1分钟K线 (handle_data) ✅ 最常用

- `MarketDataType.RECORD_ORDER` - 逐笔委托

- `MarketDataType.RECORD_TRANSACTION` - 逐笔成交

- **注意：不支持日线订阅，需用1分钟K线累积**

Trading

Query

Step 6: Code Explanation Mode (Optional)

用户可要求"解释这段代码"，提供以下输出：

**1. 策略逻辑概述**

**2. 关键代码行注释**

# 初始化：设置日志和变量
initialize(context):
    
# 订阅行情：监听指定股票的分钟线
subscribe('000001.SZ', '1m')
    
# 交易逻辑：当短期均线上穿长期均线时买入
if short_ma > long_ma:
    order(...)

**3. 风险提示**

Language Support

Python Strategy

Unified Log Format

每次生成策略时，创建一个 `.log` 文件，策略运行时将日志追加到同一文件：

strategy_name.py
strategy_name.log  <- Generation metadata + Runtime logs (unified)

**.log File Structure:**

===== GENERATION META =====
{
  "version": 1,
  "previous": null,
  "generated_at": "2026-03-05 18:00:00",
  "model": "moonshot/kimi-k2.5",
  "template": "Dual MA",
  "params": {"fast_ma": 5, "slow_ma": 20},
  "target_path": "D:\\Matic\\M-quant\\userA\\",
  "matic_exe_path": "D:\\Matic\\maticupdate.exe",
  "changelog": "Initial version"
}

===== RUNTIME LOG =====
[2026-03-05 22:20:01] [INFO] Strategy started
[2026-03-05 22:20:01] [INFO] Target price: 18.50, Order amount: 100
[2026-03-05 22:20:05] [INFO] Condition triggered! Current 18.45 <= Target 18.50
[2026-03-05 22:20:05] [INFO] Buy order sent: 601688.SH, Order ID 12345

**Runtime Debugging:**

Step 1: 错误识别

分析错误日志，分类问题类型：

Step 2: 定位问题

根据错误堆栈定位到具体代码行，结合`.log`文件中的生成元数据：

Step 3: 一键修复

提供修复方案：

``