FinClaw 量化回测

要解决的问题

把“帮我回测机构买这个策略”直接翻译成回测脚本，几乎注定失败。口语里的一个词可能对应多个数据口径，缺少 point-in-time 约束的策略代码会把未来信息泄漏进收益曲线，得到一个好看但无效的结果。更麻烦的是，当原始信号没有历史数据时，一些流程会悄悄换成看似接近的代理字段继续跑，并在报告里隐瞒替换。finclaw-backtest 只做两件事：把口语需求固化成可校验的 backtest_spec.md，以及在任何代码执行前阻断不严格的回测。

核心能力与关键步骤

整个流程分四个阶段，Phase 0 是硬门：

• Phase 0：Spec Freeze。先识别策略原型，如 timing 择时、selection 选股、event_driven 事件型、dca 定投、hedge 对冲、grid 网格。接着判断每个原始信号是否有 PIT 历史字段；有则写清 endpoint、API、field、visible_date 和 lag；无但有可解释代理，则在 spec 里标出代理与非等价风险并等待确认；两者都没有时直接标 strict_backtestable: false，生成声明性结果，不写策略代码。模糊信号词必须落到 neodata 的具体字段和阈值，例如“机构买”有机构调研次数、评级买入数量、机构持仓比例、目标价上调四个候选，需要用户选择。随后按 Tier 1/2/3 填写模板，Tier 1 涉及标的池、区间、频率、资金、基准、原型，不提供默认值；Tier 2 是复权、佣金、印花税、滑点、一手股数、T+1、年交易日、无风险利率等标准约定。Echo spec 后等用户 ack，再写盘并用 spec_validator.py 循环校验到退出码 0。
• Phase 1：策略编写。按原型选择通用模板或 event_driven_template.md，文件头记录 spec 路径和 hash，硬编码参数旁注明 derived from spec，所有 PIT 数据记录 source_api、source_field、visible_date。全市场扫描得到 0 候选时不得输出成功空结果。数值不变式包括滚动指标加载 pre-start warm-up、网格和止损止盈默认使用不复权真实价格、DCA 同时输出真实投入资金盈亏和修正净值收益并让基准同步定投、高股息标的建模分红现金或声明 qfq_price_only、科创板/创业板/空头/期货特殊制度建模或标记未建模。
• Phase 2：本地回测。K 线数据来自 neodata，代码格式为 {code}.{exchange}，凭证用 $FINCLAW_JWT_TOKEN 或 ~/.finclaw/.env。Neodata 还提供财务三表、估值、资金流、龙虎榜、融资融券、机构持仓、公司事件、研报、机构评级与目标价、宏观等接口，缺数据时显式告知用户而不是静默跳过。普通策略用预置资金，portfolio_value 等于现金加持仓市值，基准一次性持有；DCA 用外部注资，每次触发注入 inject_amount 后立即买入并令现金归零，输出 dca_metrics。result_validator.py 退出码非 0 时禁止交付。跑完后停下，等用户决定是否进入 Phase 3 与 Phase 4。
• Phase 3 与 Phase 4：诊断报告。从 backtest_result.json 提取 holdingsatend、maxdrawdownperiod、backtest_period、标的代码，批量拉取数据后写六份分析，再汇总成 strategy_diagnosis.md。报告包含 19+ 回测指标、与基准对比、六维加权评分、归因分析、最大回撤时间线、未来预期，以及按优先级排序且具体到代码改动的优化建议。

适用边界与注意点

• 严格可回测是默认状态。proxy_used: true 时，最终标题、JSON、图表和摘要都必须标注“代理策略”，选股因子的 proxy_for 非空时摘要不得继续称其为原始因子策略。
• 用户提供已有策略代码时，跳过 Phase 0 和 Phase 1，直接进入 Phase 2，但仍执行结果完整性校验。
• neodata 的数据查询主要覆盖 A 股，HK 和 US 标的的深度分析需要配合 web 搜索补充。
• HK 股票 turnover_rate 为 0，涉及换手率的策略只适用于 A 股。
• neodata 接口名规律是 v3 优先于 v2，_test 和 _bak 属于废弃版本。