Skill实战：二维码生成

注意，这篇博客编写的 Skill，它的开发，测试和使用，涉及到python，需要你 提前安装 python 编辑器。
python的安装，网上的教程很多，AI也能一步一步教你，我也就不在这里介绍了。

开发环境：Vs Code
使用Skill的Agent应用：Codex

上一篇博客，介绍天气Skill的实战，Skill的安装，如何验证是否安装成功，我这里就不演示了。
上一篇博客的博客链接：Skill实战：天气的获取

1. 需求说明

我们将开发一个名为 qrcode‑gen 的二维码生成 Skill，满足以下需求：

表格

需求项	说明
功能范围	将文本、网址、密码等内容转换为二维码图片
输入内容	支持任意字符串（URL、中文文本、密码等）
输出形式	生成 PNG 格式的二维码图片文件
技术方案	Python + qrcode[pil] 库 + 自动保存到指定目录

与天气 Skill 的区别：本 Skill 需要外部依赖安装（qrcode库），且输出为文件而非文本，涉及文件系统操作。

1.1 应用场景：

场景一：下载链接

当我们要下载一个软件的时候，我们可以把下载网页的URL，变为二维码，用户只需要使用浏览器的二维码扫描功能，扫一下二维码，就可以下载软件了。

这种场景，在实际的企业中经常使用。尤其是测试人员，需要下载不同的软件的版本，确认 bug 的时候。

场景二：WIFI密码

某一些手机品牌的手机，连接了WIFI之后，可以在设置中，生成二维码。

其他的手机扫一下这个二维码之后，能可以连接或者显示这个WIFI的密码。

1.2 qrcode库的解释

qrcode：python 的第三方库，用来生成二维码

安装命令：pip install qrcode[pil]，pil 为 Pillow 图片依赖，缺少则无法输出 PNG 图片文件。

1. qrcode.make_image()：生成二维码图片对象，可保存为 PNG 文件。

   • 简易用法：qrcode.make(内容)，快速生成图片；
   • 复杂自定义配置，需要使用 QRCode 类。

2. 支持设置参数 (二维码的尺寸，颜色，形状，甚至还可以在二维码中间加 logo)

   • box_size：二维码每个小方块的像素大小；

   • border：二维码四周空白边距，默认 4，扫码要求必须保留留白；

   • fill_color / back_color：设置二维码前景、背景颜色；

   • 内置了四级纠错码：二维码部分遮挡（可以在二维码中间加 logo）、污渍破损依旧可以识别。

     纠错等级越高，允许损坏的区域越大，但可存储的文本容量会变小。

     • L：7%，容量最大；M：15%（默认）；Q：25%；H：30%（最高纠错，适合中间嵌入 logo）
     • ⚠️二维码中间添加 logo，必须选用 Q/H 高纠错等级，否则会扫描失败，且 logo 尺寸不能过大。

3. 支持中文，需要使用 UTF‑8 编码；Windows 环境执行chcp 65001，避免中文乱码。

2. Skill开发 & 安装 & 使用

2.1 Skill 模板

我们可以按照官方文档中的模板，进行开发

官方文档：https://agentskills.io/home

模板：

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use the following command that generates a random number from 1
to the given number of sides:

```bash
echo $((RANDOM % <sides> + 1))
```

```powershell
Get-Random -Minimum 1 -Maximum (<sides> + 1)
```

Replace `<sides>` with the number of sides on the die (e.g., 6 for a standard
die, 20 for a d20).

这个模板的内容，需要我们自己更改，但是，name 和 description 是固定的。

2.2 Skill 存放的位置

2.2.1 按照规范存放

关于 SKill 文件夹存放的位置，如果是使用 Codex，按照 Codex 官方手册，应该是放在 `C:\Users\你的用户名.codex\skills\

你下载安装好 Codex 之后，就会有这个目录的：

2.2.2 任意路径存储

其实，不一定非要按照 Codex 规定的目录存放。

你可以把自己的 Skill 放在任意位置，例如：

D:\my-skills\image-search\SKILL.md

然后在运行 Codex 时，明确告诉 Codex 使用这个位置的 Skill，或者对话的方式，让它帮你安装，

但其实，安装的本质，就是将你的 Skill文件，复制到 C:\Users\你的用户名\.codex\skills

等我开发好这个 SKill 之后，我就演示一下

2.3 开发Skill

可以先在任意目录，创建 skills 文件夹，然后创建这个 Skill 的名称，我的名称是：qrcode-gen

打开 Vscode，打开创建的这个 Skill文件夹，创建好目录和文件：

然后在 Skill.md 中，进行编辑。

2.3.1 Skill.md

---
name: qrcode-gen
description: 这是一个用来生成二维码的Skill，可以将文本内容转为二维码，支持的内容有：网址（URL）、文本、密码等
---

# qrcode-gen
这是一个用来生成二维码的Skill，可以将文本内容转为二维码，支持的内容有：网址（URL）、文本、密码等

## 安装依赖
这个 Skill 依赖于 python 的第三方库：`qrcode` 库，首次使用这个 Skill 时，可以使用以下命令进行安装：

```bash
pip install qrcode[pil]
```

## 什么时候使用这个技能
当用户需要将文本内容（如网址、文本、密码等）转换为二维码时，可以使用这个技能。用户只需提供需要转换的文本内容（支持网址（URL）、文本、密码等），技能将生成对应的二维码图片，方便用户进行扫描和分享。

## 如何使用这个技能
生成二维码

```python
python /scripts/qrcode_gen.py "https://www.baidu.com"
```

生成的二维码保存在 当前目录下的 output 文件夹中

2.3.2 qrcode_gen.py

这个 qrcode_gen.py ，是在 scripts文件夹 中的：

import os
import sys
import uuid
from pathlib import Path

try:
	import qrcode
except ModuleNotFoundError:
	print("未找到 qrcode 库，请先运行: pip install qrcode[pil]")
	sys.exit(1)


def generate_qrcode(content: str) -> Path:
	"""
	用来生成二维码，
	"""

  # 1. 定义二维码的输出路径
  # 这里的路径，你可以自己定义，我是定义在这个 Skill文件夹 下的 output文件夹下了
	output_path = os.path.join(r"需要你自己定义存放的路径")

	
	if not os.path.exists(output_path):
		# 如果输出路径不存在，则创建该路径
		os.makedirs(output_path)
		
	# 2. 定义二维码图片的完整路径
	output_path = os.path.join(output_path, f"qrcode_{uuid.uuid4().hex[:8]}.png")

  # 3. 生成二维码，设置二维码的参数
	try:
		# 创建二维码对象，并设置二维码的基本参数。
		qr_code = qrcode.QRCode(
			version=None,  # 自动根据内容长度选择二维码版本。
			error_correction=qrcode.constants.ERROR_CORRECT_H,  # 使用高容错率。
			box_size=10,  # 每个二维码模块的像素大小。
			border=4,  # 二维码边缘保留 4 个模块的空白区域。
		)

		# 将待编码的文本或网址写入二维码。
		qr_code.add_data(content)
		# 根据内容自动生成二维码矩阵。
		qr_code.make(fit=True)
		# 将二维码渲染为图片并保存到指定路径。
		qr_code.make_image().save(output_path)
		print(f"二维码已生成，保存在这个路径下: {output_path}")
	except Exception as error:
		print(f"生成二维码失败: {error}")
		sys.exit(1)

	return output_path


def main() -> None:
	# 检查命令行参数，参数 0 是脚本自身的路径。
	if len(sys.argv) < 2:
		print("请输入要生成的二维码内容")
		sys.exit(1)

	# 使用第一个命令行参数作为二维码内容并生成二维码。
	generate_qrcode(sys.argv[1])


if __name__ == "__main__":
	main()

python代码的测试：

这里的测试，需要你电脑中提前按照好 python编译器。

直接打开电脑的命令行：

安装 qrcode库，输入命令：

pip install qrcode[pil]

输入命令：

python qrcode_gen.py "https://www.baidu.com"

这里我没法动态的演示二维码的扫描效果，但是最后的结果是：你使用手机的浏览器，扫描这个二维码，就会打开 百度 的官方页面。

2.4 安装Skill

第一种方式：复制目录

我们可以直接将开发好的 SKill目录，放到这个文件夹下：

这种方式，适合你清楚地知道，Codex 的skill目录在哪的情况，Codex扫描 Skill目录 的时候，能够直接识别这个Skill。

第二种方式：对话安装

打开 Codex，和他对话：

帮我安装 XXXX 下的Skill

示范：

帮我安装这个路径下的 Skill，路径：E:\code\gitee\skill-development\skills\qrcode-gen

这里的路径，是我自己的，你需要根据你自己的实际路径进行替换

检验是否安装成功：

1. 查看 Codex 的skills目录

Codex 的skills目录，在这里：

C:\Users\用户名\.codex\skills

如果已经存在了你开发的 Skill，就表示安装完成了。

2. 对话检验：

可以和 Codex，对话，问它：

列一下，你现在有哪些Skill

这样，就算是安装好了

2.5 使用 Skill

此时，我们和 Codex 对话：

帮我把 "[https://www.sogou.com](https://www.sogou.com)" 生成二维码，生成好的二维码给我展示出来

你扫码验证一下，打开的就是 搜狗 的搜索页面，证明这个Skill没有问题。

这样，我们的 SKill，就算是可以使用了。

3. 源码获取

完整的Skill文件夹获取，可以从我的gitee中下载：
gitee链接：[skills/qrcode-gen · 何先生/Skill开发 - 码云 - 开源中国](https://gitee.com/mrbgvhbhjv/skill-development/tree/master/skills/qrcode-gen)