表情包使用指南
在评论区和讨论区发送表情图片。
表情分两种，都在同一个面板里：
- 黄脸 —— 系统自带的，永远都有，像文字一样大（整条消息只有它一颗时例外， 那时会和图片表情一样大），点了会插进你的输入框；
- 图片表情 —— 站长放在服务器上的图片文件。有什么表情、分几个合集， 完全取决于站长往素材目录里放了什么。
一、怎么发
两条路，效果一样。
1. 点表情按钮（推荐）
输入区工具条最右边那个笑脸按钮，点开是一个面板：
- 面板最上面是合集标签，最左边那一栏永远是「黄脸表情」，后面才是站长的合集；
- 面板下面是网格，点其中一个就选中了它；
- 面板记得你上次退出的那一栏 —— 关掉再点开、乃至刷新页面，都直接停在那一栏， 不必每次重新找。合集的排列变了（站长加了合集）或那一栏被删掉时，退回第一栏。
选中之后发生什么，取决于你点的是哪一栏：
| 你点的是 | 点一下之后 | 为什么 |
|---|---|---|
| 黄脸表情 | 插到输入框光标处，不发送 | 它就是个表情字符，要跟着文字排 |
| 图片表情（讨论区） | 立刻发送出去 | 讨论是即时流，跟微信一个手感 |
| 图片表情（评论区） | 插到输入框光标处，不发送 | 评论是一篇正在写的文章，不能被一个表情吞掉 |
点图片表情时，讨论里那一下不会动你的草稿：写了一半的正文、待发的图片、引用、 回复对象全都原样留着，表情是单独一条消息发出去的。
选完图片表情后讨论区的面板会关掉（发完就走）；黄脸那一栏不关 —— 通常要连着 挑好几个，关掉等于每插一个都要重开一次。
2. 手写语法
在正文里直接写 [@合集名/表情名]：
[@猫猫/开心]
合集名 和 表情名 就是服务器上素材目录与文件名（去掉扩展名）。
可以写在句子里，会跟着文字排，不会把整行断开：
今天天气真好 [@猫猫/开心] 出门走走
想展示这个语法本身而不是让它生效？把它写进代码块或行内代码 （
）—— 代码里的引用一律不展开， 与其它[@猫猫/开心][@ ]引用同一口径。
二、黄脸表情
最左边那一栏「黄脸表情」是系统自带的，所有设备上长得一模一样。
为什么要专门做这一栏：系统键盘里那些 emoji（😊😭😡）在 iPhone、安卓、Windows 上 画得各不相同 —— 同一句话换台设备看就不是一个样子了。这一栏用的是同一套图片， 所以你在哪台机器上看到的都是它。
三点与图片表情不同：
和文字一样大。它就是个表情字符的替代品，能塞进句子里跟着文字排：
今天天气真好 [@黄脸/微笑] 出门走走例外是整条消息只有它一颗的时候（前后没有别的文字，也没有别的表情）：那时它会放大到 和图片表情一样大 —— 单发一颗就是「发了个表情」，不是句子里的一个字。
点一下是插进输入框，不直接发（讨论区也一样）。所以可以连着挑好几个。
不用站长准备，永远都在。素材目录是空的站点照样有这一栏。
手打语法与图片表情完全相同，把合集名写成「黄脸」即可：
[@黄脸/微笑] ✅ 内置的那张
[@黄脸/并不存在] ❌ 没有这个表情，原样显示
想知道某一格叫什么，把鼠标停在面板里的那一格上 —— 显示出来的就是它的完整 token。
三、在哪些地方能用
| 表情包 | |
|---|---|
| 评论区 | ✅ |
| 讨论区 | ✅ |
| 博客正文 | ❌ 原样显示 [@猫猫/开心] |
| 云剪贴板正文 | ❌ 原样显示 |
博客正文走的是另一套渲染管线（它还要处理投票组件与代码高亮），刻意不支持表情。
想在博客里放表情，把图传到图床再用 [@<10位图床ID>] 引用，或者贴图片直链。
四、分隔符为什么是斜杠
语法用 / 分隔合集名与表情名，而不是常见的连字符 -：
[@猫猫/开心] ✅ 合集「猫猫」，表情「开心」
[@猫猫-开心] ❌ 不是表情语法，原样显示
因为文件名里可以有连字符。如果按 - 切分，[@猫猫-开心-难过] 就没法判断
到底该切成「猫猫 + 开心-难过」还是「猫猫-开心 + 难过」。而斜杠是文件系统的保留字符，
文件名里不可能有 —— 所以按斜杠切永远只有一种切法。
顺带一个好处：这个语法永远含有 /，所以它绝不会被误认成剪贴板（8 位）或图床
（10 位）引用 —— 那两种 ID 只认字母和数字。
五、写错了会怎样
写错合集名或表情名（或者站长删掉了那个文件）时，那个位置会显示你的原文：
[@猫猫/并不存在]
不是破图标，也不是空白 —— 你看得见自己写的是什么，一眼就知道错在哪。 这与图床引用坏掉时显示裂图不同，是有意的：表情是一串你要手打的名字， 比一串要复制的 ID 更容易敲错。
这个降级是粘性的：一旦某条消息里的表情显示成了原文，在这一页刷新之前 它不会自己变回图片。站长补上了文件也要刷新才看得到。
六、限制
- 一条消息里最多展开 30 个表情，超出的部分保留原文。
- 表情不会产生通知，也不会被算作 @ 提及。
- 表情消息与普通消息一样走发言限频（讨论 120 条/分钟）—— 点表情发送、拍一拍、带图消息各算一条，连着点比打字消耗得快。
七、给站长：怎么加表情素材
「黄脸表情」那一栏是内置的，不从这个目录读 —— 你不用管它，也没法用这个目录 把它换掉。想改它的表情清单要改代码（
src/lib/emoji-faces.json）。 有一点要注意：内置的名字优先。你如果也建了个叫「黄脸」的目录，只有内置清单里 没有的那些名字才会用到你的图 —— 撞名不会报错，只是不生效；面板里也不会为它多出 一栏（那一栏上永远只写内置的那份）。⚠️
用户与音频是保留合集名，建了也不生效（目录会被直接跳过，面板里不出现）。 这两个名字已经被另外两条语法占住了，它们的形状与本语法完全一样（都是[@A/B]），所以不可能共存：
用户—— 用户名片[@用户/张三]，见docs/guide/内容引用语法指南.md第五节；音频—— 音频引用[@音频/<ID>]，见docs/guide/音频床使用指南.md。别用这两个名字建目录。
素材放在服务器的 instance/stickers/ 下（可用环境变量 STICKERS_DIR 改到别处）。
这个目录不进 git 仓库，是运行时数据 —— 所以部署时要手动把图同步上去。
目录结构
instance/stickers/
├── 猫猫/ ← 合集名（会写进 token）
│ ├── info.json ← 可选：显示名 / 排序 / 隐藏
│ ├── 开心.gif
│ └── 难过.webp
└── 日常/
└── 打招呼.png
- 目录名 = 合集名，文件名去掉扩展名 = 表情名。这两样就是 token 里的两段。
- 支持的扩展名：
.gif.webp.png.jpg.jpeg。 - 不递归：只扫一层，所以语法里也只有两级。
- 点开头（
.）或下划线开头（_）的文件与目录会被跳过，Thumbs.db与__pycache__同理 —— 拿它们放草稿或系统垃圾就行。
info.json（可选）
放在合集目录里，三个字段都是可选的：
{
"title": "猫猫合集",
"priority": 10,
"ignore": false
}
| 字段 | 作用 |
|---|---|
title |
面板标签上显示的合集名。不写就用目录名。只影响显示 —— token 里永远用目录名 |
priority |
合集排序，数字大的排前面。不写按 0 算 |
ignore |
true → 整个合集隐藏：面板里没有，手打 token 也取不到图 |
title和目录名可以不一样，这是推荐做法：目录名要短好打字（token 里用它）， 显示名可以写全（「猫猫合集」）。
生效时机
不需要重启服务。 加文件、删文件、改 info.json 最多 60 秒后生效。
换掉同名文件的内容（比如把 开心.gif 换成另一张图）是立刻生效的 ——
服务器每次请求都重新读磁盘字节，缓存里只有名字。但浏览器那边有 1 天缓存，
所以换了图之后自己可能要强刷一下才看得到。
两个注意
- 不要放 SVG。 服务器只接受 PNG / JPEG / GIF / WebP，而且是按文件内容的
真实类型判定的 —— 把一个
.svg改名成.png丢进去也没用，照样会被拒绝。 （SVG 能内嵌脚本，内联下发等于给了别人一个同源 XSS 的口子。） - 同名多扩展名时按固定优先级取一个：
.gif>.webp>.png>.jpg>.jpeg。 所以开心.gif和开心.png同时存在时，只有.gif会被用到。
版权
素材放上去就是对外公开提供了（未登录的读者也要能看到公开评论里的表情）。 用之前请确认你有权这么做 —— 尤其是从社交平台「免费分享」来的合集， 那句话往往只授权了转发，没有授权你再分发或公开传播。