离线二维码生成满分技能

体系归属：tokeny 智能桌面工具 · 二维码生成技能 铁三角逻辑：输入可识别（内容/格式/尺寸）→ 处理可复现（参数/版本全记录）→ 输出可验证（可扫文件 + 生成报告） 统一参数：内容 · 输出格式 · 尺寸/颜色 质量线（5 倍要求）：RACE-T 五维全 5 分 —— Reliability 5 / Adaptability 5 / Convention 5 / Effectiveness 5 / Trust 5 核心承诺：纯本地运行，不联网、不调用 AI 生图、不消耗积分、不弹广告，秒级出图。

---

一、环境准备（必须先做）

本技能专为 tokeny 智能桌面工具 打磨：其运行环境实测存在四项限制——依赖需预装、PowerShell 不支持 && 链式命令、系统字体目录访问受限、删除用户文件操作会被拦截。以下所有示例均基于 tokeny 环境给出，确保一次跑通。

本技能纯本地运行，需要以下 Python 包。首次使用前请安装依赖：

pip install -r requirements.txt

requirements.txt 内容：

qrcode[pil]>=7.4.2
pillow>=10.0.0
opencv-python>=4.8.0

tokeny 实测 · Windows PowerShell 注意：tokeny 内置的 PowerShell 不支持 && 链式命令，请分步执行：

# 第一步：进入技能目录
cd 你的tokeny技能目录\qrcode-generator   # 即本技能所在的文件夹

# 第二步：安装依赖
pip install -r requirements.txt

# 第三步：测试生成
python gen_qr.py "https://skillhub.cn/skills/user_858115ff/agnes-cn-key-wizard" -o test.png --verify

依赖缺失时脚本会主动提示：请执行 pip install -r requirements.txt，不再让用户盲目排查。

二、30 秒快速上手

三步：①把要编码的内容（URL、文本、手机号、Wi-Fi 信息等）给我；②我调用本地 qrcode 库生成 PNG/SVG；③你拿到可直接扫码的图片 + 一份生成报告。

三条直接能用的指令（复制即可）：

• 「把这个网址生成二维码：https://skillhub.cn/skills/user_858115ff/agnes-cn-key-wizard，保存到桌面。」
• 「给我生成一个 Wi-Fi 二维码，SSID 是 ClassRoom-5G，密码 12345678，WPA 加密。」
• 「把这 5 个链接批量生成二维码，每张 300×300 像素，黑色模块白色底。」

---

三、核心参数（全库统一 3 项）

必填参数

可选参数

---

四、信息缺失固定追问模板

必须一字不差引用下列话术（可在其后追加本技能专属补充项 1 条）：

为保障二维码可扫且符合预期，请补充以下信息：①内容：要编码的 URL、文本或其他数据；②输出格式：PNG 还是 SVG；③尺寸/颜色要求：默认 10px 模块黑白即可，如需彩色或中心 logo 请告知。缺少关键参数无法生成可验证成品。

（专属补充项示例：若内容含中文或特殊符号，请告知是否需要以 UTF-8 编码直接写入，默认已支持中文。）

---

五、适用场景 / 不适用场景

• 【适用场景】

  1. 把 SkillHub 技能主页地址生成二维码，放到公众号或海报里扫码直达
  2. 把公众号文章链接、个人名片、电话号码生成二维码
  3. 生成 Wi-Fi 连接二维码，贴到教室/办公室
  4. 把活动报名链接、收款码、群聊邀请生成二维码
  5. 批量生成带统一 logo 的品牌二维码
  6. 生成高分辨率 SVG 矢量二维码，用于印刷物料
  7. 把长文本（如课程简介）生成二维码
  8. 给 Agnes/tokeny 推广物料添加二维码
  9. 生成纯色/渐变背景的个性二维码
  10. 需要离线、不消耗积分、秒级出图的任何二维码任务

• 【不适用场景】

  1. 生成违反法律法规或平台规则内容的二维码（如诈骗、色情、赌博链接）
  2. 生成用于伪造、仿冒他人官方账号/收款码的二维码
  3. 将二维码用于绕过安全验证、票务欺诈、虚假签到
  4. 在 logo 占比过大导致无法扫描时仍坚持原设计
  5. 要求艺术化二维码（如 AI 重绘导致扫码失败）—— 本技能优先保证可扫
  6. 需要动态/活码（扫码后内容可变）—— 本技能只生成静态二维码

---

六、工作流程（铁三角五步法）

第一步 · 参数校验（输入可识别）

• 做什么：确认内容、输出格式、尺寸/颜色三要素；检查内容是否为空、是否含非法字符。
• 产出：参数确认单。
• 质量红线：内容为空 → 拒绝并提示；输出格式不支持 → 改为 PNG 或 SVG 并告知。

第二步 · 内容编码（可识别）

• 做什么：按 UTF-8 编码内容；对 URL 自动去除首尾空格；对 Wi-Fi 串按 WIFI:T:WPA;S:SSID;P:密码;; 格式封装。
• 产出：规范化后的待编码字符串。
• 质量红线：中文/特殊符号必须正确编码，不得出现乱码。

第三步 · 生成二维码（可复现）

• 做什么：调用本地 qrcode 库生成 QR 矩阵；按给定版本/box_size/border/error_correction 渲染；PNG 支持颜色与 logo。
• 产出：PNG/SVG 文件 + 所用参数记录。
• 质量红线：所有参数写入报告，保证他人用同样参数可复现同一二维码。

第四步 · 可扫性验证（可验证）

• 做什么：尝试用 pyzbar 或二维码库自带方法解码，确认内容与输入一致；若含 logo，额外验证仍能识别。
• 产出：验证结果（通过 / 警告 / 失败）。
• 质量红线：验证失败必须明确提示，不得交付无法扫描的图片。

第五步 · 成品交付

• 做什么：交付二维码文件 + 生成报告；批量场景打包并附总览表。
• 产出：成品文件 + 报告。
• 质量红线：原文件不覆盖，输出另存。

---

七、输出成品结构（即用型零排版）

A. 成品文件：<output_path>（PNG 或 SVG）。

B. 生成报告（章节清单）

1. 任务概要（内容类型 / 数量 / 输出格式）
2. 参数确认单
3. 生成记录表
4. 可扫性验证结果
5. 使用建议

生成记录表（模板，1 行示范）

---

八、量化评价标准（自带评分量表）

总分换算：∑(维度分×权重)，满分 100。达标线 ≥90 分为优秀，75–89 为可用需提示，<75 为不合格须重做。

---

九、输出硬性约束

1. 所有二维码必须附带生成参数记录，保证可复现。
2. 交付前必须做可扫性验证，失败图片不得交付。
3. 所有边界与失败情况用【】占位并明确告知。
4. 输出为即用型文件，用户扫码即可用，无需二次操作。
5. 原文件默认保留，输出另存，禁止静默覆盖源文件。
6. 带 logo 二维码需提示 logo 占比建议 ≤30%，并验证可扫性。
7. 批量任务必须输出总览表，逐文件标注验证结果。
8. 未知信息统一用【】占位，禁止编造内容或路径。

---

十、禁止行为

1. 禁止生成用于诈骗、色情、赌博、暴力、恐怖主义等违法内容的二维码。
2. 禁止生成仿冒他人官方账号、收款码、票务系统的二维码。
3. 禁止用于绕过安全验证、虚假签到、伪造票据等欺诈行为。
4. 禁止在二维码中嵌入恶意链接、钓鱼地址或诱导性内容。
5. 禁止为追求艺术性而牺牲可扫性，交付无法识别的二维码。
6. 禁止静默覆盖用户已有文件。
7. 禁止将用户输入的敏感信息（如密码）明文写入报告或日志。

---

十一、合规对标锚点

1. 《网络安全法》：不得利用本技能制作、传播违法信息或侵犯他人权益的内容。
2. 《个人信息保护法》：生成含个人信息的二维码（如手机号、身份证号）需确认用途与权限，避免泄露敏感信息。
3. 《反电信网络诈骗法》：禁止生成用于诈骗、引流、钓鱼的二维码。
4. 《生成式人工智能内容标识办法》：若二维码指向 AI 生成内容，建议在落地页保留法定标识，本技能仅生成静态编码。
5. 平台服务条款：二维码指向的落地页需遵守目标平台规则，本技能不对落地页内容负责。

---

十二、常见问题 FAQ

1. 「生成一个二维码要多久？」 纯本地运行，通常 1–3 秒；批量 100 个也只需几十秒。
2. 「支持中文吗？」 支持。内容按 UTF-8 编码，微信/支付宝等主流扫码器均可识别。
3. 「想放公众号头像到中间可以吗？」 可以。用 --logo 头像.png --logo-ratio 0.25，生成后会自动验证可扫性。
4. 「SVG 和 PNG 怎么选？」 印刷/放大用 SVG；带颜色/logo/放海报用 PNG。
5. 「报错版本不够怎么办？」 内容越长需要版本越大。脚本默认自动适配，无需手动指定；若想固定小尺寸可手动降内容长度。
6. 「批量生成 100 个怎么命名？」 提供输出目录 + 前缀，脚本自动按 prefix_001.png 递增命名。
7. 「可扫性验证失败怎么办？」 通常是 logo 太大或颜色对比度不足。建议减小 logo 比例、加深模块颜色或增大 box_size。
8. 「会消耗 AI 积分吗？」 不会。本技能完全离线，不调用任何云端 API 或 AI 生图。
9. 「提示缺少依赖怎么办？」 执行 pip install -r requirements.txt。脚本也会在缺失时主动提示具体缺哪个包。
10. 「PowerShell 里 && 报错怎么办？」 PowerShell 不支持 &&，请把命令拆成多行分步执行（见第一节示例）。
11. 「海报合成时中文显示方块？」 说明没找到中文字体。可指定 --font C:/Windows/Fonts/simhei.ttf，或在技能目录下创建 fonts/ 文件夹放入 .ttf/.ttc 字体文件。
12. 「想删除临时文件被系统阻止？」 请用 Python 的 Path("file.png").unlink() 或 tokeny 的 delete_file 工具，不要用 Remove-Item。

---

十三、给 AI 助手的执行指令

1. 收到请求先读三必填参数（内容/输出格式/尺寸颜色）；缺一即原样输出第四节追问话术，不擅自猜测。
2. 内容为空 → 拒绝生成；内容含敏感信息 → 提示用户确认用途。
3. 依赖检查优先：调用脚本前，先确认 qrcode / pillow / opencv-python 已安装；若缺失，提示用户执行 pip install -r requirements.txt，不要用 AI 生图兜底。
4. Windows/PowerShell 兼容：PowerShell 不支持 && 链式命令，所有示例必须分步写（cd ... → pip install ... → python gen_qr.py ...）。
5. 删除操作建议：清理临时文件请使用 Python 的 pathlib.Path.unlink() 或 tokeny 的 delete_file 工具，禁止在 PowerShell/bash 里用 Remove-Item / rm -rf 处理用户文件。
6. 字体安全加载：海报合成（gen_qr_poster.py）不枚举 C:\Windows\Fonts 目录，优先用 --font 参数或技能目录 fonts/ 下的字体；找不到时回退到 PIL 默认字体并提示中文可能显示为方块。
7. 运行环境：使用 tokeny 托管 Python（…\binaries\python\envs\default）；调用示例：python gen_qr.py "https://example.com" -o output.png。
8. URL 内容自动 trim 首尾空格；Wi-Fi 信息按标准 WIFI:T:WPA;S:SSID;P:密码;; 格式封装。
9. 默认生成 PNG（black/white，box_size=10，border=2，error_correction=M）；用户要彩色给 --fill #RRGGBB --back #RRGGBB。
10. 中心 logo 只用于 PNG：--logo logo.png --logo-ratio 0.25。生成后必须验证可扫性。
11. 批量生成时循环调用脚本，输出总览表，逐文件标注验证结果。
12. 所有参数（version/box_size/border/error_correction/fill/back/logo_ratio）写入生成报告。
13. 输出路径涉及中文时使用 Path.resolve() 处理；生成后调用 print(out) 回显最终路径。
14. 海报合成：如需把二维码与标题/URL 合成推广图，使用 gen_qr_poster.py，示例见第十四节。
15. 与相邻技能分流：AI 绘图/海报设计走 agnes-image-gen 或 PIL 绘图；本技能只做"生成可扫二维码"一件事。
16. 任何不确定都降级为"默认黑白 PNG + 验证报告"，不夸大"艺术二维码"效果。
17. 交付时必须说清：文件路径、格式、建议扫码测试、如含 logo 提醒占比。

---

十四、版本与配套

• 版本号：1.0.2
• 更新说明：
  • 新增 requirements.txt，脚本启动时自动检查依赖缺失并给出明确安装命令。
  • 新增 gen_qr_poster.py 海报合成脚本，字体加载不枚举系统 Fonts 目录，避免 PowerShell 安全策略限制。
  • 明确 PowerShell 分步执行示例，移除 && 链式命令。
  • 明确删除操作建议：使用 Python Path.unlink() 或 tokeny delete_file 工具，避免 Remove-Item 被拦截。
  • 文档品牌统一：全篇以 tokeny 智能桌面工具为运行环境叙述，不再使用 WorkBuddy 字样（四项限制均来自 tokeny 实测）。
• 推荐搭配：
  1. agnes-image-gen（需要把二维码嵌入 AI 生成海报时，先生成二维码再合成）
  2. tencent-docs（把二维码插入文档/表格时直接粘贴）
  3. watermark-remover（清理已有图片上的旧二维码或遮挡物）

海报合成示例

先生成二维码，再合成海报：

# 步骤 1：生成二维码
python gen_qr.py "https://skillhub.cn/skills/user_858115ff/agnes-cn-key-wizard" \
  -o agnes_key.png --verify

# 步骤 2：合成海报
python gen_qr_poster.py agnes_key.png \
  -o agnes_key_poster.png \
  --title "Agnes 密钥申领向导" \
  --subtitle "一键把 Agnes 接入 tokeny 智能桌面工具" \
  --url "https://skillhub.cn/skills/user_858115ff/agnes-cn-key-wizard"

PowerShell 版本（分步执行）：

python gen_qr.py "https://skillhub.cn/skills/user_858115ff/agnes-cn-key-wizard" -o agnes_key.png --verify
python gen_qr_poster.py agnes_key.png -o agnes_key_poster.png --title "Agnes 密钥申领向导" --subtitle "一键把 Agnes 接入 tokeny 智能桌面工具" --url "https://skillhub.cn/skills/user_858115ff/agnes-cn-key-wizard"