02-tech-stack

核心技术栈（2025）

• Windows: WebView2（Chromium Edge）+ Rust（windows-rs, webview2-com），以"父 HWND 子窗口"方式内嵌至 Qt 容器；UI 操作在 STA 线程执行
• 跨 DCC：Maya/3ds Max/Houdini/Nuke 使用 Qt 宿主；Blender 采用浮动工具窗
• Python 包：仅一个 .pyd（pyo3 + maturin），不引入第三方 Python 依赖
• 并发模型：Rust 侧消息桥与调度，Qt 负责事件循环；Rust 不接管消息泵
• 跨平台路线：macOS（WKWebView）、Linux（WebKitGTK 或 CEF/OSR）按需启用
• 最低需要支持python-3.7
• 我们的项目和环境管理使用 uv 来管理 Python 依赖，使用 just 作为任务运行器

# 使用 just 运行任务
just build          # 构建项目
just test           # 运行测试
just lint           # 运行代码检查

# 使用 uv 管理 Python 环境
uv pip install -e . # 安装 Python 包
uv run pytest       # 运行 Python 测试

HTML / 静态资源加载策略

• 内联 HTML：WebView.load_html(html: str)，适用于简单原型或不依赖本地静态资源的页面
• 本地静态站点：优先使用 WebView.load_url("file:///.../index.html") 加载磁盘上的 HTML 文件；相对路径的图片/CSS/JS 由浏览器根据该文件路径解析
• DCC + Qt 场景：QtWebView 只是一个 Qt 宿主 QWidget，所有导航行为都委托给核心 WebView：
  • QtWebView.load_html(html: str) → WebView.load_html(html)（不再暴露 base_url）
  • QtWebView.load_url(url: str) → WebView.load_url(url)，其中 url 可以是 http:// 或 file:/// URL
• 需要自定义相对路径解析时，推荐在 HTML 中使用 <base href="file:///.../"> 显式声明，而不是在 Python API 上引入 base_url 参数。

DCC 适配矩阵（Windows 优先）

• Maya 2025+（Qt6/PySide6）：QWidget.winId() → HWND；Qt 容器负责 resize/focus/DPI 事件
• 3ds Max（Qt）：QWidget.winId() → HWND；同 Maya 流程
• Houdini（PySide2/Qt5）：hou.qt.mainWindow().winId() → HWND；子 widget 作为容器
• Nuke（PySide2/Qt）：自定义 Panel 返回 QWidget；winId() → HWND
• Blender（非 Qt）：采用浮动/owned 顶层工具窗（Win32 + WebView2），提供置顶与尺寸钩子

Python 包与 API（零依赖）

• 单一 .pyd：pyo3 + maturin，ABI3（按 DCC Python 版本矩阵构建 wheel）
• API（示意）：
  • create(parent_hwnd, x, y, w, h, url, opts) -> handle
  • set_bounds(handle, x, y, w, h)
  • navigate(handle, url)
  • eval(handle, js)
  • post_message(handle, json)
  • on_message(handle, callback)
  • dispose(handle)

Standalone 模式

• 保留现有 wry/tao 模式用于独立运行和开发调试
• 后续可迁移为 Win32 + WebView2 顶层窗口（不依赖 wry/winit），与 DCC 内嵌实现一致

Cargo Features（规划）

• 默认：win-webview2 + python-bindings
• 可选：wry-backend（standalone 兼容）
• 预留：mac-wkwebview、linux-webkitgtk、linux-cef（OSR）