.. _extensions:

HTML 扩展功能
==================================================

QPro Skills 可以帮助本地 AI Agent 把行情、账户和交易数据需求制作成一个可直接运行的 ``.html`` 网页。将网页放入 QPro 的扩展目录后，既可以从 ``系统`` 菜单快速打开，也可以把它作为“扩展板块”嵌入交易页面，与报价表、行情图、下单板等板块自由组合。

.. figure:: ../images/ai_editor/extensions-overview.png
   :alt: 从 QPro Skills 生成 HTML 并嵌入 QPro 扩展板块的四步流程
   :align: center
   :width: 100%

   一个扩展的完整流程：AI 生成单 HTML 文件、放入扩展目录、选择网页模板、嵌入 QPro 页面。

扩展如何工作
--------------------------------------------------

扩展页面本身负责展示和交互，数据仍来自 QPro 的本地 API。QPro Skills 已整理好服务地址、接口、字段含义和订阅方式，Agent 可以据此生成适合嵌入的页面。

.. list-table:: 两种打开方式
   :header-rows: 1
   :widths: 24 34 42

   * - 打开方式
     - 操作入口
     - 适用场景
   * - 快速打开
     - ``系统`` -> ``打开扩展`` -> 选择 HTML 文件
     - 使用系统默认浏览器打开，适合快速预览和单独查看
   * - 嵌入 QPro
     - 添加“扩展板块”，再在板块配置中选择 HTML 模板
     - 页面直接显示在 QPro 布局中，可与其他板块一起移动、缩放和保存

使用前准备
--------------------------------------------------

#. 按 :ref:`qpro-api-ai-agent` 复制并安装 QPro Skills。
#. 按 :ref:`qpro_httpserver` 启用 ``本地 Api 接口``，重启并重新登录 QPro。扩展页面需要从当前登录的 QPro 读取本地数据。
#. 在 Codex 等支持 Skills 的本地 AI 工具中描述页面目标，并明确要求交付一个适合 QPro 扩展板块的单 HTML 文件。

例如，可以直接向 Agent 提出以下需求：

.. code-block:: text

    请使用 QPro Skills，制作一个可以放进 QPro 的横向盘口力量看板，
    并生成一个 HTML 文件。

.. figure:: ../images/ai_editor/extensions01.png
   :alt: 在 Codex 中使用 QPro Skills 生成单 HTML 扩展页面
   :align: center
   :width: 86%

   Agent 按 QPro Skills 调用本地数据服务，并把页面交付为一个 ``.html`` 文件。

推荐使用单文件 HTML，把 CSS 和 JavaScript 内嵌在页面中，便于复制、更新和分享。如果页面确实需要图片等本地资源，应保留原有相对目录结构，并将这些资源一同复制到扩展目录。

将 HTML 加入扩展目录
--------------------------------------------------

#. 在 QPro 菜单栏选择 ``系统`` -> ``打开扩展`` -> ``管理扩展目录``。
#. 将 Agent 生成的 ``.html`` 文件复制到打开的目录根层级。QPro 会识别该层级中的 HTML 文件；请确认文件扩展名确实为 ``.html``，而不是被 Windows 隐藏扩展名后的 ``.html.txt``。
#. 再次打开 ``系统`` -> ``打开扩展``，即可在菜单中看到文件名。点击文件名会使用系统默认浏览器快速打开页面。

.. figure:: ../images/ai_editor/extensions-menu.png
   :alt: QPro 系统菜单中的打开扩展入口、扩展目录和 HTML 文件列表
   :align: center
   :width: 70%

   ``打开扩展`` 会列出扩展目录中的 HTML 文件；``管理扩展目录`` 用于打开文件所在位置。

新增或替换 HTML 文件后，无需重启 QPro；重新打开 ``打开扩展`` 菜单或板块配置即可刷新文件列表。

嵌入 QPro 页面
--------------------------------------------------

#. 在任意板块内右键，选择 ``板块管理`` -> ``添加板块`` -> ``扩展板块``。

   .. figure:: ../images/ai_editor/extensions-add-pane.png
      :alt: 在 QPro 板块管理菜单中添加扩展板块
      :align: center
      :width: 72%

      从现有页面中添加一个用于承载 HTML 的“扩展板块”。

#. 在新添加的扩展板块内右键并选择 ``配置``。展开 ``网页模板`` 下的 ``打开模板``，选择已经放入扩展目录的 HTML 文件，然后点击 ``确定``。

   .. figure:: ../images/ai_editor/extensions-select-template.png
      :alt: 在扩展板块配置中选择 HTML 网页模板
      :align: center
      :width: 84%

      配置列表会显示扩展目录根层级中的 HTML 文件。

#. 页面加载后，可以像其他板块一样调整位置和大小，也可以放到其他页面或独立窗口中。有关布局操作，参见 :ref:`layout`。

   .. figure:: ../images/ai_editor/extensions-embedded-dashboard.png
      :alt: 横向盘口力量 HTML 看板嵌入 QPro 交易页面
      :align: center
      :width: 76%

      示例：AI 生成的“横向盘口力量”页面嵌入下单板下方，并随板块宽度自适应显示。

更新、切换与排查
--------------------------------------------------

* **更新页面**：用新版本覆盖同名 HTML 文件后，在扩展板块内右键选择 ``重新加载``。
* **切换页面**：在扩展板块内右键选择 ``配置``，从 ``打开模板`` 下拉列表中选择另一个 HTML。
* **列表中没有文件**：确认 HTML 位于 ``管理扩展目录`` 打开的目录根层级，且文件名以 ``.html`` 结尾，然后重新打开菜单或配置窗口。
* **页面无数据**：确认已经启用 ``本地 Api 接口``、重启并登录 QPro；如果修改过本地 API 端口，应让 Agent 按当前配置重新检查页面。
* **页面尺寸不合适**：让 Agent 使用响应式布局，避免固定宽度和固定高度，再重新加载页面。

.. note::

   QPro 本地 API 和官方 Skills 提供的是只读数据访问能力，不提供下单、撤单或改单能力。扩展能够执行 HTML 中包含的前端代码，因此只应加载来源可信、用途明确的文件；账户、持仓、委托和成交数据也不应暴露到不可信网络。