qrcode-skills

QR Code Generation & Decoding

完全ローカルで QR コードを生成・デコードします。ネットワークリクエストは不要です。

声明：

• 依存関係はすべて公開されているオープンソースライブラリです：すべての依存関係（Python：zxingcpp、Pillow、openpyxl、qrcode、Node.js：qrcode、qr-scanner-wechat、sharp、xlsx、archiver）は公開されているオープンソースプロジェクトです。PyPI / npm でソースコードとライセンスを確認できます
• すべての処理をローカルで実行します：生成とデコードはすべてユーザーのローカル環境で実行され、リモート API は呼び出さず、データもアップロードしません。デコード対象がリモート画像 URL の場合に限り、その画像をローカルにダウンロードしてからデコードします

QR コードを生成する URL（ファイルを保存せずにプレビュー可能）や、より高精度なデコードが必要な場合は、qrcode-remote-skills を使用できます：npx skills add caoliao/qrcode-remote-skills。

ランタイムの選択：Python または Node.js

すべてのスクリプトには Python 版と Node.js 版があり、機能とパラメーターは完全に同一です。スクリプトを実行する前に、必ずランタイムを選択してください。

選択手順（スクリプトの初回実行前に実施）：

1. Python が利用可能か確認します：python --version（または python3 --version）
2. Python が利用できない場合は、Node.js を確認します：node --version
3. 両方が利用できる場合は、デフォルトで Python を使用します

依存関係の確認と自動インストール：

ランタイムを選択した後、依存関係がインストール済みか確認します。不足している場合は、ユーザーに確認せずに自動インストールします：

• Python：pip list に主要なパッケージ（Pillow など）が含まれているか確認し、不足している場合は次を実行します：

  pip install -r requirements.txt
  

• Node.js：skill ディレクトリに node_modules/ が存在するか確認し、存在しない場合は次を実行します：

  npm install
  

インストール完了後にスクリプトを実行します。インストールに失敗した場合は、ユーザーに手動でインストールするよう案内します。

コマンド対応表：

機能	Python	Node.js
1 件生成して保存	python scripts/generate.py ...	node scripts/generate.js ...
1 件デコード	python scripts/decode.py ...	node scripts/decode.js ...
一括生成	python scripts/batch_generate.py ...	node scripts/batch_generate.js ...
一括デコード	python scripts/batch_decode.py ...	node scripts/batch_decode.js ...

すべてのパラメーター名と出力 JSON 形式は完全に同一です。python を node に、.py を .js に置き換えるだけです。

違いについて：

• Python 版のローカルデコードでは zxingcpp を使用し、"source": "zxing" を出力します
• Node.js 版のローカルデコードでは qr-scanner-wechat（OpenCV + WeChat のアルゴリズムに基づき、認識率がより高い）を使用し、"source": "wechat-qr" を出力します

---

QR コードの生成

テキストまたは URL を QR コード画像に変換し、ローカルファイルに保存します。

パラメーターの説明

パラメーター	必須	デフォルト値	説明
--data	はい	-	QR コードに含めるテキスト。900 文字以内を推奨
--output	はい	-	ローカルの保存先パス
--size	いいえ	400x400	画像サイズ。形式は WxH または単一の整数
--format	いいえ	png	出力形式：png（ビットマップ）または svg（ベクター）
--error-correction	いいえ	M	誤り訂正レベル：L(7%) / M(15%) / Q(25%) / H(30%)
--border	いいえ	2	境界線の幅（モジュール単位）

使用手順

ユーザーが保存先を指定しているかどうかにかかわらず、スクリプトを実行して QR コードファイルを生成する必要があります。

1. QR コードにするテキストをユーザーから取得します
2. 保存先を決定します：
   • ユーザーがパスを指定した場合（例：D:\qr.png に保存、デスクトップに保存）→ 指定されたパスを使用します
   • ユーザーがパスを指定していない場合 → 現在の作業ディレクトリにある qrcode.png を使用します（svg 形式の場合は qrcode.svg）
3. スクリプトを実行して生成します

python scripts/generate.py --data <文本内容> --output <保存路径> [--size 400x400] [--format png] [--error-correction M] [--border 2]

スクリプトの出力 JSON：

{"file": "D:\\path\\to\\qrcode.png"}

失敗した場合：

{"error": "生成失败: ..."}

ユーザーへの表示形式：

二维码已生成并保存到本地：

**本地文件：** <file>

例

ユーザー入力：https://example.com を内容とする QR コードを生成して

実行：python scripts/generate.py --data "https://example.com" --output "qrcode.png"

二维码已生成并保存到本地：

**本地文件：** D:\workspace\qrcode.png

ユーザー入力：Hello World を内容とする QR コードをデスクトップに保存して。SVG 形式、最高の誤り訂正で

実行：python scripts/generate.py --data "Hello World" --output "C:\Users\xxx\Desktop\qrcode.svg" --format svg --error-correction H

二维码已生成并保存到本地：

**本地文件：** C:\Users\xxx\Desktop\qrcode.svg

一括生成

ユーザーから Excel/CSV/TXT ファイルが提供され、QR コードの一括生成を求められた場合は、scripts/batch_generate.py を使用します。

操作手順：

1. ユーザーから一括処理用のデータファイルを受け取ります
2. スクリプトを実行します
3. need_column が返された場合は、列情報を表示してユーザーに列を選択してもらい、--column を付けて再実行します
4. 成功したら、結果をユーザーに報告します

列の検出ロジック（Excel/CSV）：

• 自動検出：先頭行のヘッダーを調べ、キーワード（data/text/content/url/内容/テキスト/データ/リンクなど）と照合します
• 列が 1 つだけの場合は、その列を使用します
• 判別できない場合、スクリプトは need_column JSON を返します。この場合、ユーザーに列を指定してもらう必要があります

TXT： 1 行につき 1 件のデータを指定します。列の選択は不要です。

python scripts/batch_generate.py --input <文件> --output-dir <输出目录> [--column <列名或索引>] [--zip] [--size 400] [--format png] [--error-correction M] [--border 2]

• --output-dir：画像の出力ディレクトリ（必須）
• インデックスをファイル名として使用します（1.png, 2.png, ...）
• --zip：出力ディレクトリを zip にまとめます

スクリプトの出力 JSON：

{"total": 100, "success": 98, "failed": 2, "output_dir": "D:\\output", "zip_file": "D:\\output.zip", "errors": [...]}

ユーザーへの表示形式：

批量生成完成：共 <total> 个，成功 <success> 个，失败 <failed> 个
输出目录：<output_dir>
ZIP 文件：<zip_file>（仅打包时显示）

---

QR コードのデコード

QR コード画像から内容を読み取り、完全にローカルでデコードします。

事前依存関係

初回使用前に、依存関係をインストールする必要があります（skill ディレクトリで実行）：

• Python：pip install -r requirements.txt（依存関係：zxingcpp + Pillow）
• Node.js：npm install（依存関係：qr-scanner-wechat + sharp）

ケース 1：1 枚の画像をデコード

Shell ツールで scripts/decode.py を実行します。ローカルファイルと画像 URL に対応しています：

python scripts/decode.py <图片路径或URL>
python scripts/decode.py --file <本地文件路径>
python scripts/decode.py --url <图片URL>

ユーザーが画像を直接送信した場合の処理：

• ユーザーが会話に画像を貼り付ける、ドラッグ＆ドロップする、または添付すると、画像は添付ファイルとして提供され、ファイルパスからアクセスできます
• 画像のローカルパスを取得したら、そのまま decode.py --file <パス> に渡します
• @ でファイルが参照されている場合も、同じファイルパスを使用します

SKILL_DIR の特定：スクリプトのパスは、この skill ディレクトリを基準としています。実行時には skill ディレクトリに cd するか、絶対パスを使用する必要があります。

スクリプトの出力 JSON で、source フィールドからデコードエンジンを判別します：

{"source": "zxing", "contents": ["解码内容"]}

失敗した場合：

{"error": "无法解码: 本地 zxing 未识别到二维码"}

ユーザーへの表示形式：

QR コードが 1 つの場合：

二维码解码结果（via <source>）：
- 内容：<解码出的文本>

QR コードが複数の場合：

二维码解码结果（共识别到 N 个二维码，via <source>）：
1. <内容1>
2. <内容2>

场景二：批量解码

当用户提供 Excel/CSV/TXT 文件要求批量解码二维码图片时，使用 scripts/batch_decode.py：

python scripts/batch_decode.py --input <文件> [--column <列名或索引>] [--output-txt <输出TXT路径>]

列检测逻辑（Excel/CSV）：

• 自动检测：扫描首行表头，匹配关键词（url/link/image/img/图片/链接/网址/二维码 等）
• 若只有一列，直接使用
• 若无法判断，脚本返回 need_column JSON，此时需要询问用户指定哪一列

TXT： 每行一个图片路径或 URL，无需列选择。

默认行为： 在原文件中新增"解码结果"列（Excel 新增列 / CSV 新增列），直接回写原文件。

单独输出 TXT： 用户明确要求时加 --output-txt 参数，所有结果按行分隔写入 TXT。

未解析的图片： 对应行写入 未解析到二维码。

脚本输出 JSON：

{"total": 50, "success": 48, "failed": 2, "output_file": "D:\\data.xlsx", "output_txt": null}

需要用户选列时：

{"need_column": true, "columns": ["名称", "图片链接", "备注"], "preview": [...], "message": "无法自动判断 URL 列，请指定 --column 参数"}

交互流程：

1. 执行脚本
2. 若返回 need_column，将 columns 和 preview 展示给用户，询问使用哪一列
3. 用户回答后，加上 --column 重新执行
4. 成功后向用户报告结果统计

呈现给用户的格式：

批量解码完成：共 <total> 个，成功 <success> 个，失败 <failed> 个
结果已写入：<output_file>
TXT 输出：<output_txt>（仅单独输出时显示）

---

注意事项

• 本地优先：所有操作均在本地完成，无需网络（除非解码的输入是远程图片 URL，此时需下载图片到本地再解码）
• 生成二维码始终需要执行脚本，输出为本地文件
• 解码二维码仅使用本地库（Python: zxingcpp / Node: qr-scanner-wechat），不依赖任何远程服务
• data 建议不超过 900 字符
• 批量操作时，若脚本返回 need_column，必须先向用户展示列信息并确认后再重新执行

工程结构

qrcode-skills/
├── SKILL.md              # 主指令文件
├── requirements.txt      # Python 依赖
├── package.json          # Node.js 依赖
└── scripts/
    ├── generate.py / .js       # 单个生成并保存到本地
    ├── batch_generate.py / .js # 批量生成图片
    ├── decode.py / .js         # 单个解码（纯本地）
    └── batch_decode.py / .js   # 批量解码（纯本地）