# sticker — 给 Claude 用的表情包库

你把喜欢的表情包 / gif 传上来、打上标签（开心 / 生气 / 委屈…），聊天里 Claude 就能按情绪挑一张发出来。
后端一个文件（`server.py`，Python + fastmcp），网页一个文件（`sticker.html`），数据一个目录（`data/`）。

## 需要

- Python 3.10+，Claude Code 已安装并登录（`claude` 命令能用）
- 不需要 VPS。装在自己电脑上就能跑；`install.sh` 那套是 Linux（systemd）的，Mac / Windows 见下面"没有 VPS"
- 聊天界面在别的机器上（比如手机）才需要挂域名或打隧道，见"显示不出来？"

## 部署（三步）

```bash
# 1. 拿下来放到想放的目录，看一眼 config.json（端口、名字…见下）
git clone https://github.com/CeylonShenyun/sticker-kit /opt/sticker && cd /opt/sticker && nano config.json

# 2. 以装了 Claude Code 的那个用户执行安装（会 sudo）
sudo ./install.sh

# 3. 打开网页传几张表情、打标签
#    http://127.0.0.1:18018/
```

## 没有 VPS / 不用 systemd（Mac、Windows、或者就想手动跑）

```bash
python3 -m venv venv
venv/bin/pip install -r requirements.txt        # Windows: venv\Scripts\pip install -r requirements.txt
venv/bin/python server.py                       # Windows: venv\Scripts\python server.py
claude mcp add -s user --transport http sticker http://127.0.0.1:18018/mcp
```

服务要一直开着（关了 Claude 就找不到工具）。Mac 上用 launchd 或者开个 tmux 挂着都行。
Windows 没实测过，Python 逻辑上没问题。

## config.json

| 字段 | 意思 |
|---|---|
| `port` | 后端端口 |
| `mcp_name` | 注册进 Claude Code 的 MCP 名，工具就叫 `mcp__sticker__sticker_find` 这样 |
| `public_base` | 图片外链前缀。空 = `http://127.0.0.1:端口/i`，只有本机能看；聊天界面走公网就填 `https://你的域名/i` |
| `tz_hours` | 时区（东八区填 8），只影响记录时间 |
| `max_mb` | 单张上限（M） |
| `title` / `subtitle` | 网页标题和副标题 |

改了 config 记得 `systemctl restart sticker`。

## Claude 怎么用

装完 Claude Code 里多了五个工具：

- `sticker_list` 看库里有哪些标签、各几张
- `sticker_find("开心")` 按标签 / 关键词挑几张，返回现成的 `![](地址)`；空着就随机
- `sticker_add("/path/to/图.gif", "开心 笑")` 把本机一张图收进库（网页不方便传的时候）
- `sticker_tag(id, "委屈")` 改标签 / 备注
- `sticker_erase(id)` 删（删了就没了）

用法就是让它"发个开心的表情"。它会 `sticker_find` 挑一张，把那行 `![](地址)` 单独放进回复。
想让它主动发，把这段写进你的 CLAUDE.md 之类的地方：

> 聊天里情绪到位了可以发表情：先 sticker_find("关键词") 挑，把返回里某一行 ![](地址) 原样单独一行放进回复。别每句都发。

## 预置表情包

想装好就有表情、或者发给朋友一份自带表情的包：把图放进 `seed/`，文件名当标签（`开心-笑.gif`），
启动时自动收进库，收过不重复。细节见 `seed/README.md`。

## 显示不出来？

`![](地址)` 只有在**能渲染 markdown 图片的聊天界面**里才显示成图（网页聊天、各种 bridge）。
纯终端里的 Claude Code 只会看到一行链接，这是终端的限制，不是坏了。

图能不能加载出来，取决于**看聊天的那个界面**能不能访问 `public_base` 那个地址（是界面去拉图，不是 Claude）：

- 界面和 sticker 在同一台机器（电脑上跑 Claude、电脑上看）：默认的 `http://127.0.0.1:端口/i` 就行，什么都不用配
- 电脑跑、手机看，同一个 WiFi：`public_base` 填电脑的局域网地址，如 `http://192.168.1.5:18018/i`；出了这个 WiFi 就看不到
- 电脑跑、在外面也想看：用 cloudflared / ngrok / tailscale 之类把 18018 端口打出去，`public_base` 填隧道给的地址
- 有 VPS 和域名：按 `nginx.example.conf` 反代，`public_base` 填 `https://你的域名/i`
- **图片那条路径不能加密码**。界面加载图片时不会带密码，锁了就是空白占位。示例配置里 `/i/` 已经 `auth_basic off`

改了 `public_base` 要重启服务。已经发过的表情是旧地址，不会跟着变。

需要本地文件路径的 bridge：图都在 `data/stickers/`，文件名就是 `sticker_find` 返回的 id 加扩展名。

## 常用

```bash
systemctl status sticker
journalctl -u sticker -n 50
```

卸载：`systemctl disable --now sticker && rm /etc/systemd/system/sticker.service`，再删目录。

## 说明

- 只收 png / jpg / gif / webp，按文件头判断，改后缀的文件进不来。
- 上传 / 删除接口没有鉴权，靠 nginx 的 basic auth 挡（示例配置里有）。`/mcp` 别暴露到公网。
- 数据只有 `data/` 一个目录，备份拷它就行。