踩坑实录：那些年我掉过的坑

症状：PowerShell 脚本里写的中文全部变成乱码，甚至直接语法报错。

根因：Windows PowerShell 5.1 读 UTF-8 无 BOM 的 .ps1 会按本地编码（GBK）解析，中文自然乱掉。

✅ 解法：脚本加 UTF-8 BOM，或避免中文字面量，用环境变量拼路径。

症状：开机自启脚本整行不执行，弹窗报编译错误。

根因：wscript 不支持 UTF-8 编码的 .vbs，带 BOM 直接编译失败。

✅ 解法：vbs 必须纯 ASCII，路径用 %USERPROFILE% 环境变量展开。

症状：调用 aria2 RPC 下载，服务端返回 500 Parse error，进度永远不动。

根因：HTTP 请求缺 Content-Length 头，走了 chunked 传输被 aria2 拒绝。

✅ 解法：RPC 请求必须显式带 Content-Length；收尾查 tellStopped 而不是等进程退出。

症状：明明手动下载了 cloudflared，插件还是报下载失败。

根因：文档说的文件名和实际检测的文件名不一致——插件检测的是不带平台后缀的名字。

✅ 解法：把下载的文件重命名成插件实际检测的文件名，而不是文档写的那个。

症状：应用皮肤后前端报「应用未确认」，重启服务直接 YAML 解析崩溃。

根因：皮肤写入配置时保留了文件头的裸空数组行、又没加 YAML 分隔符，拼出非法 YAML。

✅ 解法：写完配置先校验 YAML 合法性再应用；修复脚本备份、去裸行、加分隔符、重启。

症状：GitHub 安装的插件包装好了，但能力一个都没出现。

根因：发布包里漏了核心配置文件，安装器只生成了占位文件；打包文件列表没包含它。

✅ 解法：仓库根必须有 package.json，发布文件列表必须包含配置与入口文件。

症状：把动态插件固化成正式包后，一加载就 ReferenceError 崩掉整个前端。

根因：动态插件沙箱特有的全局对象，在固化后的正式运行环境里根本不存在。

✅ 解法：固化版改用框架官方提供的注册接口（HTTP 端点 + fetch），彻底不碰沙箱全局。（详见另一篇《动态插件固化的坑与路》）

症状：桌面端好好的拖动/缩放，手机上完全没反应。

根因：用的是鼠标事件，触摸屏根本不触发；而且没有阻止触摸滚动。

✅ 解法：改用 Pointer Events（一套代码桌面手机通吃），并加 touchAction: none 防止误滚。

症状：语音识别一会好一会崩，后启动的进程直接挂掉。

根因：录音设备独占，开机自启和手动启动重复跑了两份识别进程。

✅ 解法：常驻服务只允许一个实例，排查用进程命令行确认数量。

症状：AI 回复完，语音助手就是不开口。

根因：假设事件流尾部会有一条用户消息来触发朗读，但真实事件流根本没有它，条件永远不成立。

✅ 解法：先打印真实事件流再写逻辑；改成按会话特征 + 最后一条助手文本判断，立刻生效。