适合 AI Agent 使用的拼豆图纸生成器

子命令

MCP 工具与入参全表（共 10 个工具，个数从清单现算）

• generate_bead_pattern·图片 → 拼豆图纸（默认回本机文件路径 + 各色号用量统计；base64 需显式索取）
  三选一：image_path / image_url / image_base64

  • 可选 width（10–200，默认 80）
  • palette_brand
  • palette_sub（默认 291）
  • palette（一段式别名，与 CLI 的 --palette 同形，例 MARD/291）
  • image_type
  • mirror
  • simplify_colors（默认不开启）
  • simplify_threshold（合并占比低于此值的色号，默认 0.005）
  • bead_shape（square / circle）
  • format（png / pdf）
  • output_path（指定落盘路径）
  • include_image（为 true 才内联 base64）
  • transparent_bg（默认 true＝纯白格不绘出，与 CLI 一致；传 false 连白底一起画，等价 CLI 的 --keep-bg）
  • cell_size（每格像素，默认 50）
  • show_grid / show_color_codes / show_rulers / show_materials（四个默认 true 的显示开关，传 false 关掉对应那一项）
  • offline / no_telemetry（本次调用级的联网开关，只影响这一次）
  • agent（标注宿主 agent 名，写进匿名用量记录）
  • export_grid_path（另存一份逐格网格 JSON，随后可用 get_pattern_grid 读回、render_pattern 重画；不传＝不写）
  • export_report_path（另存一份量化报告 JSON：mean/p50/p95/max ΔE2000、色板预算损失、最差区块、长尾统计；不传＝不写）
  • preview_path ＋ preview_max_side（另存一张长边不超过 preview_max_side 的缩小预览，默认 800，只用于观察）
  • compare_path（另存一张「源图 | 图纸」并排图）
  • shopping_list_path（另存采购清单 CSV：色号/名称/HEX/颗数/建议瓶数/备注，颗数合计与网格实算豆数互印）
  • board_tiling（按实体豆板格数切块，例 16：每板一张带板号的图 + boards.json 板号→行列范围，块数 == ceil(宽/n)×ceil(高/n) 且拼回逐格无损）
  • boards_dir（分板产物目录，不传＝与 output_path 同目录）
  • target_colors（色号预算：把最终色数压到 ≤N，量化上游贪心求最优子集；与 simplify_threshold 同时给时预算优先并出读数）
  • lock_colors（配合预算：这些色号不参与合并，逗号分隔）
  • exclude_colors（排除色号，逗号分隔：产物里该色号命中必然为 0）
  • merge_colors（指定合并 "A13->B22"：源色的格子 100% 变目标色，不是落到最近邻）
  • dither（none / floyd_steinberg / atkinson / bayer，默认沿用 image_type 预设；旗标与预设同时给时旗标优先）
  • dither_strength（0~1；默认 solidRegionProtection 会把平坦区强度归零，可观测变化以 bayer 为准）
  • bg_mode（none / white / dark / auto：边界连通抠图，与边缘不连通的同色描边不会被抠掉）
  • trim_bg（配合 bg_mode 把背景带整条裁掉，canvas 随之收缩）
  • palette_file（用自己的豆子库存色板文件；与 palette / palette_brand 互斥）
• get_pattern_grid·读回一份网格文档的逐格色号（配合 generate_bead_pattern 的 export_grid_path）；坐标 1 起，与图纸四周标尺同序
  pattern_path（网格文档路径）

  • cell（"行,列" 读单格）或 region（"行1,列1,行2,列2" 读一块），二选一
  • 越界直接点名报错，不裁剪不取模
• render_pattern·从网格文档重画图纸，绝不重新量化——改过的格子按原样落地，统计由网格实算
  pattern_path（网格文档路径）

  • output_path（落盘路径，不传写本机临时目录）
  • preview_path ＋ preview_max_side（另存缩小预览）
  • compare_path ＋ compare_source_path（另存「源图 | 图纸」并排图，两张都要给）
  • bead_shape / cell_size / mirror（可选覆盖，不传＝沿用文档里记录的出图设置）
  • format（png / pdf / svg）
  • shopping_list_path（另存采购清单 CSV）
  • board_tiling ＋ boards_dir（按豆板切块：每板一张带板号的图 + boards.json）
• edit_pattern_grid·改格：就地改网格（绝不重新量化），并回一份动作回执（动了哪些格、改前改后色号、ΔE 代价、锁内跳过几格）
  pattern_path（网格文档）

  • 选择器四选一：cell（"行,列"）/ region（"行1,列1,行2,列2"）/ where（整色号，如 "A13"）/ flood（该格的边界连通同色块）
  • to（目标色号，擦成空格传 ""）
  • rules（整色号规则链 "A13->B22,B22->C3"，与选择器和 to 互斥）
  • lock / unlock（锁格清单 "30,20;31,20"）
  • dry_run（只算不写）
  • output_path（另存；不传＝就地写回）
  • image_path（给了才算本次动作的 ΔE 代价）
• diff_pattern_grids·逐格比对两份网格文档：变更清单 + 逐色号增减；格数不同直接拒绝比较
  pattern_path（改前）

  • other_pattern_path（改后）
  • 两份必须同格数，否则拒绝而不是按较小者截断
• report_pattern·对一份网格文档出结果层量化报告（ΔE 分布、色板预算损失、最差区块、逐色号代价与孤立豆、长尾统计）
  pattern_path（网格文档）

  • image_path（生成它的那张源图，必填：没有源图就算不出 ΔE，也不会拿网格自己当参照）
  • output_path（可选，另存报告）
• analyze_input·出图前的输入诊断：背景判定 / 色彩复杂度 / 构图建议 / 色板混淆警告，并给一条可直接执行的下一步命令
  图片来源三选一（image_path / image_url / image_base64）

  • width（按哪个格数诊断，默认 80）
  • palette（"品牌/型号"，用于色板混淆警告，默认 MARD/291）
• list_palettes·列出本包内置的所有拼豆色板（品牌 + 型号 + 色数），无需联网
  入参：无参数
• list_image_types·列出所有图片类型预设及其说明（随包内联），无需联网
  入参：无参数
• submit_feedback·把这次生成的使用意见回传给我们（会进入官网留言模块并标注为 agent 提交）
  rating（1–5）

  • note（一句话意见）
  • agent_name（宿主 Agent 名，缺省记为 pindoupic-mcp；别名 agent 同样生效，两个都给以 agent_name 为准）
  • agent（agent_name 的别名，与 CLI 的 --agent 同形，只传它也生效）
  • offline（true＝本次不发，与 CLI 的 `feedback --offline` 同义；非布尔一律拒绝执行，不替你猜）
  • 只含参数与评价，不含图片内容