RiotBus 是一个欧美女歌手 PK 网站 MVP：用户选择两位艺人、选择对比维度和输出模式后，页面会展示结构化数据表，并由 AI 生成可追问、可导出的 PK 报告。

项目当前重点不是做一个传统音乐资料站，而是把“查数据、看对比、生成有传播感的报告”这条链路跑通。

正式访问地址：https://riotbus.soeuriours.com

• 首页动态斜线背景，支持 刻薄女孩 / 清清白白 双主题切换。
• 首页 3 条运营 Banner，支持自动轮播、手动切换和详情弹窗。
• Banner 图片统一读取 public/assets/banners/*.png。
• 首批 20 位女歌手，支持模式化头像与模式化显示名。
• 筛选弹窗支持 2 人 PK、维度勾选、default AI / custom API 切换。
• 对比页支持销量、Spotify followers、Grammy、AOTY 乐评四类数据。
• AI 面板支持首轮报告、追问回复和分享图/PDF 文案生成。
• RAG 内容库支持艺人画像、黑称黑话、粉丝称呼、争议、荣誉、标题素材。
• AOTY 专辑级 Agent 支持手动更新专辑乐评缓存，并在用户追问具体专辑时注入 AI 上下文。
• 可选 DashScope/Qwen text-embedding-v4 embedding 流程，可导入 Chroma。

• Next.js App Router
• React
• TypeScript
• Tailwind CSS
• Framer Motion
• lucide-react
• 本地 JSON/TS seed 数据
• OpenAI-compatible chat API
• 可选 DashScope/Qwen embedding

安装依赖：

npm install

准备环境变量：

cp .env.example .env.local

至少填写：

DEFAULT_AI_BASE_URL=https://api.deepseek.com
DEFAULT_AI_MODEL=deepseek-chat
DEEPSEEK_API_KEY=your-key

启动开发环境：

npm run dev

打开：

http://localhost:3000

这个项目不是纯静态站，推荐用 OpenNext + Cloudflare Workers 部署。

安装依赖后先本地验证：

npm run typecheck
npm run build

本地预览 Cloudflare 产物：

npm run preview:cloudflare

发布到 Cloudflare：

npm run deploy:cloudflare

如果需要补 Cloudflare 环境类型：

npm run cf-typegen

Cloudflare 上运行时只依赖线上 API 和已经构建好的静态资产；public/assets/artists/source/、data/rag/index/rag-embeddings.json、data/rag/index/chroma-export.json 这类本地素材不应作为部署前提。

npm run dev
npm run typecheck
npm run build
npm run agent:aoty:update
npm run agent:aoty:query -- --artist taylor-swift
npm run rag:chunks
npm run rag:embed
npm run rag:search -- "Taylor Swift vs Lady Gaga"
npm run rag:chroma

• 艺人基础数据：data/artists.ts
• 首页 Banner 数据：data/banners.ts
• AI prompt：lib/prompts.ts
• RAG 知识库：data/rag/knowledge/artist-knowledge.json
• 结构化指标：data/rag/structured/artist-metrics.json
• AOTY 专辑级缓存：data/rag/structured/aoty-albums.json
• Banner 图片：public/assets/banners
• 生成头像：public/assets/artists/mean 和 public/assets/artists/neutral

Banner 图片命名：

gaga-cancel.png
olivia-dropdead.png
ariana-petal.png

艺人头像命名：

public/assets/artists/mean/{artist-id}-mean.jpg
public/assets/artists/neutral/{artist-id}-neutral.jpg

RAG 不用于硬数据匹配。销量、followers、Grammy、AOTY 这类硬数据继续走结构化读取；黑称、粉丝语料、争议、荣誉、标题素材才进入语义检索。

生成 chunks：

npm run rag:chunks

生成 embedding：

npm run rag:embed

本地检索：

npm run rag:search -- "尖姐和交姐谁赢" -- --mode mean --artist lady-gaga

推送 Chroma：

npm run rag:chroma

手动更新 AOTY 专辑级缓存：

npm run agent:aoty:update

这个 Agent 会按 data/rag/sources/artist-sources.json 的 AOTY 艺人主页执行 plan -> tool -> execute -> validate -> write 流程，并写入 data/rag/structured/aoty-albums.json。如果 AOTY 返回 Cloudflare challenge，脚本会记录失败原因并保留旧缓存，不会清空已有数据。

只更新单个艺人：

npm run agent:aoty:update -- --artist taylor-swift

查询缓存里的艺人专辑结果：

npm run agent:aoty:query -- --artist taylor-swift

使用本地 HTML 作为 fallback：

npm run agent:aoty:update -- --source-dir data/agent-cache/aoty-html

如果浏览器能打开 AOTY，但脚本直连被 Cloudflare 拦截，也可以把浏览器里复制出的可见文本保存为：

data/agent-cache/aoty-browser-text/taylor-swift.txt

然后运行：

npm run agent:aoty:update -- --artist taylor-swift --browser-text-dir data/agent-cache/aoty-browser-text

public/assets/artists/source 是本地参考图目录，不建议上传公开仓库。公开仓库只需要提交生成后的 mean / neutral 头像和 Banner 图。

Cloudflare 部署只需要：

• public/assets/banners
• public/assets/artists/mean
• public/assets/artists/neutral
• 代码、JSON seed、文档

• PRD：docs/prd/artist-battle/PRD-v0.md
• 页面规格：docs/prd/artist-battle/MVP-page-spec.md
• 技术方案：docs/prd/artist-battle/TECH-v0.md
• 视觉规范：docs/prd/artist-battle/frontend-style-v0.md
• 头像规范：docs/assets/artist-avatar-guidelines.md