tj-quant

数据处理流程系统在后台做什么、何时自动跑

tj-quant 是日线级、盘后的研究系统：只产出信号与分析报告，不做实盘下单。数据来自 Tushare Pro，落盘后由本系统的因子、策略、回测环节消费。

数据从哪来

• 数据源：Tushare Pro——token 在「系统设置 → 数据源」配置
• 运行窗口：日线收盘后批量处理（盘中数据不完整，见下方说明）
• 数据集：见下表；每个数据集的行数与日期范围在「数据管理」页可见

一次完整流程的四步

1. 拉数：按数据集增量拉取并校验，落盘为数据文件
2. 因子计算：对已注册因子（如动量）在全样本上计算并落盘
3. 信号生成：策略在样本池上出信号（T 日收盘出、T+1 开盘成交）
4. 回测与报告：按 A 股撮合规则回测，产出权益曲线 / 交易明细 / 持仓 / 指标报告，归档保留 60 份

什么时候会跑

• 自动：调度器每个工作日 17:03（Asia/Shanghai）自动跑完整流程，滑动窗口拉当日最新数据——日常数据保持最新主要靠它
• 手动：在「任务中心」随时发起任意环节的任务（如部署后的历史回补、财务等非每日数据）

任务队列规则

• 同一时刻只执行一个（single-flight），其余排队等待；排队中可在「任务中心」取消
• 失败任务有日志 + 「告警中心」记录；配置了通知 webhook 时会额外推送
• 任务失败不影响已成功落盘的数据

数据与回测规则页面看不到的口径约定

账户与价格口径

• 全后复权（hfq）账户：成交 / 市值 / 权益均按后复权价计算，除权日权益连续
• 一字板用真实价判断（不复权），避免复权因子扭曲涨跌停判断
• T+1 语义：T 日收盘信号 → T+1 开盘成交；全链路无未来函数

撮合约束

• 一字涨停买不进、一字跌停卖不出
• 停牌日不可交易
• 下单按 100 股整数倍

费用构成

• 佣金：万 2.5，单笔最低 5 元
• 印花税：卖出 0.05%
• 过户费：0.001%，买卖双向
• 滑点：可选，按「系统设置 → 回测参数」配置

数据区间与异常

• 行情历史自 2020-01-02 起（部署时一次性回补），此后由调度按交易日增量补齐
• 每次拉数校验 OHLC 等基本约束：少量异常行自动修复并记告警，异常 ≥100 行才终止该次刷新——偶发脏行不会让整批失败

样本池

• 单策略回测默认：市值 Top50 池
• 可切换：自定义分组 / 全市场（分批流式，资源占用可控）

怎么判断「数据 / 因子可信」

1. 数据新旧：「数据管理」看各数据集最新日期与行数；不确定就跑一次 validate（校验日历完整性 / 停牌一致性）
2. 因子有效性：「因子 → 评估」看 IC（未来 10/20 日收益截面相关性）的方向、显著性（t 值）与正占比
3. 落地验证：看信号失效跟踪（信号后 5/10/20 日实际持有收益与胜率）——与 IC 自洽才可信

如何构建策略注册即接入，不用改框架代码

策略 = 一个函数 fn(bar, p) → 信号流。写好并注册后，Web / MCP / CLI 全部立即可用，不需要改 pipeline、API 或任何界面代码。

输入与输出

• 输入 bar：行情数据框（OHLCV / 复权因子 / 涨跌停价 / 停牌标记等）
• 输入 p：参数字典——注册表默认值 + 运行时覆盖合并；每个参数带中文说明，Web / MCP 据此提示
• 输出：信号数据框，字段如下（顺序不限）

接入三步

1. 写函数：def my_strategy(bar, p)，内部实现你的逻辑并返回信号流
2. 注册：register("名称", "说明", {默认参数}, 函数, {参数说明})
3. 生效：立即出现在「策略」页，Web / MCP / CLI 直接可跑，无需重启

内置 ma_cross（双均线）、mom_break（动量突破）两个示例在 tj_quant/strategies.py，可直接照着抄：

from tj_quant.strategy import register   # MCP / 页面提交时 register 已预注入，禁止 import

def my_strategy(bar, p):
    # bar：全市场行情（含复权因子/涨跌停/停牌标记）；p：默认参数与运行时覆盖合并
    # ... 在此实现你的逻辑，返回信号数据框（字段见上表）...
    return signals

register("my_strategy", "一句话说明", {"window": 20}, my_strategy, {"window": "均线窗口"})

提交途径

• Web：「策略」页新建 / 编辑源码保存；或「AI 生成策略」按描述生成
• MCP：save_strategy 提交（落库并立即注册、重启保留）；evaluate_strategy_code 先试跑看指标
• 服务端文件：编辑 tj_quant/strategies.py 注册后生效

约束与产出

• 安全校验：提交时做静态安全校验（AST 白名单），禁止 import 与危险调用；可用能力为预注入的数据处理与数学函数——未通过校验的代码不会生效
• 运行与结果：提交生成后台任务（排队执行）；跑完信号见「信号」页、报告见「回测报告」页

报告指标解读口径与实现：tj_quant/report.py

指标口径固定（报告头可复核），含义与用途如下：

看报告的正确姿势

• 先核对报告头：数据区间 / 样本池 / 策略参数与预期一致，再谈结果
• 收益之外必看回撤与夏普：高收益 + 大回撤说明路径风险高，不可持续的概率大
• 用信号验证交叉确认：第二节的信号跟踪与 IC 能支撑的信号才可信
• 交易次数过少（如 20 笔以内）时统计意义有限

MCP 集成让 AI 客户端远程调用系统能力

MCP（Model Context Protocol）让 AI 客户端以「工具」形式远程调用 tj-quant：跑流程、查任务、管理策略、取报告，全程不打开网页。

工作原理

• 协议：MCP over HTTP（streamable-http），与 Web API 同进程、同认证体系
• 端点：<服务地址>/tj/mcp——本部署为 https://wjbd.site/tj/mcp
• 认证：请求头 Authorization: Bearer <token>

配置 token

1. 打开「系统设置 → MCP 集成」
2. 填写（或生成）MCP token 并保存；可用「测试连接」验证端点与认证
3. 把端点与 token 配到你的 AI 客户端（示例见下）

客户端接入示例

{
  "mcpServers": {
    "tj-quant": {
      "type": "http",
      "url": "https://wjbd.site/tj/mcp",
      "headers": { "Authorization": "Bearer <系统设置里配置的 token>" }
    }
  }
}

认证细节

• 优先使用「系统设置」里配置的 MCP token
• 未配置 mcp_token 时回退主密码（TJ_PASSWORD）
• 两者都未配置：端点不开放（返回 401）

主要工具

AI 客户端可自动发现完整工具清单；本地开发另可用 stdio 模式：uv run python -m tj_quant.mcp_server。