273 lines
6.3 KiB
Markdown
273 lines
6.3 KiB
Markdown
# 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.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 导出**
|
||
- 退出时自动导出
|
||
- 手动导出
|
||
|
||
8. **上下文监控**
|
||
- 新增 `/context` 命令
|
||
- 显示会话 token 使用情况
|
||
- 显示压缩阈值和剩余空间
|
||
|
||
---
|
||
|
||
## 项目配置
|
||
|
||
### project.config.yml
|
||
|
||
配置文件位于项目根目录：
|
||
|
||
```yaml
|
||
# 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`，启动时自动创建。
|
||
|
||
```yaml
|
||
# 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 并发送消息 |
|
||
|
||
### 上下文监控
|
||
|
||
| 输入 | 行为 |
|
||
|------|------|
|
||
| `/context` | 显示当前会话 token 使用情况 |
|
||
|
||
输出示例：
|
||
```
|
||
上下文使用情况
|
||
消息数: 2
|
||
已用: ~5663 / 131072 tokens (5%)
|
||
压缩阈值: 98304 tokens
|
||
压缩进度: 5%
|
||
剩余: ~92641 tokens
|
||
```
|
||
|
||
### 动态提示符
|
||
|
||
- 关闭：`👀 `
|
||
- 开启：`👀 🔊 `
|
||
|
||
### 注意事项
|
||
|
||
- 需要先安装并启动 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 源码
|
||
- 保持代码独立，便于后续版本同步
|
||
- 优先实现核心功能，再考虑增强功能
|
||
- 文档和代码同步更新
|