{"skill":{"slug":"qrcode-remote-skills","displayName":"qrcode-remote","summary":"Generate and decode QR codes using CaoLiao QR Code API. Use when the user wants to create a QR code from text/URL, decode/read QR code content from an image,...","description":"---\r\nname: qrcode-remote-skills\r\ndescription: Generate and decode QR codes using CaoLiao QR Code API. Use when the user wants to create a QR code from text/URL, decode/read QR code content from an image, or asks about QR code generation and scanning.\r\n---\r\n\r\n# QR Code Generation & Decoding\r\n\r\n使用草料二维码开放 API 生成和解码二维码，无需 API Key。\r\n\r\n## 安全声明\r\n\r\n- **隐私保护**：上传到服务端解码的二维码图片均为临时文件，过一段时间后会自动删除，不会长期存储，保障用户隐私。\r\n- **依赖透明**：本 skill 使用的第三方库（zxingcpp、Pillow、qrcode、草料 API 等）均为公开、开源的第三方库，可自行审查。\r\n- **本地优先**：解码优先在本地完成，仅在本地失败时才调用远程 API，减少数据传输。\r\n\r\n\r\n## 运行时选择：Python 或 Node.js\r\n\r\n所有脚本同时提供 Python 和 Node.js 两个版本，功能和参数完全一致。**执行任何脚本前，先确定运行时。**\r\n\r\n**选择策略（首次执行脚本前完成）：**\r\n\r\n1. 检测 Python 是否可用：`python --version`（或 `python3 --version`）\r\n2. 若 Python 不可用，检测 Node.js：`node --version`\r\n3. 两者都有时默认用 Python\r\n\r\n**依赖检查与自动安装：**\r\n\r\n确定运行时后，检查依赖是否已安装。若缺失则自动安装，无需询问用户：\r\n\r\n- **Python**：检查 `pip list` 中是否包含关键包（如 `Pillow`），若缺失则执行：\r\n  ```bash\r\n  pip install -r requirements.txt\r\n  ```\r\n- **Node.js**：检查 skill 目录下是否存在 `node_modules/`，若缺失则执行：\r\n  ```bash\r\n  npm install\r\n  ```\r\n\r\n安装完成后再执行脚本。若安装失败，提示用户手动安装。\r\n\r\n**命令对照表：**\r\n\r\n| 功能 | Python | Node.js |\r\n|------|--------|---------|\r\n| 单个生成保存 | `python scripts/generate.py ...` | `node scripts/generate.js ...` |\r\n| 单个解码 | `python scripts/decode.py ...` | `node scripts/decode.js ...` |\r\n| 批量生成 | `python scripts/batch_generate.py ...` | `node scripts/batch_generate.js ...` |\r\n| 批量解码 | `python scripts/batch_decode.py ...` | `node scripts/batch_decode.js ...` |\r\n\r\n所有参数名、输出 JSON 格式完全相同，仅将 `python` 替换为 `node`、`.py` 替换为 `.js`。\r\n\r\n**差异说明：**\r\n- Python 版本地解码使用 `zxingcpp`，输出 `\"source\": \"zxing\"`\r\n- Node.js 版本地解码使用 [`qr-scanner-wechat`](https://github.com/antfu/qr-scanner-wechat)（基于 OpenCV + 微信算法，识别率更高），输出 `\"source\": \"wechat-qr\"`\r\n\r\n---\r\n\r\n## 生成二维码\r\n\r\n将文本或 URL 编码为二维码图片，直接返回图片 URL 并提供预览。\r\n\r\n**API 端点：** `https://api.2dcode.biz/v1/create-qr-code`\r\n\r\n### 使用步骤\r\n\r\n1. 获取用户要编码的文本内容\r\n2. 对文本内容进行 URL 编码\r\n3. 拼接生成 API URL\r\n4. 将 URL 直接返回给用户，并以 Markdown 图片语法提供预览\r\n\r\n### 参数说明\r\n\r\n| 参数 | 必选 | 默认值 | 说明 |\r\n|------|------|--------|------|\r\n| data | 是 | - | 二维码中的文本内容（需 URL 编码），建议不超过 900 字符 |\r\n| size | 否 | 256x256 | 图片尺寸，格式 `WxH` 或单个整数 |\r\n| format | 否 | png | 输出格式：`png`（位图）或 `svg`（矢量） |\r\n| error_correction | 否 | M | 纠错级别：L(7%) / M(15%) / Q(25%) / H(30%) |\r\n| border | 否 | 2 | 边框宽度（码点为单位） |\r\n\r\n### 场景一：仅生成（默认）\r\n\r\n用户没有明确要求保存到本地时，直接拼接 URL 返回，**无需执行脚本**。\r\n\r\n输出格式：\r\n\r\n```\r\n二维码已生成：\r\n\r\n![QR Code](https://api.2dcode.biz/v1/create-qr-code?data=<URL编码文本>&size=400x400)\r\n\r\n**二维码链接：** https://api.2dcode.biz/v1/create-qr-code?data=<URL编码文本>&size=400x400\r\n```\r\n\r\n### 场景二：生成并保存到本地\r\n\r\n当满足以下任一条件时，使用 Shell 工具执行 `scripts/generate.py` 保存到本地：\r\n\r\n- 用户明确要求\"保存到本地\"、\"下载\"、\"导出文件\"\r\n- 用户指定了具体的保存路径（如 `保存到 D:\\qr.png`、`放到桌面`、`存到 ./output/` 等）\r\n\r\n```bash\r\npython scripts/generate.py --data <文本内容> --output <保存路径> [--size 400x400] [--format png] [--error-correction M] [--border 2]\r\n```\r\n\r\n- `--output` 为用户指定的保存路径，若用户未指定文件名则默认使用 `qrcode.png`（svg 格式用 `qrcode.svg`）\r\n- 脚本会自动创建不存在的父目录\r\n\r\n脚本输出 JSON：\r\n\r\n```json\r\n{\"url\": \"https://api.2dcode.biz/v1/create-qr-code?data=...\", \"file\": \"D:\\\\path\\\\to\\\\qrcode.png\"}\r\n```\r\n\r\n失败时：\r\n\r\n```json\r\n{\"error\": \"下载失败: ...\"}\r\n```\r\n\r\n呈现给用户的格式：\r\n\r\n```\r\n二维码已生成并保存到本地：\r\n\r\n![QR Code](<url>)\r\n\r\n**二维码链接：** <url>\r\n**本地文件：** <file>\r\n```\r\n\r\n### 示例\r\n\r\n用户输入：`帮我生成一个二维码，内容是 https://example.com`\r\n\r\n```\r\n二维码已生成：\r\n\r\n![QR Code](https://api.2dcode.biz/v1/create-qr-code?data=https%3A%2F%2Fexample.com&size=400x400)\r\n\r\n**二维码链接：** https://api.2dcode.biz/v1/create-qr-code?data=https%3A%2F%2Fexample.com&size=400x400\r\n```\r\n\r\n用户输入：`生成一个二维码保存到桌面，内容是 Hello World，SVG 格式、最高纠错`\r\n\r\n执行：`python scripts/generate.py --data \"Hello World\" --output \"C:\\Users\\xxx\\Desktop\\qrcode.svg\" --format svg --error-correction H`\r\n\r\n```\r\n二维码已生成并保存到本地：\r\n\r\n![QR Code](https://api.2dcode.biz/v1/create-qr-code?data=Hello%20World&size=400x400&format=svg&error_correction=H)\r\n\r\n**二维码链接：** https://api.2dcode.biz/v1/create-qr-code?data=Hello%20World&size=400x400&format=svg&error_correction=H\r\n**本地文件：** C:\\Users\\xxx\\Desktop\\qrcode.svg\r\n```\r\n\r\n### 场景三：批量生成\r\n\r\n当用户提供 Excel/CSV/TXT 文件要求批量生成二维码时，**先询问用户需要生成 URL 链接还是图片文件**，然后使用 `scripts/batch_generate.py` 对应模式执行。\r\n\r\n**交互流程：**\r\n\r\n1. 用户提供批量数据文件\r\n2. **询问用户**：需要生成二维码 URL 链接，还是生成图片保存到本地？\r\n3. 执行对应模式的脚本\r\n4. 若返回 `need_column`，展示列信息，询问用户选哪一列，加 `--column` 重新执行\r\n5. 成功后向用户报告结果\r\n\r\n**列检测逻辑（Excel/CSV）：**\r\n- 自动检测：扫描首行表头，匹配关键词（data/text/content/url/内容/文本/数据/链接 等）\r\n- 若只有一列，直接使用\r\n- 若无法判断，脚本返回 `need_column` JSON，此时**需要询问用户指定哪一列**\r\n\r\n**TXT：** 每行一条数据，无需列选择。\r\n\r\n#### URL 模式（生成链接）\r\n\r\n直接拼接二维码 URL 列表返回，无需网络、无需本地库，速度最快。\r\n\r\n```bash\r\npython scripts/batch_generate.py --input <文件> --mode url [--column <列名或索引>] [--output-txt <保存路径>] [--size 400] [--error-correction M] [--border 2]\r\n```\r\n\r\n- 不加 `--output-txt`：返回 JSON 中直接包含 `urls` 数组\r\n- 加 `--output-txt`：额外将链接列表保存到 TXT 文件（每行一个链接）\r\n\r\n脚本输出 JSON：\r\n\r\n```json\r\n{\"mode\": \"url\", \"total\": 100, \"urls\": [\"https://api.2dcode.biz/v1/create-qr-code?data=...\", ...], \"output_txt\": \"D:\\\\output\\\\urls.txt\"}\r\n```\r\n\r\n呈现给用户的格式（数量较少时直接列出）：\r\n\r\n```\r\n批量生成完成，共 <total> 个二维码链接：\r\n1. <url1>\r\n2. <url2>\r\n...\r\n```\r\n\r\n数量较多时（>20）建议保存到 TXT：\r\n\r\n```\r\n批量生成完成，共 <total> 个二维码链接，已保存到：<output_txt>\r\n```\r\n\r\n#### Image 模式（生成图片）\r\n\r\n生成图片保存到本地目录。默认用本地 `qrcode` 库，单条失败时 API 兜底。\r\n\r\n```bash\r\npython scripts/batch_generate.py --input <文件> --mode image --output-dir <输出目录> [--column <列名或索引>] [--zip] [--size 400] [--format png] [--error-correction M] [--border 2] [--use-api]\r\n```\r\n\r\n- 默认本地 `qrcode` 库生成，本地库未安装时报错提示安装\r\n- 单条本地生成失败时自动用远程 API 兜底\r\n- `--use-api`：强制全部走远程 API\r\n- 以索引命名（`1.png`, `2.png`, ...）\r\n- `--zip`：打包输出目录为 zip\r\n\r\n脚本输出 JSON：\r\n\r\n```json\r\n{\"mode\": \"image\", \"source\": \"local\", \"total\": 100, \"success\": 98, \"failed\": 2, \"api_fallback\": 3, \"output_dir\": \"D:\\\\output\", \"zip_file\": \"D:\\\\output.zip\", \"errors\": [...]}\r\n```\r\n\r\n呈现给用户的格式：\r\n\r\n```\r\n批量生成完成（via <source>）：共 <total> 个，成功 <success> 个，失败 <failed> 个\r\n输出目录：<output_dir>\r\nZIP 文件：<zip_file>（仅打包时显示）\r\n```\r\n\r\n---\r\n\r\n## 解码二维码\r\n\r\n从二维码图片中读取/解码内容。优先使用本地 zxing 解码，失败时自动回退到草料 API。\r\n\r\n### 前置依赖\r\n\r\n首次使用前，需安装 Python 依赖（skill 目录下执行）：\r\n\r\n```bash\r\npip install -r requirements.txt\r\n```\r\n\r\n### 解码策略（所有解码场景共用）\r\n\r\n1. **本地 zxing 优先**：使用 `zxingcpp` + `Pillow` 在本地解码，速度快、无网络依赖\r\n2. **API 回退**：若 zxing 未安装或解码失败，自动调用草料 API（`https://api.2dcode.biz/v1/read-qr-code`）\r\n   - 本地文件 → POST multipart 上传\r\n   - 图片 URL → GET 请求\r\n\r\n### 场景一：单张解码\r\n\r\n通过 Shell 工具执行 `scripts/decode.py`，支持本地文件、图片 URL、用户直接发送的图片：\r\n\r\n```bash\r\npython scripts/decode.py <图片路径或URL>\r\npython scripts/decode.py --file <本地文件路径>\r\npython scripts/decode.py --url <图片URL>\r\npython scripts/decode.py --force-api <图片路径或URL>\r\n```\r\n\r\n- `--force-api`：跳过本地 zxing，强制使用远程 API 解码。当用户明确要求用 API 解码时使用。\r\n\r\n**用户直接发送图片时的处理：**\r\n- 用户在对话中粘贴/拖入/附加图片时，图片会作为附件提供，可通过文件路径访问\r\n- 获取到图片的本地路径后，直接传给 `decode.py --file <路径>` 即可\r\n- 若图片是通过 @ 引用的文件，同样使用其文件路径\r\n\r\n**SKILL_DIR 定位**：脚本路径相对于本 skill 目录，执行时需 `cd` 到 skill 目录或使用绝对路径。\r\n\r\n脚本输出 JSON，根据 `source` 字段判断解码来源：\r\n\r\n```json\r\n{\"source\": \"zxing\", \"contents\": [\"解码内容\"]}\r\n{\"source\": \"api\", \"contents\": [\"解码内容\"]}\r\n```\r\n\r\n失败时：\r\n\r\n```json\r\n{\"error\": \"无法解码: 本地 zxing 和远程 API 均未识别到二维码\"}\r\n```\r\n\r\n呈现给用户的格式：\r\n\r\n单个二维码：\r\n\r\n```\r\n二维码解码结果（via <source>）：\r\n- 内容：<解码出的文本>\r\n```\r\n\r\n多个二维码：\r\n\r\n```\r\n二维码解码结果（共识别到 N 个二维码，via <source>）：\r\n1. <内容1>\r\n2. <内容2>\r\n```\r\n\r\n### 场景二：批量解码\r\n\r\n当用户提供 Excel/CSV/TXT 文件要求批量解码二维码图片时，使用 `scripts/batch_decode.py`：\r\n\r\n```bash\r\npython scripts/batch_decode.py --input <文件> [--column <列名或索引>] [--output-txt <输出TXT路径>]\r\n```\r\n\r\n**列检测逻辑（Excel/CSV）：**\r\n- 自动检测：扫描首行表头，匹配关键词（url/link/image/img/图片/链接/网址/二维码 等）\r\n- 若只有一列，直接使用\r\n- 若无法判断，脚本返回 `need_column` JSON，此时**需要询问用户指定哪一列**\r\n\r\n**TXT：** 每行一个图片 URL，无需列选择。\r\n\r\n**默认行为：** 在原文件中新增\"解码结果\"列（Excel 新增列 / CSV 新增列），直接回写原文件。\r\n\r\n**单独输出 TXT：** 用户明确要求时加 `--output-txt` 参数，所有结果按行分隔写入 TXT。\r\n\r\n**未解析的图片：** 对应行写入 `未解析到二维码`。\r\n\r\n脚本输出 JSON：\r\n\r\n```json\r\n{\"total\": 50, \"success\": 48, \"failed\": 2, \"output_file\": \"D:\\\\data.xlsx\", \"output_txt\": null}\r\n```\r\n\r\n需要用户选列时：\r\n\r\n```json\r\n{\"need_column\": true, \"columns\": [\"名称\", \"图片链接\", \"备注\"], \"preview\": [...], \"message\": \"无法自动判断 URL 列，请指定 --column 参数\"}\r\n```\r\n\r\n**交互流程：**\r\n\r\n1. 执行脚本\r\n2. 若返回 `need_column`，将 `columns` 和 `preview` 展示给用户，询问使用哪一列\r\n3. 用户回答后，加上 `--column` 重新执行\r\n4. 成功后向用户报告结果统计\r\n\r\n呈现给用户的格式：\r\n\r\n```\r\n批量解码完成：共 <total> 个，成功 <success> 个，失败 <failed> 个\r\n结果已写入：<output_file>\r\nTXT 输出：<output_txt>（仅单独输出时显示）\r\n```\r\n\r\n---\r\n\r\n## 注意事项\r\n\r\n- 生成二维码默认无需网络请求，直接拼接 URL 即可；保存本地或批量生成时才需要下载\r\n- 解码二维码优先本地库（Python: zxingcpp / Node: qr-scanner-wechat），仅在本地失败时才调用远程 API\r\n- data 参数需要正确的 URL 编码（空格→%20，中文等特殊字符需编码）\r\n- 草料 API 无需认证、免费使用，但禁止恶意滥用\r\n- 批量操作时，若脚本返回 `need_column`，必须先向用户展示列信息并确认后再重新执行\r\n\r\n## 工程结构\r\n\r\n```\r\nqrcode-remote-skills/\r\n├── SKILL.md              # 主指令文件\r\n├── reference.md          # API 完整参考文档\r\n├── requirements.txt      # Python 依赖\r\n├── package.json          # Node.js 依赖\r\n└── scripts/\r\n    ├── generate.py / .js       # 单个生成并保存到本地\r\n    ├── batch_generate.py / .js # 批量生成（URL 链接 / 图片）\r\n    ├── decode.py / .js         # 单个解码（本地优先 + API 回退）\r\n    └── batch_decode.py / .js   # 批量解码（回写原文件 / 输出 TXT）\r\n```\r\n\r\n## 更多信息\r\n\r\n- 完整 API 参数详情见 [reference.md](reference.md)\r\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":614,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1773296697162,"updatedAt":1778491848315},"latestVersion":{"version":"1.0.0","createdAt":1773296697162,"changelog":"- Initial release.","license":"MIT-0"},"metadata":null,"owner":{"handle":"hinisal","userId":"s1749k63vbqddvv8a31hb98eyh83gdfy","displayName":"hiNISAL","image":"https://avatars.githubusercontent.com/u/19162201?v=4"},"moderation":null}