XEngineers/CamTalk
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
develop
CamTalk/CLAUDE.md

129 lines
7.6 KiB
Markdown
Raw Permalink Normal View History

docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
# CLAUDE.md
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
CamTalk — 多模态实时 AI 视觉对话助手（摄像头 + 麦克风 + 视觉 + 语音 AI）
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
> **文档优先原则：** 开发前先读 `docs/` 设计文档，以文档为准；若代码与文档不一致，优先更新文档（尤其接口文档）。详细设计见 `docs/01-13` 系列文档。**注意**：`docs/Eino/` 框架文档内容庞大（~75 个文件），仅在需要了解 Eino Graph/节点/Callback 等框架细节时才读取。
docs: 提交信息改用中文描述，强化文档优先原则
2026-06-12 16:51:28 +08:00
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
## 常用命令
```bash
# === 前端（frontend/ 目录）===
npm run dev # Vite 开发服务器（http://localhost:5173，代理 /ws 和 /api 到 :8080）
npm run build # 生产构建（tsc -b && vite build，输出到 dist/）
npm run lint # ESLint 代码检查
npm run preview # 预览生产构建
# === 后端（backend/ 目录）===
go run ./cmd/server # 启动服务（监听 :8080，启动时自动执行数据库迁移）
golangci-lint run # Go 代码检查
# 后端测试
go test ./... # 单元测试
go test -tags=integration ./... # 集成测试（需要 PostgreSQL）
go test -v -run TestXxx ./path/ # 运行单个测试
# === Docker 部署 ===
./deploy.sh build # 构建 Docker 镜像
./deploy.sh up # 启动服务（4 容器：frontend/backend/postgres/redis）
./deploy.sh down # 停止服务
./deploy.sh logs # 查看日志（可加服务名：./deploy.sh logs backend）
./deploy.sh status # 查看服务状态
```
docs: 扁平化目录结构，优化文档为 Coding Agent 可读格式 - 移除 Obsidian 特有语法（callout、wikilinks、YAML frontmatter） - 目录结构从 3 层嵌套扁平化为编号文件（01~09） - 新增 docs/README.md 文档索引与推荐阅读顺序 - 精简冗余解释，保留所有代码块和实现参考 - CLAUDE.md 全面中文化
2026-06-12 17:08:20 +08:00
## 架构
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
三层系统：前端（React + Vite）→ Go 网关（Gin + WebSocket + Eino Graph AI 编排）→ AI 服务（DashScope LLM, MiMo STT/TTS）
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
**AI 编排流水线**（Eino Graph 7 节点 DAG）：`STT → History → ChatModel → Msg2Str → Splitter → TTS → Done`。LLM token 通过 Callback 实时推送，TTS 逐句并行合成。
feat: 集成限流器到服务 - main.go 初始化限流器（根据 Redis 可用性选择内存/Redis 实现） - WebSocket handler 添加 query 消息限流（按 userID） - Auth API 添加登录/注册限流（按 IP） - refresh 和 logout 不限流（避免影响正常用户操作） - 修复所有测试（传递 nil limiter 参数） - 所有测试通过（包括 ws 和 api 集成测试）
2026-06-21 00:00:24 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
**会话存储**（TieredManager）：L1 Memory → L2 Redis → L3 PostgreSQL 三级存储，30 分钟 TTL，Redis 故障自动降级。
feat: 集成限流器到服务 - main.go 初始化限流器（根据 Redis 可用性选择内存/Redis 实现） - WebSocket handler 添加 query 消息限流（按 userID） - Auth API 添加登录/注册限流（按 IP） - refresh 和 logout 不限流（避免影响正常用户操作） - 修复所有测试（传递 nil limiter 参数） - 所有测试通过（包括 ws 和 api 集成测试）
2026-06-21 00:00:24 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
**鉴权**：JWT 双 token 轮转（Access 120min + Refresh 7d），重放攻击检测（DB hash 校验），Redis 缓存装饰器。
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
docs: 扁平化目录结构，优化文档为 Coding Agent 可读格式 - 移除 Obsidian 特有语法（callout、wikilinks、YAML frontmatter） - 目录结构从 3 层嵌套扁平化为编号文件（01~09） - 新增 docs/README.md 文档索引与推荐阅读顺序 - 精简冗余解释，保留所有代码块和实现参考 - CLAUDE.md 全面中文化
2026-06-12 17:08:20 +08:00
## 技术栈
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
前端：React 18 + TypeScript + Vite，VAD（@ricky0123/vad-web），ONNX Runtime，国际化（zh-CN / en-US / ja-JP）
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
后端：Go 1.25+, Gin, WebSocket, Viper, Zap, CloudWeGo Eino Graph
AI：DashScope qwen3-vl-plus, MiMo ASR/TTS（可切换 Deepgram/OpenAI TTS）
存储：PostgreSQL 15 + Redis 7
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
CI/CD：Gitea Actions（`.gitea/workflows/deploy.yml`），push main/v2 自动构建部署到自建 aliyun runner
前端测试：**暂无**（package.json 无 test 脚本，无测试框架配置）
feat: 集成限流器到服务 - main.go 初始化限流器（根据 Redis 可用性选择内存/Redis 实现） - WebSocket handler 添加 query 消息限流（按 userID） - Auth API 添加登录/注册限流（按 IP） - refresh 和 logout 不限流（避免影响正常用户操作） - 修复所有测试（传递 nil limiter 参数） - 所有测试通过（包括 ws 和 api 集成测试）
2026-06-21 00:00:24 +08:00
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
## 配置体系
feat: 集成限流器到服务 - main.go 初始化限流器（根据 Redis 可用性选择内存/Redis 实现） - WebSocket handler 添加 query 消息限流（按 userID） - Auth API 添加登录/注册限流（按 IP） - refresh 和 logout 不限流（避免影响正常用户操作） - 修复所有测试（传递 nil limiter 参数） - 所有测试通过（包括 ws 和 api 集成测试）
2026-06-21 00:00:24 +08:00
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
配置优先级：**环境变量 > `config.{APP_ENV}.yaml` > `config.yaml` > 代码默认值**
配置文件位于 `backend/config/`：
- `config.yaml` — 基础配置（dev 默认值）
- `config.dev.yaml` — 开发环境覆盖（可选）
- `config.prod.yaml` — 生产环境覆盖（可选）
环境切换：`APP_ENV=dev|prod`（dev 默认，prod 启用限流 + 严格 CORS + Release 模式）
敏感信息（API Key、JWT Secret、数据库密码）**只能通过环境变量或 `.env` 文件注入**，不写入 YAML 配置文件。核心环境变量（参考 `backend/.env.example`）：
| 变量 | 说明 |
|------|------|
| `CAMTALK_AI_LLM_API_KEY` | LLM API Key（DashScope） |
| `CAMTALK_AI_STT_API_KEY` | STT API Key（MiMo/Deepgram） |
| `CAMTALK_AI_TTS_API_KEY` | TTS API Key（MiMo/OpenAI） |
| `CAMTALK_AUTH_JWT_SECRET` | JWT 签名密钥 |
| `CAMTALK_STORAGE_DSN` | PostgreSQL 连接字符串 |
| `CAMTALK_REDIS_ADDR` | Redis 地址 |
| `CAMTALK_REDIS_PASSWORD` | Redis 密码 |
## 数据库迁移
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
迁移 SQL 文件位于 `backend/migrations/`（`001_*.up.sql` 等），通过 Go `//go:embed` 嵌入二进制（见 `backend/migrations/embed.go`）。应用启动时**自动执行**未应用的迁移，无需手动运行迁移命令。迁移通过 `schema_migrations` 表追踪执行状态。
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
回滚脚本为同目录下的 `*.down.sql` 文件，需手动执行。
feat: 集成限流器到服务 - main.go 初始化限流器（根据 Redis 可用性选择内存/Redis 实现） - WebSocket handler 添加 query 消息限流（按 userID） - Auth API 添加登录/注册限流（按 IP） - refresh 和 logout 不限流（避免影响正常用户操作） - 修复所有测试（传递 nil limiter 参数） - 所有测试通过（包括 ws 和 api 集成测试）
2026-06-21 00:00:24 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
## 协议与 API
feat: 集成限流器到服务 - main.go 初始化限流器（根据 Redis 可用性选择内存/Redis 实现） - WebSocket handler 添加 query 消息限流（按 userID） - Auth API 添加登录/注册限流（按 IP） - refresh 和 logout 不限流（避免影响正常用户操作） - 修复所有测试（传递 nil limiter 参数） - 所有测试通过（包括 ws 和 api 集成测试）
2026-06-21 00:00:24 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
**WebSocket**：`ws://localhost:8080/ws?token=<jwt>&conversation_id=<uuid>`
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
- 客户端消息：`query`（图像/音频 Base64）, `config`, `interrupt`, `ping`
- 服务端消息：`connected`, `stt_result`, `llm_chunk`, `llm_done`, `tts_audio`, `error`, `pong`
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
- 心跳：客户端 30s ping，服务端 60s 超时断连；重连：指数退避 1s→30s
- 实现：`CamTalkWebSocket` 单例（`frontend/src/lib/websocket.ts`），订阅模式，自动重连
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
- WebSocket 地址自动从当前页面协议/主机推导，也可通过 `VITE_WS_URL` 环境变量显式指定（如 `wss://api.example.com/ws`）
docs: 更新技术文档，同步 Eino 重构和默认 provider 变更 - 架构设计：更新为 Eino Graph 声明式编排，增加三级存储架构说明 - 接口文档：AI 编排器章节重写为 Eino Graph，更新 LLM 服务接口 - 技术选型：新增 Eino 框架选型章节，修正 STT/LLM/TTS 默认方案 - 语音交互：Pipeline 描述改为 Eino Graph - 成本控制：模型引用修正为 qwen3-vl-plus - 技术名词解释：新增 Eino 框架相关术语 - README：增加 10/11/12 Eino 文档索引 - 10-Eino重构方案：状态更新为已实施 - CLAUDE.md：同步所有变更
2026-06-20 13:24:53 +08:00
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
**REST API**：`/api/auth/*`（注册/登录/刷新/登出），`/api/conversations/*`（CRUD + 消息分页），`/api/scenarios/*`（用户自定义情景 CRUD），`/api/health`
feat: 集成限流器到服务 - main.go 初始化限流器（根据 Redis 可用性选择内存/Redis 实现） - WebSocket handler 添加 query 消息限流（按 userID） - Auth API 添加登录/注册限流（按 IP） - refresh 和 logout 不限流（避免影响正常用户操作） - 修复所有测试（传递 nil limiter 参数） - 所有测试通过（包括 ws 和 api 集成测试）
2026-06-21 00:00:24 +08:00
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
**错误码**：`INVALID_MESSAGE`, `SESSION_NOT_FOUND`, `RATE_LIMITED`, `IMAGE_TOO_LARGE`, `LLM_TIMEOUT`, `STT/TTS/LLM_ERROR`, `INVALID_TOKEN` 等
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
## 关键文件路径
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
**后端核心**：
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
- `backend/cmd/server/main.go` — 入口，依赖注入与启动流程（存储→AI 服务→Graph→路由→Server）
- `backend/internal/eino/` — Eino Graph 编排层（graph.go 构建、adapter.go 适配、callback.go 推送、state.go 状态、nodes_*.go 各节点实现）
- `backend/internal/session/tiered.go` — 三级会话存储（TieredManager）
- `backend/internal/store/` — 持久化层（Repository 接口 + PG 实现 + Redis 缓存装饰器）
- Repository 模式：接口定义在 `user.go`/`session.go`/`message.go`，PG 实现在 `*_pg.go`，Redis 缓存装饰器在 `cached_user.go`
- `backend/internal/ws/handler.go` — WebSocket 连接管理（升级→认证→收发循环→清理）
- `backend/internal/ai/` — AI 服务抽象层（llm/stt/tts 各子目录，统一 `Service` 接口）
- `backend/internal/auth/` — JWT/bcrypt/中间件
- `backend/internal/ratelimit/` — 令牌桶限流（内存/Redis 两种后端）
- `backend/migrations/` — 嵌入式 SQL 迁移文件（embed.go + *.sql）
feat: 集成限流器到服务 - main.go 初始化限流器（根据 Redis 可用性选择内存/Redis 实现） - WebSocket handler 添加 query 消息限流（按 userID） - Auth API 添加登录/注册限流（按 IP） - refresh 和 logout 不限流（避免影响正常用户操作） - 修复所有测试（传递 nil limiter 参数） - 所有测试通过（包括 ws 和 api 集成测试）
2026-06-21 00:00:24 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
**前端核心**：
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
- `frontend/src/hooks/useVisionSession.ts` — 核心会话 Hook（~500 行，编排整个采集→发送→接收→播放流程）
- `frontend/src/lib/websocket.ts` — WebSocket 客户端单例（心跳/重连/订阅模式）
- `frontend/src/lib/auth.tsx` — AuthProvider（JWT 自动刷新 + React Context）
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
- `frontend/src/lib/api.ts` — REST 客户端（401 拦截 + token 刷新）
- `frontend/src/lib/ttsPlayer.ts` — 流式 TTS 音频播放队列
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
- `frontend/src/lib/i18n/` — 国际化（zh-CN / en-US / ja-JP）
- `frontend/src/components/` — UI 组件（LandingPage/CameraManager/MicManager/WebSocketManager/ChatPanel/SessionSidebar/ConfigPanel/VideoPreview 等）
- `frontend/vite.config.ts` — VAD 模型文件自动复制 + ONNX WASM MIME 处理 + 代理配置
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
docs: 扁平化目录结构，优化文档为 Coding Agent 可读格式 - 移除 Obsidian 特有语法（callout、wikilinks、YAML frontmatter） - 目录结构从 3 层嵌套扁平化为编号文件（01~09） - 新增 docs/README.md 文档索引与推荐阅读顺序 - 精简冗余解释，保留所有代码块和实现参考 - CLAUDE.md 全面中文化
2026-06-12 17:08:20 +08:00
## 编码规范
docs: add CLAUDE.md with project architecture and development guidelines
2026-06-12 16:49:01 +08:00
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
- **Go**：标准规范，`context.Context` 超时控制，`sync.RWMutex` 并发保护，`json:"snake_case"` 标签，编译期接口检查 `var _ Interface = (*Impl)(nil)`
- **TypeScript**：严格模式，接口定义数据模型，WebSocket 消息用可辨识联合类型（`type` 字段区分）
docs: 更新 README.md
2026-07-17 10:43:27 +08:00
- **存储层模式**：Repository 接口 + PostgreSQL 实现 + Redis 缓存装饰器（`CachedUserRepository` 包装模式）
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），语义清晰 - 通过交叉引用连接相关文档，避免重复
2026-06-21 14:48:03 +08:00
- **CORS**：禁止后端代码/配置文件配置 CORS，统一由代理层处理（开发环境 Vite proxy，生产环境 Nginx）
- **提交信息**：Conventional Commits，中文描述（如 `feat: 添加 WebSocket 心跳`）
- **禁止自动 push**：除非用户明确要求
- **文档优先**：开发前先读 `docs/` 设计文档，代码与文档不一致时优先更新文档
Reference in New Issue Copy Permalink