148 lines
4.2 KiB
Markdown
148 lines
4.2 KiB
Markdown
# hxclaw 更新日志
|
||
|
||
## 版本记录
|
||
|
||
### v0.1.0 (当前)
|
||
|
||
- [x] 流式输出功能
|
||
- [x] Markdown 渲染功能
|
||
- [x] 配置系统（支持用户配置和项目配置）
|
||
- [x] 代码中文注释
|
||
|
||
---
|
||
|
||
### v0.2.0 (计划)
|
||
|
||
- [ ] 代码块渲染
|
||
- [ ] 表格渲染
|
||
- [ ] 列表渲染
|
||
|
||
### v0.3.0 (计划)
|
||
|
||
- [ ] 代码高亮
|
||
- [ ] 集成 glow 或类似库
|
||
- [ ] 支持常见语言语法高亮
|
||
|
||
---
|
||
|
||
## 认知纠正（踩坑记录）
|
||
|
||
### Go replace 机制不需要发布到 registry
|
||
|
||
**问题**：最初担心需要像 npm 那样发布到 registry 才能被其他项目引用
|
||
|
||
**纠正**：Go 的 replace 机制可以直接指向：
|
||
- 本地路径（如 `../picoclaw`）
|
||
- GitHub 仓库 + tag（如 `github.com/sipeed/picoclaw v0.2.4`）
|
||
|
||
**知识点**：Go 模块不需要发布到任何 registry，GitHub 就是事实上的 registry
|
||
|
||
---
|
||
|
||
### hxclaw 不需要实现全部 picoclaw 功能
|
||
|
||
**问题**：最初担心需要自己实现 onboard、tools、mcp 等全部功能
|
||
|
||
**纠正**：hxclaw 是 CLI 增强层，只替换交互逻辑。picoclaw 的核心功能（agent loop、tools、mcp、skills）通过导入其 pkg 即可复用
|
||
|
||
**知识点**：采用组合优于继承的设计，需要什么功能就导入对应的包
|
||
|
||
---
|
||
|
||
### 流式输出需要判断 Provider 是否支持
|
||
|
||
**问题**：不是所有 Provider 都支持流式输出
|
||
|
||
**纠正**：需要使用类型断言判断 Provider 是否实现 `providers.StreamingProvider` 接口
|
||
|
||
**知识点**：picoclaw 的 Provider 设计使用了接口分离原则，流式是可选能力
|
||
|
||
---
|
||
|
||
### 终端渲染使用 charmbracelet 库
|
||
|
||
**问题**：如何实现 Markdown 终端渲染
|
||
|
||
**纠正**：使用 charmbracelet 家族：
|
||
- glamour：Markdown 渲染
|
||
- lipgloss：样式定义
|
||
|
||
**知识点**：charmbracelet 是 Go 终端UI 的事实标准，API 设计优雅
|
||
|
||
---
|
||
|
||
### 独立二进制部署方式
|
||
|
||
**问题**：hxclaw 和 picoclaw 的关系
|
||
|
||
**纠正**：hxclaw 作为独立二进制，用户可以同时保留两个命令：
|
||
- `picoclaw agent` 使用原版
|
||
- `hxclaw` 使用增强版
|
||
|
||
**知识点**：通过 go.mod replace 实现依赖绑定，用户无需安装 picoclaw 源码
|
||
|
||
---
|
||
|
||
### onChunk 回调接收累积文本导致重复输出
|
||
|
||
**问题**：picoclaw 的 `StreamingProvider` 接口定义 `onChunk func(accumulated string)`，注释说明每次回调时参数是累积的完整文本（如 "你好" → "你好！再次" → "你好！再次见到"），而不是增量。
|
||
|
||
**纠正**：使用 `printedLen` 跟踪已打印位置，只打印新增部分
|
||
|
||
**知识点**：picoclaw 故意设计为累积文本，这样可以在任意时刻获取完整内容用于调试
|
||
|
||
---
|
||
|
||
### spinner 组件的 model 更新必须使用返回值
|
||
|
||
**问题**：spinner 动画不动
|
||
|
||
**现象**：调用 spinner.Update(msg) 后动画不更新
|
||
|
||
**纠正**：spinner model 是值类型，需要使用返回值更新：
|
||
```go
|
||
s.spinner, _ = s.spinner.Update(msg) // 必须使用返回值更新
|
||
```
|
||
|
||
**知识点**：bubbletea v2 的组件遵循 TEA 架构模式，Update 方法返回更新后的 model，需要显式使用返回值。
|
||
|
||
---
|
||
|
||
### spinner 和流式输出在同一行的冲突问题
|
||
|
||
**问题**：spinner 使用 `\r` 回到行首刷新，流式输出也在同一行打印，导致内容混在一起
|
||
|
||
**纠正**：在第一个 token 时停止 spinner，让 spinner 输出 "思考完成." 并换行，然后再开始流式打印
|
||
|
||
**知识点**：spinner 和流式输出需要分时工作，不能同时占用同一行。
|
||
|
||
---
|
||
|
||
### 配置系统设计
|
||
|
||
**问题**：用户需要自定义主题、延迟等配置，但项目配置只有一份
|
||
|
||
**纠正**：设计多级配置系统：
|
||
- 用户配置：`~/.config/hxclaw/config.yml`（优先级最高）
|
||
- 项目配置：`project.config.yml`
|
||
- 环境变量：`HXCLAW_CONFIG` 指定路径
|
||
- 代码默认值
|
||
|
||
**合并规则**：用户配置优先于项目配置，项目配置优先于默认值
|
||
|
||
**实现**：`mergeConfig` 函数实现配置合并逻辑
|
||
|
||
---
|
||
|
||
### 代码注释规范
|
||
|
||
**问题**：代码缺少注释，后续维护困难
|
||
|
||
**纠正**：所有代码添加详细中文注释：
|
||
- 包级别注释
|
||
- 结构体注释
|
||
- 字段注释（使用行内注释 `//`）
|
||
- 函数注释
|
||
- 关键逻辑注释
|
||
|
||
**知识点**：详细注释是团队协作和后续维护的基础 |