166 lines
4.2 KiB
Markdown
166 lines
4.2 KiB
Markdown
|
# 记忆纠正 (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，次版本和修订版本重置
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 配置最佳实践
|
|||
|
|
|
|||
|
|
### 安全配置
|
|||
|
|
- 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记录经验
|