CodeBox 码盒 - 智能二维码

智能二维码生成平台 CodeBox（码盒）的 Agent Skill。免费生成二维码图片（无需 API Key），也可生成带追踪的动态二维码、智能模板匹配、短链追踪分析、动态链接更新。支持品牌/节日/行业等 150+ 风格模板，零设计门槛生成专业级二维码。

Security Scan

Skill documentation and runtime instructions largely match the QR-code generation purpose, but the SKILL.md expects an API key (CODEBOX_API_KEY) while the registry metadata declares no required environment variables — an incoherence that could lead to missing prompts or unexpected behavior and merits verification before installation.

Purpose & Capability

Name/description (QR code generation, dynamic codes, tracking, templates) align with the actions in SKILL.md (endpoints for generate_image, generate, get_stats, etc.). Required binary 'curl' is appropriate for the provided curl examples. No unrelated cloud or system access is requested in the instructions.

Instruction Scope

SKILL.md is instruction-only and directs the agent to call https://www.codebox.club REST endpoints via curl, save image outputs, and optionally return base64 JSON. The instructions do not ask the agent to read other local files, system configs, or unrelated environment variables. They do include examples that transmit potentially sensitive payloads (WiFi credentials, vCard personal data), which is expected for QR generation but is a privacy consideration for users.

Install Mechanism

There is no install spec and no code files — the skill is instruction-only and uses existing curl on PATH. This is the lowest-risk install model (nothing will be written to disk by the skill itself).

Credentials

SKILL.md documents an environment variable CODEBOX_API_KEY and shows Authorization header usage for advanced features, but the registry metadata lists no required env vars and no primary credential. This mismatch is a meaningful incoherence: an agent or UI relying on the registry metadata may not surface or request the API key, yet the runtime instructions require it for tracking/analytics endpoints.

Persistence & Privilege

The skill does not request permanent presence (always: false). It does not attempt to modify other skills or system-wide settings. Autonomous invocation is allowed (platform default) but that is not by itself a red flag here.

What to consider before installing

This skill appears to do what it says (generate static and dynamic QR codes) and only needs curl to run. Before installing, confirm whether you or your agent runtime will supply the CODEBOX_API_KEY when you want advanced (tracking/analytics) features — the skill's registry metadata does not declare that env var even though the SKILL.md uses it. Also consider privacy: example calls include WiFi credentials and vCard personal data, which will be sent to https://www.codebox.club; avoid sending secrets you don't want stored/processed by that service. Finally, because this is instruction-only with no source code, you should trust the external service (homepage looks provided) or review their privacy/API docs before enabling the skill.

CodeBox 码盒 — 智能二维码 Skill

CodeBox（码盒）是专业的智能二维码生成平台，支持动态二维码、带 Logo 二维码、彩色渐变二维码等多种样式，提供 UTM 参数追踪、扫码统计分析等功能。

本 Skill 提供两类能力：

• 免费能力（无需 API Key）：直接生成二维码图片
• 高级能力（需要 API Key）：带追踪的动态二维码、扫码统计、动态链接更新、模板浏览

Setup

Base URL: https://www.codebox.club

免费使用（generate_image）

无需任何配置，直接调用即可。限制：10 次/分钟，最大 1000px。

高级功能（需要 API Key）

设置环境变量：

export CODEBOX_API_KEY=cb_sk_your_key_here

获取 API Key：https://www.codebox.club/dashboard/settings/api-keys

高级功能的请求需要 Header：

Authorization: Bearer $CODEBOX_API_KEY
Content-Type: application/json

---

Actions

1. generate_image — 生成二维码图片（免费，无需 API Key）

直接生成二维码图片，支持 URL、文本、WiFi、名片等多种内容类型，支持自定义颜色、渐变、Logo、背景图、模板等丰富样式。返回二维码图片（PNG/SVG）。

When to use: 用户想快速生成一个二维码图片，不需要追踪和统计功能。

curl -s -X POST https://www.codebox.club/api/v1/qrcode/generate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "https://example.com",
    "size": 300,
    "format": "png",
    "dotsStyle": "rounded",
    "dotsColor": "#f59e0b",
    "backgroundColor": "#FFFFFF",
    "cornersSquareStyle": "dot",
    "cornersDotStyle": "dot",
    "errorCorrectionLevel": "M"
  }' \
  -o qrcode.png

Parameters:

Parameter	Type	Required	Description
content	string	Yes	要编码的 URL 或文本内容（最大 4000 字符）
type	string	No	内容类型：URL、TEXT、WIFI、VCARD、EMAIL、PHONE
size	number	No	图片尺寸 50-1000px（默认 300，有 API Key 时最大 2000）
format	string	No	输出格式：png（默认）或 svg
margin	number	No	边距 0-100（默认 10）
errorCorrectionLevel	string	No	容错级别：L、M（默认）、Q、H
styleMode	string	No	normal（默认）或 image（带背景图模式）
templateId	string	No	风格模板 ID（通过 list_templates 获取）
dotsStyle	string	No	模块形状：square、rounded、classy、classy-rounded、extra-rounded、dots
dotsColor	string	No	模块颜色（十六进制，如 #000000）
dotsGradient	object	No	模块渐变：{ type, rotation, colorStops }
backgroundColor	string	No	背景色（十六进制）
backgroundGradient	object	No	背景渐变
backgroundImage	string	No	背景图片 URL
backgroundImageSize	number	No	背景图缩放 0.1-2.0（默认 1.0）
backgroundImageOpacity	number	No	背景图透明度 0.1-1.0（默认 1.0）
cornersSquareStyle	string	No	定位点外框形状：square、extra-rounded、dot
cornersSquareColor	string	No	定位点外框颜色
cornersSquareGradient	object	No	定位点外框渐变
cornersDotStyle	string	No	定位点内框形状：square、dot、extra-rounded
cornersDotColor	string	No	定位点内框颜色
cornersDotGradient	object	No	定位点内框渐变
logoUrl	string	No	Logo 图片 URL
logoSize	number	No	Logo 大小比例 0.1-0.5（默认 0.2）
logoMargin	number	No	Logo 边距 0-50（默认 5）
logoX	number	No	Logo X 位置 0-1（默认 0.5 居中）
logoY	number	No	Logo Y 位置 0-1（默认 0.5 居中）
responseFormat	string	No	设为 json 返回 base64 JSON 而非图片二进制

WiFi 类型示例：

curl -s -X POST https://www.codebox.club/api/v1/qrcode/generate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "MyWiFi",
    "type": "WIFI",
    "wifi": { "ssid": "MyWiFi", "password": "12345678", "security": "WPA" },
    "dotsStyle": "rounded",
    "dotsColor": "#3b82f6"
  }' \
  -o wifi-qrcode.png

名片类型示例：

curl -s -X POST https://www.codebox.club/api/v1/qrcode/generate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "vcard",
    "type": "VCARD",
    "vcard": { "firstName": "张", "lastName": "三", "phone": "13800138000", "email": "[e-mail]", "organization": "码盒科技" },
    "dotsColor": "#10b981"
  }' \
  -o vcard-qrcode.png

JSON 格式返回（获取 base64）：

curl -s -X POST https://www.codebox.club/api/v1/qrcode/generate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "https://example.com",
    "responseFormat": "json"
  }'

Response:

{
  "success": true,
  "data": {
    "image": "data:image/png;base64,iVBORw0KGgo...",
    "format": "png",
    "size": 300,
    "mimeType": "image/png"
  }
}

Tips:

• 默认返回二进制图片，用 -o file.png 保存到文件
• 设 responseFormat: "json" 获取 base64 编码的图片数据
• 有 API Key 时尺寸上限提升到 2000px，频率提升到 60 次/分钟
• 使用 templateId 可一键应用预设风格

---

2. generate — 生成带追踪的动态二维码（需要 API Key）

创建带短链追踪的动态二维码，可事后更新目标 URL，可查看扫码统计。

When to use: 用户想创建可追踪、可动态更新的二维码，用于营销活动、线下物料等。

curl -s -X POST https://www.codebox.club/api/v1/plugin/generate \
  -H "Authorization: Bearer $CODEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "https://example.com",
    "mode": "DYNAMIC",
    "name": "夏季促销活动",
    "keywords": ["科技", "现代"],
    "errorCorrectionLevel": "M"
  }'

Parameters:

Parameter	Type	Required	Description
content	string	Yes	要编码的 URL 或文本内容
mode	string	No	DYNAMIC（默认，可追踪）或 STATIC
name	string	No	二维码显示名称
templateId	string	No	风格模板 ID（通过 list_templates 获取）
keywords	string[]	No	自动匹配模板的关键词（如 ["春节", "喜庆"]）
errorCorrectionLevel	string	No	容错级别：L、M（默认）、Q、H

Response:

{
  "success": true,
  "data": {
    "id": "clxxx...",
    "shortLink": "https://www.codebox.club/s/AbCdEf",
    "templateUsed": "tech-modern-01",
    "matchedKeywords": ["科技"],
    "styles": { ... }
  }
}

Tips:

• 使用 DYNAMIC 模式可在不重新印刷的情况下更新目标 URL
• 使用 keywords 自动匹配视觉相关的风格模板
• 使用 templateId 精确指定模板（先用 list_templates 浏览）

---

3. get_stats — 获取二维码扫码统计（需要 API Key）

获取扫描统计数据，包括总扫描量、设备分布、浏览器/操作系统统计、地理位置数据和每日趋势。

When to use: 用户想查看二维码效果、分析扫码数据、对比不同活动、或获取地域洞察。

curl -s -X GET "https://www.codebox.club/api/v1/plugin/analytics?id=QR_CODE_ID&startDate=2026-01-01&endDate=2026-03-09" \
  -H "Authorization: Bearer $CODEBOX_API_KEY"

Parameters:

Parameter	Type	Required	Description
id	string	Yes	二维码 ID（来自 generate 的响应）
startDate	string	No	起始日期 YYYY-MM-DD（默认：30 天前）
endDate	string	No	结束日期 YYYY-MM-DD（默认：今天）

Response:

{
  "success": true,
  "data": {
    "totalScans": 1234,
    "uniqueUsers": 890,
    "deviceBreakdown": { "mobile": 72.5, "desktop": 22.3, "tablet": 5.2 },
    "dailyScans": [{ "date": "2026-03-01", "count": 45 }],
    "topBrowsers": [{ "browser": "Chrome", "count": 500 }],
    "topOS": [{ "os": "iOS", "count": 400 }],
    "geoData": [{ "country": "CN", "region": "Shanghai", "city": "Shanghai", "count": 200 }]
  }
}

---

4. update_link — 更新动态二维码（需要 API Key）

修改已有动态二维码的目标 URL、名称或状态，无需重新印刷。

When to use: 用户想将现有二维码重定向到新 URL、重命名、或禁用/过期处理。

curl -s -X PATCH https://www.codebox.club/api/v1/plugin/update \
  -H "Authorization: Bearer $CODEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "QR_CODE_ID",
    "targetUrl": "https://example.com/new-page",
    "name": "秋季活动"
  }'

Parameters:

Parameter	Type	Required	Description
id	string	Yes	二维码 ID
targetUrl	string	No	新的目标 URL
name	string	No	新的显示名称
status	string	No	READY、EXPIRED 或 DELETED

至少需要提供 targetUrl、name、status 中的一个。

Response:

{
  "success": true,
  "data": {
    "id": "clxxx...",
    "targetUrl": "https://example.com/new-page",
    "name": "秋季活动",
    "status": "READY",
    "updatedAt": "2026-03-09T10:30:00.000Z"
  }
}

---

5. list_templates — 浏览风格模板（需要 API Key）

列出所有可用的二维码风格模板，包括品牌、行业、场景、艺术、平台、节日、名片等类别。返回的模板 ID 可用于 generate 或 generate_image 的 templateId 参数。

When to use: 用户想查看可用风格、找到主题模板、或在生成前按类别浏览。

curl -s -X GET https://www.codebox.club/api/v1/plugin/catalog \
  -H "Authorization: Bearer $CODEBOX_API_KEY"

Response:

{
  "success": true,
  "data": {
    "totalTemplates": 150,
    "tags": ["科技", "春节", "商务", "餐饮"],
    "categories": [
      {
        "source": "style",
        "count": 80,
        "templates": [{ "id": "tech-01", "name": "科技蓝", "category": "technology", "tags": [] }]
      },
      {
        "source": "festival",
        "count": 40,
        "templates": []
      },
      {
        "source": "business",
        "count": 30,
        "templates": []
      }
    ]
  }
}

---

6. check_quota — 查询 API 配额（需要 API Key）

查询当前计费周期的 API 调用剩余配额。

curl -s -X GET https://www.codebox.club/api/v1/quota \
  -H "Authorization: Bearer $CODEBOX_API_KEY"

---

Workflow Examples

快速生成二维码（免费）

1. 调用 generate_image 生成二维码图片，自定义颜色和样式
2. 保存图片用于分享或打印

营销活动二维码（需要 API Key）

1. 浏览模板：调用 list_templates 找到合适的风格
2. 生成二维码：调用 generate，传入 templateId 和活动 URL
3. 分享 shortLink 或嵌入二维码图片到物料中
4. 投放后，调用 get_stats 监控扫码效果
5. 需要时，调用 update_link 重定向到新 URL

A/B 测试

1. 生成两个二维码，分别指向不同的目标 URL（方案 A 和 B）
2. 在相似位置部署两个二维码
3. 积累足够数据后，调用 get_stats 对比两者效果
4. 使用 update_link 将效果差的二维码重定向到效果好的 URL

季节活动轮换

1. 生成一个 DYNAMIC 二维码用于固定展示位
2. 每个季度调用 update_link 指向新的季节页面
3. 通过 get_stats 的日期范围参数对比各季度效果