Codex Pets 是一个面向 Codex 兼容动画宠物包（pets）的社区画廊、命令行工具（CLI）与 MCP 服务。项目基于 YDB 存储资产，提供公开站点、本地账户体系、人工审核、公开生成请求以及已批准和待处理宠物的公开详情页。公开站点地址为 https://pets.ydb-qdrant.tech/ 。
主要用途 为 AI 编码智能体（如 Codex）提供可搜索、可安装的动画宠物包。 提供公开 MCP 服务，让编码智能体能够搜索、检查、安装和分享已批准的宠物包。 提供 CLI 安装命令：npx @astandrik/codex-pets install <slug> 。 允许用户通过网站表单或远程 MCP 请求生成新的宠物。 生成并管理宠物包的公开元数据、徽章、嵌入卡片等。
主要能力 公开画廊：可爬取的 HTML 画廊位于根路径 / ，分页使用 /?page=2 、 /?page=3 等。旧版 /pets 目录 URL 会永久重定向到对应主页 URL，宠物详情仍在 /pets/<slug> 。 公开 MCP 工具： search_pets：发现已批准的宠物，当需要候选或缺少确切 slug 时使用。 get_pet：获取单个公开宠物卡片，当已有已批准 slug 时使用。 get_install_instructions：获取安装命令，不增加指标。 get_badge_code：为已知 slug 生成 README 徽章片段。 get_embed_code：为已知 slug 生成 iframe 嵌入片段。 get_card_code：为已知 slug 生成动画 GIF 片段，默认为仅精灵图模式。 get_pet_request_info：了解公开的新宠物请求工作流，但不提交或检查私有请求。 HTTP 回退路由：包括 /api/openapi.json 、 /guides/best-codex-pets-for-ai-coding-agents 、 /guides/best-codex-pets-for-ai-coding-agents.md 、 /api/manifest.toon 、 /api/pets/<slug> 、 /api/pets/<slug>.toon 、 /pets/<slug>/markdown 、 /api/pets/<slug>/share 、 /badge/<slug>.svg 、 /card/<slug>.gif 等。 API 分页： /api/pets 和 /api/pets.toon 接受可选的 page 和 pageSize 参数。提供任一参数会启用附加分页元数据对象；不提供则保留旧响应形状。分页响应中，顶层 total 是返回的宠物数量，pagination.totalItems 是完整过滤后的数量。 生成请求：网站表单 /generate 和远程 MCP 共享一个队列。生成默认禁用，可通过网站表单和远程 MCP 使用。npm CLI 和浏览器 WebMCP 仅保留目录工具。 生成限制：全局每天 200 个已接受任务，默认每 IP 10 个，一个活动任务和五个等待任务，按莫斯科日历日计算。等待 30 分钟后过期，失败任务消耗配额。 生成流程：generate_pet 接受文本提示（1–2000 字符）、可选 displayName（最多 80 字符）以及新的随机 UUID requestId 。轮询 get_pet_generation(generationId) 每 5 秒一次。完成的任务返回未列出预览和下载： pet.json 、 lossless spritesheet.webp 和 pet.zip 。格式 v2 为 1536×2288，具有 9 个动画状态和 16 个朝向。结果在接受后 24 小时过期；幂等哈希保留 7 天。 元数据编辑：完成的新任务包含可编辑的名称/描述/标签。私密预览将描述更改原子保存到 pet.json 和 ZIP；标签存储用于画廊提交。保存不调用提供商，保持精灵图字节不变，需要当前元数据修订，提交后禁用。 提交审核：在过期前，使用私密结果页上的“Submit for review”保存永久画廊包和一个待处理提交，或通过 /submit 上传 ZIP。提交重试返回相同的收据。 技术栈：Next.js 16 App Router、React 19、TypeScript strict、Gravity UI + SCSS/BEM、通过 ydb-sdk 的 local-ydb / YDB 原生 gRPC、应用自有基于 YDB 的用户和会话的邮件+密码认证、宠物资产作为二进制大对象存储在 YDB、动态 robots.txt 、 sitemap.xml 、 llms.txt 、 llms-full.txt 和 OpenAPI JSON、面向智能体的 HTTP 访问通过 llms.txt / llm.txt 、 /llms-full.txt 、 /mcp 、 JSON 路由和 TOON 镜像、可选只读浏览器 WebMCP 工具、Yandex Metrika、JSZip + Sharp 用于包验证。
使用方式 安装 CLI： npx @astandrik/codex-pets install <slug> 。 本地运行 stdio MCP 服务器代理公开画廊。 公开 MCP 端点： https://pets.ydb-qdrant.tech/mcp 。 公开清单： https://pets.ydb-qdrant.tech/api/manifest 。 LLM 发现： https://pets.ydb-qdrant.tech/llms.txt 。 最佳指南： https://pets.ydb-qdrant.tech/guides/best-codex-pets-for-ai-coding-agents 。 本地开发：打开 http://localhost:3000 。本地 YDB 监控 UI 为 http://127.0.0.1:8765 。 部署：公开画廊无需机密即可渲染。账户登录、提交、审核和指标需要 YDB_PETS_ENDPOINT 、 YDB_PETS_DATABASE 和认证环境变量。可选的服务器端 MCP 指标需要 YANDEX_METRIKA_MP_TOKEN 和 YANDEX_METRIKA_MP_CLIENT_ID 。可选 IndexNow 通知通过 INDEXNOW_KEY 启用。 语义搜索：可选语义搜索使用 Yandex AI Studio 文本嵌入和 YDB 中的精确余弦排序。查询模式默认为 PET_SEARCH_MODE=lexical ；shadow 计算语义排序而不改变公开顺序；hybrid 结合词汇和文本语义排名。独立的 PET_SEARCH_VISUAL_MODE=off|shadow|hybrid 添加来自四个固定精灵图帧的离线视觉标题排名。配置 YANDEX_AI_STUDIO_FOLDER_ID 、 YANDEX_AI_STUDIO_API_KEY_FILE 和 PET_SEARCH_MODEL_REVISION=yandex-text-embeddings-v2-768-2026-07 。v2 运行时使用 768 维的托管 text-embeddings-v2-doc/query 模型。设置 PET_SEARCH_VISUAL_MODEL_REVISION=yandex-text-embeddings-v2-768-pet-vision-qwen3.6-v1 以使用兼容的 Qwen 视觉排名。旧版 256 维修订保留用于回滚。API 密钥仅通过秘密文件设置接受。提供商故障和超时回退到词汇结果；仅视觉故障保留文本混合顺序。
适用场景 AI 编码智能体需要发现、安装或分享 Codex 兼容动画宠物包时。 开发者希望为项目添加动画宠物徽章、嵌入卡片或 GIF 时。 用户希望通过文本提示生成新的动画宠物，并提交到社区画廊时。 需要公开、可爬取、面向 LLM 的宠物注册表时。
限制 生成默认禁用，必须通过网站表单或远程 MCP 明确启用。 生成结果 24 小时后过期，历史记录在过期后保留 7 天；过期条目无法打开。 清除浏览器数据会移除历史列表，但不会重置配额或取消任务。 没有基于 IP 的所有权查找、账户同步、服务器端历史枚举或新数据库模式。 历史、表单和结果页面排除分析和搜索索引；历史具有 private/no-store 和 no-referrer 头。 私密链接和 ID 必须保密；任何持有私密链接的人都可以打开对应结果或提交一次。 网站表单和远程 MCP 共享队列，受全局和每 IP 限制约束。 提交保存的包不调用生成提供商，也不改变生成配额。 文本和视觉回填需要显式 --dry-run 或 --apply ；视觉 --force 仅与 --apply 一起有效。 当 PET_RELATED_PREAPPROVAL_ENABLED 不是精确 true 时，批准会失败关闭，而不是发布缺少当前 V24 输入的宠物。
