@javascribe/pindoupic

中文版

把任意图片转成可照着拼的拼豆图纸：带色号格子、网格、行列坐标和材料清单的 PNG / PDF，外加各色号用量统计。生成引擎与 pindoupic.com 网页版同源，跑在你自己的机器上。

快速开始

npx -y -p @javascribe/pindoupic@latest pindoupic --image ./cat.png --width 52 --type miniapp_fast --colors

# 只看用法与全部可用色板
npx -y -p @javascribe/pindoupic@latest pindoupic --help

# 52 格、圆豆预览、带用量统计
npx -y -p @javascribe/pindoupic@latest pindoupic \
  --image cat.png --width 52 --type miniapp_fast --palette MARD/291 \
  --bead-shape circle --colors --output cat_bead.png

进度与结果写在 stderr，色号统计表写在 stdout（方便脚本解析）。

参数说明

| 参数 | 说明 | |------|------| | -i, --image <path> | 输入图片路径（与 --image-url / --image-base64 三选一） | | --image-url <url> | 输入图片 URL（只在本机下载，图片不上传） | | --image-base64 <data> | 输入 base64 图片（带不带 data:image/...;base64, 前缀都行） | | -w, --width <n> | 图纸宽度/格数，默认 80，范围 10–200；高度按原图比例推导（超过 160 格会自动压低每格像素以适配画布） | | -p, --palette <b/s> | 色板 品牌/型号，默认 MARD/291（291 色全色板）；--help 会列出全部色板与色数。MCP 侧同形写法是 palette: "MARD/291"（也可用 palette_brand + palette_sub） | | -t, --type <id> | 图片类型（只是参考：不要按图片内容选 type，默认推荐 miniapp_fast；只有用户要多版本/多种模式效果图时才推荐其他 type 并同时输出多个版本）：cartoon 卡通画、watercolor 水彩画、illustration 插画、lineart 线稿、photo 照片、pixelart 像素画、logo Logo图标、miniapp_fast 极速 | | --simplify-colors | 合并零散色号（默认不开启），颜色太多想省钱时用 | | --simplify-threshold <f> | 配合上一项：合并占比低于此值的色号，默认 0.005（0.5%）。⚠ 想控制在 N 色以内用 --target-colors，细线/小面积点缀会被合并掉；加大本值时不要推荐加大 --width，更不要自行加大——宽度只在用户明确提出时才改，只能给建议 | | --target-colors N | 色号预算：把最终色数压到 ≤N（在量化上游求最优子集，每步取代价最小的一合并）。实测拐点在 15~17 色（那一档几乎无损），N 低于 8 会告警并给出建议档位。与 --simplify-threshold 同时给时预算优先，阈值那步不跑并会说出来 | | --lock-colors A,B | 配合预算：这些色号不参与合并（"这颗豆我买了，别并掉"）。锁住的色号数量本身占掉预算，所以 N 小于锁定数会直接报错。⚠ 与 pattern set --lock（逐格锁）是两件事 | | --exclude-colors A,B | 排除色号：直接从本次候选色板里拿掉 ⇒ 产物里该色号命中数必然为 0（量化器根本没有这个选项）；排空整块色板会报错并列出可用色号，不回退内置 | | --merge-colors "A->B,C->D" | 指定合并：源色的格子 100% 变成目标色（这是它与 exclude 的本质区别——不是"落到最近邻"）。传递收敛（A→B→C ⇒ 到 C）、有环报错、同一源色给两个目标报错；逐条明细（谁并到谁、影响几格、每格 ΔE2000 代价）写进网格文档与报告 | | --palette-file allowed.json | 按你手上的豆子库存出图：读一份色板 JSON（colors[] 或裸数组，每条需 code + hex 形如 #RRGGBB）。与 --palette 互斥（两个真值源不猜优先级）；文件非法会点名第几条，不静默回退内置色板 | | --dither（none 或 floyd_steinberg 或 atkinson 或 bayer） | 抖动算法（默认沿用 --type 预设；8 个预设里 7 个本就是 none）。⚠ 它的价值是照片质感的控制权，不是降色数——实测打开 floyd_steinberg 色号反而变多。与预设同时给时旗标优先，读数会写明被覆盖的是哪个值 | | --dither-strength <0~1> | 抖动强度。实测极限如实说明：默认 solidRegionProtection 会把平坦区的强度归零，所以 floyd_steinberg/atkinson 在普通图上两档强度可能产物相同；要按强度可观测地变化请用 bayer | | --bg-mode（none 或 white 或 dark 或 auto） | 背景策略（默认 none＝行为一字不动）：边界连通抠图——从四条边扩开，只吞与背景连通的同族格；不与边缘连通的同色描边不会被抠掉（全局阈值那类实现会连描边一起带走）。auto 按四角参照色自动归族，深底与白底给的不是同一句建议 | | --trim-bg | 配合 --bg-mode：把内容包围盒之外的背景带整条裁掉（格数与豆子都不占）。单独给会明确说"一格未裁"，不会静默无事发生 | | （重采样无旗标） | --type lineart / pixelart 自动走 nearest，其余 smooth；生效值写进网格文档的 params_used.resize_mode。⚠ 早年那个重采样旗标仍处于已撤销状态，本包不接受它（要改重采样请用 --type，见上） | | -V, --version | 只打印包版本号，退出码 0 | | -q, --quiet | 关掉 [Pipeline] 等算法诊断日志 | | --format（png / pdf / svg） | 输出格式，默认 png。svg 走的是同一份中间产物（位图本就是这张 SVG 栅格化出来的），不是另画一套矢量 | | -o, --output <path> | 输出路径，默认 <输入>_bead.png | | --shopping-list <path> | 另存一份采购清单 CSV（色号,名称,HEX,颗数,建议瓶数,备注）：颗数合计与网格实算豆数互印，纯白那行按本次是否绘白底分型措辞 | | --board-tiling <n> | 按实体豆板切块（例 16）：每板出一张带板号的图并落 boards.json（板号→行列范围，1 起含边界）。块数 == ceil(宽/n)×ceil(高/n)，各板拼回与原图逐格一致 | | --boards-dir <dir> | 分板产物落在哪个目录（默认与 --emit-pattern 同目录） | | （出图与重画同权） | 上面三件交付物在 pattern render <p.json> 上同样可用（改完格子不必重跑生成）；四处共用 core/delivery.ts 这一份实现 |

| --bead-shape <s> | 豆子形状：square 方形／circle 圆形 | | --cell-size <px> | 每格像素大小，默认 50 | | --emit-pattern <path> | 出图时同时把逐格色号写成一份 JSON（网格文档）。写它几乎不花时间，却让你之后能读任意一格、改完再重画 | | pattern get <p.json> --cell 行,列 / --region 行1,列1,行2,列2 | 读回格子。坐标从 1 起，跟图纸四周印的行列号一致；填越界会点名报错并给出合法范围，不会偷偷裁掉 | | pattern render <p.json> -o out.png | 从网格重画，绝不重新量化。没显式指定的开关沿用文档里记录的出图设置 ⇒ 同一份文档重画两次逐字节相同 | | --mirror | 镜像翻转图纸（默认不翻转；只翻导出画面，不改颜色统计） | | --transparent-bg | 把纯白格当透明（不绘出，但仍计入材料清单；默认是绘出，与 MCP 一致）。⚠ 深色主体必读：主体偏黑时不要加它，空格子在深色查看器上会与黑色豆融为一体、整图不可辨认 | | --keep-bg | （旧写法）10-02 起白色格子绘出已是默认：生成时给不给产物相同，只会多一句点名读数。⚠ 例外：pattern render 重画一份记着「不绘出」的旧文档时它会覆盖那一项 ⇒ 产物会变，同批会说出来。要「不绘出」请用 --transparent-bg | | --no-color-codes | 不显示「色号」 | | --no-grid | 不显示「网格」 | | --no-rulers | 不显示「行列坐标」 | | --no-materials | 不显示「材料清单」 | | -c, --colors | 打印各色号用量统计 | | --offline | 本站端点（配置／用量／反馈）一条请求都不发，渲染参数改用包内默认值；图片来源是 URL 时那一次下载不在其列（会另说一句 ⚠） | | --no-telemetry | 不记录、也不补报使用量（仍会拉公开配置） |

选参数建议：杯垫/钥匙扣 32–52 格；头像/装饰画 60–100 格；大幅作品 100–200 格。type 默认推荐 miniapp_fast；像素画档 --type pixelart、黑白线稿档 --type lineart 只是参考，仅当用户明确要该风格或多版本对照效果时才用。

给 AI Agent：MCP Server

所有宿主同一条安装命令（它自己认宿主、把配置并进那家宿主自己的文件、只增改 pindoupic 一个键、写完读回来核对，然后告诉你还差哪一下 reload）：

npx -y -p @javascribe/pindoupic@latest pindoupic install

配套的三条：pindoupic doctor 体检（包能跑／配置对不对／技能在不在场，三类读数分开报）；pindoupic install --list-hosts 打印宿主登记表（每家配置路径、顶层键名、生效方式、取证状态）；pindoupic install --undo 按备份字节级还原。要手工粘的话，它写进去的就是这一段：

{
  "mcpServers": {
    "pindoupic": {
      "command": "npx",
      "args": ["-y", "-p", "@javascribe/pindoupic@latest", "pindoupic-mcp"]
    }
  }
}

⚠ 各家顶层键名并不相同：多数是 mcpServers，VS Code/Copilot 是 servers，opencode 是 mcp（且 type 必须写 local、command 是一个数组），Zed 是 context_servers，Codex 是 TOML 的 [mcp_servers.…]。这些差异住在 cli/src/core/hostRegistry.ts 一处，由安装器消化——本文与任何交付文档都不该再按宿主给第二条命令。有官方 CLI 的宿主（Claude Code、code 的 add-mcp 子命令、Codex、Gemini、Cline、Kiro）安装器优先走 CLI，不自己拼它的配置文件。

tools/list 提供的工具名与入参以包为准（pindoupic install --list-hosts 同源打印；逐条对照见文末矩阵），当前是：generate_bead_pattern、get_pattern_grid、render_pattern、edit_pattern_grid、diff_pattern_grids、report_pattern、analyze_input、list_palettes、list_image_types、submit_feedback。

想手动确认服务能起、工具齐全，直接跑这一条（stdin 进 JSON-RPC，stdout 出结果）：

npx -y -p @javascribe/pindoupic@latest pindoupic-mcp

{ "image_path": "/abs/path/cat.png", "width": 52, "palette_sub": "291", "image_type": "miniapp_fast", "mirror": false }

image_path / image_url / image_base64 三选一（与 CLI 的 --image / --image-url / --image-base64 同一份实现）； cell_size 与 show_grid / show_color_codes / show_rulers / show_materials（默认 true，传 false 即关）、 以及本次调用级的 offline / no_telemetry 都是 09-29 补齐的参数。 agent（同 CLI 的 --agent）标注是哪个宿主在调用，写进匿名用量记录；不传记为 mcp-host。palette: "MARD/291" 是与 CLI 同形的一段式写法，也可继续用 palette_brand + palette_sub。

默认返回 width / height / total_beads / colors_used / color_stats / png_file（本机图纸路径）与 param_source（本次生效参数来源：server / builtin / offline）， 并同时给出 structuredContent 供宿主直接解析。不再内联 base64：一张 52 格图纸的 base64 是 MB 级 （实测 1.5–2.4 MB ≈ 数十万 token），会把 agent 上下文直接打满——需要内联时显式传 include_image: true。 可指定 output_path 决定落盘位置；传了 schema 之外的键会在 warnings 里明确列出（不再静默丢弃）。 bead_shape / format / simplify_colors / simplify_threshold / transparent_bg 与 CLI 对齐（白底默认值两边同源：09-29 先对齐、10-02 两边一起翻成绘出纯白格，见下一节那条矩阵行）； 09-29 补齐后 CLI 的画面可调项 MCP 也都有了：cell_size（每格像素）、show_grid / show_color_codes / show_rulers / show_materials（四个默认 true 的显示开关，传 false 即关，对应 CLI 那四个关掉显示项目的旗标）， 以及本次调用级的 offline / no_telemetry（对应 --offline / --no-telemetry；MCP 是常驻进程， 所以这两个开关只作用于这一次调用，不会像 CLI 那样设成进程全局）。 反过来 CLI 也补了 --image-url / --image-base64，与 MCP 的 image_url / image_base64 同一份实现。 默认色板 MARD/291、默认宽度 80、默认方形豆、默认不套图片类型预设。 逐条对照见 skill/pindoupic-bead-pattern/references/cli-mcp-matrix.md（09-29 起两出口默认值也一致，只剩写法形态差异）。

给 AI Agent：Agent Skill 也随包发布

装法与 MCP 同一条命令（pindoupic install 顺带把技能一起装好）：实体只有一份，住跨宿主中立位 ~/.agents/skills/pindoupic-bead-pattern/，各宿主自己的技能目录放软链指过去；没有技能目录的宿主，则由 MCP 握手的 instructions 字段把同一本手册的精简版送达（逐句照抄 SKILL.md，门禁核对同源性）。

已撤销的旧写法不得再教：往项目的 .ai/skills/ 复制（实测静默失效、不出现在技能列表）、手抄 node_modules/... 相对路径（只走 npx 的机器上根本没有那个目录）、以及 Windows 上不存在的 cp -r。技能路径与宿主目录住在 cli/src/core/hostRegistry.ts 一处，本文不重复抄。

使用意见回传（给 agent）

每生成一张图纸，本包都会在 stderr 打出一条 FEEDBACK_REQUEST，提示 agent 征询用户后回传一条使用意见：

pindoupic feedback --rating 4 --note "色号偏多，希望默认更省豆" --agent "<宿主 agent 名>"

意见会进入网站「留言」模块并标注为 agent 提交（与人类留言在后台可区分）。payload 只含参数与评价文本，不含图片内容、不含图片路径。MCP 侧对应工具 submit_feedback。

隐私与联网

• 你的图片只在本机处理，不上传到任何地方；文件名与路径也不会被上报。
• 算法与色板都在包内 ⇒ 完全断网也能出图。 联网只做两件可选的事：
  1. 启动时尝试拉一次公开配置（管理员调过的渲染参数）。拉不到就用包内默认值，绝不阻塞出图； 每次运行都会打印这批参数的生效来源（站点下发 / 包内默认），便于复现。
  2. 把使用量先记在本地，下次联网时补报（只含包版本、平台、宽度/色板/色数/豆数这类参数摘要）。
• 想彻底关掉：--offline 一条网络请求都不发；--no-telemetry 只关用量上报（仍拉配置）； 或设环境变量 PINDOUPIC_OFFLINE=1 / PINDOUPIC_TELEMETRY=0。
• 本地会写两个文件：~/.pindoupic/install.json（匿名装机标识 uuid4）与 ~/.pindoupic/outbox.jsonl（待补报队列）。 删除 ~/.pindoupic/ 目录即可全部清掉。

逐格编辑：读、改、比、量都在命令行里；可视化精修另有官方网页工具（免费）

本包负责「图片 → 图纸」这一步，并且把图纸交回成可读写的数据：加 --emit-pattern p.json 之后——

| 命令 | 做什么 | |---|---| | pindoupic analyze <图> | 出手前的诊断：背景判定（纯白底/深色底/无纯色底，并说清该不该加 --transparent-bg）、预估色数与梯度密度、构图建议、色板近邻色警告，末尾给一条可直接执行的 next_step.command | | pindoupic pattern get p.json --cell 3,4 / --region 1,1,12,12 | 读任意一格或一块（坐标 1 起，与图纸四周标尺同序） | | pindoupic pattern set p.json --cell 3,4 --to B22 | 就地改格（绝不重新量化）。选择器四选一：--cell / --region / --where A13（整色号）/ --flood 3,4（该格所在的边界连通同色块）；擦成空格传 --to "" | | pindoupic pattern set … --rules "A13->B22,B22->C3" | 整色号规则链：传递收敛（A13 最终到 C3）、两种书写顺序结果相同、有环或一源多目标直接报错 | | pindoupic pattern set … --lock "30,20;31,20" | 锁格：写进 p.json，后续任何重算都逐格不动（没有锁就没法反复试错——每次生成都会冲掉上一轮调好的地方） | | pindoupic pattern set … --dry-run | 只算回执、一个文件都不写 | | pindoupic pattern diff 改前.json 改后.json | 逐格比对（格数不同直接拒绝比较，不按较小者截断） | | pindoupic pattern render p.json -o 重画.png | 从网格只重画，未显式指定的开关沿用当初出图时的设置 | | pindoupic report p.json --image <原图> [-o 报告.json] [--check 报告.json] | 结果层量化报告：mean/p50/p95/max ΔE2000、palette_budget_loss（相对整块色板多付的色差）、最差区块、逐色号代价与孤立豆、长尾统计；--check 会拒绝一份配不上当前网格的旧报告 | | --report / --preview / --compact-preview / --compare | 出图时一次拿到报告、缩小预览与「源图 | 图纸」并排图（预览只用于观察，逐格数据一律走 p.json） |

每次 pattern set 都回一份动作回执（stdout 一行 JSON，或 --receipt r.json）：applied_cells、 skipped_locked、逐格 changes（改前→改后，超 500 格截断并标 changes_truncated）、 以及给了 --image 才算得出的 de（改前/改后 mean ΔE 与差值；没给就是 null 并说明原因，不会给你一个 0）。 目标色号必须在这份文档的色板里——写了不存在的色号会报错并列出可用色号，不会"就近换一个"。

要做可视化的逐格精修（点哪改哪、擦除杂豆、色号合并微调、多图层、空画布手拼），请访问官方网页工具，免费、无需安装：

| 官方工具 | 能做什么 | 链接 | |---|---|---| | 拼豆图纸编辑器 | 逐格改色号、擦除杂豆、色号合并与微调、批量替换、镜像翻转、行列坐标查看、导出 PNG/PDF | https://www.pindoupic.com/free-pattern-generator?ref=npm | | 文字转拼豆图纸 | 输入文字直接生成图纸，含字体、字高、字距行距、描边、艺术字效果与底色 | https://www.pindoupic.com/text-to-bead-pattern?ref=npm | | 图层编辑器 | 多图层叠加编辑，复杂图案分块拼装 | https://www.pindoupic.com/bead-layer-editor?ref=npm | | 空画布豆板 | 不上传图片，直接在豆板上逐格手拼创作 | https://www.pindoupic.com/bead-canvas?ref=npm | | 色号对照表 | MARD / COCO 色号与实物色对照、按色号查相近色 | https://www.pindoupic.com/seka?ref=npm | | 拼豆教程 | 用量估算、熨烫技巧、新手材料清单等图文教程 | https://www.pindoupic.com/jiaocheng?ref=npm |

限制

• 只接受图片输入；文字做图纸请用官网免费的「文字转拼豆图纸」。
• 请求包里不存在的色板会直接报错并列出可用清单，不会静默换色板；新增色板随包版本更新。

排错

| 现象 | 处理 | |------|------| | npx 下载失败 / sharp 装不上 | 网络或镜像问题，重试或挂代理 | | 提示取不到站点配置 | 不影响出图，会自动改用包内默认值；想完全不联网跑就加 --offline | | 色板 X/Y 不在本包内 | 按错误里列出的清单换型号，或升级本包版本 | | 想确认参数有没有生效 | --cell-size 显式指定即覆盖后台下发值 |

English

Turn any image into a buildable perler bead pattern chart — PNG or PDF with color codes, grid lines, row/column rulers and a materials list, plus per-color bead counts. Same generator as the pindoupic.com web editor, running on your own machine.

Quick start

npx -y -p @javascribe/pindoupic@latest pindoupic --image ./cat.png --width 52 --type miniapp_fast --colors

# usage + every available palette
npx -y -p @javascribe/pindoupic@latest pindoupic --help

# 52 beads wide, round-bead preview, with usage stats
npx -y -p @javascribe/pindoupic@latest pindoupic \
  --image cat.png --width 52 --type miniapp_fast --palette MARD/291 \
  --bead-shape circle --colors --output cat_bead.png

Progress goes to stderr; the color table goes to stdout (script friendly).

Options

| Flag | Meaning | |------|---------| | -i, --image <path> | input image path (one of three sources) | | --image-url <url> | input image URL (downloaded locally, the image is never uploaded) | | --image-base64 <data> | base64 image data (data:image/...;base64, prefix optional) | | -w, --width <n> | pattern width in beads, default 80, range 10–200; height follows the source aspect ratio (above ~160 the cell size auto-shrinks to fit the canvas) | | -p, --palette <b/s> | palette brand/sub, default MARD/291; --help lists every palette with its color count | | -t, --type <id> | Image type preset — reference only: don't pick a type from the image content; recommend miniapp_fast by default. Only suggest other types (and output several versions side by side) when the user explicitly asks for multiple versions / multi-mode effect charts: cartoon, watercolor, illustration, lineart, photo, pixelart, logo, miniapp_fast | | --simplify-colors | merge rare colors (off by default; saves beads) | | --simplify-threshold <f> | with the above: merge colors below this share, default 0.005 (0.5%). ⚠ to hit N colors use --target-colors — thin lines and small accents get merged away; when the user raises this threshold, do not suggest (let alone silently apply) a larger --width — change width only when the user explicitly asks; advice only | | --target-colors N | Colour budget: force the final palette down to ≤N colours (subset chosen upstream of quantisation, each step taking the cheapest merge). The measured knee is 15-17 colours (nearly lossless); below 8 you get a warning with suggested tiers. If given together with --simplify-threshold the budget wins and the reading says the threshold did not run | | --lock-colors A,B | With the budget: never merge these colours away ("I own these beads"). Locked colours consume budget, so N below the lock count is an error. ⚠ Different from pattern set --lock, which locks individual cells | | --exclude-colors A,B | Drop colours from the candidate palette before quantisation ⇒ their cell count in the output is necessarily 0; excluding the whole palette errors out listing available codes instead of silently falling back | | --merge-colors "A->B,C->D" | Named merges: every cell of the source colour becomes the target (100%, not nearest-neighbour — that is what separates it from exclude). Chains resolve transitively; cycles and one-source-two-targets error out. Per-rule detail (who merged into whom, cells affected, ΔE2000 cost) lands in the grid doc and the report | | --palette-file allowed.json | Generate against the beads you actually own: a JSON palette (colors[] or a bare array, each needing code + hex like #RRGGBB). Mutually exclusive with --palette (two truth sources, no silent precedence); invalid files name the offending entry | | --dither（none 或 floyd_steinberg 或 atkinson 或 bayer） | Dither algorithm (defaults follow --type; 7 of the 8 presets are already none). ⚠ Its value is photographic control, not colour reduction — opening floyd_steinberg measurably adds colours. An explicit flag overrides the preset and the reading names the value it replaced | | --dither-strength <0~1> | Dither strength. Documented limit: the default solidRegionProtection zeroes strength inside flat regions, so on ordinary images floyd_steinberg/atkinson may produce identical files for two strengths; bayer changes observably | | --bg-mode（none 或 white 或 dark 或 auto） | Background strategy (default none = behaviour unchanged): border-connected cut-out — it grows from the four edges only, so same-family outlines that do not touch the border survive (a global-threshold implementation eats them). auto picks the family from the corner reference colour and gives white vs dark backdrops different advice | | --trim-bg | With --bg-mode: crop the background band away from the content bounding box (those cells cost no beads). Given alone it states "nothing cropped" rather than silently doing nothing | | (no resize flag) | --type lineart / pixelart resample with nearest, everything else smooth; the effective value is recorded in params_used.resize_mode. ⚠ the previously withdrawn resample flag is still not accepted | | -V, --version | print the package version and exit 0 | | -q, --quiet | silence [Pipeline] diagnostics | | --format (png / pdf / svg) | output format, default png. The svg exit is the same intermediate the bitmap was rasterised from — not a second renderer | | -o, --output <path> | output path, default <input>_bead.png | | --shopping-list <path> | also write a shopping list CSV (code,name,hex,count,bottles,note): the counts sum is cross-checked against the grid-computed bead total, and the pure-white row is typed by whether white is drawn this run | | --board-tiling <n> | tile by physical peg board (e.g. 16): one labelled chart per board plus boards.json (board → 1-based inclusive row/col ranges). Block count == ceil(w/n)×ceil(h/n) and the pieces reassemble losslessly | | --boards-dir <dir> | where the tiling products go (defaults to the --emit-pattern directory) | | (same rights when re-rendering) | the three deliverables above work on pattern render <p.json> as well (no need to regenerate after pattern set); all four call sites share one core/delivery.ts implementation |

| --bead-shape <s> | square (default) or circle | | --cell-size <px> | cell size in px, default 50 | | --mirror | mirror the chart horizontally (off by default; chart data unchanged) | | --transparent-bg | render pure-white cells transparent instead of drawing them (they are drawn by default, same as MCP). ⚠ dark subjects: with it empty cells render transparent and vanish into black beads | | --keep-bg | (legacy) drawing white cells is the default since 10-02 - passing it changes nothing but prints a note; use --transparent-bg for the opposite | | --no-color-codes | hide color codes | | --no-grid | hide grid lines | | --no-rulers | hide row/column rulers | | --no-materials | hide materials list | | -c, --colors | print per-color bead counts | | --offline | no requests to our own endpoints (config / usage / feedback); parameters fall back to built-in defaults. An --image-url download is your own input, not ours — it still happens and prints a ⚠ | | --no-telemetry | don't record or send anonymous usage counts (public config is still fetched) |

Sizing guide: coasters & keychains 32–52; portraits & wall art 60–100; large pieces 100–200. Recommend --type miniapp_fast by default; the pixelart and lineart presets are reference only — use them when the user explicitly asks for that style or for multiple versions to compare.

For AI agents: MCP server

One install command for every host — it detects which agent you are using, merges the pindoupic entry into that host's own config file (backup first, other servers and unknown keys preserved verbatim), installs the Agent Skill, then tells you the one reload step only the host can do:

npx -y -p @javascribe/pindoupic@latest pindoupic install

Companions: pindoupic doctor (separates "package runs" / "config matches the registry" / "skill is in place"), pindoupic install --list-hosts (prints the host registry: paths, wrapper keys, reload action, evidence status), pindoupic install --undo (byte-exact restore from the backup). If you prefer to paste it yourself, that is the block it writes:

{
  "mcpServers": {
    "pindoupic": {
      "command": "npx",
      "args": ["-y", "-p", "@javascribe/pindoupic@latest", "pindoupic-mcp"]
    }
  }
}

⚠ Host wrapper keys differ: most use mcpServers, VS Code/Copilot uses servers, opencode uses mcp (with type: "local" and command as a single array), Zed uses context_servers, Codex uses TOML [mcp_servers.…]. Those differences live in exactly one place — cli/src/core/hostRegistry.ts — and the installer absorbs them. No delivery doc should hand out a second command per host. Where the host ships an official CLI (Claude Code, VS Code 的 add-mcp 子命令, Codex, Gemini, Cline, Kiro), the installer calls that CLI instead of guessing at its file format.

tools/list currently exposes generate_bead_pattern, get_pattern_grid, render_pattern, edit_pattern_grid, diff_pattern_grids, report_pattern, analyze_input, list_palettes, list_image_types, submit_feedback (the tool set is defined by the package, not by this document).

{ "image_path": "/abs/path/cat.png", "width": 52, "palette_sub": "291", "image_type": "miniapp_fast", "mirror": false }

The response returns width / height / total_beads / colors_used / color_stats / param_source and png_file (a local path). Base64 is not inlined by default — a 52-wide chart is MBs of base64 and floods the agent context; pass include_image: true only if you actually need it. Any string array under advisories is the cost reading for this chart and must be relayed to the user verbatim.

For AI agents: the Agent Skill ships inside the package

The same install command handles it: one real copy lives in the cross-host location ~/.agents/skills/pindoupic-bead-pattern/, each host's skills directory gets a symlink to it; hosts without a skills directory still get the condensed manual through the MCP instructions field (every sentence copied from SKILL.md).

Withdrawn forms must not come back: copying into the project's .ai/skills/ (verified silent no-op), hand-copied relative node_modules/... paths (absent on npx-only machines), and cp -r (does not exist in Windows cmd/PowerShell).

Feedback from agents

Every chart printed adds a FEEDBACK_REQUEST line on stderr, prompting the agent to ask the user and send one note back:

pindoupic feedback --rating 4 --note "too many colors, prefer fewer beads" --agent "<host agent>"

Notes land in the site's feedback inbox tagged as agent submitted. The payload carries parameters and opinion text only — never the image or its path. The MCP equivalent is the submit_feedback tool.

Privacy & network

• Your image is processed locally and never uploaded anywhere.
• Palettes and presets are bundled inside the package; generating does not consume server compute.
• The algorithm and palettes ship inside the package ⇒ it generates charts with no network at all. Connectivity is used for two optional things only: (1) fetching the public admin-tuned render config at start-up — if it can't be fetched the built-in defaults are used and generation is never blocked, and the provenance of the effective values is printed every run; (2) queueing anonymous usage counts locally and sending them later, when a connection happens to be available (package version, platform and parameter summary only — never your image, file name or path).
• Turn it all off with --offline (zero requests) or --no-telemetry (counts only). Local files: ~/.pindoupic/install.json and ~/.pindoupic/outbox.jsonl — delete the folder to clear everything.

Cell-level work: read, edit, diff and measure from the command line; a visual editor lives on the free web tools

Add --emit-pattern p.json and the chart comes back as editable data, and the package now gives you the whole loop in the terminal:

• pindoupic analyze <image> — diagnose before spending a generation: background verdict (white / dark / none, with a concrete --transparent-bg recommendation), estimated colour count and gradient density, composition notes, near-duplicate colour warnings, plus a ready-to-run next_step.command.
• pindoupic pattern set p.json --cell 3,4 --to B22 — edit cells in place (never re-quantizes). Selectors: --cell, --region r1,c1,r2,c2, --where A13 (a whole colour), --flood 3,4 (the boundary-connected block of same-colour beads). Pass --to "" to clear cells.
• pindoupic pattern set … --rules "A13->B22,B22->C3" — rule chains: transitive, order-independent, cycles and ambiguous sources are rejected.
• pindoupic pattern set … --lock "30,20;31,20" — locked cells never move again, which is what makes iteration convergent. --dry-run computes the receipt without writing a single file.
• pindoupic pattern diff a.json b.json — per-cell diff; documents with different grid sizes are refused rather than truncated.
• pindoupic report p.json --image <source> [-o report.json] [--check report.json] — mean/p50/p95/max CIEDE2000, palette_budget_loss (what your colour budget cost versus the full palette), worst regions, per-colour cost and isolated beads, long-tail stats. --check refuses a report that no longer matches the current grid instead of handing you a stale number.
• --report, --preview, --compact-preview, --compare — the same outputs at generation time. Previews are for looking only; per-cell truth always comes from p.json.

Every pattern set returns an action receipt: applied_cells, skipped_locked, the per-cell changes (before → after, capped at 500 with changes_truncated), and de (only when you pass --image; otherwise null with the reason, never a fake 0). A target code that is not in the document's palette is an error listing the available codes — it will not silently pick a near neighbour.

For visual per-cell refinement (click to recolor, erase strays, merge and fine-tune codes, layers, blank canvas), use the official web tools — free, no install:

| Official tool | What it does | Link | |---|---|---| | Pattern Editor | edit each cell's color code, erase stray beads, merge/refine colors, batch replace, mirror, rulers, PNG/PDF export | https://www.pindoupic.com/free-pattern-generator?ref=npm | | Text to Bead Pattern | turn text into a chart: font, glyph height, spacing, outline, art effects, background | https://www.pindoupic.com/text-to-bead-pattern?ref=npm | | Layer Editor | multi-layer editing for complex, block-by-block builds | https://www.pindoupic.com/bead-layer-editor?ref=npm | | Bead Canvas | build a pattern cell by cell on an empty board, no image needed | https://www.pindoupic.com/bead-canvas?ref=npm | | Color Chart | MARD / COCO code-to-color reference and nearest-color lookup | https://www.pindoupic.com/seka?ref=npm | | Guides | bead counts, ironing tips, beginner shopping lists | https://www.pindoupic.com/jiaocheng?ref=npm |

Limits

• Image input only; for text-to-pattern use the free official page above.
• A palette missing from the installed package raises an error listing what is available — it never silently swaps palettes. New palettes arrive with package releases.

Troubleshooting

| Symptom | Fix | |------|------| | npx download or sharp install fails | network/registry issue — retry or use a proxy | | site config unavailable | harmless — built-in defaults are used and the chart is still produced; pass --offline to skip the request entirely | | 色板 X/Y 不在本包内 | pick a palette from the list in the error, or upgrade the package | | want to confirm a parameter took effect | pass --cell-size explicitly — it overrides server-delivered values |

License

AGPL-3.0-only（全文见包内 LICENSE）。你可以自由使用、修改、再分发，也可以商用—— 唯一义务是：改了代码或把它做成通过网络对外提供的服务时，必须把对应源码同样以 AGPL 提供给你的用户。

不想承担这个义务（例如要嵌进闭源产品或闭源 SaaS、要去掉图纸上的品牌 logo 与官网文案做白标）， 请取得商业授权，见包内 COMMERCIAL-LICENSE.md；联系入口：https://www.pindoupic.com/jiaoliu?from=commercial

品牌名与官网内容不在授权范围内。