Vibe-Trading backtest-diagnose 技能从回测失败到硬门禁证据的完整诊断方法论【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading本文围绕 Vibe-Trading 的 backtest-diagnose 技能 展开讲解该技能为“回测失败、报错或结果异常”设计的一套五步诊断工作流、三类错误分类法运行时错误 / 逻辑缺陷 / 数据问题以及数据源忽略清单并深入其 Hard-Gate Checklist 在 策略发现证据系统 中的源码级落地。读完后你可以掌握一套可复制的回测排障流程从检查artifacts/产物到精确定位根因、实施最小修复、并通过 AST 校验与重跑验证理解为什么“不健康的回测运行”在证据管线中会被整体拒绝而不是部分入库。适用场景与总体思路该技能的 frontmatter 将其定义为category: tool的工具型技能触发条件是用户报告回测失败、抛出异常或产出糟糕的结果。技能的核心假设是回测运行目录run dir本身就是诊断现场——运行状态、指标、权益曲线与成交记录都以文件形式落盘因此诊断的第一步永远是读产物而不是猜。技能文档给出的标准诊断工作流为五步读取现有产物用read_file检查artifacts/metrics.csv、equity.csv与trades.csv读取代码用read_file检查code/signal_engine.py与config.json分类问题使用下文错误分类法Error Taxonomy判定根因类别实施修复用edit_file修改代码然后重跑回测验证修复用read_file检查新的metrics.csv。这套流程与 Vibe-Trading 回测引擎的产物落盘机制是一一对应的。引擎在 agent/backtest/engines/base.py 的_write_artifacts方法中统一写出三类文件equity.csv逐 bar 的timestamp、ret、equity、drawdown、benchmark_equity、active_ret列、trades.csvtimestamp, code, side, price, qty, reason, pnl, holding_days, return_pct且每个完整回合写入两行——pnl0.0的入场行加带已实现盈亏的出场行以及metrics.csv一行表头加一行取值含trade_count等指标。产物解析侧则由 agent/src/strategy_discovery/run_artifacts.py 以纯只读 CSV I/O 完成不触网、不虚构——这与技能“先读产物再下结论”的思路互为印证。错误分类法Error Taxonomy技能把回测问题划分为三大类运行时错误、逻辑缺陷、数据错误并额外提供一份“数据源错误忽略清单”。以下完整继承技能文档的分类并结合源码补充可验证细节。运行时错误exit_code ! 0错误类型常见原因修复ImportError缺少依赖bash(pip install xxx)KeyErrorDataFrame 列名不匹配检查data_map中的实际列名IndexError数据为空或长度不足增加长度检查TypeError信号类型不正确确保返回值为pd.Series这一类的问题特征是进程直接以非零退出码结束。注意在策略发现证据管线中非零退出对应运行目录state.json的status不为success——agent/src/strategy_discovery/run_artifacts.py 的read_run_status读取该字段state.json缺失或不可读时按失败处理fail-closed映射到硬门禁 tokenhard-gate:exit-nonzero。逻辑缺陷回测成功但结果异常这是最容易被误判为“策略不好”的一类实际上多为代码 bug零交易trade_count0信号逻辑 bug。条件过严导致信号恒为 0。应检查入场/出场逻辑是否合理并检视信号序列确认是否全零。交易过晚首笔交易发生在回测开始 2 年之后数据过滤 bug。回看窗口可能过长或初始数据段被丢弃。应缩短窗口或检查dropna是否过于激进。资金利用率 50%大部分时间持有现金仓位管理 bug。信号触发可能过于稀疏或仓位计算逻辑有误。期末仍持仓回测结束时仍存在持仓出场时机 bug。可能缺少强制平仓或出场逻辑未覆盖最后一段行情。其中“零交易”一项与硬门禁的trade_count 0检查直接对应“期末仍持仓”则解释了为什么引擎的trades.csv用零盈亏行作为入场标记——只有配对完整的回合才能被下游 agent/src/strategy_discovery/run_artifacts.py 的read_trade_activity正确计为一次成交仅计出场行避免一行一进一出的回合被重复计数。数据错误症状根因修复未取到数据API token 无效或代码问题检查config.json数据量过少日期范围过窄扩大日期范围数据源错误忽略清单技能明确列出一组遇到时不应修改代码的关键词因为问题在数据提供方一侧数据方返回的 no data available 响应rate limitAPI limitdaily limitInformationTushare API 响应中常见这类问题的正确处置是让用户检查 API token、切换数据源或等待配额重置而不是无谓地改动信号引擎代码。Hard-Gate Checklist 与证据摄入门禁技能文档定义了五项硬门禁检查artifacts/metrics.csv存在且非空artifacts/equity.csv存在且非空trade_count 00 笔交易意味着信号 bug权益序列不含NaNexit_code 0。关键在于这份清单不只是给 Agent 的自我检查表——它同时就是策略发现Strategy Discovery证据摄入的门禁。在 agent/src/strategy_discovery/evidence_harness.py 中check_run_hard_gates按固定顺序实现五道门禁并与清单 1:1 映射为稳定的机器可读 token检查顺序检查内容失败 token1state.json存在且status success缺失时同样落到该 tokenhard-gate:exit-nonzero2artifacts/metrics.csv存在且非空hard-gate:metrics-missing3metrics.csv中trade_count 0含可解析性检查hard-gate:zero-trades4artifacts/equity.csv存在、非空且可读hard-gate:equity-empty5权益序列任意位置不含 NaN/非有限值hard-gate:equity-nan实现上有几个值得注意的设计取舍从源码结构看整体拒绝而非部分计算任一门禁失败该运行不产出任何证据行——永远不会有“部分曲线”的半截证据。第 5 道门禁的读者 equity_has_non_finite 特意不跳过坏行曲线中途出现 NaN 意味着序列结构性损坏与read_equity_series那种“跳过不可用行”的宽松解析形成对照。fail-closed 原则metrics.csv缺少trade_count列、值不可解析或state.json不可读一律按失败处理而不是猜测。资格性与充分性分离metrics.csv的trade_count只认证运行“资格”结构健康每制度regime证据行的充分性由 harness 自己按 trades.csv 的完整回合计数把关。两者可以不一致例如只有入场没有出场会抬高trade_count却不增加完整回合这是有意为之的设计。测试文件 agent/tests/test_strategy_discovery_hard_gates.py 固定了上述契约NaN 出现在权益曲线中途会整体跳过该运行不产出任何部分曲线证据行作为 Phase 1 静默跳过隐患的回归测试且重建过程是原子的——计算中途崩溃不会清空已有缓存。与 Strategy Discovery 的联动修复后如何回填证据技能文档的 “Evidence hookup” 一节说明了完整的闭环一次运行失败任一硬门禁就不产出证据行并以稳定的 token 被跳过。标准的修复闭环是按本文前述分类法诊断并修复失败的门禁重跑回测确认新的metrics.csv通过检查用refresh_strategy_evidenceAgent 工具 / MCP 工具或 CLI 命令vibe-trading strategy-evidence refresh --manifest path回填证据缓存使修复后的运行变为可查询的证据。CLI 入口在 agent/cli/commands/strategy_evidence.pyvibe-trading strategy-evidence只暴露refresh子命令内部调用与 Agent 工具同一核心函数refresh_strategy_evidence_core查询类操作list_strategies/query_strategies/get_strategy_evidence保留在 Agent 工具侧不进入 CLI。Manifest 的格式见 strategy-discovery 技能文档为包含runs数组的 JSON 对象或裸数组{ runs: [ {strategy_id: sdm:my_strategy, run_dir: ~/.vibe-trading/runs/20260701-123456-abcdef, position_size: 0.25}, {strategy_id: alpha_zoo:gtja191_171, run_dir: ~/.vibe-trading/runs/20260702-234567-bcdef0} ] }每个run_dir必须解析到运行时 runs 根目录或VIBE_TRADING_ALLOWED_RUN_ROOTS之内越界的条目以path-outside-allowed-roots:被跳过其余条目继续处理。重建是原子的所有行先全部计算完成再在单个事务中整体替换缓存——计算中途失败时旧缓存完整保留。修复原则Fixing Principles技能文档给出的四条修复纪律用edit_file做精确的代码修复而非用write_file重写整个文件——除非结构已彻底损坏只修 bug除非用户明确要求否则不改动策略逻辑本身一次只修一个问题每次修复后立即重跑回测修复迭代最多 3 轮避免无限打补丁。修复后验证规则Post-Fix Validation Rules修改signal_engine.py之后技能要求逐项确认AST 语法通过执行bash(python -c \import ast; ast.parse(open(code/signal_engine.py).read()); print(OK)\)包含class SignalEngine文件必须定义class SignalEngine包含def generate该类必须含有def generate方法重跑回测修复后重跑并验证结果。前两条结构检查类名与generate方法对应回测引擎加载信号引擎的契约引擎按约定导入运行目录code/下的信号引擎类并调用其generate方法产生信号序列因此信号引擎缺类或缺方法属于典型的“运行成功不了”一类运行时错误。action_items输出规范诊断完成后需要输出可执行的改进建议技能文档规定了写法格式Change X from A to B或Add X logic in signal_engine.py必须具体到参数值、文件名与函数名至少给出 2 条示例Change RSI threshold from 30 to 25 in signal_engine.py line 42Add signals signals.fillna(0) after signal calculation to prevent NaN propagationAdd a volume filter: skip buy signals when volume is below the 20-day average第二条示例fillna(0)防 NaN 传播与硬门禁第 4 项“权益序列不含 NaN”相呼应信号中的 NaN 正是污染下游权益曲线的常见来源在信号层显式填充比在产物层事后发现更符合“修复一处即验证一处”的纪律。总结backtest-diagnose 技能的价值在于把“回测排障”从经验性调试变成有明确工件、有分类法、有终止条件的工程流程五步工作流规定了证据收集顺序三类错误分类加忽略清单防止了对数据源问题的误修Hard-Gate Checklist 既是人工验收标准又被 evidence_harness.py 原样实现为证据摄入门禁修复原则与 AST 校验约束了修复动作的边界action_items规范保证了诊断结论可执行。对于维护自己的回测运行或接入策略发现证据管线的读者这套“先验资格、再算证据、整体拒绝、稳定 token”的 fail-closed 设计是值得直接借鉴的模式。【免费下载链接】Vibe-TradingVibe-Trading: Your Personal Trading Agent项目地址: https://gitcode.com/GitHub_Trending/vi/Vibe-Trading创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考