期货策略交给同事跑：配置、日志、版本与模拟验收清单
前言
策略在自己电脑上跑得挺好，交给同事或客户时却频频出事：密码写死在代码里、合约月份还是去年的rb2410、对方不知道用TqSim还是TqKq、没有模拟验收就直接上了实盘。国内期货程序化交接，交付物不应只是一个.py文件，而应是一套能复现运行环境、能对照检查的配置、日志规范和验收清单。
天勤常见路径是：TqSim本机调试 →TqKq快期模拟（可与 APP 对持仓）→TqAccount实盘。下面说明每项交付物写什么、日志里英文字段含义、接手人模拟验收勾选什么，全部勾选后再申请实盘小仓位。
一、交付物分别解决什么问题
| 交付项 | 内容 | 避免什么事故 |
|---|---|---|
| 代码 | main.py、config.py、signals.py | 逻辑散落、改一处漏一处 |
| requirements.txt | 含tqsdk==版本号 | 对方 pip 装到不兼容新版 |
.env.example | 列出 TQ_USER、TQ_MODE、合约列表，密码用占位符 | 密码进 git、实盘误连模拟 |
| README | 如何切换 TqSim / TqKq / TqAccount | 不知道连哪种账户 |
| VERSION 或 git tag | 策略发布版本号 | 口头说“最新版”对不上 |
| 风控说明 | emergency、涨跌停、交易时段规则 | 对方关掉过滤不知道后果 |
代码里禁止作者本机绝对路径，如D:\project\state.json；改用相对路径或环境变量。
二、配置规范：make_api 与 MODE
TqApi是天勤连接对象，整个进程通常只创建一次。建议集中在一个make_api()函数里：
TQ_MODE=sim→TqApi(TqSim(), auth=TqAuth(...))TQ_MODE=kq→TqApi(TqKq(), auth=...)TQ_MODE=live→TqApi(TqAccount(期货公司名, 资金账号, 密码), auth=...)
TqAuth是天勤账户认证（快期账户），与期货公司资金账号不是同一个概念，两套都要配置时再在 README 里写清。
启动时打印：当前 MODE、订阅的 symbol 列表、tqsdk 版本号，方便截图排错。
合约、手数、K 线周期秒数、最大回撤 MAX_DD 等全放 config，不要散落在信号函数里。
三、日志字段：英文字段名含义
建议结构化日志（CSV 或 JSON 行）包含：
| 字段 | 含义 |
|---|---|
| ts | 日志时间戳 |
| mode | 当前 TQ_MODE，sim/kq/live |
| symbol | 合约代码 |
| event | 事件类型，如 signal、order、emergency |
| bar_datetime | K 线表 datetime，触发信号的那根 bar 的业务时间 |
| target | 策略给出的目标净仓手数 |
| pos | get_position(symbol).pos，柜台净持仓 |
| order_status | 委托 status，如 ALIVE、FINISHED |
| last_msg | 委托状态说明，拒单原因常在此 |
日志按日轮转放在logs/目录，避免单文件无限增大占满磁盘。
四、模拟验收 checklist（接手人逐项勾选）
环境
- Python 版本与 requirements.txt 一致
TqAuth能登录，快期账户有效- 先用
TQ_MODE=sim或kq，勿第一步 live
连通
- 运行后
wait_update，quote.datetime在交易时段推进 - K 线用
is_changing(..., "datetime")触发，信号在iloc[-2]计算（与作者文档一致）
交易
- 最小手数下一笔，
get_position与快期 APP（TqKq 时）一致 get_trade与日志里该笔记录对照- 退出时执行
api.close()，无残留连接（可再次启动不报错）
风控
- 非交易时段不误开仓
- 演练一次 emergency（或作者提供的测试开关）
- 故意下一笔可能拒单的单，日志里有 last_msg
回归
- 同区间
TqBacktest与模拟方向大体一致（不要求逐笔相同）
全部勾选后，作者与接手人各留一份签字或邮件确认，再申请TqAccount小仓位。
五、版本与变更纪律
变更合约月份、均线参数、风控阈值时，递增 VERSION 并写 CHANGELOG 三行：改了什么、为什么、验收是否重跑。接手人禁止“顺手改一行”不记录，否则出问题时无法对应版本。
六、支持边界
交付文档写明：历史回测不保证未来盈利；出问题先按 checklist 查日志与 MODE；实盘责任人必须明确。
总结
策略交接的本质不是把代码丢过去，而是把一套可复现、可追踪、可验收的运行体系交出来：配置如何切 MODE、依赖如何锁版本、日志字段怎么对齐、验收用什么 checklist。天勤三环境（回测/模拟/实盘）切换时通常只需要在 make_api 的账户对象上做差异，但信号计算与 datetime 触发规则必须保持一致，所以交付文档要把这些‘不变的部分’写清楚。更重要的是日志与验收要能回答：这笔成交是否按预期发生、拒单来自哪里、emergency 触发是否如实执行。接手方按同一套流程跑通并留下证据，协作成本才会真正下降，而不是靠反复沟通在夜盘里追错。把交付收束成可验证的工程包，团队迭代速度也会随之提升。
FAQ
1）对方不会 Python？
可附 Docker 镜像或详细安装步骤，或约定由运维按文档部署。
2）只给编译后的 exe？
仍要 config 与日志规范，否则无法排错。
3）一个包里有三个策略？
每策略独立目录、独立 VERSION、独立 systemd 服务名。
4）DataDownloader 历史数据？
属专业版能力，单独说明权限，不默认对方一定有。
风险提示
以上内容用于交付流程参考，不构成投资建议。