type
Post
status
Published
date
slug
summary
tags
推荐
开发
建站
Nextjs
全栈
学习
出海
上站
category
阅读笔记
icon
password
技术栈选型：2025 年的“版本答案” 为了追求极致的开发效率与维护性，我选了这套组合：
Framework:@Nextjs16 +@Reactjs19
API:@tRPCiov11 + React Query
Backend:@Supabase+@Upstash
Platform:@Tauri+@Expo+#WXT
UI:@Shadcn+@Tailwindcss+ Framer Motion
AI: Vercel @AISDK6.0
 
Monorepo + 依赖注入
notion image

0.2 环境搭建

全面拥抱 Bun： • 安装依赖快 20 倍 (Monorepo 救星) • 原生支持 Workspaces • 极速启动 Next.js Dev Server
 
策略：Bun for Dev, Node for Prod 虽然 Bun 很快，但在生产环境容器中，我们依然选择稳健的 Node.js 22。
Dockerfile 揭秘： • Build 阶段：用 Bun 安装依赖 (快！) • Runner 阶段：用 Node.js 运行服务 (稳！)
notion image
 
质量检测：Husky + Lint-staged
notion image
Backend: Supabase CLI 我们没有后端 ORM 代码，只有数据库 Schema。 • `bun run db:types`: 魔法命令
✨
• 自动根据 DB 表结构生成 TypeScript 类型。 • 后端改个字段，前端立马爆红。 Fail Fast, Fail Loud. 在编译时发现错误，而不是在运行时。
这是我们的 Setup 流程，简单粗暴：
  1. bun install
  1. cp .example.env .env
  1. bun run db:push (推 Schema)
  1. bun run dev
notion image
 

0.3 架构篇

核心代码：**/core
这是整个项目的核心。 Next.js 16 + tRPC + Tailwind 4。
所有的业务逻辑、API 路由、数据库交互都在这。 它不仅是一个网站，更是其他端的“逻辑供应站”。
插件 (WXT)、桌面端 (Tauri)、App (Expo) 都是“壳子”。 它们负责： • 初始化平台环境 • 注入原生能力 (文件访问、托盘) • 挂载 Core 里的 UI 和 Hooks
代码复用率高达 90%+！
 
如何让 WXT 插件引用另一个文件夹的代码？ 我们用 Bun Workspaces 配合 Vite Alias。
修改 @bibigpt/core 里的一个函数，插件那边秒速热更新。 这种开发体验，用了就回不去了。
notion image
tRPC 全栈类型共享，
共享 Schema 的好处 后端改个字段，前端、插件、桌面端代码立马爆红提醒。
告别 Swagger，告别“接口文档”，代码就是最精准的文档。
 
交付：Commit once, Build everywhere
通过 GitHub Actions 自动化： • Web 自动部署A/B/C 三套服务器 • 插件自动打包上架商店 • 桌面端自动编译 Win/mac 安装包 • 移动端 Expo EAS Workflows
特别是移动端，EAS 把复杂的 iOS 构建搬到了云端。 eas build --auto-submit，睡一觉，TestFlight 就好了。
 

0.4如何拥抱 AI Agent 军团？

核心指挥部：Cursor

它是目前唯一懂“全项目上下文”的 IDE。 Agent Mode (Ctrl+I) 是降维打击： “把语音转文字组件提取出来，并制作单独的 SEO 页面”。 它不是在改文件，它是在理解你的意图，然后批量执行。 这就是为什么我们要维护 `
http://AGENTS.md
` —— 给 AI 的军规。

架构师：Claude Code CLI

Anthropic 官方出品。它不是聊天机器人，它是拥有 Shell 权限的高级工程师。 它能： • 运行测试并自动修复 • 分析复杂重构的影响范围 • 连接数据库 (Postgres MCP)
最重要的是，它可以配置 GLM/MiniMax 等国产模型，成本大幅降低。

参谋长：Gemini CLI

拥有 100万 Token 上下文的上下文之王。 当我需要“理解整个项目”时，我就问它。
我们定义了 Slash Commands： • /review: 帮我 Review 还没提交的代码 • /plan: 根据 TODO 生成 Step-by-Step 开发计划
 

影子写手：OpenAI Codex / GitHub PR

Mobile Idea -> Cloud Runtime -> GitHub PR。 躺在床上想到功能，直接用手机 ChatGPT 写个雏形，自动提 PR。
特别是最新的 GPT-5.2，它是个“死心眼”： 它不猜，它只信源码。 它会扒开你的代码一行行看，直到找到那个藏在深处的 Bug。 它是最好的 Bug Fixer。

神经连接：MCP (Model Context Protocol)

这是 2025 年最重要的技术。 它让 AI 不再是“与世隔绝”的大脑，而是能手脚并用的“人”。
BibiGPT 通过 MCP 让 AI： • 读取本地文件 • 操作数据库 • 抓取网页文档 • 制作 PPT 生成图片 • 甚至帮我发推（比如现在）
 

作战法则：PLAN & EXECUTE

不要上来就让 AI 写代码。 遵循 P.E.A.R. 原则：
  1. Plan: 用 Gemini 生成计划
  1. Execute: 用 Claude Code 执行
  1. Assess: 运行测试
  1. Refine: 人工微调
你不再是 Coder，你是 Commander。
 
 

程序员视角的 LLM：它不是魔法，它是数学。

很多开发者觉得 AI 是黑盒，其实它本质就是一个概率函数，类似“老虎机”： Input: Context -> Output: Next Token

1.1 程序员视角的 LLM

很多开发者觉得 AI 是黑盒，其实它本质就是一个概率函数，类似“老虎机”： Input: Context -> Output: Next Token BibiGPT 全栈 AI 实战本模块带你拆解 4 个最核心的概念： 1. Token 2. Context Window 3. Temperature 4. Streaming

Token (词元)

LLM 不识字，它只认识 Token。 "Hamburger" 不是一个词，是 "Ham", "bur", "ger"。 为什么重要？
计费按 Token 算
记忆限制按 Token 算 我们在前端用 `gpt-tokenizer` 预估 Token，以及 AI SDK 统计所消耗的 token usage

Context Window (上下文窗口)

这是 LLM 的“短期记忆”，像一条有限长的传送带。 新信息进来
旧信息掉落悬崖（被遗忘）。 这就是为什么我们需要 RAG (检索增强生成)： 不是把整本书塞进去，而是只把“当前最相关”的那几页塞进这个窗口。

Temperature (温度)

控制 AI “脑洞”的开关 (0.0 - 2.0)。
**0.0 (Cold)**: 绝对理性。 适合：代码生成、提取 JSON。
**1.0 (Hot)**: 疯狂艺术家。 适合：头脑风暴、创意写作。 在 BibiGPT： - 总结视频用 0.3 (求稳) - 起标题用 0.7 (求吸睛)
Streaming (流式传输)
这是现代 AI 应用 UX 的基石。 AI 生成很慢。如果不流式输出，用户会以为你的网断了。
要做到 TTFB (Time To First Byte) 极短，让字一个个蹦出来。 这不仅仅是特效，这是心理学。让用户感知到“它正在思考”。
总结：
Token: 计费单位
Context Window: 短期记忆传送带
Temperature: 脑洞开关
Streaming: 体验救星
 
 

1.2 Hello World

如果说 OpenAI API 是原生的 DOM 操作，那么 Vercel AI SDK 就是 jQuery。 它抹平了不同模型提供商 (OpenAI, Anthropic, Google) 之间的差异，是 Next.js 生态的事实标准。
核心双雄：generateText vs streamText
SDK 最常用的两个函数，决定了你的产品体验：
  1. generateText: 一次性生成。
      • 场景：后台总结、数据提取、Cron Jobs。
      • 特点：简单，但用户要等。
  1. streamText: 流式输出。
      • 场景：Chat UI、实时写作。
      • 特点：TTFB (首字节时间) 极快，用户体验好。
 

统一接口 (The Unified Interface)

看这段 BibiGPT 的真实生产代码。 注意 model: getModelProvider(...)。
我们不需要为 Claude 写一套代码，为 GPT-4 写另一套。 SDK 帮我们做了统一封装。切换模型只需改一个配置字符串。
 

拒绝盲飞：可观测性 (Telemetry)

生产环境不能瞎跑。 SDK 内置了 experimental_telemetry。
只需几行配置，就能将 Token 消耗、延迟、输入输出自动发送到 Langfuse 或 Helicone。 知道你的 AI 也就是花了多少钱，这点至关重要。
栗子
generateText({ model: openai('gpt-5.2'), prompt: 'Hello World' })
 

1.3 Prompt Engineering

Few-Shot Prompting：举一反三的力量

LLM 本质是模式补全引擎。 Don't tell, show. (不要只说，要演示)
给 AI 1 到 3 个 Input/Output 示例，比写 100 行繁琐规则更有效。 它能教会 AI 你的标准、语气和输出格式。

BibiGPT 实战：ASR 纠错

处理视频字幕时，AI 容易过度修正。 我们用 Few-Shot 告诉它： • 修正 React Hooks 大小写
• 保留口语化的 "gonna"
• 去除 "um, uh" 冗余词
规则不需要写死，AI 自己会领悟模式。
notion image

Chain of Thought (CoT)：让 AI 慢下来思考

AI 逐个 Token 生成，就像人说话一样，不思考容易“嘴瓢”。 强迫模型先生成推理过程（Internal Thought），再给结论。
在 BibiGPT 中，深度摘要通过 Analyze -> Extract -> Synthesize 路径生成。 拒绝流水账，直击重点。

ReAct (Reason + Act)：推理与行动的闭环

这是 AI Agent 的基石。 AI 不再是被动回答，而是主动调查： • 发现信息过期？-> 调用搜索工具。 • 需要实时数据？-> 查询数据库。
让 AI 具备时效性和真实性。

总结：Prompt 是与模型的协议

  • Few-Shot：解决“懂不懂” • CoT：解决“深不深” • ReAct：解决“准不准”
 

1.4 结构化输出

Zod：AI 的饼干模具

我们不再通过 Prompt 苦口婆心地要求 AI “请务必输出 JSON”。 我们直接用 Zod 定义数据的“形状”。
Zod 不仅让你的代码类型安全，它还直接成为了 AI 的行为准则。 不符合 Schema 的数据？根本进不来。

.describe()：最高级的提示工程

这是 BibiGPT 生产环境的绝招。 不要在外部 Prompt 里写长长的字段要求。 直接在 Zod Schema 里写 .describe()。
字段描述就是给 AI 最精准的秘密指令。 AI：明白了，保证按要求填充字段！

流式结构化：看着 JSON “生长”

谁说 JSON 必须等生成完才能用？ 配合 streamText 和 partialObjectStream，你可以看着字段一个个长出来。
对于周报、长计划生成等 UI，拒绝 Loading 动画，立即可见！

总结：不再是黑盒，而是标准 API

Vercel AI SDK 抹平了 OpenAI (JSON Mode) 和 Anthropic (Tool Calling) 的底层差异。 你只需要写一次 Zod，就能运行在任何模型上。

1.5 Agents & Tools

什么是 Agent (智能体)? Agent 不再是被动等待指令的“复读机”，而是主动决策的“指挥官”。 你给它一个任务（如：研究 React 19），它会自动： • 拆解步骤
• 选择工具
• 搜集信息
• 交付结果

Tool Calling 的真相

误区：AI 会直接运行你的代码。 真相：AI 只会输出文本 JSON 告诉你“它想运行什么”。
流程：AI 思考 -> 你的程序执行代码 -> 结果喂回 AI。 LLM 是大脑，代码是四肢。

幕后魔法：maxSteps: 5

这是 Vercel AI SDK 的精髓。 没有它，Agent 只能“想”一次。 有了它，Agent 开启自动驾驶：搜视频、读字幕、写摘要，多轮循环一气呵成。

实战：BibiGPT 语音记账

“昨天在全家买了 25 块钱便当。” Agent 自动识别意图，分类为“餐饮”，并调用数据库工具直接入账。 意图识别 + 数据归一化，Agent 才是最终形态。

2.1: tRPC - 类型安全的护城河

tRPC。 我们要构建一条连接前后端的、绝对安全的类型桥梁，彻底告别 API 文档和猜谜式开发。

Context: 异构请求的灵魂

BibiGPT 的 tRPC Context 需要同时处理 Web、插件、桌面端和 API Token 的认证。 通过在 Context 层统一抹平差异，业务代码只需关心 ctx.user。 这就是“Fail Fast”和单一职责原则。

Zod + Output：双重守卫

tRPC 的 input 必须用 Zod 验证，这已经是共识。 但更重要的是 .output()。 它强制你“清洗”返回给前端的数据，防止任何敏感字段（如用户邮箱）意外泄露。

Split Link: 智能网络分流

tRPC 不仅是类型安全，更是网络控制。 BibiGPT 使用 splitLink： • 普通请求 -> httpBatchLink (合并请求，省连接) • AI 生成 -> httpBatchStreamLink (流式响应，快！)
为不同任务匹配最优的网络策略。

总结：重构的信心

tRPC 的核心价值，是让你拥有无与伦比的重构信心。 改一个字段，所有受影响的地方都会飘红。跟着 TS 错误走，就能 100% 安全地完成重构。

2.2 Supabase - 后端的安全卫士

异构客户端的统一

BibiGPT 需要同时适配 Web、浏览器插件和桌面端，乃至开放 API。 Web 靠 Cookie，桌面端靠文件持久化。 我们利用 @supabase/ssr 库，在 Context 层抹平了所有终端的认证差异。 同一套逻辑，跑在所有端。

RLS：数据库层面的防火墙

Row Level Security (RLS) 是 Supabase 的杀手锏。 即使你的代码逻辑出 Bug 导致 API 返回了所有数据，数据库层的 auth.uid() = user_id 也会强制过滤。 不再依赖 API 校验，让数据库自己识别身份。

SQL 里的“宪法”：Policies

在数据库中定义：CREATE POLICY ... USING (auth.uid() = user_id)。 这比在业务代码里写一堆 if 判断要健壮得多。 它是 AI SaaS 多租户安全的生命线。
 

2025 认证标准：PKCE

为了极致的安全，BibiGPT 全面转向 PKCE 认证流程。 通过后端 Code 交换 Token，避免了在 URL Hash 中暴露 Access Token 的风险。 专业 SaaS，安全先行。
 

总结：后端网关已就绪

通过 SSR Client 抹平端差异，通过 RLS 构建深度防御。 Supabase 不只是数据库，它是你的后端网关。

2.3: Database Design - 记忆的载体

Schema 设计：内容与元数据分离

BibiGPT 将 user_contents (视频源) 与 user_contents_note (AI 笔记) 分离。 • 关系型 (SQL): 存储标题、时长、用户 ID。 • JSONB (NoSQL): 存储 AI 生成的字幕和摘要。 JSONB 让我们在享受 SQL 强一致性的同时，拥有 NoSQL 的灵活性。
 

pgvector: 数据库的大脑

传统的 LIKE 查询找不到“意思相近”的内容。 通过启用 pgvector 扩展，Postgres 可以直接存储和检索 Embedding 向量。 你不需要维护额外的 Pinecone 或 Weaviate。 少一个系统，多一份安稳。
 

语义搜索 (Semantic Search)

这是 RAG (检索增强生成) 的核心。 用户提问 -> 转成向量 -> 数据库计算余弦相似度 -> 返回相关片段。 我们在 Postgres 内部用 SQL 函数 match_documents 实现了这一切。 计算就在数据旁边，速度极快。
 

SQL Migrations: 代码化管理

数据库变更不能靠手点。 BibiGPT 严格遵循 Migration-based 工作流。 bun run db:push 将变更纳入版本控制。 可审计、可回滚、可协作。
 

总结：Postgres Maximalism 我们用 Postgres 做搜索、做鉴权、做向量、存 JSON。 One Database to rule them all.

 

2.4: Task Queue - Serverless 的异步救星

Supabase 数据库是整个 AI SaaS 应用的长期记忆。 但是，数据库不是万能的。 当遇到需要跑 10 分钟的视频转录任务时，千万不要让数据库连接挂着等待。
今天我们来解决 AI 应用中最棘手的问题：耗时任务与超时。
 

Serverless 的阿喀琉斯之踵

Next.js API 路由有 10-60 秒的超时限制。 而一个长视频的转录可能需要 5 分钟。 同步执行 = 504 Gateway Timeout = 用户流失。 我们需要异步队列。
 

架构：HTTP as a Queue

我们使用 Upstash QStash。 Producer (API) 把任务丢给 QStash，立即返回 "Pending"。 QStash 在后台慢慢把任务推给 Consumer (Worker)。 削峰填谷，自动重试。HTTP 就是我们的协议。
 

消费端：安全验证

Worker 是一个公开的 API Route。 为了防止恶意调用，我们必须验证 QStash 的签名。 verifySignature 是第一道防线。
notion image
 

Rate Limiting：API 防弹衣

除了队列，Redis 还用来做限流。 我们不能让恶意用户刷爆 OpenAI 的额度。 通过 Redis 滑动窗口限流，每秒几万次检查都毫无压力。
 

总结：后端基建完成

tRPC 网关 + Supabase 堡垒 + Upstash 队列。 这就是现代 AI SaaS 的坚实地基。
 

3.1: 视频转录 - AI 业务的入口

音视频内容的转录 如果没有精准的逐字稿，再强的 Prompt 也是“巧妇难为米之炊”。

提取：只取精华

千万不要下载 4K 视频！ B站和 YouTube 都支持 DASH 流，我们可以通过官方 API 单独提取音频流。 这样不仅节省了 90% 的带宽，还让处理速度瞬间起飞。

速度：Groq LPU 降维打击

虽然 OpenAI Whisper 很强，但 GPU 还是太慢。 在 2025 年，BibiGPT 多语言转录使用了 Groq 的 Whisper 服务，值得一提 12 月 25 日英伟达 200 亿美元收购了 Groq 核心团队成员。 凭借 LPU 芯片，1 小时的长视频转录只需几十秒。这种极致反馈是 UX 的生命线。

预处理：压缩胜过切片

API 都有文件大小限制 (25MB)。 我们的绝招：MP3 32kbps 极度压缩。 Whisper 对音质极其宽容，压缩后哪怕 2 小时的播客也能塞进一个 API 调用，无需复杂的切片合并。

Whisper 也吃 Prompt

很多人不知道，Whisper 支持 prompt 参数。 我们可以注入视频标题作为上下文，告诉 AI：这是一段关于 "tRPC" 和 "Next.js" 的讨论。 这能显著提升专业术语的拼写准确率。

总结：文字已就绪

掌握了源头优化、Groq 加速、预处理和上下文注入，你已经拿到了高质量的“AI 燃料”。

3.2: 智能摘要引擎

面对 2 小时的播客或会议视频，LLM 也会感到“疲惫”。 即便 Context Window 够大，高昂的成本和“信息遗忘”（Lost in the Middle）依然是商业化的拦路虎。
BibiGPT 如何处理无限长的视频？秘诀是 Map-Reduce。
 

Map-Reduce：分而治之

对于超长视频，我们不盲目全量输入：
  1. Split: 将字幕切成 25 分钟的 Chunks。
  1. Map: 并行调用小模型（如 gpt-5-mini）生成局部摘要。
  1. Reduce: 将所有局部摘要合并，用大模型（如 gpt-5）进行最终归约。
快、省、全。
 

Prompt Chain：逐步求精

高质量的摘要不是一次生成的。 BibiGPT 采用提示链技术： Outline (大纲) -> Detail (提取要点) -> Polish (最终润色)。 这种“多步走”策略比单次生成更稳定，逻辑更清晰。
 

动态 Prompt 路由

不同视频类型需要不同的侧重点。 教程需要步骤，访谈需要金句，新闻需要 5W1H。 我们先用 Classifier 识别类型，再动态路由到对应的 Prompt 模板。 这才是真正的“智能”摘要。
 

总结：从原始数据到结构化知识

通过 Map-Reduce 解决长度，Prompt Chain 解决深度，Dynamic Prompting 解决适应性。 BibiGPT 将 LLM 的潜力发挥到了极致。
 

3.3: RAG - 给 AI 外挂大脑

ChatGPT 很强，但它不知道你的视频讲了什么。 BibiGPT 的 "Chat with Video" 功能，就是为了解决这个问题。 我们不是把 2 小时的字幕全塞给 LLM，而是通过 RAG (检索增强生成)，只喂给它最相关的片段。
 

Embedding：把意义数字化

关键词搜索 (Ctrl+F) 很傻。它找不到 "React 的缺点" 和 "React 的局限性" 之间的联系。 Embedding 将文本转化为 1536 维的向量。在这个空间里，意义相近的词距离更近。 我们使用 text-embedding-3-small 或同等向量模型，便宜又强大。
 

Indexing：语义切片

切片 (Chunking) 是一门艺术。 切得太碎，语义断裂；切得太大，包含噪音。 BibiGPT 采用 "Semantic Chunking + Overlap" 策略。 每个片段保留 100 字符的重叠窗口，确保上下文连贯。
 

Retrieval：pgvector 向量搜索

我们不需要专门的向量数据库（如 Pinecone）。 Supabase 的 pgvector扩展让 Postgres 拥有了向量能力。 一个简单的 SQL 函数 match_documents，就能在毫秒级找出与用户问题最相关的 5 个片段。 All-in-One Database 架构再次胜利。
 

总结：事实与幻觉

RAG 是连接 LLM 通用知识与你私有数据的桥梁。 通过 Chunking -> Embedding -> Retrieval -> Generation。 我们让 AI 基于事实说话，而不是凭空捏造。
 

3.4: 多模态实战 - 让 AI 看见世界

文字总结已是红海，多模态才是未来。 如果 AI 只能“听”到讲师说“看这张图”，却“看”不到图，那它的理解就是残缺的。 BibiGPT 集成 GPT-5 与 Gemini 3 Pro，构建“听觉+视觉”双通道引擎。
 

视觉流水线：智能截图

视频由无数帧组成，全部分析太贵且低效。 我们的策略：基于语义提取关键帧。 先分析字幕找到“描述性段落”，再调用 FFmpeg 在对应时间点精准截图。 只抓重点，不看废片。
 

双引擎对决：GPT-5 vs Gemini

  • GPT-5: 精准的“显微镜”。适合对单张关键帧进行深度图表分析。 • Gemini 3 Pro: 宏大的“望远镜”。拥有 1M+ Context，能原生理解长视频的起承转合。 BibiGPT 根据场景动态切换，取长补短。
 

代码实战：Gemini Video API

Gemini 的开发体验极佳。 无需自己切片截图，直接上传视频文件，它就能“看懂”一切。 这是处理长视频（如 1 小时课程）的终极杀器。
 

总结：AI 大脑拼图完成

Module 3 结束！ 我们构建了 Whisper (耳)、Map-Reduce (脑)、RAG (记)、Vision (眼)。 一个全能的 AI 分析引擎已就绪。

4.1: Shadcn UI 定制：打造你的设计系统

UI 组件库。

在 React 生态中，组件库的选择一直是老大难问题。MUI 太重，Ant Design 样式太难改，Chakra UI 运行时性能有损耗。 现在的王者是@ShadcnUI。 它其实不是组件库，它是“复制代码生成器”，并支持完整的设计主题，每个变量都可以个性化。

架构分层：The Anatomy

Shadcn 的精妙之处在于它的分层架构：
  • 底层：Radix UI (无头组件，负责 A11y 和逻辑)
  • 中间：Tailwind CSS (原子化样式)
  • 上层：Shadcn (胶水代码)
既有 Radix 的稳健，又有 Tailwind 的灵活。

拥有代码的所有权

npm install button 是把代码锁在 node_modules 黑盒里。 shadcn add button 是把源码下载到你的 components/ui 目录。 这意味着什么？ 意味着你可以让 AI 随意魔改！想加动效？想改圆角？直接改源码，不用跟 !important 较劲。

业务组件封装

别只用原生组件。 BibiGPT 基于 Shadcn 封装了大量的业务组件。 比如 SummaryCard，它组合了 Card, Badge, Button 等基础原子。 原子化设计 (Atomic Design) 在这里得到了完美体现。

注入灵魂：Framer Motion

光有静态 UI 还不够。 为了让 AI 生成的内容像流水一样自然出现，我们结合了 framer-motion (motion/react)。 封装一个 <FadeIn> 组件，给每个段落加上细微的进入动画。 这种“呼吸感”是区别高级应用与土味网页的关键。

总结：生产力与自由度的平衡

Shadcn UI + Motion 让你既有现成的轮子用，又能享受 DIY 的自由。 它是 AI 时代构建现代 Web 应用的最佳选择。

4.2: 流式 UI - 别让用户干等

AI 生成一篇长文可能需要 30 秒。 如果让用户盯着 Loading 转圈圈 30 秒，他早就关页面了。 在 AI 应用中，速度往往是心理学问题。 秘诀是 Streaming UI (流式界面)。

Latency Masking：先上车后补票

乐观 UI (Optimistic UI) 是前端体验的核心。 当你发送消息时，不要等服务器确认，直接把它画在屏幕上。 配合流式输出（只要 AI 吐出第一个字就显示），用户的等待感会被瞬间消解。 快，是感觉出来的。

光标闪烁：缓解焦虑的小把戏

看这个一闪一闪的光标。 这不仅仅是耍帅。 它在潜意识里告诉用户：“别急，我还在思考，我还在干活。” 一个简单的 CSS 动画 animation: blink，能显著降低用户的焦虑值。

骨架屏：拒绝 Spinner

在连接建立的那 1-2 秒，显示什么？ 千万别用 Spinner（转圈圈让人烦躁）。 用 Skeleton (骨架屏)。 搞几个灰色的长条闪一闪，假装那是文字。它预示着“内容马上就来”。

总结：极致丝滑的体验

流式输出 + 乐观 UI + 骨架屏 + 闪烁光标 = 极致丝滑。 让用户感觉不到延迟，这就是前端工程师的魔法。

4.3: 复杂状态管理 - Zustand 优先架构

前端开发最大的坑就是 State Management。 Props Drilling? Context Hell? Redux Boilerplate? BibiGPT 的架构原则非常清晰：
  • Zustand 管理全局 UI 状态
  • nuqs 管理 URL 参数
  • React Query/tRPC 管理服务端数据
 

Zustand：轻量级全局状态

为什么选 Zustand？因为它是 Single Source of Truth。 对于 "Sidebar 是否打开"、"用户偏好设置" 这种跨页面状态，Zustand 是不二之选。 配合 persist 中间件，一行代码就能把状态自动保存到 localStorage。 刷新页面？状态还在。
 

nuqs：URL 即状态

对于 "搜索关键词"、"Tab 选项" 这类需要分享的状态，绝不能只存在内存里。 使用 nuqs (Next URL Query Strings)，将状态同步到 URL。 发给同事的链接，打开就是你看到的界面。 Deep Linking 是 SaaS 的基本修养。
 

Server State：数据库才是真理

不要把 API 数据塞进 Zustand！这是初学者最爱犯的错。 用户数据、视频列表... 这些属于 Server State。 交给 React Query (via tRPC)。 它自带缓存、自动重试、窗口聚焦刷新。 让后端数据库成为唯一的真理来源。
 

总结：状态分层金字塔

不要一把梭，要分层治理：
  • Async Data: React Query/tRPC (Server State)
  • Global UI: Zustand (Client State)
  • Shareable: nuqs (URL State)
  • Local: useState (Component State)
 

4.4: 国际化 (i18n) - 赚全世界的钱

虽然 BibiGPT 目前 80% 的用户可能都还是中文用户，但我们不能止步于此。 AI 是无国界的。如果你想做成真正出海征服整个世界，必须 Global First。 i18n 不仅仅是翻译 JSON 文件，它是关于文化适配、本地化 SEO 和全球增长的野心。
 
为什么要出海？
中文互联网很卷，但全球市场是星辰大海。 支持多语言意味着你的 Total Addressable Market (TAM) 瞬间扩大 7*5 倍。 这不是选修课，这是必修课。 Don't limit your potential revenue.
 

Middleware：智能路由

我们使用 next-intl。 它通过 Middleware 自动探测用户的浏览器语言。 如果是西班牙语用户访问，自动跳到 /es。 最重要的是，它对SEO极其友好。Google 能通过 hreflang 准确索引你的多语言页面，带来免费的有机流量。
 

Deep Localization：不止是翻译

真正的本地化不仅仅是 UI 翻译。 是 AI 生成内容的意译和基于用户需求的创作输出， 用户看英文视频，我们用 GPT-5 生成中文摘要；看日文视频，生成英文摘要。 这种动态的、Cross-Language 的内容理解，才是 AI 产品的杀手锏。
 

总结：Module 4 完结

前端部分搞定！ 界面美了 (Shadcn+Motion)，速度快了 (Streaming)，状态稳了 (Zustand)，语言通了 (i18n)。 万事俱备，只欠东风。
 

5: 商业化与增长

5.1：支付集成。

我们将把 BibiGPT 从一个工具，变成一台 24/7 运转的印钞机。
很多独立开发者都有“发布恐惧症”。 总觉得功能还不够完美，不敢收钱。
其实，Buy Button (购买按钮) 才是检验产品价值的唯一标准。 与其纠结功能，不如尽早上线支付。如果没人买，说明你的产品还没解决真正的痛点

为什么选 Lemon Squeezy 而不是 Stripe？

对于个人开发者，处理全球税务 (VAT) 是个噩梦。
Lemon Squeezy 是 MoR (Merchant of Record)，Stripe 也意识到这一点最终把它给收购了
简单说：它是你的分销商。它替你收钱、替你缴税，最后把利润转给你。 你只管写代码，脏活累活它全包了。

支付流程其实就是一个异步状态机：

  1. Client: 用户点击“升级” -> 2. Server: 创建订单
  1. Lemon: 用户在托管页面完成支付
  1. Webhook: Lemon Callback Server & 飞书通知
  1. DB: 验证无误，给用户加时长/权益
最关键的是 Step 4 & 5。
 

代码实战：创建 Checkout

调用 API 创建支付链接时，有一个极其重要的参数：customData。 一定要把 userId/userEmail 传进去！
否则等 Webhook 回调发过来，你只知道“有人付了钱”，却不知道是“谁”付的。这就尴尬了。
 

Webhook 安全：P0 级最高警戒

Webhook 是个公开接口，谁都能调。 万一黑客伪造一个 order_created 请求，你也给他发货？
必须验签 (Verify Signature)！ 拿 Lemon 发来的 X-Signature 和你自己算的 HMAC Hash 对比。 注意：计算 Hash 必须用 Raw Body (原始二进制流)，解析过的 JSON 是算不对的。

本地调试 Webhook

在 localhost:3000 开发时，外网的 Lemon Squeezy 访问不到你。 你需要一个隧道。
神器推荐：ngrok 或 Cloudflare Tunnel。 ngrok http 3000 -> 获得公网 URL -> 填入 Lemon 后台测试。 打通任督二脉！

订阅生命周期 (Subscription Lifecycle)

SaaS 比一次性付费复杂得多。 用户取消订阅了怎么办？
立即停止服务
维持服务直到当前周期结束 (ends_at) 我们要维护一个状态机：Active, Past Due (扣款失败), Cancelled, Expired。 做生意，细节决定成败。

总结：

  1. MoR (Lemon Squeezy) 解决税务合规。
  1. 传递 userId 确保订单关联。
  1. Webhook 验签保证资金安全。
  1. 正确处理订阅生命周期。
 

5.2: 用户体系与配额 (User System & Quota)

"Pricing is not just about the number; it's about the fence you build around your value." 定价不仅仅是数字，更是你为核心价值构建的围栏。
如何设计一套既能防止白嫖，又能让付费用户感到尊贵的系统？

数据库设计哲学：关注点分离

不要在 users 表里加一堆 is_vip, expire_date 字段。 BibiGPT 采用独立的 users_time 表。
  • auth.users: 管身份 (Who you are)
  • users_time: 管权益 (What you have)
这样设计，以后加 Team 功能或 Enterprise 套餐时，不需要改动核心用户表。

混合权益模型 (Hybrid Model)

很多 SaaS 只有订阅制。但在 BibiGPT，我们支持混合模式：
  1. 订阅制 (Subscription): 检查 expires_at。只要没过期，随便用。
  1. 按量付费 (Pay-as-you-go): 检查 remaining_minutes。
非会员买了 100 分钟包？没问题，扣余额就行。 这最大化了转化率。

扣费逻辑：必须原子化

前端可以做 Optimistic UI（乐观更新），但扣费绝对不行！ 必须是原子操作。
Postgres 没有直接的 decrement API？ 写个 RPC (Stored Procedure) 或者使用事务。 逻辑：Check Balance -> Run Task -> Deduct (Atomic)。
如果任务失败了？当然不扣费，做良心商家。

Rate Limiting：API 的守门员

即使是付费用户，也不能每秒发 100 个请求（可能是脚本）。 我们使用 Upstash Redis 做滑动窗口限流。
  • Free: 1 次/10秒，10 次/天
  • Pro: 10 次/10秒，无上限
这不仅是保护服务器，更是一种“软性推销”： “今日免费额度已用完，升级 Pro 解锁无限次。”

懒重置 (Lazy Reset) vs Cron Job

每月给免费用户重置 60 分钟额度。
笨办法：写个 Cron Job 每天半夜遍历 100万 用户数据库。（服务器爆炸）
聪明办法：Lazy Reset。 用户登录时，检查 last_reset_date。 “哟，一个月没来了？给你重置一下。” 没人来？那就永远不用重置。省下的计算资源都是钱。

权益分级 (Tiered Features)

除了时长，还有模型能力的区分。 BibiGPT 的 AI Service 会检查用户身份：
  • Free: 只能用 GPT-5-mini 或 DeepSeek。
  • Pro: 解锁 GPT-5, Gemini 3 Pro, Claude 4.5 Sonnet。
好钢用在刀刃上，贵模型留给付费用户。

总结：

  1. users_time 独立表管理权益。
  1. 支持订阅+按量混合模式。
  1. Upstash Redis 做身份感知限流 (Identity-based Rate Limiting)。
  1. Lazy Reset 节省资源。
 

5.3: 埋点与分析 (Analytics & Observability)

"If you can't measure it, you can't improve it." 做 AI 产品，不仅要看用户数据，还要盯着 Token 成本。

BibiGPT 的双轨分析策略：

1. Amplitude: 关注“人”的行为 (点击、留存)。 2. Langfuse: 关注“AI”的表现 (Prompt、Token、Cost)。
Thread: 如何搭建全链路数据监控

LLM 可观测性：Langfuse

AI 是个黑盒？不。 Langfuse 就像飞机的黑匣子记录仪。 每一次对话、每一个 Prompt、每一分钱的 Token 消耗，全部记录在案。
集成 Vercel AI SDK 极其简单，只需几行代码配置 traceExporter。
 

单客经济模型 (Unit Economics)

你知道你的付费用户是赚还是亏吗？ 通过 Langfuse 聚合数据，我们可以看到： - 用户 A: 付费 $9，消耗 API $2 -> 赚 $7
- 用户 B: 付费 $9，消耗 API $15 -> 亏 $6
发现“亏损用户”后，可以针对性地进行限流或引导升级 Enterprise 套餐。 这叫精细化运营。
 

负反馈闭环 (Feedback Loop)

用户点了“
”之后发生了什么？ 在 BibiGPT，这个负反馈会实时推送到 Langfuse。 我每周会专门复盘这些得负分的 Trace： 是 Prompt 写得不好？还是 Context 截断了？ 针对性优化 Prompt，然后再上线 A/B 测试。 让产品越用越聪明。
 

转化漏斗 (Conversion Funnel)

在 Amplitude 里，我们盯着这条线： Visit -> Paste URL -> Summary Success -> Upgrade Click -> Pay
如果在“Summary Success”到“Upgrade Click”流失率高，说明你的摘要质量没打动人。 如果在“Upgrade Click”到“Pay”流失率高，说明太贵了或支付流程繁琐。 哪里漏了补哪里。
 

盲人摸象 vs 激光制导

没有数据的开发，就是盲人摸象。 凭直觉觉得“用户需要这个功能”，结果上线后没人用。
有了 Langfuse + Amplitude，你的每一个决策都是 Data-Driven 的。 “这个改动让 Token 成本降低了 20%，同时用户满意度提升了 5%。” 这才叫专业。
 

总结：

  1. Langfuse 监控 AI 成本与质量。
  1. Amplitude 分析用户行为漏斗。
  1. 建立负反馈闭环，持续优化 Prompt。
  1. 关注 Unit Economics，确保商业模式健康。
 

5.4: 增长黑客 (Growth Hacking)

"Growth is not magic; it's engineering + psychology." 增长不是魔法，是技术与人性的结合。

BibiGPT 的双引擎增长模型：

1. SEO: 被动流量，让 Google 为你打工。
2. Affiliate: 主动流量，利用互惠与炫耀心理，让用户帮你扩圈。
Thread: 如何设计一个自动增长的飞轮

Programmatic SEO: 流量的地基

BibiGPT 的核心资产是海量 UGC 内容。 手动写 Landing Page 是不可能的。 我们利用 Programmatic SEO，将每一个视频总结都变成一个关键词入口。
10 万个视频 = 10 万个销售员，24 小时不间断工作。 配合 sitemap.xml 和 JSON-LD，让 Google 每天来吃自助餐。
 

分享心理学：面子 vs 里子

仅仅“好用”是不够的。为什么要用户分享？
  1. 互惠 (里子): "分享给朋友，你拿 20% 佣金，他拿 7 天会员。"
  1. 炫耀 (面子): "看，我读完了这个 3 小时的硬核视频（其实是 AI 帮我读的）。"
我们要同时满足这两点。

Dynamic OG Image: 让分享成为一种炫耀

为了满足“炫耀心理”，分享卡片必须足够精美。 没人愿意在朋友圈发一个丑陋的蓝色链接。
我们用 @vercel/og 实时生成精美的 Social Card。 React 代码直接转图片！一张图胜过千言万语，CTR 提升 300%。

Affiliate Program: 20% 现金返利

为了满足“互惠心理”，我们直接分钱。 每个用户都有专属链接 ?ref=xxx。
只要有人通过你的链接付费，你直接拿 20% 现金。 对于 KOL 和重度用户，BibiGPT 不仅仅是一个工具，更是一个副业。 这种动力是极其强大的。向动力非常强大。

The Growth Loop: 增长飞轮

SEO 带来第一批用户 -> 用户被“里子(佣金)” and “面子(精美卡片)”驱动分享 -> 带来更多新用户 -> SEO 权重提升。
不需要投广告。 产品本身就是一台利用人性弱点（褒义）的永动机。

总结：

1. SEO 解决冷启动，让机器干活。 2. Affiliate 解决裂变，让用户干活。 3. 心理学 (炫耀/互惠) 是驱动力。 4. 技术 (@vercel/og) 是燃料。

6：跨平台架构 (Chrome Extension & Desktop)

6.1: 浏览器插件 (Browser Extension)

 
Module 5 我们完成了 Web 端的商业闭环。 但用户不想每次都 "复制链接 -> 打开新标签页 -> 粘贴"。 最好的体验是：我在看 B站，旁边直接弹出总结。 这就需要做插件。 以前做插件很痛苦，现在有 WXT —— 插件界的 Next.js。
Thread: 如何用一套代码“寄生”在浏览器里

难点一：鉴权桥接 (Cookie Sharing)

用户在官网登录了，插件怎么知道？让用户再登一次？太蠢了。 我们要让插件“偷”官网的 Cookie。
在 manifest.json 申请 host_permissions。 插件就能拿到 Supabase 的授权信息，直接发起 API 请求。 无感登录，体验拉满。
notion image

难点二：Shadow DOM 隔离

直接往 B站页面里插按钮？ 会被 B站的 CSS 污染，按钮变得奇形怪状。 必须用 Shadow DOM。
它是一个隔离的沙盒。 WXT 对此支持极好，一行配置，你的 UI 就像穿了防护服，百毒不侵。
notion image

最佳实践：Side Panel API

不要用弹窗 (Popup)，一点击就关掉了。 不要用内容注入 (Content Script UI)，会遮挡视频。
Chrome 新出的 Side Panel API 是终极方案。 它像浏览器的原生侧边栏一样，常驻、不遮挡、体验丝滑。 BibiGPT 现在主要就用这个模式。

总结：

  1. WXT 框架极极大简化了开发配置。
  1. Cookie Sharing 实现无感登录。
  1. Shadow DOM 解决样式冲突。
  1. Side Panel 提供原生级体验

6.2: 桌面端应用 (Desktop App)

Electron 打包出来 500MB 起步？因为塞了个 Chrome。 Tauri 打包只要 10MB。 因为它用系统自带的 WebView，后端用 Rust。
性能炸裂，体积小巧。 非常适合 BibiGPT 这种需要本地处理能力的工具。
Thread: 如何用 Web 技术构建高性能桌面应用

架构解析：Next.js + Rust

前端还是我们熟悉的 Next.js (静态导出)。 后端是 Rust。 它俩通过 IPC (进程间通信) 说话。
"UI 的归 UI，逻辑的归 Rust。" 既保留了 Web 的开发效率，又拥有了 Native 的性能。

Rust Sidecar: 本地 FFmpeg

用户不想上传 2GB 的视频文件？ 没问题，我们在本地处理。
Tauri 允许打包二进制文件 (Sidecar)。 我们在 Rust 里调用本地的 FFmpeg，几秒钟提取出音频。 只传几 MB 的音频给服务器。既省流量，又保护隐私。
notion image

自定义协议：videoproxy://

出于安全，网页不能直接读 file://。 我们需要注册一个自定义协议。
Rust 拦截 videoproxy:// 请求，读取文件流，返给前端。 这样 <video src="videoproxy://..."> 就能流畅播放本地视频了。

系统级能力：全局快捷键

Web 做不到的事，桌面端能做。 比如：全局截图。
注册 Cmd+Shift+B。 用户在任何界面按下，自动截图并发送给 AI 分析。 这种“无处不在”的便利性，才是桌面端的杀手锏。

总结：

  1. Tauri = 小体积 + 高性能。
  1. Rust Sidecar 解决本地重计算 (FFmpeg)。
  1. Custom Protocol 解决文件访问。
  1. Global Shortcut 提供系统级便利。

6.3: 移动端应用 (Mobile App)

以前写 React Native，配环境能配哭。 现在用 @Expo
。基本不用碰 Xcode 和 Android Studio。 再加上 Uniwind (Tailwind v4)，你甚至可以直接写 Tailwind 类名。 感觉就像在写网页一样，但产出的是原生 App。
Thread: 前端工程师如何统治 iOS & Android

Expo Router: 文件即路由

看这个目录结构，是不是很眼熟？ app/index.tsx, app/video/[id].tsx。 这就是 Expo Router。
跟 Next.js 一模一样。 做完 Web 端，你的脑子不需要切换 Context，直接就能写 App。
notion image

逻辑复用，UI 分离

注意：div 不能在手机上跑，要用 View。UI 必须重写。 但是 逻辑 (Logic) 是 100% 复用的。 Hooks, Zod Schemas, tRPC Client... 我们在手机端直接调
http://api.video
.getById.useQuery。 这就是 Monorepo 的威力。

杀手级功能：Share Extension

我在抖音/YouTube App 里，点“分享” -> “BibiGPT”。 App 自动唤起，链接自动填好。
这才是原生体验。 利用 Expo Config Plugins，我们可以轻松配置 iOS/Android 的原生分享菜单。

随时随地：语音笔记

手机最大的优势是麦克风。 我们集成 expo-audio。 随时随地录制灵感，传给 Whisper 转文字，再用 AI 总结。 把手机变成你的第二大脑输入端。

总结：

  1. Expo + Uniwind = 极致开发体验。
  1. Expo Router 降低认知负担。
  1. 逻辑代码复用率 > 90%。
  1. 原生能力 (Share/Audio) 补全场景。
至此，BibiGPT 全平台制霸达成！ Web, Extension, Desktop, Mobile。 一个 Monorepo，一个人，一套逻辑。

6.4: CI/CD 自动化流水线

写代码最爽的是 git push。 最痛苦的是 Push 完还得手动打包、手动上传、手动发版。 让 GitHub Actions 成为你的 24 小时在线运维团队。 不仅是 Web，我们还要自动化发布 Chrome 插件、桌面端 和 移动端应用。
Thread: 一个人活成一支队伍的秘密封装 CI/CD 流水线。

CI: 质量守门员

每次提 Pull Request，机器人会自动运行： Lint + Type Check + Test。 如果这一步挂了，红叉叉会直接打在你的 PR 上。
禁止合入主分支。 这就是质量底线。再也不用担心手滑写错分号导致线上挂了。封装 CI 规则。

CD (Web): Vercel 预览环境

对于 Next.js，Vercel 是绝配。 最杀手级的功能是 Preview Deployment。
每一个 PR 都会自动生成一个独立的临时 URL。 发给 PM 或设计师验收：“你看看这个按钮颜色对不对？” 验收通过再 Merge，瞬间上线生产环境。封装 Vercel 自动化。
notion image

CD (Extension): 自动上架

浏览器插件发布很繁琐：打包 -> 压缩 -> 登录后台 -> 上传 -> 填版本号... 用 chrome-extension-upload Action。
现在，我只要打一个 Git Tag (v1.2.0)。 GitHub Actions 自动帮我把 zip 包扔到 Chrome Web Store。 从此告别手动上传。封装插件自动化。

CD (Desktop): 矩阵构建 (Matrix Build)

这是最硬核的。 要在 Linux 上编译 Windows .exe 和 macOS .dmg？难。 GitHub Actions 提供了免费的 macos-latest 和 windows-latest 机器。
使用 Matrix Strategy，一次 Push，并行构建三个平台的安装包。 Tauri Action 自动把它们上传到 GitHub Releases。封装桌面端自动化。

CD (Mobile): Expo EAS Workflows

以前发布 App 是开发者的噩梦：证书、签名、打包... 现在用 EAS Workflows。
它能与 GitHub Actions 深度集成。 代码一并，EAS 自动在云端完成打包、签名、并分发到 TestFlight 和 Google Play。 发布 App 变得像部署网页一样无感。封装移动端自动化。

Release Please: 自动写 Changelog

版本号怎么管？Changelog 谁来写？ Google 开源的 Release Please。 它会分析你的 Commit Message： feat: -> 升小版本 fix: -> 升补丁版本 自动生成
http://CHANGELOG.md
并提 PR。 你只要点一下 Merge，上述所有发布流程自动触发。封装版本自动化。

总结：

  1. CI 守住代码质量。
  1. Vercel Preview 提升协作效率。
  1. Extension/Desktop/Mobile 全平台自动构建发布。
  1. Release Please 管理版本。
把“发布”从一种仪式变成日常。 现在，你可以放心地去睡觉了。机器人在帮你干活。