.. _qpro_httpserver: ======================================== QPro HTTP server 与 AI Agent 使用说明 ======================================== 概述 ===== QPro HTTP server 用于把 QPro 内部的账户、持仓、委托、成交快照以只读 HTTP 查询方式提供给本机或受信任网络中的程序。它适合解决越来越多的个性化监控需求：用户不需要重新写一套交易程序，也不需要让外部程序接管交易信号，只要读取 QPro 已经汇总好的多账户实时数据，就可以让本地 Agent 或脚本完成更自由的数据探索和风控监控。 用户可以按自己的问题查询 ``AccountSnap``、``PositionSnap``、``OrderSnap``、``TradeSnap`` 四张快照表。 典型价值 ========= 传统交易软件很难覆盖所有个性化监控诉求。启用 HTTP server 后，可以让 AI Agent 或本地脚本基于 QPro 的实时数据做下面这些事情： * 按用户自己的品种分组、策略分组或业务分组做板块级盈亏统计。 * 按用户自己的风控规则组合账户、持仓、委托和成交数据，生成更个性化的提醒。 * 把 QPro 实时数据接入自建网页、看板或大屏，做可视化程度更高的展现方案。 启用本地 API 接口 ================= 使用 HTTP server 前，需要先在 QPro 中手工启用本地 API 接口。进入 ``系统`` -> ``选项`` -> ``选项设置``。 .. figure:: ../images/ai_editor/qpro-options-settings-menu.png :alt: QPro 系统菜单中的选项设置入口 :align: center :width: 420px 从 QPro 的 ``系统`` 菜单进入 ``选项设置``。 在 ``账户持仓监控`` 中，把 ``启用本地 Api 接口`` 设置为 ``是``。默认 ``Api 服务端口`` 为 ``8811``，本机 Agent 或脚本通常通过 ``http://127.0.0.1:8811`` 访问。 .. figure:: ../images/ai_editor/qpro-enable-local-api.png :alt: 在账户持仓监控中启用本地 Api 接口 :align: center :width: 92% 在 ``账户持仓监控`` 中启用本地 API 接口。 推荐使用 QPro skill =================== 更推荐用户把 QPro 提供的 skill 复制给自己的本地 Agent。这样 Agent 不只知道 HTTP server 地址，还能知道表结构、字段含义、查询限制和常见监控 SQL，写出来的查询会更贴近 QPro 的真实数据模型。 使用方式：从 QPro 中复制 Skills ------------------------------- 在 QPro 顶部菜单中点击 ``帮助`` -> ``复制 skills``，把复制出来的内容粘贴给自己的本地 Agent。 .. figure:: ../images/ai_editor/qpro-copy-skills-menu.png :alt: QPro 帮助菜单中的复制 skills 入口 :align: center :width: 260px QPro 帮助菜单中的 ``复制 skills`` 入口。 示例一：自定义板块级别的盈亏统计 ================================ 用户可以让 Agent 按自己的业务口径定义板块，而不是只能按交易所、品种或固定页面分组。例如把多个品种归为“黑色”“有色”“贵金属”，再统计持仓盈亏、浮动盈亏、平仓盈亏和手续费。 .. figure:: ../images/ai_editor/httpserver-sector-pnl.png :alt: 自定义板块级别的盈亏统计示意图 :align: center :width: 92% 自定义板块盈亏看板示意：把多个品种按用户自己的规则归到板块，并展示盈亏、手续费和保证金。 这类统计适合“我自己的板块定义”“我自己的策略桶”“某批账户合并看收益”这类需求。用户只需要说明板块口径，Agent 可以根据 QPro skill 中的表结构和查询规则生成对应查询，再按用户定义重新汇总。 示例二：更具个性化的风控通知 ============================ 用户可以让 Agent 根据自己的规则组合多个表和多个条件，再触发本地弹窗、企业微信、飞书、短信或其他通知。例如：某些账户可用资金低于阈值、某些板块保证金过高、某些合约出现未完成委托时才提醒。 .. figure:: ../images/ai_editor/httpserver-risk-alert.png :alt: 更具个性化的风控通知示意图 :align: center :width: 92% 个性化风控通知示意：把账户、持仓、委托和成交状态组合成用户自己的提醒规则。 这类规则可以非常贴近用户自己的交易习惯：不同账户不同阈值、不同品种不同阈值、只在交易时段提醒、同一个异常在一定时间内只提醒一次。HTTP server 只提供只读数据，实际查询和通知逻辑由 Agent 或本地脚本完成。 示例三：可视化程度更高的展现方案 ================================ 用户可以把 HTTP server 作为实时数据源，接入自己熟悉的展示方式，例如 Streamlit、ECharts、Grafana、Jupyter Notebook 或内部网页。Agent 可以定时读取数据，并把结果整理成更适合观察的视图，例如账户-板块热力图、保证金占用排行、盈亏瀑布图、持仓变化时间线。 .. figure:: ../images/ai_editor/httpserver-visual-dashboard.png :alt: 可视化程度更高的展现方案示意图 :align: center :width: 92% 可视化展现示意：把 QPro 实时快照接入自建看板，按用户自己的观察方式展示账户、板块、风险和持仓变化。 这类方案可以把 QPro 的实时快照变成用户自己的看板。需要历史曲线时，可以让 Agent 或外部程序定时轮询 HTTP server，并把每次查询结果存到自己的时序库或 CSV 中，再按自己的方式渲染。 安全说明 ========= HTTP server 第一阶段没有应用层鉴权。推荐只在本机通过 ``127.0.0.1`` 使用。如果需要让局域网内其他机器访问，应自行确认网络边界、防火墙和访问控制，避免把账户、持仓、委托、成交数据暴露给不可信环境。 表和字段 ========= 四张表和字段含义见 :ref:`qpro_httpserver_schema`。实际字段也可以随时通过 ``GET /tables`` 获取。