mirror of
https://github.com/moeru-ai/airi.git
synced 2026-05-17 12:49:33 +00:00
9a182e0b68
Some checks are pending
Cloudflare Workers (server-dev) / Deploy - stage-web (server-dev) (push) Waiting to run
Why:
- Add a real bidirectional streaming TTS path: raw LLM tokens are
forwarded to the upstream model (Volcengine v3 via the unspeech ws
bridge) without client-side segmentation, so the model owns sentence
splitting and audio chunks play as they arrive.
- Move audio endpoints out of /api/v1/openai/. `/audio/voices`,
`/audio/models`, `/audio/voices/streaming` are not real OpenAI public
APIs, and the streaming TTS surface has nothing to do with OpenAI —
keeping them under /openai/ mislabelled the contract.
- Introduce `capabilities.speech.transport` on ProviderDefinition so
future streaming providers (ElevenLabs / Cartesia / OpenAI Realtime)
opt in without touching Stage.vue or the session factory.
- Unify Stage.vue's TTS path through a single StageTtsSession so the
chat-orchestrator hooks no longer branch on provider id.
What:
- apps/server: new ws proxy /api/v1/audio/speech/ws bridges client ↔
unspeech with auth, pre-flight flux check, billing from upstream
session.finished.usage, OTel spans.
- apps/server: audio routes moved from /api/v1/openai/audio/* to
/api/v1/audio/* (hard cutover; 404 sentinel tests added).
- apps/server: new /api/v1/audio/voices/streaming proxy reads voices
from unspeech /api/voices?provider=volcengine.
- apps/server: new STREAMING_TTS_UPSTREAM configKV entry +
scripts/seed-streaming-tts.ts.
- stage-ui: new libs/speech/streaming-pipeline.ts opens one ws per LLM
intent (appendText / finish / cancel + onSentence / onError / onDone).
- stage-ui: new libs/speech/tts-session.ts — StageTtsSession interface
with segmenter and streaming adapters; factory dispatches by
capabilities.speech.transport instead of hard-coded provider id.
- stage-ui: providerOfficialSpeechStreaming with capabilities.speech =
{ transport: 'bidirectional-ws' }; settings page with model/voice
picker + ws-based preview.
- stage-ui: Stage.vue chat hooks collapsed to a single currentSession;
hot-swap watcher cancels mid-session on provider/voice/model change;
unmount cancels and drains playback.
Tests:
- 9 streaming-pipeline tests (happy path / buffered / error / cancel /
truncation)
- 11 tts-session tests (factory branch coverage + adapter contracts)
- 4 audio-speech-ws route tests (forwarding / billing / pre-flight /
config-missing)
- 3 legacy-path 404 sentinels in v1 route tests
- Verification doc updated to reflect automated coverage.
|
||
|---|---|---|
| .. | ||
| verifications | ||
| account-deletion.md | ||
| admin-flux-grants.md | ||
| architecture-overview.md | ||
| auth-and-oidc.md | ||
| billing-architecture.md | ||
| config-and-naming-conventions.md | ||
| data-model-and-state.md | ||
| email-auth-resend.md | ||
| flux-meter.md | ||
| llm-router-codex-followups.md | ||
| metrics-ownership.md | ||
| observability-conventions.md | ||
| observability-metrics.md | ||
| README.md | ||
| redis-boundaries-and-pubsub.md | ||
| stripe-pricing.md | ||
| transport-and-routes.md | ||
| workers-and-runtime.md | ||
AIRI Server AI Context
这组文档面向后续 AI / 开发者协作，目标是让人快速回答四个问题：
- 服务端是怎么启动和组装的
- 每条 API / WS 请求最终落到哪个服务
- 哪些状态以 Postgres 为真相源，哪些只是缓存或派生数据
- 计费、充值、事件分发这些高风险链路有哪些约束
文档索引
architecture-overview.md- 入口、依赖注入、应用装配、核心边界
transport-and-routes.md- HTTP / WebSocket 接口面、路由到服务映射、鉴权与中间件
data-model-and-state.md- 主要表、状态归属、缓存边界（事件队列层已拆掉）
workers-and-runtime.md- 单
apirole、无后台 loop、运行时约束（admin grant / Stripe webhook 等都同步在请求线程）
- 单
redis-boundaries-and-pubsub.md- Redis key / channel 收口、Pub/Sub 边界、运行时校验约束
config-and-naming-conventions.mdconfigKV默认值来源、Redis key 命名、HTTP route 命名、后续收敛 TODO
billing-architecture.md- 计费链路专项说明，重点看 Flux ledger / Stripe 幂等
stripe-pricing.md- Flux 充值定价以 Stripe Product/Price 为单一真相源，多币种 / 缓存 / 运营操作
flux-meter.md- Sub-Flux 计量服务（TTS/STT 等）的债务账本机制与复用指南
observability-conventions.md- traces / metrics 命名规则，标准 OTel 字段与
airi.*自定义字段边界，SemconvStability 迁移、Counter priming、Dashboard 变量陷阱
- traces / metrics 命名规则，标准 OTel 字段与
observability-metrics.md- 全量 metric 目录（按域分组：HTTP / Auth / Engagement / Revenue / GenAI / Email / Rate limit / Runtime），含名字、类型、Labels、落点
metrics-ownership.md- 指标分层规则：什么走 Grafana / 什么走 PostHog / 什么是 Postgres truth；含 7 题判定 Checklist、PostHog 事件命名约定、当前指标归属总表、PostHog 接入路线图
auth-and-oidc.md- 认证与 OIDC Provider 架构、登录流程、trusted clients、踩坑记录
email-auth-resend.md- Resend 接入、Better Auth 四个邮件 callback、范围 / 决策 / 不做项
account-deletion.md- 账号注销架构：auth 表 hard delete + 业务表软删，handler 协议、各业务行为、failure 模型
admin-flux-grants.md- Admin 批量发 FLUX（活动赠送）：单一同步 POST，无 batch 表无后台 loop，
adminGuard邮箱白名单 + 可选idempotencyKey
- Admin 批量发 FLUX（活动赠送）：单一同步 POST，无 batch 表无后台 loop，
verifications/email-auth.md- 邮箱注册 / 忘记密码 / OIDC 桥接登录 三条用户路径的真实实测证据
verifications/account-deletion.md- 账号注销端到端验证：what's verified（schema/typecheck/units）和 what's pending（live DB + Resend + Stripe trace）
verifications/admin-flux-grants.md- Admin 同步发 FLUX 路径：同步 grant / dry-run / adminGuard 拒绝（架构刚从 batch 切换到同步，待重新实测）
verifications/flux-unbilled-exploit-fix.md- Unpaid-usage exploit 修补（commit
7267b0d6b）的代码层验证 + 残余 gap（TTS flux-meter 未适配 partial-debit）+ follow-up 清单
- Unpaid-usage exploit 修补（commit
verifications/flux-unbilled-reconciliation.md- 70.2K 历史漏账的取证 SQL + Loki query 模板、处理决策框架、修补后的监控建议
快速结论
apps/server/src/app.ts是唯一的 API 应用装配入口。- 服务端采用
Hono + injeca + Drizzle + Redis + better-auth。 - 路由层整体较薄，业务逻辑主要在
src/services/。 - Postgres 是所有余额与计费状态的唯一真相源，Redis 只做缓存、KV、Pub/Sub。计费链路不再使用 Redis Streams。
- WebSocket 只用于聊天同步，跨实例广播依赖 Redis Pub/Sub。
- 对外 LLM 能力不是本地推理，而是转发到配置里的 gateway，再按 usage / fallback rate 扣 Flux。
修改代码前建议先看
- 改 API 入口或新增依赖：先看
architecture-overview.md - 改某个接口行为：先看
transport-and-routes.md - 改表结构、缓存或幂等：先看
data-model-and-state.md - 想加任何"异步副作用 / 后台 loop"：先看
workers-and-runtime.md的"运行时修改建议" - 改 Redis key、Pub/Sub 边界：先看
redis-boundaries-and-pubsub.md - 改配置默认值、Redis key 命名、HTTP route 命名：先看
config-and-naming-conventions.md - 改扣费、充值、Stripe：先看
billing-architecture.md - 改 Flux 充值价格 / 多币种 / Stripe Product/Price：先看
stripe-pricing.md - 改 trace / metric attributes、OTel 命名：先看
observability-conventions.md - 加新 metric / 找当前 metric 全量列表：先看
observability-metrics.md - 决定新指标该走 Grafana 还是 PostHog：先看
metrics-ownership.md - 改认证、OIDC、登录流程：先看
auth-and-oidc.md - 改邮件 service / Better Auth 邮件 callback：先看
email-auth-resend.md - 改账号注销 / 业务 service 的
deleteAllForUser：先看account-deletion.md - 改 admin 发 FLUX 路径：先看
admin-flux-grants.md - 改 TTS / STT / embedding 等 sub-Flux 计量：先看
flux-meter.md