WorkBuddy + Skills 让你的考试认证全流程自动化

一、业务背景以及痛点介绍

1.1. 业务背景

通过小鹅通开设了大量在线培训课程，每门课程对应专属的电子证书。学员完成课程学习并通过最终的结业考试后，需要统一发放认证证书。

完整的证书发放流程涉及三个环节：

（1） 获取名单：从小鹅通考试后台导出通过考试的学员名单，包含姓名、邮箱、成绩三个字段

（2）生成证书并发送：为每位学员生成专属的 PDF 证书，并通过邮件逐一发送

（3）入库存档：将发证记录录入官方认证查询系统，供用户完成证书查询验证

此前这些环节由部门内部的一个 Java 脚本项目完成，每次发证需要经历以下步骤：

- 登录小鹅通后台，找到对应考试，手动下载学员名单 CSV

- 手动调整 CSV 的列名和格式，使其满足 Java 脚本项目的输入要求

- 运行 Java 脚本项目，根据本地环境配置路径、安装依赖、调整参数

- 项目生成 PDF 证书并通过统一邮箱分别发送给每个学员

- 发证完成后，再次手动整理数据格式，导入证书查询系统进行入库

1.2. 痛点介绍

- 强依赖 Java 运行环境：Java 项目需要本机安装 JDK、配置 Maven 或 Gradle 依赖、处理文件路径等。不同电脑的环境差异导致每次部署都需要大量调试，只有部门内的技术人员才能操作

- 流程割裂、重复劳动：从下载名单到格式整理，从发证到入库，每个环节都需要人工介入。尤其是在小鹅通导出名单和证书查询系统入库之间，需要两次手动整理表格结构，工作量翻倍

- 错误风险高：手动处理 CSV 时容易漏行、错列；发证前缺乏统一的预览确认环节，一旦参数出错会导致批量错发，且难以追溯

- 无法分担工作：由于操作门槛高，证书发放工作长期集中在个别技术人员手中，其他人无法分担，成为部门瓶颈

二、Skills 总体框架

证书发放 Skill 是一个全流程自动化 Pipeline，通过一个 Python 脚本整合了小鹅通 API 对接、CSV/Excel 解析、Word 模板填充、PDF 转换、邮件发送、数据入库等全部环节。

2.1. Skills 文件结构

SKILL.md  — AI 行为指令（WorkBuddy 使用）
README.md  — 说明文档（人类阅读）
requirements.txt  — Python 依赖清单
scripts/certificate_pipeline.py  — 核心脚本（1250 行，26 个函数）
references/parameters.md  — 参数参考手册
template/证书.docx  — 证书模板

2.2. 两种学员信息获取模式及统一处理管道

方式 A：小鹅通 API（推荐）

用户提供 app_id + client_id + secret_key
脚本自动获取 access_token（2 小时缓存）
运行 --list-exams 列出最近考试供用户选择
自动拉取考试结果 + 学员信息（姓名、邮箱、成绩）

方式 B：本地CSV 文件上传（备选）

用户上传 CSV/Excel 名单文件
脚本自动解析并映射列名

统一处理管道

成绩筛选 → 自动编号 → Word 模板填充 → PDF 转换 → 邮件发送 → 数据库入库

2.3. Skills 涉及技术栈

环节	技术实现
小鹅通 API	Python urllib.request，HTTP POST/GET
CSV/Excel 解析	Python 内置 csv + openpyxl
Word 模板填充	python-docx（替换文本框占位符）
PDF 转换	Word COM / WPS COM / LibreOffice CLI 自动降级
邮件发送	smtplib + email（支持 SSL/TLS）
数据库入库	pymysql，自动去重
Token 管理	本地文件缓存（2 小时有效期内复用）

三、Skills 详解

3.1 Skills 脚本源码详解

certificate_pipeline.py 共约 1250 行，按功能划分为五个模块：

模块一：小鹅通 API 对接（~100 行）

函数	功能	调用的小鹅通 API
xiaoe_get_token()	获取 access_token（带本地缓存）	GET /token
xiaoe_list_exams()	获取考试列表	POST /xe.examination.list.get/1.0.0
xiaoe_get_exam_results()	获取考试结果（自动分页）	POST /xe.examination.result.list/1.0.0
xiaoe_batch_get_users()	批量获取用户信息（自动分批）	POST /xe.user.batch_by_user_id.get/2.0.0
xiaoe_fetch_students()	全流程合并	组合上述 API

自动处理：

· 认证鉴权：app_id + client_id + secret_key → access_token（2 小时缓存）

· 分页拉取：考试结果每页最多 30 条，自动翻页

· 分批查询：用户信息每批最多 50 人，自动分批 + 限速（0.5 秒间隔）

· 数据合并：姓名优先级 b_real_name > nick_name > wx_nickname；邮箱优先级 b_email > account_email

· 关联课程：从考试的 goods_info 字段提取课程名称，用于邮件正文

模块二：学员名单解析（~100 行）

函数	功能
load_students()	统一入口，自动识别 CSV/Excel
parse_csv()	CSV 解析（自动检测 GBK/UTF-8 编码）
parse_excel()	Excel 解析（支持指定 sheet）
normalize_columns()	中文列名自动映射（姓名→nickname，邮箱→email）

支持的中文列名映射：姓名、微信昵称、邮箱、最高成绩、成绩、手机、手机号、备用邮箱

模块三：PDF 证书生成（~200 行）

Word 模板处理：

· 证书模板 (.docx) → 文本框占位符: nickname / validUntil / certificateNo → 底图: background.png（可选替换）
· python-docx 替换文本框文字 → zipfile 替换底图文件 → 生成临时 .docx

PDF 转换（自动降级）：

Windows 平台：

· Word COM（win32com → Word.Application）—— 最快
· WPS COM（win32com → Kwps/KWPS/WPS.Application）
· LibreOffice CLI（soffice --convert-to pdf）—— 需安装

macOS/Linux 平台：

· WPS CLI（wps --convert-to pdf）
· LibreOffice CLI（soffice --convert-to pdf）—— 保底

检测命令：--detect-pdf。安装命令：--install-pdf-tool wps [路径] 或 --install-pdf-tool libreoffice [路径]

模块四：邮件发送（~100 行）

功能	说明
SMTP 协议	支持 SSL（465）和 STARTTLS（587）
附件	PDF 证书作为附件发送
邮件正文	HTML 格式，支持占位符：{username} {courseName} {batch} {sendDate}
频控	每封邮件间隔 1 秒，防 SMTP 限流
主题	按证书类型自动选择

邮件正文示例：

XX同学：
    你好！
    恭喜你顺利通过 **** 实战训练营(202607期)结业考试，
    获得******** AI Agent 开发工程师认证证书，附件为你的电子版的证书，
    请查收。祝你在以后的工作、学习、生活中万事顺意。
                                        单位名称：*****
                                        2026年07月20日

模块五：认证信息入库（~80 行）

· 使用 pymysql 连接 MySQL
· 入库前自动去重：按 certificate_name + name + email 三重校验

仅执行 SELECT（查重）和 INSERT（写入），不执行任何 DELETE 操作

· 编写的证书记录可直接在证书查询系统中检索

3.2 自动识别证书类型

识别关键字	模板文件	邮件中显示	数据库中记录
考试/课程名含认证类型关键字	证书.docx	AI Agent 开发工程师认证证书	AI Agent 开发工程师

脚本自动从考试名称/课程名称中识别证书类型，无需人工指定。

3.3 自动完成证书规则编号

FIT-{年月}-{证书类型}-{序号}

· 企业缩写-202607-认证缩写-001 → 2026年7月发放的第1张证书
· 企业缩写-202607-认证缩写-003 → 2026年7月发放的第3张证书

自动生成，无需手动指定。按学员顺序递增编号。有效期统一设置为发放日期 + 2 年 - 1 天（精确处理闰年）。

3.4 全自动执行流程

以下是直接通过小鹅通 API 获取学员信息模式的标准执行流程：

【Step 0】 用户提供凭证（app_id + client_id + secret_key）

运行 --list-exams，显示最近 10 个有学员参与的考试
用户选择考试（通过编号或考试名称）

【Step 1】 自动判断证书类型，确认及格分数线和自动生成的参数

【Step 2】 数据映射与证书编号生成

【Step 3】 运行 pipeline（带 --generate-only）→ 生成 PDF 并展示 PDF 和邮件正文给用户预览确认

【Step 4】 用户确认后，提供 SMTP 和/或数据库信息

运行 pipeline（不带 --generate-only）→ 发邮件 + 入库

【Step 5】 验证结果，确认成功/失败统计

3.5 关键设计原则

安全约束：

· 禁止 DELETE 操作，仅允许 SELECT / INSERT / UPDATE

· SMTP 密码和数据库密码均不硬编码，每次发证向用户索取

· 推荐使用专用数据库账号（如 cert_bot），仅授予 SELECT + INSERT + UPDATE 权限

防错机制：

· 必须先 --generate-only 预览，用户确认后才能正式发送

· 全量读取数据，禁止仅预览前几行

· 每次用用户新上传的文件，禁止复用旧缓存

· 一步失败即停止后续处理，防止重复/错发

AI 约束：

· AI 必须运行预写脚本，不得自行编写代码替代

· AI 不得询问证书类型（脚本自动识别）

· AI 不得擅自行动，每一步都需要用户确认

四、AI 自动化效果演示（两种提问方式）

4.1 基于 WorkBuddy 安装 skill

安装该 skill 只需要将该压缩包发送给workbuddy，直接让它帮你安装即可。

4.2 Skill 执行流程

步骤一：发送指令

安装好之后，选择certificate-issuance技能，发送：

帮我发送证书。

然后给出小鹅通店铺ID、应用ID和应用Serect。（第一种学员信息获取方式）

或者选择要上传的学员名单：学员名单.csv。（第二种学员信息获取方式）

Skill会确认发放计划，列举证书类型：AI Agent 开发工程师认证（这是写死的，是根据小鹅通api获取的考试名称/课程名称/上传的学员名单的名称来进行判断：比如这里我上传的是XX学员名单.csv，就会自动判断为 AI Agent 开发工程师认证）
证书类型和证书模板会按照 skill 逻辑自动列出。然后 AI 会询问用户及格线是多少，来判断哪些学员通过了考试，没有通过的不发放证书。