Codex Pets

Codex Pets

Codex 兼容动画宠物的社区画廊，支持本地账户、人工审核、公开生成请求、由 YDB 支持的素材存储，以及已批准和待审核宠物的公开详情页面。

公共网站：https://pets.ydb-qdrant.tech/.

此浏览器中的我的生成记录

/my-generations 会列出在此处接受的任务，以及已在同一浏览器中明确打开的可用私人结果，无需登录。每条记录仅在浏览器存储中保存其私有能力 ID 以及保存和过期时间戳。描述和图像不会存储在此历史记录中。请妥善保管浏览器数据和私人链接；任何能够访问它们的人都可以打开相应结果。

状态使用现有的逐次生成 GET 端点查询，同时最多读取三项。进行中的任务会刷新；就绪或失败的任务会停止轮询。此视图不会创建、重试、取消或发布任务。结果仍会在接受后 24 小时过期。历史记录会保留最新的 50 条，直至过期后七天；过期记录无法打开。清除浏览器数据会移除此列表，但不会重置配额或取消任务。无法找回之前未知的链接；打开现有的可用私人链接会将其添加到此浏览器的列表中。

历史记录、表单和结果页面均不包含分析功能，也不会被搜索引擎编入索引。历史记录使用 private/no-store 和 no-referrer 标头。系统不会基于 IP 查询所有权，不提供账户同步、服务器端历史记录枚举，也不会新增数据库架构。

通过远程 MCP 生成宠物

generate_pet 接受文本 prompt（1–2000 个字符）、可选的 displayName（最多 80 个字符）以及全新的随机 UUID requestId。如果响应断开，请在内容相同的情况下重复使用该 requestId：不会产生重复任务或额外配额。同一 ID 搭配不同内容会被拒绝。请妥善保管请求 ID 和生成 ID。

每隔 5 秒轮询一次 get_pet_generation(generationId)。已完成的任务会返回未列出的预览和下载文件：pet.json、无损的 spritesheet.webp 以及 pet.zip。格式 v2 的尺寸为 1536×2288，包含 9 种动画状态和 16 个视线方向。结果会在接受后 24 小时过期；幂等性哈希会保留 7 天。新完成的任务包含可编辑的名称、描述和标签。私人预览会将描述更改原子性地保存到 pet.json 和 ZIP 中；标签会保存供画廊投稿使用。保存不产生费用，不会调用提供商，不会更改精灵图字节内容，且需要使用当前元数据版本；提交后将无法编辑。现有已完成任务可以手动编辑，无需进行新的模型调用。元数据响应不可用或未知时，仍会保留可用的图像包和手动填写字段；系统不会自动重试，并会保留未知费用的记账标记。此工具不会将内容发布到画廊。过期前，可在私人结果页面点击 提交审核，保存永久画廊包并创建一条待审核投稿，或通过 /submit 上传 ZIP。提交重试会返回相同回执，即使响应已丢失也是如此。任何持有私人链接的人都可以提交该结果一次；如果已登录，首次提交者将拥有该投稿。联系方式会保持私密。提交已保存的包不会调用生成提供商，也不会更改生成配额。之后获批时，可通过现有的管理工作流准备元数据和搜索嵌入。 运营方通过 sprite-gen 2.44.0 为每个任务支付 12 个 GPT Image 2.5 Sunburst/high 阶段的费用：一个基础图像和 11 个行。基础图像完成后，最多 11 个行会并发运行。每个失败的图像阶段可在 5 秒后重试一次，适用于 RemoteDisconnected、IncompleteRead、HTTP 500 或 HTTP 520，因此最多会进行 24 次图像尝试。成功的阶段不会重复。之后，新任务最多会发起一次 gpt-6.1-sol 文本/视觉请求，用于拟定英文名称、描述和标签；元数据不会自动重试。

启用 PET_GENERATION_REVIEW_FLOW_ENABLED=true 后，网站允许提交角色图像、文本或两者，并在生成基础角色后暂停，等待用户明确确认。该标志默认为 false。无论该标志如何设置，JSON 和 MCP 接收的任务仍会自动处理；已有任务会保留其保存的策略。确认前，编辑角色会使用已保存的基础图像创建一个由文本引导的新版本，只消耗一次常规尝试，并保留之前的版本。参考图像会保持私密，并在任务到期时一并过期。有关限制和发布要求，请参阅网站审核和图像参考。

/generate 网站表单和远程 MCP 共用一个队列。限制为：全局每天接受 200 个任务，默认每个 IP 10 个任务，最多 1 个活动任务和 5 个等待任务；按莫斯科日历日统计。等待任务会在 30 分钟后过期，失败的任务也会占用配额。已完整记录的终端提供商故障仅影响失败的任务；写入未确认、租约丢失和未分类结果会暂停后续付费工作，以便运营方审核。每天 50 美元的阈值会检查已记录的用量，但不会预留金额。进行中的调用和未知费用可能导致超出该金额；未知费用标记会在任务过期和午夜后继续保留。提示词表单和私密预览不会包含分析数据/Webvisor。有关运维约定，请参阅行恢复和费用核算。

生成默认禁用，可通过网站表单和远程 MCP 使用。npm CLI 和浏览器 WebMCP 仍仅提供目录工具。有关明确的架构、候选项和手动启用步骤，请参阅 DEPLOYMENT.md。

技术栈

• Next.js 16 App Router、React 19、严格模式 TypeScript
• Gravity UI + SCSS/BEM
• 通过 ydb-sdk 使用 local-ydb / YDB 原生 gRPC
• 应用自有的电子邮件+密码身份验证，用户和会话由 YDB 提供支持
• 宠物资源以二进制 blob 的形式存储在 YDB 中
• 动态生成 robots.txt、sitemap.xml、llms.txt、llms-full.txt 和 OpenAPI JSON
• 面向 Agent 的 HTTP 访问：通过 llms.txt / llm.txt、/llms-full.txt、 /mcp、JSON 路由，以及核心注册表数据的 TOON 镜像提供
• 在受支持的浏览器运行时中提供可选的只读浏览器 WebMCP 工具
• 使用与 ydb-qdrant-ui 相同的计数器（104844437）的 Yandex Metrika， 并可选提供服务端聚合 MCP 指标
• 使用 JSZip + Sharp 进行软件包验证

开发

nvm use 24
npm install
cp .env.example .env.local
npm run dev

打开 http://localhost:3000。

提交更改前，请运行本地检查：

npm run lint
npx tsc --noEmit --incremental false
npm test
CODEX_PETS_DATA_SOURCE=mock NEXT_TELEMETRY_DISABLED=1 npm run build

Agent 访问

Codex Pets 提供公共 MCP 服务，供编码 Agent 搜索、检查、安装和分享已批准的宠物包。

主要公共入口：

• 最佳指南：https://pets.ydb-qdrant.tech/guides/best-codex-pets-for-ai-coding-agents
• LLM 发现入口：https://pets.ydb-qdrant.tech/llms.txt
• MCP 端点：https://pets.ydb-qdrant.tech/mcp
• 公共清单：https://pets.ydb-qdrant.tech/api/manifest
• CLI 安装：npx @astandrik/codex-pets install <slug>

连接 Codex：

codex mcp add codexPets --url https://pets.ydb-qdrant.tech/mcp

运行本地 stdio MCP 服务，以代理公共图库：

npx @astandrik/codex-pets mcp

可用的 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 备用路由也可公开访问：

• /openapi.json
• /api/openapi.json
• /llms-full.txt
• /guides/best-codex-pets-for-ai-coding-agents
• /guides/best-codex-pets-for-ai-coding-agents.md
• /api/manifest
• /api/manifest.toon
• /api/pets
• /api/pets.toon
• /api/pets/<slug>
• /api/pets/<slug>.toon
• /pets/<slug>/markdown
• /api/tags
• /api/tags.toon
• /api/pets/<slug>/share
• /badge/<slug>.svg
• /card/<slug>.gif
• /embed/<slug>

可爬取的 HTML 图库位于 /；分页使用 /?page=2、/?page=3，以此类推。旧版 /pets 目录 URL 会永久重定向到对应的首页 URL，而宠物详情仍位于 /pets/<slug>。

/api/pets 和 /api/pets.toon 接受可选的 page 和 pageSize 参数，并始终返回 pagination 元数据。不提供这两个参数时，响应为第 1 页，最多包含 200 只宠物。只提供 page 而不提供 pageSize 时，页面大小仍为 24。顶层的 total 是返回的宠物数量；pagination.totalItems 是筛选后的完整数量，而 pagination.hasNextPage 表示是否还有更多结果。发起下一次请求时，将 pagination.page 加 1，并显式传入返回的 pagination.pageSize。

如果你部署在 /codex-pets 这样的子路径下，请设置：

NEXT_PUBLIC_BASE_PATH=/codex-pets
NEXT_PUBLIC_APP_URL=https://example.com/codex-pets

公开图库无需密钥即可渲染。若要实现账户登录、提交、审核和指标功能，则需要 YDB_PETS_ENDPOINT、YDB_PETS_DATABASE 和身份验证环境变量。可选的服务端 MCP 指标也需要 YANDEX_METRIKA_MP_TOKEN 和 YANDEX_METRIKA_MP_CLIENT_ID。 可选的 IndexNow 通知由 INDEXNOW_KEY 启用；应用会提供 /<key>.txt，并在管理员批准宠物后向 IndexNow 发送通知。

可选的语义搜索使用 Yandex AI Studio 文本嵌入，并在 YDB 中进行精确余弦排序。查询模式默认为 PET_SEARCH_MODE=lexical；shadow 会计算语义排序，但不改变公开结果顺序；hybrid 会结合词法排序和文本语义排序。独立的 PET_SEARCH_VISUAL_MODE=off|shadow|hybrid 会根据 4 个固定精灵图帧，额外添加离线视觉描述排序。描述及其来源信息仅供内部使用；公开 JSON、TOON、首页、MCP 和 WebMCP 的结构均不会改变。配置 YANDEX_AI_STUDIO_FOLDER_ID、YANDEX_AI_STUDIO_API_KEY_FILE 和 PET_SEARCH_MODEL_REVISION=yandex-text-embeddings-v2-768-2026-07。v2 运行时使用由托管服务提供的 text-embeddings-v2-doc/query 模型，维度为 768。设置 PET_SEARCH_VISUAL_MODEL_REVISION=yandex-text-embeddings-v2-768-pet-vision-qwen3.6-v1，即可启用兼容的 Qwen 视觉排序。旧版 256 维版本仍已注册，可用于回滚。API 密钥只能通过密钥文件设置提供。提供商故障和超时会回退到词法搜索结果；仅视觉功能发生故障时，会保留文本混合排序结果。

若要使用生成的示例数据在没有 YDB 的情况下运行：

CODEX_PETS_DATA_SOURCE=mock AUTH_MODE=single-user \
  [email protected] \
  NEXT_PUBLIC_APP_URL=http://localhost:3000 \
  npm run dev -- --port 3000

生产环境说明

对于 https://pets.example.com 这样的专用公共子域名，建议：

NEXT_PUBLIC_APP_URL=https://pets.example.com
NEXT_PUBLIC_BASE_PATH=

如果应用容器通过 Docker 主机名访问 YDB，例如 grpc://ydb-local:2136，请在与 YDB 容器相同的 Docker 网络上运行应用：

docker run --network ydb-net ...

Telegram 等预览爬虫通过轻量级预览路由处理：

• /api/preview/site
• /api/preview/pets/[slug]

反向代理应在将预览机器人请求代理到常规 App Router 页面之前，将针对 / 和 /pets/<slug> 的请求重写到这些端点。请参阅：

• deploy/nginx-pets-subdomain.conf.example
• deploy/nginx-pets-edge-proxy.conf.example

本地 YDB 快速入门

进行本地应用开发时，普通的本地 YDB 根数据库 /local 就够用了；无需 CMS 租户或动态节点。应用在主机上运行，因此 local-ydb 容器必须在 127.0.0.1:2136 上发布 gRPC 端口。

如果使用 local-ydb MCP，请先通过 local_ydb_destroy_stack(confirm=true) 和 local_ydb_bootstrap_root_database(confirm=true) 清理并初始化根数据库。如果生成的容器未在 127.0.0.1:2136 上发布端口，请在同一卷上仅重新创建容器，并设置主机 gRPC 端口：

docker rm -f ydb-local
docker run -d --name ydb-local --no-healthcheck --network ydb-net \
  --restart unless-stopped \
  -p 127.0.0.1:2136:2136 \
  -p 127.0.0.1:8765:8765 \
  -v ydb-local-data:/ydb_data \
  -e GRPC_PORT=2136 \
  -e MON_PORT=8765 \
  -e GRPC_TLS_PORT= \
  -e YDB_GRPC_ENABLE_TLS=0 \
  -e YDB_ANONYMOUS_CREDENTIALS=1 \
  -e YDB_LOCAL_SURVIVE_RESTART=1 \
  ghcr.io/ydb-platform/local-ydb:26.1.1.6

使用以下本地应用环境变量：

AUTH_MODE=single-user
AUTH_SINGLE_USER_ID=local-admin
[email protected]
AUTH_SINGLE_USER_NAME="Local Admin"
SESSION_COOKIE_SECRET=dev-cookie-secret
PASSWORD_PEPPER=dev-password-pepper
[email protected]

YDB_ANONYMOUS_CREDENTIALS=1
YDB_ENDPOINT=grpc://127.0.0.1:2136
YDB_PETS_ENDPOINT=grpc://127.0.0.1:2136
YDB_PETS_DATABASE=/local
NEXT_PUBLIC_APP_URL=http://localhost:3000

本地通过主机访问 Docker 时需要设置 YDB_ENDPOINT，因为 ydb-sdk 否则会使用可能包含 Docker 容器主机名的发现端点。

应用架构、填充种子数据并启动应用：

docker cp ydb/schema.yql ydb-local:/tmp/codex-pets-schema.yql
docker exec ydb-local /ydb -e grpc://localhost:2136 -d /local scripting yql -f /tmp/codex-pets-schema.yql
npm run db:migrate
npm run seed:dev:reset
npm run dev -- --port 3000

打开 http://localhost:3000。本地 YDB 监控界面的地址为 http://127.0.0.1:8765。

对于远程部署或基于租户的部署，请将应用指向可访问的租户端点，例如：

YDB_PETS_ENDPOINT=grpc://ydb-host:2137
YDB_PETS_DATABASE=/local/your-tenant
YDB_STATIC_CREDENTIALS_USER=appuser
YDB_STATIC_CREDENTIALS_PASSWORD_FILE=/run/secrets/app.password
YDB_STATIC_CREDENTIALS_AUTH_ENDPOINT=grpc://ydb-host:2136

无需完整账户流程的本地开发方式：

AUTH_MODE=single-user
AUTH_SINGLE_USER_ID=local-admin
SESSION_COOKIE_SECRET=dev-cookie-secret
PASSWORD_PEPPER=dev-password-pepper
[email protected]

常规内置账户流程：

AUTH_MODE=app-session
SESSION_COOKIE_SECRET=change-me
PASSWORD_PEPPER=change-me-too
[email protected]

在现有的本地 YDB 租户上手动创建表：

ydb -e "$YDB_PETS_ENDPOINT" -d "$YDB_PETS_DATABASE" scripting yql -f ydb/schema.yql

将迁移应用到现有数据库：

npm run db:migrate

迁移完成后，预览并应用已批准宠物的文本和视觉回填：

npm run search:backfill -- --dry-run
npm run search:backfill -- --apply
npm run search:backfill -- --apply --slug orbit-otter --force
npm run search:backfill-vision -- --dry-run
npm run search:backfill-vision -- --apply --slug orbit-otter
npm run search:backfill-vision -- --apply
npm run search:eval:calibrate
npm run search:eval:holdout

两种回填都必须显式指定 --dry-run 或 --apply；视觉回填的 --force 仅可与 --apply 一起使用。它们绝不会输出文档文本、说明文字、图像、嵌入向量、提示词或机密信息。试运行仍会读取并计算图像拼接表的哈希值，但绝不会调用任何 AI 服务提供商，也不会写入 YDB。安全的上线流程为：基础配置 lexical、视觉模式 off → 增量迁移 → 回填 → 视觉模式 shadow → 校准 → 未触碰的保留测试集 → 人工审核综合排序的前五个 sexy 结果 → 两种模式均设为 hybrid。

如果已应用的文本或视觉回填更改了向量，输出中会显示所需的相关宠物快照后续操作。嵌入维护完成后，请运行完整的 V24 派生数据流程，以免快照排序过时：

npm run related:backfill-description-query -- --dry-run
npm run related:backfill-description-query -- --apply
npm run related:backfill-description-document -- --dry-run
npm run related:backfill-description-document -- --apply
npm run related:backfill-annotations -- --dry-run
npm run related:backfill-annotations -- --apply
npm run related:backfill-annotation-query -- --dry-run
npm run related:backfill-annotation-query -- --apply
npm run related:backfill-annotation-document -- --dry-run
npm run related:backfill-annotation-document -- --apply
npm run related:rebuild -- --dry-run
npm run related:rebuild -- --apply
npm run related:verify:v24

相关宠物的描述相似度使用基于同一段规范化 name + kind + description 文本构建的查询和文档独立版本。标签不会纳入任一嵌入输入。查询版本使用同一 768 维模型的查询角色，文档版本则使用文档角色。按顺序运行模型回填，使其共享 AI Studio 速率预算。V24 将描述相似度与受控的实体、系列、合集和原型标注相结合。视觉相似度会影响合格层级内的排序，也会在主题数量和类别之后，为共享主题的稀疏回退候选排序。视觉证据本身不能使匹配合格或挽救匹配。关系策略新增已验证的父级家族和已知编号系列的根项，但不会替代实体／系列标识符或已存储的标注。它会保留显式的家族字段覆盖项。注册表变更需要新的关系策略版本和代次，而不是新的标注嵌入。当前排名版本为每只已批准宠物存储 8 个按顺序排列的 slug。宠物详情页会立即显示全部 8 个（桌面端 4 列、平板端 3 列、移动端 2 列）；私有 Markdown 副本则有意只保留前 4 个。其已持久化版本不可变，因此可以将活动代次与当前实现的精确版本进行核对。

文本和视觉回填会分别根据各自的活动版本解析嵌入提供方。如果文本和视觉版本使用不兼容的嵌入模型，视觉排名会安全地停用。

管理员批准可以排入一项原子化准备操作，刷新常规搜索文档、描述查询／文档向量、受控标注及其两种标注向量角色，以及视觉输入。只有在所有输入均为最新后，它才会在同一事务中发布宠物、审核记录和已准备的代次。失败时，宠物会保持待审核状态，之前的代次仍保持活动状态。当 PET_RELATED_PREAPPROVAL_ENABLED 不完全等于 true 时，批准会安全失败，而不会发布缺少最新 V24 输入的宠物。 原子化代次激活也会轮换相关候选项和站点地图的缓存键，因此独立工作进程不依赖 Next 请求上下文。 npm run related:verify:v24 为只读操作：它会根据已存储的输入重新计算 V24，并在不调用 AI Studio 的情况下检查覆盖范围、完整性、活动版本以及精确的有序快照一致性。

首次回滚方式是设置 PET_SEARCH_VISUAL_MODE=off；使用 PET_SEARCH_MODE=lexical 也可停用文本语义轮廓。新增的字幕和嵌入表可以保留。 已检入的评估查询位于 src/lib/pets/search/search-eval-fixtures.json，包含冻结的 calibration 和 holdout 拆分。Calibration 会针对权重 0.25、0.50、0.75 和 1.00 评估所有已观察到的视觉分数；holdout 命令要求使用已提交且绑定版本的配置文件，不得用于调优。实时评估需要配置 YDB 和 AI Studio 访问权限，并会输出汇总结果以及最终 sexy 审核列表中的公开 slug。

创建架构后，填充本地开发数据：

npm run seed:dev

使用 npm run seed:dev:reset 仅替换固定的 dev_* 种子记录。

当前行为

• 公众用户可以浏览图库并打开 /pets/[slug]。
• 公众用户无需登录即可提交宠物，需提供文件和可选的联系邮箱。
• 公众用户无需登录即可请求生成宠物，需提供联系邮箱、文本简介和可选的参考图片。
• 已登录用户只能在 /my-pets 下查看自己的宠物。
• 已登录用户可以在 /my-requests 下查看自己的宠物生成请求。
• 管理员由 INITIAL_ADMIN_EMAILS 确定。
• 管理员可以在 /admin/submissions 批准、拒绝和删除待处理的宠物。
• 管理员可以在 /admin/requests 审核生成请求，并将其关联到现有宠物。
• 所有者可以在 /my-pets 删除自己的宠物。
• 管理员可以在宠物详情页删除任何宠物。
• 已删除的宠物会从所有者列表、公开列表和 sitemap.xml 中消失。

SEO、Agent 和分析

• robots.txt 由 src/app/robots.ts 提供。
• 规范的 /api/manifest 和 /api/manifest.toon URL 允许搜索引擎和 AI 爬虫访问，并返回 X-Robots-Tag: index, follow。两种格式均包含完整的已审核目录。这些精确路径例外不会开放查询参数变体、名称相似的路径或其他受限 API 路由。
• sitemap.xml 为动态生成，并包含当前所有已审核的宠物。
• llms.txt 为动态生成，提供精选的、便于 AI 读取的图库、清单和已审核宠物页面索引。对于请求单数文件名的抓取器，/llm.txt 是直接的纯文本别名。
• llms-full.txt 为动态生成，提供扩展版、便于 AI 读取的文档，其中包含 API 参考链接、身份验证说明、示例和 Webhook 状态。
• /openapi.json 是面向公开 Agent/开发者契约子集的规范 OpenAPI 3.1 规范。它有意省略公开指标变更和下载重定向路由。对于探测可预测 API 路径的扫描器，/api/openapi.json 是其别名。
• /developers 和 /docs/api 是可编入索引的开发者资源页面，便于发现 API、OpenAPI、MCP、身份验证和 Webhook 信息。
• /mcp 是公开的 Streamable HTTP MCP 服务，提供只读目录工具，并支持面向编码 Agent 的配额限制生成。 Codex 可通过以下命令连接： codex mcp add codexPets --url https://pets.ydb-qdrant.tech/mcp。
• 官方 MCP Registry 名称： tech.ydb-qdrant.pets/codex-pets-ydb-qdrant。
• server.json 和 /.well-known/mcp/server.json 提供公开远程服务的 MCP Registry 元数据。
• /.well-known/mcp-registry-auth 提供 mcp-publisher 使用的公开 HTTP 域名身份验证记录。
• HTTP Agent 访问是主要的公开机器契约：
  • /mcp — Streamable HTTP MCP 端点，包含目录工具： search_pets、get_pet、get_install_instructions、get_badge_code、 get_embed_code、get_card_code 和 get_pet_request_info
  • /openapi.json 和 /api/openapi.json — OpenAPI 3.1 公开 Agent/开发者契约子集
  • /llms-full.txt — 扩展版、便于大模型读取的 API、身份验证、MCP、软件包和 Webhook 文档
  • /developers 和 /docs/api — 开发者门户和 API 文档页面
  • /server.json 和 /.well-known/mcp/server.json — MCP Registry 元数据， 指向公开的 Streamable HTTP 远程服务
  • /.well-known/mcp-registry-auth — 公开的 MCP Registry HTTP 身份验证记录
  • /api/manifest — 已审核宠物列表，包含页面 URL、安装命令和 资源 URL
  • /api/manifest.toon — 公开清单的 TOON 镜像，便于大模型检索
  • /api/pets?q=<query>&kind=all|creature|object|character — 已审核宠物 列表/搜索 JSON，不含私人联系邮箱
  • /api/pets.toon?q=<query>&kind=all|creature|object|character — 已审核宠物 列表/搜索的 TOON 镜像，不含私人联系邮箱
  • /api/pets/<slug> — 单个已审核宠物的公开详情 JSON，不含私人联系邮箱
  • /api/pets/<slug>.toon — 公开详情数据的 TOON 镜像，不含私人联系 邮箱
  • /api/tags — 已审核宠物的当前标签计数
  • /api/tags.toon — 当前标签计数的 TOON 镜像
  • /api/pets/<slug>/share — 已清理的安装、徽章和嵌入代码片段
  • /api/pets/<slug>/install — 只读安装说明，不会变更指标
  • /badge/<slug>.svg — README 徽章 SVG
  • /card/<slug>.gif — 动画 GIF 分享界面。支持 mode=sprite|card、state 和 scale；默认可分享的输出仅包含精灵图。
  • /embed/<slug> — iframe 嵌入页面。支持 mode=sprite|card、state、scale、theme、compact 和可见性切换项。
  • npx @astandrik/codex-pets install <slug> — CLI 安装命令格式
• 浏览器 WebMCP 是一种只读的渐进增强功能。它仅适用于提供 navigator.modelContext 的浏览器运行时；普通 HTTP 爬虫和 ChatGPT 浏览会话应使用上述端点。 支持的浏览器 WebMCP 工具：
  • search_codex_pets — 通过 /api/pets 搜索已审核的宠物
  • get_codex_pet — 通过 /api/pets/[slug] 获取一个已审核的宠物
  • get_codex_pets_manifest — 获取 /api/manifest
  • get_current_codex_pet — 查看当前标签页中打开的已审核宠物
• WebMCP 有意不提供提交、点赞、下载/安装计数、身份验证、管理、审核或删除操作。
• 网站地图会在审核变更后自动更新；新审核通过的宠物会自动出现在其中，无需 cron 任务或手动重建。
• Yandex Metrika 仅在生产环境中加载，并跟踪：
  • 账户注册/登录成功和错误
  • 宠物提交成功和错误
  • 宠物生成请求成功和错误
  • 审核通过/拒绝/删除
  • 相关宠物在可见度达到 50% 时的展示次数，以及详情页导航点击次数，包括来源 slug、目标 slug 和从 1 开始的位置
  • 相关安装命令的复制和下载，包括直接在卡片上的操作，以及 30 分钟浏览器会话中匹配的详情页操作
• 服务端 MCP 汇总指标为可选项。仅当配置了 YANDEX_METRIKA_MP_TOKEN 和 YANDEX_METRIKA_MP_CLIENT_ID 时才会启用。 MCP 指标使用专用的技术 Metrika ClientID，并在 mcp_tool_call 目标事件之前发送一个合成的 /mcp 页面浏览事件。负载仅包含工具名称、状态、安全 slug、种类、结果数量和限制等汇总工具维度；不包含原始 MCP 搜索文本、IP 地址、user-agent、origin 标头、联系邮箱、所有者邮箱或所有者标识符。
• IndexNow 为可选项。在运行时环境中设置 INDEXNOW_KEY，即可启用公开密钥文件，以及审核通过时向图库、新宠物详情页、sitemap.xml、llms.txt 和 /api/manifest 发送通知。

主要路由

• / — 公共展示库
• /request — 公共宠物生成请求流程
• /submit — 公共提交流程
• /login、/register、/logout — 本地账户流程
• /my-pets — 所有者视图
• /my-requests — 已登录用户的生成请求视图
• /admin/submissions — 管理员审核队列
• /admin/requests — 管理员宠物生成请求队列
• /pets/[slug] — 宠物详情页
• /agents — Agent 和 MCP 连接指南
• /developers — Codex Pets 开发者门户
• /docs/api — Codex Pets API 文档
• /guides/best-codex-pets-for-ai-coding-agents — Codex 宠物选择分类指南
• /guides/codex-pets-vs-vscode-pets — 编辑器宠物使用场景对比指南
• /mcp — 公共 Streamable HTTP MCP 端点
• /openapi.json、/api/openapi.json — 公共 OpenAPI 规范
• /server.json、/.well-known/mcp/server.json — MCP Registry 元数据
• /api/manifest — 公共 Agent/CLI 清单
• /api/manifest.toon — 公共清单的 TOON 镜像
• /api/pets — 公共已批准宠物列表/搜索 JSON
• /api/pets.toon — 已批准宠物列表/搜索的 TOON 镜像
• /api/pets/[slug] — 公共已批准宠物详情 JSON
• /api/pets/[slug].toon — 公共宠物详情数据的 TOON 镜像
• /api/tags、/api/pets/[slug]/share、/api/pets/[slug]/install — 只读 Agent/分享 JSON
• /api/tags.toon — 已批准标签计数的 TOON 镜像
• /badge/[slug].svg、/card/[slug].gif、/embed/[slug] — 分享入口
• /robots.txt、/sitemap.xml、/llms.txt、/llm.txt、/llms-full.txt — SEO 和 AI 可读输出

面向 Agent 的检查

使用 CODEX_PETS_DATA_SOURCE=mock npm run dev -- --port 3000，无需本地 YDB 即可对面向 Agent 的路由进行冒烟测试。预期的公共端点：

curl -I http://localhost:3000/
curl -I http://localhost:3000/api/pets
curl -I http://localhost:3000/api/pets.toon
curl -I http://localhost:3000/api/manifest
curl -I http://localhost:3000/api/manifest.toon
curl -I http://localhost:3000/openapi.json
curl -I http://localhost:3000/api/openapi.json
curl -I http://localhost:3000/api/tags
curl -I http://localhost:3000/api/tags.toon
curl -I http://localhost:3000/llms.txt
curl -I http://localhost:3000/llm.txt
curl -I http://localhost:3000/llms-full.txt
curl -I http://localhost:3000/developers
curl -I http://localhost:3000/docs/api
curl -I http://localhost:3000/guides/best-codex-pets-for-ai-coding-agents
curl -I http://localhost:3000/guides/codex-pets-vs-vscode-pets
curl -i http://localhost:3000/mcp

进行 JSON 响应 MCP 冒烟测试：

curl -s http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

要测试 WebMCP 本身，请使用支持 WebMCP 的 Chrome 或实验室浏览器，并检查 navigator.modelContext 是否公开了上面列出的只读工具。在不支持 WebMCP 的普通浏览器中，客户端注册器不会执行任何操作；这是预期行为，不会影响 HTTP Agent 契约。

私有部署说明

具体的主机操作说明、本地路径和运维备注应放在被 git 忽略的 private/ 目录中。本仓库的公共文档应保持通用且可安全提交。

宠物包

每只宠物以以下形式分发：

• pet.json
• spritesheet.webp 或 spritesheet.png
• 可下载的 ZIP，根目录中包含这两个文件

注册表接受两种 Codex 图集版本，每种均使用 192x208 的单元格：

• v1：省略 spriteVersionNumber 或将其设为 1；使用 1536x1872 的 8x9 图集。
• v2：将 spriteVersionNumber 设为 2；使用 1536x2288 的 8x11 图集，其中第 9 和第 10 行包含 16 个顺时针朝向。

CLI 安装

可通过 npm 将展示库中已批准的宠物安装到 Codex：

npx @astandrik/codex-pets install zero-two-2

默认情况下，CLI 会从 https://pets.ydb-qdrant.tech 读取 /api/manifest，并写入 ${CODEX_HOME:-~/.codex}/pets/<slug>/。使用 --force 替换现有的本地宠物文件夹，或使用 CODEX_PETS_URL / --url 指定其他部署。如果 Codex 已在运行，请先重启，然后再前往“设置”->“外观”->“宠物”中选择新宠物。

可选动作指导

PET_GENERATION_ANIMATION_HINTS_ENABLED=true 可在基础确认前启用一个可选的动作字段。该功能默认关闭。一段描述中可以同时包含总体偏好和针对各动画状态的条件。首次确认通过后，文本即固定；重试时会返回已接受的设置。指导可优化九种状态下的动作、转身和手势；不支持尺寸变化和由光标驱动的头部动作。基础生成和视线生成保持不变，不会增加额外的提供方阶段或每日尝试次数。

启用指导前，请先部署兼容的 Web 版本和生成工作进程版本。关闭该标志会阻止新的指导，但已接受的任务和重放仍会继续。回滚时请保留兼容的读取器和写入器，以免丢弃已保存的指导。生成生命周期请参阅 docs/pet-generation-parallel-rows.md。