diff --git a/gitpodcast-analysis.md b/gitpodcast-analysis.md
new file mode 100644
index 0000000..376c6ee
--- /dev/null
+++ b/gitpodcast-analysis.md
@@ -0,0 +1,590 @@
+# GitPodcast 项目深度分析报告
+
+> **项目地址**: https://github.com/BandarLabs/gitpodcast
+> **在线服务**: https://gitpodcast.com
+> **许可证**: MIT
+> **分析日期**: 2026-05-26
+
+---
+
+## 一、项目概述
+
+GitPodcast 是一个能将任意 GitHub 仓库在数秒内转化为一段双人对话式播客音频的 Web 应用。用户只需将 GitHub URL 中的 `hub` 替换为 `podcast`（如 `github.com/user/repo` → `gitpodcast.com/user/repo`）即可直接访问对应的播客。
+
+### 核心能力
+- **即时播客生成**：输入 GitHub 仓库 URL，自动生成 5~20 分钟的双人对话播客
+- **双模式输出**：Basic（~5 分钟）和 In-Depth（~10+ 分钟，含中场休息）
+- **幻灯片生成**：同步生成 Marp 格式的 Markdown 幻灯片，支持 React Flow 渲染的幻灯片浏览
+- **字幕同步**：基于 WebVTT 格式的实时字幕与音频同步播放
+- **缓存机制**：PostgreSQL 缓存生成结果，避免重复调用 LLM/TTS
+- **用户认证**：Clerk 登录后可解锁 In-Depth 模式
+- **URL 快捷方式**：`hub` → `podcast` 的 URL 替换快捷入口
+
+---
+
+## 二、整体架构
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                         Frontend (Next.js 15)                        │
+│  ┌──────────┐  ┌──────────────┐  ┌────────────┐  ┌──────────────┐  │
+│  │ 首页/入口 │  │ /[user]/[repo]│  │ ReactFlow  │  │  音频播放器   │  │
+│  │ (MainCard)│  │   页面       │  │ 幻灯片视图  │  │ 字幕同步显示  │  │
+│  └──────────┘  └──────┬───────┘  └────────────┘  └──────────────┘  │
+│                        │ fetch (REST)                                │
+│  ┌─────────────────────┴────────────────────────────────────────┐   │
+│  │              Server Actions (cache.ts / repo.ts / github.ts)  │   │
+│  │              Drizzle ORM → PostgreSQL                         │   │
+│  └──────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────┬────────────────────────────────────────┘
+                              │ HTTP POST
+                              ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                    Backend (FastAPI, Python 3.12, Docker)            │
+│                                                                      │
+│  ┌───────────┐   ┌──────────────┐   ┌───────────────┐              │
+│  │  Routers  │   │   Services   │   │  Core Utils   │              │
+│  │ generate/ │──▶│ github_svc   │   │ slowapi limiter│              │
+│  │ modify/   │   │ claude_svc   │   │ JWT/Clerk auth │              │
+│  └───────────┘   │ openai_svc   │   └───────────────┘              │
+│                  │ gemini_svc   │                                    │
+│                  │ speech_svc   │──▶ Azure Speech Batch Synthesis   │
+│                  │ slide_svc    │                                    │
+│                  └──────────────┘                                    │
+└──────────────────────────────────────────────────────────────────────┘
+         │                    │                    │
+         ▼                    ▼                    ▼
+   GitHub API          Azure OpenAI /         Azure Cognitive
+   (file tree,      Gemini Flash /          Services Speech
+    README,          Claude 3.5 Sonnet       (TTS Batch)
+    file content)
+```
+
+---
+
+## 三、技术栈详解
+
+### 3.1 前端 (Frontend)
+
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| **Next.js** | ^15.2.3 | React 全栈框架 (App Router) |
+| **TypeScript** | ^5.5.3 | 类型安全 |
+| **React** | ^18.3.1 | UI 库 |
+| **Tailwind CSS** | ^3.4.3 | 原子化 CSS |
+| **ShadCN UI** (Radix) | - | 基于 Radix UI 的组件库 (Dialog/Label/Progress/Radio/Tooltip/Card/Button) |
+| **@xyflow/react** | ^12.4.4 | 幻灯片画布渲染 (React Flow) |
+| **Mermaid.js** | ^11.4.1 | 系统架构图渲染 |
+| **Reveal.js** | ^5.1.0 | 幻灯片展示框架 |
+| **WaveSurfer.js** | ^1.3.4 | 音频波形可视化 |
+| **AudioMotion-Analyzer** | ^4.5.0 | 音频频谱分析 |
+| **Highlight.js** | ^11.11.1 | 代码高亮 |
+| **React Markdown** | ^10.1.0 | Markdown 渲染 |
+| **Remark/Rehype** | - | Markdown 处理管线 (GFM, parse, highlight, stringify) |
+| **PostHog** | ^1.203.1 | 前端行为分析 |
+| **@clerk/nextjs** | ^6.13.0 | 用户认证 |
+| **Zod** | ^3.23.3 | 运行时类型校验 (配合 @t3-oss/env-nextjs) |
+| **Geist** | ^1.3.0 | 字体 |
+| **Lucide React** | ^0.468.0 | 图标库 |
+
+**前端初始化框架**: T3 Stack (create-t3-app v7.38.1)，预配置了 Tailwind + Drizzle + tRPC (本项目未使用 tRPC) + Next.js Auth。
+
+### 3.2 后端 (Backend)
+
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| **FastAPI** | 0.115.6 | Python Web 框架 |
+| **Python** | 3.12 | 后端运行时 |
+| **Uvicorn** | 0.34.0 | ASGI 服务器 |
+| **SlowAPI** | 0.1.9 | API 限流 (基于 IP) |
+| **Pydantic** | 2.10.3 | 请求/响应数据验证 |
+| **PyJWT** | 2.10.1 | GitHub App JWT 认证 |
+| **Requests** | 2.32.3 | HTTP 客户端 |
+| **PyDub** | - | 音频处理 (MP3 时长检测) |
+| **Docker** | Python 3.12-slim | 容器化部署 |
+| **FFmpeg** | (系统依赖) | 音频编解码支持 |
+| **api-analytics** | 1.2.5 | API 使用量分析 |
+| **clerk-backend-api** | - | Clerk 后端认证校验 |
+
+### 3.3 数据库与 ORM
+
+| 技术 | 版本 | 用途 |
+|------|------|------|
+| **PostgreSQL** | - | 主数据库 (Neon Serverless 或本地 Docker) |
+| **Drizzle ORM** | ^0.33.0 | 类型安全 ORM |
+| **Drizzle Kit** | ^0.24.0 | 数据库迁移工具 |
+| **@neondatabase/serverless** | ^0.10.4 | Neon 无服务器 PostgreSQL 驱动 |
+| **Postgres.js** | ^3.4.4 | PostgreSQL 驱动 (本地开发) |
+
+**数据库表结构** (表前缀 `gitdiagram_`，继承自 GitDiagram 项目):
+
+1. **`diagram_cache`**: 缓存 Mermaid 图表代码和文本解释
+   - PK: `(username, repo)`
+   - 字段: `diagram`, `explanation`, `createdAt`, `updatedAt`
+
+2. **`audio_blob_storage`**: 缓存生成的音频和字幕
+   - PK: `(username, repo)` — repo 字段实际存 `reponame|audio_length`
+   - 字段: `audioBase64`, `duration`, `format`, `webVtt`, `createdAt`, `updatedAt`
+
+### 3.4 AI 与大模型服务
+
+| 服务 | 模型 | 角色 |
+|------|------|------|
+| **Azure OpenAI** | GPT-4o | 关键文件选择 + SSML 播客脚本生成 (主力) |
+| **Gemini** | Flash 2.0 Experimental | SSML 生成的免费备选方案 (15 次/分钟) |
+| **Anthropic Claude** | 3.5 Sonnet | Mermaid 图表生成/修改 + Token 计数 (遗留自 GitDiagram) |
+| **Azure Speech** | Batch Synthesis API | SSML → MP3 音频合成 (TTS) |
+
+**TTS 语音角色**:
+- 主持人 (Host): `en-US-AvaMultilingualNeural`
+- 嘉宾 (Guest): `en-US-DustinMultilingualNeural`
+
+### 3.5 部署与基础设施
+
+| 组件 | 方案 |
+|------|------|
+| **前端托管** | Vercel (Next.js SSR) |
+| **后端托管** | AWS EC2 (Docker + Nginx) |
+| **数据库** | Neon Serverless PostgreSQL / 本地 Docker PostgreSQL |
+| **CDN/代理** | Nginx (后端反向代理) |
+| **CI/CD** | GitHub Actions |
+| **监控** | PostHog (前端) + api-analytics (后端) |
+
+---
+
+## 四、核心数据流程
+
+### 4.1 播客生成流程
+
+```
+用户输入 GitHub URL
+        │
+        ▼
+  ┌─────────────────┐
+  │ 1. 解析 URL      │  提取 username/repo
+  └────────┬────────┘
+           ▼
+  ┌─────────────────┐
+  │ 2. 获取仓库数据   │  GitHubService
+  │                  │  ├─ get_default_branch()  → 默认分支
+  │                  │  ├─ get_github_file_paths_as_list()  → 文件树 (排除 node_modules 等)
+  │                  │  ├─ get_github_readme()  → README
+  │                  │  └─ get_github_file_content()  → 关键文件内容 (OpenAI 选出 ≤10 个文件，每个截断 50KB)
+  └────────┬────────┘
+           │  LRU Cache (5 分钟)
+           ▼
+  ┌───────────────────────────────────┐
+  │ 3. 生成 SSML 播客脚本             │
+  │                                   │
+  │  Short 模式:                      │
+  │    单次 LLM 调用                  │
+  │    输入: file_tree + README + 关键文件 │
+  │    Prompt: PODCAST_SSML_PROMPT    │
+  │                                   │
+  │  Long 模式:                       │
+  │    两个并发 LLM 调用 (ThreadPool)  │
+  │    ├─ Call A: tree + README       │  → PODCAST_SSML_PROMPT_BEFORE_BREAK
+  │    └─ Call B: 关键文件内容         │  → PODCAST_SSML_PROMPT_AFTER_BREAK
+  │    合并后包裹在 <speak> 标签内     │
+  └────────┬──────────────────────────┘
+           ▼
+  ┌─────────────────────────────────┐
+  │ 4. SSML 校验与清洗              │
+  │   ├─ XML 解析验证 (ET.fromstring)│
+  │   ├─ 过滤 ``` 代码块标记        │
+  │   ├─ sanitize: 移除非法标签     │
+  │   └─ 最多 3 次重试              │
+  └────────┬────────────────────────┘
+           ▼
+  ┌─────────────────────────────────┐
+  │ 5. TTS 语音合成                 │  Azure Speech Batch Synthesis API
+  │   ├─ PUT 请求提交 SSML          │
+  │   ├─ 轮询合成状态 (Succeeded)   │
+  │   ├─ 下载 ZIP → 提取音频        │
+  │   └─ 最多 3 次重试              │
+  └────────┬────────────────────────┘
+           ▼
+  ┌─────────────────────────────────┐
+  │ 6. 生成 WebVTT 字幕             │
+  │   ├─ 从 SSML 提取纯文本         │
+  │   ├─ 按 WPM 计算每行时间戳      │
+  │   └─ 输出 WebVTT 格式           │
+  └────────┬────────────────────────┘
+           ▼
+  ┌─────────────────────────────────┐
+  │ 7. 响应返回与缓存               │
+  │   ├─ 音频: MP3 bytes (Response) │
+  │   ├─ 字幕: Base64 编码放 X-VTT-Content Header │
+  │   ├─ 音频: Base64 存入 PostgreSQL│
+  │   └─ WebVTT: 存入 PostgreSQL    │
+  └─────────────────────────────────┘
+```
+
+### 4.2 SSML Prompt 设计
+
+播客采用双人对话形式 (Host + Guest)，核心 prompt 策略：
+
+| Prompt | 用途 | 覆盖内容 |
+|--------|------|---------|
+| `PODCAST_SSML_PROMPT` | Short 模式单次生成 | 项目概述 + 架构 + 技术特色 |
+| `PODCAST_SSML_PROMPT_BEFORE_BREAK` | Long 模式前半段 | 同上 + "中场休息前"提示 |
+| `PODCAST_SSML_PROMPT_AFTER_BREAK` | Long 模式后半段 | 重要代码 + 优化 + 调用关系 + "中场休息后"提示 |
+| `SLIDE_PROMPT` | 幻灯片生成 | Marp Markdown 格式的技术幻灯片 |
+
+**Prompt 工程细节**:
+- 要求生成 ≥200 个 `<voice>` 标签 per 角色
+- 添加自然填充词 (`um`, `uh`) 增强真实感
+- 要求混合长短回答，避免单调
+- 目标时长 20+ 分钟
+- 使用 `<break>` 标签模拟自然停顿
+- 讨论架构模式、设计原则、组件关系、技术亮点
+
+### 4.3 关键文件选择流程
+
+```
+File Tree (完整)
+    │
+    ▼
+OpenAI GPT-4o (Structured Output)
+    │  System: "选出最多 10 个最重要的文件路径"
+    │  Response Format: Pydantic FileListFormat
+    │
+    ▼
+[file1.py, file2.ts, ..., file_n.py]  (≤10 个)
+    │
+    ▼ 逐个获取内容 (base64 解码)
+    │
+    ▼
+每个文件截断到 50,000 字符
+    │
+    ▼
+拼接为: "FPATH: xxx \n CONTENT: ..."
+```
+
+---
+
+## 五、关键服务模块详解
+
+### 5.1 `github_service.py` — GitHub API 交互
+
+- **认证优先级**: GitHub App (JWT + Installation Token) > GitHub PAT > 无认证 (60 req/hr)
+- **JWT 生成**: RS256 签名，10 分钟有效期
+- **文件树获取**: 使用 Git Trees API (`recursive=1`)，自动过滤 `node_modules/`, `.min.`, 图片, 锁文件等
+- **分支回退**: 先查 default_branch，失败后依次尝试 `main` → `master`
+- **文件内容**: Contents API 返回 Base64 编码，客户端解码
+
+### 5.2 `speech_service.py` — Azure 语音合成
+
+- **合成方式**: 使用 Azure Batch Synthesis API (`/texttospeech/batchsyntheses/`)，而非实时 SDK
+- **音频格式**: `audio-16khz-32kbitrate-mono-mp3`
+- **轮询机制**: 每 2 秒轮询一次合成状态，支持 `Running` → `Succeeded` → 下载 ZIP
+- **ZIP 提取**: 下载结果中的 `.wav`/`.mp3` 文件
+- **字幕生成** (`ssml_to_webvtt`):
+  - 从 SSML 提取纯文本 (去除 `<speak>`, `<voice>`, `<break>` 等标签)
+  - 基于 WPM (words per minute) 动态计算每段字幕时长
+  - 自动换行 (max 45 字符) 和分词 (max 30 词/cue)
+  - 输出标准 WebVTT 格式
+- **SSML 清洗**: XML 解析验证 + 移除非 `<voice>` 子元素 + 去除 Markdown 代码块标记
+
+### 5.3 `openai_service.py` — Azure OpenAI 调用
+
+- **模型**: Azure OpenAI GPT-4o (可通过 `AZURE_OPENAI_MODEL_NAME` 配置)
+- **关键文件选择**: 使用 Structured Output (`response_format=FileListFormat`) 确保返回格式化的文件列表
+- **API 版本**: `2024-10-21`
+
+### 5.4 `gemini_service.py` — Gemini Flash 备选
+
+- **模型**: `gemini-2.0-flash-exp`
+- **流程**: 上传文件 → 等待处理 → Chat Session → 生成 SSML
+- **参数**: temperature=1, top_p=0.95, top_k=40, max_output_tokens=8192
+
+### 5.5 `claude_service.py` — Claude 服务 (遗留)
+
+- **用途**: Mermaid 图表的修改功能 + Token 计数
+- **模型**: `claude-3-5-sonnet-latest`
+- **注意**: 该服务继承自 GitDiagram 项目，在本项目中图表生成功能已基本弃用
+
+---
+
+## 六、前端架构
+
+### 6.1 页面路由
+
+```
+/                          → 首页 (page.tsx): MainCard + Hero
+/[username]/[repo]/        → 仓库播客页: 核心交互页面
+```
+
+### 6.2 核心组件层级
+
+```
+app/layout.tsx (PostHogProvider + GlobalStateProvider + ClerkProvider)
+├── app/page.tsx (首页)
+│   ├── Hero (品牌标题)
+│   ├── MainCard (URL 输入 + 模式选择 + 示例仓库)
+│   └── ProductHuntEmbed
+│
+└── app/[username]/[repo]/page.tsx (仓库页面)
+    ├── MainCard (修改/重新生成/自定义)
+    ├── <audio> (音频播放器, controls)
+    ├── Card (实时字幕显示)
+    ├── Button (幻灯片自动播放切换)
+    └── ReactFlow (幻灯片画布)
+        └── Slide × N (自定义 ReactFlow 节点)
+```
+
+### 6.3 状态管理
+
+- **全局状态**: React Context (`GlobalStateContext`)
+  - `audioLength`: `short` / `long`
+  - `anotherVariable`: 用于触发页面刷新的随机数
+- **本地状态**: `useDiagram` 自定义 Hook 管理全部业务状态
+  - diagram, error, loading, audioUrl, subtitleUrl, slides, etc.
+- **认证**: `@clerk/nextjs` 提供 `useAuth()` / `getToken()`
+
+### 6.4 幻灯片渲染
+
+- 幻灯片以 `---` 分隔的 Marp Markdown 格式生成
+- 每个幻灯片渲染为 React Flow 的自定义 `slide` 节点
+- 支持键盘方向键导航和自动播放 (5 秒间隔)
+- 使用 BFS 遍历在 2D 平面上布局幻灯片节点
+
+---
+
+## 七、API 端点
+
+### 后端 API (`:8000`)
+
+| 方法 | 路径 | 功能 | 限流 |
+|------|------|------|------|
+| `POST` | `/generate` | 生成播客音频 + 字幕 | 无 (临时关闭) |
+| `POST` | `/generate/slide` | 生成 Marp 幻灯片 | - |
+| `POST` | `/generate/cost` | 估算生成成本 | - |
+| `POST` | `/modify` | 修改已有图表 | 2 次/分钟, 10 次/天 |
+| `GET` | `/` | 健康检查 | 100 次/天 |
+
+### 请求体格式
+
+```json
+// /generate
+{
+  "username": "string",
+  "repo": "string",
+  "instructions": "string",      // 可选，自定义指令 (≤1000 字符)
+  "api_key": "string | null",    // 可选，自定义 API Key
+  "audio": true,                 // 是否生成音频 (区别于仅图表)
+  "audio_length": "short|long"   // 播客时长
+}
+```
+
+### 响应格式
+
+| 场景 | 响应 |
+|------|------|
+| `audio=false` | JSON: `{"diagram": "Mermaid code", "explanation": "..."}` |
+| `audio=true` | MP3 流 (`Content-Type: audio/mpeg`) + `X-VTT-Content` Header (Base64 编码 WebVTT) |
+| `/generate/slide` | JSON: `{"slide_markdown": "..."}` |
+| 错误 | JSON: `{"error": "..."}` |
+
+---
+
+## 八、认证与授权
+
+- **前端认证**: Clerk (`@clerk/nextjs`)
+  - `SignInButton` 组件控制 In-Depth 模式访问
+  - Server-side middleware (`clerkMiddleware`) 保护 `/generate` 路由
+- **后端认证**: `clerk-backend-api` 校验请求
+  - `is_signed_in()` 函数验证 JWT
+  - Long 模式需要登录才能访问
+- **GitHub 认证**: 三级回退
+  1. GitHub App (Client ID + Private Key + Installation ID) — 5000 req/hr
+  2. GitHub PAT — 5000 req/hr
+  3. 无认证 — 60 req/hr
+
+---
+
+## 九、缓存策略
+
+### 9.1 内存缓存 (LRU)
+
+```python
+@lru_cache(maxsize=100)
+def get_cached_github_data(username, repo):
+    # 缓存 GitHub API 结果 (file tree, README, file content)
+    # 避免 cost 和 generate 的重复 API 调用
+```
+
+### 9.2 数据库缓存 (PostgreSQL)
+
+- **图表缓存**: `diagram_cache` 表，upsert on conflict
+- **音频缓存**: `audio_blob_storage` 表，Base64 编码存储
+- **缓存命中策略**: 90% 概率先查缓存 (`Math.random() < 0.90`)
+- **缓存键**: `(username, repo + "|" + audio_length)` 用于区分不同时长
+
+---
+
+## 十、项目目录结构
+
+```
+gitpodcast/
+├── backend/                         # Python 后端
+│   ├── app/
+│   │   ├── main.py                  # FastAPI 入口，CORS/中间件/路由注册
+│   │   ├── prompts.py               # 全部 LLM Prompt 模板
+│   │   ├── core/
+│   │   │   └── limiter.py           # SlowAPI 限流器
+│   │   ├── routers/
+│   │   │   ├── generate.py          # /generate 路由 (核心接口)
+│   │   │   └── modify.py            # /modify 路由
+│   │   └── services/
+│   │       ├── github_service.py    # GitHub API 交互
+│   │       ├── openai_service.py    # Azure OpenAI (SSML 生成 + 文件选择)
+│   │       ├── gemini_service.py    # Gemini Flash (备选 SSML)
+│   │       ├── claude_service.py    # Claude (图表修改 + Token 计数)
+│   │       ├── speech_service.py    # Azure Speech TTS + WebVTT
+│   │       └── slide_service.py     # 幻灯片生成
+│   ├── nginx/                       # Nginx 配置
+│   ├── Dockerfile                   # Python 3.12-slim + FFmpeg
+│   ├── entrypoint.sh                # 启动脚本
+│   ├── deploy.sh                    # 部署脚本
+│   └── requirements.txt             # Python 依赖
+│
+├── src/                             # Next.js 前端
+│   ├── app/
+│   │   ├── page.tsx                 # 首页
+│   │   ├── layout.tsx               # 根布局
+│   │   ├── providers.tsx            # PostHog + 全局状态 Provider
+│   │   ├── [username]/[repo]/
+│   │   │   └── page.tsx             # 仓库播客页 (核心页面)
+│   │   └── _actions/
+│   │       ├── cache.ts             # Server Actions: 数据库缓存读写
+│   │       ├── github.ts            # GitHub 相关 Server Actions
+│   │       └── repo.ts              # 仓库信息相关 Actions
+│   ├── components/
+│   │   ├── main-card.tsx            # URL 输入 + 模式选择
+│   │   ├── hero.tsx                 # 首页标题
+│   │   ├── loading.tsx              # 加载动画
+│   │   ├── slide-paginator.tsx      # 幻灯片分页器
+│   │   ├── mermaid-diagram.tsx      # Mermaid 图表组件
+│   │   ├── customization-dropdown.tsx # 自定义选项下拉
+│   │   ├── api-key-dialog.tsx       # API Key 输入对话框
+│   │   └── ui/                      # ShadCN UI 组件
+│   ├── hooks/
+│   │   └── useDiagram.ts            # 核心业务逻辑 Hook
+│   ├── lib/
+│   │   ├── fetch-backend.ts         # 后端 API 调用封装
+│   │   ├── exampleRepos.ts          # 示例仓库列表
+│   │   └── utils.ts                 # 工具函数 (WebVTT 解析等)
+│   ├── server/db/
+│   │   ├── index.ts                 # Drizzle ORM 配置
+│   │   └── schema.ts                # 数据库 Schema
+│   ├── styles/
+│   │   └── globals.css              # 全局样式
+│   └── env.js                       # 环境变量 Schema (Zod)
+│
+├── public/                          # 静态资源
+├── docs/                            # 文档图片
+├── .github/                         # GitHub Actions CI/CD
+│
+├── package.json                     # 前端依赖 (pnpm)
+├── pnpm-lock.yaml                   # 锁文件
+├── docker-compose.yml               # 后端 Docker Compose
+├── drizzle.config.ts                # Drizzle 迁移配置
+├── middleware.ts                    # Next.js 中间件 (Clerk)
+├── next.config.js                   # Next.js 配置
+├── tailwind.config.ts               # Tailwind 配置
+├── tsconfig.json                    # TypeScript 配置
+├── postcss.config.js                # PostCSS 配置
+├── components.json                  # ShadCN 配置
+├── .env.example                     # 环境变量模板
+└── start-database.sh                # 本地 PostgreSQL 启动脚本
+```
+
+---
+
+## 十一、环境变量一览
+
+| 变量 | 用途 | 必需 |
+|------|------|------|
+| `SPEECH_KEY` | Azure Speech API Key | 是 (TTS) |
+| `SPEECH_REGION` | Azure Speech 区域 | 是 (TTS) |
+| `GEMINI_API_KEY` | Google Gemini API Key | 可选 |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API Key | 是 (主力 LLM) |
+| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI Endpoint URL | 是 |
+| `AZURE_OPENAI_MODEL_NAME` | 模型名 (默认 gpt-4o) | 否 |
+| `ANTHROPIC_API_KEY` | Anthropic Claude API Key | 可选 |
+| `POSTGRES_URL` | PostgreSQL 连接串 | 是 |
+| `NEXT_PUBLIC_API_DEV_URL` | 后端 API URL (开发用) | 否 |
+| `GITHUB_PAT` | GitHub Personal Access Token | 可选 (提升限流) |
+| `GITHUB_CLIENT_ID` | GitHub App Client ID | 可选 |
+| `GITHUB_PRIVATE_KEY` | GitHub App Private Key | 可选 |
+| `GITHUB_INSTALLATION_ID` | GitHub App Installation ID | 可选 |
+| `CLERK_SECRET_KEY` | Clerk Secret Key | 是 (Long 模式) |
+| `API_ANALYTICS_KEY` | api-analytics Key | 可选 |
+| `NEXT_PUBLIC_POSTHOG_KEY` | PostHog API Key | 可选 |
+| `NEXT_PUBLIC_POSTHOG_HOST` | PostHog Host | 可选 |
+
+---
+
+## 十二、项目特点与设计亮点
+
+### 12.1 架构亮点
+
+1. **多 LLM 协作**: OpenAI (文件选择 + 主力 SSML) + Gemini (免费备选) + Claude (图表修改 + Token 计数)，三者各司其职
+2. **并发生成**: Long 模式使用 `ThreadPoolExecutor` 并发调用 LLM，将前半段和后半段播客并行生成后合并
+3. **双层缓存**: LRU 内存缓存 (GitHub 数据) + PostgreSQL 持久化缓存 (音频/图表/字幕)，大幅降低重复请求成本
+4. **SSML 全链路**: 从 LLM 输出到 TTS 合成，包含校验 → 清洗 → 重试的完整容错链
+
+### 12.2 Prompt 工程
+
+- **双人对话格式**: Host (Ava) + Guest (Dustin) 模拟真实播客对话
+- **自然度优化**: 要求添加填充词 (`um`/`uh`)、混合长短回答、使用 `<break>` 停顿
+- **内容深度**: 前半段讨论架构概览，后半段深入代码细节和实现原理
+- **Token 控制**: 长播客拆分为两个并发 prompt，各自限定 100K tokens
+
+### 12.3 工程实践
+
+- **类型安全**: 前端 TypeScript + Zod schema，后端 Pydantic models
+- **结构化输出**: OpenAI Structured Output (`response_format`) 确保文件列表格式
+- **渐进式降级**: 无 GitHub 凭证 → 无认证请求 (60/hr)；无 Azure → 返回错误提示
+- **成本估算**: 内置 `/generate/cost` 端点，基于 Claude Token 计数预估费用
+
+### 12.4 用户体验
+
+- **URL 魔术**: `github.com` → `gitpodcast.com` 一键转换
+- **音频字幕同步**: WebVTT 字幕与音频精确同步，基于 WPM 动态计算时间戳
+- **幻灯片浏览**: React Flow 画布 + 键盘导航 + 自动播放
+- **示例仓库**: 提供一键体验的示例仓库 (FastAPI, Streamlit, Flask 等)
+
+---
+
+## 十三、与 GitDiagram 的关系
+
+GitPodcast 是从 [GitDiagram](https://gitdiagram.com) 项目 Fork 演变而来（致谢部分明确提到），两者共享大量代码：
+
+| 共享部分 | 差异 |
+|---------|------|
+| FastAPI 后端骨架 | GitPodcast 新增 audio/slide 生成路由 |
+| GitHub Service | 相同 |
+| Claude Service (图表修改) | GitPodcast 新增 OpenAI/Gemini/Speech Service |
+| Mermaid 图表 Prompt | GitPodcast 新增 SSML/Slide Prompt |
+| Drizzle Schema (`diagram_cache`) | GitPodcast 新增 `audio_blob_storage` 表 |
+| 前端 ShadCN 组件 | GitPodcast 新增音频播放器/幻灯片视图 |
+| 数据库表前缀 `gitdiagram_` | 保留了原始前缀 |
+
+---
+
+## 十四、局限性与改进方向
+
+1. **成本依赖 Azure**: 主力 LLM (GPT-4o) 和 TTS (Azure Speech) 都依赖 Azure，成本较高
+2. **SSML 质量不稳定**: LLM 可能生成无效 SSML，需最多 3 次重试
+3. **缓存无 TTL**: PostgreSQL 缓存无过期机制，旧数据可能一直保留
+4. **单点故障**: 音频合成失败直接返回错误，无备选 TTS 方案
+5. **遗留代码**: Claude Service + Mermaid 相关代码来自 GitDiagram，功能已基本弃用但未清理
+6. **限流临时关闭**: 生产环境的 rate limit 被注释 (`# TEMP: disable rate limit for growth`)
+
+---
+
+## 十五、总结
+
+GitPodcast 是一个架构清晰、Prompt 设计用心的 AI 播客生成工具。它的核心价值在于将 **GitHub 仓库理解** + **LLM 叙事生成** + **TTS 语音合成** 三个能力串联为一条完整的管线，同时通过多层缓存和多 LLM 协作来优化成本和体验。项目从 GitDiagram 演变而来，保留了成熟的 Git 交互和图表组件，在此基础上叠加了音频/幻灯片/字幕生成的新能力，是一个典型的 AI-native 全栈应用。