Python股票回测策略接口怎么写：检查输入数据与信号输出
解释Python股票策略收益前，先验接口。无参数构造类，调用generate(data_map)，逐个检查返回证券键、序列索引与含义。类型注解或成功导入，不证明实际对象符合数据契约。交付应包含可运行正常样本和错误注入，不只是一段看起来合理的函数签名。
本指南分两层：无依赖可移植契约样例，以及真正使用pandas DataFrame和Series的补充验收。CoTrading接口能力仍为规划或待核实，两者都不启动Vibe，也不证明完整runner、市场执行或策略盈利。输入全为合成，不调用外部数据和账户。
参考接口与本例政策分开
所审阅参考加载路径要求可无参数构造、存在可调用generate，结果为字典且每个值为pandas Series。后续参考处理使用信号键与数据键的交集，并不原生要求所有输入证券都必须返回。适配时先确认这一边界，不把自己更严格的测试误写成通用入口要求。
本教程为一个冒烟契约主动收紧：每只输入股票均须输出序列，索引与输入完全一致，值为零或一且声明做多目标含义。这些是作者选择的编辑验收政策，不是所有Vibe策略原生规定。严格测试帮助发现意外漏股，但改变政策需要同时解释缺键会怎样影响持仓。
样例的semantics = 'target_long_state'也是自己添加的政策标记，不是Vibe强制原生属性。本契约拒绝负一，不意味着其他股票策略一切负信号都无效。别的接口必须声明自己的信号含义和执行许可，不能仅根据符号推断卖空可用，也不能把一个多头例子推广成全部策略定义。
先写数据映射再写类
输入按稳定研究标识建字典，真实pandas例有US:A与US:B，各自DataFrame含close列、同样三个有序合成日期。生产适配还需价格单位、行是否完整、必需字段与可得时点，DataFrame容器本身不提供这些保证。列存在也不等于可用于当时决策。
真实生成器拒绝空映射、非DataFrame、缺收盘列、空表和缺收盘，并在计算前检查输入索引唯一递增。这是本例支持的形状，不意味着任意供应商表已经自动规范。错误应指向具体证券与字段，实际集成可以扩展诊断信息，不能只是捕获全部异常后返回空字典。
日期给定二〇二六年一月五至七日，但没有查询交易所日历，仅用完整观察检查索引。后续执行研究仍要确认下一可交易期和市场约束。接口通过不能写成这些工作已发生，也不能把示例连续日历日期当所有市场通用的交易日推进算法。
返回带标签序列而非裸数组
pandas Series官方说明描述带轴标签的一维对象。标签重要，因为运算可以按索引对齐，不只按列表位置。返回三个数相同的Python列表仍不符合真实pandas契约，也可能掩盖日期错位。输出长度正确只是其中一项，不是完整对齐证据。
从输入收盘序列计算能保留原日期索引。直接由列表新建Series而不传索引，通常得到默认整数索引，长度可能正确但标签错误。因此验收同时检查真实Series类型与索引精确相等，不仅检查长度。不能在检查前擅自重设索引，使错误输出看起来通过。
Index.is_unique官方文档给出唯一性检查。pandas本身允许重复标签，所以拒绝重复是应用契约，不是Series天然不能表示。不能静默去重后，把缩短输出与原数据混用；来源重复应先明确处理政策，再生成对应信号，保留原始证据。
定义一个可手算信号
类没有必填构造参数。每行完整收盘与当前及前两条均值比较，不足三条输出零，严格高于为一，相等或低于为零。含义是目标做多状态，不是每个一都新增满仓买单。执行层如果需要方向事件，应另转换，不能把同一数组同时解释成状态和事件。
US:A收到十、十、十二，输出[0, 0, 1]；US:B十、十、八，输出[0, 0, 0]。两者保留各自三日索引。这里不计算成交、股数、费用和账户收益，因为接口任务不需要虚构这些结果。没有收益不是缺稿，而是验证范围与产物保持一致。
pandas版使用需要三条观察的尾部滚动平均，再把布尔比较转整数。生成前深拷贝两表，之后用pandas表比较断言输入未改变。这个检查能发现函数为方便计算而覆盖原close或重设索引，避免后续别的策略读取被污染数据。它仍不等于任意副作用安全审计。
无依赖样例诚实标范围
下载标准库样例，保存R573.py，使用Python 3.12及以上运行python R573.py。源文件docs/growth/research/round-5/examples/R573.py使用合成列表和明确命名的Signals数据类，检查键、索引、值域及含义等可移植契约部分。
该数据类不是pandas Series，通过只证明这些契约检查和信号序列，不能充当真实pandas类型证据。补充例专门弥补这一个证据缺口，不升级成完整runner联调。两层输出独立保留，让用户没装pandas也能理解基本验收，同时知道实际依赖测试在哪里。
标准库包拒绝外层列表、错误证券键、重复标签、把预期信号对象换列表，以及本零一政策下的负值，还拒绝未声明语义。这些是该样例违约，不是在宣称每个外部引擎都会拒绝同样状态。是否接受部分覆盖或负信号，必须看实际策略契约，不能从本测试名反推。
真pandas补充例单独执行
下载pandas补充例，保存R573-pandas.py。可用python -m pip install pandas==3.0.1准备环境，再运行python R573-pandas.py。仓库文件为docs/growth/research/round-5/examples-extra/R573-pandas.py，这是可选依赖脚本，不属于无依赖标准库版本。
作者实际使用Python 3.12.14和pandas 3.0.1执行，得到两份预期信号并确认输入未改。六种错误分别为外层类型、证券键、非Series、输入重复索引、输出错位索引，以及所选多头政策下负信号，全部被拒；另测未声明语义拒绝。运行版本与输出记录，不仅靠文档推测。
这是实际pandas对象证据，不是未执行代码，也不是借相似类名替代。静态站只提供文件，不执行Python，读者在本地运行补充例才需依赖。它没有连接Vibe、行情或券商，不能因真实库测试通过就声称下游撮合、可卖数量和成本已经正常。那些仍需独立运行证据。
适配时先确定宽松与严格边界
已有策略若允许部分键，参考交集处理可接受子集；本冒烟测试要求全覆盖，是为了暴露意外漏股。若放宽，必须同时说明缺失证券如何影响已有仓位，不能一会儿叫继续持有，一会儿叫零目标或强退。缺键含义是政策，不是字典数据类型自动决定的。
接口合规、时间正确和交易有效分别报告。对齐Series仍可含前视算法；其他契约允许负值也不证明所选市场能卖空；类构造成功也不证明数据获取或完整runner成功。保存源码、Python/pandas版本、输入模式、主动收紧政策及真实断言输出，适配或语义变化后重跑。
完成条件是可复现且标签准确的接口验收：有标准库契约证据，也有真正pandas对象证据，并清楚列出未测阶段。不要因为测试全部绿色，就把原生最小入口、作者编辑契约和账户执行三层合并为一句策略已经可用。分层结论使接手者能在正确位置继续，而不重复验证已完成部分或跳过未知部分。
政策变化不要误作类型变化
只返回US:A的有效子集，与返回无命名空间A这种未知键不同。所审参考交集可以使用前者，本全覆盖冒烟契约则主动拒绝。判断缺输出是否故障前先决定政策。如果允许部分输出，应为US:B保留无信号状态，并在接口之外明确它对旧持仓的影响，不能靠字典没有该键自动推断账户动作。
同样，Series容器可以保存本做多例不允许的值。零一检查是在执行经济输出词汇，不是pandas存储限制。交接报告把容器错误、标签错误、语义错误分别列出；依赖升级可能影响对象行为，策略变化可能影响允许词汇，二者需要不同修复和证据。不能为了某条负值通过就取消全部索引检查。
这种分层还允许读者合理改造示例：如果真正策略需要更宽词汇，先写清每个值代表目标状态、订单方向还是退出事件，再扩展值域和对应预期输出，而不是只删掉负一断言。若信号类型改成连续权重，则还要声明范围、缺失与资金解释。那是新的验收契约，本例结果不能自动替它背书。
最后把测试版本与运行环境一起交付。真实pandas补充文件含可复制完整实现，标准库文件只验证可移植部分，两者不能互换结论。读者可以先理解无依赖检查，再在需要时安装固定版本运行真实对象；静态下载只是交付媒介，不暗示网站或产品替用户执行了策略。明确这些边界，绿色测试才具有可用而有限的含义。
常见问题
全键覆盖和语义属性都是原生要求吗？
不是，它们是本多头冒烟例主动增加的政策；所审参考后续使用键交集。
标准库文件验证了pandas类型吗？
没有，真实类型需运行独立pandas补充例。