Quant2Ptrader-MCP

# 📘 Quant2Ptrader-MCP 使用指南 ## 🎯 功能说明 将聚宽（JoinQuant）策略代码自动转换为Ptrade格式，支持两种输入方式： ### 方式1: 直接输入代码（code参数） - 适合短代码片段 - 直接粘贴代码即可 - 无需保存文件 ### 方式2: 文件路径（filepath参数）⭐ 推荐长代码使用 - 适合完整策略文件 - 支持格式：`.py`, `.txt`, `.text`, `.code`, `.strategy` - 避免复制粘贴长代码 ## 📝 参数说明 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `code` | string | 否* | 聚宽策略的完整Python代码 | | `filepath` | string | 否* | 策略文件的完整路径 | | `output_dir` | string | 否 | 输出目录路径（可选，默认为原文件目录或当前目录）⭐ **新增** | **注意**: - `code` 和 `filepath` 至少要提供一个，优先使用 `filepath` - `output_dir` 为可选参数，不提供时自动决定输出位置 ## 💬 使用示例 ### 示例1: 在Claude中直接输入代码 ``` 请将这个聚宽策略转换为Ptrade格式： from jqdata import * def initialize(context): set_benchmark('000300.XSHG') def handle_data(context, data): order('000001.XSHE', 100) ``` ### 示例2: 在Claude中提供文件路径 **Windows路径：** ``` 请转换这个策略文件： C:\Users\YourName\Documents\my_strategy.py ``` **Linux/Mac路径：** ``` 请转换这个策略文件： /home/user/strategies/double_ma.py ``` ### 示例3: 相对路径 ``` 请转换当前目录下的策略文件： ./strategies/my_strategy.txt ``` ### 示例4: 指定输出目录 ``` 请转换这个文件，并保存到指定目录： 文件路径: C:\Users\Me\my_strategy.py 输出目录: D:\ptrade_output\ ``` ## 📊 转换报告格式 转换完成后，会生成详细报告，包括： ### 1. 源文件信息 ``` 📄 源文件信息 文件: my_strategy.py ``` 或 ``` 📄 源文件信息 直接输入的代码 ``` ### 2. 转换状态 ``` ✅ 转换状态：成功 ``` ### 3. 输出文件信息 ⭐ **重点** ``` 💾 输出文件 文件路径: C:\Users\Me\my_strategy_ptrade.py 文件名: my_strategy_ptrade.py 文件大小: 1644 字节 ``` **关键点**：转换后的代码已自动保存为.py文件，可直接使用！ ### 4. 代码修改详情 ``` 📝 代码修改详情（共 N 处） 修改 1：第 2 行 - 原代码: from jqdata import * - 新代码: from ptrade.api import * - 原因: 更新导入模块为Ptrade ``` ### 5. 注意事项 ``` ⚠️ 注意事项（N 项） 1. 检测到日志输出函数，Ptrade使用相同的log对象，无需修改 2. ... ``` ### 6. 代码预览 ``` 🎯 转换后的Ptrade代码（已保存） 代码已成功保存到文件，可直接使用！ 如需查看代码内容，打开文件：C:\...\my_strategy_ptrade.py <折叠的代码预览> ``` **注意**：完整代码在生成的.py文件中，不再完整显示在报告中 ### 7. 下一步操作 - 🎯 **直接使用文件**：将生成的.py文件上传到Ptrade平台 - ⚠️ **检查注意事项** - 🧪 **运行回测验证** - 🔧 **调整参数** ## 🔧 支持的文件格式 | 格式 | 扩展名 | 说明 | |------|--------|------| | Python | `.py` | 标准Python文件 | | 文本 | `.txt` | 纯文本格式 | | 文本 | `.text` | 纯文本格式（全称） | | 代码 | `.code` | 代码文件 | | 策略 | `.strategy` | 策略文件 | ## ❌ 常见错误处理 ### 错误1: 文件不存在 ``` ❌ 转换失败: 文件不存在: /path/to/file.py ``` **解决**: 检查文件路径是否正确，确保文件存在 ### 错误2: 不支持的文件格式 ``` ❌ 转换失败: 不支持的文件格式: .doc 支持的格式: .py, .txt, .text, .code, .strategy ``` **解决**: 将文件另存为支持的格式 ### 错误3: 未提供参数 ``` ❌ 转换失败: 请提供策略代码（code参数）或文件路径（filepath参数） ``` **解决**: 至少提供 code 或 filepath 参数之一 ### 错误4: 代码为空 ``` ❌ 转换失败: 策略代码不能为空 ``` **解决**: 确保文件不是空的，或者提供有效的代码内容 ## 🎨 完整使用流程 ### Step 1: 准备策略文件 将聚宽策略保存为 `.py` 或 `.txt` 文件 ### Step 2: 配置MCP服务器 在Claude Desktop配置中添加： ```json { "mcpServers": { "quant2ptrader": { "command": "npx", "args": ["-y", "quant2ptrader-mcp"] } } } ``` ### Step 3: 在Claude中调用 提供文件路径或直接粘贴代码 ### Step 4: 获取转换结果 查看详细报告和转换后的代码 ### Step 5: 复制到Ptrade 将转换后的代码复制到Ptrade平台 ### Step 6: 测试验证 在Ptrade上运行回测验证策略 ## 💡 最佳实践 ### ✅ 推荐做法 1. **长代码使用文件路径**：超过50行的策略建议保存为文件后传路径 2. **使用.py扩展名**：虽然支持多种格式，但.py最标准 3. **绝对路径优先**：避免相对路径可能的歧义 4. **转换前备份**：保留原始聚宽代码作为备份 5. **回测验证**：转换后务必在Ptrade上回测验证 ### ❌ 避免做法 1. 不要直接在生产环境使用未测试的转换代码 2. 不要忽略警告信息中的兼容性提示 3. 不要假设100%兼容，部分API可能需要手动调整 4. 不要使用不支持的文件格式 ## 🔍 API转换规则 ### 完全兼容（无需修改） - `initialize()`, `handle_data()` - `order()`, `order_target()`, `order_value()`, `order_target_value()` - `set_benchmark()`, `set_commission()`, `set_slippage()` - `get_price()`, `attribute_history()`, `get_current_data()` - `context.portfolio`, `context.run_info` - `log.info()`, `log.warn()` ### 自动转换 - `from jqdata import *` → `from ptrade.api import *` - `import jqdata` → `import ptrade` ### 需要注意 - `run_daily()`, `run_weekly()`, `run_monthly()` - 时间参数格式 - `get_index_stocks()` - 参数格式 - `get_fundamentals()` - 查询语法 ## 📞 获取帮助 - 📝 GitHub Issues: https://github.com/guangxiangdebizi/quant2ptrader-mcp/issues - 📧 Email: guangxiangdebizi@gmail.com - 📖 完整文档: 见 README.md --- **Happy Trading! 🚀**