qr-code-skill

二维码生成 + 识别技能。使用成熟库：qrcode（生成）+ pyzbar/ZBar（识别）。

功能

1. 生成二维码

• 默认大小 400×400px，支持 300 / 400 / 500 / 600 px
• 默认容错率 15%，支持 7% / 15% / 25% / 30%（对应 QR 纠错级别 L/M/Q/H）
• 默认版本 4（33×33 模块），范围 1（21×21）~ 40（177×177）
• 默认边距 3 个色块，支持 1 / 2 / 3 / 4
• 图片保存到 test_output/qr-code-skill/，命名含尺寸/版本/容错/边距信息
• 每次任务都保留完整记录（历史可追溯）：每次生成/识别都会产生 1 张二维码图 + 1 个对应 json，全部累积保留，不覆盖、不清理。
• json 与图片一一对应：结果 json 与二维码图同名同时间戳（图片 .png → _result.json，如 20260825_113159_qr_400x400_v4_ec15_b3.png ↔ 20260825_113159_qr_400x400_v4_ec15_b3_result.json），保证多次任务（含同一秒多次）互不冲突、均可追溯。
• 结果 json 保存：模式/内容/图片路径/参数/result 等完整信息。

2. 识别二维码

• 从图片文件读取二维码内容（PNG/JPG/BMP 等常见格式）
• 支持识别图片中的多个二维码，返回列表

实现原理

• 生成：qrcode 库构造 QRCode（指定 version / error_correction / border），以 整数倍 box_size 生成（模块为纯色块），若与目标尺寸有偏差再用 NEAREST 最近邻对齐到精确目标尺寸。全程不产生灰阶（中间灰阶像素=0），保证模块边缘为清晰的纯黑/纯白硬边，与 cli.im 等网站出图同样清晰。
• 识别：pyzbar.pyzbar.decode() 读取图片中所有二维码并解码 UTF-8 内容。
• 版本约束：内容过长会超出版本容量，脚本会给出友好提示（建议增大版本或降低容错率），并 passed=false。

环境依赖

• Python（当前 3.9.5 已验证可用）
• qrcode 8.x（生成）
• pyzbar 0.1.x + ZBar（识别；Windows 下 pyzbar 0.1.9 win_amd64 wheel 已内置 ZBar DLL）
• Pillow（图像缩放/打开）

安装：

python -m pip install qrcode pyzbar

入口脚本

• scripts/qr_code.py（生成 + 识别主脚本）

用法

生成（默认参数）

# 默认 400x400, 容错15%, 版本4(33x33), 边距3
python skills/qr-code-skill/scripts/qr_code.py --data '{"cameraID":"7069942000888999","P":"1TU8Z009"}'

生成（指定参数）

# 500x500, 容错25%, 版本8, 边距2
python skills/qr-code-skill/scripts/qr_code.py --data '{"cameraID":"xxx"}' \
    --size 500 --error-correction 25 --version 8 --border 2

# 只保留最终一张：加 --clean，执行前清空旧产物
python skills/qr-code-skill/scripts/qr_code.py --data '{"cameraID":"xxx"}' --clean

> 注：每次任务结果 json 与二维码图同名同时间戳（.png→_result.json）并全部保留，历史可追溯；如想清空历史用 --clean。

识别

python skills/qr-code-skill/scripts/qr_code.py --decode <图片路径.png>

> ⚠️ PowerShell 传 JSON 转义提示：PowerShell 会把双引号当文本边界吞掉，导致 JSON 引号丢失（{"a":"1"} 变 {a:1}）。请在命令行用单引号包裹整个 JSON（如上例），或在 Python/程序中直接调用。脚本本身对引号完全保真（已实测：生成内容 = 识别内容，含双引号）。

参数

> 生成模式必须给 --data；识别模式必须给 --decode；二者互斥。

输出

结果 JSON 输出到 test_output/qr-code-skill/（生成图片也在此目录）。

生成结果 JSON

{
  "mode": "generate",
  "data": "{\"cameraID\":\"7069942000888999\",\"P\":\"1TU8Z009\"}",
  "size": 400,
  "error_correction": 15,
  "version": 4,
  "modules": 33,
  "border": 3,
  "output_file": "C:\\...\\test_output\\qr-code-skill\\20260825_105755_qr_400x400_v4_ec15_b3.png",
  "result": {
    "passed": true,
    "messages": "二维码已生成: C:\\...\\20260825_105755_qr_400x400_v4_ec15_b3.png"
  }
}

识别结果 JSON

{
  "mode": "decode",
  "image": "C:\\...\\xxx.png",
  "decoded": ["{\"cameraID\":\"7069942000888999\",\"P\":\"1TU8Z009\"}"],
  "count": 1,
  "result": {
    "passed": true,
    "messages": "识别到 1 个二维码"
  }
}

字段说明

> 失败体现：参数非法（尺寸/容错/版本/边距不支持）、内容超出版本容量、图片打不开/无二维码时，result.passed=false，messages 给出明确原因。

变更记录

• v1.0.1（2026-08-25）：三处改进。
  1. 修复二维码模糊：v1.0.0 用 1px/模块 生成后做 LANCZOS 缩放，非整数倍缩放产生亚像素灰阶、模块边缘发灰"蒙蒙的"。改为整数倍 box_size 生成（纯色模块块），偏差用 NEAREST 最近邻对齐目标尺寸，全程不产生灰阶。验证：300/400/500/600px 生成后中间灰阶像素=0（100% 纯黑白硬边），与 cli.im 同等清晰。
  2. 落盘结果 JSON：生成/识别成功后结果写入与图片同名同时间戳的 json（图片 .png → _result.json），保存二维码描述信息（尺寸/容错/版本/模块/边距）、图片路径、内容。
  3. 保留全部历史记录：每次任务（生成/识别）独立成对产出「1 图 + 1 json」，全部累积保留、互不覆盖（含同一秒多次也各自成对），多次任务可完整追溯。（--clean 保留为手动清理历史的可选开关）
• v1.0.0（2026-08-25）：初版。
  1. 生成：qrcode 库，默认 400px/容错15%/版本4/边距3，支持 300~600px、7/15/25/30% 容错、版本1~40、边距1~4。
  2. 识别：pyzbar(ZBar)，支持多二维码识别、UTF-8 解码。
  3. 保存到 test_output/qr-code-skill/，结果 JSON 含 result.passed/messages。
• 验证：给定数据 {"cameraID":"7069942000888999","P":"1TU8Z009"} 生成→识别闭环，引号保真；多参数组合（300~600px×容错×版本×边距）生成+解码全部通过；非法参数与超容量场景友好报错。