docs: 重构文档结构,规范编号并整合冗余内容

## 主要变更

### 文档重构(减少 1199 行,-23%)
- 01-架构设计.md: 503→369 行 (-27%),删除 DDL/配置示例,精简鉴权/存储描述
- 02-接口文档.md: 1313→570 行 (-57%),删除 Go 接口/Orchestrator 实现/配置管理
- 07-成本控制.md: 65→59 行 (-9%),代码块替换为文件引用

### 文档编号规范化
- 08-功能创意.md → 删除(内容整合到 README.md "功能扩展方向")
- 10-Eino框架与编排设计.md → 08-Eino框架与编排设计.md
- 情景切换.md → 09-情景切换.md
- 12-鉴权体系.md → 10-鉴权体系.md
- 13-令牌桶限流.md → 11-令牌桶限流.md

### 交叉引用更新
- 01-架构设计.md: 更新对鉴权体系/令牌桶限流的引用为新编号
- README.md: 更新文档索引表、推荐阅读顺序、新增功能扩展方向

### 删除过时文档
- 09-技术名词解释.md(内容已整合到 03-技术选型.md)
- 10-Eino重构方案.md(历史记录,已完成)
- 11-Eino框架技术文档.md(已合并到 08)
- 情景切换功能完整文档.md(已规范化为 09)

## 重构原则
- 架构文档聚焦系统结构,移除实现细节
- 接口文档保留纯契约,删除内部实现
- 编号连续(01-11),语义清晰
- 通过交叉引用连接相关文档,避免重复
This commit is contained in:
hhs
2026-06-21 14:48:03 +08:00
parent 9e5f691056
commit 032de796c8
17 changed files with 2790 additions and 3989 deletions

View File

@@ -4,7 +4,16 @@
本文档记录项目中各项技术的**选型过程、替代方案对比和决策理由**。技术选型没有"绝对正确",只有"更适合"。
**定位**:本文档记录各项技术选型过程和决策理由
技术选型章节包含关键术语解释,帮助快速理解技术概念
### 后端核心技术栈
| 名词 | 解释 |
|------|------|
| **Go (Golang)** | 高并发后端语言Google 开发,杀手锏是 goroutine——极轻量协程一个程序可轻松开几万个每个只占几 KB 内存,适合管理大量 WebSocket 长连接 |
| **gorilla/websocket** | Go WebSocket 库Go 标准库无内置 WebSocket 支持,此库是社区最成熟的选择,处理了协议握手、帧解析等底层细节 |
| **Viper** | Go 配置管理库,读取 JSON/YAML/TOML 配置,支持环境变量覆盖,方便开发/测试/生产环境用不同配置 |
| **Zap** | Go 结构化日志库Uber 开源,输出 JSON 格式日志,方便工具搜索分析,性能远超标准库 log |
```
技术选型
@@ -34,6 +43,18 @@
## 一、AI 编排框架选型
### 关键术语
| 名词 | 解释 |
|------|------|
| **Eino** | 字节跳动开源的 Go AI 应用开发框架CloudWeGo Eino提供 Graph DAG 编排、组件抽象ChatModel/Tool 等)、流式处理和 Callback AOP 机制 |
| **compose.Graph** | Eino 的 DAG 编排器,声明式有向无环图,节点可以是 Lambda、ChatModel、ToolsNode 等,边定义数据流向 |
| **Lambda** | Graph 中的可组合函数单元四种模式InvokableLambda同步、StreamableLambda流式输出、CollectableLambda流式输入、TransformableLambda双向流式 |
| **StreamReader** | Eino 的流式数据抽象 `schema.StreamReader[T]`,类似 io.Reader 的语义,`Recv()` 读取一帧,`io.EOF` 表示流结束 |
| **Callback** | Eino 的 AOP 机制类似中间件的钩子支持节点生命周期回调OnStart/OnEnd/OnError/OnEndWithStreamOutput |
> 更多 Eino 相关概念详见 [10-Eino框架与编排设计.md](10-Eino框架与编排设计.md)
### 候选方案对比
| 框架 | 语言 | 特点 | CamTalk 适用性 |
@@ -74,6 +95,14 @@ github.com/cloudwego/eino-ext/components/model/openai v0.1.13 # OpenAI 兼容 C
## 二、AI 服务栈选型
### 关键术语
| 名词 | 解释 |
|------|------|
| **多模态 LLM** | 能读文字又能看图片的大语言模型,如 GPT-4oOpenAI、Claude SonnetAnthropic给照片+问题能"看懂"照片再回答 |
| **STT** | Speech-to-Text语音转文字。流式识别延迟可低于 500ms |
| **TTS** | Text-to-Speech文字转语音。支持流式——边生成边读不必等全部生成完 |
### STT语音识别
| 方案 | 延迟 | 成本 | 特点 |
@@ -106,7 +135,15 @@ LLM 通过 Eino 框架的 `eino-ext/components/model/openai` ChatModel 组件接
---
## 、持久化层选型
## 、持久化层选型
### 关键术语
| 名词 | 解释 |
|------|------|
| **PostgreSQL** | 关系型数据库,支持 JSONBJSON 二进制格式可建索引、窗口函数、CTE 等高级特性 |
| **Redis** | 内存 KV 数据库,数据放在内存里,读写微秒级。支持 TTL 过期自动清理 |
| **MVCC** | Multi-Version Concurrency Control多版本并发控制PostgreSQL 用此实现高并发读写而不阻塞 |
### 数据特征分析
@@ -220,7 +257,19 @@ Go Gateway (TieredManager)
---
## 、前端边缘处理层选型
## 、前端边缘处理层选型
### 关键术语
| 名词 | 解释 |
|------|------|
| **React 18** | 组件化 UI 框架Facebook 开源把页面拆成组件搭积木拼装。18 版本支持并发渲染 |
| **TypeScript** | 带类型的 JavaScript在 JS 基础上增加类型声明,编译阶段就能发现类型错误 |
| **Vite** | 前端构建工具,利用浏览器原生 ES Module开发时毫秒级热更新HMR构建产物小 |
| **WebSocket** | 浏览器与服务器的双向通道。HTTP 是"一问一答"WebSocket 像打电话——接通后双方随时互发消息,适合实时对话场景 |
| **ONNX Runtime Web** | 浏览器端 AI 推理引擎,微软定义的通用模型格式 ONNX 的运行引擎,可在浏览器中用 WASM 加速跑轻量模型(如 VAD、关键帧检测零延迟、不耗服务器资源 |
| **VAD** | Voice Activity Detection语音活动检测检测"人有没有在说话"。WebRTC 内置了高效的 VAD 算法 |
| **MediaDevices API** | 浏览器摄像头/麦克风接口,`navigator.mediaDevices.getUserMedia()` 是浏览器音视频采集的唯一标准入口,无需插件 |
### 总览
@@ -270,7 +319,16 @@ vad-web 是"够用且最轻"的平衡点——直接包装浏览器原生 WebRTC
---
## 、认证与用户系统选型
## 、认证与用户系统选型
### 关键术语
| 名词 | 解释 |
|------|------|
| **JWT** | JSON Web Token无状态 token服务端不存 session分布式友好 |
| **HS256** | HMAC-SHA256JWT 对称签名算法,用同一密钥签名和验证 |
| **bcrypt** | 密码哈希算法,自适应 cost factor抗暴力破解 |
| **pgx** | Go 生态性能最优的 PostgreSQL 驱动,原生协议实现,内置连接池 pgxpool |
### 总览