DOCUMENTATION / v1.0.0-beta1

把表情接入你的 Agent。

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

01 / 一句话安装

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

请阅读 https://timmyagentic.si/install.md，直接为当前 Agent 安装并配置 Emomo，完成后验证搜索和图片下载。

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

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

npm install -g --ignore-scripts https://github.com/timmyagentic/emomo/releases/download/v1.0.0-beta1/timmyagentic-emomo-cli-1.0.0-beta1.tgz
emomo --version
emomo skill install --agent codex

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

02 / 搜索、看图、下载

emomo doctor
emomo search "收到" --limit 5
emomo get <返回的-id>
emomo download <返回的-id> --dir ./memes

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

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

如果保存过本地图库，可明确选择公开服务：

emomo search "开心" --api-url https://api.timmyagentic.si/agent/v1 --limit 5

03 / REST API

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

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

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

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

共享服务使用中文单字/双字与英文词的 FTS5 / BM25 检索，多个检索词为 OR 召回。图片标签、说明和可靠 OCR 参与索引。它不会自动调用模型、生成描述、重排或恢复旧服务；Agent 可自行改写一次关键词。

每个 Cloudflare 边缘节点按同一 IP 约每 60 秒 30 次请求限流；计数为最终一致，不是全局硬上限。请求体最大 8 KiB，Worker 内部成功响应缓存 60 秒。429 响应包含 Retry-After，请尊重退避时间。共享图库有 7,302 张静态主图，467 个重复版本不在公开索引中。图片由 images.timmyagentic.si 提供完整字节。

04 / 本地图库

已有本地目录可用 emomo catalog use /path/to/catalog 明确选择，也可每次指定 --catalog。本地模式不上传图片或文字，缺盘时明确失败，不自动回退到云端。导入命令和维护流程见 CLI README。

本地目录支持 --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。

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