@javascribe/pindoupic 0.3.0 → 0.5.0

package/README.md

@@ -1,68 +1,173 @@
 # @javascribe/pindoupic
 
-把任意图片转成可照着拼的**拼豆图纸**：带色号格子、网格、行列编号和材料清单的 PNG / PDF，外加各色号用量统计。
-生成引擎与 [pindoupic.com](https://www.pindoupic.com) 网页版同一套算法，跑在你自己的机器上。
+# 中文版
+
+把任意图片转成可照着拼的**拼豆图纸**：带色号格子、网格、行列坐标和材料清单的 PNG / PDF，外加各色号用量统计。生成引擎与 [pindoupic.com](https://www.pindoupic.com) 网页版同源，跑在你自己的机器上。
+
+## 快速开始
 
 ```bash
 npx -y -p @javascribe/pindoupic pindoupic --image ./cat.png --width 52 --type cartoon --colors
 ```
 
-## 数据在包里，算法是密文：站点不可达时不能生成
+```bash
+# 只看用法与全部可用色板
+npx -y -p @javascribe/pindoupic pindoupic --help
+
+# 52 格、圆豆预览、带用量统计
+npx -y -p @javascribe/pindoupic pindoupic \
+  --image cat.png --width 52 --type cartoon --palette MARD/291 \
+  --bead-shape circle --colors --output cat_bead.png
+```
+
+进度与结果写在 **stderr**，色号统计表写在 **stdout**（方便脚本解析）。
+
+## 参数说明
 
-| 内容 | 放在哪 | 断网时会怎样 |
-|------|--------|--------------|
-| 9 套色板（MARD 24/48/72/96/120/221/264/291、COCO 291） | 随包内联 | 照常可用 |
-| 8 种图片类型预设参数 | 随包内联 | 照常可用 |
-| 渲染参数（格子像素、色号填充比例） | **可选**从 `/api/v1/config` 读取，3 秒取不到用包内固化值 | 用包内值，出图不受影响 |
-| **图纸生成算法** | 密文 `dist/core.enc.json`（AES-256-GCM），**密钥不在包里** | 取不到密钥 ⇒ 直接报错，不出图 |
+| 参数 | 说明 |
+|------|------|
+| `-i, --image <path>` | 输入图片路径（必填） |
+| `-w, --width <n>` | 图纸宽度/格数，默认 50，范围 10–200（超过 160 格会自动压低每格像素以适配画布） |
+| `-p, --palette <b/s>` | 色板 品牌/型号，默认 `MARD/120`；`--help` 会列出全部色板与色数 |
+| `-t, --type <id>` | 图片类型：`cartoon 卡通画`、`watercolor 水彩画`、`illustration 插画`、`lineart 线稿`、`photo 照片`、`pixelart 像素画`、`logo Logo图标`、`miniapp_fast 极速` |
+| `--simplify-colors` | 合并稀有色号，颜色太多想省钱时用 |
+| `--format <png\|pdf>` | 输出格式，默认 png |
+| `-o, --output <path>` | 输出路径，默认 `<输入>_bead.png` |
+| `--bead-shape <s>` | 豆子形状：`square 方形`／`circle 圆形` |
+| `--cell-size <px>` | 每格像素大小，默认 50 |
+| `--mirror` | 镜像翻转图纸（默认不翻转；只翻导出画面，不改颜色统计） |
+| `--keep-bg` | 保留白色背景（默认把纯白格当透明） |
+| `--no-color-codes` | 不显示「色号」 |
+| `--no-grid` | 不显示「网格」 |
+| `--no-rulers` | 不显示「行列坐标」 |
+| `--no-materials` | 不显示「材料清单」 |
+| `-c, --colors` | 打印各色号用量统计 |
+
+选参数建议：杯垫/钥匙扣 32–52 格；头像/装饰画 60–100 格；大幅作品 100–200 格。像素画用 `--type pixelart`；黑白线稿用 `--type lineart`。
 
-- 设计意图：生成过程全在本机跑，不消耗服务器算力；但解密密钥由 pindoupic.com 下发（与网页版同一端点 `/api/v1/crypto/algo-key`），**网站挂了本包就不能用**。
-- 你的图片**只在本机处理，不上传**到任何地方；联网只为取一次算法密钥。
-- 自托管：把 `PINDOUPIC_API` 指向你自己的后端，并保证它提供 `/crypto/algo-key` 且与加密时用的是同一个 `HMAC_SECRET`。
-- 实测三条：在线出图的色号用量表与上一版逐字一致；站点不可达时报错并给出可执行的下一步；发布产物里读不到任何算法标识符与仓库路径（判据见 `scripts/verify-cli-data-0927.cjs`）。
+## 给 AI Agent：MCP Server
 
-## 命令行
+`tools/list` 提供三个工具：`generate_bead_pattern`、`list_palettes`、`list_image_types`。
 
+```json
+{
+  "mcpServers": {
+    "pindoupic": {
+      "command": "npx",
+      "args": ["-y", "-p", "@javascribe/pindoupic", "pindoupic-mcp"]
+    }
+  }
+}
 ```
-pindoupic --image <path> [options]
-
-图片选项:
-  -i, --image <path>      输入图片路径 (必填)
-  -w, --width <n>         图纸宽度/格数 (默认 50, 范围 10-150)
-  -p, --palette <b/s>     色板 品牌/型号 (默认 MARD/120)
-  -t, --type <id>         cartoon, watercolor, illustration, lineart, photo, pixelart, logo, miniapp_fast
-  --resize-mode <mode>    smooth|nearest (默认 smooth)
-  --simplify-colors       精简稀有色号 (默认不精简)
-
-导出选项:
-  --format <fmt>          png|pdf (默认 png)
-  -o, --output <path>     输出路径 (默认 <输入>_bead.png)
-  --bead-shape <shape>    circle|square (默认 square)
-  --cell-size <px>        格子像素大小 (默认 50)
-  --keep-bg               保留白色背景 (默认透明)
-
-显示选项 (默认全部显示):
-  --no-color-codes / --no-grid / --no-rulers / --no-materials
-
-其他:
-  -c, --colors            输出各颜色用量统计 (stdout)
-  -h, --help              帮助（会列出全部可用色板与预设）
+
+```json
+{ "image_path": "/abs/path/cat.png", "width": 52, "palette_sub": "291", "image_type": "cartoon", "mirror": false }
+```
+
+返回 `width` / `height` / `total_beads` / `colors_used` / `color_stats`，以及 `png_data_url`（base64，可直接落盘）和 `png_file`（本机临时文件路径）。
+
+## 给 AI Agent：Agent Skill 也随包发布
+
+装好包后 `skill/` 目录就在安装路径里，那是教 Agent 选参数、交付结果的操作手册：
+
+```bash
+cp -r node_modules/@javascribe/pindoupic/skill/pindoupic-bead-pattern ~/.claude/skills/   # Claude Code 全局
+cp -r node_modules/@javascribe/pindoupic/skill/pindoupic-bead-pattern .ai/skills/         # Qoder 当前项目
 ```
 
-进度与结果写在 **stderr**，色号统计表写在 **stdout**，脚本解析时按此分流。
+## 使用意见回传（给 agent）
+
+每生成一张图纸，本包都会在 stderr 打出一条 `FEEDBACK_REQUEST`，提示 agent 征询用户后回传一条使用意见：
+
+```bash
+pindoupic feedback --rating 4 --note "色号偏多，希望默认更省豆" --agent "<宿主 agent 名>"
+```
+
+意见会进入网站「留言」模块并标注为 **agent 提交**（与人类留言在后台可区分）。payload 只含参数与评价文本，**不含图片内容、不含图片路径**。MCP 侧对应工具 `submit_feedback`。
+
+## 隐私与联网
+
+- 你的图片**只在本机处理，不上传**到任何地方。
+- 色板与图片类型预设随包内联，出图不消耗服务器算力。
+- 首次生成需要能访问 pindoupic.com 完成一次联网激活；离线环境请自托管或联系官方。
+
+## 想要更细的格子级编辑？请用拼豆Pic 官方在线工具（免费）
+
+本包负责「图片 → 图纸」这一步。要**逐格精修**，请访问官方网页工具，免费、无需安装：
 
-示例：
+| 官方工具 | 能做什么 | 链接 |
+|---|---|---|
+| 拼豆图纸编辑器 | 逐格改色号、擦除杂豆、色号合并与微调、批量替换、镜像翻转、行列坐标查看、导出 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 装不上 | 网络或镜像问题，重试或挂代理 |
+| 提示无法联网激活 / 取不到授权 | 无法访问 pindoupic.com（离线、公司网络、DNS）。恢复联网后重试 |
+| `色板 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](https://www.pindoupic.com) web editor, running on your own machine.
+
+## Quick start
+
+```bash
+npx -y -p @javascribe/pindoupic pindoupic --image ./cat.png --width 52 --type cartoon --colors
+```
 
 ```bash
-# 杯垫大小、圆豆预览、要 PDF 打印版
+# usage + every available palette
+npx -y -p @javascribe/pindoupic pindoupic --help
+
+# 52 beads wide, round-bead preview, with usage stats
 npx -y -p @javascribe/pindoupic pindoupic \
   --image cat.png --width 52 --type cartoon --palette MARD/291 \
   --bead-shape circle --colors --output cat_bead.png
 ```
 
-## 给 AI Agent：MCP Server
+Progress goes to **stderr**; the color table goes to **stdout** (script friendly).
 
-`tools/list` 实测三个工具：`generate_bead_pattern`、`list_palettes`、`list_image_types`。
+## Options
+
+| Flag | Meaning |
+|------|---------|
+| `-i, --image <path>` | input image path (required) |
+| `-w, --width <n>` | pattern width in beads, default 50, range 10–200 (above ~160 the cell size auto-shrinks to fit the canvas) |
+| `-p, --palette <b/s>` | palette brand/sub, default `MARD/120`; `--help` lists every palette with its color count |
+| `-t, --type <id>` | preset: `cartoon`, `watercolor`, `illustration`, `lineart`, `photo`, `pixelart`, `logo`, `miniapp_fast` |
+| `--simplify-colors` | merge rare colors into neighbours (saves beads) |
+| `--format <png\|pdf>` | output format, default png |
+| `-o, --output <path>` | output path, default `<input>_bead.png` |
+| `--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) |
+| `--keep-bg` | keep the white background instead of transparent cells |
+| `--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 |
+
+Sizing guide: coasters & keychains 32–52; portraits & wall art 60–100; large pieces 100–200. Pixel art: `--type pixelart`. Line art: `--type lineart`.
+
+## For AI agents: MCP server
+
+`tools/list` exposes `generate_bead_pattern`, `list_palettes`, `list_image_types`.
 
 ```json
 {
@@ -75,54 +180,64 @@ npx -y -p @javascribe/pindoupic pindoupic \
 }
 ```
 
-`generate_bead_pattern` 入参（本机文件优先用 `image_path`）：
-
 ```json
-{ "image_path": "/abs/path/cat.png", "width": 52, "palette_sub": "291", "image_type": "cartoon" }
+{ "image_path": "/abs/path/cat.png", "width": 52, "palette_sub": "291", "image_type": "cartoon", "mirror": false }
 ```
 
-返回 JSON 含 `width`/`height`/`total_beads`/`colors_used`/`color_stats`，以及 `png_data_url`（base64，可直接落盘）和 `png_file`（本机临时文件路径）。
+The response contains `width`, `height`, `total_beads`, `colors_used`, `color_stats`, plus `png_data_url` (base64, ready to write) and `png_file` (a local temp path).
 
-## 给 AI Agent：Agent Skill 也随包发布
+## For AI agents: the Agent Skill ships inside the package
 
-装好包后，`skill/` 目录就在安装路径里——那是教 Agent 怎么选参数、怎么交付结果的操作手册（SKILL.md + 色板/预设对照表）：
+After installing, the `skill/` folder sits in the package directory — an operating manual that tells an agent how to pick parameters and deliver results:
 
 ```bash
-# Claude Code（全局技能目录）
-cp -r node_modules/@javascribe/pindoupic/skill/pindoupic-bead-pattern ~/.claude/skills/
+cp -r node_modules/@javascribe/pindoupic/skill/pindoupic-bead-pattern ~/.claude/skills/   # Claude Code, global
+cp -r node_modules/@javascribe/pindoupic/skill/pindoupic-bead-pattern .ai/skills/         # Qoder, this project
+```
+
+## Feedback from agents
 
-# Qoder / 其他宿主（当前项目技能目录）
-cp -r node_modules/@javascribe/pindoupic/skill/pindoupic-bead-pattern .ai/skills/
+Every chart printed adds a `FEEDBACK_REQUEST` line on stderr, prompting the agent to ask the user and send one note back:
+
+```bash
+pindoupic feedback --rating 4 --note "too many colors, prefer fewer beads" --agent "<host agent>"
 ```
 
-没有仓库访问权限的 Agent 也能拿到这份手册：`npm view @javascribe/pindoupic dist.tarball` 取地址后解包，或直接 `npm i @javascribe/pindoupic` 再看上面那条 `cp`。
+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
 
-| 场景 | 建议 |
-|------|------|
-| 杯垫 / 钥匙扣 | `--width 32`~`52` |
-| 头像 / 装饰画 | `--width 60`~`100` |
-| 大幅作品 | `--width 100`~`150` |
-| 颜色太多想省钱 | 加 `--simplify-colors` |
-| 像素画 / 游戏角色 | `--type pixelart --resize-mode nearest` |
-| 黑白线稿、简笔画 | `--type lineart` |
-| 真人照片 | `--type photo` |
+- Your image is processed locally and **never uploaded** anywhere.
+- Palettes and presets are bundled inside the package; generating does not consume server compute.
+- The first generation needs to reach pindoupic.com for a one-time activation; for offline environments self-host or contact us.
 
-## 限制
+## Need cell-level editing? Use the free official web tools
 
-- 只接受**图片**输入。想把文字做成图纸，用网页版免费的「文字转图纸」：https://www.pindoupic.com/text-to-bead-pattern
-- 新增色板/预设随包发布更新；请求包里没有的色板会直接报错并列出可用清单，不会静默换色板。
+This package handles image → chart. For **per-cell refinement**, 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` 下载包失败 / sharp 装不上 | 网络或镜像问题，重试或挂代理 |
-| 报「无法连接 pindoupic.com 获取算法密钥」 | 站点不可达或网络被拦。算法是密文分发、密钥在线领取，恢复联网后重试即可；离线场景请改用自托管（见上表） |
-| `色板 X/Y 不在本包内` | 按错误里列出的清单换型号，或升级本包版本 |
-| 想确认参数有没有生效 | `--cell-size` 显式指定即覆盖后台下发值 |
+| `npx` download or sharp install fails | network/registry issue — retry or use a proxy |
+| activation / authorization unavailable | pindoupic.com unreachable (offline, corporate network, DNS). Retry once the network is back |
+| `色板 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
 
-MIT。品牌与算法版权归 pindoupic.com。
+MIT. Brand and generator algorithm copyright pindoupic.com.