在 TqSdk 中K 线不是每次调用都返回一份全新结果而是一段会被事件循环持续更新的序列。正确的使用方式是先订阅所需周期和长度再通过wait_update接收变化最后用is_changing区分“当前 K 线价格变了”和“已经生成一根新 K 线”。这一区分直接决定指标会不会重复计算、信号会不会重复触发。获取一段可更新的 K 线序列get_kline_serial的核心参数是合约代码、周期秒数和数据长度。下面订阅螺纹钢主连的 1 分钟 K 线并保留最近 100 根。主连适合做连续研究示例涉及交易时还需要映射到实际月份合约。import os from tqsdk import TqApi, TqAuth api TqApi( authTqAuth(os.environ[TQ_USER], os.environ[TQ_PASSWORD]) ) klines api.get_kline_serial( KQ.mSHFE.rb, duration_seconds60, data_length100, ) try: while True: api.wait_update() if api.is_changing(klines.iloc[-1], close): print(klines.iloc[-1][[datetime, open, high, low, close]]) finally: api.close()返回值具有 DataFrame 风格可以使用iloc、列选择和常见 pandas 计算方式。不过它不是静态表格事件循环收到数据后末行会继续变化出现新周期时整段序列也会向前滚动。保存某一时刻的数据时应显式复制需要的内容而不是假设这个对象永远不变。常用字段分别表达什么每根 K 线包含起始时间、开盘价、最高价、最低价、收盘价、成交量和持仓量等字段。datetime是纳秒级时间戳表示该根 K 线的起始时间。显示给人阅读时可以转换为日期时间程序判断新 K 线时直接比较或监听这个字段更稳定。open、high、low、close描述该周期内的价格范围volume是成交量close_oi是周期结束时的持仓量。不同字段解决的问题不同计算均线通常使用收盘价观察周期内波动会用到最高价和最低价研究量价关系还需要成交量和持仓量。不要因为表里字段很多就一次性把所有字段都加入策略。订阅刚建立时前部数据可能存在空值尤其是可用历史不足或对象尚未完成首次更新时。计算前应检查所需窗口是否已经具备有效数据。把空值直接填成零可能会人为制造价格跳变和错误信号因此应先明确缺失的原因。时间字段还承担对齐作用。两个合约或两个周期的序列长度相同不代表最后一行对应同一时刻。跨品种比较之前应先检查datetime是否能够对齐遇到上市时间不同或交易时段差异时直接按行号相减可能把不同时间的数据拼在一起。研究结果一旦依赖错位数据后面的公式再精确也没有意义。序列滚动意味着行位置表达的是“当前距离末尾多远”而不是某根 K 线永久不变的身份。需要长期保存事件时应记录合约、周期和时间戳把它们作为回查依据。只记iloc[-2]这样的相对位置程序下一轮更新后就无法说明当时引用的是哪根线。当前 K 线变化不等于新 K 线在一分钟尚未结束时最新成交会不断改变当前 K 线的最高、最低、收盘和成交量。监听close变化适合做盘中观察却可能在一分钟内触发许多次。如果策略定义为“每根一分钟线结束后计算一次”应该监听末行datetime的变化。last_time None while True: api.wait_update() current_time klines.iloc[-1].datetime if last_time is None: last_time current_time continue if api.is_changing(klines.iloc[-1], datetime): closed_bar klines.iloc[-2] print(上一根已结束 K 线收盘价:, closed_bar.close) last_time current_time当最后一行的时间变化时原来的末行已经移动到倒数第二行所以已完成周期通常读取iloc[-2]。首次进入循环时还没有“上一轮”可比较代码需要跳过初始化避免把订阅完成误判成策略事件。指标计算要与触发频率一致以简单均线为例如果策略只在新 K 线出现时决策就在新线事件中计算已完成 K 线的窗口。这样同一根 K 线不会因为盘中价格变化重复产生信号也便于回测和实时运行保持相同节奏。if api.is_changing(klines.iloc[-1], datetime): closed klines.close.iloc[:-1] ma5 closed.iloc[-5:].mean() ma20 closed.iloc[-20:].mean() print(MA5:, ma5, MA20:, ma20)在计算前还应确认至少有 20 根有效收盘价。示例只展示数据与触发关系并不是完整策略均线交叉如何定义、是否过滤重复信号、当前持仓怎样处理都需要单独写成明确规则。多个周期同时使用时每个序列都有自己的更新时间。不要因为较短周期更新就假设较长周期也已经形成新线。分别监听各自的datetime再决定是否组合计算逻辑会更清楚。多合约策略也适用同样原则。每个订阅对象只在自身发生相关变化时更新对应指标再把最新结果写入一个清楚的状态表。最终组合判断读取这个状态表并检查各项时间是否仍然有效。这样能避免任意一个合约更新时把其他合约的旧数据误当作同一时刻的新信息。计算函数最好接收一份明确的数据切片并返回结果不在函数内部创建新的 API 或事件循环。行情推进和数学计算分开后同一个指标函数既能用历史样本测试也能被实时循环调用更容易发现窗口长度、空值和边界索引问题。K 线研究的边界K 线把一个周期内的交易压缩为几个汇总字段它适合趋势、波动和指标研究但不能还原周期内每一笔成交的先后顺序。仅凭一分钟 K 线无法知道最高价和最低价哪个先出现也无法精确复刻所有成交队列。回测结果同样受数据粒度和模拟撮合规则影响。策略若依赖非常细的盘中顺序应使用更合适的数据并明确验证边界。主连序列用于研究连续走势时还要注意它不是一个可以直接成交的具体合约实盘执行需要处理实际合约和换月。还要避免未来数据泄漏。做实时判断时只能使用当时已经形成的数据在新 K 线刚出现时上一根已完成线可以使用当前末行仍在形成。若在历史表上一次性计算指标后再挑选结果需要确认公式没有通过居中窗口、反向填充或后续行间接使用未来信息。验证 K 线代码时可以手工记录连续几次事件的末行时间、倒数第二行时间和指标值。少量可读样本往往能很快发现触发行取错、初始化误判和窗口不足比一开始只看整段收益曲线更可靠。K 线使用清单周期秒数、数据长度和合约代码与研究目标一致。指标窗口已有足够的有效数据没有把缺失值随意填成零。监听datetime判断新 K 线监听价格字段判断当前线变化。使用已完成 K 线时读取正确行避免把正在形成的末行当成收盘结果。研究连续合约与执行具体合约分开回测结论不超出数据粒度。把“动态序列、变化字段、已完成周期”这三个概念分清后K 线代码就不再只是把 DataFrame 套进公式。每次计算为什么发生、使用的是哪一根线、结果能支持什么结论都会有明确答案。