菜单
Use when working on Bubba, HEATER's AI assistant — /api/chat/* endpoints, provider streaming (src/ai/providers.py), token metering and spend caps, AI provider keys, attachments/page-context, saved prompts, or the chat composer in web/src/components/bubba/.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when starting any task on HEATER's live product — the api/ FastAPI backend (Railway service "celebrated-respect") or web/ Next.js frontend (heater-v1-0-1.vercel.app) — or when unsure where code lives, how a request flows, which database owns what, why CORS/Yahoo-writes/billing seem "missing", or which app (Streamlit vs React) is the real one. Load this first on App B work.
Use when working on HEATER App B auth or billing — Clerk JWT verification, unexpected 401/402, HEATER_API_WRITE_TOKEN, Stripe checkout/webhooks/subscription tiers, require_pro gating, tier-based AI spend caps — or when auth "works locally but not live" (or vice versa), or a page bounces to /sign-in on hard load.
Use when proving a HEATER algorithm works — calibrating constants, backtesting projections or recommendations, validating win probabilities, adding uncertainty intervals, checking calibration drift — or before letting any new math drive user-facing recommendations. Also when asked "is this signal real?" or when a calibration run finds no clear winner.
Use when editing api/contracts/*, when api/openapi.json or web/src/lib/api/generated.ts drift (test_openapi_contract or the CI openapi-ts-sync job failing), when JSON responses 500 or render "nan"/"+nan" badges, or when adding/renaming fields on a response the live frontend already consumes.
Use when App B misbehaves and the cause isn't obvious — works locally but not on Railway/Vercel (or vice versa), a live page renders empty/zero/wrong data, an endpoint 500s or times out, or tests see different data than the app. Run this playbook before changing code.
Use when deploying HEATER App B, changing Railway or Vercel env vars/service config, diagnosing live 502s/timeouts/blank data after deploy, operating the Yahoo-token or Statcast relays, or driving Railway/Vercel headlessly from a terminal.
| name | heater-appb-bubba-ai |
| description | Use when working on Bubba, HEATER's AI assistant — /api/chat/* endpoints, provider streaming (src/ai/providers.py), token metering and spend caps, AI provider keys, attachments/page-context, saved prompts, or the chat composer in web/src/components/bubba/. |
Bubba is read-only on the league — it recommends, never writes. Its explainer tools are additive and registry-first (src/ai/tools.py over CONSTANTS_REGISTRY); never give it a mutating tool without an explicit owner decision.
src/ai/providers.py is shared with the live Streamlit app. _chat_events() (providers.py:46-166) is the streaming generator; chat() (169-200) is a thin DRAIN over it that must return the byte-identical pre-streaming dict. Frozen-reference guard: tests/api/test_ai_providers_streaming.py:79 test_chat_is_a_drain_returning_todays_exact_dict — if your change makes it fail, the live Streamlit app just changed; redesign additively.
Failure story: litellm.stream_chunk_builder returns None on an empty stream — undiscovered, None.choices would have crashed the LIVE app's chat() hot path via the shared drain. Guarded at providers.py:95-103 (graceful done). When touching the stream loop, preserve that guard and the terminal-done contract.
ChatService.send (api/services/chat_service.py): key check → cap check → call → meter BEFORE persist (~line 162) so history failures can't skip billing. send_stream meters server-side before emitting the terminal done frame — a tail-disconnect still bills. Mid-stream partial-token metering was a documented under-count until P5 added it (litellm constraint: Py<3.14 for ≥1.83.8; CI runs 3.12).src/ai/budget.is_over_cap(user_id, on_own_key, cap_usd=None) (budget.py:72-76) — the cap_usd override is the tier hook; own-key users are exempt. api/gating.py::get_managed_ai_cap resolves tier→cap, returns None while billing dormant (= admin default) and NEVER raises (store failure → bounded, logged over-grant). Over-cap streaming error carries code:"over_cap" → frontend OverCapNudge (Bubba.tsx ~841). Chat identity offset: chat_user_id = 1_000_000_000 + AppUser.id.src/ai/keys.py — per-provider env HEATER_AI_ADMIN_KEY_<PROVIDER> (keys.py:27-33); resolution user-own-key → admin key → None (124-142); Fernet key HEATER_AI_KEY (falls back to HEATER_RELAY_KEY). Key VALUES never in git.ChatService._build_user_content (chat_service.py:60-89): with NO tag/image/page-context it returns the bare message string — that exact byte-identity is what keeps the equivalence test green; attachments produce the OpenAI multimodal parts list; page_context folds a data-json block into the user turn. Vision-incapable model + image → graceful error frame, never a 500.
bubba.sendStream handles text_delta / tool_started / tool_result / done / error (Bubba.tsx:380-436). Errors surface as an in-chat frame — the stream endpoint never 500s mid-stream.usePageData publishes {pageId, data} to BubbaContext; Bubba serializes to a 16 KB UTF-8-byte cap, code-point-safe (Bubba.tsx:57). Wiring a page through usePageData gives Bubba context for free.data-bubba-tag off PlayerLink (intercepts before PlayerDialog); data-bubba-panel excludes Bubba itself from snapshots; snapshots of cross-origin headshots render blank (documented html-to-image caveat, keyed on source==="snapshot").Model/pricing questions → the claude-api skill. Adding a normal (non-chat) endpoint → heater-appb-endpoint-slice. Tier design changes (new tiers, cap amounts) are owner decisions.