拼豆网站技术方案

这份方案说明拼豆工坊本机版的当前实现，以及后续云端网站规划。当前顺序为：导入图片 → 选择“免费试用”，或点击“精准生成”设置背景与风格后再开始准备 → 准备完成 → 选择格数与用色 → 本机生成并直接进入编辑器。精准生成仅在点击“开始精准生成”后调用Seedream与Seed Evolving各一次；免费试用完全在本机自动去背景、零API。调格数/用色、生成、编辑、撤销与重做不追加模型调用；格数、色号和数量均由本机程序确定。

文档更新：2026年10月30日。本机版包含精准生成的自动去背景开关（默认开启）、卡通/写实风格（默认卡通）、原图描线色匹配、MARD 221色社区参考、两次模型准备、直接出图、编辑与高清PNG/SVG/CSV/JSON导出。生成后联合更新素材和网格，不弹采用框，可联合撤销与重做。用户已放弃直接像素重绘的试验，本次未接入默认流程。PDF分块打印、原厂校准色卡、云端数据库和额度管理尚未实现；标注“规划”的内容不代表已经上线。当前操作见两次准备接入说明 （本地文件：docs/两次准备接入说明.md），旧版回执见历史证据索引 （本地文件：docs/完整模型接入说明.md）。

本次调整：精准选项与高清PNG

选择免费试用时，本机通用边缘多色算法自动去背景，直接准备素材，不查询API；复杂背景可能残留。点击精准生成只展开两项设置：自动去背景默认true，生成风格默认cartoon、可选realistic。点击“开始精准生成”才提交Seedream一次素材整理、Evolving一次区域保护与条件配色计划。卡通沿用原有无阴影二维平涂方案；写实保留真实脸型、五官比例、自然肤质与材质质感，适度合并杂色，不强制卡通化或像素化。背景关闭时保留完整原场景，不执行强制透明，也不把画面补成矩形边框。准备后才选50/100/150格和8/12/16色，生成直接更新编辑器与素材。

区域编号、蒙版和坐标对应Seedream素材；原图用于描线检测和显示，不与素材区域混用。Evolving不接收最终格数、预算或用豆统计，没有看过后来生成的最终图纸。缓存素材、原图匹配描线HEX和条件计划独立于格数/用色及编辑，同页调参后可零模型调用重生成。换图、导入其他项目、切换方式、修改去背景/生成风格或修改连接使准备失效，并停止旧准备后续阶段。草稿保存完整原图origin，刷新不保存prepared计划，重新精准生成以完整原图为输入。

PNG下载默认由Chart.toSVG(project,{scale:2,highDefinition:true})栅格化，50格宽3040像素、100格宽5840像素，格内色号更大更粗，格线对比增强。150格或更大图纸按6400万像素、长边10000像素上限自动控制实际倍率；文件放大不增加豆格数、不补回五官细节、不重新调用模型。SVG继续默认矢量导出。本次选项与高清导出仅做受控接口/本机验证，没有新增写实或保背景真实调用；最终验收记录为docs/精准选项高清验证.json。

颜色候选采用 MakeBead 发布的MARD221社区数据，固定版本并保留 CC BY4.0 署名；不宣称原厂RGB或实物校准。数据来源与许可。单图预算8/12/16色，实际颜色可能更少。透明空白与白色材料分开；每格色号与用豆数均来自最终数组。

主流程仅使用两个字节模型：doubao-seedream-5-0-flash-260915一次，doubao-seed-evolving一次，共用本机服务内存中的方舟API Key。主界面不再要求主体分割服务或AK/SK，也不调用saliency_seg或layer_decomposition。参数建议、自然语言操作、独立质检和制作教程属于后续界面规划。

历史实测与兼容能力

上一版“默认去背景、卡通平涂、直接出图”曾取得两份真实成功回执：Seedream任务462d90cb-5b4a-40a0-8ff6-0f2ff971dc58、Evolving任务c8d20121-109c-40ff-bf02-013524342d50。实际模型调用与最终回放分开记录；历史Seedream回执 （本地文件：docs/自动出图实测/精准-Seedream回执.json）、历史Evolving回执 （本地文件：docs/自动出图实测/精准-豆包方案回执.json）均为succeeded。这些回执不证明本次新增写实或保背景组合的实际效果。

最终本机回放 （本地文件：docs/自动出图实测/最终校验/最终验证.json）的执行模式为offline-replay-of-saved-successful-provider-results，复用上述真实产物，新增provider请求0次。最终免费50×50/上限12色为11色806颗；精准50×50/上限12色为10色808颗；精准100×100/上限8色为8色3375颗。本轮三种图纸的统一轮廓均为原图匹配的H5 #48464e。免费API0、调参请求0、采用弹窗0，直接更新编辑器与素材；底部图例按实际网格统计。这不是又一次完整付费调用。

该历史卡通提示要求去除阴影、渐变、高光、投影与杂色，不要拼豆颗粒或立体质感，并保留固有色、五官与姿势；实际素材仍有少量衣褶暗面和头发高光，不能称绝对无阴影或完美平涂。原图与素材预览供用户查看，图纸直接生成，无确认弹窗。

两种方式均从原图去底后的描线证据检测颜色，匹配最近MARD并缓存其HEX；最终轮廓统一为该颜色，计入预算且protected，不固定H7黑。MARD是社区近似色，不能保证与原图RGB或实物豆完全一致。

上一版两次准备记录在docs/两次AI实测：当时需对照采用，50格为7色829颗、100格为8色3495颗，素材仍有拼豆颗粒。这些历史数字和回执仅用于追溯，不作为当前自动出图版本的验收。上一版两次验证 （本地文件：docs/两次AI实测/两次准备验证.json）。

历史兼容能力：后端保留火山视觉统一Key接口和AK/SK签名的CVProcess路径，以及旧版造型与两阶段语义接口，主界面已隐藏独立入口。旧版四次模型调用、后续新增两次VLM复验和零新增调用回放，均保留在docs/完整模型实测；793颗/12色/356保护格仅属于旧样本，不是当前自动出图统计。旧版首轮 （本地文件：docs/完整模型实测/完整流程验证.json）、旧版中间复验 （本地文件：docs/完整模型实测/复验/复验验证.json）、旧版最终回放 （本地文件：docs/完整模型实测/最终校验/最终验证.json）。

本机自动合并使用CIELAB欧氏距离24限制，逐个来源→目标颜色配对校验；距离过大保留原色，混合规则仅应用合格配对。保护格、放豆位置和颜色预算均单独检查。历史72格中间结果曾出现红发并黑、黄领口并橙的语义误判，保留为问题复现记录；颜色更少、改动更多都不是质量评分。

“模型实测 · 50格”打开的是保存的旧版对照，本次0次模型调用，不代表当前自动出图流程。历史自动出图回执、素材和图纸记录在docs/自动出图实测；上一版两次准备、早期四次模型流程和人工蒙版均保留历史标签。

1 目标和首版范围

用户完成一次操作后，应获得三项结果：能看懂整体效果的预览、能逐格照着拼的图纸、能准备材料的分色清单。

1.1 转换入口

两种方式在准备好后显示同一套格数与用色选项，默认50×50、12色，固定MARD社区参考。精准入口额外提供背景与风格设置，免费仍自动本机去背景。最终生成直接替换编辑器中的素材和项目，联合撤销/重做恢复两者；格数/用色变化和编辑不清除准备缓存，也不重调AI。

1.2 首版功能

• JPG、PNG、WebP 单张静态图片导入；文件最大 10 MiB，实际解码不超过 2000 万像素。

• 界面提供50×50、100×100、150×150预设。格数与导出图片像素数分别计算；自定义格数界面尚未提供。

• 保持比例居中，默认留白2格；去背景素材先紧裁透明主体，自适应描边可能在主体外补1格。描边使用原图检测并匹配到MARD的颜色，受预算与保护约束；保留背景时保留原场景，不给完整画面补矩形轮廓。手动裁剪与留白调节属于规划。

• 8、12、16色上限，默认12色；两个生成入口固定使用MARD 221色社区参考。历史P01—P16示例仍可查看。MARD不是原厂实测或认证色卡。

• 单格画笔、橡皮、取色、整色替换、指定色高亮、撤销与重做、缩放与拖动画布。

• 当前显示原图与准备素材预览；最终生成直接进入编辑器，不弹配色前后采用框。历史保存样例仍可能展示独立抠图及旧对照，明确标注旧版。编辑器可开关网格与色号。

• 本地自动草稿、项目JSON导入导出、高清PNG、SVG、用豆CSV导出。PDF分块图纸尚未实现。

当前为本机工具，AI使用用户在本机填写的凭证。邀请码、多人协作、作品社区、材料购买、支付和跨设备同步属于后续规划。

2 总体架构和技术栈

当前实现采用原生JavaScript、Canvas 2D及Node.js内置HTTP服务。转换、编辑、统计和导出在浏览器完成；本机后端保存内存凭证、校验请求并串行调度模型。队列和结果仅在服务内存，浏览器草稿保存在IndexedDB。各入口最终使用同一网格数据结构。

以下架构图与选型表为未来云端网站规划，当前本机版没有PostgreSQL、对象存储、邀请码或云端额度账本。

pg-boss 使用 PostgreSQL 管理后台队列，首版可复用同一个数据库。官方仓库 pdf-lib 支持绘制文字和矢量图形并嵌入字体，适合按格绘制打印图纸。官方文档

具体依赖版本在开工时锁定到锁文件，并记录 Node 运行时版本；本方案不把未验证的版本号写成兼容性承诺。

3 图像模型接入

3.1 首版供应商

当前Seedream模型ID为doubao-seedream-5-0-flash-260915。请求使用1K、PNG、单张输出，去背景时才携带透明背景参数；本机服务维护任务状态。既有卡通＋去背景方案的历史真实成功回执不代表新增写实或保背景组合已实测，也不保证绝对无阴影或完全保真。火山官方图片生成教程

接入方式：POST https://ark.cn-beijing.volces.com/api/v3/images/generations。适配器配置 model、prompt、image、size、output_format、response_format；首版一次只请求一张结果，默认从 1K 档开始测试。最终请求结构以该供应商当前接口契约测试为准。

模型供应商按用户要求统一为豆包和字节，应用不接入其他厂商的模型。

“精准生成”编排Seedream一次联合素材准备与Evolving一次区域保护和条件配色，不发起独立主体分割或第二次VLM。两个模型共用本机服务内存中的方舟API Key；免费试用无模型依赖。旧处理器只保留兼容，不向主界面暴露AK/SK或独立模型功能，不自动换模型或重发请求。

3.1.1 当前：一次素材理解与条件配色

调用 POST https://ark.cn-beijing.volces.com/api/v3/chat/completions，使用 image_url 图像输入与严格 JSON Schema 输出。stage: "plan"一次输入Seedream素材、原素材编号图、区域描述和MARD色卡，输出完整区域语义标签、protect标记及条件局部规则。请求不含最终gridSize、maxColors、analysis、usedCodes或counts；模型不知道用户稍后选定的参数，没有看过最终网格。图片理解、结构化输出。

程序拥有固定区域蒙版和编号，模型不能新增坐标。候选是连通色块，可能把一个部位拆成多个区域；标签属于模型判断，不能视为精确语义分割。图片内文字不作为操作指令。

每条规则为regionId、fromCodes、toCode、reason。来源色须在该原素材区域paletteCodes中，目标色须在本次色卡中；提示最多12条，解析硬上限64条。区域保护必须完整覆盖，按同次protect标记逐条隔离受保护区域、未知色号和无效来源规则。全局格式或敏感信息错误整批拒绝。最终本机生成后才按真实格子匹配条件，依据原始网格独立执行，避免A→B、B→C链式替换；并检查保护、占位、预算与色差24。

前端显示两次准备进度、实际模型与任务号，成功后缓存素材、原图描线HEX和计划，再显示参数。Evolving失败可查看已完成素材，但不能当作完整计划继续。换图、切换模式、修改背景/风格和改连接清除准备；格数/用色、编辑、联合撤销与重做不清除同页缓存。旧analyze/rules两阶段接口仅供兼容。

3.1.2 当前：联合素材准备与本机最终生成

精准入口先显示去背景与卡通/写实设置；点击“开始精准生成”才串行完成一次Seedream、一次Evolving，用户再选参数并生成。素材和编号同源，程序拥有编号、蒙版、索引与最终网格。material-plan.js保存区域几何及MARD映射，后续以当前格数/用色和缓存描线HEX重新计算，再执行条件计划；编辑、撤销和重做不重做准备。生成成功直接联合更新网格和素材。

当前style=bead-combined新增removeBackground布尔值（默认true）和renderStyle（cartoon/realistic，默认cartoon）。去背景时输入与输出要求alpha PNG，并发送background=transparent，前端加透明边仅为格式准备，输出仍检查实际透明和有效主体。保留背景时输入可为PNG/JPEG/WebP，不发送透明背景参数，输出接受普通RGB或RGBA PNG，尺寸边长14至4096。非法字段/类型在付费前拒绝。规范化选项纳入幂等，省略与显式默认一致，改变任一项而复用同一键返回409。/api/preparation-status新增optionsVersion=precise-options-v1、supportsBackgroundChoice=true和风格列表，旧服务不应静默忽略新设置。详见选项接口 （本地文件：docs/精准生成选项接口.md）。旧bead、faithful和simple风格保持兼容。

AI准备不接收最终颜色预算，后端先依素材区域验证条件建议。用户选参后，本机再依据真实网格执行颜色预算、区域和保护校验，并将自动替换限制为CIELAB欧氏距离不超过24；较大差异保留原色。这不是Delta E 2000，也不保证语义正确。混合规则只应用近色来源配对；空白、保护格和放豆位置保持不变，超预算或无匹配建议不强行应用。零格修改如实显示。

阶段显示任务号、安全诊断与实际模型；失败、未知或停止不继续后续付费阶段。最后生成直接进入编辑器，无弹窗和采用步骤；联合撤销/重做恢复对应素材与项目。既有卡通＋去背景历史记录见docs/自动出图实测；旧版样例仍可零调用查看，保留历史标签。

3.2 提示词模板

精准生成按卡通/写实与去背景选择使用固定提示，不把图片内文字当作指令，不让模型生成最终格子。模型固定，用户可以选择风格。下面仅为默认卡通＋去背景的约束摘要：

根据参考图生成适合拼豆转换的二维平涂人物素材。
保持人物数量、朝向、动作、发型、服装主色及原图裁切范围。
保留可识别的五官、姿势及材质固有色，移除渐变、高光、投影和光照阴影。
只画无阴影二维平涂，合并杂色，不画拼豆颗粒、凹孔或立体豆面。
沿用原图描线色，不擅自改成纯黑，使用清晰轮廓和有限连续色块。
完整保留原图中可见的手脚，不新增人物或道具。
人物居中；只输出造型素材，不生成网格、文字、色号或材料统计。
输入只是加了透明边的原图；同次提取主体、去除原背景并整理造型，主体之外输出原生透明。

“生成100×100”由程序保证单元数，不能靠提示词保证。模型先准备素材，本机后按参数生成并直接显示可编辑网格。模型不能保证完美保留细节；用户可查看预览、改格或撤销，不设置人工确认前置步骤。

3.3 供应商适配器

当前页面显示模型名称，凭证由本机服务内存管理，请求适配器只访问既定字节官方域名。下列统一接口为未来云端拆包设计，不是当前文件接口。

type ProviderInput = {
  sourceAssetId: string;
  sourceBytes: Uint8Array;
  promptVersion: string;
  prompt: string;
  model: string;
  outputSize: "1K" | "1.5K" | "2K";
};

type ProviderOutput = {
  imageBytes: Uint8Array;
  mimeType: "image/png" | "image/jpeg" | "image/webp";
  providerRequestId: string | null;
  resolvedModel: string;
  usage: Record<string, number> | null;
};

interface ImageProvider {
  edit(input: ProviderInput, signal: AbortSignal): Promise<ProviderOutput>;
}

这里的outputSize是规划中的内部质量档位。各字节能力适配器自行映射参数；结果URL只下载允许的官方HTTPS地址，base64限长解码，后续处理图像字节。

供应商结果URL可能过期。本机服务收到后立即读取并校验图像，不把外部临时URL当成永久项目内容；当前项目JSON不包含原始图片字节。

3.4 去背景

精准生成提供自动去背景开关，默认开启。开启时由Seedream联合去背景与所选风格整理；外围透明边仅是格式准备，不代表抠图完成，输出逐次检查实际alpha与有效主体，不透明或全透明空主体停止准备。关闭时要求保留原图背景和场景，不强制透明；背景颜色进入最终网格并计入用色与用豆，白底也作为白色材料，不等同于编辑画布的显示底色。不追加CV或拆层回退。

免费试用采用本机通用边缘多色算法自动去背景，零API，不提供精准入口的背景/风格选择；复杂场景可能残留或影响主体边缘，不能当作任意背景的完美语义分割。原图描线证据匹配最近MARD并缓存HEX；精准生成始终以完整原图送Seedream，不在旧AI结果上继续重绘。去背景素材保留主体轮廓，保留背景素材不把完整场景补成矩形边框。背景蒙版手工编辑器仍属规划。

4 图纸生成算法

4.1 图像和蒙版规范化

当前在浏览器Canvas中解码图片并规范化为PNG；导入素材最长边缩至1600像素后参与处理。本机服务再次检查实际格式、大小和相关尺寸，不直接信任扩展名。服务端Sharp、统一EXIF及色彩管理为云端规划。

透明格为“不放豆”，白色是合法材料颜色，必须与空白分开。当前alpha阈值为128，界面未提供阈值调节；不能把浅色像素统一删除。

清晰图纸先紧裁透明主体，以细分区域的真实颜色和局部线迹取样，再匹配参考色卡。普通旧转换保留原来的单点取样行为。显示像素图使用最近邻放大，不能把显示放大等同于图纸取样。

4.2 严格生成指定格数

宽 W、高 H、留白 p，人物有效区域为 w×h 时：

scale = min((W - 2p) / w, (H - 2p) / h)
imageColumns = round(w * scale)
imageRows = round(h * scale)
offsetX = floor((W - imageColumns) / 2)
offsetY = floor((H - imageRows) / 2)
cells.length = W * H

100×100格、p=2时，取样主体最长边最多占96格；50×50时最多占46格。清晰图纸自适应描边可在主体外补1格，仍在固定画布中。画布不随人物比例改变。完整模型流程会拒绝没有有效主体的模型产物；核心离线算法可返回空网格。

4.3 颜色数量与真实色卡

处理顺序为：采样颜色 → 在允许的品牌色集合中选择至多 K 个代表色 → 将所有非空格映射到这些颜色 → 生成网格和统计。

• 当前按材质色族聚合颜色，在CIELAB空间用欧氏色差选择参考色，并优先保留关键线迹和轮廓。Delta E 2000属于可选后续改进，不是当前实现。

• 代表色去重并重新分配后，实际用色数量必须不超过 K。不能只对完整品牌色卡逐格找最近色，否则会突破用户设置的颜色上限。

• 当前轮廓和细节色都计入K。轮廓使用原图证据匹配到MARD的缓存HEX，统一为该颜色并标为protected，不固定H7黑；自动规则不能改动轮廓格。保留背景的完整场景不补矩形外边框。用户手动锁色界面尚未提供。

• 当前不使用抖动，也没有抖动开关，以免增加交错色点。

• 当前取样不使用随机数，同一RGBA输入、色卡和参数产生确定的网格。

• K 是自动转换的用色上限。用户手动增加颜色时明确提示并更新实际色数；新增色写入项目快照并分配稳定索引，不能借色卡顺序解释。

• 生成 50、100、150 格版本时，从保存的素材重新采样；格数增加可以保留更多素材细节，不能恢复 AI 已简化掉的信息。

当前清晰图纸和完整协作使用MARD 221色社区RGB参考，保留MakeBead来源与CC BY4.0署名；旧转换和旧示例继续使用P01—P16自定义参考。两者均非原厂实测或认证。未来原厂色卡应从可核验且有授权的数据导入，不能从截图取色后标成品牌标准。

色卡记录 paletteId、version、brand、series、beadSize、beadPitch（如可靠来源提供）、sourceUrl、verifiedAt；每色有稳定 colorId、印刷色号、名称和屏幕参考 sRGB。项目嵌入实际使用颜色快照，色卡升级不改变旧图纸。屏幕预览不作为实物颜色一致性的保证。

4.4 可拼性检查

当前清晰图纸根据局部线迹保护细节，整理低对比孤点，自适应描边避免连接原本独立的部件；并未提供独立的断点高亮与修复面板。四邻接连通提示、补格和忽略操作为规划。数字连通也不能保证熨烫强度，细脖颈和单格连接需实物验证。

5 项目数据和编辑一致性

所有预览、统计和导出都从同一个 ProjectDocument 读取。图纸生成之后不再从预览 PNG 识别色号。

type ProjectDocument = {
  schemaVersion: 1;
  revision: number;
  name: string;
  width: number;
  height: number;
  cells: number[];
  palette: {
    index: number;
    code: string;
    name: string;
    hex: string;
  }[];
  meta: { paletteLabel: string };
};

强制约束：

• 项目规范化允许width与height为1～200的整数；界面转换预设为50/100/150。cells按行优先排列，长度严格为width×height。

• cells中0代表空白，非零整数引用palette中的index，每个引用必须存在。白豆使用非零索引。

• 内存可用 Uint16Array，项目 JSON 使用整数数组；不得用易变化的色卡顺序隐式解释旧项目。

• 数组下标为 y×width+x，内部坐标从 0 开始，界面和导出编号从 1 开始。

• totalBeads 等于非零单元数，各色数量之和等于 totalBeads；统计是派生值，不以用户上传的统计字段为真值。

• 临时参考色卡必须在界面和导出中显示“自定义参考色”，实际品牌版显示品牌、系列和色卡版本。

编辑使用“命令＋单元格差量”管理，撤销/重做恢复精确旧值，每次生效操作产生新的 revision。批量换色视为一个命令；颜色索引在项目内保持稳定。

导出启动时冻结一个 revision 的网格和色卡快照。用户继续编辑时，导出仍完成旧快照并明确版本，避免文件混入新旧数据。异步转换同样带 generationId，过期的计算结果不能覆盖用户的新编辑。

当前IndexedDB草稿保存项目、素材dataURL及完整原图origin。刷新可恢复原图与当前素材，不持久化prepared区域/计划；重新精准生成从完整原图开始，避免将旧AI素材当新原图。下载的项目JSON仍仅包含网格和色卡，不内嵌原图或凭证；导入后可编辑导出，重新准备需另选图片。生成直接联合更新网格与素材，撤销/重做保留对应快照。当前没有sourceDigest或云端同步；清理浏览器数据会丢失草稿，项目JSON可备份网格。

6 AI 后台任务和费用控制

当前本机任务状态为queued、running、succeeded、failed或unknown，共用单活跃请求队列。排队取消在发送前结束；运行中停止等待后，已发请求仍可能完成或计费。幂等键与请求内容、任务类型、相关模型或鉴权模式绑定，同一逻辑任务不自动再次发送。

主流程仅使用方舟API Key，只保存在服务运行内存；关闭或重启后，新准备任务需重填。旧兼容抠图路径的AK/SK也只保存在运行内存，但主界面不要求填写。页面关闭设置时清空凭证输入，不写入HTML、项目JSON、浏览器持久存储、日志或分发包。准备结果只在当前页面缓存；调参和编辑不发模型请求。以下数据库、额度预留、outbox及邀请码设计属于云端规划。

6.1 请求与状态

API 接受请求后返回 202 和 jobId，前端按 2 秒起步、最多 10 秒的间隔轮询。只显示已知阶段，不把等待时间编造成百分比。

queued → dispatched → storing → succeeded
queued → canceled
queued / storing → failed
dispatched → unknown
dispatched / storing → cancel_requested → canceled 或 succeeded

• queued：数据库已入队，尚未发送供应商。

• dispatched：外部请求开始，记录 attemptId、时间、可获取的供应商请求标识。

• storing：已拿到结果，正在下载、校验或转存；此阶段失败仅重试文件处理。

• unknown：请求可能已被供应商接收，但超时或进程中断导致结果无法确认。

• succeeded：自有存储中已有校验过的结果，并已在数据库提交结果素材 ID。

供应商调用初始超时设为 5 分钟，属于可调整的工程配置，不是生成时长承诺。Seedream 接口按当前同步生成模式处理，不假定存在通用查询 API。

6.2 幂等与恢复

POST /v1/ai-jobs 必须携带 Idempotency-Key。数据库对“ownerSessionId＋key”建立唯一约束，并保存规范化请求摘要。同键同内容返回已有任务；同键不同内容返回 409。

创建业务任务、预留额度、写入 outbox 在同一数据库事务提交。投递进程将 outbox 转发到 pg-boss，任务进程执行前再对业务任务状态做原子检查，避免重复消费触发重复发送。

队列可靠性不等于外部模型计费 exactly-once。供应商已接收但响应丢失时，不能安全保证只计费一次：

• 结果不确定进入 unknown，保留已预留额度，不自动重发，也不自动切换另一模型。

• 只有明确未被供应商受理，或供应商明确支持幂等/结果查询时，才按其契约安全恢复。

• 管理端可核查供应商记录后确认成功、失败或释放额度。

• 用户主动重新生成应作为新的调用，操作前说明会消耗一次新的额度。

取消排队任务可以释放额度；已经发送的任务只能请求停止后续处理，不能承诺免除外部费用。若结果随后到达，应转存后按状态决定保留或清理，避免错误地再次生成。

6.3 初始限额

建议试运行配置：AI 并发 2、每个邀请码累计 10 次、全站每天最多 100 次外部生成，均为可调整的产品参数。额度在数据库原子预留；本地页面状态或前端按钮禁用不作为计费控制。

以邀请码、会话和 IP 组合做限流，避免重建匿名会话无限领取额度。记录外部调用数、确认计费、unknown 数和成功可用结果数；设置日费用预算上限，计费规则未录入前，以调用次数硬上限控制开销。

7 接口与数据存储

7.1 后端接口

当前主流程接口为/api/preparation-status能力检查、/api/status、/api/config、/api/semantic-status、/api/semantic-config、/api/jobs的bead-combined风格和/api/semantic-jobs的plan阶段。任务统一通过GET /api/jobs/:id查询、POST /api/jobs/:id/cancel取消。写请求需本机同源Origin和JSON类型，模型任务需Idempotency-Key；语义任务携带X-Expected-Model避免配置变化时换模型，成功任务提供providerModel。旧cutout接口、旧造型风格和analyze/rules仅保留兼容，主界面不调用。

以下/v1接口、会话Cookie、数据库及对象存储规则为未来云端规划，不代表本机版提供公网会话或云端保存。

普通转换、本地项目保存、网格编辑和导出不需要这些后端接口。前端仅在用户选择 AI 并知悉原图会发送给外部服务后上传图片。

会话 Cookie 设置 HttpOnly、Secure、SameSite；跨站写请求校验 Origin，并使用 CSRF 防护。服务端始终从会话确定 owner，忽略客户端伪造的 owner 字段。

7.2 数据表

邀请码在数据库保存摘要；模型 API Key 由服务端密钥管理注入，不进入前端构建产物。首版不在服务端存完整项目网格，减少云端同步与个人数据负担。

7.3 资源限制与隔离

• 对格式按实际解码内容校验，不信任扩展名和浏览器声明；拒绝 SVG 输入、动画文件、损坏文件与超大像素图。

• 上传许可限制大小、对象 key 和时效；complete 必须再次验证。每个会话同时最多保留 3 个活动上传，未完成上传 1 小时后清理。

• 素材采用私有对象 key；读取、删除、任务查询都校验 ownerSessionId。签名下载地址默认 5 分钟有效。

• 云端原图和 AI 结果默认保留 24 小时，界面显示到期时间并支持主动删除；保留期间允许下载到本地项目。

• 不接受用户提供任意图片 URL 让服务器抓取。供应商结果 URL 只允许适配器认可的 HTTPS 域名，重定向后重新校验，禁止访问内网地址。

• 日志只记录任务 ID、状态、时间和必要计费信息，不记录原图 base64、密钥或带签名的下载 URL。

8 画布交互与导出

8.1 编辑器

当前在同一Canvas中绘制色块、网格和高亮，缩放足够清楚时显示格内色号。命中测试使用CSS像素坐标，绘制考虑devicePixelRatio。多层Canvas是后续性能优化选项。

网格按单元数据绘制，不为每格创建DOM节点。旧普通转换使用Worker并有本机回退；当前清晰图纸及规则计算在页面中执行，尚未全部迁入Worker。

手机支持缩放、拖动和点击改格；画笔模式与拖动模式分开。鼠标指针或触点旁显示当前“行、列、色号”，并为色块列表提供名称和数量文字。

8.2 文件输出

规划中的PDF详图分区为每页25×25格、单格5mm，使用全局坐标；100×100对应16页详图，另附总览和清单。分块色号至少7pt，长色号需换行或增大格子。这些尚不是本机版的导出能力。

图纸的 5 mm 是阅读布局参数，不表示对应材料的实际孔距。按实物 1:1 打印需要可靠的品牌板孔距、标尺和 100% 打印设置，放在后续独立功能中。

准备材料时可显示“实际数量”和“建议备料数量”两列。建议备料按 ceil(实际数量×1.05) 计算并标明 5% 余量；不能把余量加入实际总数。

当前导出先复制并规范化项目快照；PNG使用Chart.toSVG(project,{scale:2,highDefinition:true})在浏览器中栅格化，放大格内字号、字重与格线对比，受6400万像素/长边10000像素限制自动控制实际倍率。导出像素数增加不改变项目豆格数、色号或数量；SVG下载继续使用默认矢量布局。导出尚未迁入Worker，大图导出失败时仍可保存SVG或项目JSON，无需重新调用模型。

9 工程目录与模块接口

建议建立独立项目目录，现有演示素材只作为测试样本导入，不修改原稿。

apps/web/                 页面、Canvas编辑器、本地草稿、导出工作线程
apps/api/                 会话、上传许可、任务API、额度入口
apps/worker/              模型调用、转存、任务恢复、资源清理
packages/pattern-core/    网格规范化、降采样、限色、匹配、统计、连通检查
packages/project-schema/ 项目结构、输入校验、版本迁移、旧试版导入
packages/exporters/       PNG/SVG/PDF/CSV生成
packages/provider/        字节主体分割、Seedream、Seed Evolving适配器与错误归一化
packages/palette-data/    有来源的色卡与自定义参考色卡
tests/fixtures/           两份100格项目与边界样本
tests/e2e/                上传、转换、编辑、导出与任务异常流程

核心接口建议：

normalizeProject(input: unknown): ProjectDocument
convertToPattern(input: RgbaInput, options: ConvertOptions): ProjectDocument
getCounts(project: ProjectDocument): PatternCounts
applyCommand(project: ProjectDocument, command: EditCommand): EditResult
findComponents(project: ProjectDocument): Component[]
exportPattern(snapshot: ProjectDocument, options: ExportOptions): Promise<Blob>

上面的类型在各自包内统一定义。核心包只接收 RGBA、蒙版、参数和色卡，不读取 DOM、数据库或供应商 URL。浏览器解码器与 Sharp 解码器作为边界模块，避免在不同运行环境中各写一套颜色匹配算法。

已有试版 JSON 使用二维色号字符串；迁移时按色号建立稳定索引，空值转为 0，保留格子原值。回归测试以迁移前后的坐标及数量一致为准，不对原素材重新采样来比较字节。

10 验收与上线门槛

本次99项核心、126项后端、15项界面测试共240项通过。背景/风格组合使用受控接口响应，高清PNG经过实际界面下载核验；默认卡通离线回放 （本地文件：docs/精准选项高清验证/实测回放/最终验证.json）复用以前的两份真实产物、新增provider0，50格PNG为3040×3498、100格为5840×6298，高度随图例变化。免费API0、改格数/用色新增调用0、采用弹窗0。没有新增写实或保背景真实模型调用，不把旧回执当作新组合的生成质量证明；总验收记录为docs/精准选项高清验证.json。

上一版“默认去背景、卡通平涂、直接出图”曾取得Seedream及Evolving两份真实成功回执；历史最终验证 （本地文件：docs/自动出图实测/最终校验/最终验证.json）复用其保存产物离线回放，新增provider0。该历史样本免费50格为11色806颗、精准50格为10色808颗、精准100格为8色3375颗；当时轮廓匹配H5 #48464e，免费API0、调参请求0、弹窗0，94项核心、116项后端和8项界面测试通过。历史素材仍有少量衣褶暗面与头发高光，不能称绝对无阴影或完美保真。

上一版docs/两次AI实测的829/3495颗、7/8色与当时16界面/64核心/115后端测试均为历史结果，不能用来证明本次新增背景/风格设置与高清PNG行为。

旧版四次调用、后续新增两次VLM复验和零新增调用回放，保留在docs/完整模型实测。旧样本793颗/12色/356保护格及10色/72格误判中间结果，均不作为当前两次流程的证据；历史样例入口保留旧版标签。

以下为未来网站规划的验收目标，不是全部已经完成的测试结果。

10.1 固定样本

本次已生成的两份 100 格图纸可作为回归样本：

保留它们的 JSON、PNG、SVG 和 CSV 作为 fixtures。导入已有网格再导出时，数量和坐标必须不变。新算法重新转换素材可能产生不同结果，应单独记录，不能把旧数量当作所有新转换的标准答案。

10.2 自动化验收

1. 100×100 输出必须有 10000 个单元；横图、竖图、透明图均保持比例，空图有可读错误。

2. 白豆保留为非零单元，空白为 0；去背景不误删未选择的白衣和眼白。

3. 所有色号都来自项目色卡；自动转换实际用色不超过 K；自定义色卡不会被导出成品牌认证色卡。

4. 单格改色、擦除、整色替换、撤销、重做后，总数与逐色计数实时一致。

5. 导出时继续编辑，文件只能对应冻结的一个 revision；重新导入项目恢复精确网格。

6. PNG、SVG、PDF 和 CSV 的格子、色号、总数一致；PDF 页码、分块全局坐标、中文与长色号无缺失。

7. 连续 10 次提交相同幂等键，只产生一个逻辑任务和一次外部发送尝试；异键不能绕过额度原子预留。

8. 外部请求接收后超时、任务进程中断或网络断开，进入 unknown，不由队列自动产生第二次收费生成。

9. 模型成功但素材转存失败，只重试转存；供应商临时 URL 过期时有明确错误和恢复入口。

10. 其他会话不能读取、下载、删除素材或查询任务；损坏文件、过大图片、伪装扩展名被拒绝。

测试使用固定本地供应商桩，覆盖“明确拒绝”“响应丢失”“结果下载失败”；端到端测试不默认调用付费模型。

10.3 体验与模型验收

在约定的中档桌面设备与当前稳定版浏览器上，以 100×100、16 色为基准：普通转换 P95 目标不超过 2 秒，单格编辑与统计更新目标不超过 100 ms。200×200 转换目标不超过 5 秒。开工后记录测试设备和图片，实测再修订，不把服务商生成时间写成固定 SLA。

模型试验先使用本次两张图，再补充 8 张不同构图样本。每张最多生成 2 次，最多 20 次外部调用；评估动作/朝向保留、五官辨识度、手脚是否被裁掉、背景处理难度和生成后的杂色数量。邀请至少 3 名实际拼豆用户盲看，至少 8 张获得“愿意继续修图并制作”的判断，再考虑扩大 AI 入口。

正式推广前至少完成一次实物拼装和一次 PDF 打印检查。数字网格连通和统计正确不能替代实物可用性。

11 部署、监控与成本

11.1 试运行部署

前端静态资源独立部署；API 与任务进程运行在同一国内区域，连接 PostgreSQL 与私有对象存储。建议从 2 vCPU / 4 GiB 应用实例、AI 并发 2 起步，数据库采用独立持久存储或托管服务；这是起始配置，容量以实测决定。

API 和任务进程分开启动与重启。发布采用版本化镜像或构建产物，保留上一版；数据库迁移先备份、保持向后兼容。现有 deploy-project 部署技能在实施阶段另行读取，本方案不假定其目标服务器已确定。

11.2 监控

至少记录任务排队时长、外部生成时长、转存成功率、unknown 数、每张用户认可结果的调用次数、限额触发次数和浏览器导出失败率。素材日志不含图片内容。

队列积压、unknown 增加、日额度接近上限时提醒维护者；可通过 feature flag 关闭 AI 新任务，普通模式继续可用。定期测试数据库恢复，自动清理到期素材、悬空上传和失效 outbox。

11.3 成本算法

每张可用结果的AI成本
= 所有实际计费调用金额之和 / 用户确认可用的结果数

月总成本
= 应用与数据库固定成本
+ 对象存储和流量
+ AI实际调用费用
+ 额外分割服务费用（如启用）

具体单价从已开通账户的官方计费页导入配置，区分模型、输出尺寸和计费项目。当前没有可靠的同图测试账单，不给出“每张固定多少钱”的承诺。重新选择格数、改格子、换色和重新导出复用已有素材，不再触发 AI 生成。

12 开发顺序与交付

按 1 名熟悉该技术栈的开发者估算，首版约 12～18 个工程日，另预留色卡获取、账号开通和真人测试等待时间；属于工作量估算。

每个阶段应能单独演示。普通转换与导出先上线试用，再逐步开放 AI 名额；模型效果不达标时仍然保留可用的原图转换产品。

最先的 30 分钟任务：把现有马步和抬膝两份 100×100 JSON 放入测试样本，完成空白/白豆区分、总数断言和一个最小网格预览。这一步不需要模型密钥，可以先验证数据基础。

13 官方依据与实施前配置

• 模型能力、型号、请求与结果 URL 生命周期：火山 Seedream 图片生成教程。

• 字节主体分割：主体分割参数。

• Seed Evolving看图与结构化规则：图片理解、结构化输出。

• 图片缩放与比例保持：Sharp resize。

• 持久任务队列：pg-boss 官方仓库。

• PDF 绘制与字体嵌入：pdf-lib 官方文档。

模型接入前需准备对应供应商账户及额度，密钥只在服务器配置；有可靠来源的品牌色卡到位前，网站使用“自定义参考色卡”标识。部署服务器、对象存储桶、域名和字体授权在实施时落实，不影响先完成本地转换与编辑闭环。

完整模型接入说明与历史证据

更新日期：2026年10月30日。

当前主流程为“免费试用”或“精准生成”：免费试用在本机自动去背景；点击精准生成先展开自动去背景开关（默认开启）与卡通/写实风格（默认卡通），再点击“开始精准生成”才提交Seedream与Evolving各一次。准备完成后选格数与用色，点击“生成最终图纸”直接更新编辑器和素材，不弹采用框。操作和接口以自动出图与两次准备接入说明 （本地文件：docs/两次准备接入说明.md）为准；本文件后半保留旧版历史证据。

如何开始

1. 双击项目中的一键启动.bat，使用打开的本机网页。
2. 上传图片，选择“免费试用”或“精准生成”。免费试用无需Key、不查询API，自动本机去背景。精准入口只展开设置，不立刻提交模型。
3. 精准方式先在“豆包设置”填写方舟API Key，选择自动去背景与卡通/写实，再点击“开始精准生成”。卡通使用现有无阴影平涂方案；写实保留真实脸型、五官比例和材质质感，适度合并杂色，不强制卡通或像素化。去背景关闭时保留原背景与场景，不强加矩形描边。固定使用Seedream 5.0 Flash与Seed Evolving，不需要主体分割凭证或AK/SK。
4. 等素材准备完成，再选50×50等格数及8/12/16色上限，点击“生成最终图纸”。本机生成与后续调参均不再调用模型。
5. 生成后直接编辑或导出，不需要采用或确认；每次生成会替换当前图纸和素材，联合撤销、重做可一起恢复两者。

凭证只交给本机服务运行内存，重启服务后需要重新填写。保存设置不调用模型。不要把完整凭证发到聊天、截图或项目文件中。

准备素材、原图匹配描线HEX与条件计划缓存在同一页面，调格数/用色、编辑、撤销和重做后仍可复用，不重新调用AI。换图、切换方式、修改去背景或生成风格、修改连接或导入其他项目会使其作废，并停止旧准备的后续阶段。草稿保存当前素材和完整原图origin，刷新不保存准备计划；重新精准生成会使用完整原图，避免继续重绘上一张AI素材。

示例下拉中的“模型实测 · 50格”属于旧版流程，打开本身为0次调用；其中历史对照与采用交互不能代表当前直接出图行为，也不能证明本次新增背景/风格的实际效果。历史人工蒙版示例继续保留人工说明。

当前两次准备分别做什么

区域编号、蒙版和坐标都属于Seedream素材。Evolving一次理解原素材区域并提出条件建议，没有看过之后按用户参数生成的最终图纸。原图只供人工核对姿势和细节，不与素材坐标混用。主流程不再调用火山视觉；旧接口仅作兼容保留。

免费试用以本机通用边缘多色算法自动去背景，复杂场景可能有残留。两种方式均由原图描线证据匹配最近MARD并缓存HEX，最终可识别的轮廓使用该颜色，计入预算且受保护，不固定H7黑；保留背景的画面不补矩形边框，背景颜色进入网格并计入色数和用豆，白底也需要白色材料。MARD只是社区近似色，不代表与原图RGB或实物完全一致。

选项接口使用removeBackground布尔值和renderStyle: "cartoon"/"realistic"，默认true/cartoon；只允许bead-combined携带这两项。/api/preparation-status返回optionsVersion: "precise-options-v1"，前端在付费提交前确认服务支持。去背景结果须为alpha PNG，保留背景结果允许普通RGB PNG；幂等包含规范化后的背景与风格，省略和显式默认相同，任一选择改变而复用同一键返回409。详见精准选项接口 （本地文件：docs/精准生成选项接口.md）。

Seedream负责素材，不负责格子、材料编号、坐标或数量。50×50表示2500个单元，不代表2500颗豆；空白为不放豆，白色材料仍计数。50格不能保证保留全部五官。

失败、停止与直接更新

任一准备阶段失败、结果未知或用户停止，后续阶段不提交，也不自动重试、换模型或补抠图。已发送请求仍可能完成或计费，重新开始前先核对服务记录。已完成的素材可在阶段区查看，任务号与安全诊断可用于核对。

调整格数/用色或编辑格子不会清除本页面的素材、描线色与计划缓存，可再次本机生成；每次成功生成直接替换当前项目，想保留人工编辑可先导出或之后撤销。换图、导入其他项目、切换模式、修改自动去背景或生成风格、修改连接会清除准备，并停止旧准备的后续阶段。局部规则只匹配修改前网格，空白、保护格和放豆位置不变，不能超出用色预算；CIELAB欧氏距离24限制自动合并，较远色保留。无效建议显示原因，0格修改如实报告，手动改色仍可使用。

颜色更少或改动更多都不等于效果更好。生成后直接显示可编辑图纸及数量，不弹配色前后采用框；原图和素材预览仍可查看。计数正确不保证造型完全保真，用户可改格或联合撤销。

本次选项与高清输出验证

本次99项核心、126项后端、15项界面测试共240项通过。背景/风格组合使用受控接口响应；默认卡通离线回放 （本地文件：docs/精准选项高清验证/实测回放/最终验证.json）复用以前的两份真实产物、新增provider0，实际界面下载50格PNG为3040×3498、100格为5840×6298（高度随图例变化）。没有新增写实或保背景真实模型调用，旧回执不能证明新组合的生成质量。总记录见docs/精准选项高清验证.json。PNG默认高清2倍导出，色号更大、更粗，格线更清楚；150格或更大输出按6400万像素和长边10000像素上限自动控制实际倍率。PNG分辨率提高不增加豆格数、不补回五官细节，也不调用AI；SVG继续默认矢量导出。用户已放弃直接像素重绘的试验，网站默认流程没有接入该试验。

历史自动出图版本：真实调用与回放

上一版“免费试用/精准生成、默认自动去背景、原图描线色、直接入编辑器”的两次真实准备曾成功：Seedream任务462d90cb-5b4a-40a0-8ff6-0f2ff971dc58与Evolving任务c8d20121-109c-40ff-bf02-013524342d50。回执分别为历史Seedream （本地文件：docs/自动出图实测/精准-Seedream回执.json）和历史Evolving （本地文件：docs/自动出图实测/精准-豆包方案回执.json）。

该历史素材仍有少量衣褶暗面与头发高光，不称绝对无阴影。最终验证 （本地文件：docs/自动出图实测/最终校验/最终验证.json）已回读成功，执行模式为offline-replay-of-saved-successful-provider-results：复用上述两份真实产物，最终回放新增模型请求0次。

该历史样本免费50×50/上限12色为11色806颗，精准50×50/上限12色为10色808颗，精准100×100/上限8色为8色3375颗；三种图纸使用当时原图匹配的H5 #48464e轮廓。该版本免费API0、改参数新增请求0、生成采用弹窗0，直接入编辑器；图例按实际网格统计，当时94项核心、116项后端和8项界面测试通过。上述与下述更早统计均不能当作本次背景/风格及高清PNG选项的验证。

上一版历史：两次准备后确认采用

上一版两次准备验证 （本地文件：docs/两次AI实测/两次准备验证.json）记录一次Seedream和一次Evolving、约57.757秒。对应历史回执为联合素材 （本地文件：docs/两次AI实测/01-Seedream-回执.json）与区域条件计划 （本地文件：docs/两次AI实测/02-豆包方案-回执.json），当时仍需查看对照并采用，尚无本轮的自动出图和原图描线色行为。

上一版50×50、上限12色为7色829颗、改动10格、保护508格；同缓存100×100、上限8色为8色3495颗、0格改动、保护2033格，新增API0次。当时素材仍有生成式颗粒纹理。这些旧数字和文件保留原样，不能冒用为新版无颗粒平涂、自动去背景与统一原图描线的结果。

当前接口、缓存边界和原图恢复说明见自动出图与两次准备接入说明 （本地文件：docs/两次准备接入说明.md）。以下三节为更早的四次流程历史，末尾色卡和导出说明继续适用。

旧版历史：首轮四次真实调用

以下记录属于旧版“四次模型调用”流程。当前自动出图回执与最终回放在自动出图实测 （本地文件：docs/自动出图实测/最终校验/最终验证.json），上一版两次准备另存两次AI实测 （本地文件：docs/两次AI实测），三者不混作同一版本证据。

旧版主体分割曾通过AK/SK路径真实成功；早期401/50400属于当时开通与授权确认前的记录。这些历史结果不意味着当前主流程还需要主体分割或AK/SK。

完整四次调用的首轮回执状态均为succeeded：

首轮完整流程验证 （本地文件：docs/完整模型实测/完整流程验证.json）记录50×50、793颗、12色、局部改色0格。10条格式合格规则因12色预算已满未应用，另2条保护区域规则被隔离。首轮确认服务调用和产物生成，不能说它已获得局部配色改善。

旧版历史：新增两次VLM复验

素材坐标和预算候选范围修正后，复用了上述真实主体分割和Seedream结果，只新增区域识别、配色两次Evolving调用，没有重新发起前两项模型请求。

复验验证 （本地文件：docs/完整模型实测/复验/复验验证.json）记录：50×50、793颗、10色，12条规则改动72格，356个保护格和放豆位置不变。配色前后校验 （本地文件：docs/完整模型实测/复验/配色前后校验.json）另存程序约束检查。

这是有上述语义误判的中间结果，不能把12色降为10色直接称为质量提升，不作为推荐图纸。它保留为问题复现记录，与最终输出分开。

可查看首轮五图对照 （本地文件：docs/完整模型实测/完整流程-前后对照.png）和中间复验对照 （本地文件：docs/完整模型实测/复验/模型协作-前后对照.png），均为对应轮次的历史证据。

旧版历史：最终本机回放，新增模型调用0次

启用近色限制后，复用上述4份真实成功产物和回执，只执行最终本机规则、对照与导出，没有再次调用外部模型。三轮新增请求分别是首轮4次、中间复验2次、最终回放0次；最终回放不能当作又一次完整付费模型验证。

已回读最终验证 （本地文件：docs/完整模型实测/最终校验/最终验证.json）和最终前后校验 （本地文件：docs/完整模型实测/最终校验/配色前后校验.json）：

旧版保存样例为最终马步PNG （本地文件：docs/完整模型实测/最终校验/马步-50x50-图纸.png）、SVG （本地文件：docs/完整模型实测/最终校验/马步-50x50-图纸.svg）、CSV （本地文件：docs/完整模型实测/最终校验/马步-50x50-用豆清单.csv）、项目JSON （本地文件：docs/完整模型实测/最终校验/马步-50x50-项目.json）及最终前后对照 （本地文件：docs/完整模型实测/最终校验/模型协作-前后对照.png）。它们仅作旧版历史对照，保存的“模型实测 · 50格”采用这组保守结果，点击只打开对照；72格误判的中间产物不作为推荐输出。

色卡、导出与其他入口

MARD 221色RGB来自MakeBead craft-color-codes固定版本，使用CC BY 4.0许可并保留署名。它是社区屏幕参考，未经MARD原厂认证或实体校准，购买材料前核对实物色卡。

PNG、SVG、CSV和项目JSON均从当前网格生成。项目JSON备份网格与色卡，不含原始图片。当前没有云端同步及PDF分块图纸。

希望完全不用模型时，先选择“免费试用”自动本机去背景，再选参数并点击“生成最终图纸”，直接进入编辑器。免费入口不提供这组精准选项，复杂背景可能残留。旧分区、造型与普通转换入口不向主界面展示；旧P01—P16示例、编辑和导出继续保留。