chore: mini-openclaw 初始版本

Next.js 前端 + FastAPI/LangChain 后端透明 agent平台 - 含 .gitignore, 敏感文件(sessions数据/.env/venv等)已排除 - 待后续添加 trajectory 自进化机制
2026-09-01 16:40:10 +08:00
parent 73796a6abd
commit 42ce992a0f
76 changed files with 14207 additions and 0 deletions
@@ -0,0 +1,352 @@
+# 快速参考手册
+
+## 🚀 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`，获得更好的交互体验