# 朋友制作器 PRD

[English](en/PRD.md)

版本：v0.2
状态：Alpha 试用中
更新时间：2026-05-22

## 1. 产品概述

`朋友制作器 / Friend Maker` 是一个面向 `macOS / Windows x64 + ESP32-WROOM-32 / ESP-32S + Nintendo Switch` 的自动绘制工具。

用户在电脑上导入图片、调整绘制参数并生成动作脚本，再通过 ESP32 模拟 `Bluetooth Classic` Switch Pro Controller，把图案稳定绘制到《朋友收集：梦想生活》/ `Tomodachi Life` 的画布中。

当前版本已经不再是“只有脚本生成的原型”，而是一个可打包运行的桌面端应用。它内部承载同一套本地 Web 工作台，同时保留仓库源码路线作为开发、调试和协议验证入口，主线 workflow 仍然是下面四页：

- `脚本生成`
- `刷入固件`
- `手柄测试`
- `调试测速`

产品当前仍然坚持下面这条原则：

- 稳定优先于速度
- 可复现优先于炫技
- 可调试优先于自动化程度

## 2. 当前版本一句话

截至 `2026-05-22`，仓库已经具备一条可试用闭环：

`桌面端应用 / 仓库源码入口 -> 刷入固件 -> 手柄测试 -> 调试测速 -> 脚本生成 -> 串口 ACK 发送 -> ESP32 蓝牙控制器输出 -> Switch 画布绘制`

推荐首次使用顺序已经固定为：

1. `刷入固件`
2. `手柄测试`
3. `调试测速`
4. `脚本生成`

## 3. 当前要解决的问题

在 Switch 画板里手工复刻图像，主要有这些痛点：

- 重复劳动多，时间成本高
- 光标移动容易偏，整张图会歪
- 颜色切换步骤繁琐，且容易漏操作
- 同一张图难以稳定复现
- 硬件链路一旦出问题，难以快速定位卡在哪一段

当前版本的目标不是一次性解决“任意图片高保真自动彩绘”，而是先把下面这件事做稳：

`让用户能在一个本地工作台里完成刷机、连手柄、导图和正式绘制，并且每一段都可观察、可排错。`

## 4. 目标用户

### 4.1 核心用户

- 能接受开发板、串口和基础命令行的创客用户
- 想在 Switch 画板里复刻像素图、角色图、标志图的早期试用者
- 愿意先接受固定场景假设，再逐步调参的人

### 4.2 非目标用户

- 希望开箱即用、零配置的普通消费者
- 不愿接触开发板、固件和串口的用户
- 期待任意游戏、任意画布、任意颜色空间都自动适配的用户

## 5. 当前版本目标

### 5.1 产品目标

- 把桌面端入口、仓库源码路线和四页 Web 工作流打通
- 让刷固件、测连接、调 timing 和开始绘制都能在同一套本地系统里完成
- 让单色绘制、官方色绘制和自定义多色进入“可试用、可复现、可排错”的状态

### 5.2 当前成功标准

当前 Alpha 版本至少满足以下条件：

- 用户能启动 `macOS` 或 `Windows x64` 桌面端应用，或通过仓库源码路线启动本地工作台
- 用户能正常进入 `脚本生成 / 刷入固件 / 手柄测试 / 调试测速` 四页
- 用户能在页面里导入 `PNG / JPG / WEBP / SVG`，看到预览、统计信息和实际命令脚本
- 用户能在页面里调用本机 `PlatformIO` 刷入 ESP32 固件
- 用户能在页面里完成手柄连接、蓝牙重置和按钮/摇杆测试
- 用户能在页面里调 `inputDelay / buttonPressDuration` 并运行闭环测速
- 用户能通过串口按 `ACK` 模式发送脚本，并在日志里看到过程
- 用户能在固定场景假设下完成单色、官方色或自定义多色绘制
- 用户能看到恢复任务列表，并从恢复点继续未完成的绘制
- 用户能选择图纸模板，并让模板裁切结果反映到预览与执行命令里

## 6. 当前已完成能力

### 6.1 桌面端与运行时

- 已有 `Electron` 桌面端壳
- 已有 `macOS` 打包路径：`dmg` / `zip`
- 已有 `Windows x64` 打包路径：`nsis`
- 仓库源码路线仍保留为开发、调试和协议验证入口
- 打包应用会附带固件目录、图标资源与 `Windows` 驱动资源
- 打包运行时会先把固件复制到可写目录，再交给 `PlatformIO` 使用

### 6.2 脚本生成页

- 固定 `256x256` 脚本坐标画布
- 公开 UI 支持方块像素笔刷的 `1 / 3 / 7 / 13 / 19 / 27` 六种大小
- 圆形像素笔刷当前仍是预留入口，不作为正式绘制主线
- `单色绘制`
- `官方色绘制`
- `自定义多色`
- `8 / 16 / 32 / 64 / 84` 官方色量化档位
- `8 / 9 / 16 / 18 / 24 / 32 / 64 / 84 / 128` 自定义多色色阶档位
- 图片缩放与横纵偏移
- 自动扣背景
- 图纸模板裁切、模板预览与模板分类选择
- 官方色盘预览与实际用色高亮
- 命令脚本复制、下载、执行
- 一键开始绘制
- 暂停 / 继续 / 中断 / 强制恢复状态
- 固定高度的滚动执行日志

### 6.3 刷入固件页

- 自动检测本机 `PlatformIO`
- 选择固件环境和串口设备
- 直接在页面内编译并刷入 ESP32
- 返回刷写结果卡片
- 返回完整刷写日志
- `Windows` 驱动辅助安装入口

### 6.4 手柄测试页

- 刷新串口
- 连接手柄
- 重置手柄蓝牙
- 方向键 / 摇杆 / 按钮单步测试
- 自定义测试命令发送
- 展示蓝牙发现、认证、连接、配对、可发送状态
- 展示最近主机、传输层、初始化步骤和错误
- 固定高度的滚动测试日志

### 6.5 调试测速页

- 调整 `inputDelay` 与 `buttonPressDuration`
- 当前 timing 本地持久化
- 快速方向 / 按钮试按
- 闭环基准测速与结果卡片
- 将 timing 同步到正式绘制脚本的 `CFG INPUT`

### 6.6 恢复任务与模板系统

- 恢复任务会落盘到用户文档目录
- 异常退出、暂停或中断后可重新读取恢复任务
- 恢复任务会记录命令进度、resume plan、串口参数和预览摘要
- 图纸模板有独立定义、分类、遮罩资源与预览资源
- 模板裁切会直接参与预览生成和正式命令生成

### 6.7 固件与协议

- 文本协议解析
- 串口 ACK 发送链路
- `I / H / M / P / A / B / X / Y / C / W / S / R / E` 等基础命令
- `BC RESET` 与官方色槽位配置相关命令
- 蓝牙控制器连接状态读取
- `TAP` / `HOLD` / `STICK` 等测试型命令

## 7. 当前范围与不做项

### 7.1 当前版本范围

- 平台：
  - `macOS` 桌面端安装包
  - `Windows x64` 桌面端安装包
  - `macOS / Windows` 仓库源码路线
- 本地形态：`Electron 桌面端应用 + 内嵌本地 Web 工作台 + TypeScript 开发工具链`
- 硬件主线：`ESP32-WROOM-32 / ESP-32S`
- 控制器路线：`ESP32 Bluetooth Classic -> Switch`
- 目标场景：Switch 版《朋友收集：梦想生活》绘图页

### 7.2 当前明确不做

- `Linux` 正式打包与正式支持
- 自动视觉校准
- 自定义颜色精确自动调色
- 任意游戏 UI 自动识别
- 脱机任务上传后独立执行

## 8. 关键使用流程

### 8.1 首次使用流程

1. 启动桌面端应用，或用仓库源码路线启动本地工作台
2. 在 `刷入固件` 页刷入推荐固件
3. 在 `手柄测试` 页完成蓝牙连接与按钮验证
4. 在 `调试测速` 页先把当前板子、线材和 timing 跑稳
5. 回到 `脚本生成` 页导入图片并调整参数
6. 先生成预览与命令，确认无误后正式开始绘制

### 8.2 日常绘制流程

1. 打开桌面端应用或本地调试入口
2. 快速确认手柄状态
3. 导入新图片
4. 选择 `单色绘制`、`官方色绘制` 或 `自定义多色`
5. 检查网页里所选画笔预设、中心起点、模板选择与官方色槽位前提
6. 开始绘制，并在日志和恢复任务状态里观察执行过程

## 9. 技术与场景假设

当前主线按下面这些固定假设运行：

- 目标画布按 `256x256` 脚本坐标处理
- 开始绘制前，Friend Maker 会自动切到网页里所选画笔
- 开始绘制前，画笔 / 光标已经停在画布中心
- 建议使用 `方块笔刷`
- `A` 负责绘制
- 方向键负责单格移动
- 如果使用 `官方色绘制`，游戏右侧 `9` 个色盘槽位保持默认颜色

这些假设不是最终形态，而是当前版本为了稳定性选择的工程边界。

## 10. 当前限制

- 仍然依赖固定场景假设，不是全自动校准
- 官方 `7x12` 色盘仍在持续校准
- 自定义多色虽然已经作为正式功能开放，但颜色还原与长流程稳定性仍在继续优化
- 桌面端依然依赖本机 `PlatformIO`、工具链与部分上游下载成功
- 桌面端打包安装体验和错误提示仍需要继续打磨，尤其是 `Windows` 路径

### 10.1 色差调整方案（后续版本说明）

这一节用于记录后续对“网页预览颜色 vs Switch 实际观感”差异的调整边界，方便后面继续调参和改实现时保持同一口径。

这不表示当前 Alpha 已经实现视觉闭环，也不改变 7.2 里“自动视觉校准”和“自定义颜色精确自动调色”暂不承诺的范围。

- 目标不是追求任意图片的绝对色准，而是在不引入摄像头闭环的前提下，让 `官方色绘制` 和 `自定义多色` 的最终观感比当前更接近网页预览，并保持可复现
- 调整优先级先做 `官方色绘制`，再做 `自定义多色`；`单色绘制` 不作为这一轮色差优化重点
- 调整链路按两段处理：
  - `感知色差匹配`：逐步从当前偏工程化的 RGB 距离，升级到更接近人眼观感的匹配方式，用于减少明显错色
  - `游戏内偏色补偿`：在候选色确定后，再叠加针对游戏内显示效果的补偿规则，例如暗部保护、低饱和颜色保护、暖色偏移和亮部压缩
- `官方色绘制` 后续维护一份可版本化的 `84 色校准表`，允许每个官方色记录“预览参考色”和“实机补偿结论 / 权重”；后续优先改表，不要把修正逻辑分散写死到多处
- `自定义多色` 后续维护一组可调拨杆，而不是一次性写死目标值；优先考虑这些调节项：
  - 量化前的亮度 / 饱和度预补偿
  - 量化后的单色槽位微调
  - 暗部、肤色、低饱和区域的保守保护
  - 不同笔刷大小下是否启用不同补偿档
- 预览层和执行层后续要保留“修正前 / 修正后”的概念，避免之后只能看到最终颜色，却分不清偏差来自量化、补偿还是游戏内显示
- 任何色差修正都不应破坏现有恢复任务、命令分段和官方色 / 自定义色槽位协议；颜色修正应优先作为 `image quantize -> palette selection -> preview` 之间的独立步骤接入
- 后续验收至少要能拿固定测试图比较“修正前 / 修正后”的预览与实机结果，并记录每次调整主要改善的是哪类图片

## 11. 里程碑状态

### Phase 0：本地工作台成型

状态：已完成

- 本地 Web 工作台四页结构已建立
- 公开文档、开发文档、联调路径与示例素材已就位

### Phase 1：串口链路与脚本执行

状态：已完成

- 图片预览、命令生成、串口 ACK 发送已打通
- 日志、暂停 / 继续 / 中断控制已接入

### Phase 2：桌面端壳与资源打包

状态：已完成

- 已接入 `Electron` 主进程入口
- 已接入 `macOS` / `Windows x64` 打包脚本
- 已接入固件复制到可写目录、图标资源和 `Windows` 驱动资源打包

### Phase 3：网页内刷固件与设备验证

状态：已完成到可试用阶段

- 可直接在页面内调用 `PlatformIO`
- 可查看刷写结果与日志
- 已接入手柄连接、状态读取和单步测试

### Phase 4：正式绘制闭环与恢复能力

状态：已进入 Alpha 试用

- `刷入固件 -> 手柄测试 -> 调试测速 -> 脚本生成 -> 开始绘制` 已可跑通
- 单色、官方色和自定义多色主线均可试用
- 恢复任务与模板系统已经接入正式 workflow

### Phase 5：后续优化阶段

状态：持续进行中

- 视觉校准
- 脱机执行
- 更稳的颜色与位移校准
- 可版本化的色差补偿与调色拨杆
- 更完整的桌面端安装、恢复和排障体验

## 12. 当前验收标准

当前版本的阶段性验收，以这些标准为准：

- `npm run check` 与 `npm run build` 可通过
- 桌面端入口可正常启动，并打开四页工作流
- `刷入固件` 页能检测 `PlatformIO` 与串口
- `手柄测试` 页能显示连接状态并发送测试命令
- `脚本生成` 页能生成预览、脚本和执行统计
- 恢复任务可写入、重新读取并继续执行
- 图纸模板可被选择，并正确反映到预览和命令生成结果
- 正式执行时日志可观测、命令按 ACK 推进

截至 `2026-05-22` 的本地自动化核验结果：

- `npm run ci:local:quick` 通过
- `npm run build` 通过
- `esp32dev_wireless`、`esp32dev_wireless_switch2`、`esp32dev_wireless_switch_lite` 三个固件环境编译通过
- `npm run build --prefix site/flasher` 与 `npm run verify:pages --prefix site/flasher` 通过
- 真实硬件刷写、蓝牙配对、timing 调整和实机绘制仍按快速上手逐段验收

## 13. 仓库中的对应实现

- 桌面端打包与脚本：`package.json`
- 桌面端主进程：`apps/desktop/src/electron/main.ts`
- Web UI 服务：`apps/desktop/src/web/server.ts`
- Web UI 交互：`apps/desktop/src/web/static/app.js`
- Web UI 页面：`apps/desktop/src/web/static/index.html`
- 恢复任务：`apps/desktop/src/web/recoverySessions.ts`
- 图纸模板：`apps/desktop/src/drawingTemplates.ts`
- 图片处理：`apps/desktop/src/image/*`
- 后续色差调整主落点：`apps/desktop/src/image/quantize.ts`、`apps/desktop/src/config/officialPalette.ts`、`apps/desktop/src/web/static/app.js`
- 路径生成：`apps/desktop/src/path/scanline.ts`
- 串口发送：`apps/desktop/src/serial/sender.ts`
- 固件实现：`firmware/esp32/src/*`

## 14. 下一阶段优先级

1. 继续提高蓝牙连接与长时间绘制稳定性
2. 按“感知色差匹配 -> 游戏内偏色补偿 -> 可版本化校准表 / 调色拨杆”的顺序，继续优化官方色与自定义多色的颜色还原和实际观感
3. 继续优化绘制路径、命令执行路径与长流程效率
4. 继续优化用户使用体验，包括执行日志、状态提示、失败恢复体验、桌面端安装体验与内部验证说明