Alpha v1.0.3

InstructionX_UIKit alpha-v1.0.3

新增功能

1. 代码编辑器 InstructionX_UIKit.code_editor（新子包）

纯 PySide6 实现（无 WebView / JavaScript），对齐 VS Code 编辑区体验。

模块	内容
editor.py	CodeEditor 主控件：Gutter + 文本区 + MiniMap + 浮层组合；Ctrl+D 多选批量编辑（替代 Alt+Click 多光标）
highlight.py	HighlightEngine(QSyntaxHighlighter) + 亮/暗语法色板 + 语言注册表
languages.py	内置 python / cpp / js / ts / json / html / css / markdown / qss / plain，导入即注册
regions.py	区域高亮优先级：诊断 > 搜索当前命中 > 搜索命中 > 选中词 > 括号匹配 > 自定义层 > 语法
gutter.py / minimap.py	行号 + 断点 + 折叠标记；小地图（视口指示 + 点击跳转）
panels.py	查找替换栏 / 补全弹窗 / 悬停气泡（provider 驱动）
diff_editor.py	DiffEditor：并排 / 内联 / auto 断点三种模式、滚动同步、变更刻度条

• 能力：语法高亮、查找替换（正则 / 大小写 / 整词）、诊断标记、断点、基于缩进的折叠、补全与悬停 provider、自定义快捷键与绘制钩子、亮暗主题实时切换。
• 演示页：demo/pages/code_editor.py（编辑器演示 + Diff 对比两个子页）。

2. 图表引擎：OpenGL 渲染

• 图表绘制改由私有 GL 视口（QOpenGLWidget）承载，公共 API 零改动——set_option / update_option 的调用方式与渲染效果与历史一致。
• GL 不可用时自动回退软件光栅视口（offscreen / minimal 测试环境、无 GL 驱动、UIKIT_CHART_GL=off）。
• 分层渲染：静态前缀（底色 / 坐标轴 / 网格 / 刻度文字 / 图例 / 标题）与系列层分别位图缓存；纯数据更新时静态层命中缓存。

3. 图表引擎：大规模数据管线

• 紧凑存储与零拷贝摄入：大数值数组按引用持有为缓冲区，set_option 不再逐元素深拷贝（150 万点由约 2.1 s 降至毫秒级）。
• 运行时降采样与保真承诺：阈值 = 绘图区像素宽 × 系数，逐桶保留极值；逐像素列 y 极值与全量直绘严格一致，尖峰毛刺不丢。可见点数不超过阈值时不做任何降采样。
• 轴范围计算向量化并按数据身份缓存（缩放提速约 35 倍）；采样点映射矢量化并带首用自检护栏（抽样比对逐点结果，分歧即永久禁用快路径）。
• 散点 large 像素桶聚合（图元压缩 2451 倍）。

4. 图表引擎：实时数据接入

sess = chart.stream(series="信号", window=20000, interval=1/90)
sess.write(value)          # 采集线程内高频调用，任意线程安全
sess.close()
print(sess.stats)          # {batches, points, frames, merged, dropped, buffered}

• RingBuffer：单写单读无锁环形缓冲，先写数据、最后更新长度；写满丢最旧且 dropped 可观测。
• FrameCoalescer：投递频率高于刷新节奏时成批合并、不丢点。
• StreamSession：GUI 定时器按节奏取数入图；ChartWidget.set_stream_data() 为流式专用入口（只换数据、不重建 option / 渲染器）。

5. 图表引擎：GPU 原生直绘（可选，默认关闭）

{"type": "line", "name": "信号", "data": ys, "gpuDirect": True}

顶点经 VBO 上传、坐标变换在 GLSL 内完成（矩阵在 numpy 里一次算好再构造 QMatrix4x4）。GL 视口会「认领」可直绘的系列并由 GPU 接管绘制，QPainter 不再重复绘制同一条曲线。

6. Demo 新增

• 巨量数据综合演示（图表页底部）：默认 150 万点（可拉到 500 万），后台线程生成数据；读数给出数据点数 / 实际渲染点数 / set_option 耗时 / QPainter 单帧 / GPU 直绘单帧 / 90 fps 预算判定；含「滚动窗口」档位（500 ~ 100,000 点）。
• 实时滚动流：独立线程按约 1000 点/秒产数写入环形缓冲，图表只保留最近 N 点、写满丢最旧；读数给出实测入图频率（会话记录的滑动平均）、采样吞吐、单帧绘制耗时。
• 导航新增「代码编辑器」大类，共 11 大类 / 78 个演示页。

---

性能改进（均为实机实测）

场景	改进前	改进后
150 万点折线单帧布局	—	提速约 525 倍（运行时降采样接入后）
百万点 set_option 摄入	约 2.1 s（深拷贝）	毫秒级（零拷贝）
轴范围计算（缩放）	—	提速约 35 倍
实时滚动流（20,000 点窗口）	约 20 Hz	单帧绘制 3.3 ms → 90 fps 预算内（预算 11.11 ms）
实时滚动流（500 点窗口）	—	端到端 120 Hz、单帧绘制 1.3 ms
同屏 16 图稳态	—	1.0 ms / 图（缓存命中）

关键优化点：

• 静态层缓存键由 option 版本号 改为轴的解析结果，纯数据更新时命中缓存（8.15 ms/帧 → 0）。
• GL 视口下 GPU 接管的系列不再被 QPainter 重画（同一条曲线原本光栅化两遍，约 24 ms/帧）。
• 流式入图走专用通路，省掉每帧 _rebuild（6.83 ms）与多余重排。

---

修复

图表引擎

• 采样阈值改为不可关闭的「屏幕像素下限」：series["sampling"] = None 曾被实现为「不做任何降采样」，实测 150 万点在约 1000 px 绘图区下 layout 2.8 秒、单帧绘制 8.8 秒，事件循环完全不响应，Windows 判定 AppHang 并杀进程。现在该取值只表示「不做额外降采样」，阈值仍取绘图区像素宽 × 系数。
• GL_MAX_POINTS 真正生效：常量注释写明「超过则拒绝直绘」，但执行点漏写，导致 150 万点照旧上传 VBO；现按实测标定为 400 万顶点（150 万 / 300 万顶点实测稳定）。
• 空类目 category 轴的坐标映射：{"type":"category","data":[]}（流式入图标准写法）曾让屏幕 x 飞到 200 万（绘图区右边界才 872），整幅只剩一条压在边缘的平线。
• update_option 接收 numpy 数组：原先会被当作「数据缺失」丢弃，导致曲线消失；现按引用包装为缓冲区。
• 数值 x 轴的标量下标范围：修正后标量数据在数值 x 轴下不再落入坐标区之外。

代码编辑器

• DiffEditor 的两个页面容器带上父级：无父级的 QWidget 是顶层窗口，addWidget 会先把它当窗口上屏一帧。在多屏（尤其混合 DPI）环境下表现为**「首次进入该页时闪出一个窗口又关掉」**。
• 补全弹窗与悬停气泡延迟创建：两者带 Qt.ToolTip 标志（刻意不用 Qt.Popup，避免 show 时抓取键盘鼠标导致编辑器看似卡死），因而各自占一个原生窗口；原先在构造期创建会在页面可见时产生窗口抖动，现改为首次使用时创建。

---

升级说明

• 无破坏性变更：图表、组件、布局、动画的既有调用方式完全不变。
• 新增依赖声明：numpy>=2.0（图表大数据管线，已在 pyproject.toml / uv.lock / requirements.txt 同步）。
• 版本号：InstructionX_UIKit.__version__ = "alpha-v1.0.3"（唯一来源）；pyproject.toml 为 PEP 440 等价形式 1.0.3a1。
• 环境变量（可选，均有默认值）：UIKIT_CHART_GL（auto / on / off）、UIKIT_BLUEPRINT_GL。

---

已知限制

如实列出，避免误用：

1. 90 fps 的判定口径：端到端帧率受显示器垂直同步约束（60 Hz 屏读数即约 60），不能用它判断图表能力；请以单帧绘制耗时为准（预算 1000/90 = 11.11 ms）。图表初始化时也可用 chart.benchmark() 取到该口径。
2. sampling: None 在大数据上无效：屏幕像素是物理下限，超过它的点既看不到也点不到。需要更密的点请把图表画大（4K 下阈值自动升高），而不是关掉采样。
3. large 聚合与 gpuDirect 适用面：gpuDirect 目前仅支持「标量数值序列」形态的折线；散点大数据请用 large。
4. 同屏多图的极端场景：16 图稳态无压力（约 1 ms/图），但「同一帧内全部更新数据」约为 89 ms（11 fps），硬下限是每图采样与布局的固定成本，建议错开更新时机。
5. 暗色主题仍为实验性功能，个别组件的细节表现仍在打磨。
6. charts/pyramid.py（分层采样金字塔）已实现但默认不接入：实测查询 0.016 ms vs 直接分桶 0.63 ms，但内存 +2.0 倍。

---

测试与验证

• 32 个离屏自测脚本、456 项检查通过（test_gallery 需逐页遍历全部 Demo，其中 Markdown / Mermaid / 聊天页依赖 Chromium GPU 进程，在受限沙箱环境下无法启动，与源码无关）。
• 图表大数据相关验证：采样保真（逐像素列极值逐点比对）、空类目轴 band 中心逐点比对、像素下限、GPU 顶点数与数据点数一致性、实时滚动流读数口径。
• 所有性能数字均在实机（NVIDIA RTX 4070 Ti SUPER / OpenGL 4.6、2560×1440@DPR1.5）以离屏或真实 GL 视口实测，非估算。

Alpha v1.0.2

InstructionX_UIKit alpha-v1.0.2

新功能（feat）

新增 MarkdownView 组件

• Qt 内置引擎原生渲染 Markdown，令牌化样式，append_markdown 流式追加，plain 变体与空占位（b31a7fa）
• 支持 LaTeX 数学公式渲染：matplotlib mathtext 后台异步渲染 + LRU 缓存（MathRenderHub）（e60e2dd）

Mermaid 图表升级

• 改用官方 mermaid.js 引擎渲染：WebEngine 同引擎光栅化，支持全量图型（610775e）
• 新增交互式查看器 MermaidView：叠加层方式嵌入文档，支持拖动平移 / Ctrl+滚轮缩放 / 工具条（8ef00f2）

新增流式对话布局 chat_conversation

• Markdown 消息气泡（user 右对齐 / assistant 整宽），append_to_message 流式追加，底部输入区与 messageSubmitted 信号（9154925）
• 气泡操作条：统计 / 复制 / 删除 / 编辑，AI 气泡加重新生成 / 继续生成（56694b8）
• 支持开发者自定义操作条文案（778c4b6）

Demo 增强

• 流式对话演示覆盖 MarkdownView 全部特性（4489c04）；新增 Markdown 全格式总览流式追加演示分组（6edc595）；流式追加演示覆盖行内与块级 LaTeX 公式（76a4b6c）；MarkdownView 页扩充 Mermaid 图型示例（ed005a9）
• 统一顶层窗口图形 API 为 OpenGL，避免蓝图 GL 视口与 WebEngine 混用冲突（1aa3acc）

缺陷修复（fix）

Markdown / Mermaid

• 修复 MarkdownView 流式增量渲染多项缺陷（41ae61b）：流式追加的块结构与公式增量渲染（c186131）、闭合行残留与列表重解析编号重置（4b2be92）、代码块内边距与块间距过紧（3e7e4ff）
• 修复 Mermaid 降级渲染器解析缺陷与查看器交互一致性（4781fec）

图表（charts）

• 修复 update_option 数据动画失效与 _to_float 缺省语义回归（2b047f8）
• 审计修复：布局缓存脏标记、dataZoom 窗口正确性、gauge 对齐 ECharts、brush 高亮、异常可见性与共享工具（347c5ba）

布局（layouts）

• 修复流式对话滚动跟随状态机两处误判（8296200）；assistant 消息补充圆角气泡底（d87f98c）
• 审计修复：DashboardGrid 上限校验、hero 空占位、替换语义统一、卡片构建器合并、split_panel 防抖（2cd6ffc）

组件（components）

• 审计修复：表单必填校验、缩放与侧槽缓存、浮层生命周期、主题连接清理、SizeMixin 抽取、Timeline/Steps 公开 API（50379a7）

蓝图（blueprint）

• 修复半透明顶层窗口 GL 视口首帧缺失与带体节点手势卡顿（e379acb）
• 审计修复：手势结算冻结、菜单生命周期、边色主题刷新、set_title API、GL 探测缓存守卫（708f905）

动画 / 主题 / Demo

• 修复滚动故事面板 paintEvent 内 render 自身导致的递归重绘（cf61465）
• 动画审计修复：幽灵 spacer 三层兜底、顶级窗口快照动画、slide_transition 快照化、隐藏停表、stop 清理缺口、clear_ripple 新 API（8e9f6aa）
• 主题审计修复：语义色令牌文档同步、QSS 资产原子写入与超龄清理、死导入与死 QSS 规则删除（539c806）
• Demo 审计修复：用法提示对齐真实 API、数量版本文案同步、私有耦合消除、依赖版本统一（0a904d7）

兼容性说明

• 依赖要求：Python >= 3.14，PySide6 >= 6.11.1，qrcode[pil]（QRCodeView）、matplotlib（MarkdownView 公式渲染，本版本新增依赖）
• 公共 API 保持向后兼容

Alpha v1.0.1

InstructionX_UIKit alpha-v1.0.1

蓝图节点图 GPU 加速渲染版本。本次更新的核心是蓝图画布渲染后端重构：在保持公共 API 完全不变的前提下，引入 GPU 辅助绘制，显著改善高分辨率（4K+）与大节点量场景下的平移 / 缩放流畅度。已集成旧版本的项目只需升级组件库，无需修改任何代码。

亮点：蓝图画布 GPU 加速渲染

画布绘制改由内部视口承载，运行时自动选择后端：

• GL 后端（默认，可用时）：视口基于 QOpenGLWidget，背景 / 网格 / 连线 / 节点位图合成走 GPU。无可见自定义体（body_builder）的节点以缓存位图代理由视口统一绘制，平移 / 缩放 / 拖动期间节点内容零重绘；带可见自定义体的节点自动回退为真实控件渲染。
• 软件后端（自动回退）：无 GL 环境（含 QT_QPA_PLATFORM=offscreen 的测试环境）自动使用普通 QWidget 视口，行为与历史版本完全一致，离屏测试与截图回归不受影响。
• 环境变量 UIKIT_BLUEPRINT_GL 可手动控制：auto（默认）/ on（强制尝试，失败回退并记 WARNING）/ off（强制软件渲染，可用于排查显示问题）。

配套绘制优化（两条后端同时受益）：

• 网格平铺纹理缓存；连线路径 / 包围盒 / 采样点缓存与视口裁剪、命中测试包围盒粗筛
• 节点选中发光改由画布层自绘（移除 QGraphicsEffect）；引脚坐标等热点数据缓存
• 拖动 / 悬停 / 框选 / 流动虚线改为局部重绘；视图手势期间跳过逐节点几何落位，手势结束统一补偿；滚轮缩放防抖

实测参考（1080p 窗口、300 节点 / 450 边，桌面 OpenGL 4.6）：

操作	优化前（纯 CPU）	本版 GL 后端
画布平移	约 45 ms/帧	约 19 ms/帧
滚轮缩放	约 51 ms/帧	约 15 ms/帧

分辨率越高（4K+），GL 后端相对纯 CPU 绘制的优势越明显。

注意（Qt 固有行为）：QOpenGLWidget 加入已可见的顶层窗口时，Qt 会重建该窗口的原生句柄，表现为窗口短暂关闭后重开一次。建议在顶层窗口 show() 之前创建 BlueprintCanvas（或预创建一次蓝图页面）；启动时一次性创建并长期持有画布的应用不受影响。详见 docs/USAGE.md §8.6。

新功能：蓝图节点注册表 owner 命名空间隔离

• 注册表键改为 (owner, type_name)：多个插件 / 模块可注册同名节点类型但引脚定义不同，互不干扰
• 注册、查询、创建均可携带 owner 关键字参数划定命名空间；owner=None 为全局命名空间，不传 owner 的旧调用行为完全不变
• 画布、创建菜单、节点体构造全链路支持 owner 透传；同空间异定义覆盖记 WARNING
• 详见 docs/USAGE.md §8.4；Demo 蓝图页已改为标准用法示范（uikit-demo 命名空间 + other-plugin 共存演示）

修复

• 依赖声明：pyproject.toml 补充 qrcode[pil]>=7.4，与 requirements.txt 保持一致（Issue #2）
• Demo 蓝图页：修复选中节点时闪弹一个游离小窗口的问题（属性面板重建时控件被直接摘除父级、短暂成为可见顶层窗口）
• Demo 主窗口：修复首次切换到蓝图页时主窗口短暂关闭后重开的问题（蓝图页改为窗口显示前预创建）

兼容性

• 公共 API 零变化，旧项目直接升级即可
• 测试代码（test 分支）全部离屏通过：29 个测试脚本，含蓝图模块、75+ 演示页遍历与亮 / 暗截图回归

Alpha v1.0.0

InstructionX_UIKit alpha-v1.0.0

首个公开测试版本。InstructionX_UIKit 是一个基于 PySide6（Qt for Python）的纯桌面 UI 组件库：设计令牌 + 亮/暗双主题、57 个组件、12 个响应式布局预设、52 个动画预设、原生图表引擎与蓝图节点图编辑器。

本版本为 Alpha 阶段：API 整体趋于稳定，但细节仍可能调整；暗色主题为实验性功能，个别组件在暗色下的细节表现仍在打磨。

亮点

• 设计令牌 + 双主题：色彩 / 字体 / 间距 / 圆角 / 阴影 / 断点 / 动效全部令牌化，ThemeManager 一键切换亮 / 暗主题，无需重启，全部组件实时热切换。
• 57 个组件：输入 / 展示 / 反馈三大类，动态属性 + 全局 QSS 驱动，统一 sm / md / lg 尺寸体系与完整状态矩阵（hover / pressed / disabled / focus）。
• 12 个响应式布局预设：API 驱动工厂函数，基于断点的响应式重排，空数据自动显示优雅占位。
• 52 个动画预设：28 个属性动画（快照覆盖层方案，规避 Qt6 + QSS + 高 DPI 下 QGraphicsEffect 失效问题）+ 24 个 QTimer 自绘动画组件。
• 原生图表引擎：纯 QPainter 实现的 ECharts 风格图表，不依赖 WebView / JavaScript；set_option 数据驱动，20+ 系列类型，主题感知实时换肤。
• 蓝图节点图：类 UE5 Blueprint / ComfyUI 的节点图编辑器，支持右键建节点、引脚拖线、类型校验、JSON 序列化与执行状态模拟。
• 职责分离：Kit 包零假数据、零 Demo 逻辑，一切内容由调用方 API 传入；独立 Demo 程序内置 74+ 演示页，每页顶部附「用法」代码示例。

安装

pip install -r requirements.txt

依赖：PySide6>=6.6（含 Addons）与 qrcode[pil]>=7.4，除此之外无任何第三方依赖。要求 Python 3.14+。

快速开始

import sys
from PySide6.QtWidgets import QApplication, QVBoxLayout, QWidget

from InstructionX_UIKit.theme import ThemeManager
from InstructionX_UIKit.components import Button, LineEdit, Statistic

app = QApplication(sys.argv)
ThemeManager.instance().apply(app)   # 应用全局主题（默认亮色）

win = QWidget()
lay = QVBoxLayout(win)
lay.addWidget(Statistic(title="活跃用户", value=24317))
lay.addWidget(LineEdit(placeholder="请输入关键词"))
lay.addWidget(Button("确定", variant="primary"))
win.resize(720, 560)
win.show()
sys.exit(app.exec())

运行完整 Demo（74+ 演示页，含 Playground 调参与「用法」示例）：

python main.py

文档

• README — 项目总览与快速上手
• docs/USAGE.md — 使用手册（主题系统、全部组件 / 布局 / 动画 / 图表 / 蓝图示例）
• docs/Design.md — 设计规范（令牌数值、断点、动效、状态矩阵）

说明

• 暗色主题为实验性功能：亮 / 暗切换机制与令牌体系已完整，个别组件在暗色下的细节表现仍在打磨，欢迎反馈。
• 测试代码在 test 分支：main / dev 仅含源码与文档；全部离屏自测（含截图回归）随完整源码维护在 test 分支。
• Alpha 阶段如遇到 API 调整，会在后续 Release 中明确列出变更点。