solidrock-quant 0.2.0__py3-none-any.whl

solidrock/__init__.py

@@ -0,0 +1,53 @@
+"""SolidRockQuant · 磐石智擎 — Agent 原生的量化研究与回测框架.
+
+数据层快速上手::
+
+    from solidrock import DataStore, parse_symbol
+    from solidrock.data.sources import create_source
+
+    src = create_source("akshare")
+    store = DataStore(".solidrock")
+    df = src.fetch_bars(["000001.SZ", "600519.SH"], start="2024-01-01")
+    store.update_bars(df, source="akshare")
+
+回测快速上手::
+
+    from solidrock import BacktestConfig, BacktestEngine, Strategy
+
+    class MyStrategy(Strategy):
+        ...
+
+    result = BacktestEngine(MyStrategy, BacktestConfig(start="2024-01-01", end="2025-12-31"),
+                            DataStore(".solidrock")).run()
+    print(result.metrics["sharpe"])
+"""
+
+from solidrock.agent.errors import ErrorCode, SolidRockError
+from solidrock.backtest import BacktestConfig, BacktestEngine, BacktestResult, Context
+from solidrock.config import Settings, get_settings
+from solidrock.data.store import DataStore
+from solidrock.data.symbols import AssetType, Symbol, parse_symbol
+from solidrock.factors import Factor, FactorData, analyze_factor
+from solidrock.strategy.base import Strategy
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AssetType",
+    "BacktestConfig",
+    "BacktestEngine",
+    "BacktestResult",
+    "Context",
+    "DataStore",
+    "ErrorCode",
+    "Factor",
+    "FactorData",
+    "Settings",
+    "SolidRockError",
+    "Strategy",
+    "Symbol",
+    "__version__",
+    "analyze_factor",
+    "get_settings",
+    "parse_symbol",
+]

solidrock/agent/__init__.py

@@ -0,0 +1,5 @@
+"""Agent 接口层：MCP Server、错误规范、技能文件."""
+
+from solidrock.agent.errors import ErrorCode, SolidRockError, err
+
+__all__ = ["ErrorCode", "SolidRockError", "err"]

solidrock/agent/errors.py

@@ -0,0 +1,95 @@
+"""错误体系：稳定错误码 + 修复建议（hint）规范.
+
+全库统一抛出 :class:`SolidRockError`。每条错误必须携带：
+
+- ``code``：稳定的枚举错误码，Agent 依赖它做分支判断；只能追加，不能改名或删除；
+- ``message``：人读描述；
+- ``hint``：**可执行**的修复建议，Agent 依赖它自纠错，这是"Agent 友好"的硬性要求。
+
+示例::
+
+    raise err(
+        ErrorCode.SYMBOL_NOT_FOUND,
+        f"代码 {raw} 在数据源中不存在",
+        hint="先调用 search_instruments 确认符号；股票代码需带交易所后缀，如 000001.SZ",
+    )
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+
+class ErrorCode(str, Enum):
+    """稳定错误码（对外契约，只追加不修改）。"""
+
+    # --- 请求与符号 ---
+    SYMBOL_INVALID = "SYMBOL_INVALID"  # 符号格式非法
+    SYMBOL_NOT_FOUND = "SYMBOL_NOT_FOUND"  # 格式合法但数据源查无此标的
+    PARAM_INVALID = "PARAM_INVALID"  # 参数非法（日期区间倒置等）
+
+    # --- 数据源 ---
+    SOURCE_NOT_REGISTERED = "SOURCE_NOT_REGISTERED"  # 未注册的数据源名
+    SOURCE_UNAVAILABLE = "SOURCE_UNAVAILABLE"  # 依赖库未安装或网络不可达
+    SOURCE_AUTH_FAILED = "SOURCE_AUTH_FAILED"  # 鉴权失败（token 缺失/无效/积分不足）
+    SOURCE_REQUEST_FAILED = "SOURCE_REQUEST_FAILED"  # 请求失败（限流/超时/接口变动）
+    CAPABILITY_NOT_SUPPORTED = "CAPABILITY_NOT_SUPPORTED"  # 数据源不具备该能力
+
+    # --- 本地数据 ---
+    NO_DATA = "NO_DATA"  # 本地无数据，需要先更新
+    DATA_FORMAT_INVALID = "DATA_FORMAT_INVALID"  # 数据不符合标准 schema
+    SNAPSHOT_NOT_FOUND = "SNAPSHOT_NOT_FOUND"
+    SNAPSHOT_EXISTS = "SNAPSHOT_EXISTS"
+    SNAPSHOT_READ_ONLY = "SNAPSHOT_READ_ONLY"  # 快照是只读副本
+
+    # --- 策略校验（M3+ 回测/Agent 层使用） ---
+    STRATEGY_INVALID = "STRATEGY_INVALID"
+    LOOKAHEAD_SUSPECTED = "LOOKAHEAD_SUSPECTED"
+
+    # --- 其他 ---
+    INTERNAL_ERROR = "INTERNAL_ERROR"  # 未预期的框架错误（应附复现步骤报 issue）
+
+
+class SolidRockError(Exception):
+    """框架内所有受检错误的基类。"""
+
+    def __init__(
+        self,
+        code: ErrorCode,
+        message: str,
+        *,
+        hint: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.hint = hint
+        self.details = details or {}
+
+    def to_dict(self) -> dict[str, Any]:
+        """输出 MCP 信封中的 ``error`` 段（见 docs/design.md §8.2）。"""
+        out: dict[str, Any] = {"code": self.code.value, "message": self.message}
+        if self.hint:
+            out["hint"] = self.hint
+        if self.details:
+            out["details"] = self.details
+        return out
+
+    def __str__(self) -> str:
+        text = f"[{self.code.value}] {self.message}"
+        if self.hint:
+            text += f"\nhint: {self.hint}"
+        return text
+
+
+def err(
+    code: ErrorCode,
+    message: str,
+    *,
+    hint: str | None = None,
+    details: dict[str, Any] | None = None,
+) -> SolidRockError:
+    """便捷构造函数。"""
+    return SolidRockError(code, message, hint=hint, details=details)

solidrock/agent/mcp_server.py

@@ -0,0 +1,224 @@
+"""MCP Server（FastMCP，stdio 传输）.
+
+接入 Claude Desktop / Claude Code 等 LLM 客户端::
+
+    # .mcp.json
+    {"mcpServers": {"solidrock": {"command": "srq", "args": ["mcp", "serve"]}}}
+
+所有工具返回 JSON 字符串（统一信封，见 tools.py）。工具的 docstring 即
+LLM 看到的使用说明，必须自包含、带单位与示例。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from solidrock import __version__
+from solidrock.agent.errors import ErrorCode, err
+
+
+def build_server() -> Any:
+    """构建 MCP Server 实例（兼容 mcp 1.x FastMCP 与 2.x MCPServer）."""
+    try:  # mcp 2.x
+        from mcp.server.mcpserver import MCPServer as _Server
+    except ImportError:
+        try:  # mcp 1.x（fastmcp 已在 2.x 改名，此处兼容旧版）
+            from mcp.server.fastmcp import FastMCP as _Server  # type: ignore[attr-defined, no-redef]
+        except ImportError as exc:
+            raise err(
+                ErrorCode.SOURCE_UNAVAILABLE,
+                "MCP 扩展未安装",
+                hint="pip install 'solidrock-quant[mcp]' 或 pip install mcp",
+            ) from exc
+
+    from solidrock.agent import tools as t
+
+    mcp = _Server(
+        "solidrock",
+        instructions=(
+            "SolidRockQuant：A股/期货量化研究与回测框架。"
+            "典型研究闭环：get_data_overview → fetch_bars(补数据) → 编写策略文件 → "
+            "validate_strategy → run_backtest → compare_experiments 迭代改进。"
+            f"当前版本 {__version__}。"
+        ),
+    )
+
+    @mcp.tool()
+    def get_data_overview() -> str:
+        """查看本地数据总览：已缓存的行情（符号数/行数/日期范围）、交易日历、快照、实验数量。
+
+        开始任何研究前先调用它了解本地有什么数据。返回 JSON 信封。
+        """
+        return t.tool_get_data_overview()
+
+    @mcp.tool()
+    def data_health(symbols: list[str] | None = None, jump_threshold: float = 0.2) -> str:
+        """数据体检：缺失交易日、OHLC 异常、复权因子缺失、单日大幅波动。
+
+        symbols 缺省检查全部本地标的。回测前建议跑一次，避免坏数据污染结论。
+        """
+        return t.tool_data_health(symbols=symbols, jump_threshold=jump_threshold)
+
+    @mcp.tool()
+    def list_data_sources() -> str:
+        """列出可用数据源（akshare/tushare 等）及其能力与可用性。"""
+        return t.tool_list_data_sources()
+
+    @mcp.tool()
+    def search_instruments(query: str, limit: int = 20) -> str:
+        """按代码或名称搜索标的。
+
+        示例：query="510300" 找沪深300ETF；query="贵州茅台" 找 600519.SH。
+        股票符号格式：<6位代码>.<SZ|SH|BJ>，指数/ETF 同理，期货为 <品种><月份>.<交易所>。
+        """
+        return t.tool_search_instruments(query=query, limit=limit)
+
+    @mcp.tool()
+    def fetch_bars(
+        symbols: list[str] | str,
+        start: str | None = None,
+        end: str | None = None,
+        source: str | None = None,
+        freq: str = "1d",
+    ) -> str:
+        """拉取/更新行情到本地（增量幂等）。
+
+        symbols 为统一符号或其列表，如 ["000001.SZ", "510300.SH"]；
+        start/end 格式 YYYY-MM-DD（建议显式给 start）；freq：1d（默认）/
+        1m / 5m（分钟线无复权因子，仅供研究，事件回测用日线）。
+        """
+        return t.tool_fetch_bars(symbols=symbols, start=start, end=end, source=source, freq=freq)
+
+    @mcp.tool()
+    def get_trading_calendar(
+        start: str | None = None,
+        end: str | None = None,
+        update: bool = False,
+    ) -> str:
+        """查询交易日历（update=True 时先从数据源刷新）。"""
+        return t.tool_get_trading_calendar(start=start, end=end, update=update)
+
+    @mcp.tool()
+    def validate_strategy(strategy_file: str) -> str:
+        """策略代码静态检查：语法、前视偏差（shift(-n)/bfill）、Context API 误用。
+
+        回测前必调用（run_backtest 内部也会自动调用）。strategy_file 为策略
+        .py 文件的绝对路径。返回 issues 列表（severity: error/warning）。
+        """
+        return t.tool_validate_strategy(strategy_file=strategy_file)
+
+    @mcp.tool()
+    def run_backtest(
+        strategy_file: str,
+        start: str,
+        end: str,
+        params: dict[str, Any] | None = None,
+        benchmark: str | None = "000300.SH",
+        execution: str = "next_open",
+        initial_cash: float = 1_000_000.0,
+        name: str | None = None,
+    ) -> str:
+        """运行回测（自动静态校验 + 结果自动留痕）。
+
+        strategy_file：策略文件绝对路径（内含一个 Strategy 子类）；
+        params：策略参数覆盖，如 {"fast": 10}；
+        execution：next_open（默认，防前视）| same_close（仅快速研究）；
+        benchmark 传 null 关闭基准对比。返回核心指标 + 产物目录
+        （report.md/result.json/trades.csv/nav.csv）。
+        """
+        return t.tool_run_backtest(
+            strategy_file=strategy_file,
+            start=start,
+            end=end,
+            params=params,
+            benchmark=benchmark,
+            execution=execution,
+            initial_cash=initial_cash,
+            name=name,
+        )
+
+    @mcp.tool()
+    def list_experiments(kind: str | None = None, limit: int = 20) -> str:
+        """列出最近的实验（kind: backtest/factor，默认全部）。"""
+        return t.tool_list_experiments(kind=kind, limit=limit)
+
+    @mcp.tool()
+    def get_experiment(run_id: str) -> str:
+        """查看单个实验的完整配置、指标与产物路径。"""
+        return t.tool_get_experiment(run_id=run_id)
+
+    @mcp.tool()
+    def compare_experiments(run_ids: list[str]) -> str:
+        """并排对比多个实验的核心指标（至少 2 个 run_id，来自 list_experiments）。"""
+        return t.tool_compare_experiments(run_ids=run_ids)
+
+    @mcp.tool()
+    def run_factor_analysis(
+        factor_file: str,
+        universe: list[str],
+        start: str,
+        end: str,
+        params: dict[str, Any] | None = None,
+        quantiles: int = 5,
+        fwd_period: int = 1,
+        name: str | None = None,
+    ) -> str:
+        """运行因子分析：RankIC + 分层回测（自动留痕）。
+
+        factor_file：因子文件绝对路径（内含一个 Factor 子类，compute 返回
+        index=date/columns=symbol 的宽表）；universe 为股票池符号列表（建议
+        50 只以上，截面太少 IC 不可信）；quantiles 分层数；fwd_period 前瞻
+        收益期。解读：|IC均值|>0.03 且 ICIR>0.5 才值得继续；层间单调性比
+        多空收益更重要。
+        """
+        return t.tool_run_factor_analysis(
+            factor_file=factor_file,
+            universe=universe,
+            start=start,
+            end=end,
+            params=params,
+            quantiles=quantiles,
+            fwd_period=fwd_period,
+            name=name,
+        )
+
+    @mcp.tool()
+    def run_vectorized_backtest(
+        factor_file: str,
+        universe: list[str],
+        start: str,
+        end: str,
+        params: dict[str, Any] | None = None,
+        top: float = 0.2,
+        bottom: float = 0.2,
+        fee_rate: float = 1.5e-4,
+        name: str | None = None,
+    ) -> str:
+        """向量化因子筛选：做多头部分位、做空尾部分位的组合净值（秒级）。
+
+        适合批量扫参数的快速迭代；逐日再平衡、收盘成交、单一费率，
+        结论仅用于相对比较，最终结论用 run_backtest 事件引擎复核。
+        """
+        return t.tool_run_vectorized_backtest(
+            factor_file=factor_file,
+            universe=universe,
+            start=start,
+            end=end,
+            params=params,
+            top=top,
+            bottom=bottom,
+            fee_rate=fee_rate,
+            name=name,
+        )
+
+    return mcp
+
+
+def main() -> None:
+    """stdio 入口（srq mcp serve）。"""
+    server = build_server()
+    server.run()  # stdio
+
+
+if __name__ == "__main__":
+    main()

solidrock/agent/skills/backtest-workflow.md

@@ -0,0 +1,75 @@
+# SKILL: 回测研究流程
+
+目标：让 Agent 独立完成"检查数据 → 写策略 → 校验 → 回测 → 读结果 → 迭代"的完整闭环。
+
+## 0. 前置认知
+
+- 所有 MCP 工具返回 **JSON 信封**：`status`("ok"/"error") + `data` + `artifacts`(文件路径) + `error.{code,message,hint}`。
+- 出错时先读 `error.hint` 并按它行动，不要盲目重试相同参数。
+- 符号格式：`000001.SZ` / `600519.SH` / `000300.SH`(指数) / `510300.SH`(ETF) / `RB2505.SHFE`(期货) / `RB.SHFE`(主连)。
+- 引擎默认 `next_open` 执行（收盘信号次日开盘成交，防前视）；不要为了"更好的回测收益"改用 `same_close`。
+
+## 1. 检查本地数据
+
+调用 `get_data_overview`，确认：
+1. 回测区间内的交易日历已覆盖（否则 `get_trading_calendar` 传 `update=true`）；
+2. 目标标的日线已缓存且区间覆盖"回测起点往前 250 个交易日"（策略 warmup）；
+   缺数据 → `fetch_bars(symbols=[...], start=<回测起点-365天>, end=今天)`。
+
+## 2. 编写策略文件
+
+在项目工作区写一个 `.py` 文件（内含**一个** Strategy 子类）：
+
+```python
+from solidrock import Context, Strategy
+
+
+class MyStrategy(Strategy):
+    params = {"symbol": "510300.SH", "fast": 5, "slow": 20}
+
+    def setup(self, ctx: Context) -> None:
+        ctx.universe = [str(self.params["symbol"])]  # 必须设置
+
+    def on_signal(self, ctx: Context) -> None:  # 每个交易日收盘后调用
+        symbol = str(self.params["symbol"])
+        close = ctx.history(symbol, int(self.params["slow"]) + 1, fields="close")[symbol]
+        window = close.iloc[-int(self.params["slow"]) :]
+        if window.isna().any() or len(window) < int(self.params["slow"]):
+            return  # 数据不足（warmup 期/停牌）直接跳过
+        target = 1.0 if window.iloc[-int(self.params["fast"]) :].mean() > window.mean() else 0.0
+        ctx.order_target_percent(symbol, target)
+```
+
+可用 API（只有这些，幻觉调用会被静态检查拦截）：
+- 下单：`ctx.order(sym, qty)`、`ctx.order_value(sym, value)`、`ctx.order_target_percent(sym, pct)`、`ctx.order_target_value(sym, value)`、`ctx.cancel_all()`
+- 数据：`ctx.history(symbols, n, fields="close")`（宽表 DataFrame，含当日 bar）、`ctx.position(sym)`
+- 查询：`ctx.portfolio`（cash/positions/total_value）、`ctx.now`、`ctx.params`
+- 其他：`ctx.log(msg)`
+
+硬性规则：
+- **只能用截至当前 bar 的数据**（`shift(-n)`、`bfill` 会被拦截）；
+- 参数全部通过 `self.params` 声明与读取，方便对比实验；
+- 仓位目标用 `order_target_percent`，不要手写股数对齐逻辑（引擎处理整手/T+1/资金约束）。
+
+## 3. 校验并回测
+
+1. `validate_strategy(strategy_file=<绝对路径>)` — 有 error 必须先修；
+2. `run_backtest(strategy_file=<绝对路径>, start="YYYY-MM-DD", end="YYYY-MM-DD", params={...}, name="<可辨识的实验名>")`；
+3. 读返回的 `metrics`（核心：annual_return / sharpe / max_drawdown / trade_win_rate / annual_turnover / excess_annual_return）与 `rejection_counts`。
+
+## 4. 迭代
+
+- `list_experiments` → `compare_experiments(run_ids=[...])` 横向对比；
+- 每次改动只动一个变量（一个参数或一处逻辑），实验名带上改动点（如 "双均线-fast10"）；
+- 警惕过拟合：参数扫描得到的"最优"参数要换区间/换标的验证；
+- 交易胜率低但盈亏比高是趋势策略常态，单看胜率会误判。
+
+## 5. 常见错误码
+
+| code | 含义 | 处置 |
+|------|------|------|
+| NO_DATA | 本地无数据/区间无交易日 | fetch_bars 补数据或修正区间 |
+| SYMBOL_INVALID | 符号格式错 | 用 search_instruments 确认 |
+| LOOKAHEAD_SUSPECTED | 疑似前视 | 按行号修复，不要绕过 |
+| STRATEGY_INVALID | 语法/API 误用 | 按 issues 修复 |
+| WEIGHT_CAP | 触发仓位上限 | 正常风控行为；若目标仓位>上限属策略设计问题 |

solidrock/agent/skills/data-update-workflow.md

@@ -0,0 +1,46 @@
+# SKILL: 数据更新流程
+
+目标：让 Agent 正确地把行情数据落到本地并保证可复现。
+
+## 决策树
+
+1. `get_data_overview` 看现有数据；
+2. 需要新数据 → `fetch_bars`；
+3. 做实验前 → 创建数据快照（`srq data snapshot create <tag>`，或提醒用户执行）。
+
+## fetch_bars 用法
+
+```
+fetch_bars(symbols=["000001.SZ", "510300.SH"], start="2023-01-01", end="2026-09-08")
+```
+
+- **增量幂等**：重复调用只补缺口，不产生重复行；
+- **start 建议显式给**：不传时走增量续拉（本地无数据则从 1990 年全量拉，慢）；
+- **回测 prep**：回测起点往前留 ≥250 个交易日（warmup），即 start ≈ 回测起点 - 15 个月；
+- 返回摘要含每个符号在本地库中的总行数与覆盖区间；
+- 复权因子自动获取（东财主通道失败自动切新浪）。
+
+## 交易日历
+
+```
+get_trading_calendar(update=true)   # 首次使用/年末更新
+```
+回测引擎依赖日历切分交易日；日历缺失时报 NO_DATA 并提示更新。
+
+## 数据快照（可复现的关键）
+
+数据每天都会变（新 bar、复权因子修正）。严肃实验前创建快照：
+
+```
+srq data snapshot create snap-20260908     # CLI 命令，近零拷贝
+```
+
+- 快照只读；回测结果会记录所用快照名，复现实验 = 指定同一快照；
+- 不要往快照里写数据（会被拒绝）。
+
+## 数据口径备忘
+
+- 价格：**原始价 + 复权因子**（不做前复权落库），hfq = close × adj_factor；
+- volume 单位：手（股票与期货均如此）；amount 单位：元；
+- pre_close 为除权后口径（与交易所一致）；
+- 指数/期货 adj_factor 恒为 1；新浪回退通道的 ETF 因子为 NaN。

solidrock/agent/skills/experiment-comparison-workflow.md

@@ -0,0 +1,46 @@
+# SKILL: 实验对比与策略迭代
+
+目标：让 Agent 用实验追踪做有依据的策略改进，而不是凭印象改参数。
+
+## 核心循环
+
+```
+list_experiments(limit=20)
+  → 挑出同策略不同参数（或不同策略同区间）的 run_id
+    → compare_experiments(run_ids=[...])
+      → 读差异 → 形成假设 → 只改一个变量 → run_backtest → 回到开头
+```
+
+## 怎么读对比表
+
+指标列含义与陷阱：
+
+| 指标 | 含义 | 陷阱 |
+|------|------|------|
+| annual_return | 年化收益（几何） | 短区间年化会被放大 |
+| sharpe | 年化收益/年化波动 | 收益平稳的策略才可信；<0.5 基本不可用 |
+| max_drawdown | 最大回撤 | 必须结合年化看（卡玛 = 年化/\|回撤\|） |
+| trade_win_rate | 平仓交易胜率 | 趋势策略 30-40% 是常态，别拿它否决策略 |
+| profit_factor | 总盈利/总亏损 | >1.3 才有继续优化的价值 |
+| annual_turnover | 年化换手 | 高换手 + 低超额 = 费用吃掉收益 |
+| excess_annual_return | 相对基准年化 | 评估策略的最终标准 |
+
+## 实验纪律
+
+1. **单变量原则**：两次实验只差一个参数/一处逻辑，否则对比无意义；
+2. **实验命名带信息**：`双均线-fast10` 优于 `test2`；
+3. **控制数据版本**：对比的实验应基于同一数据快照（get_experiment 看 data_snapshot）；
+4. **防过拟合**：
+   - 同一组参数换 2-3 个不重叠区间验证；
+   - 换 1-2 个同类标的验证；
+   - 参数敏感性：最优参数附近的邻居参数表现不应断崖式变差；
+5. **费用意识**：A股双边成本约 0.15%（佣金+印花税+过户+滑点），策略年换手 1000% 意味着每年先亏 1.5%。
+
+## 产物引用
+
+每次实验的完整数据在 `get_experiment(run_id).artifacts_dir` 下：
+- `result.json`：完整指标、逐日净值、全部成交与拒单（机器读）；
+- `report.md`：人读报告；
+- `trades.csv` / `nav.csv`：明细。
+
+需要逐笔分析时直接读这些文件，不要试图让工具返回大表。