HxClaw/agents.md

hxclaw AI 行为指南

开发规范

设计原则

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

代码要求

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

交流规范

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

---

项目背景

定位

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

技术栈

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

---

当前任务

v0.3.0 目标

实现聊天记忆体功能：

1. 集成 libSQL (TursoDB) 数据库
2. 实现会话维度的短期记忆
3. 支持向量检索（硅基流动 API）
4. 命令行支持（/new, /memory, /sessions）

---

实现进度

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 等配置

---

v0.3.0 进度

1. 数据库层

   • 集成 libSQL (TursoDB)
   • 创建 sessions 和 chats 表
   • 实现 CRUD 操作
   • 数据库保存在 ~/.config/hxclaw/hxclaw.db

2. 独立上下文系统

   • 创建 GetContextPrompt() 返回会话摘要
   • 注入到 ProcessDirect() 调用前
   • 不再依赖 picoclaw session

3. 向量服务

   • 封装硅基流动 Embedding API
   • 实现向量生成和相似度检索

4. 会话管理

   • 自动创建 Session（首次输入聊天消息时）
   • 手动创建（/new 命令，只是重置 currentSession）
   • LLM 生成摘要（文言文风格）
   • summary_timeout 配置（默认 30 秒）

5. UI 优化

   • 合并状态显示到单行
   • 金色图标 + 灰色文字
   • 暗绿色"会话已保存"/暗红色"保存异常"

6. 双记忆系统合并

   • 读取 picoclaw 的 MEMORY.md 作为长期记忆
   • 合并到 hxclaw 的会话摘要上下文
   • AI 同时看到长期记忆和会话摘要

7. JSON 导出

   • 退出时自动导出
   • 手动导出

---

项目配置

project.config.yml

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

# hxclaw 项目配置文件

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

# Markdown 渲染配置
markdown:
  theme: dark     # 渲染主题：dark, light, dracula, tokyo-night 等
  line_width: -1 # 自动换行宽度（-1=禁用，0=自动，>0=固定宽度）

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

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

# 聊天记忆体配置
memory:
  enabled: true          # 启用开关
  auto_session: true    # 自动创建 Session
  auto_export: true      # 退出时自动导出
  summary_timeout: 30    # 摘要生成超时（秒）
  vector:
    api_key: ""         # 硅基流动 API Key
    base_url: "https://api.siliconflow.cn/v1"
    model: "BAAI/bge-m3"
  recall:
    keywords: ["之前", "聊过", "记得"]
    auto_recall: true
    similarity_threshold: 0.7

配置加载优先级：

1. 环境变量 HXCLAW_CONFIG 指定路径
2. 项目根目录 project.config.yml

---

用户配置

用户配置文件位于 ~/.config/hxclaw/config.yml，启动时自动创建。

# hxclaw 用户配置文件
# 此文件位于 ~/.config/hxclaw/config.yml
# 用户配置优先于项目配置

# Markdown 渲染配置
markdown:
  theme: dark     # 渲染主题
  line_width: 0  # 换行宽度

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

# TTS 语音配置
tts:
  enabled: false # 全局开关
  auto: true     # AI 回复后自动朗读

---

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

go build -o hxclaw ./cmd/hxclaw

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

---

注意事项

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