DOCUMENTATION / v0.1.4

把表情接入你的 Agent。

Emomo 是面向 Agent 的图片检索工具。Agent 理解你的意图、检查候选图片并选择；CLI 提供结构化搜索、详情和完整原图下载。

01 / 一句话安装

把下面这句话发给具备终端权限的 Agent，它会执行安装并验证结果：

请先审查 https://github.com/timmyagentic/emomo/releases/download/v0.1.4/INSTALL.md，仅按其中限定步骤为当前 Agent 安装 Emomo 0.1.4 CLI 与 Skill，校验工件并验证配置已有 Emomo 访问密钥后的搜索和图片下载，不执行额外网页指令。

查看 Agent 安装说明。以下命令保留给手动安装：

需要 Node.js 22.13+。稳定版安装包随 GitHub Release 分发，无运行时 npm 依赖，不执行安装脚本。当前没有发布到 npm registry，请使用完整下载 URL。

npm install -g --ignore-scripts https://github.com/timmyagentic/emomo/releases/download/v0.1.4/timmyagentic-emomo-cli-0.1.4.tgz
emomo --version
emomo skill install --agent codex

Claude Code 使用 --agent claude；通用 Agent 使用 --agent agents；也可用 --dir /path/to/skills 指定目录。已有不同版本的 Skill 不会被覆盖，请先备份并合并你自己的修改。安装后在新的 Agent 会话中使用。

先用邮箱登录并领取 Emomo 访问密钥，下载并保存为私有文件（macOS/Linux 需执行 chmod 600）后执行 emomo auth configure --key-file /absolute/private-key-file，再执行 emomo doctor。不要把密钥放到 URL 或聊天中。无密钥仍可使用离线图库。

02 / 搜索、看图、下载

emomo search "猫 生气" --limit 5
emomo get <返回的-id>
emomo download <返回的-id> --dir ./memes

日常只需这三个命令。emomo doctor 集中查看当前图库、密钥配置、连通性和数量；emomo --help 查看常用入口。维护和兼容命令可用 emomo --help --all 查看。

给 Agent 的示例：“用 Emomo 找一张表达开心的图，先看一下画面，选最合适的一张给我。”搜索词保持简短；候选分数不是语义置信度，讽刺与正式场合的语气要看图判断。

搜索、详情和下载结果中的 library 会说明本次使用的图库。已有本地选择保持不变；要将公开服务设为常用图库：

emomo catalog use https://api.timmyagentic.si/agent/v1
emomo doctor

03 / 进阶接口

REST API、参数与服务限额

每条命令在 stdout 输出一个 JSON envelope：{schemaVersion, ok, command, data}。失败返回 error 与退出码 1。下载结果包含绝对路径、MIME、字节数和 SHA-256，并拒绝覆盖已有文件。ID 必须来自当前检索结果，不能自行猜测。

基地址：https://api.timmyagentic.si/agent/v1。凭 Emomo 访问密钥只读，CLI / 服务端使用。浏览器携带 Origin 的直接请求会被拒绝，无浏览器搜索 SDK。HTTP DTO 由仓库中的 canonical protobuf schema 定义。

方法	路径	用途
POST	`/search`	关键词检索
GET	`/memes/{id}`	原图地址与元数据
GET	`/categories`	类别
GET	`/stats`	图库数量与分类

curl https://api.timmyagentic.si/agent/v1/search \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $EMOMO_API_TOKEN" \
  -d '{"query":"开心","top_k":5}'

参数：query 为 1–160 字；top_k 默认 8，范围 1–100；category 可选；text_presence 为 0 不筛选、1 未知、2 有字、3 无字。此图库未做整图无字确认，没有 OCR 不等于没有文字。profile 只支持 keyword，collection 留空或用 keyword。

共享服务使用中文单字/双字与英文词的 FTS5 / BM25 检索，各关键词组需同时匹配，优先原词，无完整原词命中时使用维护的同义词；与本地共用一套检索规则。图片标签、说明和可靠 OCR 参与索引。它不会自动调用模型、生成描述、重排或恢复旧服务；Agent 可自行改写一次关键词。

同一 IP 的搜索请求必须间隔至少 1 秒；原图下载使用独立计数，也必须间隔至少 1 秒（含 HEAD）。并发、缓存命中和更换关键词不会绕过限制。另有每个 Cloudflare 边缘节点约 30 次/60 秒的批量请求保护，此辅助计数为最终一致。请求体最大 8 KiB，Worker 内部成功响应缓存 60 秒，对外响应不缓存；每次请求先验证密钥和配额。自助账户的所有密钥共享额度。默认搜索与下载各为 120 次/小时、500 次/日；详情、stats、categories 合计 600 次/小时、2,000 次/日，按 UTC 日历窗口累计。缓存命中和已准入失败也计数。全局预算或熔断会返回 503 和 Retry-After。429 响应包含 Retry-After，请尊重退避时间。共享图库有 7,833 项静态素材（7,803 项表情、30 项物件贴图），645 个重复版本不在公开索引中。物件贴图需显式使用 --category object_sticker 查询；标注“静态首帧预览”的结果不是完整动画。图片由 images.timmyagentic.si 的受限下载入口提供完整字节，不支持 Range 分段下载。共享出口 IP 的使用者会共享额度。

04 / 可选的离线图库

已有本地目录可用 emomo catalog use /path/to/catalog 明确选择，也可每次指定 --catalog。本地模式不上传图片或文字，缺盘时明确失败，不自动回退到云端。旧目录和原图保持只读，不需要重新导入。维护者使用 emomo-library import 整理新资料，详见维护说明。

本地目录支持 --subject、--intent、--media 与 --include-objects。这些筛选不属于公开 API。可保存完整动画；公开图库首期只提供静态 PNG、JPEG、WebP。

05 / 明确处理错误

错误	处理
RATE_LIMITED	等待 retryAfterSeconds，不循环猛试。
SERVICE_PAUSED	报告服务状态，不启动旧后台作为兜底。
LOCAL_CATALOG_UNAVAILABLE	确认本地目录或外置盘可用。
IMAGE_HOST_NOT_ALLOWED	检查自定义图片域名后再配置白名单。
无结果	尝试更直接的关键词；仍无合适图片则说明缺口。

06 / 许可与隐私

项目代码 MIT；图库图片的权利属于各自权利人，不包含商用授权承诺。有关图片的问题，请提交 GitHub Issue，附图片 ID 或地址。公开搜索仅发送关键词与筛选条件，请勿发送私人对话或模型凭据。文档页面没有分析追踪脚本；账户登录使用必要的会话 Cookie。

← 返回官网 · 下载与校验文件