yoyo/memory.md

# 记忆纠正 (memory.md)

> 本文档记录开发过程中的重要定义、踩过的坑和经验总结，用于AI内部知识纠正。

## 使用说明
- 定期更新，特别是遇到问题后
- 按类别组织，便于查找
- 包含具体示例和解决方案

## 技术决策记录

### Go语言选择
**决策**: 使用Go语言而非Node.js或Deno  
**原因**: 
1. Go编译为单一二进制文件，部署方便
2. 性能优秀，适合CLI工具
3. 强大的标准库支持
4. 用户愿意学习Go

**影响**: 项目结构、依赖管理、开发工具链

---

### 面向对象设计
**决策**: 在Go中实现面向对象设计模式  
**模式应用**:
1. **工厂模式**: ProviderFactory创建厂商实例
2. **策略模式**: Provider接口定义不同厂商策略
3. **依赖注入**: Translator依赖Provider接口

**注意事项**:
- Go中没有类，使用结构体
- 继承通过组合实现
- 多态通过接口实现

---

## 术语定义

### 厂商 (Provider)
指提供大模型API的服务商，如硅基流动、火山引擎等。每个厂商实现统一的`Provider`接口。

### 配置 (Config)
全局配置对象，包含API密钥、模型选择、超时设置等。使用YAML格式。

### 核心翻译器 (Translator)
负责协调配置、厂商和Prompt管理，执行翻译任务的核心类。

## 踩过的坑

### 环境变量加载问题
**问题**: 配置文件中的环境变量（如`${API_KEY}`）没有正确解析  
**原因**: 没有实现环境变量替换功能  
**解决方案**: 
1. 使用`os.Getenv`读取环境变量
2. 在配置加载时进行字符串替换
3. 添加环境变量验证

**预防措施**: 
- 在配置加载后验证所有必需的环境变量
- 提供清晰的错误信息

---

### 厂商API差异
**问题**: 不同厂商的API格式差异较大  
**原因**: 每个厂商有自己的请求/响应格式  
**解决方案**:
1. 定义统一的`TranslateRequest`和`TranslateResponse`
2. 在每个厂商实现中进行格式转换
3. 使用适配器模式

**经验**: 
- 优先设计统一接口
- 将厂商特定逻辑封装在实现内部
- 提供原始响应用于调试

---

### 版本号管理混乱
**问题**: 版本号递增规则不明确  
**原因**: 没有明确的版本管理规范  
**解决方案**: 
1. 采用语义化版本：主版本.次版本.修订版本
2. 第三位限制为00-99
3. 建立更新流程

**规范**:
- 小修复：修订版本+1
- 新功能：次版本+1，修订版本重置为00
- 重大变更：主版本+1，次版本和修订版本重置

---

### 环境变量加载问题
**问题**: 配置文件中的环境变量没有正确加载  
**原因**: Go程序不会自动加载.env文件，需要使用第三方库  
**解决方案**: 
1. 使用`github.com/joho/godotenv`包
2. 在程序启动时调用`godotenv.Load()`
3. 将.env文件添加到.gitignore

**代码示例**:
```go
import "github.com/joho/godotenv"

func main() {
    _ = godotenv.Load() // 加载.env文件
    // 然后加载配置文件
}
```

**注意事项**:
- 不要提交真实的.env文件到版本控制
- 提供.env.example模板
- 在文档中说明环境变量配置方法

---

## 配置最佳实践

### 安全配置
- API密钥使用环境变量
- 不提交敏感信息到版本控制
- 提供`.env.example`模板

### 配置验证
- 启动时验证所有必需配置
- 提供有意义的错误信息
- 支持配置热重载（未来）

### 默认值策略
- 为非必需配置提供合理的默认值
- 默认值应在`config.setDefaults()`中设置
- 记录默认值的作用

---

## 开发工作流

### 日常开发流程
1. 从`dev`分支创建功能分支
2. 开发并测试功能
3. 更新相关文档（taolun.md、changelog.md）
4. 提交到功能分支
5. 合并到`dev`分支
6. 测试通过后合并到`main`

### 版本发布流程
1. 确保`dev`分支稳定
2. 更新版本号
3. 更新changelog.md
4. 创建版本标签
5. 合并到`main`分支

### 文档维护
- 每次重要讨论后更新taolun.md
- 每个版本更新changelog.md
- 遇到问题后更新memory.md

---

## 文档管理规范

### why.md (项目初衷文档)
**用途**: 记录项目初衷、愿景、目标和个人笔记  
**编辑权限**: 只能由项目所有者（用户）编辑  
**位置**: 项目根目录  
**内容建议**: 
- 项目愿景
- 核心问题
- 目标用户
- 期望功能
- 个人笔记

**注意事项**:
- AI不应修改此文件
- 文件内容反映创始人的个人想法
- 可以自由格式，不强制结构

### 文档协作规范
**taolun.md**: AI与用户共同维护的讨论记录  
**changelog.md**: AI与用户共同维护的版本记录  
**memory.md**: AI主导的知识纠正和经验总结  
**why.md**: 用户专属的项目初衷文档

**编辑流程**:
1. 用户编辑why.md记录初衷
2. AI编辑taolun.md记录讨论
3. AI更新changelog.md记录版本
4. AI更新memory.md记录经验

---

## 语言代码处理经验

### 语言代码标准化
**问题**: 需要支持多种语言代码格式，但内部应使用标准格式  
**解决方案**: 
1. 使用BCP 47语言标签作为标准格式（如 `zh-CN`、`en-US`）
2. 实现智能解析函数 `ParseLanguageCode()`
3. 支持别名映射（如 `cn` → `zh-CN`、`en` → `en-US`）

**最佳实践**:
- 语言代码小写，地区代码大写（如 `zh-CN`，不是 `zh-cn`）
- 提供语言名称映射用于显示（如 `zh-CN` → "中文(简体)"）
- 支持模糊匹配和建议功能

### 交互式配置经验
**问题**: 命令行工具需要友好的配置界面  
**解决方案**: 
1. 使用 `github.com/AlecAivazis/survey/v2` 库
2. 实现分步配置流程
3. 提供默认值和确认选项

**注意事项**:
- 交互式库需要终端支持
- 提供非交互式模式（如配置文件模板）
- 错误处理要友好，避免程序崩溃

### 命令行参数解析经验
**问题**: Go标准库 `flag` 包功能有限，需要支持子命令  
**解决方案**: 
1. 使用 `flag` 包解析选项参数
2. 手动处理子命令（如 `onboard`）
3. 提供清晰的帮助信息

**命名冲突处理**:
- 避免变量名与包名冲突（如 `onboard` 变量与 `onboard` 包）
- 使用后缀区分（如 `onboardFlag`）

## 配置文件管理经验

### 开发阶段配置策略
**决策**: 开发阶段使用 `.env` + `configs/config.yaml`  
**原因**: 
1. 简化开发环境配置
2. 符合12-factor应用原则
3. 避免过早优化

**实施**:
- `.env` 文件存储API密钥等敏感信息
- `configs/config.yaml` 存储复杂配置结构
- 使用环境变量替换 `${VAR}`

### 配置文件格式选择
**决策**: 使用YAML格式  
**原因**: 
1. 人类可读性好
2. 支持复杂数据结构
3. Go生态支持良好

**注意事项**:
- 使用 `gopkg.in/yaml.v3` 库
- 注意缩进和格式
- 提供配置验证