webkubor/charmoji-sticker-skill
charmoji
Verified微信表情开放平台静态表情投稿全流程 SOP —— 一张 IP 正面照进,整套可提交素材出。覆盖 IP 命名与简介文案、9 情绪选题、museav 中台批量出图、240×240 表情图 / 750×400 详情页横幅 / 240×240 封面 / 50×50 聊天面板图标切图、透明背景与白描边机检、含义词字数校验、赞赏三件套、付费表情(10 微信豆)、审核红线与高频拒因;上架后还能一条命令出 1080×1920 竖版推广视频(合成走 reel-kit)。触发词:微信表情、表情包、表情专辑、表情投稿、提交表情、表情形象、微信表情开放平台、sticker、表情审核、含义词、赞赏引导图、付费表情、微信豆、表情封面、聊天面板图标、表情推广视频、表情包宣传片、表情串成视频。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.3 KB |
| examples/album.yml | config | 1.1 KB |
| examples/submit.md | markdown | 2.1 KB |
| references/animated.md | markdown | 8.8 KB |
| references/audit.md | markdown | 8.1 KB |
| references/ip-design.md | markdown | 4.4 KB |
| references/pitfalls.md | markdown | 15.1 KB |
| references/platform.md | markdown | 6.1 KB |
| references/specs.md | markdown | 9.7 KB |
| scripts/check_assets.pyexecutable | script | 12.9 KB |
| scripts/fit_assets.pyexecutable | script | 8.2 KB |
| scripts/gen_album.shexecutable | script | 7.5 KB |
| scripts/install_skill.pyexecutable | script | 9.0 KB |
| scripts/ip.py | script | 34.8 KB |
| scripts/lint.shexecutable | script | 4.5 KB |
| scripts/make_gif.py | script | 6.8 KB |
| scripts/make_promo.pyexecutable | script | 6.7 KB |
| scripts/make_submit.pyexecutable | script | 5.6 KB |
| scripts/new_album.shexecutable | script | 10.7 KB |
| scripts/page_tpl.py | script | 10.9 KB |
| scripts/restyle.py | script | 8.3 KB |
| templates/album.yml | config | 1.5 KB |
references/pitfalls.md
View on GitHub# 踩坑记录(给下一个 agent / 下一个我)
全部来自 2026-08-26~27 开发这个 skill 时的真实翻车,每条都写清**症状 → 根因 → 修法**。
前四条与表情包无关,是写中文 shell 脚本的通用陷阱,值得单独记住。
---
## 一、bash:变量名后紧跟全角标点,变量名被吞
**症状**:`set -u` 下报 `JOBS?: unbound variable`,而 `JOBS=3` 明明在上面赋过值。
```bash
JOBS=3
echo "并发 $JOBS,单张约 50s" # ✗ 炸:变量名被解析成 JOBS,(含全角逗号的字节)
echo "并发 ${JOBS},单张约 50s" # ✓
```
**根因**:全角标点(`,。():`)是多字节 UTF-8,bash 在解析 `$NAME` 边界时会把这些字节
当成标识符的合法组成部分,于是变量名变成了 `JOBS\xef\xbc\x8c`。
**修法**:**中文输出里的变量一律写 `${VAR}`**。写完扫一遍:
```bash
grep -nP '\$\{?[A-Za-z_][A-Za-z0-9_]*[^\x00-\x7F]' *.sh
```
这条只在中文脚本里出现,英文脚本永远不会踩 —— 所以英文项目的经验里查不到。
## 二、bash:`set -e` + `(( i++ ))` 静默终止脚本
**症状**:循环一次都没执行,脚本 exit 0 干净退出,没有任何报错。查了半天以为是出图 API 挂了。
```bash
set -e
i=0
(( i++ )) # ✗ i 的旧值是 0 → 算术表达式求值为 0 → 退出码 1 → set -e 终止脚本
i=$((i + 1)) # ✓
(( i += 1 )) # ✓ 赋值形式返回 0
```
**根因**:`(( expr ))` 的退出码取决于表达式的值 —— 值为 0 就返回 1。`i++` 是后缀,
先返回旧值 0,于是第一次自增必炸;`i` 从 1 开始时反而不炸,所以这个 bug 很会骗人。
**顺带一条边界**:`[[ cond ]] && cmd` 这种写法在 `set -e` 下**是安全的** ——
条件假时 `[[ ]]` 不是 `&&` 列表的最后一个命令,属于 set -e 的豁免情形。
别为了「保险」把它们全改成 `if`,那是在改不存在的 bug。真正危险的是**独立的** `(( ))` 语句。
**判定顺序**:脚本静默 exit 0 且循环没跑 → 先查 `set -e` 与算术/测试语句的组合,
再去怀疑外部命令。别反过来。
### 同一家族的另两个入口(我后来又栽了一次)
`set -euo pipefail` 里能静默杀掉脚本的不止算术语句。这两个我是在批量出图 8 张全失败、
**且一条错误日志都没打印**的情况下才挖出来的:
```bash
# ① 命令替换里只有一个命令,它的非零退出码就是命令替换的退出码
out=$(museav gen ... 2>&1) # ✗ 出图失败 → museav exit 1 → set -e 杀子 shell
out=$(museav gen ... 2>&1 || true) # ✓
# ② pipefail 下,管道里任何一环失败都算整个管道失败 —— grep 无匹配就是「失败」
url=$(grep -oE 'https://\S+' <<< "$out" | grep -v '/refs/' | tail -1) # ✗
url=$(grep -oE 'https://\S+' <<< "$out" | grep -v '/refs/' | tail -1 || true) # ✓
```
②尤其阴:**它只在"没匹配到"的那条路径上炸**,也就是只在出错时炸 ——
正常流程测一百遍都测不出来,一旦线上出错就连错误处理代码一起带走。
有意思的是旧代码 `url=$(museav ... | grep ... | tail -1)` **反而没事**:
museav 在管道中间,退出码取自末尾的 `tail`(总为 0)。我为了"看到错误原文"把 museav
从管道里拆出来单独放进命令替换,恰好同时踩进 ① 和 ②。**改动引入的 bug 常常长这样:
你修好了 A,顺手改变了原本兜住 B 的那个巧合。**
**判定顺序补充**:凡是「错误处理代码看起来没执行」的现象,先怀疑
`set -e` / `pipefail` 在错误处理之前就把进程杀了 —— 而不是怀疑自己的 if 条件写错。
调试手段:临时 `set +e` 或 `bash -x` 跑一遍,看输出停在哪一行。
## 三、bash:`wait -n` 需要 4.3+,macOS 自带的是 3.2
`/bin/bash` 在 macOS 上是 GNU bash 3.2.57(GPLv3 之后 Apple 就不升了)。
`wait -n`、关联数组 `declare -A`、`${var^^}` 全都不支持。
`#!/usr/bin/env bash` 在你机器上可能解析到 homebrew 的 bash 5,但别人 clone 走就未必。
并发限流的兼容写法(分批 wait,3.2 可用):
```bash
for x in "${LIST[@]}"; do
work "$x" &
if (( i % JOBS == 0 )); then wait; fi # 条件放在 if 里,规避第二条坑
done
wait
```
## 四、别拿「终端所见」推断「管道所得」
**症状**:`museav reverse ip.png` 在终端打印一整份 SCULPT 报告(风格、标签、六要素、中英 prompt),
于是我写了 awk 去抓「英文 prompt:」那一行。结果重定向到文件后,文件里只有 107 字节的纯英文 prompt ——
那份报告走的是 **stderr**,stdout 只有结果本身。我的 awk 抓空,脚本反而回归。
**根因**:CLI 的人类可读输出(stderr)与机器可读输出(stdout)是两个通道。
看终端截图写解析代码,等于对着 stderr 编程。
**修法**:写解析前先 `cmd > /tmp/out.txt` 再 `od -c /tmp/out.txt` 看真实字节。
一条命令的成本远低于一次回归。
### 反面的另一半:也别把 stderr 扔掉
同一个坑的镜像版本。我在批量出图里写了 `museav gen ... 2>/dev/null`,
于是 8 张图全失败时,日志只有一句「出图失败」。我一度怀疑是新加的姿势 prompt 触发了审核。
手动跑一次(不吞 stderr)才看到真实原因:
```
❌ 中台 API /api/generate 失败: 出图太频繁了,喝口茶歇会儿再来
```
是**上游限流**,跟 prompt 毫无关系。`2>/dev/null` 把唯一能定位根因的信息删了,
换来的"干净输出"让排查方向整体跑偏。
**修法**:`2>&1` 合并后再从中提取,失败时把上游原文打出来;
并按错误类型分流 —— 限流要**退避**后重试(`sleep $((n*45))`),
真错误重试无意义、直接报原文。
**合并 stderr 后必然出现的新坑**:中间产物的 URL 也进了输出流。
我用 `grep -oE 'https://...\.png' | tail -1` 取结果地址,
而失败时输出里只剩垫图的上传地址 `https://.../refs/xxx.png` —— 会被当成出图成功。
提取前先排除中间产物:`grep -v '/refs/'`。
**推论**:`2>/dev/null` 是给**已知且无害**的噪音用的,不是给"我还没读过的输出"用的。
在读懂一个命令的两个输出流分别装什么之前,别急着静音任何一个。
---
## 五、透明 PNG 垫图,读图会把透明区读成 "black background"
**症状**:透明底的 IP 图喂给读图逆向,出来的 prompt 尾巴是
`..., against a black background.`,再拿这句去出图,出的全是黑底 —— 与「须透明背景」直接冲突。
**修法**:出图前把背景短语从 prompt 里剥掉,再由自己的 GUARD 段落统一声明透明背景。
第一版我写的是枚举介词的正则 `(against|on)\s+a\s+.*background`,
下一次读图就返回了 `sitting in front of a black background` —— **没匹配上**。
`against / on / in front of / over / with / set in…` 永远列不全。
改成按逗号分段、丢掉含关键词的整个子句,与介词无关:
```bash
awk -v RS=',' 'BEGIN{sep=""} tolower($0) !~ /background/ {
gsub(/^[[:space:]]+|[[:space:]]+$/, ""); if ($0 != "") { printf "%s%s", sep, $0; sep=", " }
}' <<< "$IP_DESC"
```
顺带避开了另一个雷:`pink bows on its ears` 里的 `on` 不能被吃掉。
按子句过滤天然不会误伤 —— 这个子句里没有 `background`。
**推论**:从自然语言里剔除某类信息时,**按语义单元(子句)过滤关键词**比
**按句式枚举模式**更鲁棒。前者只需要一个词,后者要穷举所有说法。
## 六、AI 出图不严格遵守 `--ratio`
`museav gen -r 1:1` 实测返回 1240×1269(近似方形但不是),文件 2MB。
**所以切图环节不能跳过**,也不能假设出图尺寸。永远过一遍 `fit_assets.py`。
## 七、均值哈希对「同底色」图集体失效
**症状**:8 张画面明显不同的白底表情,两两汉明距离全是 0,被判「整套差异不足」。
**根因**:ahash 把图缩到 8×8 灰度再比均值。主体只占画面 55%、背景是大片白时,
64 个采样点里绝大多数落在背景上 → 所有图都长一样。
**修法**:① 先裁到主体外接框再算哈希;② 改用差分哈希(比相邻像素的明暗关系,
对低对比度更敏感)。主体框的取法要兼容两种图:有 alpha 的按 alpha 找,
全不透明的照片型按「非白像素」找。
## 八、白描边检测会把白色系角色全判违规
**症状**:一只白猫的每张图都报「主体轮廓 33% 近白 → 白色描边」。
**根因**:只看轮廓的近白比例。白猫的轮廓当然近白 —— 因为它内部也是白的。
**修法**:判**对比**而不是判绝对值 —— 轮廓近白比例减去主体内部近白比例,
差值超过阈值才是描边。验证要**双向**做:
构造一张真带 4px 白描边的图确认仍能 FAIL(否则你只是把检测器改废了),
再用白猫确认不再误报。只测一个方向等于没测。
## 九、批量切图会把 raw/ 里的非表情图一起吞掉
横幅底图 `banner-src.png`、IP 原照都放在同一个 `raw/` 下,
批量模式按扩展名收集文件 → 8 张表情图变成 10 张,含义词条数校验跟着报错。
按文件名前缀排除(`banner-src` / `ip.` / `00-`),并让上游的计数逻辑用同一套排除规则。
## 十、抠图抠不出主体:先怀疑自己的预处理,别怀疑模型
**症状**:`museav remove-bg` 输出条纹残影,主体几乎全被抠掉。换四张源图、换两个模型都一样。
我一度归因为「白猫配米色背景对比太低」——**错的**。
**排查方法**:拿一个基准实现(`rembg` 官方 Python 包)跑同一张图。基准能抠出来,
说明模型没问题、图没问题,问题在自家的预处理/后处理。然后逐项对齐参数。
**查出三个独立 bug,共同点是全都不报错**:
1. **`sharp` 对单通道 raw 做 `resize` 后返回 3 通道**(灰度被展开成 RGB)。
代码仍按 `mask[i]` 索引 → 以 1/3 步长错位采样 → 条纹残影。**这是主因。**
探针只要一行:`toBuffer({resolveWithObject:true})` 打出 `info.channels`。
2. **输入尺寸与归一化参数被硬编码成一套**,而每个模型都不同
(isnet 1024/std 1.0,u2net **320**/ImageNet 参数)。u2net 因此直接崩,
isnet 因 std 用 0.5 而非 1.0 把输入值域放大一倍。
3. **BiRefNet 的输出是 logits,要先过 sigmoid**;ISNet/U2Net 的输出已在 0-1 区间。
漏了不报错,只会得到一张几乎全半透明的 mask。
**推论**:图像/张量管线里最危险的不是崩溃,是**隐式的形状与值域变换** ——
通道数被悄悄改掉、值域被悄悄放大、logits 被当概率用。这类 bug 不抛异常,
只让结果「看起来怪」。所以:
- 每次跨库传 buffer,都打一次 `length / channels / width×height` 对不对得上;
- 模型的 size/mean/std/是否 sigmoid **必须随模型定义**,不能提到全局常量;
- 有基准实现就拿数值逐项对齐,别靠看图猜。
(这三个 bug 已在 museav-cli 源码里修掉,并加了 BiRefNet-Lite 作默认模型。)
## 十一、上游有频次限制,连跑几轮就会被挡
**症状**:改完出图 prompt 想验证效果,连续跑第三、四轮时 8 张全失败。
```
❌ 中台 API /api/generate 失败: 出图太频繁了,喝口茶歇会儿再来
```
冷却期是**分钟级甚至更久**(我 45s / 90s / 135s 三级退避都没等出来),
所以「改一版就跑一轮验证」的节奏在有频次限制的上游面前是行不通的。
**修法**:
1. 退避重试要有,但别指望它能穿过长冷却期 —— 它解决的是偶发限流,不是配额耗尽。
2. **验证性实验要提前规划批次**:一次跑够、一次看全,而不是改一点跑一次。
3. 撞上冷却期就**如实标注「未验证」**,别把「对症的推断」写成「已验证的结论」。
我的姿势多样化改动就停在这一步 —— 代码保留,文档写明没跑通对照实验。
## 十二、幂等重跑要跳过已完成项,别重复烧配额
批量出图会偶发失败(上游超时、审核拦截),8 张出 6 张,后面的「张数须 8~24」直接 FAIL。
两个必须同时做的设计:
1. **单张失败重试一次** —— 一次重试能救回大部分偶发失败。
2. **重跑时跳过已产出的项** —— 否则用户为了补 2 张要重出 8 张,白烧 6 次配额;
同时提供 `--regen` 显式强制重出。
推论:任何「幂等」的批处理脚本,幂等的含义应该是**补齐差集**,不是**重做全集**。
后者虽然结果也对,但对计费/限速的上游是灾难。
## 十三、工具的默认值可能落后于策略真源
**症状**:`cs image upload demo.jpg --path skills` 顺利成功,返回 PicX 的 jsdelivr 链接。
但 `cs resource policy` 明确写着「picx = 冻结新增,r2 = 当前主力,新图统一走 R2」。
命令的 `--help` 也自称「默认 → PicX,适合所有项目」。**同一个 CLI 的两个子命令自相矛盾。**
**根因**:策略改了(R2 变主力),但上传命令的默认后端没跟着改。
默认值是最容易滞后的那部分——它不报错,只是静静地把新数据写进已废弃的通道。
**修法**:涉及「往哪写」的操作,先查策略真源(这里是 `cs resource policy`),
再显式指定目标(`--target r2`),不要依赖默认值。已经写错的要清理:
```bash
gh api -X DELETE repos/<owner>/<repo>/contents/<path> -f message="..." -f sha="$sha"
```
**推论**:文档、CLI 帮助、默认值、策略真源这四者会各自漂移。判断顺序是
**策略真源 > 文档 > 帮助文本 > 默认值**,且发现不一致时要回头把滞后的一方修掉,
否则下一个 agent 会照着同一个默认值再错一次。
## 十四、机检查得了规格,查不了「画面里写了什么」
机检能判尺寸、体积、透明背景、相似度,**判不了画面里的文字内容**。
一套专辑被驳回,理由是详情页横幅与赞赏引导图「含有非自有版权的应用程序推广信息【微信】」——
就因为宣传图上印了「微信表情包专辑」几个字。这几张图机检全是 ✅。
**修法**:提交前必须人眼逐张过一遍对外展示图(横幅、赞赏引导图、赞赏致谢图),
确认没有任何品牌名、App 名、平台名 —— 包括「微信」自己。
把这一步写进流程,而不是指望机检。
**推论**:任何自动检查都有它照不到的维度。清楚知道边界在哪,
比假装机检通过就等于合规更重要。`check_assets.py` 的输出里因此写明
「机检只能拦规格问题,创意与权利问题得靠你自己」。
## 十五、静默压缩比报错更危险
微信表情平台对超规格素材**不报错、不拒收,直接压缩裁剪**。
这类「宽容」的上游最坑:你以为传成功了,主体被裁掉才发现。
凡是上游会静默处理的字段,都要在本地先校验到位 —— 这就是 `check_assets.py` 存在的理由。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |