# Windows 与 Mac 兼容开发规范

本规范适用于后续所有开发、修复、文档和发版。插件以Windows与macOS为共同目标，不能仅验证开发电脑后宣称双平台可用。

## 实现要求

- 文件路径用node:path组合，区分Windows盘符、反斜杠、空格、中文和macOS绝对路径；导入本地模块使用pathToFileURL，禁止把Windows路径直接当URL。
- 启动进程优先execFile/spawn参数数组，不用字符串拼接命令；按平台识别可执行文件及.cmd。PowerShell和bash示例分别标明，不把Unix命令直接给Windows用户。
- 不硬编码 /Users、/tmp、盘符或用户目录；使用系统目录API及现有配置。Windows文件占用、权限、原子替换失败应明确报错，不通过删除原文件或清空目录来恢复。
- FFmpeg/ffprobe按平台发现并检测路径；配置有空格或中文时正常调用。缺失只引导检查/获准后安装，不自行执行brew或winget。
- 成品包含入口、客户端、locale/en.json、locale/zh.json、预设、技能及用户指南；运行时不依赖开发机node_modules，不引入构建脚本运行依赖。

## 安装与在线更新

- Mac默认仓库安装，提供成品包备用；Windows默认安装.tgz成品文件或下载链接。Windows ZIP包含原始tgz，package目录只作资料和旧目录恢复，不再作为推荐新装来源。
- 本地成品安装后文件由安装器托管；不能依赖外部解压目录一直存在。在线更新保持配置和任务记录，失败不能先卸载或重置Key。
- 原目录变空或locale缺失先核对当前解析路径及包内文件，再恢复整个旧目录。没有证据时不归因安装器删除，不谎称仅修改指南即修复宿主问题。
- 不放宽供应链策略，不要求全局Git重写或批准未知安装脚本。更新来源使用同版成品，不使用发布页URL作为包地址。
- 安装目录 `pnpm-lock.yaml` 里本插件缺少 `integrity` 的残留记录会让pnpm拒绝整次安装（`ERR_PNPM_MISSING_TARBALL_INTEGRITY`），Windows现场出现过、macOS正常路径写不出。自愈实现见 `src/internal/update-lockfile.ts`：判定覆盖没人引用的旧记录与半条记录，扫描当前profile及其同级staging目录，每2秒复查，只删本插件记录并留备份；客户端命中该错误等一次清理再重试，不换镜像。改动这块要在两平台核对扫描范围、备份文件名与原子替换，Windows实机更新仍按第6条要求单独验证。

## 验证与发版门槛

1. 每项涉及平台的改动，在开发记录中说明两平台影响和验证方式。
2. 执行构建、现有相关测试及实际Harness Schema校验，先确认没有运行中的视频任务。
3. GitHub Actions在windows-latest、macos-latest分别用同一tgz、固定pnpm版本和strictDepBuilds安装。临时目录含中文及空格，验证真实旧成品升级到新成品、语言资源、技能、指南、配置/任务保留及移动原安装文件后仍可读取。目录链接迁移是单独风险路径，不用首次成品安装代替。
4. 自动检查只写临时profile，不使用真实Key、不调用付费API；两个平台全部通过后才能进入上传Release步骤。
5. 发布前核对ZIP完整性、tgz原字节、SHA-256及重复打包一致，所有附件来自同一成品，不上传价格参考资料。
6. 涉及桌面安装、热加载、更新或文件占用时，还需按变更风险进行真实Harness界面验证。没有实机环境时在发布记录明确未覆盖范围；自动runner安装通过不等于桌面实机更新通过。
7. 用户指南、教程、宣传页涉及的平台操作保持一致；指南不写版本日志，工程验证写入对应release文档。

自动检查入口：scripts/check-package-install.mjs。CI发布检查：.github/workflows/publish.yml。

维护脚本（scripts/release.mjs、scripts/clean-releases.mjs、scripts/pack-test.mjs）只用于开发环境，不进插件成品包；它们通过参数数组调用 node、git、gh，不依赖 POSIX 专有命令，Windows 与 macOS 使用同一入口。clean-releases.mjs 默认只演练，删除不可逆，需人工确认计划（或由仓库变量显式开启的定期工作流）后执行。