NathanAlex7
42ce992a0f
Next.js 前端 + FastAPI/LangChain 后端透明 agent平台 - 含 .gitignore, 敏感文件(sessions数据/.env/venv等)已排除 - 待后续添加 trajectory 自进化机制
353 lines
6.9 KiB
Markdown
353 lines
6.9 KiB
Markdown
# 快速参考手册
|
||
|
||
## 🚀 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`，获得更好的交互体验
|