titor/yoyo

Files

z.to 8a200e2bcd initial: project structure and documentation setup

- Create project directory structure
- Initialize Go module
- Set up development documentation (why.md, taolun.md, changelog.md, memory.md, AGENTS.md)
- Configure YAML config template
- Set up .gitignore and .env.example
- Design OOP architecture with factory and strategy patterns

Version: 0.0.1

2026-03-28 23:19:13 +08:00

4.2 KiB

Raw Blame History

记忆纠正 (memory.md)

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

使用说明

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

技术决策记录

Go语言选择

决策: 使用Go语言而非Node.js或Deno
原因:

Go编译为单一二进制文件，部署方便
性能优秀，适合CLI工具
强大的标准库支持
用户愿意学习Go

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

面向对象设计

决策: 在Go中实现面向对象设计模式
模式应用:

工厂模式: ProviderFactory创建厂商实例
策略模式: Provider接口定义不同厂商策略
依赖注入: Translator依赖Provider接口

注意事项:

Go中没有类，使用结构体
继承通过组合实现
多态通过接口实现

术语定义

厂商 (Provider)

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

配置 (Config)

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

核心翻译器 (Translator)

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

踩过的坑

环境变量加载问题

问题: 配置文件中的环境变量（如${API_KEY}）没有正确解析
原因: 没有实现环境变量替换功能
解决方案:

使用os.Getenv读取环境变量
在配置加载时进行字符串替换
添加环境变量验证

预防措施:

在配置加载后验证所有必需的环境变量
提供清晰的错误信息

厂商API差异

问题: 不同厂商的API格式差异较大
原因: 每个厂商有自己的请求/响应格式
解决方案:

定义统一的TranslateRequest和TranslateResponse
在每个厂商实现中进行格式转换
使用适配器模式

经验:

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

版本号管理混乱

问题: 版本号递增规则不明确
原因: 没有明确的版本管理规范
解决方案:

采用语义化版本：主版本.次版本.修订版本
第三位限制为00-99
建立更新流程

规范:

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

配置最佳实践

安全配置

API密钥使用环境变量
不提交敏感信息到版本控制
提供.env.example模板

配置验证

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

默认值策略

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

开发工作流

日常开发流程

从dev分支创建功能分支
开发并测试功能
更新相关文档（taolun.md、changelog.md）
提交到功能分支
合并到dev分支
测试通过后合并到main

版本发布流程

确保dev分支稳定
更新版本号
更新changelog.md
创建版本标签
合并到main分支

文档维护

每次重要讨论后更新taolun.md
每个版本更新changelog.md
遇到问题后更新memory.md

文档管理规范

why.md (项目初衷文档)

用途: 记录项目初衷、愿景、目标和个人笔记
编辑权限: 只能由项目所有者（用户）编辑
位置: 项目根目录
内容建议:

项目愿景
核心问题
目标用户
期望功能
个人笔记