# 朋友制作器开发手册 [English](en/development-manual.md) 专为 Switch 版《朋友收集：梦想生活》制作。 更新时间：2026-05-22 状态：持续开发中 ## 0. 2026-05-22 本地核验快照 本次核验覆盖当前仓库里的桌面端、Web flasher 和 ESP32 固件编译链路： - `npm run ci:local:quick`：通过，包含桌面端类型检查、`94` 个桌面端测试、flasher 类型检查、`8` 个 flasher 测试和 flasher Web 构建 - `npm run build`：通过，完成根项目 TypeScript 编译和静态资源复制 - `~/.platformio/penv/bin/pio run -d firmware/esp32 -e esp32dev_wireless`：通过 - `~/.platformio/penv/bin/pio run -d firmware/esp32 -e esp32dev_wireless_switch2`：通过 - `~/.platformio/penv/bin/pio run -d firmware/esp32 -e esp32dev_wireless_switch_lite`：通过 - `npm run build --prefix site/flasher`：通过，生成网页刷机站发布产物 - `npm run verify:pages --prefix site/flasher`：通过 补充说明： - 当前机器上的 `python3 -m platformio` 不可用，但 `~/.platformio/penv/bin/pio` 可用；因此固件编译按公开文档里的完整 `pio` 路径完成核验 - 上述结论只代表自动化测试、构建和固件编译通过；真实刷写、蓝牙配对、timing 调整和实机绘制仍需要按快速上手在具体硬件上逐段验证 ## 作者说明 - 来源作者：小红书作者 `惜羽拓麻镇` - 当前仓库采用 `GPL-3.0-or-later` 开源协议 - 如公开转发、转载或二次分享，建议注明作者名称 `惜羽拓麻镇` - 如公开转发、转载或二次分享，建议同时附上原始发布地址 ## 1. 当前目标 当前项目的目标不是一次性做完整的“任意图片自动彩绘”，而是先把下面这条实际试用链路做稳： `桌面端应用 / 仓库源码入口 -> 刷入固件 -> 手柄测试 -> 调试测速 -> 脚本生成 -> 串口 ACK 执行 -> ESP32 蓝牙控制器输出 -> Switch 画板稳定复现` 当前优先级： 1. 蓝牙连接和长时间执行稳定 2. 单色绘制、官方色绘制与自定义多色稳定 3. 颜色来源与位移假设继续校准 4. 再考虑更复杂的自动化能力 ## 2. 当前运行形态 当前项目实际存在两条入口： - `桌面端安装包`：面向 `macOS` / `Windows x64` - `仓库源码路线`：面向开发、调试和协议验证 对应到当前实现里： - `apps/desktop/src/electron/main.ts` 负责桌面端壳、资源路径选择、本地 Web 服务启动和主窗口管理 - `package.json` 里已经提供 `electron:dev`、`dist:mac`、`dist:win:x64` 等脚本 - 打包应用不会直接在只读资源目录里运行固件，而是先把 `firmware/esp32` 复制到可写目录，再交给 `PlatformIO` - `Windows` 打包会附带 `drivers/windows` 资源，供桌面端页面里的驱动辅助入口使用 - `apps/desktop/src/web/recoverySessions.ts` 负责恢复任务的落盘、读取、过期清理与恢复状态转换 - 恢复任务当前默认保存在用户文档目录下的 `FriendMaker/recovery-sessions` - `apps/desktop/src/drawingTemplates.ts` 负责图纸模板定义，模板遮罩和预览资源从静态资源目录加载 这意味着当前开发口径不再只是“CLI + 网页”，而是： `Electron 桌面端应用 + 内嵌本地 Web 工作台 + TypeScript 开发工具链` ## 3. 当前稳定能力 截至当前版本，已经验证或基本可用的能力有： - 已具备 `macOS` / `Windows x64` 桌面端打包脚本与桌面端入口 - Web UI 已覆盖 `脚本生成 / 刷入固件 / 手柄测试 / 调试测速` 四页 - 页面里可以直接调用 `PlatformIO` 编译并刷入固件 - 页面里可以直接做手柄连接、蓝牙重置、按钮 / 方向 / 摇杆测试 - 页面里可以直接调 `inputDelay / buttonPressDuration` 并跑闭环测速 - `256x256` 脚本坐标画布 - 公开 UI 当前开放方块像素笔刷的 `1 / 3 / 7 / 13 / 19 / 27` 六种大小 - 圆形像素笔刷仍处于预留/受保护状态，生成和执行主线暂不依赖它 - 进入绘图页后，从画布中心开始绘制 - 中断恢复后，重新进入绘图页时也只按“画布中心起步”建模 - `A` 用作落笔 / 绘制 - 方向键用于单格移动 - 页面可导入图片、生成预览、查看统计并执行命令 - 单色绘制链路已跑通 - 官方色绘制链路已接入 `image-q` - 自定义多色链路已正式接入，可按批次写入 `9` 个自定义色槽 - 官方色会量化到 `7 x 12` 的 `84` 色基础盘，并配置游戏右侧 `9` 个槽位 - 图纸模板系统已接入模板分类、模板预览、模板遮罩和命令裁切 - 自动扣背景、辅助线预览、官方色盘预览都已接入 - 图片导入链路当前支持 `PNG / JPG / WEBP / SVG` - 执行日志、刷写日志、测试日志都已在页面中可观察 - `inputDelay` 当前更适合作为稳定性旋钮，`buttonPressDuration` 更适合作为力度旋钮 - 暂停、中断或异常后的恢复任务会落盘；如果应用在暂停态退出，下次启动后该任务也会自动转成可恢复状态 - 桌面端打包会附带固件目录、图标资源和 `Windows` 驱动资源 - ESP32 已支持基础串口协议 - ESP32 已支持正式绘制所需的 ACK 执行链路 - ESP32 已支持 `TAP <按钮> <次数>`、`HOLD <按钮> <毫秒>`、`STICK ` 等测试命令 - 网页刷机站当前可发布 `Switch1 和 Lite 固件`、`Switch 2` 两个可见型号，并隐藏旧标准 `Switch` 固件入口 ## 4. 当前绘图页建模 当前目标绘图页按下面的固定规则建模： - 进入绘图页后，光标在主画布中心 - 当前没有一个可依赖的“把主画布光标稳定归到左上角”的复位语义 - 因此恢复流程也必须假设用户重新进入绘图页后，仍然从画布中心重新起步 - 当前工具是画笔 - `A` 为绘制 - 方向键每次移动 1 格 - 画布按 `256x256` 脚本坐标处理 这意味着脚本生成页当前主线就是： - 固定 `256x256` - 固定按“中心起步” - 单色、官方色与自定义多色三条正式路线 - 固定以方块像素笔刷为公开 UI 主线，圆形像素笔刷暂不作为正式绘制入口 补充区分： - 文档里如果提到“归左上角”或“左上角起点”，默认都不是指主画布 - 这类描述只应用在色盘列表、基本颜色页或自定义颜色编辑页的内部导航建模上 ## 5. 多色方案分叉 当前多色有两条可能路线： ### 路线 A：基本颜色 这是当前推荐主线。 已知事实： - 基本颜色是系统自带默认盘 - 基本颜色区域为 `7 行 x 12 列` - 总共 `84` 个可直接选择的基础颜色 这条路线的优点： - 颜色集合有限 - 不需要在自定义颜色编辑页里精确调色 - 更适合开环控制 - 更适合做稳定的自动绘制 这条路线后续应该这样做： 1. 记录完整 `7 x 12` 基本颜色表 2. 给每个颜色定义固定的 `row / col` 3. 网页端把目标图片量化到这 `84` 个颜色 4. ESP32 只负责打开颜色页并选择对应格子 当前已接入的程序设计： - Web UI 已接入 `官方色绘制` - 官方色绘制会把图片量化到 `84` 个基本颜色 - 脚本层已接入 `BC ` 命令 - 固件会按 `slot -> 基本颜色页 row/col` 的方式配置 9 个色盘槽位 - 当前策略不再尝试“归左上角”，而是假设 9 个槽位起始都处于游戏默认颜色状态，并跟踪每个槽位当前的 `row / col` - 脚本开始时会先发送 `BC RESET`，把固件内部槽位状态重置为“默认槽位颜色状态” - `BC RESET` 只重置颜色槽位的内部跟踪状态，不表示主画布光标被重置到左上角 - 在基本颜色页移动到目标格子后，按一次 `A` 就会直接回到画布，因此官方色槽位配置不再额外发送 `B / A / B` 当前结论： `基本颜色 7x12` 是后续多色绘制的推荐主线。 ### 路线 B：自定义颜色 这是当前已经正式接入 `自定义多色` 的路线。 已知事实： - 颜色页有“基本颜色”和“自定义颜色”两个标签 - 进入绘图页后按 `Y` 打开色盘列表 - 色盘列表有 `9` 个色盘位 - 色盘列表上方还有其他非色盘项 - 再按一次 `Y` 可进入色盘编辑页 - 进入编辑页后，`R` 切到“自定义颜色”标签，`L` 切到“基本颜色”标签 - `B` 退出色盘页 / 编辑页 - `A` 选中当前色盘 - 编辑页中，`ZL / ZR` 控制下面的色相条，上方大色块是二维选色区 - `M 1 0 / M -1 0 / M 0 -1 / M 0 1` 的方向语义已确认正确 当前仍需继续优化自定义颜色自动化的原因： - `TAP DLEFT 20` 与 `TAP DLEFT 40` 的位移关系不稳定 - 点按次数与光标位移不是严格线性 - 长按和点按的结果不同，长按存在递增或加速效应 - 没有视觉反馈时，无法保证 `#RRGGBB` 被准确落到目标位置 当前结论： `自定义颜色自动调色` 已作为 `自定义多色` 的正式能力接入，但颜色精度和稳定性仍需继续优化。 ## 6. 自定义颜色页已确认信息 虽然当前已经正式接入自动改色，但这些已确认事实仍然需要保留，后续会继续用于优化。 ### 6.1 色盘列表 - `Y` 打开色盘列表 - 色盘列表中，连续按 `下` 可以稳定到底部 - 底部到顶部之间共有 `9` 个色盘位 这说明色盘列表的稳定选择策略应该是： 1. 打开列表 2. 一路向下归到底部 3. 再向上回到目标槽位 ### 6.2 编辑页方向语义 已确认： - 上方大色块： - `M 1 0` 向右 - `M -1 0` 向左 - `M 0 -1` 向上 - `M 0 1` 向下 - 下面色相条： - `ZL` 向左 - `ZR` 向右 ### 6.3 编辑页重置策略 已确认： - 自定义颜色流程进入编辑页后，需要先按一次 `R` 才是正确的自定义颜色标签 - 官方色流程进入编辑页后，需要先按一次 `L` 才是正确的基本颜色标签 - 同时按对角方向不稳定 - 先纵向归零，再横向归零，再重置色相条更合理 - 当前自定义颜色实验分支改为优先测试“左上角起点” - 目前实测稳定的一组归位参数为：上推 `1500ms`、左推 `3000ms`、`ZL` 长按 `2500ms` 推荐的重置顺序是： 1. 向上归零 2. 向左归零 3. `ZL` 长按归到色相条左端 ### 6.4 量程探索结论 当前探索得到的现象： - 上方大色块横向量程明显很长 - 上方大色块纵向量程约为横向的一半量级 - 色相条使用 `HOLD` 测得的时间不可靠，因为长按可能加速 - 目前按实机测试记录，自定义颜色编辑页可先按以下量程理解： - 色相约 `200` 步 - 饱和度约 `213` 步 - 明度约 `112` 步 - `ZR` 的色相前进方向与标准 `HSV hue` 增长方向相反，换算时需要做反向映射 - 当前归位到左上角后，明度高端更接近起点；要压低明度，需要向下移动而不是向上移动 当前结论： 以后如果要继续做自定义颜色自动化，必须： - 优先使用 `TAP` 计数 - 不再使用 `HOLD` 时长直接换算颜色坐标 ## 7. 当前协议补充 当前协议除原有绘图命令外，还增加了测试型命令： ### 7.1 `TAP` 格式： ```txt TAP