该技能面向 Kotlin 与 Compose Multiplatform 桌面应用（JVM 桌面）的开发与构建，汇总了 24 个来自生产环境的“陷阱”，每个陷阱以 references/ 下的一个短文件呈现（不足 150 行）。每个文件给出可用的正确模式、具体的失败方式与原因，以及一节“Verifying it”，提供可在用户项目树上执行的验证命令。使用时，先根据即将编写的代码或正在追查的症状匹配条目，再用 Read 工具阅读所有可能适用的文件，然后再提出代码或修复建议；验证命令中如出现源项目的路径，应替换为用户项目中的对应路径。文件中若引用未列出的陷阱名，则位于同级的其他技能中，可用 glob ../*/references/<name>.md 打开。
内容按主题分为两组。第一组是“桌面 JVM 上的原生代码”：JNA 手写 C 库绑定（Windows 上含义不同的打开标志、按裸偏移读取结构体、被弱引用持有的回调、注册过晚的搜索路径、确认实际打开的文件）；生成 JVM 应用可加载并分发的原生共享库（预构建便携包通常并非可加载库、在支持的最老基础系统上构建、运行路径选择、有意排除的库、以加载并初始化冒烟测试作为构建门禁）；捆绑原生库的 soname 冲突（随附的通用基础库抢占共享对象名导致平台 API 缺符号）；macOS 代码签名前剥离 ._* 伴生文件（避免签名后系统删除文件导致应用被报“已损坏”）；桌面 JVM 内存占用的诚实评估与降低（堆与整体占用比、区分泄漏与分配器空闲页的实验、每线程分配器 arena 导致占用随核数变化）；嵌入原生 C 媒体引擎（每个媒体项一个句柄、专用事件泵线程、输出驱动固定与渲染上下文创建顺序、属性写入限定在同一线程、可选引擎选项的特性检测、数字格式）；通过媒体引擎的编辑列表 URL 形式在桌面把独立音频流与视频流作为单一源播放（流 URL 的长度前缀引用、合并两项不得在交叉淡化中途准备）；在 Compose Desktop 中不嵌入重量级 AWT 面板渲染视频帧（在 StateFlow 上发布不可变快照、用普通 Image 绘制、在 UI 线程外转换、匹配引擎像素字节序）；接入各操作系统“正在播放”与传输控制界面（打包应用需在主线程初始化、通过 JVM 原生访问层调用系统媒体框架、对交给系统的回调保持强引用、限定在自有线程）；针对无法修补的库缺陷编写变通方案模板（说明机制、列出接受的权衡、留出降级逃生口、写明移除条件）。
第二组是“打包、签名、CI 与构建”：使用配置驱动的打包器打包 JVM 桌面应用（HOCON 配置会静默忽略未知键，应用级、按操作系统段、嵌套组的键绑定差异，命令行覆盖键，固定打包 JDK，静默固定 PATH 的环境块）；对会“失败开放”并忽略未知键的格式，以生成产物而非配置来验证功能（两次构建 A/B 对比、产物指纹 grep、CI 断言防回归）；在 JVM 桌面应用端到端接通自定义 URL scheme（按操作系统注册、启动时参数过滤、单实例转发、把回调令牌送达应用状态）；对桌面应用运行 R8 等字节码压缩器（哪些优化族必须关闭、混淆为何破坏渲染与反射层、原生绑定加协程加 HTTP 客户端所需的 keep 规则族、如何把压缩后的 jar 交给打包器）；诊断“子配置解析后无法修改配置”一类的 Gradle 失败（二分插件、哪些修复是已知死路）；处理传递依赖的严格版本约束覆盖自选版本的问题（找出谁固定了什么、何时强制回退与整体对齐、记录固定以免被升级回破坏状态）；用两个不同归属的 Gradle 任务分发预构建原生库（开发机构建切片并打印摘要，CI 只下载并按构建文件中固定的摘要校验）；Windows 11 移除经典命令行管理查询工具后检测虚拟机（通过 PowerShell 查询管理层、同时探测制造商与型号、刻意选择失败方向）；发布自签名 MSIX 离线安装包（随包附带安装脚本与签名证书、脚本化信任再侧载、跨版本保持签名密钥稳定）；在多平台桌面构建承诺某 CPU 架构目标前审计每个原生依赖的切片（一个缺失原生会在首次使用而非构建时拖垮整个目标，审计应做成可重复命令并在每次依赖升级时重跑）；查找并修复仅靠时序运气通过的 CI 步骤（同名挂载卷异步卸载与下一轮挂载碰撞、下载器把错误页静默存为产物）；为多平台桌面应用组织 GitHub Actions 发布流水线（一个 Linux runner 交叉构建各平台产物，另设小型 macOS 作业只做真正需要 macOS 的一步，作业间交接产物，不在昂贵 runner 上编译）；用 BuildKonfig 把构建期配置接入 Kotlin Multiplatform 应用（从不受版本控制的本地属性文件读取机密并注入为生成常量，无机密分支得到空字符串使功能自行禁用而非构建失败，以及新版 Gradle 对生成源所需的任务依赖接线）。
适用场景：桌面构建失败、安装包异常、签名或公证问题、原生库加载问题、内存异常、媒体播放与系统媒体集成异常、CI 偶发失败等。限制：内容面向 Kotlin/JVM 桌面与 Compose Multiplatform 技术栈，具体版本、依赖与配置细节以各参考文件为准；本文档未提供该技能的收费、平台或使用许可信息。