haibao-tts-cli/changelog.md

版本变更记录 (changelog.md)

[0.1.0] - 2026-04-24

新增

• 初始化 Rust 项目结构（edition 2021）
• 配置 Cargo.toml 依赖（使用国内源，稀疏索引协议）
• 创建项目文档体系（taolun.md、changelog.md、agents.md）
• 实现配置管理模块 (config.rs) - Singleton 模式
  • 统一配置文件路径为 ~/.config/tts/config.toml（所有平台）
  • 使用 home 库获取家目录
• 实现 API 调用模块 (api.rs) - Builder 模式
  • TtsClient 结构体封装 API 调用
  • 支持双 Header 认证（api-key + Authorization）
  • Base64 解码音频数据
• 实现 CLI 模块 (cli.rs) - clap derive 模式
  • 添加 Onboard 子命令（引导式配置）
  • 添加 Voices、Config、ShowConfig 子命令
• 实现主程序入口 (main.rs)
  • 异步主函数（tokio）
  • 错误处理和退出码规范（0-4）
  • 支持从文本或文件输入
• 创建 project.config.toml 管理项目版本
• Release 版本构建成功（无警告）
• 语音合成功能测试成功

技术栈

• Rust (edition 2021)
• clap 4.6 (CLI 参数解析)
• reqwest 0.12 (HTTP 客户端)
• tokio 1.52 (异步运行时)
• serde + serde_json (序列化)
• toml (配置文件)
• base64 0.22 (音频解码)
• home 0.5 (跨平台家目录获取)
• anyhow 1.0 (错误处理)

功能列表

• ✅ 文本转语音（TTS）
• ✅ 支持多种音色（default_zh, default_en, mimo_default）
• ✅ 配置文件管理（~/.config/tts/config.toml）
• ✅ CLI 引导式配置（onboard 命令）
• ✅ 列出可用音色（voices 命令）
• ✅ 配置管理（config set/show 命令）
• ✅ WAV 音频输出

---

版本规范

遵循 语义化版本 2.0.0：

• 主版本号：不兼容的 API 修改
• 次版本号：向下兼容的功能性新增
• 修订号：向下兼容的问题修正

修改（第三轮 - 流式输出）

• 修改 synthesize() 返回音频数据而非保存文件
• 支持输出到 stdout（二进制流）
• 保留 --output 参数用于保存到文件
• 输出到 stdout 时自动抑制提示信息
• 便于作为 claw skill 集成

修改（第四轮 - 音频播放）

• 添加 rodio 0.19 依赖（音频播放库）
• 添加 --play 参数（直接播放音频）
• 修改 synthesize() 返回音频数据
• 新增 play_audio() 函数（使用 rodio 播放）
• 支持三种输出方式：播放/保存/流式输出
• --play 和 --output 互斥

[0.1.0] 最终状态

新增功能（第四轮）

• 添加 rodio 0.19 音频播放库
• 新增 --play 参数：直接播放音频（单次播放，不循环）
• synthesize() 函数改为返回音频数据 Vec
• 新增 play_audio() 函数：使用 rodio 从内存播放 WAV

修改（第四轮）

• 修改 Cargo.toml：添加 rodio 依赖
• 修改 cli.rs：添加 --play 参数（与 --output 互斥）
• 修改 main.rs：
  • synthesize() 返回 Result<Vec>
  • 添加 play_audio() 函数
  • run() 支持三种输出方式

修复（第四轮）

• 修复 synthesize() 重复代码问题
• 修复 stdout 输出被 println 污染的问题
• 移除未使用的导入警告

功能列表（最终）

• ✅ 文本转语音（TTS）
• ✅ 支持多种音色（default_zh, default_en, mimo_default）
• ✅ 配置文件管理（~/.config/tts/config.toml）
• ✅ CLI 引导式配置（onboard 命令）
• ✅ 列出可用音色（voices 命令）
• ✅ 配置管理（config set/show 命令）
• ✅ 直接播放音频（--play 参数）
• ✅ 保存文件（--output 参数）
• ✅ 流式输出（stdout 二进制流）
• ✅ WAV 音频输出

修改（第五轮 - 音色扩展）

• 更新音色列表为 Mimo-TTS 完整列表（8个音色）
• 默认音色从 default_zh 改为 mimo_default
• 添加音色验证（无效时使用 mimo_default）
• 更新 list_voices() 显示详细音色信息
• 废弃 default_zh 和 default_en

修改（第六轮 - UI 主题化）

• 新增 ratatui 0.26 + crossterm 0.27 依赖
• 新建 src/ui.rs 模块（主题、组件）
• 美化所有 CLI 输出（voices、config、onboard 等）
• 重写 onboard() 为交互式表单页面
• 支持 API Key 隐藏输入（显示 *）
• 所有命令输出统一主题风格
• 使用 crossterm 实现彩色输出（未使用完整 ratatui Terminal）

实施完成（第六轮）

1. ✅ 创建 src/ui.rs 模块（使用 crossterm 美化输出）
2. ✅ 修改 main.rs 引入 ui 模块
3. ✅ 美化 list_voices() 输出（彩色表格）
4. ✅ 美化 show_config() 输出（彩色标签）
5. ✅ 重写 onboard() 为交互式表单（支持密码隐藏输入）
6. ✅ 美化播放和保存完成消息
7. ✅ Release 构建成功（仅有未使用代码警告）
8. ✅ 功能测试通过（voices、show-config）

[0.3.0] - 2026-04-25

新增（守护进程模式）

• ✅ 实现守护进程（Daemon）模式，类似 Docker 架构
• ✅ 创建 src/daemon.rs 模块（TCP Socket 服务器）
  • 使用 tokio::net::TcpListener 监听 TCP 连接
  • 处理客户端 JSON 请求（文本、音色、格式、风格）
  • PID 文件管理（启动/停止/状态检测）
  • 日志记录到 ~/.config/tts/ttsd.log
  • 复用现有 TTS API 调用和音频播放功能
• ✅ 创建 src/client.rs 模块（TCP 客户端）
  • 连接到守护进程并发送 TTS 请求
  • 支持 JSON over TCP 协议
  • 接收并处理守护进程响应
• ✅ 新增 daemon 子命令：
  • daemon start [-d] - 启动守护进程（支持 -d 后台运行）
  • daemon stop - 停止守护进程（无需端口）
  • daemon status - 查看守护进程状态（无需端口）
  • start 支持 --port 参数（默认 9876）
• ✅ 新增 send 子命令：
  • 发送文本到守护进程进行语音合成
  • 支持 --voice、--format、--style 参数
  • 支持 --port 参数（默认 9876）
• ✅ 新增 ttsd 内部子命令（守护进程模式）
  • 由 daemon start -d 自动调用
  • 使用 nohup 实现后台运行（Unix）
• ✅ 跨平台支持：
  • 所有平台统一使用 ~/.config/tts/ 目录
  • TCP Socket 通用方案
• ✅ 协议设计（JSON over TCP）

测试通过（2026-04-25）

• ✅ mimo-tt-s daemon start -d --port 9876 - 后台启动成功
• ✅ mimo-tt-s send --port 9876 "消息" - 发送成功，返回"播放完成"
• ✅ mimo-tt-s daemon status - 状态显示正确
• ✅ mimo-tt-s daemon stop - 停止成功
• ✅ 日志正常记录（~/.config/tts/ttsd.log）

新增（第十二轮 - 日志格式升级）

• ✅ 添加日志级别（自动检测 INFO/WARN/ERROR）
• ✅ 添加 PID 信息
• ✅ 新格式：[时间戳] [级别] [PID] 消息
• ✅ 添加 daemon logs 子命令
  • 支持 --lines N 参数
  • 默认显示 20 行

修改（第十二轮）

• 修改 daemon.rs：
  • 添加 LogLevel 枚举
  • 自动检测消息中的关键词判断级别
  • 新格式：追加到旧日志后面（区分新旧日志）
• 修改 cli.rs：
  • 添加 Logs 变体到 DaemonAction

新日志格式

[2026-04-25 05:48:05] [INFO] [15278] 正在播放音频...
[2026-04-25 05:48:10] [INFO] [15278] 响应: {"status":"ok","message":"播放完成"}

级别自动检测

• INFO - 默认（正常运行信息）
• WARN - 包含"警告"、"注意"
• ERROR - 包含"错误"、"失败"、"无法"

新增（第十三轮 - HTTP 接口）

• ✅ 添加 HTTP 接口（端口 = TCP端口 + 1）
• ✅ tiny_http 依赖
• ✅ POST /synthesize 接口
• ✅ GET /health 健康检查

修改（第十三轮）

• Cargo.toml: 添加 tiny_http
• daemon.rs: 添加 HTTP 服务器函数
• start_daemon: 自动启动 HTTP 服务器

HTTP 接口

地址	方法	说明
http://127.0.0.1:9877/synthesize	POST	语音合成
http://127.0.0.1:9877/health	GET	健康检查

测试通过

• ✅ curl 测试 /synthesize
• ✅ curl 测试 /health
• ✅ mimo-tts send 命令

---

[0.1.0] - 2026-04-24

• ✅ 实现守护进程（Daemon）模式，类似 Docker 架构
• ✅ 创建 src/daemon.rs 模块（TCP Socket 服务器）
  • 使用 tokio::net::TcpListener 监听 TCP 连接
  • 处理客户端 JSON 请求（文本、音色、格式、风格）
  • PID 文件管理（启动/停止/状态检测）
  • 日志记录到 ~/.config/tts/ttsd.log
  • 复用现有 TTS API 调用和音频播放功能
• ✅ 创建 src/client.rs 模块（TCP 客户端）
  • 连接到守护进程并发送 TTS 请求
  • 支持 JSON over TCP 协议
  • 接收并处理守护进程响应
• ✅ 新增 daemon 子命令：
  • daemon start - 启动守护进程
  • daemon stop - 停止守护进程
  • daemon status - 查看守护进程状态
  • 支持 --port 参数（默认 9876）
• ✅ 新增 send 子命令：
  • 发送文本到守护进程进行语音合成
  • 支持 --voice、--format、--style 参数
  • 支持 --port 参数（默认 9876）
• ✅ 跨平台支持：
  • 所有平台统一使用 ~/.config/tts/ 目录
  • TCP Socket 通用方案（Windows/Linux/macOS 均支持）
• ✅ 协议设计（JSON over TCP）：
  • 客户端请求：{"text": "...", "voice": "...", "format": "...", "style": "..."}
  • 服务端响应：{"status": "ok", "message": "..."}
• ✅ style 参数作为宏观场景风格（与文本内 [style] 标签并存）
  • 服务端自动转换为 <style>...</style> 标签（符合官方文档）
  • 支持如"开心"、"东北话"、"唱歌"等风格描述

修改（第十一轮）

• 修改 Cargo.toml：
  • 添加 dirs = "5.0" 依赖（跨平台配置目录）
  • 添加 chrono = "0.4" 依赖（日志时间戳）
• 修改 src/cli.rs：
  • 添加 DaemonCommand 和 DaemonAction 枚举
  • 添加 Send 子命令定义
• 修改 src/main.rs：
  • 声明新模块 daemon 和 client
  • 添加命令分发逻辑

技术细节

• 使用 tokio::spawn 处理多个并发客户端连接
• 使用 serde_json 序列化/反序列化 JSON 协议
• 使用 dirs::home_dir() 获取家目录，拼接配置路径
• PID 文件用于检测守护进程是否运行（跨平台兼容）
• 日志同时输出到文件和控制台
• 播放功能复用现有的 play_audio() 函数
• 守护进程支持 Ctrl+C 优雅停止

---

[0.2.0] - 2026-04-24

新增（第十轮 - 自动语气转换器）

• ✅ 创建 src/tone.rs 独立模块（高内聚低耦合）
• ✅ 实现 apply_tone() 函数（自动语气转换）
• ✅ 实现 insert_mid_tone() 函数（细粒度控制）
• ✅ 实现 analyze_tone() 函数（分析语气）
• ✅ 实现 has_tone_tag() 函数（检测已有标签）
• ✅ 默认启用，无需额外参数
• ✅ 支持整体风格标签 [语气]
• ✅ 支持细粒度控制标签 （描述）

修改（第十轮）

• 修改 main.rs：引入 tone 模块
• 修改 main.rs：在 synthesize() 中调用语气转换

语气映射规则

• ！ → [激动] + ！（激动）
• ？ → [疑惑] + ？（疑惑）
• 。 → [平静] + 。（停顿）
• …… → ……（拖长音）
• 多种标点 → 组合标签如 [激动 疑惑]

技术细节

• 使用 [语气] 格式添加整体风格
• 使用 （描述） 格式添加细粒度控制
• 符合 Mimo-TTS 音频标签控制规范
• 检测已有标签，避免重复添加
• 4 个单元测试全部通过

[0.2.0] - 开发中

新增（第九轮 - 流式输出完成）

• ✅ 实现 --stream 参数功能（流式 API 调用）
• ✅ 使用 SSE（Server-Sent Events）处理流式响应
• ✅ 流式输出时自动使用 pcm16 格式
• ✅ 支持流式输出到 stdout 或保存到文件
• ✅ 修改 api.rs 添加流式请求方法
• ✅ 使用 futures::StreamExt 处理字节流
• ✅ 流式 API 返回原始 PCM16 数据（无 WAV 头）
• ✅ 支持 --stream 和 --play 同时使用
• ✅ 新增 pcm16_to_wav() 函数（自动封装 WAV 头）

修改（第九轮）

• 修改 Cargo.toml：添加 futures、tokio-util 依赖
• 为 reqwest 添加 stream feature
• 修改 main.rs：synthesize() 支持 stream 参数
• 修改 main.rs：支持流式数据播放（PCM16 → WAV）
• 修改 api.rs：修复 read_stream_response 实现

修复（第九轮）

• 修复 StreamReader 编译错误（改用 futures::StreamExt）
• 修复 reqwest stream feature 缺失问题
• 修复播放时未识别 PCM16 格式问题

技术细节

• PCM16 转 WAV：24000Hz, 16bit, 单声道
• WAV 头 44 字节，包含必要的格式信息
• 流式播放时自动添加 WAV 头再播放

新增（第七轮 - 配置分层设计）

• 实现分层配置设计：
  • project.config.toml - 项目默认配置（base_url、default_format）
  • ~/.config/tts/config.toml - 用户配置（api_key、default_voice）
• 用户配置覆盖项目默认配置中的对应项
• 临时文件生成在当前目录（不允许离开当前目录）

修改（第七轮）

• 重写 config.rs 实现分层配置加载
• 修改 cli.rs 移除 base_url 参数
• 修改 ui.rs 简化显示和表单（只处理 api_key 和 default_voice）
• 修改 main.rs 使用新的配置结构
• 更新 project.config.toml 添加 base_url 和 default_format

修复（第七轮）

• 修复默认音色未生效问题（config.rs 默认值改为 mimo_default）
• 修复配置文件只保存用户配置项

[0.1.0] - 2026-04-24