Cat AdOps Tycoon

用一只猫，讲清楚广告请求、实时竞价、收入、体验、留存与 LTV。

🐾 立即在线体验  ·  产品需求  ·  系统架构

_{竖屏网页小游戏 · 原创角色美术 · Cloudflare Workers + D1 在线运行}

Cat AdOps Tycoon 是一款可完整游玩的广告商业化经营小游戏。玩家选择猫咪运营官和广告策略，连续经营 7 天，观察广告主实时竞价，在收入、猫咪体验与留存之间做选择，最终获得经营评级、动态成就和 AI 运营日报。

产品亮点

• 4 位具有独立商业化属性的猫咪运营官与原创 3D 角色立绘；
• 5 种可解释的广告策略：佛系、激励、插屏、高价和 AI 托管；
• Ad Request → 底价过滤 → DSP 出价 → 成交 → 展示/点击/转化完整链路；
• Revenue、Fill Rate、CTR、eCPM、Mood、Fatigue、D1 Retention、7D LTV 等核心指标；
• 7 日连续经营、D1/SQLite 持久化、S/A/B/C 结算评级和 8 个动态成就；
• 7 日 A/B 策略实验、累计收入曲线与综合胜者结论；
• OpenAI 兼容 Chat Completions 日报，异常时自动降级为离线分析；
• 手机优先响应式设计、横向角色卡牌、PWA Manifest 与安全区适配；
• 同时支持本地 Docker 与 Cloudflare Workers + Static Assets + D1 部署。

在线架构

flowchart LR
    Browser[手机 / 桌面浏览器] --> Assets[Workers Static Assets]
    Browser --> API[Cloudflare Worker API]
    API --> Engine[竞价与经营引擎]
    API --> D1[(Cloudflare D1)]
    API --> Report{日报生成}
    Report -->|配置 Secret| LLM[OpenAI 兼容 API]
    Report -->|无 Key / 调用异常| Offline[离线分析器]

Loading

公开体验环境默认使用离线日报，不会向第三方发送玩家数据；经营历史保存在 Cloudflare D1。项目本地版本保留 FastAPI + SQLite，便于学习、测试和二次开发。

本地运行

需要 Node.js 20.9+、pnpm、Python 3.12+ 与 uv。

cd api
uv sync --extra dev

cd ../web
pnpm install

cd ..
./scripts/dev.sh

• Web：http://127.0.0.1:3000
• API 文档：http://127.0.0.1:8000/docs

也可使用 Docker：

docker compose up --build

Cloudflare 部署

Cloudflare 版本将 Next.js 导出为静态资源，由同一个 Worker 提供 /api/*，经营记录写入 D1。

首次部署：

cd web
pnpm install

# 创建数据库后，将返回的 database_id 写入 ../wrangler.jsonc
pnpm exec wrangler d1 create catops-db
pnpm cf:migrate:remote
pnpm cf:deploy

后续部署只需：

cd web && pnpm cf:deploy

如需在线 LLM，请使用 Worker Secret，禁止把 Key 写入配置文件：

cd web
pnpm exec wrangler secret put OPENAI_API_KEY --config ../wrangler.jsonc

然后在 wrangler.jsonc 的公开变量中配置兼容服务的 OPENAI_BASE_URL 与 OPENAI_MODEL。

OpenAI 兼容协议

本地启用真实 LLM：

cp .env.example .env

OPENAI_API_KEY=your-key-here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4.1-mini

实现兼容 POST /chat/completions 的服务均可接入。.env、.env.local、数据库和运行缓存均已加入 .gitignore。

运行时策略：

1. 已配置 Key：请求兼容接口并验证结构化 JSON；
2. 未配置 Key：直接使用内置离线分析器；
3. 超时、状态码或结构异常：自动降级且不中断经营；
4. UI 与经营档案明确标记 LLM 或 离线 来源。

项目结构

CatOps/
├── api/                  # FastAPI / SQLModel / SQLite 本地后端
├── worker/               # Cloudflare Worker API 与 D1 migrations
├── web/                  # Next.js 竖屏网页小游戏
│   ├── public/assets/    # 原创游戏角色和广告主素材
│   └── src/
├── docs/                 # 架构、演示指南与体验截图
├── wrangler.jsonc        # Cloudflare Workers / Assets / D1 配置
├── docker-compose.yml
├── LICENSE
└── PRD/prd_V0.md

API

Method	Path	说明
GET	/api/health	服务、版本、持久化与 LLM 状态
GET	/api/catalog	猫咪、策略和广告主目录
POST	/api/simulate	运行单日模拟、生成日报并持久化
POST	/api/experiment	运行 3–14 日策略对照实验
GET	/api/llm/status	返回 LLM/离线模式，不暴露密钥
GET	/api/players/{id}/progress	经营历史、成就与七日结算
DELETE	/api/players/{id}/progress	重置指定猫咪的经营档案

质量检查

cd api
uv run pytest -q
uv run ruff check .

cd ../web
pnpm lint
pnpm build
pnpm typecheck:worker
pnpm build:cloudflare

项目已验证 FastAPI 测试、Ruff、ESLint、TypeScript、Next.js 生产构建、Wrangler 本地运行、D1 读写、Cloudflare 线上冒烟和极窄手机视口。

设计边界

• 竞价是可解释的业务抽象模型，不连接真实广告平台或完整 OpenRTB；
• A/B 结果是模拟推演，不代表真实线上因果结论；
• 当前使用匿名浏览器 player_id，没有账号和多租户权限；
• 公开环境不配置 LLM Key 时会稳定使用离线日报。

License

MIT License © 2026 CatOps contributors.