feat(hands): restructure Hands UI with Chinese localization
Major changes: - Add HandList.tsx component for left sidebar - Add HandTaskPanel.tsx for middle content area - Restructure Sidebar tabs: 分身/HANDS/Workflow - Remove Hands tab from RightPanel - Localize all UI text to Chinese - Archive legacy OpenClaw documentation - Add Hands integration lessons document - Update feature checklist with new components UI improvements: - Left sidebar now shows Hands list with status icons - Middle area shows selected Hand's tasks and results - Consistent styling with Tailwind CSS - Chinese status labels and buttons Documentation: - Create docs/archive/openclaw-legacy/ for old docs - Add docs/knowledge-base/hands-integration-lessons.md - Update docs/knowledge-base/feature-checklist.md - Update docs/knowledge-base/README.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
276
docs/knowledge-base/troubleshooting.md
Normal file
276
docs/knowledge-base/troubleshooting.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# 故障排查指南
|
||||
|
||||
> 记录开发过程中遇到的问题、根因分析和解决方案。
|
||||
|
||||
---
|
||||
|
||||
## 1. 连接问题
|
||||
|
||||
### 1.1 WebSocket 连接失败
|
||||
|
||||
**症状**: `WebSocket connection failed` 或 `Unexpected server response: 400`
|
||||
|
||||
**排查步骤**:
|
||||
|
||||
```bash
|
||||
# 1. 检查 OpenFang 是否运行
|
||||
curl http://127.0.0.1:50051/api/health
|
||||
|
||||
# 2. 检查端口是否正确
|
||||
netstat -ano | findstr "50051"
|
||||
|
||||
# 3. 验证 Agent ID
|
||||
curl http://127.0.0.1:50051/api/agents
|
||||
```
|
||||
|
||||
**常见原因**:
|
||||
|
||||
| 原因 | 解决方案 |
|
||||
|------|----------|
|
||||
| OpenFang 未启动 | `./openfang.exe start` |
|
||||
| 端口错误 | OpenFang 使用 50051，不是 4200 |
|
||||
| Agent ID 无效 | 使用 `/api/agents` 获取真实 UUID |
|
||||
|
||||
### 1.2 端口被占用
|
||||
|
||||
**症状**: `Port 1420 is already in use`
|
||||
|
||||
**解决方案**:
|
||||
|
||||
```bash
|
||||
# Windows - 查找并终止进程
|
||||
netstat -ano | findstr "1420"
|
||||
taskkill /PID <PID> /F
|
||||
|
||||
# 或使用 PowerShell
|
||||
Stop-Process -Id <PID> -Force
|
||||
```
|
||||
|
||||
### 1.3 Vite 代理不工作
|
||||
|
||||
**症状**: 前端请求返回 404 或 CORS 错误
|
||||
|
||||
**检查清单**:
|
||||
|
||||
- [ ] `vite.config.ts` 中配置了 `/api` 代理
|
||||
- [ ] `ws: true` 已启用（WebSocket 需要）
|
||||
- [ ] `changeOrigin: true` 已设置
|
||||
- [ ] 重启 Vite 开发服务器
|
||||
|
||||
---
|
||||
|
||||
## 2. 聊天问题
|
||||
|
||||
### 2.1 LLM API Key 未配置
|
||||
|
||||
**症状**:
|
||||
```
|
||||
Missing API key: No LLM provider configured.
|
||||
Set an API key (e.g. GROQ_API_KEY) and restart
|
||||
```
|
||||
|
||||
**根本原因**: Agent 使用的 LLM 提供商没有配置 API Key
|
||||
|
||||
**解决方案**:
|
||||
|
||||
1. 检查 Agent 使用的提供商：
|
||||
```bash
|
||||
curl -s http://127.0.0.1:50051/api/status | jq '.agents[] | {name, model_provider}'
|
||||
```
|
||||
|
||||
2. 配置对应的 API Key：
|
||||
```bash
|
||||
# 编辑 ~/.openfang/.env
|
||||
echo "ZHIPU_API_KEY=your_key" >> ~/.openfang/.env
|
||||
echo "BAILIAN_API_KEY=your_key" >> ~/.openfang/.env
|
||||
echo "GEMINI_API_KEY=your_key" >> ~/.openfang/.env
|
||||
```
|
||||
|
||||
3. 重启 OpenFang：
|
||||
```bash
|
||||
./openfang.exe restart
|
||||
```
|
||||
|
||||
**快速解决**: 使用已配置的 Agent
|
||||
|
||||
| Agent | 提供商 | 状态 |
|
||||
|-------|--------|------|
|
||||
| General Assistant | zhipu | 通常已配置 |
|
||||
|
||||
### 2.2 流式响应不显示
|
||||
|
||||
**症状**: 消息发送后无响应或响应不完整
|
||||
|
||||
**排查步骤**:
|
||||
|
||||
1. 确认 WebSocket 连接状态：
|
||||
```typescript
|
||||
console.log(client.getState()); // 应为 'connected'
|
||||
```
|
||||
|
||||
2. 检查事件处理：
|
||||
```typescript
|
||||
// 确保处理了 text_delta 事件
|
||||
ws.on('message', (data) => {
|
||||
const event = JSON.parse(data.toString());
|
||||
if (event.type === 'text_delta') {
|
||||
console.log('Delta:', event.content);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
3. 验证消息格式：
|
||||
```javascript
|
||||
// ✅ 正确
|
||||
{ type: 'message', content: 'Hello', session_id: 'xxx' }
|
||||
|
||||
// ❌ 错误
|
||||
{ type: 'chat', message: { role: 'user', content: 'Hello' } }
|
||||
```
|
||||
|
||||
### 2.3 消息格式错误
|
||||
|
||||
**症状**: WebSocket 连接成功，但发送消息后收到错误
|
||||
|
||||
**根本原因**: 使用了文档中的格式，而非实际格式
|
||||
|
||||
**正确的消息格式**:
|
||||
```json
|
||||
{
|
||||
"type": "message",
|
||||
"content": "你的消息内容",
|
||||
"session_id": "唯一会话ID"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 前端问题
|
||||
|
||||
### 3.1 Zustand 状态不更新
|
||||
|
||||
**症状**: UI 不反映状态变化
|
||||
|
||||
**检查**:
|
||||
|
||||
1. 确保使用 selector：
|
||||
```typescript
|
||||
// ✅ 正确 - 使用 selector
|
||||
const messages = useChatStore((state) => state.messages);
|
||||
|
||||
// ❌ 错误 - 可能导致不必要的重渲染
|
||||
const store = useChatStore();
|
||||
const messages = store.messages;
|
||||
```
|
||||
|
||||
2. 检查 immer/persist 配置
|
||||
|
||||
### 3.2 流式消息累积错误
|
||||
|
||||
**症状**: 流式内容显示不正确或重复
|
||||
|
||||
**解决方案**:
|
||||
```typescript
|
||||
onDelta: (delta: string) => {
|
||||
set((state) => ({
|
||||
messages: state.messages.map((m) =>
|
||||
m.id === assistantId
|
||||
? { ...m, content: m.content + delta } // 累积内容
|
||||
: m
|
||||
),
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Tauri 桌面端问题
|
||||
|
||||
### 4.1 Tauri 编译失败
|
||||
|
||||
**常见错误**:
|
||||
- Rust 版本不兼容
|
||||
- 依赖缺失
|
||||
- Cargo.toml 配置错误
|
||||
|
||||
**解决方案**:
|
||||
```bash
|
||||
# 更新 Rust
|
||||
rustup update
|
||||
|
||||
# 清理并重新构建
|
||||
cd desktop/src-tauri
|
||||
cargo clean
|
||||
cargo build
|
||||
```
|
||||
|
||||
### 4.2 Tauri 窗口白屏
|
||||
|
||||
**原因**: Vite 开发服务器未启动或连接失败
|
||||
|
||||
**解决方案**:
|
||||
1. 确保 `pnpm dev` 在运行
|
||||
2. 检查 `tauri.conf.json` 中的 `beforeDevCommand`
|
||||
3. 检查浏览器控制台错误
|
||||
|
||||
### 4.3 Tauri 热重载不工作
|
||||
|
||||
**检查**:
|
||||
- `beforeDevCommand` 配置正确
|
||||
- 文件监听未超出限制（Linux: `fs.inotify.max_user_watches`）
|
||||
|
||||
---
|
||||
|
||||
## 5. 调试技巧
|
||||
|
||||
### 5.1 启用详细日志
|
||||
|
||||
```typescript
|
||||
// gateway-client.ts
|
||||
private log(level: string, message: string, data?: unknown) {
|
||||
if (this.debug) {
|
||||
console.log(`[GatewayClient:${level}]`, message, data || '');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 WebSocket 抓包
|
||||
|
||||
```bash
|
||||
# 使用 wscat 测试
|
||||
npm install -g wscat
|
||||
wscat -c ws://127.0.0.1:50051/api/agents/{agentId}/ws
|
||||
```
|
||||
|
||||
### 5.3 检查 OpenFang 状态
|
||||
|
||||
```bash
|
||||
# 完整状态
|
||||
curl -s http://127.0.0.1:50051/api/status | jq
|
||||
|
||||
# Agent 状态
|
||||
curl -s http://127.0.0.1:50051/api/agents | jq '.[] | {id, name, state}'
|
||||
|
||||
# Hands 状态
|
||||
curl -s http://127.0.0.1:50051/api/hands | jq '.[] | {id, name, requirements_met}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 错误代码参考
|
||||
|
||||
| 错误信息 | 原因 | 解决方案 |
|
||||
|---------|------|----------|
|
||||
| `Port 1420 is already in use` | Vite 服务器已运行 | 终止现有进程 |
|
||||
| `Unexpected server response: 400` | Agent ID 无效 | 使用真实 UUID |
|
||||
| `Missing API key` | LLM 提供商未配置 | 配置 API Key |
|
||||
| `Connection refused` | OpenFang 未运行 | 启动服务 |
|
||||
| `CORS error` | 代理未配置 | 检查 vite.config.ts |
|
||||
|
||||
---
|
||||
|
||||
## 更新历史
|
||||
|
||||
| 日期 | 变更 |
|
||||
|------|------|
|
||||
| 2026-03-14 | 初始版本 |
|
||||
Reference in New Issue
Block a user