winforms-to-qt-mapper

提供完整的C# WinForms到Qt C++迁移指导,包括架构分析、控件映射、事件转换、布局迁移、性能优化和测试验证。适用于从单体WinForms应用重构为分层Qt架构的企业级项目。 使用时机: - 需要将WinForms应用迁移到Qt框架时 - 需要设计Qt分层架构和接口层时 - 需要分析WinForms项目...

Security Scan

The skill broadly matches its stated purpose (WinForms → Qt migration) but contains multiple packaging and instruction inconsistencies and disproportionately heavy dependencies that warrant caution before installing or running on sensitive codebases.

Purpose & Capability

The scripts and documents (analyzers, mapper, code generator, Roslyn analyzer) are consistent with a WinForms-to-Qt migration tool; Roslyn-based analysis and an 'IntelligentMapper' justify some ML and analysis dependencies. However, package.json and SKILL.md disagree on file locations and names (e.g., SKILL.md references migration_planner.js, code_generator.js, interface_generator.js, layered_architect.js etc., while the manifest contains differently named scripts such as generate_qt_code.js and analyze_winforms.js). The package also lists server/web libraries (express, ws, helmet) and ML libs (tensorflow, brain.js) that are heavier than strictly necessary for a static code-mapping tool and may be disproportionate unless the tool actually provides a web UI or remote ML service.

Instruction Scope

SKILL.md instructs the agent (and user) to run many node scripts against a user's project path, which necessarily reads project files and writes generated Qt code — appropriate for the stated task. But SKILL.md references multiple script filenames that are missing or differently named in the repo, which will cause runtime errors or unexpected behavior. The instruction set is otherwise explicit about scanning source files, generating outputs, and validating UI parity (pixel comparisons, style validation). There is no instruction to send project data to external endpoints in SKILL.md, but some scripts (not fully shown) import child_process and networking-related dependencies, so you should inspect scripts for any network calls before running on private code.

Install Mechanism

No install spec is declared (instruction-only install), so nothing is automatically downloaded at install time — lower supply-chain risk. However, package.json lists many dependencies (tensorflow/tfjs, brain.js, express, ws, multiple logging libs) and devDeps; installing or npm installing the package will fetch numerous third-party packages. Some entries look unusual for a pure offline converter (express/helmet/cors/compression), increasing the attack surface when performing npm install. The repo appears to expect Node >=18 but also references @microsoft/codeanalysis-csharp (a .NET analysis concept) which may not behave as expected in a Node environment — another install/runtime mismatch to verify.

Credentials

The skill does not request environment variables, credentials, or config paths. The runtime instructions operate on local project files, which is appropriate for the stated purpose. No secrets or external credentials are declared or required by SKILL.md.

Persistence & Privilege

The skill is not marked always:true and uses default autonomous invocation (normal). There is no evidence the skill attempts to modify other skills or agent-wide configuration. It writes generated code to user-specified output directories (expected behavior).

What to consider before installing

This package appears to implement a legitimate WinForms→Qt migration toolkit, but there are notable red flags you should address before running it on sensitive code: 1) Verify filenames and runtime commands: SKILL.md refers to scripts that are missing or named differently in the repo. Confirm which scripts exist and test them on a small sample project first to avoid surprises. 2) Review scripts for network/exec usage: Search all JS files for child_process.exec/execSync/spawn, axios/fetch/ws/express usage, and any hardcoded URLs or remote endpoints. If scripts attempt network calls, inspect what is sent and to where. 3) Inspect dependencies: The dependency list includes heavy ML libraries and several webserver packages. If you npm install, these will be fetched — consider auditing or installing in an isolated environment (container or VM). If you do not need the web/ML features, consider trimming or forking the repo. 4) Run in a sandbox: Execute the tools on non-sensitive sample projects first (or inside a disposable container) to validate behavior, output locations, and that no unexpected outbound traffic occurs. 5) Check build/runtime mismatches: Some referenced tooling (Roslyn/.NET analysis) may require .NET tooling rather than pure Node; confirm prerequisites and ensure you have the correct environment before running. 6) Confirm licensing and provenance: The source/origin is listed as unknown; verify the repository origin and maintainers, and review CHANGELOG/README claims (e.g., '100% zero compile errors') skeptically and validate with your own build tests. If you want, I can (a) search the provided files for network or exec usage and summarize exact lines that matter, or (b) list missing script names and where SKILL.md and package.json diverge so you can fix or test safely.

WinForms到Qt迁移工具

快速开始

场景A: 全新项目迁移

# 1. 分析WinForms项目架构
node scripts/architecture_analyzer.js --project <路径> --output <文件>

# 2. 生成迁移计划
node scripts/migration_planner.js --analysis <分析结果> --output <计划文件>

# 3. 生成Qt代码
node scripts/code_generator.js --mapping <映射文件> --output <目录>

场景B: 架构重构

# 1. 设计分层架构
node scripts/layered_architect.js --project <路径> --output <设计文件>

# 2. 创建接口层
node scripts/interface_generator.js --analysis <分析结果> --output <目录>

# 3. 性能优化
node scripts/performance_optimizer.js --project <路径> --output <优化建议>

场景C: 现有项目优化

# 1. 性能分析
node scripts/performance_analyzer.js --project <路径> --output <分析报告>

# 2. 测试生成
node scripts/test_generator.js --project <路径> --output <测试目录>

核心功能

1. 架构分析

功能: 分析WinForms单体架构,识别依赖关系和复杂度

输出:

• 依赖图和复杂度分析
• 重构建议和优先级
• 接口层设计方案

详细指南: architecture_analysis.md

2. 接口层生成

功能: 生成MainControlWrapper接口层代码

特性:

• 标准接口分类(初始化/控制、数据获取、配置管理等)
• 接口命名规范
• 测试框架自动生成

详细指南: interface_layer.md

3. 代码转换

功能: WinForms代码到Qt代码的转换

包含:

• 控件映射 → control_mapping.md
• 事件转换 → event_conversion.md
• 布局迁移 → layout_migration.md

4. 性能优化

功能: Qt项目性能分析和优化

优化策略:

• 延迟加载策略
• UI刷新优化
• OpenGL加速
• 缓存机制设计

详细指南: performance_optimization.md

5. 测试验证

功能: 完整的测试体系建立

覆盖范围:

• 完整的测试用例分类(单元测试、接口测试、集成测试、UI测试、性能测试)
• Google Test框架使用
• 测试覆盖率目标(>90%)

详细指南: testing_strategy.md

迁移工作流程

阶段1: 需求分析和UI清单

# 1. 分析WinForms项目架构
node scripts/architecture_analyzer.js --project <路径> --output analysis.json

# 2. 建立UI功能清单(重要!)
node scripts/ui_inventory.js --project <路径> --output ui_inventory.json

# 3. 生成迁移计划
node scripts/migration_planner.js --analysis analysis.json --ui ui_inventory.json --output plan.json

# 4. 输出内容:
#    - 项目结构分析
#    - UI功能清单(字体、布局、颜色、交互等)
#    - 控件和事件清单
#    - 依赖关系图
#    - 复杂度评估

重要提示: UI功能清单是实现100% UI一致性的基础,详见 UI功能清单文档

阶段2: 设计规划

# 1. 设计分层架构
node scripts/layered_architect.js --analysis analysis.json --output architecture.json

# 2. 生成接口层
node scripts/interface_generator.js --analysis analysis.json --output interface/

# 3. 输出内容:
#    - 分层架构设计
#    - 接口层定义
#    - 数据模型设计
#    - 性能优化策略

阶段3: 代码转换

# 1. 生成Qt项目基础
node scripts/code_generator.js --mapping plan.json --output QtProject/

# 2. 转换控件和属性
node scripts/control_mapper.js --mapping plan.json --output QtProject/

# 3. 转换事件处理
node scripts/event_converter.js --mapping plan.json --output QtProject/

# 4. 迁移布局系统
node scripts/layout_migrator.js --mapping plan.json --output QtProject/

阶段4: UI一致性验证(重要!)

# 1. 像素级UI对比
node scripts/ui_compare.js --winforms WinFormsApp/ --qt QtProject/ --output ui_diff.json

# 2. 字体和颜色验证
node scripts/validate_styles.js --project QtProject/ --inventory ui_inventory.json --output style_validation.json

# 3. 交互行为验证
node scripts/validate_interactions.js --project QtProject/ --output interaction_report.json

# 4. 可折叠/隐藏功能验证
node scripts/validate_collapsible_ui.js --project QtProject/ --output collapsible_report.json

验证标准: 详见 UI一致性验证清单

阶段5: 测试验证

# 1. 生成测试代码
node scripts/test_generator.js --project QtProject/ --output tests/

# 2. 验证迁移结果
node scripts/validate_migration.js --qt-project QtProject/ --winforms-project WinFormsProject/

# 3. 性能测试
node scripts/performance_tester.js --project QtProject/ --output perf_report.json

# 4. 输出内容:
#    - 测试用例报告
#    - 覆盖率分析
#    - 性能对比
#    - 回归测试结果

常用命令速查

架构分析

# 完整分析
node scripts/architecture_analyzer.js --project ./WinFormsApp --output analysis.json

# 仅分析依赖
node scripts/architecture_analyzer.js --project ./WinFormsApp --type dependencies --output deps.json

# 仅分析复杂度
node scripts/architecture_analyzer.js --project ./WinFormsApp --type complexity --output complexity.json

代码生成

# 生成完整项目
node scripts/code_generator.js --mapping mapping.json --output QtApp/

# 仅生成接口层
node scripts/interface_generator.js --analysis analysis.json --output interface/

# 仅生成测试
node scripts/test_generator.js --project QtApp/ --output tests/

验证和优化

# 验证迁移
node scripts/validate_migration.js --qt-project QtApp/ --winforms-project WinFormsApp/

# 性能分析
node scripts/performance_analyzer.js --project QtApp/ --output perf_analysis.json

# 优化建议
node scripts/performance_optimizer.js --analysis perf_analysis.json --output optimization.json

参考文档索引

详细的迁移指南请查看 references/ 目录:

架构设计

• 架构分析完整指南 - WinForms架构分析和评估
• 分层架构设计 - Qt分层架构设计方法
• 接口层设计 - MainControlWrapper接口层设计

代码转换

• 控件映射参考 - WinForms到Qt控件映射
• 事件转换指南 - C#事件到Qt信号槽转换
• 布局迁移指南 - 布局系统迁移
• 数据绑定转换 - 数据绑定到Model/View转换

高级主题

• 内存管理 - C#到C++内存管理转换
• 多线程转换 - C#多线程到Qt多线程转换
• DLL集成 - DLL集成方案(显式加载)

性能和测试

• 性能分析 - 性能分析方法
• 性能优化 - 性能优化策略(+47%提升经验)
• 测试策略 - 测试策略(172个测试用例经验)
• 测试生成 - 测试代码生成

问题解决

• 编译问题解决 - 编译问题解决
• 常见问题 - 常见问题解决
• 最佳实践 - 最佳实践总结

UI一致性(重要!)

• UI功能清单 - 迁移前UI清单和验证方法
• UI差异对比 - WinForms vs Qt UI差异详细对比
• 可折叠UI实现 - 可折叠/隐藏UI组件实现指南

模板和示例

项目模板

# Qt项目模板
assets/templates/qt-project-template/

# 接口层模板
assets/templates/interface-layer-template/

# 测试模板
assets/templates/test-template/

示例代码

• 控件映射示例
• 事件转换示例
• 布局迁移示例
• 性能优化示例

技术支持

文档

• 故障排除指南
• FAQ
• 术语表

示例

• 完整项目示例
• UI一致性示例
• 可折叠UI示例

外部资源

• Qt官方文档
• Qt控件参考
• 信号和槽机制
• 布局管理系统

---

UI 100%一致性验证指南

验证流程

迁移前
  ↓
建立UI功能清单 ← [ui_inventory_checklist.md]
  ↓
迁移实现
  ↓
像素级UI对比 ← [ui_differences.md]
  ↓
字体和颜色验证
  ↓
交互行为验证
  ↓
可折叠/隐藏功能验证 ← [collapsible_ui.md]
  ↓
100%一致 ✅

必须验证的内容

1. 外观一致性

• ✅ 控件尺寸(像素级)
• ✅ 控件间距(像素级)
• ✅ 字体、颜色、样式
• ✅ 图标、图片显示
• ✅ 控件边框、圆角

2. 布局一致性

• ✅ 窗体初始大小
• ✅ 控件初始位置
• ✅ 响应式缩放行为
• ✅ 最小/最大尺寸
• ✅ 停靠行为

3. 交互一致性

• ✅ 鼠标事件响应
• ✅ 键盘快捷键
• ✅ Tab顺序
• ✅ 焦点行为
• ✅ 拖拽行为

4. 可折叠/隐藏功能

• ✅ 面板折叠/展开
• ✅ 标签页动态管理
• ✅ 菜单项动态控制
• ✅ 工具栏状态切换

验证工具

• Screen Ruler: 像素级测量
• PixPick: 取色器
• Snipaste: 截图对比
• PyAutoGUI: 自动化截图对比

常见差异修复

差异	WinForms	Qt	修复方法
按钮圆角	0px	2-4px	border-radius: 0px
表格行高	23px	21px	setDefaultSectionSize(23)
滚动条宽度	17px	16px	setStyleSheet("width: 17px")

---

重要提示: 本Skill提供的是迁移指导和辅助工具,无法实现100%自动化转换。重要的业务逻辑、复杂交互和性能优化需要人工审查和调整。

UI一致性: 实现100% UI一致性需要严格遵循UI功能清单,进行像素级验证,特别是字体、布局、颜色和可折叠/隐藏功能的细节对比。