Add agent onboarding documentation and enhance API for active instruments

- Introduced AGENTS.md to provide guidelines on project structure, architecture, coding style, testing, and commit practices for agent onboarding.
- Added new APIs: `active_instrument`, `active_instruments`, `instrument_history`, and `instruments_history` to improve instrument retrieval and historical data access.
- Updated existing API methods to ensure consistency and clarity in handling active instruments and their histories.
- Enhanced integration tests to validate the new APIs and ensure proper functionality with active and inactive instruments.

Author: Cuizi7

AGENTS.md

@@ -0,0 +1,41 @@
+# Repository Guidelines
+
+## Project Structure and Module Organization
+- `rqalpha/` is the main package; core engine code is under `rqalpha/core/`, and built-in mods under `rqalpha/mod/`.
+- `rqalpha/examples/`, `strategy_test/`, and `test_strategy/` provide sample strategies/configs.
+- `tests/` is split into `tests/unittest/` and `tests/integration_tests/`; docs live in `docs/`.
+
+## Architecture Overview (for Agent Onboarding)
+- The engine is event-driven: `rqalpha/core/executor.py` consumes events and publishes them through `rqalpha/core/events.py`.
+- Strategy lifecycle hooks live in `rqalpha/core/strategy.py` (`init`, `before_trading`, `handle_bar`, `handle_tick`, `open_auction`, `after_trading`) with pre/post phases for mod hooks.
+- `rqalpha/environment.py` is the runtime registry for core services (data proxy/source, broker, portfolio, mods).
+- Extension contracts are defined in `rqalpha/interface.py`; new data/execution integrations should implement these.
+
+## Build, Test, and Development Commands
+- `pip install -e .` installs the package and `rqalpha` CLI.
+- `rqalpha run -f path/to/strategy.py -s YYYY-MM-DD -e YYYY-MM-DD` runs a backtest.
+- `make -C docs html` builds documentation locally.
+
+## Coding Style and Naming Conventions
+- Follow PEP 8: 4-space indentation, `snake_case` functions/variables, `CapWords` classes, `UPPER_SNAKE_CASE` constants.
+- Keep APIs, errors, and type hints consistent with existing `rqalpha/` modules.
+
+## Testing Guidelines
+- Use `pytest`; run `pytest tests` for the full suite.
+- Unit tests target individual modules under `tests/unittest/`.
+- Integration tests under `tests/integration_tests/` run full backtests via `rqalpha.run_func`.
+- Pattern to follow (see `tests/integration_tests/test_backtest_results/`): define strategy callbacks in-test, build a `config` dict, and use `run_and_assert_result` to compare outputs against `outs/*.txt`.
+- If not explicitly told otherwise, prefer strategy-style integration tests that exercise the full framework with real data. Agents may read bundle data or call `rqdatac` to pick concrete instruments and dates.
+
+## Commit and Pull Request Guidelines
+- Recent commits use imperative, sentence-case summaries (e.g., "Refactor ...", "Fix ...", "Update ..."). Keep messages short and scoped.
+- PRs should describe the change, link related issues if any, and include test results or rationale when tests are not run.
+
+## Agent-Specific Pointers
+- Entry points: `rqalpha/__main__.py`, `rqalpha/cmds/run.py`, and `rqalpha/main.py`.
+- For strategy behavior: `rqalpha/core/strategy.py` and `rqalpha/core/events.py`.
+- For data/instruments: `rqalpha/data/` and `rqalpha/interface.py`; for orders/portfolio: `rqalpha/portfolio/` and `rqalpha/mod/rqalpha_mod_sys_accounts/`.
+
+## Documentation and Data Notes
+- Update `docs/` when public behavior changes.
+- Data access and strategy behavior are tightly coupled to RQAlpha/RQData; avoid changing data contracts without migration notes.

CHANGELOG.rst

@@ -12,8 +12,31 @@ CHANGELOG
 **[不兼容改动]**
 
 - `get_position` 不能传入还未上市的 order_book_id，传入此类代码会抛出异常
+- `Instrument.listing_at` 更名为 `active_at`，旧方法移除
 
-**[新增 API]**
+**[新增功能]**
+
+- 新增 `active_instrument` / `active_instruments` API，用于获取当前交易时点正在活跃（上市中、未退市）的合约对象
+- 新增 `instrument_history`/ `instruments_history` API，用于获取合约历史记录列表（包含未上市或已退市合约）
+
+**[重构和改善]**
+
+- API 参数校验支持自动转换（Instrument/symbol -> order_book_id），统一下单与查询路径
+- 风控、下单、分析等模块统一基于交易时点的合约对象进行判断
+
+**[其他改进]**
+
+- 依赖调整：`typing-extensions` 版本提升至 `>=4.5.0`
+- 更新翻译文件
+
+**[For Mod 开发者] 接口变更指引**
+
+- `DataProxy` 增加合约历史/活跃合约相关接口（如 `get_active_instrument(s)`、`get_instrument_history`、`get_instruments_history` 等）
+- `Environment.get_instrument` 及 `DataProxy` 旧合约相关接口（因不符合新假设）标记为废弃
+- 参数校验体系调整
+  - 新增 `assure_that` 支持参数自动转换（如 Instrument / symbol -> order_book_id），若 API 内部需要参数格式转换，推荐直接使用该功能将检验和转换合并
+  - 移除部分依赖 “全局唯一 Instrument” 假设的校验规则，如 `is_valid_stock` / `is_valid_future` / `is_valid_instrument` 等
+  - 新增 `is_valid_order_book_id` 用于 order_book_id 的基础合法性检验/转换
 
 
 6.0.0

docs/source/api/base_api.rst

@@ -325,6 +325,30 @@ instruments - 合约详细信息
 ..  autofunction:: instruments
 
 
+active_instrument - 当前交易时点活跃合约
+------------------------------------------------------
+
+..  autofunction:: active_instrument
+
+
+instrument_history - 合约历史记录
+------------------------------------------------------
+
+..  autofunction:: instrument_history
+
+
+active_instruments - 批量活跃合约
+------------------------------------------------------
+
+..  autofunction:: active_instruments
+
+
+instruments_history - 批量合约历史记录
+------------------------------------------------------
+
+..  autofunction:: instruments_history
+
+
 history_bars - 某一合约历史 bar 数据
 ------------------------------------------------------
 

rqalpha/apis/api_base.py

@@ -610,7 +610,7 @@ def all_instruments(type=None, date=None):
     else:
         types = None
 
-    result = env.data_proxy.all_instruments(types, dt)
+    result = env.data_proxy.get_all_instruments(types, dt)
     if types is not None and len(types) == 1:
         data = []
         for i in result:
@@ -641,6 +641,7 @@ def all_instruments(type=None, date=None):
 def instruments(id_or_symbols: Union[str, Iterable[str]]) -> Union[None, Instrument, List[Instrument]]:
     """
     获取某个国家市场内一个或多个合约的详细信息。目前仅支持中国市场。
+    若传入单个合约代码且存在多个历史合约，则返回合约列表；找不到合约时返回 None。
 
     :param id_or_symbols: 合约代码或者合约代码列表
 
@@ -702,12 +703,87 @@ def instruments(id_or_symbols: Union[str, Iterable[str]]) -> Union[None, Instrum
     EXECUTION_PHASE.AFTER_TRADING,
     EXECUTION_PHASE.SCHEDULED,
 )
-@apply_rules(assure_that("id_or_sym").is_active_instrument())
-def active_instrument(id_or_sym: Union[str, Instrument]) -> Instrument:
-    return cast(Instrument, id_or_sym)
+@apply_rules(assure_that("order_book_id").is_active_instrument())
+def active_instrument(order_book_id: Union[str, Instrument]) -> Instrument:
+    """
+    获取当前交易时点正在活跃（上市中、未退市）的合约对象。
+
+    :param order_book_id: 合约代码或 Instrument
+    :return: 当前交易时点有效的 Instrument 对象
+    :raises: 若合约在当前交易时点未上市或已退市，会抛出异常
+    """
+    return cast(Instrument, order_book_id)
+
+
+@export_as_api
+@ExecutionContext.enforce_phase(
+    EXECUTION_PHASE.ON_INIT,
+    EXECUTION_PHASE.BEFORE_TRADING,
+    EXECUTION_PHASE.OPEN_AUCTION,
+    EXECUTION_PHASE.ON_BAR,
+    EXECUTION_PHASE.ON_TICK,
+    EXECUTION_PHASE.AFTER_TRADING,
+    EXECUTION_PHASE.SCHEDULED,
+)
+@apply_rules(assure_that("order_book_id").is_valid_order_book_id())
+def instrument_history(order_book_id: str) -> list[Instrument]:
+    """
+    获取指定合约的历史记录列表（包含未上市或已退市合约）。
+
+    :param order_book_id: 合约代码或 symbol
+    :return: 合约历史列表，按上市时间排序
+    """
+    return Environment.get_instance().data_proxy.get_instrument_history(order_book_id)
+
+
+@export_as_api
+@ExecutionContext.enforce_phase(
+    EXECUTION_PHASE.ON_INIT,
+    EXECUTION_PHASE.BEFORE_TRADING,
+    EXECUTION_PHASE.OPEN_AUCTION,
+    EXECUTION_PHASE.ON_BAR,
+    EXECUTION_PHASE.ON_TICK,
+    EXECUTION_PHASE.AFTER_TRADING,
+    EXECUTION_PHASE.SCHEDULED,
+)
+@apply_rules(assure_that("order_book_ids").is_valid_oid_list())
+def active_instruments(
+    order_book_ids: Union[str, Instrument, Iterable[str], Iterable[Instrument]]
+) -> dict[str, Instrument]:
+    """
+    批量获取当前交易时点已上市的合约对象。
 
+    :param order_book_ids: 合约代码或 Instrument 的可迭代对象
+    :return: order_book_id -> Instrument 的映射
+    """
+    env = Environment.get_instance()
+    dt = env.trading_dt
+    return env.data_proxy.get_active_instruments(cast(list, order_book_ids), dt)
+
+
+@export_as_api
+@ExecutionContext.enforce_phase(
+    EXECUTION_PHASE.ON_INIT,
+    EXECUTION_PHASE.BEFORE_TRADING,
+    EXECUTION_PHASE.OPEN_AUCTION,
+    EXECUTION_PHASE.ON_BAR,
+    EXECUTION_PHASE.ON_TICK,
+    EXECUTION_PHASE.AFTER_TRADING,
+    EXECUTION_PHASE.SCHEDULED,
+)
+@apply_rules(assure_that("order_book_ids").is_valid_oid_list())
+def instruments_history(
+    order_book_ids: Union[str, Instrument, Iterable[str], Iterable[Instrument]]
+) -> list[Instrument]:
+    """
+    批量获取合约历史记录列表（包含已退市合约）。
+
+    :param order_book_ids: 合约代码或 Instrument 的可迭代对象
+    :return: 合约对象列表
+    """
+    env = Environment.get_instance()
+    return env.data_proxy.get_instruments_history(cast(list, order_book_ids))
 
-# TODO: 提供 instrument_history, active_instruments, instruments_history 等 API
 
 @export_as_api
 @apply_rules(
@@ -1002,4 +1078,3 @@ def repay(amount, account_type=DEFAULT_ACCOUNT_TYPE.STOCK):
     env = Environment.get_instance()
     return env.portfolio.finance_repay(amount * -1, account_type)
 
-

tests/integration_tests/test_api/test_api_base.py

@@ -219,6 +219,70 @@ def handle_bar(context, _):
     run_func(config=__config__, init=init, handle_bar=handle_bar)
 
 
+def test_instrument_api():
+    from rqalpha.utils.exception import RQInvalidArgument
+
+    config = {
+        "base": {
+            "start_date": "2019-01-02",
+            "end_date": "2019-01-04",
+            "frequency": "1d",
+            "accounts": {
+                "stock": 1000000,
+            }
+        },
+        "extra": {
+            "log_level": "error",
+        },
+    }
+
+    def init(context):
+        context.active_stock = "000001.XSHE"
+        context.inactive_stock = "000979.XSHE"
+
+    def handle_bar(context, _):
+        active_ins = active_instrument(context.active_stock)
+        assert active_ins.order_book_id == context.active_stock
+        assert active_ins.active_at(context.now)
+
+        ins = instruments(context.active_stock)
+        assert isinstance(ins, Instrument)
+        assert ins.order_book_id == context.active_stock
+        listed_date = ins.listed_date.date() if hasattr(ins.listed_date, "date") else ins.listed_date
+        assert listed_date <= context.now.date()
+
+        ins_list = instruments([context.active_stock, context.inactive_stock])
+        assert isinstance(ins_list, list)
+        assert {i.order_book_id for i in ins_list} == {context.active_stock, context.inactive_stock}
+
+        active_history = instrument_history(context.active_stock)
+        assert len(active_history) >= 1
+        assert active_history == sorted(active_history, key=lambda i: i.listed_date)
+
+        inactive_history = instrument_history(context.inactive_stock)
+        assert len(inactive_history) >= 1
+        delisted_date = inactive_history[-1].de_listed_date
+        assert delisted_date is not None
+        delisted_date = delisted_date.date() if hasattr(delisted_date, "date") else delisted_date
+        assert delisted_date < context.now.date()
+
+        active_map = active_instruments([context.active_stock, context.inactive_stock])
+        assert context.active_stock in active_map
+        assert context.inactive_stock not in active_map
+
+        history_list = instruments_history([context.active_stock, context.inactive_stock])
+        assert {i.order_book_id for i in history_list} == {context.active_stock, context.inactive_stock}
+
+        try:
+            active_instrument(context.inactive_stock)
+        except RQInvalidArgument:
+            pass
+        else:
+            raise AssertionError("inactive instrument should raise RQInvalidArgument")
+
+    run_func(config=config, init=init, handle_bar=handle_bar)
+
+
 def test_sector():
     def handle_bar(_, __):
         assert len(sector('金融')) >= 80, "sector('金融') 返回结果少于 80 个"