我了个豆从零开始详细教程：把照片变成拼豆图纸，顺手核完库存和报价-二楼后座

拼豆这件事，圈外人看到的是”把图拼出来”，真正做过的人知道：图纸做出来，只是第一步。

接下来你还要确认一堆更烦的事——做多大？用几种颜色？每种要多少颗？店里的豆够不够？缺了一种颜色，能不能换？换完以后，价格和备料单还对得上吗？

「我了个豆」（wolege-dou）就是冲着这串问题做的：一个跑在你自己电脑上的开源工具，把「图片 → 拼豆图纸」和「已有图纸 → 库存检查 → 换色候选 → 备料表 / 报价表」这两条链打通。

它有两个很不一样的入口，本文会一条条讲清楚：怎么装、怎么跑、参数怎么设、哪些地方必须人工拍板、以及一个很容易踩的坑（图片入口里的 P01、P02 不是真实品牌色号）。

先说结论：它不接任何外部生图大模型，不需要 API Key，原图只在你本机内存里处理，应用不保存原图。但它也不是「随便传张照片就能自动接上门店库存」——两个入口的数据要求完全不同，这一点后文会展开。

一、我了个豆是什么？一句话：把照片变成”能照着拼”的图纸

它的官方定位是「本地拼豆出图、库存检查与报价 MVP」。注意最后两个字：MVP。作者写得很直白——这是本地能跑的技术验证版本，不是已经验收的门店生产系统。

功能上分两块，正好对应两类人：

入口	你提供什么	得到什么
图片出图	JPG / JPEG / PNG / WebP 图片	拼豆预览、参考配色、总颗数、逐色数量、网格 PNG、分页 PDF、完整 ZIP
已有图纸：库存与报价	品牌色号图纸、色卡、库存、计价规则、订单偏好	用豆需求与库存检查、缺货清单、换色候选、人工批准后的备料表、报价表、生产资料包

它和”AI 生图”不是一回事，这是刻意的

作者在说明里特别强调了一句：工作流里完全不必要接入 API 生图，照片入口也不调用外部图片大模型。

这带来两个直接好处：一是不用买 Key、不用部署模型，装完就能用；二是原图不出本机——图片在你本机服务的内存里处理，应用本身不保存原图（当然，你导出的图纸、配色和数量仍然可能带用户内容，该自己存好的还是要存好）。

为什么它坚持”不让模型猜数”

架构上有一句我挺认同的话：产品保持单 Agent 架构；出图、色差、颗数、库存、工时、金额与验证，全部由确定性代码处理，不让语言模型猜数。

说白了就是——算法该算的用算法算，模型不参与”大概多少颗”这种必须精确的事情。每一组导出都以 canonical_result.json 为唯一事实源，所以不会出现”预览是一个版本、下载下来又是另一个版本”的情况。

二、两个入口，分别解决两类人的问题

很多人第一次用会混淆这两个入口。它们的输入要求完全不一样，我拆开讲。

入口一：图片出图（照片 → 图纸）

这个入口最直观：传一张主体清晰、背景简单的图，设定横向格数、纵向格数和最多颜色数，点「生成拼豆图」，你就能看到拼豆预览、总颗数，以及每一种颜色各要多少颗。

确认效果后可以下载三样东西：带参考编号的网格 PNG、分页 PDF，或者完整的图纸包 ZIP。

作者演示时的参数是 32×80 格、2560 颗、24 色。顺便说一句，他特意注明：那是图纸结果，不是已经做好的实物，更不是客户收益案例。

入口二：已有图纸 —— 库存与报价

如果你手上已经有绑定品牌色号的图纸，再补上品牌色卡、门店库存、计价规则和订单偏好，它就能替你干这几件事：

检查用豆需求与库存，算出够不够
列出缺货的颜色
给出换色候选
人工确认后，生成备料表、报价表和生产资料包

换色可以按三种偏好来排：偏向接近原配色（closest）、优先消耗现有库存（inventory_first）、或者优先压低材料成本（lowest_cost）。但注意，候选只是给你比较的，它不会替你直接改掉顾客的图。

两个入口的关键差别

	图片出图	已有图纸：库存与报价
输入	一张图片	图纸 + 色卡 + 库存 + 计价规则 + 订单偏好
输出	图纸、配色、颗数	库存检查、换色候选、备料表、报价表
要不要品牌色号	不需要（用的是参考编号）	必须是品牌色号
能不能直接用于采购	不能	人工确认后可以

⚠️ 这里就是那个最容易踩的坑：图片入口里出现的 P01、P02，是这张图内部的参考编号，不是任何真实拼豆品牌的色号，不能拿去直接采购。普通照片想进入品牌生产流程，得先完成品牌色号匹配和核对。

我了个豆的两个入口：左侧图片出图（原图、图纸、颗数），右侧色号需求与库存检查、报价流程

三、本机跑起来：三条命令（macOS / Linux）

先说环境：Python 3.11 或更高版本。除此之外没有别的硬要求，依赖联网装一次，装完应用本身可以完全本地跑。

把源码下载解压后，进入那个包含 README 的目录，然后：

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-public-lock.txt
sh scripts/python.sh -m wolege_dou.cli serve --host 127.0.0.1 --port 8766

然后浏览器打开 http://127.0.0.1:8766/ 就能看到界面了。终端要一直开着，按 Ctrl+C 停止。

如果 8766 端口被占用，把命令里的 8766 换成 8767，浏览器地址同步改掉即可。

三个容易被忽略的细节

细节	说明
别只复制 Python 包	它交付的是完整源码目录的运行方式，不是能独立安装的 wheel。请保留 `src/`、`web/`、`config/`、`data/fixtures/` 这些目录
Python 运行时的选择顺序	脚本按 `WOLEGE_PYTHON` → 项目 `.venv` → 可选工作区 Python → 系统 `python3` 的顺序挑。想指定就用 `WOLEGE_PYTHON=/绝对路径/python`；工作区 Python 可用 `WOLEGE_BUNDLED_PYTHON` 覆盖
Windows 还没验收	作者明确说了：Windows 尚未完成运行与视觉验收，可以自己建虚拟环境、装依赖、把 `PYTHONPATH` 指向源码的 `src` 目录，再跑同样的模块方式。项目不宣称所有平台都已通过验收

四、第一次出图：参数到底怎么设

界面上的可调项就三个：横向格数、纵向格数、最多颜色数。范围如下：

参数	范围	默认	影响
横向格数	16 ~ 96	48	越大越精细，也越费豆
纵向格数	16 ~ 96	48	同上
最多颜色数	2 ~ 32	16	越少越好备料，但损失渐变和细节
文件大小	最多 8 MiB	—	超了要先压
图片像素	最多 2000 万像素	—	超了要先缩

减少格数或颜色一定会丢细节，而且改完参数必须重新生成，预览不会自动跟着变。

两种构图模式，别选错

完整保留：保持原图比例，多余的地方留白。想完整还原画面就选它。
铺满：按目标格数裁切填满。想画面撑满底板就选它，代价是边缘会被裁掉。

还有两个关于”豆”的细节，做报价的人特别容易算错：

透明部分和构图留白不计豆——所以带透明通道的 PNG 不会虚增颗数。
但照片本身的白背景仍然会生成白豆——一张白底产品图，背景那些格子是要真豆子填的。算成本前记得把这块考虑进去。

另外要提前知道：它不提供自动抠图、文字生图、无图创作。想让出图好看，原图本身得拍得干净——主体清晰、背景简单，这一步没有捷径。

五、库存与报价：要准备哪 5 类文件

展开「已有图纸：库存与报价」后，你要提供完整的 5 类文件。缺一类都会卡住：

类别	格式	内容要点
图纸	JSON、带元数据 CSV，或 PNG + 显式色号 mapping	必须绑定品牌色号
色卡	CSV / JSON	需要带 LAB、版本、来源、证据类别
库存	CSV / XLSX	以颗为单位，含预留、安全库存、单价、货位
计价规则	JSON 或受限 YAML	不得省略真实业务参数
订单偏好	JSON	在 `closest` / `inventory_first` / `lowest_cost` 里主动选

字段定义看仓库里的 docs/INPUT_CONTRACTS.md 和 docs/DATA_DICTIONARY.md。

两个必须人工拍板的地方

这一点作者写得很克制，我觉得也是最值得称赞的设计：

换色需要人工确认。系统给候选，人决定换不换。
最终价格需要单独批准，而且批准是绑定当前输入与当次报价的——输入变了，批准就失效。

只有走完这两步，才能生成生产资料包。而且要记住：包生成 ≠ 库存已扣减。它不自动扣库存、不收款、不采购、不退款、不发布、不发送资料。它负责整理和计算，人负责确认和执行。

⚠️ 仓库里 data/fixtures/evals/E01 那些示例，evidence_class 全部是 SYNTHETIC（合成数据），只能用来测试，绝对不能拿去给真实顾客报价。

六、授权：这不是”随便商用”的开源

这一条必须单独拎出来说，因为它和大多数人的直觉相反。

它采用的许可证是 PolyForm Noncommercial 1.0.0——不是默认允许自由商用的标准开源许可。

场景	能不能用
个人学习、自己出图玩	可以（符合 LICENSE 允许的用途）
门店经营、收费服务等商业使用	需要另行取得书面授权，先联系作者

用作者的原话说：这里说的是”源码公开”，不是默认允许自由商用的标准开源。如果你是想拿它开店或做付费服务，务必先去看仓库里的 LICENSE 和 COMMERCIAL_USE.md，再决定要不要联系授权。

七、自检与已知限制

想确认自己这套环境跑起来没问题，执行一条命令：

sh scripts/verify_public.sh

它会重跑单元测试、集成 / HTTP 测试，以及 E01 ~ E10 的合成评测。它不读取旧机器的 PASS 记录，也不要求已有服务在运行——输出落在本机 artifacts/，不会提交到仓库。

几个诚实的”没做完”：

两项旧操作指南的字体测试在缺少 macOS Arial Unicode 字体时会明确跳过——跳过不能算通过。
Linux / Windows 上中文 PNG 与 PDF 的字体显示，尚未完成跨平台视觉确认。项目不打包系统字体，PDF 阅读器本身也会影响中文显示。
技术测试通过只证明当次源码的行为，不证明实物效果、真实库存准确、商家收益，也不代表生产发布批准。

安全边界：别把它挂到公网

这一点作者写得很硬：

服务只绑定 127.0.0.1 这类回环地址，不要接公网反向代理、隧道或远程共享。
它没有真实登录、没有门店角色隔离、没有多店 SaaS、没有公网服务防护。

所以正确姿势就是：自己电脑上跑、自己浏览器开。不要图省事把它放到服务器上对外提供服务。更多规则见 docs/SECURITY_AND_PRIVACY.md，第三方声明见 THIRD_PARTY_NOTICES.md。

八、常见坑与排查

这几个是我觉得最容易卡住人的地方，按踩到的频率排：

现象	原因	怎么解
浏览器打不开 `127.0.0.1:8766`	终端被关了，或者端口被占用	终端必须一直开着；端口占用就把命令里的 `8766` 换成 `8767`，地址同步改
命令跑起来报找不到模块 / 页面缺样式	只复制了 Python 包，没保留 `web/`、`config/`、`data/fixtures/`	必须保留完整源码目录，它不是能独立安装的 wheel
改了格数或色数，预览没变	参数改了但没重新点生成	每次调参后都要重新生成，预览不会自动跟随
拿着 `P01` 去下单买豆	把它当成了品牌色号	`P01` 只是这张图的参考编号，采购前必须先做品牌色号匹配
算出来成本偏低，实际差不少	白底照片的背景也占了格子	照片自身的白背景会生成白豆，只有透明区和构图留白才不计豆
拿仓库里的示例数据试报价	那些是 `SYNTHETIC` 合成数据	只能用于技术验证，不能对真实顾客报价
想把它放到服务器上给同事用	它没有登录、没有权限隔离、没有公网防护	只绑回环地址本机用，不要接公网反代、隧道或远程共享

九、高频问答

Q1：要联网吗？要买 API Key 吗？

装依赖那一步要联网，之后就完全本地跑了。不需要任何 API Key，也不需要部署模型。

Q2：我的原图会被上传到别的地方吗？

照片入口不调用外部图片大模型，图片在你本机服务的内存里处理，应用本身不保存原图。但要注意：你导出的图纸、配色和数量仍然可能带用户内容，该自己保管好的还是要保管好。

Q3：能自动抠图、或者用文字直接生成图吗？

都不能。当前版本不提供自动抠图、文字生图、无图创作。想出图好看，原图得是主体清晰、背景干净的那种。

Q4：支持多大、什么格式的图？

JPG / JPEG / PNG / WebP，单张最大 8 MiB、最多 2000 万像素。格子宽高各 16～96，颜色数 2～32。

Q5：它能自动扣库存、收款吗？

不能，而且是刻意不做。它不自动扣库存、收款、采购、退款、发布或发送资料。生产资料包生成出来，不等于库存已经扣减——它负责整理和计算，人负责确认和执行。

Q6：我能拿它开店收费吗？

需要先取得书面授权。它用的是 PolyForm Noncommercial 1.0.0，属于”源码公开”，不是默认允许自由商用的标准开源。个人学习和自己出图玩没问题，门店经营、收费服务要走商业授权咨询。

Q7：测试全绿就代表可以给客户用了吗？

不代表。技术测试通过只证明当次源码的行为，不证明实物效果、真实库存准确、商家收益，也不代表生产发布批准。作者自己写明当前是本地技术 MVP，门店流程和实物效果尚未完成验收。

十、说点实在的：它现在值不值得你折腾

我的判断分三种情况：

你的情况	建议
只是自己拼着玩，想把照片变成图纸	值得试。本地跑、不花钱、不传图，出图加颗数统计这块已经能用了
开拼豆店 / 接定制单，想理清库存和报价	可以先摸流程，但别直接上生产。它需要你先把色卡、库存、计价规则整理成规定的文件格式，这是笔前期的活；而且作者自己说了门店流程尚未验收
只想”传张照片就自动出报价”	现在的版本满足不了。两个入口数据要求不同，照片要进品牌流程必须先做色号匹配