yoyo/changelog.md

# 变更日志 (changelog.md)

> 本文档记录所有版本变更，包含功能、修复和讨论链接。

## 使用说明
- 版本号格式：`主版本.次版本.修订版本`（如 `0.0.1`）
- 第三位为00-99，超过99时增加第二位
- 每个版本包含指向讨论记录的链接

## 未来架构想法
- [ ] 支持流式翻译输出
- [x] 添加本地缓存减少API调用 ✅ 已完成
- [ ] 实现插件系统支持自定义厂商
- [ ] 支持批量翻译文件
- [ ] 添加Web界面（可选）

## 待实现
- [ ] 实现硅基流动厂商
- [ ] 实现火山引擎厂商
- [ ] 实现国家超算厂商
- [ ] 实现Qwen厂商
- [ ] 实现OpenAI兼容厂商
- [ ] 配置文件热重载
- [ ] 翻译历史记录

## 当前正实现
- [x] TUI界面模块拆分计划 ✅ 已制定
- [x] 模块1: TUI框架搭建 ✅ 已完成
- [x] 模块2: 输入组件 ✅ 已完成
- [x] 模块3: 翻译显示区 ✅ 已完成
- [x] 模块4: 状态栏/主题 ✅ 已完成
- [x] 模块5: 快捷键系统 ✅ 已完成
- [x] 模块6: 集成翻译 ✅ 已完成

## TUI界面实现计划 (v0.6.0) - 全部完成!
| 步骤 | 模块 | 内容 | 状态 |
|------|------|------|------|
| 1 | TUI框架搭建 | bubbletea基础App结构、运行循环 | ✅ 已完成 |
| 2 | 输入组件 | 文本输入框，光标、基础编辑 | ✅ 已完成 |
| 3 | 翻译显示区 | 结果展示、格式化、滚动 | ✅ 已完成 |
| 4 | 状态栏/主题 | 底部状态栏、语言选择、主题配色 | ✅ 已完成 |
| 5 | 快捷键系统 | 退出、清空、切换语言等 | ✅ 已完成 |
| 6 | 集成翻译 | 对接现有Translator、加载动画 | ✅ 已完成 |

## TUI界面重构计划 (v0.8.0) - 聊天风格
| 步骤 | 模块 | 内容 | 状态 |
|------|------|------|------|
| 1 | 模块结构拆分 | 创建 view/components/styles/keys 子目录 | ✅ 已完成 |
| 2 | 消息数据结构 | ChatMessage, ChatGroup 结构定义 | ✅ 已完成 |
| 3 | 消息列表组件 | 可滚动的消息历史展示 (viewport) | ✅ 已完成 |
| 4 | 原文+译文样式 | 区分显示用户输入和翻译结果 | ✅ 已完成 |
| 5 | 固定底部输入框 | textarea + Ctrl+J 换行 + 固定高度5行 | ✅ 已完成 |
| 6 | 状态栏 | 完整信息显示 | ✅ 已完成 |
| 7 | 翻译逻辑集成 | 对接 Translator | ✅ 已完成 |
| 8 | 输入框背景色 | 使用 FocusedStyle/BlurredStyle 设置背景 | ✅ 已完成 |
| 9 | 输入框修复 | 修复Ctrl+J换行后第一行被遮住的问题 | ✅ 已完成 |

## TUI界面改进计划 (v0.7.0)
| 步骤 | 模块 | 内容 | 状态 |
|------|------|------|------|
| 7 | 多行输入 | textarea组件替换textinput | ✅ 已完成 |
| 8 | 弹出框组件 | 通用modal组件 | ⏳ 待实现 |
| 9 | 斜杠命令菜单 | / 触发命令选择器，模糊匹配 | ⏳ 待实现 |
| 10 | 翻译结果滚动 | viewport组件支持长文本 | ⏳ 待实现 |
| 11 | 复制功能 | clipboard集成 | ⏳ 待实现 |
| 12 | 状态栏扩展 | 显示耗时、token用量 | ⏳ 待实现 |

## 待修复BUG
- 无

## 版本历史

### 0.7.1 (2026-04-08) - TUI界面改进
**类型**: 优化版本  
**状态**: 开发中  

**改进内容**:
- ✅ 添加帮助信息栏目 - 使用 bubbles help 组件，位于界面底部
- ✅ 帮助按键绑定 - Ctrl+H 切换帮助显示
- ✅ Logo 版本号注入 - 使用 build.sh + ldflags 自动注入 git 版本
- ✅ 翻译卡片样式 - 翻译结果 Padding(1,3,1,3) 增加上方空隙
- ✅ Viewport 上方内边距 - 第一个翻译卡片显示时增加上方空白

**构建脚本改进**:
- ✅ 扩展 build.sh 支持跨平台编译
- ✅ 添加 -h 帮助选项
- ✅ 支持 -o 自定义输出文件名
- ✅ 支持平台: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64

**讨论记录**:
- [帮助功能和样式改进](taolun.md#2026-04-08-tui界面帮助功能与样式改进)

**下一步**:
- 实现模块8: 弹出框组件

---

### 0.7.0 (2026-04-06) - TUI界面改进
**类型**: 功能版本  
**状态**: 开发中  

**改进内容**:
- ✅ 模块7: 多行输入 - textarea组件替换textinput
- ✅ 模块7补充: 布局和样式优化 - 全宽/自适应高度/深色背景
- ⏳ 模块8: 弹出框组件 - 通用modal
- ⏳ 模块9: 斜杠命令菜单 - / 命令选择器
- ⏳ 模块10: 翻译结果滚动 - viewport
- ⏳ 模块11: 复制功能 - clipboard
- ⏳ 模块12: 状态栏扩展 - 耗时/token

**讨论记录**:
- [TUI界面改进计划](taolun.md#2026-04-06-1400-版本-070---tui界面改进计划)

**下一步**:
- 实现模块8: 弹出框组件

---

### 0.6.0 (2026-04-06) - TUI交互界面
**类型**: 功能版本  
**状态**: 已完成  

**变更内容**:
- ✅ 模块1: TUI框架搭建 - 添加bubbletea依赖，实现基础App结构
- ✅ 模块2: 输入组件 - textinput组件、基础输入处理
- ✅ 模块3: 翻译显示区 - 结果显示区域、样式定义
- ✅ 模块4: 状态栏/主题 - 底部状态栏、语言显示、配色完善
- ✅ 模块5: 快捷键系统 - Ctrl+L清空、Ctrl+T切换语言
- ✅ 模块6: 集成翻译 - Enter触发翻译、异步执行、加载状态、错误处理

**技术实现**:
- 使用 `github.com/charmbracelet/bubbletea` v1.3.10
- 使用 `github.com/charmbracelet/bubbles` (textinput组件)
- 使用 `github.com/charmbracelet/lipgloss` v1.1.0
- 基础model结构: config、translator字段

**讨论记录**:
- [TUI界面模块拆分计划](taolun.md#2026-04-06-1000-版本-060---tui界面模块拆分计划)

**下一步**:
- 实现模块7: 多行输入

---

### 0.5.0 (2026-03-29) - 本地缓存功能
**类型**: 功能版本  
**状态**: 已发布  

**变更内容**:
- ✅ 添加本地缓存模块 (internal/cache/)
- ✅ 实现SQLite缓存存储层，支持高效查询和存储
- ✅ 实现缓存键生成策略（基于原文+语言对的SHA256哈希）
- ✅ 修改Translator类集成缓存功能，先查缓存再调用API
- ✅ 添加缓存配置到Config结构，支持自定义缓存参数
- ✅ 实现缓存管理命令：cache clear, cache stats, cache cleanup
- ✅ 添加组合缓存清理策略（数量限制+时间过期）
- ✅ 更新配置文件模板，添加缓存配置示例
- ✅ 更新帮助文档，添加缓存相关命令说明

**技术实现**:
- 使用 `github.com/mattn/go-sqlite3` 作为SQLite驱动
- 实现缓存接口 (Cache interface)，支持多种存储后端
- 缓存表包含完整字段：原文、译文、语言对、模型、Prompt、用量统计
- 自动清理过期缓存和超出数量限制的缓存
- 异步保存缓存，不阻塞翻译结果返回

**使用示例**:
```bash
# 基本翻译（自动使用缓存）
yoyo "Hello world"
yoyo "Hello world"  # 第二次调用将从缓存返回

# 缓存管理命令
yoyo cache clear           # 清空翻译缓存
yoyo cache stats           # 查看缓存统计信息
yoyo cache cleanup         # 清理过期缓存
```

**配置示例**:
```yaml
cache:
  enabled: true           # 是否启用缓存
  max_records: 10000      # 最大缓存记录数
  expire_days: 30         # 缓存过期天数
  db_path: "~/.config/yoyo/cache.db"  # 缓存数据库文件路径
```

**讨论记录**:
- [本地缓存功能设计](taolun.md#2026-03-29-1500-版本-050-本地缓存功能设计)

**下一步**:
- 完善缓存功能测试
- 添加缓存命中率统计
- 实现按语言清理缓存功能
- 优化缓存性能

---

### 0.5.1 (2026-03-29) - 缓存功能修复
**类型**: 修复版本  
**状态**: 已发布  

**变更内容**:
- ✅ 修复缓存清空命令中的VACUUM事务错误
- ✅ 修复缓存统计中的NULL值处理错误
- ✅ 修复缓存过期清理策略，支持expire_days=0时清理所有记录
- ✅ 添加缓存模块单元测试
- ✅ 更新版本号到v0.5.1

**修复问题**:
- 缓存清空命令执行时出现"cannot VACUUM from within a transaction"错误
- 缓存统计查询在空表时出现NULL值转换错误
- 缓存过期清理策略在expire_days=0时不工作

**测试结果**:
- 所有缓存模块测试通过
- 缓存命令功能正常
- 缓存集成功能正常

**下一步**:
- 完善缓存功能测试
- 添加缓存命中率统计
- 实现按语言清理缓存功能
- 优化缓存性能

---

### 0.4.0 (2026-03-29) - 管道符功能
**类型**: 功能版本  
**状态**: 已发布  

**变更内容**:
- ✅ 添加管道符支持，允许与其他命令行工具联合使用
- ✅ 实现管道输入检测 (isPipeInput函数)
- ✅ 实现从标准输入读取 (readFromStdin函数)
- ✅ 添加 --quiet 和 -q 参数控制统计信息输出
- ✅ 更新帮助文档，添加管道使用示例
- ✅ 修复 content/filter.go 中的正则表达式错误
- ✅ 更新版本号到 v0.3.0

**使用示例**:
```bash
# 管道翻译文件
cat file.txt | yoyo
cat file.txt | yoyo --lang=en

# 管道翻译命令输出
echo "Hello world" | yoyo --lang=cn

# 静默模式，只输出翻译结果
echo "Hello world" | yoyo -q

# 与其他命令组合使用
cat file.txt | yoyo | grep "关键词"
yoyo "Hello" | wc -l
```

**讨论记录**:
- [管道符功能设计](taolun.md#管道符功能设计)

**下一步**:
- 实现更多厂商（火山引擎、国家超算、Qwen、OpenAI兼容）
- 添加配置文件路径查找机制
- 实现配置文件迁移工具
- 完善错误处理和用户体验

### 0.3.0 (2026-03-29) - 内容过滤与代码处理
**类型**: 功能版本  
**状态**: 已发布  

**变更内容**:
- ✅ 添加内容过滤模块 (internal/content/)
- ✅ 实现基础字符过滤（移除控制字符、规范化换行符、截断超长符号）
- ✅ 实现代码块和行内代码识别
- ✅ 实现代码注释智能识别（支持 JS/TS/Java/Python/Go/HTML 等 30+ 语言）
- ✅ 添加 go-enry 依赖实现编程语言智能检测
- ✅ 添加 SkipKeywords 配置项，默认保留 TODO/FIXME/HACK 等关键词不翻译
- ✅ 集成内容处理到 Translator 模块

**新增文件**:
- `internal/content/content.go` - 模块入口
- `internal/content/filter.go` - 基础字符过滤
- `internal/content/parser.go` - 内容解析器和语言检测

**配置更新**:
- `configs/config.yaml` 新增 `skip_keywords` 配置项
- 支持用户自定义不翻译的关键词列表

**使用示例**:
```bash
# 翻译包含代码的文档，自动识别代码和注释
yoyo "这是一个文档 ```js // TODO: fix this ```"
# 代码块保持不变，只翻译注释中的词汇
# TODO: 修复这个
```

**讨论记录**:
- [内容过滤与代码处理设计](taolun.md#内容过滤与代码处理设计)

**下一步**:
- 实现更多厂商（火山引擎、国家超算、Qwen、OpenAI兼容）
- 添加配置文件路径查找机制
- 实现配置文件迁移工具
- 完善错误处理和用户体验

### 0.2.0 (2026-03-29) - 语言支持和配置向导
**类型**: 功能版本  
**状态**: 开发中  

**变更内容**:
- ✅ 添加语言代码智能解析模块 (internal/lang)
- ✅ 支持 `--lang` 参数指定目标语言
- ✅ 支持多种语言代码格式（标准BCP47、别名、中文名称）
- ✅ 实现 onboard 交互式配置向导
- ✅ 更新配置结构添加语言字段
- ✅ 添加 survey 库依赖用于交互式界面
- ✅ 改进CLI命令行接口
- ✅ 添加语言模块单元测试

**新增文件**:
- `internal/lang/lang.go` - 语言代码解析模块
- `internal/lang/lang_test.go` - 语言模块测试
- `internal/onboard/onboard.go` - 配置向导实现

**支持的语言代码**:
- 标准格式: zh-CN, zh-TW, en-US, en-GB, ja, ko, es, fr, de 等
- 简短别名: cn(中文), en(英文), jp(日文), kr(韩文) 等
- 中文名称: chinese(中文), english(英文), japanese(日文) 等

**使用示例**:
```bash
# 基本翻译
yoyo "Hello world"
yoyo --lang=cn "Hello world"
yoyo --lang=en "你好世界"
yoyo --lang=zh-TW "Hello world"

# 配置向导
yoyo onboard
yoyo onboard --force
```

**讨论记录**:
- [语言代码解析设计](taolun.md#语言代码解析设计)
- [onboard配置向导](taolun.md#onboard配置向导)

**下一步**:
- 实现更多厂商（火山引擎、国家超算、Qwen、OpenAI兼容）
- 添加配置文件路径查找机制
- 实现配置文件迁移工具
- 完善错误处理和用户体验

### 0.0.3 (2026-03-29) - 环境变量加载修复
**类型**: 修复版本  
**状态**: 开发中  

**变更内容**:
- ✅ 修复环境变量加载问题
- ✅ 添加godotenv依赖
- ✅ 更新memory.md记录踩坑经验
- ✅ 测试CLI基本功能

**讨论记录**:
- [环境变量加载修复](taolun.md#2026-03-29-0000-版本-003-环境变量加载修复)

**下一步**:
- 实现更多厂商
- 添加更多测试
- 完善错误处理

### 0.0.2 (2026-03-28) - 核心架构实现
**类型**: 功能版本  
**状态**: 开发中  

**变更内容**:
- ✅ 实现Config配置类（internal/config/config.go）
- ✅ 实现Provider接口和工厂模式（internal/provider/）
- ✅ 实现硅基流动厂商（internal/provider/siliconflow.go）
- ✅ 实现Translator核心翻译类（internal/translator/）
- ✅ 实现Prompt管理器（internal/translator/prompt.go）
- ✅ 创建CLI入口点（cmd/yoyo/main.go）
- ✅ 添加配置文件模板（configs/config.yaml）
- ✅ 添加单元测试（internal/config/config_test.go）
- ✅ 初始化Git仓库和版本标签

**讨论记录**:
- [实现核心架构](taolun.md#2026-03-28-2350-版本-002-实现核心架构)

**下一步**:
- 实现其他厂商（火山引擎、国家超算、Qwen、OpenAI兼容）
- 添加更多测试
- 实现批量翻译功能
- 添加翻译历史记录
- 实现配置文件热重载

### 0.0.1 (2026-03-28) - 项目初始化
**类型**: 初始化版本  
**状态**: 开发中  

**变更内容**:
- ✅ 确定技术栈为Go语言
- ✅ 设计OOP架构（Config、Provider、Translator）
- ✅ 制定开发规范（taolun.md、changelog.md、memory.md、why.md）
- ✅ 确定分支策略（main、dev）
- ✅ 设计项目结构
- ✅ 创建项目初衷文档（why.md）

**讨论记录**:
- [确定技术栈](taolun.md#2026-03-28-2230-版本-001-确定技术栈)
- [设计OOP架构](taolun.md#2026-03-28-2300-版本-001-设计oop架构)
- [制定开发规范](taolun.md#2026-03-28-2330-版本-001-制定开发规范)
- [创建项目初衷文档](taolun.md#2026-03-28-2345-版本-001-创建项目初衷文档)

**下一步**:
- 创建项目目录结构
- 初始化Go模块
- 实现Config类
- 实现Provider接口
- 用户填写why.md内容

---

## 版本号管理规则

### 版本号格式
`主版本.次版本.修订版本`（例如：`1.2.3`）

### 更新规则
1. **主版本**（第一位）：重大架构变更、不兼容更新
2. **次版本**（第二位）：新功能、重要特性
3. **修订版本**（第三位）：小修复、优化（00-99）

### 更新流程
1. 完成开发并测试
2. 更新changelog.md
3. 更新taolun.md（如有讨论）
4. 更新memory.md（如有新知识）
5. 更新版本号
6. 提交到dev分支
7. 测试通过后合并到main
8. 创建版本标签：`git tag v0.0.1`

### 示例版本递增
- `0.0.1` → `0.0.2`：小修复
- `0.0.99` → `0.1.0`：新功能（修订版本溢出）
- `1.2.3` → `2.0.0`：重大架构变更

---

## v0.8.1 (2026-04-07)

### 新功能
- 使用 lipgloss v2 设计翻译结果卡片组件
- 卡片包含三部分：元信息行（Tokens/耗时/模型）、用户输入（碳黑背景）、翻译结果

### 升级
- 升级 `charm.land/lipgloss/v2` v1.1.0 → v2.0.2
- 升级 `charm.land/bubbletea/v2` v1.3.10 → v2.0.2
- 升级 `charm.land/bubbles/v2` → v2.1.0
- 更新所有模块路径为 `charm.land/xxx/v2` 格式

### 技术细节
- 背景色: #1A1A1A (碳黑色)
- 用户输入区域无边框，纯背景色
- 组件间距: 5px marginBottom
- View() 方法返回 `tea.View` 类型
- KeyMsg 改为 KeyPressMsg，使用 `msg.String()` 判断键位

**讨论记录**: [taolun.md#版本-0.8.1-翻译结果卡片组件设计](taolun.md#版本-081---翻译结果卡片组件设计)

---

## v1.0.0-beta (2026-04-07)

### 新功能
- ASCII艺术Logo标题，带紫色→粉色渐变效果
- 输入框改造：
  - 使用 `:::` 紫色分隔符替代上下边框
  - Ctrl+J 换行功能
- 信息栏改造：
  - 合并显示：语言、模型名、缓存记录数
  - 添加翻译状态 Spinner 动画 (MiniDot)
- 翻译结果卡片优化：
  - 底部 `▣` 图标左侧边距从3减少到2
  - `▣` 与文字间距从3减少到2

### 技术细节
- 使用 lipgloss 实现 True Color 渐变效果
- 使用 charmbracelet/bubbles spinner 组件实现加载动画
- 版本号显示在Logo右侧 [v1.0.0-beta]
- 动态调整 viewport 高度适应终端

### 版本号规则
- 版本号需与 git 标签、changelog.md 中的版本号保持三方同步

**讨论记录**: [taolun.md#版本-100-beta-Logo和信息栏改造](taolun.md#版本-100-beta-logo和信息栏改造)

---

## v1.1.0 (2026-04-07)

### BUG修复
- 修复配置文件路径使用相对路径导致管道模式下无法找到配置的问题
- 修复onboard配置保存到错误路径的问题
- 修复.env文件只在当前目录加载的问题

### 新功能
- 配置文件路径智能解析：`~/.config/yoyo/config.yaml` → `./configs/config.yaml`
- onboard配置向导迁移到 `charm.land/huh/v2`，替代 `survey` 库
- 新增路径解析工具 `internal/config/path.go`

### 改进
- 配置查找优先级：`--config` 参数 > `~/.config/yoyo/config.yaml` > `./configs/config.yaml`
- 配置文件统一保存到 `~/.config/yoyo/config.yaml`（符合XDG规范）
- .env文件统一从 `~/.config/yoyo/.env` 加载
- onboard使用huh的Form+Group模式，更美观的交互体验
- 移除 `github.com/AlecAivazis/survey/v2` 依赖

### 技术细节
- 新增 `config.ResolveConfigPath()` 函数处理路径解析
- 新增 `config.GetUserConfigPath()` 返回标准配置路径
- 新增 `config.GetUserEnvPath()` 返回标准环境变量路径
- 支持 `~` 路径展开
- huh使用v2版本，支持泛型和链式API

 **讨论记录**: [taolun.md#2026-04-07-配置路径修复和huh迁移](taolun.md)

---

## v1.1.1 (2026-04-08)

### BUG修复
- 修复 `--help` `-h` `-?` `--version` 在默认交互式模式下无响应的问题
- 原因：交互模式判断优先于help/version检查，导致flags被忽略

### 新功能
- 新增 `internal/logo/logo.go` 模块，统一管理logo展示
- 编译时通过 `-ldflags` 注入版本号，实现动态版本管理
- 新增 `build.sh` 脚本，自动获取git版本并注入

### 改进
- 帮助信息和版本输出使用渐变logo（紫→青色）
- TUI头部与CLI帮助信息使用统一的logo模块
- 移除TUI头部的 `[Ctrl+C 退出]` 显示
- 统一版本号格式：` ( v1.1.1-dirty )` 或 ` ( )`（无版本时）

### 技术细节
```go
// logo模块核心函数
func GradientText(text string, startColor, endColor string) string
func GetLogoPattern() string  // 返回4行ascii art
func GetVersionSuffix() string  // 返回 " (v1.1.1-dirty )" 或 " ( )"
func PrintLogoWithVersion()  // 打印完整logo
```

```bash
# build.sh 版本注入
VERSION=$(git describe --tags --always --dirty 2>/dev/null || echo "")
go build -ldflags "-X github.com/titor/fanyi/internal/logo.version=${VERSION}" -o yoyo ./cmd/yoyo
```

- 渐变色方案：`#B413DC`（紫）→ `#00C8C8`（青）
- TUI通过调用 `logo.GradientText(logo.GetLogoPattern(), "#B413DC", "#00C8C8")` 获取渐变logo

**讨论记录**: [taolun.md#2026-04-08-Logo模块化与渐变色统一](taolun.md)