讯飞图片生成 (xunfei-image-gen)
调用讯飞星火图片生成 API（xopzimageturbo）进行 AI 文生图。
版本: v2.2.0
依赖: httpx, Pillow（Python 包，需自行安装：pip install httpx Pillow）
凭证配置（必读）
本技能从环境变量读取讯飞 API 凭证，三个变量均为必填：
| 环境变量 | 说明 |
|---|---|
XUNFEI_APP_ID |
讯飞开放平台 App ID |
XUNFEI_API_KEY |
讯飞 API Key |
XUNFEI_API_SECRET |
讯飞 API Secret |
可选环境变量（有默认值）：
| 环境变量 | 默认值 | 说明 |
|---|---|---|
XUNFEI_ENDPOINT |
maas-api.cn-huabei-1.xf-yun.com |
API 接入域名 |
XUNFEI_DOMAIN |
xopzimageturbo |
模型 domain |
XUNFEI_PATCH_ID |
xopzimageturbo |
patch_id |
在 QwenPaw 中：控制台 → 工作区 → 技能 → 本技能的配置，填入 JSON：
{
"XUNFEI_APP_ID": "你的_app_id",
"XUNFEI_API_KEY": "你的_api_key",
"XUNFEI_API_SECRET": "你的_api_secret"
}
QwenPaw 会把匹配 requires.env 的 key 注入为环境变量。
> 也支持本地 config.json 回退（见 config.example.json），便于脱离 QwenPaw 直接跑脚本，
> 但请勿把含真实密钥的 config.json 提交到公开仓库。
使用方式
所有图片统一输出到 output/xf-image/ 目录下。
默认：纯生成（不裁剪，保留水印）
python scripts/xunfei_gen.py \
-p "一只可爱的小猫在草地上奔跑" \
-o output/xf-image/cat.png
生成 + 裁剪水印（用户提到"裁剪"、"去水印"时）
讯飞水印在右下角，--crop-bottom 默认裁掉底部 124px。
python scripts/xunfei_gen.py \
-p "一只可爱的小猫在草地上奔跑" \
-o output/xf-image/cat.png \
--crop-bottom
自定义裁剪高度
python scripts/xunfei_gen.py -p "..." -o out.png --crop-bottom 150
参数说明
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
-p, --prompt |
✅ | - | 图片描述文字（≤1024 字符） |
-o, --output |
❌ | output.png |
输出路径 |
-n, --negative-prompt |
❌ | "" |
负面提示词 |
--width |
❌ | 1024 |
图片宽度 |
--height |
❌ | 1024 |
图片高度 |
--seed |
❌ | 42 |
随机种子 |
--steps |
❌ | 20 |
推理步数 |
--guidance |
❌ | 5.0 |
提示词相关度 |
--scheduler |
❌ | DPM++ 2M Karras |
调度器 |
-c, --config |
❌ | ../config.json |
配置文件路径（环境变量优先） |
--crop-bottom |
❌ | 0 |
裁剪底部像素去水印；不带值时默认 124 |
支持的调度器：DPM++ 2M Karras、DPM++ SDE Karras、DDIM、Euler a、Euler
完整流程（Agent 使用）
- 判断需求：用户只说"生成图片"→ 不加
--crop-bottom；提到"裁剪""去水印" → 加--crop-bottom - 生成图片：调用脚本，输出到
output/xf-image/ - 查看并发送：
view_image查看效果 +send_file_to_user发给用户 - 正文附图片路径：发送后，在回复正文里附上图片路径（如
output/xf-image/cat.png）——见下方说明 - 失败处理：脚本以非零退出码返回错误（含审核类提示），stderr 可读；不要把空文件当成功
控制台图片显示说明（必读）
现象：send_file_to_user 发送的图片会出现在控制台"完成步骤"折叠区内，且因 file:// URL 浏览器无法打开，点击不显示。
对策（无需改代码，按此约定执行即可）：
- 发送后，在回复正文里附上图片路径（如：
图片已保存到 output/xf-image/cat.png）。控制台会把主消息流正文中的文件路径渲染为可点击链接，用户直接点击即可查看。 - 用户反馈看不到/点不开图片时：不要重复排查，直接
send_file_to_user重发一次——重新发送后图片会随主消息流正确显示。 - 折叠区里那份无法点击的图片忽略即可，无需向用户解释技术细节。
- ⚠️
view_image的展示不能替代发送。只要用户要求"发给我/发送"，就必须执行send_file_to_user——不要因为 view_image 已经显示过图片就跳过发送步骤。
> 背景：该折叠显示是 QwenPaw 控制台对工具结果消息的固有行为，不是本技能的 bug。
错误码提示
讯飞安全审核相关错误，脚本会给出友好提示：
| code | 含义 | 建议 |
|---|---|---|
| 10021 | 输入内容触发安全审核 | 调整描述词，减少敏感描述 |
| 10022 | 生成结果被安全审核拦截 | 调整描述词，减少敏感描述 |
| 10024 | 图片引擎内部报错（常因内容触发审核） | 调整描述词 |
注意事项
- ⚠️ Prompt 不超过 1024 字符，请求超时 120 秒
- ⚠️ 水印在右下角，
--crop-bottom默认裁 124px - ⚠️ 推荐尺寸 1024×1024
- ✅ 凭证从环境变量读取，
config.json不含真实密钥（仅config.example.json作模板）
文件结构
xunfei-image-gen/
├── SKILL.md # 本文档（含 QwenPaw frontmatter）
├── config.example.json # 配置模板（占位符，无真实密钥）
└── scripts/
└── xunfei_gen.py # 核心生图脚本 v2.2
