Bead

Bead 是一个面向网页与移动端的 AI Agent 拼豆图案工作台。它把图片转成可编辑的拼豆画布，支持逐格修正、颜色统计、模板交换和烫法预览，让图案从设计、校对到制作准备保持在同一条工作流中。

功能概览

• 画布编辑：支持 16×16、29×29、58×58 和 87×87 画布，提供移动画布、选择移动、画笔、橡皮、混豆和吸管工具。
• 双路径图案生成：同时提供本地传统算法和 AI Agent 两种生成方式，用户可以按速度、可控性和艺术表现选择合适的路径。
• 模板工作流：导入、编辑并导出 .bead.json 模板；导入时会校验模板类型、画布尺寸、颜色代码和颜色值。
• 导出：导出带坐标、颜色代码和颜色统计的图案图片，便于制作和核对。
• 烫法预览：使用 Three.js 展示不同烫法、光照和磨砂效果，解决线下制作无法所见即所得的问题。
• 本地持久化：作品和编辑历史保存在浏览器本地，支持撤销、重做、复制和清空草稿。
• 响应式布局：桌面端使用右侧颜色/预览面板；移动端将工具栏、颜色面板和 3D 设置收纳到底部，适配窄屏操作。
• 主题与跨端：支持跟随系统、浅色和深色主题；通过 Capacitor 将同一套 client 体验封装到 iOS 与 Android，并接入文件系统、分享和媒体能力。

作品与发现

应用的主导航分为两个核心页面：

• 作品页：集中管理本地创建和导入的作品。可以新建不同尺寸的画布，继续编辑已有作品，重命名、复制或删除项目，也可以从作品操作菜单发布当前图案。
• 发现页：浏览已经发布的拼豆作品，打开详情查看完整图案，并将喜欢的作品添加回自己的作品列表继续编辑。

发布会提交作品名称、画布尺寸和当前快照。空画布不能发布，服务端还会校验快照中的颜色和单元格范围，确保进入发现页的内容是完整且可复用的。

AI Agent 图案生成

传统算法适合快速、可重复的像素化处理：它在浏览器内对图片做平均色/主色采样，映射到 MARD 调色板，再清理过小区域。这种方式响应快、结果可预测，但只看像素和颜色距离，不理解主体、构图或语义。尤其当大图被压缩到小尺寸画布时，细节容易互相吞并，轮廓可能扭成一团。

AI Agent 先理解图片中的主体，再针对目标画布尺寸进行艺术化重构。它会尝试移除背景、保留主体的轮廓比例与标志性特征，使用适合拼豆的块面和高对比色，并直接按目标网格组织画面。因此它对照片、插画和复杂构图有更广泛的适应性；在大图转小画布时，也能主动取舍细节、强化识别度，而不是把所有内容机械压缩。

两种结果都会回到同一个可编辑画布，用户可以继续逐格修改、切换颜色或重新生成，不会被生成结果锁定。

可追溯的 AI Pipeline

AI 生成不是一次不可见的黑盒请求，而是一条由 Inngest 驱动的可追溯任务流程：

1. API 保存原始图片，创建 jobId，写入 queued 状态，并发送 ai/image.pipeline.requested 事件。
2. Inngest 以 jobId 做幂等键并配置重试，先记录 processing，再执行 ai-stylize：调用图像模型完成主体提取和拼豆风格化。
3. rasterize-bead-pattern 将风格化图片栅格化到目标尺寸，限制颜色数量并映射到 MARD 调色板。
4. mark-completed 保存结果对象和 completed 状态；任一步骤失败时，统一写入 failed 状态和可展示的错误信息。

每个步骤都有独立名称、输入输出对象和日志上下文，便于重试单个阶段、定位失败原因、查看任务进度，并让前端通过 queued、processing、completed、failed 状态稳定地轮询结果。

解决线下制作的所见即所得痛点

普通豆图主要回答“每个位置应该怎么拼”，却无法告诉用户完成熨烫后会呈现什么样的表面质感。在线下制作中，用户往往要等到摆豆、加热、压平之后，才知道摆豆预览和最终成品之间的差异；一旦比例、颜色或烫法不合适，返工成本很高。

Bead 把摆豆、毛巾烫、澡巾烫、蒸布烫和华夫格烫放进同一套 3D 预览中，并提供光照与磨砂调节。用户可以在动手制作前先比较不同烫法下的立体轮廓、孔洞、阴影和表面纹理，从“知道如何拼”进一步变成“知道做出来会是什么样”。

界面截图

以下截图展示同一份拼豆作品在不同视口下的实际布局。

主题

应用支持跟随系统、浅色和深色三种主题，可在“设置”中随时切换。下面的作品首页、编辑器与 3D 预览截图均使用浅色主题。

外部视图：画布编辑器

桌面端保留完整的顶部操作栏和右侧颜色索引/色板；移动端将主要操作压缩到顶部，并把颜色选择与画布工具放到底部面板。以下两张截图均为浅色主题。

桌面端	移动端

内部视图：3D 预览

3D 预览会根据当前模板渲染不同颜色的豆子。桌面端设置面板固定在右侧，移动端设置面板位于画布下方并可折叠。以下两张截图均为浅色主题。

桌面端	移动端

工作流

1. 在“作品”中选择画布尺寸，创建新的拼豆作品。
2. 从图片生成图案，或导入已有模板；在画布中用画笔、橡皮、混豆和吸管完成细节调整。
3. 使用颜色索引和统计信息核对用色，再导出图案图片或模板文件。
4. 打开 3D 预览，比较摆豆、毛巾烫、澡巾烫、蒸布烫和华夫格烫的成品效果，再调整光照与磨砂效果。

Monorepo 结构

Bead 是一个由 Bun workspaces 与 Nx 管理的 TypeScript monorepo。仓库将可运行应用放在 apps/，将共享领域逻辑和 UI 放在 packages/，多个应用共享同一套画布、颜色、模板和组件能力。

apps/client   # 拼豆编辑器：画布编辑、图片生成、模板和 3D 预览
apps/site     # 产品站点
apps/api      # API、AI Agent 服务与 Inngest 任务
packages/core # 画布、颜色、模板和导出等共享逻辑
packages/ui   # 共享 UI 组件

运行

环境要求：Node.js 20+，以及 Bun。

bun install

• 只体验拼豆编辑器：bun run dev:client
• 同时启动 client、site 和 api：bun run dev:all

打开 http://localhost:5173 进入编辑器。在“作品”中创建或打开项目，也可以从编辑器顶部导入 .bead.json 文件继续编辑。

跨端实现

apps/client 是主要的交互应用，负责画布编辑、AI Agent 入口、3D 场景和本地作品管理。apps/api 提供 AI 图片流水线、对象存储和 Inngest 任务；Capacitor 以 client 的构建产物作为 WebView 内容，并提供原生平台接入层：

• iOS 与 Android 使用同一套 React UI 和业务逻辑。
• 文件系统能力用于保存和读取作品资源。
• 分享能力用于把生成的图案交给系统分享面板。
• 媒体能力为移动端的图片导入与导出提供适配。

模板格式

模板是 JSON 文件，包含版本、画布尺寸、调色板、扁平化的 beads 数组以及可选的统计信息。beads 数组长度必须等于 rows × cols，每个单元格可以是 null 或带有 code 与 hex 的颜色对象。项目会在导入时拒绝尺寸不匹配、颜色代码未知或 hex 不一致的文件。

技术栈

TypeScript、React 19、Vite、TanStack Router、TanStack DB、Three.js、Konva、Tailwind CSS、Radix UI 和 Bun workspace。