桌面游戏助手的三条技术链路：约束求解、本地 OCR 与音频样本匹配

这是一个围绕复杂物品清单构建的个人桌面原型。它把三类不同问题放进同一个工作流：在多层容器和独立分区中规划摆放、从本机截图提取文字线索、用已确认的录音样本给候选音效排序。三条链路复用同一份物品描述，但各自有清楚的输入边界和“不能声称什么”。

本文依据本机工作树的源码、自动化测试和项目验证记录整理；没有把未公开仓库里的原始实现或第三方图鉴数据照搬到这里。当前记录不是 Windows 安装包、真实游戏适配或音频准确率报告。

结构：网页原型与桌面桥分开

核心界面用原生 Web 技术实现，求解、样本特征和目录匹配位于可独立测试的模块中。Electron 主进程只承担网页无法可靠完成的系统边界：选择屏幕或窗口、在 Windows 请求系统音频回环、启动本机 OCR 进程，以及把受限能力通过 preload 暴露给界面。

项目提供三种运行方式，但它们不是等价环境：单文件预览无需安装依赖，适合试用清单和算法；本地开发服务只监听回环地址，承接需要本机 OCR 的请求；Electron 版本再增加受系统权限约束的屏幕与音频采集。预览可以说明主要交互，却不能证明桌面采集、OCR 安装或 Windows 打包正常。

摆放问题：把布局变成可验证的搜索

一个容器不是一张随便拼接的矩形。模型把每个分区保留为独立格网，物品记录尺寸、重量、价值、允许的朝向、类型限制和是否必带；容器放入另一个容器后，会新增下一层可用分区。这样能避免把两个并排小格错误合并成长条，也能表达“容器可装背包，但该分区不能装弹挂”一类限制。

求解过程大致分成四步：

1. 校验清单、尺寸、分区、重量、最大嵌套深度和搜索预算，拒绝不完整或越界输入。
2. 先构造一个可行解作为当前最好结果，避免搜索刚开始就因预算耗尽而没有任何可展示布局。
3. 对容器放置、旋转和普通物品位置进行有界搜索；使用剩余价值上界剪枝，并跳过同一父容器中完全等价的空分区状态。
4. 搜索完成后用独立校验器重新检查分区边界、重叠、类型、嵌套、必带物品和重量，再把结果转换为逐步摆放指引。

优化目标是明确的字典序：价值模式先最大化总价值，再比较剩余格子；空间模式先最大化剩余格子，再比较价值。自动装备模式会分别检查背包和弹挂的组合，并把总时间与节点预算分配给候选方案。

预算中止时，界面只报告“当前最佳”，不能把已检查的部分组合包装成全局最优。只有候选组合全部完成证明，或算法能证明已达到严格上界时，才标记为“最优”。这一区分比显示一个看似精确的分数更重要：近似结果有用，但必须诚实说明搜索是否完成。

实现仍有明确的第一版范围：单次最多 36 件物品、12 个分区，重量未知时拒绝套用重量上限；不建模弹药堆叠、拆分物品、枪械拆件或所有赛季规则。所谓最优，只对用户输入的数据、配置规则和目标成立。

OCR：识别文字，不替用户确认清单

桌面 OCR 把不超过 8 MB 的 PNG、JPEG 或 WebP 图片写入临时目录，调用 Tesseract 的简体中文与英文识别，再将 TSV 输出按行和坐标框聚合。匹配器会做全角归一化、别名和名称片段相似度匹配；短暂混入相邻 HUD 文本时，也尝试在较短窗口里找近似名称。

结果同时保留 OCR 文字置信度和物品名称匹配度。近似命中不是事实，因此默认只作为待核对候选；遮挡、重叠截图、隐藏容器内容和画面中未出现的数量无法通过算法“补出来”。识别函数在退出路径删除临时文件，主进程用 spawn 参数数组运行 OCR，不经过 shell 字符串拼接。

项目没有把清单识别做成云端服务。截图留在用户设备上，OCR 需要本机安装 Tesseract 和对应语言包；单文件预览没有桌面 IPC，所以不提供这条能力。

音频：相似度排名不是概率

录音样本经单声道重采样、静音检测和裁剪后，提取固定长度的对数梅尔频谱特征；特征包含 40 帧、每帧 24 个频带。比较时使用受限带宽的动态时间规整，容忍同一声音在播放速度和起止位置上的轻微变化。画面占格与朝向还可以先缩小候选集合，再按已确认样本计算距离并排序。

输出字段刻意叫“相似度”，并固定为未校准状态，而不是“概率”。没有样本覆盖、最佳与次佳结果过近、样本距离过大或候选覆盖不完整时，算法会返回“无法确定”。这避免把小样本的相似度误读成游戏内掉落概率。

目前自动测试使用可重复生成的合成信号检查采样率、音量变化、静音、歧义和拒识；它们证明代码按预设条件运行，不证明真实游戏音效可以被稳定识别。要评估准确率，仍需经许可收集真实、带标签的录音，并按音效类别和设备分别验证。

Electron 权限边界

窗口启用 contextIsolation、sandbox，并关闭 Node 集成。渲染进程只能通过少量 preload 函数请求平台信息、来源列表和 OCR；主进程核对发送方窗口、主 frame 与本地页面地址，拒绝外部页面和子 frame 调用。窗口跳转与弹窗另行拦截。

屏幕或窗口采集只接受用户发起的动作及已选择来源；Windows 才声明系统音频回环能力，Mac 不把普通屏幕流伪装成系统声音。拒绝权限、取消选择或来源消失都应终止采集。这里仍需在目标 Windows 设备实际验证权限提示、不同显示缩放、音轨选择与长时间采集。

测试如何给算法兜底

截至 2026-10-20，当前本地验证有 138 项自动测试：求解器的 20 个固定种子小场景会与独立位掩码穷举结果对照；独立校验器覆盖重叠、越界、循环嵌套和必带遗漏；桌面 IPC 测试验证外部页面/子 frame 被拒绝；音频测试使用合成信号；OCR 测试使用本机 Tesseract 识别生成的中文字图。当前 npm test 为 138/138 通过；npm run check 检查 34 个 JavaScript 文件、桌面构建配置、单文件预览语法与页面 ID 引用。

在当前工作树运行：

npm test
npm run check

这组测试不包括 Electron 安装包启动、Windows 游戏实机截图、系统声音采集、真实音效的识别效果或签名发布。当前原型没有真实校准音频，也没有把任何相似度显示为成功概率；物品尺寸与参考价格同样不是实时、完整的游戏数据库。

2026-10-20 的回归检查还发现单文件预览落后于模块源码：scripts/build-preview.mjs 已打包 ocrScaleFactor，但旧生成 HTML 没有解构该函数，低分辨率识别选区因此抛出 ReferenceError。重新运行 npm run build:preview 后，低分辨率选区缩放/坐标还原回归通过。另将“换图时旧 OCR 结果不得覆盖新图”的测试夹具改为 1920×1080；该用例只验证并发与按钮状态，不再因低分辨率自动放大而依赖未提供的 Canvas 测试桩。生成预览已修复，自动化检查通过，但这不代表已重建候选安装包；Windows 安装和目标设备验收仍未完成。

下一步工程化

• 给清单、物品规则和音频特征定义显式 schema 版本与迁移，不让未来字段变化静默破坏本地文件。
• 为引用的物品规则记录来源、观测日期、可信度和“重量未知”等字段；过期价格应明显标成参考值。
• 在 Windows CI 和目标设备上验证 Electron 安装包、权限撤回、音频回环及缩放布局，再讨论正式分发。
• 对音频排名建立带标签的独立验证集，按样本覆盖率、候选歧义和拒识率评估；达不到标准时继续输出“无法确定”。

官方资料

• Electron 安全建议 与 Context Isolation：用于核对主进程/渲染进程隔离、IPC 校验和外部页面边界。
• Electron desktopCapturer：屏幕来源与桌面音频采集 API；不同操作系统和 Electron 版本的行为需要分别实测。
• Node.js child_process.spawn：子进程参数数组与生命周期管理。
• Tesseract User Manual：OCR 引擎、语言数据和命令行使用说明。

这是一个可运行、可测试的个人工程原型，不是游戏官方工具，也不替代玩家核对。代码通过约束、预算、拒识与独立校验来收敛风险；真实环境尚未验证的部分，仍应诚实留在待办里。