HxClaw/agents.md

# hxclaw AI 行为指南

## 开发规范

### 设计原则

- **面向对象 + 设计模式**：所有功能拆分成模块，模块可复用
- **模块化**：每个功能独立成包，包内高内聚，包间低耦合
- **设计模式**：常用单例、工厂、策略模式

### 代码要求

- **注释**：全局使用中文注释，注释内容详细，说明意图和实现逻辑
- **测试**：所有代码需编写单元测试和功能测试，通过后才可交付
- **命名**：变量、函数、文件名使用英文，注释使用中文

### 交流规范

- **语言**：全程使用中文回答和思考
- **问题处理**：一个问题若超过3次尝试仍无法解决，立即停止，告诉用户遇到的问题，询问用户接下来怎么办
- **进度同步**：每次开始编写代码前，更新讨论记录和其他文档

---

## 项目背景

### 定位

- hxclaw 是 picoclaw 的 CLI 增强工具
- 提供流式输出和 Markdown 终端渲染
- 作为独立二进制，与 picoclaw 共存

### 技术栈

- 语言：Go 1.21+
- 依赖：通过 go.mod replace 复用 picoclaw
- 终端库：charmbracelet/lipgloss
- 测试：Go 标准测试框架

---

## 当前任务

### v0.2.0 目标

实现 TTS 语音朗读功能：
1. 集成 mimo-tts client（TCP 连接本地 daemon）
2. 添加配置文件 TTS 开关
3. 实现命令行切换（/tts on/off/status）
4. 实现临时 TTS 前缀（`T 消息`）
5. 动态提示符显示状态（👀 🔊）

---

## 实现进度

### v0.2.0 已完成功能

1. **TTS 语音朗读**
   - 集成 mimo-tts client（TCP 连接）
   - 配置文件开关（tts.enabled）
   - 命令行切换（/tts on/off/status）
   - 临时 TTS 前缀（`T 消息`）
   - 动态提示符显示状态（👀 🔊）
   - 静默失败处理（网络异常时仅记录日志）

2. **流式输出（新流程）**
   - 等待 AI 返回完整响应
   - Markdown 转译
   - 模拟流式输出（从配置读取速度）
   - 效果更好，无残留问题

3. **Markdown 渲染**
   - 使用 glamour 库渲染 Markdown
   - 支持多种主题（dark, light, dracula, tokyo-night 等）
   - 通过 project.config.yml 配置主题

4. **项目配置**
   - 通过 project.config.yml 统一管理配置项
   - 支持流式速度、渲染主题、Logo、TTS 等配置

---

## 项目配置

### project.config.yml

配置文件位于项目根目录：

```yaml
# hxclaw 项目配置文件

# 模拟流式输出配置
streaming:
  line_delay_ms: 1000      # 每行输出后的延迟（毫秒）
  last_line_delay_ms: 600  # 最后一行延迟（毫秒）

# Markdown 渲染配置
markdown:
  glamour_style: dark  # 渲染主题：dark, light, dracula, tokyo-night 等

# UI 配置
ui:
  logo: "🦐"
  user_prefix: "👀 "

# TTS 语音配置
tts:
  enabled: false   # 全局开关（默认关闭）
  port: 9876       # mimo-tts daemon 端口
  auto: true       # AI 回复后自动朗读
```

配置加载优先级：
1. 环境变量 `HXCLAW_CONFIG` 指定路径
2. 项目根目录 `project.config.yml`

---

## TTS 使用指南

### 命令

| 输入 | 行为 |
|------|------|
| `/tts` | 切换 TTS 开关 |
| `/tts on` | 开启 TTS |
| `/tts off` | 关闭 TTS |
| `/tts status` | 显示 TTS 状态 |
| `T 消息` | 临时开启 TTS 并发送消息 |

### 动态提示符

- 关闭：`👀 `
- 开启：`👀 🔊 `

### 注意事项

- 需要先安装并启动 mimo-tts daemon：`mimo-tts daemon start`
- TTS 服务端地址：本地 9876 端口（默认）
- 网络异常时会静默失败，仅记录日志

---

## 依赖管理

### Go 依赖

- `charm.land/glamour/v2` - Markdown 渲染
- `charm.land/lipgloss/v2` - 终端样式
- `charm.land/x/term` - 终端控制
- `github.com/muesli/termenv` - 终端环境工具
- `gopkg.in/yaml.v3` - 配置文件解析
- `github.com/ergochat/readline` - 终端输入

### 配置文件

- `cmd/hxclaw/main.go` - 主入口逻辑
- `cmd/hxclaw/internal/markdown.go` - Markdown 渲染器
- `cmd/hxclaw/internal/helpers.go` - 辅助函数（Readline）
- `cmd/hxclaw/internal/config.go` - 项目配置加载
- `cmd/hxclaw/internal/tts.go` - TTS 客户端

---

## 已知问题

1. **重绘残留**：某些情况下有轻微文本重复（已通过新流程解决）
2. **终端兼容性**：termenv 在某些终端可能不完全工作

---

## 待优化

1. 打印和 TTS 朗读同时进行（而非先打印完再读）
2. 添加更多主题支持
3. 添加命令行参数支持主题选择

---

## 构建命令

picoclaw GitHub地址：https://github.com/sipeed/picoclaw.git

```bash
go build -o hxclaw ./cmd/hxclaw
```

生成的可执行文件位于项目根目录。

---

## 注意事项
- 不要修改 picoclaw 源码
- 保持代码独立，便于后续版本同步
- 优先实现核心功能，再考虑增强功能
- 文档和代码同步更新