haibao-tts-cli/agents.md

项目规范与 AI 规范 (agents.md)

项目规范

代码风格

• 使用 Rust 官方代码风格（rustfmt）
• 所有公开 API 必须包含中文文档注释（///）
• 复杂逻辑必须包含行内中文注释
• 结构体、枚举、trait 使用 PascalCase 命名
• 变量、函数使用 snake_case 命名

架构设计

本项目采用 面向对象 (OOP) + 设计模式 架构：

1. Builder 模式：用于构建复杂的 API 请求对象
2. Strategy 模式：不同音色和音频格式的处理策略
3. Singleton 模式：全局配置管理器（确保配置只加载一次）
4. 封装：每个模块负责单一职责，通过 pub 控制可见性

错误处理

• 使用 anyhow::Result<T> 作为统一返回类型
• 自定义错误类型（如需更精细控制）
• 退出码规范：
  • 0: 成功
  • 1: 参数错误
  • 2: 配置错误（如缺少 API Key）
  • 3: API 调用失败
  • 4: 文件操作失败

文档要求

• 每次，不管是从plan切换到build，还是开始生成代码，都必须先保存上下文到对应的文档，防止丢失操作记录
• 每次操作前必须更新对应文档
• 代码变更同步更新 changelog.md
• 踩坑记录及时写入【认知修正】章节

---

AI 规范

沟通语言

• 全程使用中文与用户沟通
• 代码注释使用中文
• 文档使用中文编写

执行顺序

每次执行任何操作前，按以下顺序更新文档：

1. 更新 taolun.md - 记录本次对话要点
2. 更新 agents.md 的【认知修正】- 如有踩坑
3. 更新 changelog.md - 如有版本变更
4. 执行实际操作

---

认知修正（踩坑记录）

2026-04-24 - 项目初始化

问题：Mimo-TTS API 文档无法直接访问

现象：使用 webfetch 工具访问 https://platform.xiaomimimo.com/docs/ 返回的内容不完整 原因：网站可能有反爬虫机制或需要 JavaScript 渲染 解决方案：通过 websearch 搜索相关内容，从第三方文档（如 DMXAPI、GitHub 项目）获取 API 详细信息 经验：对于无法直接抓取的文档，可以通过搜索引擎找到镜像或第三方整理的资料

问题：API 认证需要双 Header

现象：标准的 OpenAI SDK 方式（仅使用 Authorization Bearer）可能无法正常工作 原因：Mimo-TTS API 要求同时提供 api-key 和 Authorization: Bearer 两个 Header 解决方案：在代码中同时设置两个 Header 经验：阅读 API 文档时要注意认证方式的特殊性，不能假设与标准 OpenAI API 完全一致

2026-04-25 - 守护进程功能开发

问题：clap derive 模式参数传递

现象：--port 参数无法传递给 daemon start 子命令，报错"unexpected argument '--port' found" 原因：在 clap derive 模式中，父命令的参数需要在子命令之前使用，不能放在子命令之后 解决方案：修改 DaemonCommand 为独立结构体，--port 参数定义在父命令级别，使用正确的参数顺序 正确用法：mimo-tts daemon --port 9876 start 错误用法：mimo-tts daemon start --port 9876 经验：clap derive 模式中，参数位置很重要，父命令的参数应该在子命令之前

问题：chrono 依赖缺失

现象：daemon.rs 中使用 chrono::Local::now() 但 Cargo.toml 未添加 chrono 依赖 原因：代码中使用了 chrono 库但忘记在 Cargo.toml 中添加依赖 解决方案：添加 chrono = "0.4" 到 Cargo.toml 经验：每次使用新的外部 crate 时，都要检查 Cargo.toml 中是否已添加对应依赖

问题：style 参数与文本内标签的并存设计

现象：用户要求 style 参数作为宏观场景风格，同时文本内可以包含细粒度风格标签 原因：Mimo-TTS 官方文档支持两种方式：<style>...</style> 标签（宏观）和文本内 [xxx] 标签（细粒度） 解决方案：

• style 参数：按官方文档转换为 <style>...</style> 标签放到文本开头
• 文本内标签：保留原有逻辑（[激动] 等格式）
• 两者可以并存，互不影响 经验：设计 API 时要考虑不同层次的需求，宏观参数和微观标签可以互相补充