接口目录：

binary_serializable_t
commission_supplier_t
dashboard_meta_context_t
data_collector_plugin_context_t
data_collector_plugin_t
deployment_context_t
description_meta_context_t
environment_context_t
exit_context_t
initialization_context_t
instrument_configuration_supplier_t
logger_t
market_data_source_context_t
market_data_source_plugin_t
metric_t
parameter_access_context_t
parameter_context_t
position_access_context_t
runtime_context_t
serializable_merge_t
signal_meta_context_t
source_plugin_context_t
source_plugin_t
strategy_base_imp_t
strategy_meta_context_t
strategy_state_manager_t
strategy_t
text_serializable_t
tick_sink_t
trade_source_context_t
trade_source_plugin_t

binary_serializable_t

头文件：serializable.h；命名空间：thunder。

二进制序列化契约，由需要存档的对象实现。写入和读取字段的顺序、类型必须一致。

binary_serialize_to

virtual void binary_serialize_to(boost::archive::binary_oarchive&);

通过 Boost binary 归档写入对象。调用方创建归档并保证流可用；实现类负责匹配字段顺序和版本。

示例：

void demo(binary_serializable_t &api, std::ostream &stream) {
    boost::archive::binary_oarchive archive(stream);
    api.binary_serialize_to(archive);
}

binary_deserialize_from

virtual void binary_deserialize_from(boost::archive::binary_iarchive&);

通过 Boost binary 归档读取对象。调用方创建归档并保证流可用；实现类负责匹配字段顺序和版本。

示例：

void demo(binary_serializable_t &api, std::istream &stream) {
    boost::archive::binary_iarchive archive(stream);
    api.binary_deserialize_from(archive);
}

commission_supplier_t

头文件：commission_interface.h；命名空间：thunder。

手续费供应接口，可作为交易插件的附加能力。CTP 实现会查询费率；当前 IBKR 交易插件直接返回 false，调用方必须处理不可用情况。

on_query_commission

virtual bool on_query_commission(const instrument_unique_name_t&, commission_t&);

由供应方查询合约手续费，返回 true 时输出有效。CTP 查询包含异步请求和等待，避免假定它是无阻塞读取。

示例：

void demo(commission_supplier_t &api, const instrument_unique_name_t &name) {
    commission_t commission;
    if (api.on_query_commission(name, commission)) {
        const auto ratio = commission.open_ratio_by_money();
        (void)ratio;
    }
}

dashboard_meta_context_t

头文件：strategy/dashboard_meta_context.h；命名空间：thunder::strategy。

框架传给 strategy_t::get_dashboard_meta 的上下文，用于构造仪表盘元数据。

继承接口：logger_t、metric_t、environment_context_t。继承函数的参数及示例见对应基类。

此类没有新增业务函数。以下示例展示通过该阶段上下文调用继承的日志函数；指标与环境变量用法参见基类。

void demo(dashboard_meta_context_t &context) {
    context.logging(severity_levels::debug, "进入当前阶段");
}

data_collector_plugin_context_t

头文件：data_center/data_collector_plugin_context.h；命名空间：thunder::data_collector。

DataCenter 提供给采集插件的上下文，用于上传合约资料以及记录日志和指标。

继承接口：logger_t、metric_t。继承函数的参数及示例见对应基类。

on_instrument_data

virtual void on_instrument_data(const instrument_t&);

采集插件向 DataCenter 上报完整合约资料；实参由通道转换得到。

示例：

void demo(data_collector_plugin_context_t &api, const instrument_t &instrument) {
    api.on_instrument_data(instrument);
}

data_collector_plugin_t

头文件：data_center/data_collector_plugin.h；命名空间：thunder::data_collector。

DataCenter 采集插件契约。宿主依次调用 initialization、install，运行期间可调用 update_configuration，最后调用 uninstall。初始化成功或安装成功不等于远端已经登录。实现类用 COLLECTOR_PLUGIN_EXPORT 导出。

get_name

virtual name_t get_name();

返回采集插件名称。

示例：

void demo(data_collector_plugin_t &api) {
    const auto name = api.get_name();
    (void)name;
}

get_description

virtual description_t get_description();

返回说明文本。

示例：

void demo(data_collector_plugin_t &api) {
    const auto description = api.get_description();
    (void)description;
}

get_configuration_fields

virtual fields_set_t get_configuration_fields();

返回采集插件初始化字段及说明；配置值统一通过字符串映射传入。IBKR 采集器使用 host、port、client_id；CTP 使用前置地址和账户等字段。

示例：

void demo(data_collector_plugin_t &api) {
    const auto fields = api.get_configuration_fields();
    for (const auto &[name, description] : fields) {
        (void)name; (void)description;
    }
}

initialization

virtual bool initialization(const configuration_t &, data_collector_plugin_context_t*, std::weak_ptr<tick_sink_t>);

安装前初始化。传入配置、借用的插件上下文和行情接收端弱引用；返回 false 时不应继续安装。示例配置针对 IBKR，CTP 应按其字段说明准备配置。

示例：

void demo(data_collector_plugin_t &api, data_collector_plugin_context_t &context, std::weak_ptr<tick_sink_t> sink) {
    data_collector_plugin_t::configuration_t configuration{
        {"host", "127.0.0.1"}, {"port", "7497"}, {"client_id", "1"}
    };
    const bool ready = api.initialization(configuration, &context, sink);
    (void)ready;
}

install

virtual bool install();

初始化成功后启动采集，返回安装结果；远端连接和登录可能仍在异步进行。

示例：

void demo(data_collector_plugin_t &api) {
    const bool installed = api.install();
    (void)installed;
}

uninstall

virtual void uninstall();

停止采集并释放线程、连接及定时器。应先停止异步回调，再释放上下文。

示例：

void demo(data_collector_plugin_t &api) {
    api.uninstall();
}

update_configuration

virtual void update_configuration(const collect_configuration_t &);

热更新采集范围，参数是 JSON 文本字符串，格式由插件定义。CTP 当前接受正则表达式数组，IBKR 接受含 instruments 数组的对象；不是 initialization 的账户配置映射。下面两个函数分别针对相应插件，不应对同一实例混用。

示例：

void demo(data_collector_plugin_t &api) {
    api.update_configuration(R"(["rb.*", "ag.*"])");
}

// 仅对 IBKR 采集器：此配置表示最新合约集合为空。
void demo_ibkr(data_collector_plugin_t &api) {
    api.update_configuration(R"({"instruments":[]})");
}

deployment_context_t

头文件：strategy/deployment_context.h；命名空间：thunder::strategy。

部署时由框架提供，用于查询交易槽、合约属性并恢复保存点。strategy_arbitrage/spi.cpp 在 on_deployment 中读取价格步长和合约乘数。

继承接口：logger_t、metric_t、environment_context_t、strategy_meta_context_t、strategy_state_manager_t、parameter_access_context_t、position_access_context_t。继承函数的参数及示例见对应基类。

get_slot_count

virtual size_t get_slot_count();

返回部署的交易槽数量；交易槽参数应对应已配置的合约。

示例：

void demo(deployment_context_t &api) {
    const size_t count = api.get_slot_count();
    (void)count;
}

get_price_tick

virtual ratio_t get_price_tick(trade_slot_t);

返回交易槽合约的最小价格变动单位。

示例：

void demo(deployment_context_t &api) {
    const ratio_t step = api.get_price_tick(0);
    (void)step;
}

get_volume_multiple

virtual size_t get_volume_multiple(trade_slot_t);

返回交易槽的合约乘数。套利策略将乘数保存在 uint_vector_state 中用于金额计算。

示例：

void demo(deployment_context_t &api) {
    const size_t multiplier = api.get_volume_multiple(0);
    (void)multiplier;
}

get_margin_ratio

virtual bool get_margin_ratio(trade_slot_t, double &long_position, double &short_position);

查询多头、空头保证金比例，经引用参数输出；返回 false 时不使用输出。

示例：

void demo(deployment_context_t &api) {
    double long_ratio = 0.0, short_ratio = 0.0;
    if (api.get_margin_ratio(0, long_ratio, short_ratio)) {
        const double ratio = long_ratio;
        (void)ratio;
    }
}

query_instrument

virtual bool query_instrument(trade_slot_t, instrument_t &);

按交易槽查询合约资料。成功时输出 instrument_t，否则返回 false。

示例：

void demo(deployment_context_t &api) {
    instrument_t instrument{};
    if (api.query_instrument(0, instrument)) {
        const auto name = instrument.unique_name;
        (void)name;
    }
}

get_user_defined_savepoint

virtual bool get_user_defined_savepoint(strategy_user_defined_savepoint_t&);

读取策略自定义保存点字符串。与 strategy_t::on_user_defined_savepoint 配套；解码格式由策略约定。

示例：

void demo(deployment_context_t &api) {
    strategy_user_defined_savepoint_t payload;
    if (api.get_user_defined_savepoint(payload)) {
        // 本示例约定保存点为字符串版本号。
        const bool version_one = payload == "v1";
        (void)version_one;
    }
}

get_currency_unit

virtual std::optional<currency_unit_t> get_currency_unit(trade_slot_t);

返回可选的币值单位比例；无值时不能直接解引用。

示例：

void demo(deployment_context_t &api) {
    if (const auto unit = api.get_currency_unit(0)) {
        const auto numerator = unit->numerator();
        const auto denominator = unit->denominator();
        (void)numerator; (void)denominator;
    }
}

description_meta_context_t

头文件：strategy/description_meta_context.h；命名空间：thunder::strategy。

框架传给 strategy_t::get_description 的上下文。

继承接口：logger_t、metric_t、environment_context_t。继承函数的参数及示例见对应基类。

此类没有新增业务函数。以下示例展示通过该阶段上下文调用继承的日志函数；指标与环境变量用法参见基类。

void demo(description_meta_context_t &context) {
    context.logging(severity_levels::debug, "进入当前阶段");
}

environment_context_t

头文件：strategy/environment_context.h；命名空间：thunder::strategy。

读取策略环境变量的基础接口；返回字符串映射的只读引用。

get_environment_variables

virtual const std::map<std::string, std::string> & get_environment_variables();

返回环境变量的只读映射引用；先检查键是否存在。

示例：

void demo(environment_context_t &api) {
    const auto &env = api.get_environment_variables();
    if (auto it = env.find("MODE"); it != env.end()) {
        const std::string mode = it->second;
        (void)mode;
    }
}

exit_context_t

头文件：strategy/exit_context.h；命名空间：thunder::strategy。

框架传给 strategy_t::on_exit 的退出阶段上下文。

继承接口：logger_t、metric_t、environment_context_t。继承函数的参数及示例见对应基类。

此类没有新增业务函数。以下示例展示通过该阶段上下文调用继承的日志函数；指标与环境变量用法参见基类。

void demo(exit_context_t &context) {
    context.logging(severity_levels::debug, "进入当前阶段");
}

initialization_context_t

头文件：strategy/initialization_context.h；命名空间：thunder::strategy。

策略初始化阶段上下文，可判断是否从归档加载。

继承接口：logger_t、metric_t、environment_context_t、strategy_meta_context_t。继承函数的参数及示例见对应基类。

此类没有新增业务函数。以下示例展示通过该阶段上下文调用继承的日志函数；指标与环境变量用法参见基类。

void demo(initialization_context_t &context) {
    context.logging(severity_levels::debug, "进入当前阶段");
}

instrument_configuration_supplier_t

头文件：source/instrument_configuration_supplier.h；命名空间：thunder。

按合约唯一名称提供合约配置的查询契约。

get_instrument_configuration

virtual bool get_instrument_configuration(const instrument_unique_name_t&, instrument_t&);

按合约唯一名称查询配置，返回 true 时输出有效。

示例：

void demo(instrument_configuration_supplier_t &api, const instrument_unique_name_t &name) {
    instrument_t instrument{};
    if (api.get_instrument_configuration(name, instrument)) {
        const auto step = instrument.price_tick;
        (void)step;
    }
}

logger_t

头文件：logger.h；命名空间：thunder。

框架提供的日志接口，采用 printf 风格的变参格式。

logging

virtual void logging(severity_levels, const char *, ...);

写入指定级别的日志。格式串和实参类型必须匹配；动态文本用 %s 传递。

示例：

void demo(logger_t &api) {
    api.logging(severity_levels::info, "合约=%s 最新价=%.2f", "demo", 100.0);
}

market_data_source_context_t

头文件：source/market_data_source_context.h；命名空间：thunder。

引擎提供给行情源的回调接口。行情插件将转换后的 tick 所有权交给引擎。

继承接口：metric_t。继承函数的参数及示例见对应基类。

on_tick_data

virtual void on_tick_data(std::unique_ptr<tick_t>);

行情插件向引擎提交 tick。unique_ptr 按值传递，调用后原指针不再拥有对象。

示例：

void demo(market_data_source_context_t &api, const tick_t &sample) {
    auto tick = std::make_unique<tick_t>(sample);
    api.on_tick_data(std::move(tick));
}

market_data_source_plugin_t

头文件：source/market_data_source_plugin.h；命名空间：thunder。

行情源插件契约。宿主初始化插件并推送完整订阅集合；插件负责维护订阅差异与连接，在卸载时释放资源。实现类用 SOURCE_PLUGIN_EXPORT 导出。

继承接口：source_plugin_t。继承函数的参数及示例见对应基类。

market_data_source_initialization

virtual void market_data_source_initialization(source_plugin_context_t *, market_data_source_context_t *);

宿主传入公共上下文和行情上下文。插件保存借用指针、读取配置并启动连接流程，指针寿命由宿主管理。

示例：

void demo(market_data_source_plugin_t &api, source_plugin_context_t &source, market_data_source_context_t &market) {
    api.market_data_source_initialization(&source, &market);
}

market_data_source_on_update_subscribed_instruments_list

virtual void market_data_source_on_update_subscribed_instruments_list(const std::set<instrument_unique_name_t> &);

接收最新的完整订阅集合，不是仅新增的合约。IBKR 实现转换集合后调用订阅更新；传空集合表示最新列表为空。

示例：

void demo(market_data_source_plugin_t &api, const std::set<instrument_unique_name_t> &instruments) {
    api.market_data_source_on_update_subscribed_instruments_list(instruments);
}

market_data_source_is_subscribing_instruments

virtual bool market_data_source_is_subscribing_instruments();

返回当前是否仍有订阅；为 true 时引擎拒绝移除该源。

示例：

void demo(market_data_source_plugin_t &api) {
    const bool subscribed = api.market_data_source_is_subscribing_instruments();
    (void)subscribed;
}

market_data_source_unload

virtual void market_data_source_unload();

卸载行情源，结束订阅、连接及后台任务；实现应保证资源释放后不再调用借用的宿主上下文。

示例：

void demo(market_data_source_plugin_t &api) {
    api.market_data_source_unload();
}

metric_t

头文件：metric.h；命名空间：thunder。

带标签的指标接口。store、counter、scalar 的名称与参数由 SDK 定义；存储、聚合和采样细节取决于宿主实现。IBKR 和 CTP 采集器使用 counter 上报一段时间内累计的 tick 数。

store

virtual void store(const metric_name_t&, const metric_value_t&, const metric_tags_t&);

记录带标签的指标值。本例记录最新价。

示例：

void demo(metric_t &api) {
    api.store("last_price", 100.0, {{"slot", "0"}});
}

counter

virtual void counter(const metric_name_t&, const metric_value_t&, const metric_tags_t&);

上报计数指标。本例上报本批次处理的 12 条行情。

示例：

void demo(metric_t &api) {
    api.counter("tick_count", 12.0, {{"source", "demo"}});
}

scalar

virtual void scalar(const metric_name_t&, const metric_value_t&, const metric_tags_t&);

上报标量指标。本例记录当前连接数；具体展示方式由宿主决定。

示例：

void demo(metric_t &api) {
    api.scalar("connections", 1.0, {{"source", "demo"}});
}

parameter_access_context_t

头文件：strategy/parameter_access_context.h；命名空间：thunder::strategy。

按名称和类型读取策略参数。参数应先在 get_parameters_meta 中声明；缺失参数或类型不匹配的行为未在接口头文件中规定。

int_parameter

virtual int64_t int_parameter(const std::string &);

按键读取 int64_t 参数。示例键 volume 应在参数元数据中以对应类型声明。

示例：

void demo(parameter_access_context_t &api) {
    const int64_t value = api.int_parameter("volume");
    (void)value;
}

double_parameter

virtual double double_parameter(const std::string &);

按键读取 double 参数。示例键 threshold 应在参数元数据中以对应类型声明。

示例：

void demo(parameter_access_context_t &api) {
    const double value = api.double_parameter("threshold");
    (void)value;
}

string_parameter

virtual std::string string_parameter(const std::string &);

按键读取 std::string 参数。示例键 instrument 应在参数元数据中以对应类型声明。

示例：

void demo(parameter_access_context_t &api) {
    const std::string value = api.string_parameter("instrument");
    (void)value;
}

parameter_context_t

头文件：strategy/parameter_context.h；命名空间：thunder::strategy。

框架传给 strategy_t::get_parameters_meta 的元数据上下文。

继承接口：logger_t、metric_t、environment_context_t。继承函数的参数及示例见对应基类。

此类没有新增业务函数。以下示例展示通过该阶段上下文调用继承的日志函数；指标与环境变量用法参见基类。

void demo(parameter_context_t &context) {
    context.logging(severity_levels::debug, "进入当前阶段");
}

position_access_context_t

头文件：strategy/position_access_context.h；命名空间：thunder。

按交易槽读取持仓及已实现、未实现盈亏；其命名空间是 thunder，不是 thunder::strategy。

get_position

virtual assets_t get_position(trade_slot_t);

返回交易槽持仓快照，包含多空数量、均价及明细。

示例：

void demo(position_access_context_t &api) {
    const assets_t p = api.get_position(0);
    const volume_t net = p.long_volume - p.short_volume;
    (void)net;
}

get_realized_profit

virtual price_t get_realized_profit(trade_slot_t);

返回指定交易槽的已实现盈亏。金额口径由宿主实现决定。

示例：

void demo(position_access_context_t &api) {
    const price_t profit = api.get_realized_profit(0);
    (void)profit;
}

get_unrealized_profit

virtual price_t get_unrealized_profit(trade_slot_t);

返回指定交易槽的未实现盈亏。金额口径由宿主实现决定。

示例：

void demo(position_access_context_t &api) {
    const price_t profit = api.get_unrealized_profit(0);
    (void)profit;
}

runtime_context_t

头文件：strategy/runtime_context.h；命名空间：thunder::strategy。

部署时由引擎交给策略的运行服务。strategy_arbitrage 保存其地址，用于报单、状态、持仓、定时器和汇率操作。仅在框架保证的生命周期内使用。

insert_order

virtual primary_order_ref_t insert_order(const order_parameter_t&);

按交易槽提交订单并返回主引用；空引用表示未得到有效主引用。价格、数量、类型及开平标志应匹配合约和通道能力，后续状态以订单回报为准。

示例：

void demo(runtime_context_t &api) {
    order_parameter_t order{};
    order.slot = 0;
    order.type = order_type_t::NORMAL_LIMIT_ORDER;
    order.direction = order_direction_t::BUY;
    order.offset = order_offset_t::INCREASE;
    order.volume = 1;
    order.price = 100.0; // 演示价，调用前按合约步长及行情校验。
    const auto ref = api.insert_order(order);
    if (!ref) {
        api.logging(severity_levels::warning, "未获得有效订单引用");
    }
}

cancel_order

virtual last_error_id_t cancel_order(const cancellation_parameter_t&);

提交撤单请求，参数包含交易槽和订单引用。NO_ERROR 不代表已经撤单成功，应等待状态回报。

示例：

void demo(runtime_context_t &api, trade_slot_t slot, const primary_order_ref_t &primary, const secondary_order_ref_t &secondary) {
    cancellation_parameter_t request{};
    request.slot = slot;
    request.primary_ref = primary;
    request.secondary_ref = secondary;
    const auto error = api.cancel_order(request);
    if (error != last_error_id_t::NO_ERROR) {
        api.logging(severity_levels::warning, "撤单请求未成功提交");
    }
}

is_channel_valid

virtual bool is_channel_valid(trade_slot_t);

检查交易槽对应通道当前是否有效；返回 true 也不能保证后续请求必然成功。

示例：

void demo(runtime_context_t &api) {
    const bool available = api.is_channel_valid(0);
    (void)available;
}

get_shared_value

virtual bool get_shared_value(shared_index_id_t, double &ret);

按共享索引读取 double 值，经引用输出；只有返回 true 时使用结果。

示例：

void demo(runtime_context_t &api, shared_index_id_t index) {
    double value = 0.0;
    if (api.get_shared_value(index, value)) {
        const double snapshot = value;
        (void)snapshot;
    }
}

increase_shared_value

virtual bool increase_shared_value(shared_index_id_t, double dt, function<bool(double)>);

增加共享值，返回操作结果。第三个参数是条件函数；头文件未规定传入条件的是更新前还是更新后值，也未承诺并发语义。本例使用恒真条件，不依赖这些细节。

示例：

void demo(runtime_context_t &api, shared_index_id_t index) {
    const bool ok = api.increase_shared_value(index, 1.0, [](double) { return true; });
    (void)ok;
}

decrease_shared_value

virtual bool decrease_shared_value(shared_index_id_t, double dt, function<bool(double)>);

减少共享值，返回操作结果。第三个参数是条件函数；头文件未规定传入条件的是更新前还是更新后值，也未承诺并发语义。本例使用恒真条件，不依赖这些细节。

示例：

void demo(runtime_context_t &api, shared_index_id_t index) {
    const bool ok = api.decrease_shared_value(index, 1.0, [](double) { return true; });
    (void)ok;
}

set_shared_value

virtual bool set_shared_value(shared_index_id_t, double new_value, function<bool(double)>);

设置共享值，返回操作结果。第三个参数是条件函数；头文件未规定传入条件的是更新前还是更新后值，也未承诺并发语义。本例使用恒真条件，不依赖这些细节。

示例：

void demo(runtime_context_t &api, shared_index_id_t index) {
    const bool ok = api.set_shared_value(index, 10.0, [](double) { return true; });
    (void)ok;
}

query_commission

virtual bool query_commission(const instrument_unique_name_t&, commission_t&);

按合约唯一名称查询手续费结构；成功时填充 commission_t。不可用时返回 false，不能当成零手续费。

示例：

void demo(runtime_context_t &api, const instrument_unique_name_t &instrument) {
    commission_t commission;
    if (api.query_commission(instrument, commission)) {
        const auto text = commission.to_string();
        (void)text;
    }
}

calculate_commission

virtual bool calculate_commission(trade_slot_t, price_t, volume_t, commission_value_t&);

根据槽位、价格和数量计算开仓、平今、平昨手续费。返回 true 后读取各金额和币种。

示例：

void demo(runtime_context_t &api) {
    commission_value_t fees{};
    if (api.calculate_commission(0, 100.0, 1, fees)) {
        const auto open_fee = fees.increase;
        const auto currency = fees.current_type;
        (void)open_fee; (void)currency;
    }
}

create_timer

virtual timer_handler_t create_timer(size_t timeout_ms, timer_callback_t&&, bool enable_lock = true);

创建毫秒定时任务并返回句柄。回调接收无参数；enable_lock 默认为 true，具体锁语义由宿主定义。套利示例在回调中再次创建定时器实现周期调度，因此不要假设它自动重复。

示例：

void demo(runtime_context_t &api) {
    const timer_handler_t timer = api.create_timer(1000, []() {
        // 到期后执行任务；需要周期执行时按宿主约定再次调度。
    });
    (void)timer;
}

cancel_timer

virtual void cancel_timer(timer_handler_t);

按句柄取消定时器。退出时同步处理回调捕获对象的生命周期；接口未承诺取消会等待正在执行的回调结束。

示例：

void demo(runtime_context_t &api, timer_handler_t timer) {
    api.cancel_timer(timer);
}

get_utc_time

virtual time_point_t get_utc_time();

返回 UTC 系统时间点 time_point_t。

示例：

void demo(runtime_context_t &api) {
    const time_point_t now = api.get_utc_time();
    (void)now;
}

get_trade_permission_state

virtual void get_trade_permission_state(bool &increase_enabled, bool &decrease_today_enabled, bool &decrease_yesterday_enabled);

通过三个 bool 引用分别输出开仓、平今和平昨权限。

示例：

void demo(runtime_context_t &api) {
    bool increase = false, today = false, yesterday = false;
    api.get_trade_permission_state(increase, today, yesterday);
    (void)increase; (void)today; (void)yesterday;
}

is_trading

virtual bool is_trading(trade_slot_t, const zoned_time_point_t&);

按交易槽和带时区时间检查交易时段。当前参数是 zoned_time_point_t，应显式传入时区；部分旧项目直接传 UTC time_point_t 的写法不适用于此声明。

示例：

void demo(runtime_context_t &api) {
    const zoned_time_point_t local_time{"Asia/Shanghai", api.get_utc_time()};
    const bool active = api.is_trading(0, local_time);
    (void)active;
}

get_trade_day

virtual trade_day_t get_trade_day(trade_slot_t);

返回槽位对应的交易日字符串。交易日与自然日不一定相同，格式由对应通道定义。

示例：

void demo(runtime_context_t &api) {
    const trade_day_t day = api.get_trade_day(0);
    (void)day;
}

to_uniform_price

virtual uniform_price_t to_uniform_price(trade_slot_t, price_t);

将价格转换为统一单位、统一币种及同时统一单位和币种的三个结果。

示例：

void demo(runtime_context_t &api) {
    const uniform_price_t converted = api.to_uniform_price(0, 100.0);
    const price_t unified = converted.uniform_price;
    (void)unified;
}

update_currency_exchange_rate

virtual void update_currency_exchange_rate(const currency_t &from, const currency_t &to, ratio_t, bool global = false);

更新 from 到 to 的换算比率；global 默认为 false。示例将 1 USD 换算为 7 CNY；作用范围及反向汇率维护由宿主实现决定。

示例：

void demo(runtime_context_t &api) {
    api.update_currency_exchange_rate(currency_t::USD, currency_t::CNY, 7.0, false);
}

serializable_merge_t

头文件：serializable.h；命名空间：thunder。

二进制序列化的扩展接口，提供合并式反序列化。哪些字段覆盖或累加由实现类定义。

继承接口：binary_serializable_t。继承函数的参数及示例见对应基类。

deserialize_merge_from

virtual void deserialize_merge_from(boost::archive::binary_iarchive &);

从二进制归档读取并合并到当前对象；合并规则由实现定义。

示例：

void demo(serializable_merge_t &api, std::istream &stream) {
    boost::archive::binary_iarchive archive(stream);
    api.deserialize_merge_from(archive);
}

signal_meta_context_t

头文件：strategy/signal_meta_context.h；命名空间：thunder::strategy。

框架传给策略信号声明及调用函数的上下文。

继承接口：logger_t、metric_t、environment_context_t。继承函数的参数及示例见对应基类。

此类没有新增业务函数。以下示例展示通过该阶段上下文调用继承的日志函数；指标与环境变量用法参见基类。

void demo(signal_meta_context_t &context) {
    context.logging(severity_levels::debug, "进入当前阶段");
}

source_plugin_context_t

头文件：source/source_plugin_context.h；命名空间：thunder。

引擎为行情源和交易源提供的公共上下文。初始化时保存宿主传入的指针，不接管其所有权。

继承接口：logger_t、metric_t。继承函数的参数及示例见对应基类。

query_instrument_configuration

virtual bool query_instrument_configuration(const instrument_unique_name_t&, std::map<source_name_t, instrument_t>&);

查询多个源提供的合约配置。输出映射的键为源名称；应选取与当前通道匹配的条目。

示例：

void demo(source_plugin_context_t &api, const instrument_unique_name_t &name, const source_name_t &source) {
    std::map<source_name_t, instrument_t> configurations;
    if (api.query_instrument_configuration(name, configurations)) {
        if (const auto it = configurations.find(source); it != configurations.end()) {
            const instrument_t instrument = it->second;
            (void)instrument;
        }
    }
}

upload_instrument_configuration

virtual void upload_instrument_configuration(const source_name_t&, const instrument_unique_name_t&, instrument_t&&);

上传指定源、指定合约的配置，第三个参数是右值引用。

示例：

void demo(source_plugin_context_t &api, const source_name_t &source, instrument_t instrument) {
    const auto name = instrument.unique_name;
    api.upload_instrument_configuration(source, name, std::move(instrument));
}

get_configuration

virtual source_plugin_configuration_t get_configuration() const;

获取当前源实例配置，JSON 位于 json_config 成员中。

示例：

void demo(source_plugin_context_t &api) {
    const source_plugin_configuration_t configuration = api.get_configuration();
    const boost::json::value json = configuration.json_config;
    (void)json;
}

get_instance_index

virtual size_t get_instance_index() const;

返回插件实例索引。IBKR 和 CTP 交易源将其写入订单引用的 account_number 字段，需遵守该字段范围。

示例：

void demo(source_plugin_context_t &api) {
    const size_t index = api.get_instance_index();
    (void)index;
}

source_plugin_t

头文件：source/source_plugin.h；命名空间：thunder。

行情源和交易源的公共基类。实现插件时继承 market_data_source_plugin_t 或 trade_source_plugin_t。配置字段模式是字段名到说明的映射，不是 JSON Schema。

get_configuration_schema

virtual configuration_schema_t get_configuration_schema() const;

返回配置字段名到说明的映射。IBKR 使用 name、host、port、client_id 等字段。

示例：

void demo(source_plugin_t &api) {
    const auto fields = api.get_configuration_schema();
    for (const auto &[name, description] : fields) {
        (void)name; (void)description;
    }
}

get_plugin_name

virtual std::string get_plugin_name() const;

返回插件类型名称，例如 ibkr_tws_md；与实例唯一名称不同。

示例：

void demo(source_plugin_t &api) {
    const std::string name = api.get_plugin_name();
    (void)name;
}

is_source_pending

virtual bool is_source_pending();

返回源是否处于 pending 状态。头文件规定 pending 期间引擎拒绝操作请求。

示例：

void demo(source_plugin_t &api) {
    const bool pending = api.is_source_pending();
    (void)pending;
}

is_source_online

virtual bool is_source_online();

返回源的在线状态。具体登录和连接判定由插件实现。

示例：

void demo(source_plugin_t &api) {
    const bool online = api.is_source_online();
    (void)online;
}

get_source_state

virtual void get_source_state(boost::json::value& out);

将用于控制面板展示的自定义状态写入 JSON 输出参数。不要展示口令等敏感配置。

示例：

void demo(source_plugin_t &api) {
    boost::json::value state;
    api.get_source_state(state);
    const std::string text = boost::json::serialize(state);
    (void)text;
}

configuration_hot_update

virtual void configuration_hot_update();

由宿主在配置更新后调用。接口没有配置参数，插件通过已保存的 source_plugin_context_t 重新读取配置；是否重连取决于实现。

示例：

void demo(source_plugin_t &api) {
    api.configuration_hot_update();
}

symbol_validation

virtual bool symbol_validation(const instrument_unique_name_t&);

判断插件是否接受合约标识。IBKR 行情源检查类型是否为 IBKR_TWS_L1，不能将 true 等同于合约已被远端确认。

示例：

void demo(source_plugin_t &api, const instrument_unique_name_t &instrument) {
    const bool accepted = api.symbol_validation(instrument);
    (void)accepted;
}

get_source_unique_name

virtual std::string get_source_unique_name();

返回当前源实例的唯一名称。IBKR 实现从配置的 name 字段读取。

示例：

void demo(source_plugin_t &api) {
    const std::string unique_name = api.get_source_unique_name();
    (void)unique_name;
}

calculate_source_unique_name

virtual std::string calculate_source_unique_name(const boost::json::value&) const;

从给定 JSON 配置计算实例唯一名称。配置解析失败可能抛出异常，格式由插件决定。

示例：

void demo(source_plugin_t &api, const boost::json::value &config) {
    const std::string name = api.calculate_source_unique_name(config);
    (void)name;
}

strategy_base_imp_t

头文件：strategy/strategy_base_imp.h；命名空间：thunder::strategy。

继承 strategy_t 的信号辅助抽象基类。已实现信号声明和分派，派生类仍须实现策略生命周期及其他纯虚函数。使用时链接 strategy_base_imp 库。

继承接口：strategy_t。继承函数的参数及示例见对应基类。

get_signal_struct

virtual const signal_controller_t & get_signal_struct(signal_meta_context_t&);

受保护的纯虚函数，返回信号名到元数据与处理器的映射引用。派生类可用 BEGIN_SIGNAL_HANDLER_DEF 等宏实现；映射及其中捕获的对象必须保持有效。

示例：

// 以下成员放在策略派生类内；其他策略纯虚函数仍需实现。
const signal_controller_t &get_signal_struct(signal_meta_context_t &) override {
    return handlers_;
}
signal_controller_t handlers_; // 放在 strategy_base_imp_t 派生类中。

get_signal_declares

void get_signal_declares(signal_declares_t &signals, signal_meta_context_t&);

将信号参数名称、类型签名和说明输出到映射。strategy_base_imp_t 从 get_signal_struct 读取并写入，现有输出映射不会自动清空。

示例：

void demo(strategy_base_imp_t &api, signal_meta_context_t &context) {
    signal_declares_t declarations;
    api.get_signal_declares(declarations, context);
}

invoke_signal

std::string invoke_signal(const signal_name_t &name, signal_argument_list_t &args, signal_meta_context_t&);

按信号名称分派字符串参数并返回结果文本。strategy_base_imp_t 对名称不存在、参数数量不匹配或处理器无效抛出 runtime_error；参数转换也可能失败。

示例：

void demo(strategy_base_imp_t &api, const signal_name_t &name, signal_argument_list_t &arguments, signal_meta_context_t &context) {
    try {
        const std::string result = api.invoke_signal(name, arguments, context);
        (void)result;
    } catch (const std::exception &) {
        // 调用方记录或向界面报告信号错误。
    }
}

strategy_meta_context_t

头文件：strategy/strategy_meta_context.h；命名空间：thunder::strategy。

提供策略数值 ID 和 UUID 的基础接口。

get_strategy_id

virtual strategy_id_t get_strategy_id();

返回当前策略的数值标识。

示例：

void demo(strategy_meta_context_t &api) {
    const strategy_id_t id = api.get_strategy_id();
    (void)id;
}

get_strategy_uuid

virtual boost::uuids::uuid get_strategy_uuid();

返回策略 UUID，类型为 boost::uuids::uuid。

示例：

void demo(strategy_meta_context_t &api) {
    const auto uuid = api.get_strategy_uuid();
    (void)uuid;
}

strategy_state_manager_t

头文件：strategy_state_manager.h；命名空间：thunder。

以字符串键访问框架管理的策略状态。下列函数均由 STRATEGY_STATE_ACCESS_INTERFACE 宏展开；每种类型分别提供可写引用访问和存在性查询。首次访问的创建及默认值语义取决于宿主；恢复后不要无条件重置已有状态。

int_state

int_state_t &int_state(const std::string &key);

返回 int_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.int_state("demo.int");
    state = 1;
}

int_state_exists

bool int_state_exists(const std::string &key) const;

查询 int_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.int_state_exists("demo.int");
    (void)exists;
}

uint_state

uint_state_t &uint_state(const std::string &key);

返回 uint_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.uint_state("demo.uint");
    state = 1u;
}

uint_state_exists

bool uint_state_exists(const std::string &key) const;

查询 uint_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.uint_state_exists("demo.uint");
    (void)exists;
}

double_state

double_state_t &double_state(const std::string &key);

返回 double_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.double_state("demo.double");
    state = 1.5;
}

double_state_exists

bool double_state_exists(const std::string &key) const;

查询 double_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.double_state_exists("demo.double");
    (void)exists;
}

string_state

string_state_t &string_state(const std::string &key);

返回 string_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.string_state("demo.string");
    state = "ready";
}

string_state_exists

bool string_state_exists(const std::string &key) const;

查询 string_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.string_state_exists("demo.string");
    (void)exists;
}

int_int_map_state

int_int_map_state_t &int_int_map_state(const std::string &key);

返回 int_int_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.int_int_map_state("demo.int_int_map");
    state[0] = 1;
}

int_int_map_state_exists

bool int_int_map_state_exists(const std::string &key) const;

查询 int_int_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.int_int_map_state_exists("demo.int_int_map");
    (void)exists;
}

int_uint_map_state

int_uint_map_state_t &int_uint_map_state(const std::string &key);

返回 int_uint_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.int_uint_map_state("demo.int_uint_map");
    state[0] = 1;
}

int_uint_map_state_exists

bool int_uint_map_state_exists(const std::string &key) const;

查询 int_uint_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.int_uint_map_state_exists("demo.int_uint_map");
    (void)exists;
}

int_double_map_state

int_double_map_state_t &int_double_map_state(const std::string &key);

返回 int_double_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.int_double_map_state("demo.int_double_map");
    state[0] = 1.5;
}

int_double_map_state_exists

bool int_double_map_state_exists(const std::string &key) const;

查询 int_double_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.int_double_map_state_exists("demo.int_double_map");
    (void)exists;
}

int_string_map_state

int_string_map_state_t &int_string_map_state(const std::string &key);

返回 int_string_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.int_string_map_state("demo.int_string_map");
    state[0] = "ready";
}

int_string_map_state_exists

bool int_string_map_state_exists(const std::string &key) const;

查询 int_string_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.int_string_map_state_exists("demo.int_string_map");
    (void)exists;
}

uint_int_map_state

uint_int_map_state_t &uint_int_map_state(const std::string &key);

返回 uint_int_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.uint_int_map_state("demo.uint_int_map");
    state[0] = 1;
}

uint_int_map_state_exists

bool uint_int_map_state_exists(const std::string &key) const;

查询 uint_int_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.uint_int_map_state_exists("demo.uint_int_map");
    (void)exists;
}

uint_uint_map_state

uint_uint_map_state_t &uint_uint_map_state(const std::string &key);

返回 uint_uint_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.uint_uint_map_state("demo.uint_uint_map");
    state[0] = 1;
}

uint_uint_map_state_exists

bool uint_uint_map_state_exists(const std::string &key) const;

查询 uint_uint_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.uint_uint_map_state_exists("demo.uint_uint_map");
    (void)exists;
}

uint_double_map_state

uint_double_map_state_t &uint_double_map_state(const std::string &key);

返回 uint_double_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.uint_double_map_state("demo.uint_double_map");
    state[0] = 1.5;
}

uint_double_map_state_exists

bool uint_double_map_state_exists(const std::string &key) const;

查询 uint_double_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.uint_double_map_state_exists("demo.uint_double_map");
    (void)exists;
}

uint_string_map_state

uint_string_map_state_t &uint_string_map_state(const std::string &key);

返回 uint_string_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.uint_string_map_state("demo.uint_string_map");
    state[0] = "ready";
}

uint_string_map_state_exists

bool uint_string_map_state_exists(const std::string &key) const;

查询 uint_string_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.uint_string_map_state_exists("demo.uint_string_map");
    (void)exists;
}

string_int_map_state

string_int_map_state_t &string_int_map_state(const std::string &key);

返回 string_int_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.string_int_map_state("demo.string_int_map");
    state["leg0"] = 1;
}

string_int_map_state_exists

bool string_int_map_state_exists(const std::string &key) const;

查询 string_int_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.string_int_map_state_exists("demo.string_int_map");
    (void)exists;
}

string_uint_map_state

string_uint_map_state_t &string_uint_map_state(const std::string &key);

返回 string_uint_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.string_uint_map_state("demo.string_uint_map");
    state["leg0"] = 1;
}

string_uint_map_state_exists

bool string_uint_map_state_exists(const std::string &key) const;

查询 string_uint_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.string_uint_map_state_exists("demo.string_uint_map");
    (void)exists;
}

string_double_map_state

string_double_map_state_t &string_double_map_state(const std::string &key);

返回 string_double_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.string_double_map_state("demo.string_double_map");
    state["leg0"] = 1.5;
}

string_double_map_state_exists

bool string_double_map_state_exists(const std::string &key) const;

查询 string_double_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.string_double_map_state_exists("demo.string_double_map");
    (void)exists;
}

string_string_map_state

string_string_map_state_t &string_string_map_state(const std::string &key);

返回 string_string_map_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.string_string_map_state("demo.string_string_map");
    state["leg0"] = "ready";
}

string_string_map_state_exists

bool string_string_map_state_exists(const std::string &key) const;

查询 string_string_map_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.string_string_map_state_exists("demo.string_string_map");
    (void)exists;
}

int_vector_state

int_vector_state_t &int_vector_state(const std::string &key);

返回 int_vector_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.int_vector_state("demo.int_vector");
    state.push_back(1);
}

int_vector_state_exists

bool int_vector_state_exists(const std::string &key) const;

查询 int_vector_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.int_vector_state_exists("demo.int_vector");
    (void)exists;
}

uint_vector_state

uint_vector_state_t &uint_vector_state(const std::string &key);

返回 uint_vector_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.uint_vector_state("demo.uint_vector");
    state.push_back(1);
}

uint_vector_state_exists

bool uint_vector_state_exists(const std::string &key) const;

查询 uint_vector_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.uint_vector_state_exists("demo.uint_vector");
    (void)exists;
}

double_vector_state

double_vector_state_t &double_vector_state(const std::string &key);

返回 double_vector_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.double_vector_state("demo.double_vector");
    state.push_back(1.5);
}

double_vector_state_exists

bool double_vector_state_exists(const std::string &key) const;

查询 double_vector_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.double_vector_state_exists("demo.double_vector");
    (void)exists;
}

string_vector_state

string_vector_state_t &string_vector_state(const std::string &key);

返回 string_vector_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.string_vector_state("demo.string_vector");
    state.push_back("ready");
}

string_vector_state_exists

bool string_vector_state_exists(const std::string &key) const;

查询 string_vector_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.string_vector_state_exists("demo.string_vector");
    (void)exists;
}

int_list_state

int_list_state_t &int_list_state(const std::string &key);

返回 int_list_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.int_list_state("demo.int_list");
    state.push_back(1);
}

int_list_state_exists

bool int_list_state_exists(const std::string &key) const;

查询 int_list_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.int_list_state_exists("demo.int_list");
    (void)exists;
}

uint_list_state

uint_list_state_t &uint_list_state(const std::string &key);

返回 uint_list_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.uint_list_state("demo.uint_list");
    state.push_back(1);
}

uint_list_state_exists

bool uint_list_state_exists(const std::string &key) const;

查询 uint_list_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.uint_list_state_exists("demo.uint_list");
    (void)exists;
}

double_list_state

double_list_state_t &double_list_state(const std::string &key);

返回 double_list_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.double_list_state("demo.double_list");
    state.push_back(1.5);
}

double_list_state_exists

bool double_list_state_exists(const std::string &key) const;

查询 double_list_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.double_list_state_exists("demo.double_list");
    (void)exists;
}

string_list_state

string_list_state_t &string_list_state(const std::string &key);

返回 string_list_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.string_list_state("demo.string_list");
    state.push_back("ready");
}

string_list_state_exists

bool string_list_state_exists(const std::string &key) const;

查询 string_list_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.string_list_state_exists("demo.string_list");
    (void)exists;
}

int_deque_state

int_deque_state_t &int_deque_state(const std::string &key);

返回 int_deque_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.int_deque_state("demo.int_deque");
    state.push_back(1);
}

int_deque_state_exists

bool int_deque_state_exists(const std::string &key) const;

查询 int_deque_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.int_deque_state_exists("demo.int_deque");
    (void)exists;
}

uint_deque_state

uint_deque_state_t &uint_deque_state(const std::string &key);

返回 uint_deque_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.uint_deque_state("demo.uint_deque");
    state.push_back(1);
}

uint_deque_state_exists

bool uint_deque_state_exists(const std::string &key) const;

查询 uint_deque_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.uint_deque_state_exists("demo.uint_deque");
    (void)exists;
}

double_deque_state

double_deque_state_t &double_deque_state(const std::string &key);

返回 double_deque_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.double_deque_state("demo.double_deque");
    state.push_back(1.5);
}

double_deque_state_exists

bool double_deque_state_exists(const std::string &key) const;

查询 double_deque_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.double_deque_state_exists("demo.double_deque");
    (void)exists;
}

string_deque_state

string_deque_state_t &string_deque_state(const std::string &key);

返回 string_deque_state_t 的可写引用。示例演示写入；初始化逻辑应结合对应的 exists 函数，避免覆盖恢复值。

示例：

void demo(strategy_state_manager_t &api) {
    auto &state = api.string_deque_state("demo.string_deque");
    state.push_back("ready");
}

string_deque_state_exists

bool string_deque_state_exists(const std::string &key) const;

查询 string_deque_state_t 类型的指定键是否已存在。存在性按类型查询，不应假定与其他状态类型共享命名空间。

示例：

void demo(strategy_state_manager_t &api) {
    const bool exists = api.string_deque_state_exists("demo.string_deque");
    (void)exists;
}

strategy_t

头文件：strategy/strategy.h；命名空间：thunder::strategy。

策略主接口，由策略实现，框架调用生命周期、行情、订单和元数据回调。STRATEGY_EXPORT 导出策略工厂。示例中的回调调用用于说明参数，实际策略由框架驱动。

get_description

virtual std::string get_description(description_meta_context_t&);

返回策略简介，框架传入描述元数据上下文。

示例：

void demo(strategy_t &api, description_meta_context_t &context) {
    const std::string description = api.get_description(context);
    (void)description;
}

get_dashboard_meta

virtual dashboard_meta_t get_dashboard_meta(dashboard_meta_context_t&);

返回仪表盘二维布局，每项包含指标指针、名称、颜色和坐标轴等。指针指向的原子数值必须在使用期间有效。

示例：

void demo(strategy_t &api, dashboard_meta_context_t &context) {
    const auto dashboard = api.get_dashboard_meta(context);
    (void)dashboard;
}

get_metrics_abstract_row

virtual void get_metrics_abstract_row(std::vector<double>&);

填充摘要行数值。各列的含义和顺序应与策略界面约定一致。

示例：

void demo(strategy_t &api) {
    std::vector<double> row;
    api.get_metrics_abstract_row(row);
}

get_parameters_meta

virtual std::map<std::string, parameter_item_meta_t> get_parameters_meta(parameter_context_t&);

返回参数名到 parameter_item_meta_t 的映射。参数类型、说明及默认值应匹配运行时 int/double/string_parameter 访问。

示例：

void demo(strategy_t &api, parameter_context_t &context) {
    const auto parameters = api.get_parameters_meta(context);
    (void)parameters;
}

on_user_defined_savepoint

virtual bool on_user_defined_savepoint(strategy_user_defined_savepoint_t&);

生成自定义保存点，经字符串引用输出；返回 false 表示未成功生成。套利策略使用 Boost 文本归档编码自己的状态。

示例：

void demo(strategy_t &api) {
    strategy_user_defined_savepoint_t payload;
    if (api.on_user_defined_savepoint(payload)) {
        // 宿主保存 payload，部署时通过 get_user_defined_savepoint 交回。
    }
}

on_initialization

virtual void on_initialization(initialization_context_t &);

策略初始化回调。可读取归档恢复状态；不要在此假定运行上下文已经可用。

示例：

void demo(strategy_t &api, initialization_context_t &context) {
    api.on_initialization(context);
}

on_deployment

virtual void on_deployment(deployment_context_t &, runtime_context_t &);

部署回调，同时获得部署上下文和运行上下文。套利策略在此保存 runtime_context_t 指针并恢复状态。

示例：

void demo(strategy_t &api, deployment_context_t &deployment, runtime_context_t &runtime) {
    api.on_deployment(deployment, runtime);
}

on_exit

virtual void on_exit(exit_context_t&);

退出回调。在实现中停止策略持有的异步任务，并处理定时器和回调捕获对象的生命周期。

示例：

void demo(strategy_t &api, exit_context_t &context) {
    api.on_exit(context);
}

on_tick

virtual void on_tick(trade_slot_t, const ::thunder::tick_t &);

收到槽位行情时回调，tick 为借用的只读引用；需长期保存时复制必要字段。

示例：

void demo(strategy_t &api, trade_slot_t slot, const tick_t &tick) {
    api.on_tick(slot, tick);
}

on_order_trade

virtual void on_order_trade(const order_trade_event_t &);

逐笔成交事件，包含成交日、时间、价格和本次成交量。由引擎触发；下例用于演示事件参数传递。

示例：

void demo(strategy_t &api, const order_trade_event_t &event) {
    api.on_order_trade(event);
}

on_order_progress

virtual void on_order_progress(const order_progress_event_t &);

订单进度事件，包含累计成交量 traded_volume 和剩余数量 remain_volume。套利策略把它交给订单执行器。由引擎触发；下例用于演示事件参数传递。

示例：

void demo(strategy_t &api, const order_progress_event_t &event) {
    api.on_order_progress(event);
}

on_order_state_change

virtual void on_order_state_change(const order_state_change_event_t &);

订单状态变化事件，例如 CANCELED；不能用撤单请求返回值替代此回报。由引擎触发；下例用于演示事件参数传递。

示例：

void demo(strategy_t &api, const order_state_change_event_t &event) {
    api.on_order_state_change(event);
}

on_secondary_ref

virtual void on_secondary_ref(const secondary_order_ref_event_t &);

接收柜台侧订单引用，供关联回报及撤单使用。套利策略检查非空后交给订单执行器。由引擎触发；下例用于演示事件参数传递。

示例：

void demo(strategy_t &api, const secondary_order_ref_event_t &event) {
    api.on_secondary_ref(event);
}

get_signal_declares

virtual void get_signal_declares(signal_declares_t &signals, signal_meta_context_t&);

将信号参数名称、类型签名和说明输出到映射。strategy_base_imp_t 从 get_signal_struct 读取并写入，现有输出映射不会自动清空。

示例：

void demo(strategy_t &api, signal_meta_context_t &context) {
    signal_declares_t declarations;
    api.get_signal_declares(declarations, context);
}

invoke_signal

virtual std::string invoke_signal(const signal_name_t &, signal_argument_list_t &, signal_meta_context_t&);

按信号名称分派字符串参数并返回结果文本。strategy_base_imp_t 对名称不存在、参数数量不匹配或处理器无效抛出 runtime_error；参数转换也可能失败。

示例：

void demo(strategy_t &api, const signal_name_t &name, signal_argument_list_t &arguments, signal_meta_context_t &context) {
    try {
        const std::string result = api.invoke_signal(name, arguments, context);
        (void)result;
    } catch (const std::exception &) {
        // 调用方记录或向界面报告信号错误。
    }
}

text_serializable_t

头文件：serializable.h；命名空间：thunder。

文本序列化契约，使用 Boost.Serialization 文本归档；不等同于 JSON。

text_serialize_to

virtual void text_serialize_to(boost::archive::text_oarchive&);

通过 Boost text 归档写入对象。调用方创建归档并保证流可用；实现类负责匹配字段顺序和版本。

示例：

void demo(text_serializable_t &api, std::ostream &stream) {
    boost::archive::text_oarchive archive(stream);
    api.text_serialize_to(archive);
}

text_deserialize_from

virtual void text_deserialize_from(boost::archive::text_iarchive&);

通过 Boost text 归档读取对象。调用方创建归档并保证流可用；实现类负责匹配字段顺序和版本。

示例：

void demo(text_serializable_t &api, std::istream &stream) {
    boost::archive::text_iarchive archive(stream);
    api.text_deserialize_from(archive);
}

tick_sink_t

头文件：data_center/tick_sink.h；命名空间：thunder::data_collector。

DataCenter 行情接收端。采集器在初始化时保存 weak_ptr，发送前 lock 并判空；start 和 stop 由接收端的生命周期管理者调用。

sink

virtual void sink(std::unique_ptr<const thunder::tick_t> tick);

提交一条只读 tick 并转移所有权。接收端不可用时不要解引用空 shared_ptr。

示例：

void demo(tick_sink_t &api, const tick_t &sample) {
    auto tick = std::make_unique<tick_t>(sample);
    api.sink(std::move(tick));
}

start

virtual void start();

启动接收端处理；该操作属于接收端生命周期，不是采集插件的 install。

示例：

void demo(tick_sink_t &api) {
    api.start();
}

stop

virtual void stop();

停止接收端处理。停止时队列如何排空由具体接收端实现规定。

示例：

void demo(tick_sink_t &api) {
    api.stop();
}

trade_source_context_t

头文件：source/trade_source_context.h；命名空间：thunder。

交易插件向引擎上报订单事件的接口。引擎再将带交易槽等信息的事件转发给策略。主引用关联引擎订单，次级引用保存通道或柜台侧标识。

on_order_trade

virtual void on_order_trade(const primary_order_ref_t&, const secondary_order_ref_t&, const trade_day_t&, const trade_time_t&, price_t, volume_t);

向引擎上报本次成交，参数依次为主引用、次级引用、交易日、成交 UTC 时间、价格和成交量。

示例：

void demo(trade_source_context_t &api, const primary_order_ref_t &primary, const secondary_order_ref_t &secondary, const trade_day_t &day, const trade_time_t &time) {
    api.on_order_trade(primary, secondary, day, time, 100.0, 1);
}

on_order_progress

virtual void on_order_progress(const primary_order_ref_t&, const secondary_order_ref_t&, completed_volume_t, remaining_volume_t);

向引擎上报累计已成交量和剩余量。例中原始数量为 3，累计成交 1，剩余 2；不要把累计量当成新增成交量。

示例：

void demo(trade_source_context_t &api, const primary_order_ref_t &primary, const secondary_order_ref_t &secondary) {
    api.on_order_progress(primary, secondary, 1, 2);
}

on_order_state_change

virtual void on_order_state_change(const primary_order_ref_t&, const secondary_order_ref_t&, order_state_t);

向引擎上报柜台已确认的订单状态，例如 CANCELED。

示例：

void demo(trade_source_context_t &api, const primary_order_ref_t &primary, const secondary_order_ref_t &secondary) {
    api.on_order_state_change(primary, secondary, order_state_t::CANCELED);
}

on_secondary_ref

virtual void on_secondary_ref(const primary_order_ref_t&, const secondary_order_ref_t&);

向引擎上报主引用与柜台次级引用的对应关系；应使用实际收到的标识。

示例：

void demo(trade_source_context_t &api, const primary_order_ref_t &primary, const secondary_order_ref_t &secondary) {
    api.on_secondary_ref(primary, secondary);
}

trade_source_plugin_t

头文件：source/trade_source_plugin.h；命名空间：thunder。

交易源插件契约，由宿主初始化并调用报单、撤单和卸载函数。通道返回只表示请求阶段结果，订单最终进度通过 trade_source_context_t 异步回报。实现类用 SOURCE_PLUGIN_EXPORT 导出。

继承接口：source_plugin_t。继承函数的参数及示例见对应基类。

trade_source_initialization

virtual void trade_source_initialization(source_plugin_context_t *, trade_source_context_t *);

宿主注入公共上下文和交易回报上下文。插件保存指针并启动连接与登录流程。

示例：

void demo(trade_source_plugin_t &api, source_plugin_context_t &source, trade_source_context_t &trade) {
    api.trade_source_initialization(&source, &trade);
}

trade_source_insert_order

virtual primary_order_ref_t trade_source_insert_order(order_type_t, const instrument_t &, order_direction_t, order_offset_t, volume_t, price_t, primary_order_ref_t);

宿主调用插件报单，依次传入订单类型、合约、方向、开平、数量、价格和主引用。插件可能补充主引用字段；空引用表示失败。IBKR 当前实现处理普通限价和市价，不能假定所有枚举均受支持。

示例：

void demo(trade_source_plugin_t &api, const instrument_t &instrument, primary_order_ref_t primary) {
    const auto ref = api.trade_source_insert_order(
        order_type_t::NORMAL_LIMIT_ORDER, instrument, order_direction_t::BUY,
        order_offset_t::INCREASE, 1, 100.0, primary);
    if (!ref) {
        // 请求阶段未得到有效引用。
    }
}

trade_source_cancel_order

virtual last_error_id_t trade_source_cancel_order(primary_order_ref_t, const instrument_t&, secondary_order_ref_t);

按主引用、合约配置和次级引用发起撤单。CTP 使用柜台订单号，IBKR 当前实现主要使用主引用中的递增部分。返回 NO_ERROR 后仍须等待异步回报。

示例：

void demo(trade_source_plugin_t &api, primary_order_ref_t primary, const instrument_t &instrument, secondary_order_ref_t secondary) {
    const auto error = api.trade_source_cancel_order(primary, instrument, secondary);
    const bool submitted = error == last_error_id_t::NO_ERROR;
    (void)submitted;
}

trade_source_get_trade_day

virtual trade_day_t trade_source_get_trade_day();

读取交易源的交易日字符串。CTP 与登录时的交易日相关；当前 IBKR 实现返回 IBKR_CONST_TRADE_DAY，不能统一按日期解析。

示例：

void demo(trade_source_plugin_t &api) {
    const trade_day_t day = api.trade_source_get_trade_day();
    (void)day;
}

trade_source_unload

virtual void trade_source_unload();

卸载交易源并终止连接、定时器和工作线程。

示例：

void demo(trade_source_plugin_t &api) {
    api.trade_source_unload();
}

API索引

binary_serializable_t

binary_serialize_to

binary_deserialize_from

commission_supplier_t

on_query_commission

dashboard_meta_context_t

data_collector_plugin_context_t

on_instrument_data

data_collector_plugin_t

get_name

get_description

get_configuration_fields

initialization

install

uninstall

update_configuration

deployment_context_t

get_slot_count

get_price_tick

get_volume_multiple

get_margin_ratio

query_instrument

get_user_defined_savepoint

get_currency_unit

description_meta_context_t

environment_context_t

get_environment_variables

exit_context_t

initialization_context_t

instrument_configuration_supplier_t

get_instrument_configuration

logger_t

logging

market_data_source_context_t

on_tick_data

market_data_source_plugin_t

market_data_source_initialization

market_data_source_on_update_subscribed_instruments_list

market_data_source_is_subscribing_instruments

market_data_source_unload

metric_t

store

counter

scalar

parameter_access_context_t

int_parameter

double_parameter

string_parameter

parameter_context_t

position_access_context_t

get_position

get_realized_profit

get_unrealized_profit

runtime_context_t

insert_order

cancel_order

is_channel_valid

get_shared_value

increase_shared_value

decrease_shared_value

set_shared_value

query_commission

calculate_commission

create_timer

cancel_timer

get_utc_time

get_trade_permission_state

is_trading

get_trade_day

to_uniform_price

update_currency_exchange_rate

serializable_merge_t

deserialize_merge_from

signal_meta_context_t

source_plugin_context_t

query_instrument_configuration

upload_instrument_configuration

get_configuration

get_instance_index