# 快速参考手册

## 🚀 5 分钟上手

### 第一次使用

```bash
# 1. 一键安装
install.bat

# 2. 启动后端（新终端窗口）
start-backend.bat

# 3. 启动前端（新终端窗口）
start-frontend.bat

# 4. 打开浏览器
http://localhost:3000
```

### 日常使用

```bash
# 终端 1：后端
cd backend
venv\Scripts\activate.bat
uvicorn app:app --host 0.0.0.0 --port 8002

# 终端 2：前端
npm run dev
```

## 📡 API 快速测试

### 健康检查
```bash
curl http://localhost:8002
# 返回: {"name":"mini OpenClaw","version":"0.1.0","status":"running"}
```

### 聊天接口
```bash
curl -X POST http://localhost:8002/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"你好","session_id":"test","stream":false}'
```

### 会话列表
```bash
curl http://localhost:8002/api/sessions
```

### 技能列表
```bash
curl http://localhost:8002/api/skills
```

### RAG 模式开关
```bash
# 查看状态
curl http://localhost:8002/api/config/rag-mode

# 开启 RAG
curl -X PUT http://localhost:8002/api/config/rag-mode \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'
```

## 💬 对话示例

### 基础对话
```
用户: 你好
Agent: 你好！我是 mini OpenClaw，很高兴为你服务 🤖
```

### 使用技能
```
用户: 查询北京的天气
Agent: 
  [工具调用: read_file("skills/get_weather/SKILL.md")]
  [工具调用: fetch_url("https://wttr.in/Beijing?format=j1")]
  北京当前天气：晴，温度 25°C，湿度 40%，东南风 3 级。
```

### 执行命令
```
用户: 列出当前目录的文件
Agent:
  [工具调用: terminal("dir")]
  当前目录包含以下文件：
  - app.py
  - api/
  - graph/
  ...
```

### 运行代码
```
用户: 用 Python 计算 1 到 100 的和
Agent:
  [工具调用: python_repl("sum(range(1, 101))")]
  结果是 5050
```

### 读取文件
```
用户: 读取 config.json 的内容
Agent:
  [工具调用: read_file("config.json")]
  配置文件内容：
  {
    "rag_mode": false
  }
```

## 🛠️ 常用命令

### 后端开发

```bash
# 激活虚拟环境
cd backend
venv\Scripts\activate.bat

# 安装新依赖
pip install package_name
pip freeze > requirements.txt

# 启动开发服务器（自动重载）
uvicorn app:app --host 0.0.0.0 --port 8002 --reload

# 查看日志
# 输出会直接显示在终端
```

### 前端开发

```bash
# 安装新依赖
npm install package_name

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 运行生产版本
npm start
```

### 调试技巧

```bash
# 检查后端是否运行
curl http://localhost:8002

# 检查前端是否运行
curl http://localhost:3000

# 查看 Python 包版本
cd backend
venv\Scripts\activate.bat
pip list

# 查看 Node 包版本
npm list

# 完整测试
test.bat
```

## 📁 关键文件位置

### 配置文件
- `backend/.env` - 环境变量（API key、模型配置）
- `backend/config.json` - 运行时配置（RAG 模式等）

### 身份定义
- `backend/workspace/IDENTITY.md` - Agent 身份信息
- `backend/workspace/AGENTS.md` - 操作指南和协议

### 记忆系统
- `backend/memory/MEMORY.md` - 长期记忆
- `backend/sessions/*.json` - 会话历史

### 技能定义
- `backend/skills/*/SKILL.md` - 各技能的定义文件

## 🔧 常见问题速查

### 后端启动失败

**问题**: `ModuleNotFoundError: No module named 'xxx'`
```bash
# 解决：重新安装依赖
cd backend
venv\Scripts\activate.bat
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

**问题**: `Address already in use`
```bash
# 解决：端口被占用，杀掉进程或换端口
# 查找进程
netstat -ano | findstr :8002
# 杀掉进程
taskkill /PID <进程号> /F
# 或换端口启动
uvicorn app:app --host 0.0.0.0 --port 8003
```

### 前端启动失败

**问题**: `Error: Cannot find module 'next'`
```bash
# 解决：重新安装依赖
npm install --registry=https://registry.npmmirror.com
```

**问题**: 前端无法连接后端
```bash
# 检查：
# 1. 后端是否在 8002 端口运行
curl http://localhost:8002

# 2. 检查浏览器控制台的错误信息

# 3. 确认 src/lib/api.ts 中的 API_BASE 配置正确
```

### 模型调用失败

**问题**: `AuthenticationError` 或 `APIError`
```bash
# 检查 backend/.env 配置：
# 1. DEEPSEEK_API_KEY 是否正确
# 2. DEEPSEEK_BASE_URL 是否可访问
# 3. DEEPSEEK_MODEL 名称是否正确

# 测试网关连通性
curl http://49.232.133.151/v1/models
```

### RAG 检索不工作

```bash
# 1. 确认 RAG 模式已开启
curl http://localhost:8002/api/config/rag-mode

# 2. 重建索引（重启后端会自动重建）
# 或通过代码手动触发：
cd backend
venv\Scripts\activate.bat
python -c "from graph.memory_indexer import get_memory_indexer; from pathlib import Path; get_memory_indexer(Path('.')).rebuild_index()"
```

## 🎯 性能优化建议

### 后端
- 使用 `--workers 4` 启动多进程：`uvicorn app:app --workers 4`
- 开启 uvloop：`pip install uvloop`
- 使用 Redis 缓存会话（TODO）

### 前端
- 生产环境使用 `npm run build` + `npm start`
- 开启 Next.js 静态优化
- 使用 CDN 加速静态资源

### 模型
- 短对话用 `deepseek-v4-flash`（快）
- 复杂任务用 `deepseek-v4-pro`（准）
- 适当调整 `temperature`（创造性 0.7-1.0，精确性 0-0.3）

## 📚 进阶主题

### 自定义技能

创建 `backend/skills/my_skill/SKILL.md`:

```markdown
---
name: my_skill
description: 我的自定义技能
---

# 我的技能

## 使用场景
当用户请求 XXX 时使用

## 执行步骤
1. 步骤一
2. 步骤二
3. 步骤三

## 示例
用户：XXX
Agent：[执行流程]
```

重启后端即可使用。

### 自定义工具

创建 `backend/tools/my_tool.py`:

```python
from langchain_core.tools import tool

@tool
def my_tool(input: str) -> str:
    """工具描述"""
    # 实现
    return result
```

在 `backend/tools/__init__.py` 中注册：

```python
from .my_tool import my_tool

def get_all_tools(base_dir):
    return [
        # ... 其他工具
        my_tool,
    ]
```

### 修改系统提示

编辑 `backend/workspace/IDENTITY.md` 和 `AGENTS.md`，重启后端生效。

## 🔗 相关链接

- **项目文档**: README.md
- **架构说明**: ARCHITECTURE.md
- **开发日志**: DEVLOG.md
- **LangChain 文档**: https://python.langchain.com/
- **LlamaIndex 文档**: https://docs.llamaindex.ai/
- **FastAPI 文档**: https://fastapi.tiangolo.com/
- **Next.js 文档**: https://nextjs.org/docs

## 💡 提示与技巧

1. **技能优先**: 复杂任务先定义技能（SKILL.md），再让 Agent 调用
2. **记忆管理**: 重要信息让 Agent 写入 MEMORY.md，下次对话会记得
3. **会话管理**: 不同主题用不同会话，保持上下文清晰
4. **RAG 模式**: 知识库内容多时开启 RAG，自动检索相关信息
5. **调试模式**: 查看工具调用过程，理解 Agent 的思考路径
6. **流式体验**: 保持 `stream: true`，获得更好的交互体验