feat: add AI学习助手 agent (KG+RAG ideal) and renshenguo feishu bot
- Add AI学习助手 agent creation script with all 39 tools, 3-layer KG+RAG memory - Add renshenguo (人参果) feishu bot integration (app_service + ws_handler) - Register renshenguo WS client in main.py startup - Add RENSHENGUO_APP_ID / RENSHENGUO_APP_SECRET / RENSHENGUO_AGENT_ID config - Reorganize docs from root into docs/ subdirectories - Move startup scripts to scripts/startup/ - Various backend optimizations and tool improvements Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
renjianbo
570
docs/integrations/ADB工具和Android日志Agent搭建总结.md
Normal file
570
docs/integrations/ADB工具和Android日志Agent搭建总结.md
Normal file
@@ -0,0 +1,570 @@
|
||||
# ADB工具和Android日志Agent搭建总结
|
||||
|
||||
## ✅ 完成状态
|
||||
|
||||
**任务**: 创建ADB工具和Android日志获取Agent
|
||||
**状态**: ✅ 已完成
|
||||
**完成时间**: 2026-01-23
|
||||
|
||||
---
|
||||
|
||||
## 📋 实现内容
|
||||
|
||||
### 1. ADB日志工具（adb_log）✅
|
||||
|
||||
**文件位置**: `backend/app/services/builtin_tools.py`
|
||||
|
||||
**功能描述**:
|
||||
- 通过ADB命令获取Android设备日志
|
||||
- 支持多种ADB命令类型
|
||||
- 支持日志过滤和级别控制
|
||||
- 支持超时和行数限制
|
||||
|
||||
**支持的命令类型**:
|
||||
|
||||
1. **logcat** - 获取日志
|
||||
- 获取Android设备的logcat日志
|
||||
- 支持按标签过滤（如 `ActivityManager`、`SystemServer`）
|
||||
- 支持按级别过滤（V/D/I/W/E/F/S）
|
||||
- 支持限制返回行数
|
||||
|
||||
2. **devices** - 列出设备
|
||||
- 列出所有连接的Android设备
|
||||
- 显示设备详细信息
|
||||
|
||||
3. **shell** - 执行shell命令（受限）
|
||||
- 只允许执行安全命令
|
||||
- 支持的命令：`getprop`、`dumpsys`、`pm`、`am`、`settings`
|
||||
- 不允许执行危险命令（如 `rm`、`reboot` 等）
|
||||
|
||||
**工具参数**:
|
||||
|
||||
```python
|
||||
async def adb_log_tool(
|
||||
command: str = "logcat", # 命令类型：logcat/devices/shell
|
||||
filter_tag: Optional[str] = None, # 日志标签过滤或shell命令
|
||||
level: Optional[str] = None, # 日志级别：V/D/I/W/E/F/S
|
||||
max_lines: int = 100, # 最大返回行数（1-10000）
|
||||
timeout: int = 10 # 超时时间（秒，1-60）
|
||||
) -> str
|
||||
```
|
||||
|
||||
**工具Schema**:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "adb_log",
|
||||
"description": "执行ADB命令获取Android设备日志。支持logcat（获取日志）、devices（列出设备）、shell（执行shell命令）。可以过滤日志标签和级别。",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"type": "string",
|
||||
"enum": ["logcat", "devices", "shell"],
|
||||
"description": "ADB命令类型",
|
||||
"default": "logcat"
|
||||
},
|
||||
"filter_tag": {
|
||||
"type": "string",
|
||||
"description": "日志标签过滤或shell命令"
|
||||
},
|
||||
"level": {
|
||||
"type": "string",
|
||||
"enum": ["V", "D", "I", "W", "E", "F", "S"],
|
||||
"description": "日志级别过滤"
|
||||
},
|
||||
"max_lines": {
|
||||
"type": "integer",
|
||||
"description": "最大返回行数",
|
||||
"default": 100
|
||||
},
|
||||
"timeout": {
|
||||
"type": "integer",
|
||||
"description": "命令执行超时时间（秒）",
|
||||
"default": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**返回格式**:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"command": "adb logcat -d -t 100",
|
||||
"return_code": 0,
|
||||
"output": "日志内容...",
|
||||
"output_lines": 100,
|
||||
"error": null,
|
||||
"timestamp": "2026-01-23T11:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
**安全特性**:
|
||||
- ✅ 超时控制（防止长时间执行）
|
||||
- ✅ 行数限制（防止输出过长）
|
||||
- ✅ Shell命令白名单（只允许安全命令）
|
||||
- ✅ 错误处理和日志记录
|
||||
|
||||
---
|
||||
|
||||
### 2. 工具注册 ✅
|
||||
|
||||
**文件位置**: `backend/app/main.py`
|
||||
|
||||
**注册代码**:
|
||||
|
||||
```python
|
||||
from app.services.builtin_tools import (
|
||||
adb_log_tool,
|
||||
ADB_LOG_SCHEMA
|
||||
)
|
||||
|
||||
tool_registry.register_builtin_tool("adb_log", adb_log_tool, ADB_LOG_SCHEMA)
|
||||
```
|
||||
|
||||
**注册状态**: ✅ 已注册（共10个内置工具）
|
||||
|
||||
---
|
||||
|
||||
### 3. Android日志获取助手Agent ✅
|
||||
|
||||
**文件位置**: `backend/scripts/generate_android_log_agent.py`
|
||||
|
||||
**Agent信息**:
|
||||
- **Agent ID**: `b68e96d2-da66-4402-86a5-9fae6b5ac092`
|
||||
- **Agent名称**: `Android日志获取助手`
|
||||
- **工作流ID**: `4df28591-7d47-403e-b7dc-9fc298b79527`
|
||||
- **描述**: 通过ADB命令获取和分析Android设备日志的智能助手。支持获取logcat日志、列出设备、执行shell命令等功能。
|
||||
|
||||
**工作流结构**:
|
||||
|
||||
```
|
||||
开始 → 意图识别 → JSON解析 → LLM工具调用 → 结束
|
||||
```
|
||||
|
||||
**节点详情**:
|
||||
|
||||
1. **开始节点** (`start`)
|
||||
- 接收用户输入
|
||||
- 输入格式: `{"query": "用户请求"}`
|
||||
|
||||
2. **意图识别节点** (`intent-recognize`)
|
||||
- 类型: LLM节点
|
||||
- 模型: deepseek-chat
|
||||
- 功能: 分析用户请求，提取ADB命令参数
|
||||
- 输出格式: JSON
|
||||
```json
|
||||
{
|
||||
"command": "logcat|devices|shell",
|
||||
"filter_tag": "标签或shell命令（可选）",
|
||||
"level": "V|D|I|W|E|F|S（可选）",
|
||||
"max_lines": 100
|
||||
}
|
||||
```
|
||||
|
||||
3. **JSON解析节点** (`json-parse`)
|
||||
- 类型: JSON节点
|
||||
- 功能: 解析意图识别的结果
|
||||
- 操作: parse
|
||||
|
||||
4. **LLM工具调用节点** (`llm-with-tools`)
|
||||
- 类型: LLM节点（启用工具调用）
|
||||
- 模型: deepseek-chat
|
||||
- 启用工具: `adb_log`
|
||||
- 功能: 根据解析的参数调用adb_log工具，分析日志内容
|
||||
|
||||
5. **结束节点** (`end`)
|
||||
- 返回最终结果
|
||||
|
||||
**工作流配置**:
|
||||
|
||||
```json
|
||||
{
|
||||
"nodes": [
|
||||
{
|
||||
"id": "start",
|
||||
"type": "start",
|
||||
"position": {"x": 100, "y": 200},
|
||||
"data": {"label": "开始"}
|
||||
},
|
||||
{
|
||||
"id": "intent-recognize",
|
||||
"type": "llm",
|
||||
"position": {"x": 400, "y": 200},
|
||||
"data": {
|
||||
"label": "意图识别",
|
||||
"provider": "deepseek",
|
||||
"model": "deepseek-chat",
|
||||
"temperature": 0.3,
|
||||
"max_tokens": 200,
|
||||
"prompt": "分析用户请求，提取ADB命令参数..."
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "json-parse",
|
||||
"type": "json",
|
||||
"position": {"x": 700, "y": 200},
|
||||
"data": {
|
||||
"label": "解析参数",
|
||||
"operation": "parse",
|
||||
"json_path": "$"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "llm-with-tools",
|
||||
"type": "llm",
|
||||
"position": {"x": 1000, "y": 200},
|
||||
"data": {
|
||||
"label": "执行ADB命令",
|
||||
"provider": "deepseek",
|
||||
"model": "deepseek-chat",
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 2000,
|
||||
"enable_tools": true,
|
||||
"selected_tools": ["adb_log"],
|
||||
"prompt": "根据解析的参数，使用adb_log工具获取Android设备日志..."
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "end",
|
||||
"type": "end",
|
||||
"position": {"x": 1300, "y": 200},
|
||||
"data": {"label": "结束"}
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"id": "e1",
|
||||
"source": "start",
|
||||
"target": "intent-recognize"
|
||||
},
|
||||
{
|
||||
"id": "e2",
|
||||
"source": "intent-recognize",
|
||||
"target": "json-parse"
|
||||
},
|
||||
{
|
||||
"id": "e3",
|
||||
"source": "json-parse",
|
||||
"target": "llm-with-tools"
|
||||
},
|
||||
{
|
||||
"id": "e4",
|
||||
"source": "llm-with-tools",
|
||||
"target": "end"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 使用说明
|
||||
|
||||
### 1. 环境要求
|
||||
|
||||
**ADB环境**:
|
||||
- 需要安装 Android SDK Platform Tools
|
||||
- 需要将 `adb` 命令添加到 PATH
|
||||
- 需要连接 Android 设备或启动模拟器
|
||||
|
||||
**验证ADB环境**:
|
||||
```bash
|
||||
adb version
|
||||
adb devices
|
||||
```
|
||||
|
||||
### 2. 测试Agent
|
||||
|
||||
**使用测试工具**:
|
||||
```bash
|
||||
# 获取最近的错误日志
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取最近的错误日志"}'
|
||||
|
||||
# 列出所有连接的设备
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "列出所有连接的设备"}'
|
||||
|
||||
# 获取ActivityManager的日志
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取ActivityManager的日志"}'
|
||||
|
||||
# 获取特定级别的日志
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取错误级别的日志"}'
|
||||
```
|
||||
|
||||
**通过API调用**:
|
||||
```bash
|
||||
curl -X POST http://localhost:8037/api/v1/agents/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-d '{
|
||||
"agent_id": "b68e96d2-da66-4402-86a5-9fae6b5ac092",
|
||||
"input_data": {
|
||||
"query": "获取最近的错误日志"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### 3. 在前端使用
|
||||
|
||||
1. 打开 Agent 管理页面
|
||||
2. 找到 "Android日志获取助手"
|
||||
3. 点击"测试"或"执行"
|
||||
4. 输入查询请求，例如：
|
||||
- "获取最近的错误日志"
|
||||
- "列出所有连接的设备"
|
||||
- "获取ActivityManager的日志"
|
||||
|
||||
---
|
||||
|
||||
## 📊 功能特点
|
||||
|
||||
### 1. 智能意图识别
|
||||
- 自动分析用户请求
|
||||
- 提取ADB命令参数
|
||||
- 支持自然语言输入
|
||||
|
||||
### 2. 灵活的日志过滤
|
||||
- 按标签过滤（如 `ActivityManager`、`SystemServer`）
|
||||
- 按级别过滤（V/D/I/W/E/F/S）
|
||||
- 可限制返回行数
|
||||
|
||||
### 3. 安全控制
|
||||
- Shell命令白名单
|
||||
- 超时控制
|
||||
- 行数限制
|
||||
- 错误处理
|
||||
|
||||
### 4. 智能分析
|
||||
- 自动分析日志内容
|
||||
- 提取关键信息
|
||||
- 生成总结报告
|
||||
|
||||
---
|
||||
|
||||
## 🔧 技术实现
|
||||
|
||||
### 1. 工具实现
|
||||
|
||||
**核心技术**:
|
||||
- `subprocess` - 执行系统命令
|
||||
- `asyncio` - 异步执行和超时控制
|
||||
- `json` - 结果格式化
|
||||
|
||||
**关键代码**:
|
||||
```python
|
||||
async def adb_log_tool(
|
||||
command: str = "logcat",
|
||||
filter_tag: Optional[str] = None,
|
||||
level: Optional[str] = None,
|
||||
max_lines: int = 100,
|
||||
timeout: int = 10
|
||||
) -> str:
|
||||
# 构建adb命令
|
||||
if command == "logcat":
|
||||
adb_cmd = ["adb", "logcat", "-d"]
|
||||
if level:
|
||||
adb_cmd.extend([f"*:{level}"])
|
||||
if filter_tag:
|
||||
adb_cmd.append(filter_tag)
|
||||
adb_cmd.extend(["-t", str(max_lines)])
|
||||
# ...
|
||||
|
||||
# 异步执行命令
|
||||
result = await asyncio.wait_for(
|
||||
asyncio.to_thread(_execute_adb),
|
||||
timeout=timeout + 2
|
||||
)
|
||||
|
||||
# 返回JSON格式结果
|
||||
return json.dumps({...}, ensure_ascii=False)
|
||||
```
|
||||
|
||||
### 2. Agent工作流
|
||||
|
||||
**工作流设计**:
|
||||
- 使用LLM进行意图识别
|
||||
- 使用JSON节点解析参数
|
||||
- 使用LLM工具调用执行ADB命令
|
||||
- 自动分析和总结结果
|
||||
|
||||
**数据流**:
|
||||
```
|
||||
用户输入 → 意图识别 → JSON解析 → 工具调用 → 结果分析 → 输出
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 使用示例
|
||||
|
||||
### 示例1: 获取错误日志
|
||||
|
||||
**输入**:
|
||||
```json
|
||||
{
|
||||
"query": "获取最近的错误日志"
|
||||
}
|
||||
```
|
||||
|
||||
**处理流程**:
|
||||
1. 意图识别: 提取 `command=logcat`, `level=E`
|
||||
2. JSON解析: 解析参数
|
||||
3. 工具调用: `adb_log(command="logcat", level="E", max_lines=100)`
|
||||
4. 结果分析: 分析错误日志，提取关键信息
|
||||
|
||||
**输出**:
|
||||
```
|
||||
已获取最近的错误日志，共发现3个错误：
|
||||
|
||||
1. [2026-01-23 10:30:15] ActivityManager: 应用崩溃
|
||||
- 包名: com.example.app
|
||||
- 错误类型: NullPointerException
|
||||
|
||||
2. [2026-01-23 10:31:20] SystemServer: 服务启动失败
|
||||
- 服务名: MediaService
|
||||
- 错误原因: 权限不足
|
||||
|
||||
3. [2026-01-23 10:32:05] NetworkManager: 网络连接失败
|
||||
- 错误类型: ConnectionTimeout
|
||||
- 建议: 检查网络配置
|
||||
```
|
||||
|
||||
### 示例2: 列出设备
|
||||
|
||||
**输入**:
|
||||
```json
|
||||
{
|
||||
"query": "列出所有连接的设备"
|
||||
}
|
||||
```
|
||||
|
||||
**处理流程**:
|
||||
1. 意图识别: 提取 `command=devices`
|
||||
2. JSON解析: 解析参数
|
||||
3. 工具调用: `adb_log(command="devices")`
|
||||
4. 结果分析: 格式化设备列表
|
||||
|
||||
**输出**:
|
||||
```
|
||||
已找到2个连接的设备：
|
||||
|
||||
1. emulator-5554
|
||||
- 状态: device
|
||||
- 型号: Android SDK built for x86
|
||||
|
||||
2. 192.168.1.100:5555
|
||||
- 状态: device
|
||||
- 型号: SM-G991B
|
||||
```
|
||||
|
||||
### 示例3: 获取特定标签日志
|
||||
|
||||
**输入**:
|
||||
```json
|
||||
{
|
||||
"query": "获取ActivityManager的日志"
|
||||
}
|
||||
```
|
||||
|
||||
**处理流程**:
|
||||
1. 意图识别: 提取 `command=logcat`, `filter_tag=ActivityManager`
|
||||
2. JSON解析: 解析参数
|
||||
3. 工具调用: `adb_log(command="logcat", filter_tag="ActivityManager", max_lines=100)`
|
||||
4. 结果分析: 分析ActivityManager日志
|
||||
|
||||
**输出**:
|
||||
```
|
||||
已获取ActivityManager日志，共100行：
|
||||
|
||||
关键活动：
|
||||
- 应用启动: com.example.app (10:30:15)
|
||||
- Activity切换: MainActivity → SettingsActivity (10:31:20)
|
||||
- 应用关闭: com.example.app (10:32:05)
|
||||
|
||||
性能指标：
|
||||
- 平均启动时间: 1.2秒
|
||||
- Activity切换次数: 15次
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
### 1. ADB环境要求
|
||||
- ✅ 必须安装 Android SDK Platform Tools
|
||||
- ✅ 必须将 `adb` 命令添加到 PATH
|
||||
- ✅ 必须连接 Android 设备或启动模拟器
|
||||
|
||||
### 2. 安全限制
|
||||
- ✅ Shell命令只允许执行安全命令
|
||||
- ✅ 不允许执行危险命令（如 `rm`、`reboot` 等）
|
||||
- ✅ 超时控制防止长时间执行
|
||||
- ✅ 行数限制防止输出过长
|
||||
|
||||
### 3. 性能优化
|
||||
- ✅ 默认限制返回100行日志
|
||||
- ✅ 支持超时控制（默认10秒）
|
||||
- ✅ 异步执行避免阻塞
|
||||
|
||||
### 4. 错误处理
|
||||
- ✅ 处理ADB命令执行失败
|
||||
- ✅ 处理设备未连接情况
|
||||
- ✅ 处理超时情况
|
||||
- ✅ 详细的错误信息返回
|
||||
|
||||
---
|
||||
|
||||
## 🚀 扩展建议
|
||||
|
||||
### 1. 功能扩展
|
||||
- [ ] 支持实时日志监控（logcat -c）
|
||||
- [ ] 支持日志保存到文件
|
||||
- [ ] 支持日志搜索和过滤
|
||||
- [ ] 支持多设备管理
|
||||
- [ ] 支持日志分析和统计
|
||||
|
||||
### 2. 安全增强
|
||||
- [ ] 添加用户权限控制
|
||||
- [ ] 添加命令执行审计
|
||||
- [ ] 添加设备访问控制
|
||||
- [ ] 添加日志访问记录
|
||||
|
||||
### 3. 性能优化
|
||||
- [ ] 支持日志缓存
|
||||
- [ ] 支持增量获取
|
||||
- [ ] 支持并行处理
|
||||
- [ ] 支持结果压缩
|
||||
|
||||
---
|
||||
|
||||
## 📊 统计信息
|
||||
|
||||
- **工具数量**: 1个（adb_log）
|
||||
- **Agent数量**: 1个（Android日志获取助手）
|
||||
- **工作流节点数**: 5个
|
||||
- **代码行数**: 约200行（工具实现）+ 约150行（Agent脚本）
|
||||
- **完成时间**: 2026-01-23
|
||||
|
||||
---
|
||||
|
||||
## 🎉 总结
|
||||
|
||||
本次实现了完整的ADB工具和Android日志获取Agent，包括：
|
||||
|
||||
1. ✅ **ADB日志工具** - 功能完整、安全可靠
|
||||
2. ✅ **工具注册** - 已集成到工具注册表
|
||||
3. ✅ **Agent工作流** - 智能意图识别和工具调用
|
||||
4. ✅ **文档完善** - 使用说明和示例齐全
|
||||
|
||||
Agent已经可以正常使用，支持通过自然语言请求获取Android设备日志，并自动分析和总结结果。
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-01-23
|
||||
**文档版本**: v1.0
|
||||
**状态**: 已完成 ✅
|
||||
213
docs/integrations/ADB工具验证方法.md
Normal file
213
docs/integrations/ADB工具验证方法.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# ADB工具验证方法
|
||||
|
||||
本文档介绍如何验证 `adb_log` 工具是否可以正常调用 ADB 命令。
|
||||
|
||||
## 方法一：使用测试脚本（推荐）
|
||||
|
||||
### 1. 运行测试脚本
|
||||
|
||||
```bash
|
||||
cd /home/renjianbo/aiagent
|
||||
python test_adb_tool.py
|
||||
```
|
||||
|
||||
### 2. 测试内容
|
||||
|
||||
脚本会自动测试以下功能：
|
||||
|
||||
- ✅ **列出设备** (`adb devices`)
|
||||
- ✅ **获取最近日志** (`adb logcat -d -t 10`)
|
||||
- ✅ **获取错误级别日志** (`adb logcat -d *:E -t 5`)
|
||||
- ✅ **执行shell命令** (`adb shell getprop ro.build.version.release`)
|
||||
- ✅ **错误处理** (验证无效命令的处理)
|
||||
|
||||
### 3. 预期结果
|
||||
|
||||
如果所有测试通过，说明 ADB 工具工作正常。
|
||||
|
||||
## 方法二：通过前端单节点测试
|
||||
|
||||
### 1. 准备工作
|
||||
|
||||
1. 打开工作流编辑器
|
||||
2. 找到或创建一个包含 `adb_log` 工具的 LLM 节点
|
||||
3. 确保节点已启用工具调用并选择了 `adb_log` 工具
|
||||
|
||||
### 2. 测试步骤
|
||||
|
||||
1. **选中节点**：点击 "执行ADB命令" 节点
|
||||
2. **输入测试数据**：在测试输入框中输入：
|
||||
```json
|
||||
{
|
||||
"query": "列出设备"
|
||||
}
|
||||
```
|
||||
或
|
||||
```json
|
||||
{
|
||||
"query": "获取最近日志"
|
||||
}
|
||||
```
|
||||
3. **运行测试**：点击 "运行测试" 按钮
|
||||
4. **查看结果**：检查执行结果中是否包含实际的 ADB 命令输出
|
||||
|
||||
### 3. 验证要点
|
||||
|
||||
- ✅ LLM 正确识别用户意图
|
||||
- ✅ LLM 调用了 `adb_log` 工具（不是生成文本）
|
||||
- ✅ 工具返回了真实的 ADB 命令结果
|
||||
- ✅ 结果中包含设备信息或日志内容
|
||||
|
||||
## 方法三：通过 Agent 测试
|
||||
|
||||
### 1. 使用 "Android日志获取助手" Agent
|
||||
|
||||
1. 打开 Agent 列表
|
||||
2. 找到 "Android日志获取助手"
|
||||
3. 点击运行
|
||||
|
||||
### 2. 测试命令
|
||||
|
||||
尝试以下输入：
|
||||
|
||||
- `列出设备`
|
||||
- `获取最近日志`
|
||||
- `获取错误日志`
|
||||
- `获取最近10条日志`
|
||||
|
||||
### 3. 查看执行详情
|
||||
|
||||
1. 在 Agent 执行结果页面，点击 "查看详情"
|
||||
2. 检查执行日志，确认：
|
||||
- ✅ 工具调用记录存在
|
||||
- ✅ 工具参数正确（command, max_lines 等）
|
||||
- ✅ 工具返回了真实结果
|
||||
|
||||
## 方法四：直接调用工具函数（开发调试）
|
||||
|
||||
### 1. Python 交互式测试
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
import json
|
||||
import sys
|
||||
sys.path.insert(0, 'backend')
|
||||
|
||||
from app.services.builtin_tools import adb_log_tool
|
||||
|
||||
# 测试列出设备
|
||||
result = asyncio.run(adb_log_tool(command="devices"))
|
||||
print(json.loads(result))
|
||||
|
||||
# 测试获取日志
|
||||
result = asyncio.run(adb_log_tool(command="logcat", max_lines=5))
|
||||
print(json.loads(result))
|
||||
```
|
||||
|
||||
### 2. 验证工具注册
|
||||
|
||||
```python
|
||||
from app.services.tool_registry import tool_registry
|
||||
|
||||
# 检查工具是否已注册
|
||||
schema = tool_registry.get_tool_schema("adb_log")
|
||||
print(schema)
|
||||
|
||||
# 检查工具函数是否存在
|
||||
func = tool_registry.get_tool_function("adb_log")
|
||||
print(func)
|
||||
```
|
||||
|
||||
## 常见问题排查
|
||||
|
||||
### 问题1：测试脚本报错 "未找到adb命令"
|
||||
|
||||
**原因**：ADB 未安装或不在 PATH 中
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 检查 adb 是否安装
|
||||
which adb
|
||||
|
||||
# 如果未安装，安装 Android SDK Platform Tools
|
||||
# Ubuntu/Debian:
|
||||
sudo apt-get install android-tools-adb
|
||||
|
||||
# 或下载 Platform Tools:
|
||||
# https://developer.android.com/studio/releases/platform-tools
|
||||
```
|
||||
|
||||
### 问题2：测试返回 "未找到设备"
|
||||
|
||||
**原因**：没有连接 Android 设备或模拟器
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 检查设备连接
|
||||
adb devices
|
||||
|
||||
# 如果显示 "no devices"，请：
|
||||
# 1. 连接 Android 设备并启用 USB 调试
|
||||
# 2. 或启动 Android 模拟器
|
||||
```
|
||||
|
||||
### 问题3：LLM 不调用工具，返回文本响应
|
||||
|
||||
**原因**：LLM 可能误解了用户意图或提示词配置不当
|
||||
|
||||
**解决方案**：
|
||||
1. 检查节点配置中的提示词是否明确要求调用工具
|
||||
2. 确保工具已正确选择并启用
|
||||
3. 在单节点测试时，确保输入数据格式正确
|
||||
4. 查看后端日志，检查工具调用请求
|
||||
|
||||
### 问题4：工具调用超时
|
||||
|
||||
**原因**：ADB 命令执行时间过长
|
||||
|
||||
**解决方案**：
|
||||
- 减少 `max_lines` 参数（默认100行）
|
||||
- 增加 `timeout` 参数（默认10秒，最大60秒）
|
||||
- 使用更具体的过滤条件（filter_tag, level）
|
||||
|
||||
## 验证清单
|
||||
|
||||
在验证 ADB 工具时，请确认：
|
||||
|
||||
- [ ] ADB 已正确安装并在 PATH 中
|
||||
- [ ] 至少有一个 Android 设备已连接（或模拟器运行中）
|
||||
- [ ] `adb devices` 命令可以列出设备
|
||||
- [ ] 测试脚本可以成功执行
|
||||
- [ ] 单节点测试可以调用工具并返回结果
|
||||
- [ ] Agent 可以正确使用工具
|
||||
- [ ] 工具调用可视化功能正常显示工具调用过程
|
||||
|
||||
## 快速验证命令
|
||||
|
||||
```bash
|
||||
# 1. 检查 ADB 安装
|
||||
adb version
|
||||
|
||||
# 2. 检查设备连接
|
||||
adb devices -l
|
||||
|
||||
# 3. 测试获取日志（命令行）
|
||||
adb logcat -d -t 5
|
||||
|
||||
# 4. 运行测试脚本
|
||||
python test_adb_tool.py
|
||||
```
|
||||
|
||||
## 成功标志
|
||||
|
||||
✅ **工具工作正常**的标志：
|
||||
|
||||
1. 测试脚本所有测试通过
|
||||
2. 单节点测试返回真实的 ADB 命令结果（不是 LLM 生成的文本）
|
||||
3. 执行日志中可以看到工具调用记录
|
||||
4. 工具调用可视化显示工具被正确调用
|
||||
5. Agent 可以成功获取设备日志
|
||||
|
||||
---
|
||||
|
||||
**提示**：如果遇到问题，请查看后端日志 (`docker-compose logs backend`) 获取详细错误信息。
|
||||
162
docs/integrations/Android日志Agent问题分析.md
Normal file
162
docs/integrations/Android日志Agent问题分析.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# Android日志获取助手问题分析
|
||||
|
||||
## 📊 问题描述
|
||||
|
||||
用户在前端使用"Android日志获取助手"，输入"获取最近日志"，Agent返回了详细内容，但存在以下问题：
|
||||
|
||||
### ⚠️ 发现的问题
|
||||
|
||||
1. **命令格式错误**
|
||||
- Agent返回的命令：`adb_log --command "recent"`
|
||||
- 实际adb_log工具支持的命令：`logcat`、`devices`、`shell`
|
||||
- `recent` 不是有效的命令类型
|
||||
|
||||
2. **日志日期异常**
|
||||
- 返回的日志日期：2024-01-15
|
||||
- 当前实际日期：2026-01-23
|
||||
- 明显是示例数据，不是真实日志
|
||||
|
||||
3. **返回内容特征**
|
||||
- 返回内容非常完整，包含详细的分析和总结
|
||||
- 格式过于规范，像是LLM生成的示例
|
||||
- 而不是实际调用adb_log工具执行后的真实结果
|
||||
|
||||
### 🔍 可能的原因
|
||||
|
||||
1. **LLM没有实际调用工具**
|
||||
- LLM可能根据工具描述生成了示例响应
|
||||
- 而不是真正调用adb_log工具执行命令
|
||||
|
||||
2. **工具调用参数错误**
|
||||
- LLM可能传递了错误的参数（如`command="recent"`）
|
||||
- 导致工具调用失败，LLM生成了示例响应
|
||||
|
||||
3. **工具调用未执行**
|
||||
- 工具调用请求可能没有正确发送
|
||||
- 或者工具执行失败，LLM用示例内容填充
|
||||
|
||||
---
|
||||
|
||||
## ✅ 正确的行为应该是
|
||||
|
||||
### 1. 工具调用参数
|
||||
|
||||
对于"获取最近日志"的请求，应该：
|
||||
- `command`: `"logcat"`（不是"recent"）
|
||||
- `max_lines`: `100`（默认值）
|
||||
- `level`: 可选（如需要过滤级别）
|
||||
- `filter_tag`: 可选（如需要过滤标签）
|
||||
|
||||
### 2. 实际执行流程
|
||||
|
||||
```
|
||||
用户输入: "获取最近日志"
|
||||
↓
|
||||
意图识别: 提取参数 {command: "logcat", max_lines: 100}
|
||||
↓
|
||||
工具调用: adb_log(command="logcat", max_lines=100)
|
||||
↓
|
||||
实际执行: adb logcat -d -t 100
|
||||
↓
|
||||
返回结果: JSON格式的真实日志数据
|
||||
↓
|
||||
LLM分析: 基于真实日志数据进行分析
|
||||
```
|
||||
|
||||
### 3. 预期返回格式
|
||||
|
||||
应该返回类似这样的真实结果：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"command": "adb logcat -d -t 100",
|
||||
"return_code": 0,
|
||||
"output": "真实的日志内容...",
|
||||
"output_lines": 100,
|
||||
"timestamp": "2026-01-23T15:30:00"
|
||||
}
|
||||
```
|
||||
|
||||
然后LLM基于这个真实结果进行分析。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 解决方案
|
||||
|
||||
### 方案1: 检查工具调用日志
|
||||
|
||||
在前端执行详情页面：
|
||||
1. 打开执行详情
|
||||
2. 点击"执行ADB命令"节点
|
||||
3. 查看"工具调用"卡片
|
||||
4. 检查是否有工具调用记录
|
||||
5. 查看工具调用的参数和结果
|
||||
|
||||
### 方案2: 改进意图识别
|
||||
|
||||
修改意图识别节点的prompt，确保：
|
||||
- 正确识别"获取最近日志" → `command="logcat"`
|
||||
- 不要生成无效的命令类型
|
||||
|
||||
### 方案3: 增强工具调用提示
|
||||
|
||||
在LLM工具调用节点的prompt中：
|
||||
- 明确要求必须调用工具
|
||||
- 不要生成示例内容
|
||||
- 必须基于工具返回的真实结果进行分析
|
||||
|
||||
### 方案4: 检查工具调用配置
|
||||
|
||||
确认Agent配置：
|
||||
- ✅ 启用工具调用：`enable_tools: true`
|
||||
- ✅ 选中工具：`selected_tools: ["adb_log"]`
|
||||
- ✅ 工具配置正确传递
|
||||
|
||||
---
|
||||
|
||||
## 📝 测试建议
|
||||
|
||||
### 测试1: 使用更明确的输入
|
||||
|
||||
```json
|
||||
{
|
||||
"query": "请使用adb_log工具获取最近的100行日志"
|
||||
}
|
||||
```
|
||||
|
||||
### 测试2: 检查工具调用可视化
|
||||
|
||||
1. 执行Agent后，查看执行详情
|
||||
2. 检查"工具调用"卡片
|
||||
3. 确认是否有工具调用记录
|
||||
4. 查看工具调用的参数和结果
|
||||
|
||||
### 测试3: 查看后端日志
|
||||
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml logs backend | grep -E "执行工具|adb_log|tool_call"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 结论
|
||||
|
||||
**当前状态**: ⚠️ Agent可能没有真正调用adb_log工具，而是生成了示例响应
|
||||
|
||||
**需要验证**:
|
||||
1. ✅ 检查执行详情中的工具调用记录
|
||||
2. ✅ 确认工具是否被实际调用
|
||||
3. ✅ 查看工具调用的参数是否正确
|
||||
4. ✅ 检查工具执行结果
|
||||
|
||||
**建议操作**:
|
||||
1. 在前端执行详情页面查看工具调用可视化
|
||||
2. 如果工具没有调用，检查Agent配置和prompt
|
||||
3. 如果工具调用了但参数错误，改进意图识别
|
||||
4. 如果工具执行失败，查看错误日志
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-01-23
|
||||
**状态**: 需要进一步验证
|
||||
473
docs/integrations/Android日志获取助手使用指南.md
Normal file
473
docs/integrations/Android日志获取助手使用指南.md
Normal file
@@ -0,0 +1,473 @@
|
||||
# Android日志获取助手使用指南
|
||||
|
||||
## 📖 简介
|
||||
|
||||
**Android日志获取助手**是一个智能Agent，可以通过自然语言请求获取和分析Android设备日志。它使用ADB（Android Debug Bridge）命令与Android设备通信，支持获取logcat日志、列出设备、执行shell命令等功能。
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 环境准备
|
||||
|
||||
**必需条件**:
|
||||
- ✅ 已安装 Android SDK Platform Tools
|
||||
- ✅ `adb` 命令已添加到系统PATH
|
||||
- ✅ Android设备已连接或模拟器已启动
|
||||
|
||||
**验证ADB环境**:
|
||||
```bash
|
||||
# 检查ADB版本
|
||||
adb version
|
||||
|
||||
# 检查设备连接
|
||||
adb devices
|
||||
```
|
||||
|
||||
**预期输出**:
|
||||
```
|
||||
List of devices attached
|
||||
emulator-5554 device
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💻 使用方式
|
||||
|
||||
### 方式1: 前端界面使用（推荐）
|
||||
|
||||
**步骤**:
|
||||
1. 打开平台前端页面: `http://101.43.95.130:8038`
|
||||
2. 登录系统
|
||||
3. 进入 **Agent管理** 页面
|
||||
4. 找到 **"Android日志获取助手"**
|
||||
5. 点击 **"测试"** 或 **"执行"** 按钮
|
||||
6. 在输入框中输入您的请求（自然语言）
|
||||
7. 点击 **"执行"** 按钮
|
||||
8. 等待执行完成，查看结果
|
||||
|
||||
**输入格式**:
|
||||
- 直接使用自然语言，例如：
|
||||
- "获取最近的错误日志"
|
||||
- "列出所有连接的设备"
|
||||
- "获取ActivityManager的日志"
|
||||
- "adb devices"
|
||||
|
||||
---
|
||||
|
||||
### 方式2: 命令行测试工具
|
||||
|
||||
**使用测试脚本**:
|
||||
```bash
|
||||
cd /home/renjianbo/aiagent
|
||||
|
||||
# 基本用法
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "您的请求"}'
|
||||
```
|
||||
|
||||
**常用示例**:
|
||||
|
||||
```bash
|
||||
# 1. 列出所有连接的设备
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "列出所有连接的设备"}'
|
||||
|
||||
# 2. 获取最近的错误日志
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取最近的错误日志"}'
|
||||
|
||||
# 3. 获取ActivityManager的日志
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取ActivityManager的日志"}'
|
||||
|
||||
# 4. 获取特定级别的日志
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取警告级别的日志"}'
|
||||
|
||||
# 5. 执行adb devices命令
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "adb devices"}'
|
||||
|
||||
# 6. 获取系统日志
|
||||
python3 test_workflow_tool.py -a "Android日志获取助手" -i '{"query": "获取系统日志"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 方式3: API调用
|
||||
|
||||
**使用curl命令**:
|
||||
```bash
|
||||
# 1. 登录获取Token
|
||||
TOKEN=$(curl -s -X POST http://localhost:8037/api/v1/auth/login \
|
||||
-d 'username=admin&password=123456' \
|
||||
| python3 -c 'import sys, json; print(json.load(sys.stdin).get("access_token"))')
|
||||
|
||||
# 2. 执行Agent
|
||||
curl -X POST http://localhost:8037/api/v1/agents/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-d '{
|
||||
"agent_id": "b68e96d2-da66-4402-86a5-9fae6b5ac092",
|
||||
"input_data": {
|
||||
"query": "获取最近的错误日志"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
**使用Python脚本**:
|
||||
```python
|
||||
import requests
|
||||
import json
|
||||
|
||||
# 登录
|
||||
login_response = requests.post(
|
||||
"http://localhost:8037/api/v1/auth/login",
|
||||
data={"username": "admin", "password": "123456"}
|
||||
)
|
||||
token = login_response.json()["access_token"]
|
||||
|
||||
# 执行Agent
|
||||
execute_response = requests.post(
|
||||
"http://localhost:8037/api/v1/agents/execute",
|
||||
headers={
|
||||
"Authorization": f"Bearer {token}",
|
||||
"Content-Type": "application/json"
|
||||
},
|
||||
json={
|
||||
"agent_id": "b68e96d2-da66-4402-86a5-9fae6b5ac092",
|
||||
"input_data": {
|
||||
"query": "获取最近的错误日志"
|
||||
}
|
||||
}
|
||||
)
|
||||
|
||||
result = execute_response.json()
|
||||
print(json.dumps(result, indent=2, ensure_ascii=False))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 使用示例
|
||||
|
||||
### 示例1: 列出连接的设备
|
||||
|
||||
**输入**:
|
||||
```json
|
||||
{
|
||||
"query": "列出所有连接的设备"
|
||||
}
|
||||
```
|
||||
|
||||
**或自然语言**:
|
||||
```
|
||||
列出设备
|
||||
adb devices
|
||||
```
|
||||
|
||||
**预期输出**:
|
||||
```
|
||||
已找到1个连接的设备：
|
||||
|
||||
1. emulator-5554
|
||||
- 状态: device（已连接且正常运行）
|
||||
- 类型: Android模拟器
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 示例2: 获取错误日志
|
||||
|
||||
**输入**:
|
||||
```json
|
||||
{
|
||||
"query": "获取最近的错误日志"
|
||||
}
|
||||
```
|
||||
|
||||
**或自然语言**:
|
||||
```
|
||||
获取错误日志
|
||||
显示最近的错误
|
||||
```
|
||||
|
||||
**预期输出**:
|
||||
```
|
||||
已获取最近的错误日志，共发现X个错误：
|
||||
|
||||
1. [时间] 标签: 错误信息
|
||||
- 详细信息
|
||||
- 建议操作
|
||||
|
||||
2. [时间] 标签: 错误信息
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 示例3: 获取特定标签的日志
|
||||
|
||||
**输入**:
|
||||
```json
|
||||
{
|
||||
"query": "获取ActivityManager的日志"
|
||||
}
|
||||
```
|
||||
|
||||
**或自然语言**:
|
||||
```
|
||||
获取ActivityManager日志
|
||||
显示ActivityManager的活动
|
||||
```
|
||||
|
||||
**预期输出**:
|
||||
```
|
||||
已获取ActivityManager日志，共100行：
|
||||
|
||||
关键活动：
|
||||
- 应用启动: com.example.app (时间)
|
||||
- Activity切换: MainActivity → SettingsActivity (时间)
|
||||
- 应用关闭: com.example.app (时间)
|
||||
|
||||
性能指标：
|
||||
- 平均启动时间: X秒
|
||||
- Activity切换次数: X次
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 示例4: 获取特定级别的日志
|
||||
|
||||
**输入**:
|
||||
```json
|
||||
{
|
||||
"query": "获取警告级别的日志"
|
||||
}
|
||||
```
|
||||
|
||||
**支持的级别**:
|
||||
- `V` - Verbose（详细）
|
||||
- `D` - Debug（调试）
|
||||
- `I` - Info（信息）
|
||||
- `W` - Warning（警告）
|
||||
- `E` - Error（错误）
|
||||
- `F` - Fatal（致命）
|
||||
- `S` - Silent（静默）
|
||||
|
||||
**自然语言示例**:
|
||||
```
|
||||
获取错误日志
|
||||
显示警告信息
|
||||
获取调试日志
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 示例5: 执行Shell命令（受限）
|
||||
|
||||
**输入**:
|
||||
```json
|
||||
{
|
||||
"query": "获取设备属性"
|
||||
}
|
||||
```
|
||||
|
||||
**支持的安全命令**:
|
||||
- `getprop` - 获取系统属性
|
||||
- `dumpsys` - 转储系统服务信息
|
||||
- `pm` - 包管理器命令
|
||||
- `am` - Activity管理器命令
|
||||
- `settings` - 设置命令
|
||||
|
||||
**不支持的危险命令**:
|
||||
- ❌ `rm` - 删除文件
|
||||
- ❌ `reboot` - 重启设备
|
||||
- ❌ `su` - 超级用户
|
||||
- ❌ 其他可能破坏系统的命令
|
||||
|
||||
---
|
||||
|
||||
## 🎯 支持的请求类型
|
||||
|
||||
### 1. 设备管理
|
||||
- ✅ "列出所有连接的设备"
|
||||
- ✅ "检查设备连接状态"
|
||||
- ✅ "adb devices"
|
||||
|
||||
### 2. 日志获取
|
||||
- ✅ "获取最近的日志"
|
||||
- ✅ "获取错误日志"
|
||||
- ✅ "获取警告日志"
|
||||
- ✅ "获取ActivityManager的日志"
|
||||
- ✅ "获取系统日志"
|
||||
- ✅ "获取特定标签的日志"
|
||||
|
||||
### 3. 日志过滤
|
||||
- ✅ 按标签过滤（如 `ActivityManager`、`SystemServer`）
|
||||
- ✅ 按级别过滤（V/D/I/W/E/F/S）
|
||||
- ✅ 限制返回行数（默认100行）
|
||||
|
||||
### 4. Shell命令（受限）
|
||||
- ✅ 获取设备属性
|
||||
- ✅ 查询包信息
|
||||
- ✅ 查询系统服务
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 工作流程
|
||||
|
||||
Agent的工作流程如下：
|
||||
|
||||
```
|
||||
用户输入
|
||||
↓
|
||||
意图识别节点（LLM）
|
||||
- 分析用户请求
|
||||
- 提取ADB命令参数
|
||||
↓
|
||||
JSON解析节点
|
||||
- 解析意图识别结果
|
||||
- 提取命令参数
|
||||
↓
|
||||
LLM工具调用节点
|
||||
- 调用adb_log工具
|
||||
- 执行ADB命令
|
||||
- 分析日志内容
|
||||
↓
|
||||
结束节点
|
||||
- 返回最终结果
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 查看执行详情
|
||||
|
||||
### 在前端查看
|
||||
|
||||
1. 执行Agent后，点击 **"查看详情"** 按钮
|
||||
2. 在 **执行详情** 页面中：
|
||||
- 查看整体执行状态
|
||||
- 查看每个节点的执行情况
|
||||
- 查看工具调用可视化
|
||||
- 查看输入和输出数据
|
||||
|
||||
3. 点击 **"执行ADB命令"** 节点，查看：
|
||||
- 节点执行详情
|
||||
- 工具调用时间线
|
||||
- 工具调用参数和结果
|
||||
- 执行日志
|
||||
|
||||
### 工具调用可视化
|
||||
|
||||
在节点执行详情中，可以看到：
|
||||
- ✅ 工具调用时间线
|
||||
- ✅ 工具名称和状态
|
||||
- ✅ 工具调用参数
|
||||
- ✅ 工具执行结果
|
||||
- ✅ 执行耗时
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
### 1. ADB环境要求
|
||||
- ✅ 必须安装 Android SDK Platform Tools
|
||||
- ✅ 必须将 `adb` 命令添加到 PATH
|
||||
- ✅ 必须连接 Android 设备或启动模拟器
|
||||
- ✅ 设备必须启用USB调试（物理设备）
|
||||
|
||||
### 2. 安全限制
|
||||
- ✅ Shell命令只允许执行安全命令
|
||||
- ✅ 不允许执行危险命令（如 `rm`、`reboot` 等）
|
||||
- ✅ 超时控制防止长时间执行（默认10秒）
|
||||
- ✅ 行数限制防止输出过长（默认100行）
|
||||
|
||||
### 3. 性能优化
|
||||
- ✅ 默认限制返回100行日志
|
||||
- ✅ 支持超时控制（默认10秒）
|
||||
- ✅ 异步执行避免阻塞
|
||||
|
||||
### 4. 错误处理
|
||||
- ✅ 处理ADB命令执行失败
|
||||
- ✅ 处理设备未连接情况
|
||||
- ✅ 处理超时情况
|
||||
- ✅ 详细的错误信息返回
|
||||
|
||||
---
|
||||
|
||||
## 🔍 常见问题
|
||||
|
||||
### Q1: 提示"设备未连接"怎么办？
|
||||
|
||||
**A**: 请检查：
|
||||
1. 设备是否已连接（`adb devices`）
|
||||
2. USB调试是否已启用（物理设备）
|
||||
3. ADB服务是否正常运行（`adb kill-server && adb start-server`）
|
||||
|
||||
### Q2: 执行超时怎么办？
|
||||
|
||||
**A**:
|
||||
- 默认超时时间为10秒
|
||||
- 如果日志量很大，可能需要更长时间
|
||||
- 可以尝试限制返回行数或使用更具体的过滤条件
|
||||
|
||||
### Q3: 如何获取更多日志？
|
||||
|
||||
**A**:
|
||||
- Agent默认返回100行日志
|
||||
- 可以通过更具体的过滤条件获取相关日志
|
||||
- 例如："获取ActivityManager最近200行的日志"
|
||||
|
||||
### Q4: 工具调用没有执行？
|
||||
|
||||
**A**:
|
||||
- 检查Agent配置中是否启用了工具调用
|
||||
- 检查是否选中了 `adb_log` 工具
|
||||
- 尝试使用更明确的输入，例如："请使用adb_log工具执行adb devices命令"
|
||||
|
||||
### Q5: 如何查看工具调用详情？
|
||||
|
||||
**A**:
|
||||
- 在前端执行详情页面，点击 **"执行ADB命令"** 节点
|
||||
- 查看 **"工具调用"** 卡片
|
||||
- 查看工具调用时间线、参数和结果
|
||||
|
||||
---
|
||||
|
||||
## 🎓 最佳实践
|
||||
|
||||
### 1. 使用明确的请求
|
||||
- ✅ "获取最近的错误日志"
|
||||
- ❌ "日志"
|
||||
|
||||
### 2. 指定具体的标签或级别
|
||||
- ✅ "获取ActivityManager的错误日志"
|
||||
- ❌ "获取日志"
|
||||
|
||||
### 3. 限制返回行数
|
||||
- ✅ "获取最近的50行错误日志"
|
||||
- ❌ "获取所有错误日志"
|
||||
|
||||
### 4. 使用自然语言
|
||||
- ✅ "列出所有连接的设备"
|
||||
- ✅ "显示最近的警告信息"
|
||||
- ✅ "获取系统日志"
|
||||
|
||||
---
|
||||
|
||||
## 📞 技术支持
|
||||
|
||||
如果遇到问题，请：
|
||||
1. 检查ADB环境是否正确配置
|
||||
2. 检查设备是否已连接
|
||||
3. 查看执行详情页面的错误信息
|
||||
4. 查看后端日志：`docker-compose -f docker-compose.dev.yml logs backend`
|
||||
|
||||
---
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- [ADB工具和Android日志Agent搭建总结](./ADB工具和Android日志Agent搭建总结.md)
|
||||
- [Agent搭建通用方法指南](./Agent搭建通用方法指南.md)
|
||||
- [工具调用可视化实现总结](./工具调用可视化实现总结.md)
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-01-23
|
||||
**文档版本**: v1.0
|
||||
**Agent状态**: ✅ 已发布，可正常使用
|
||||
96
docs/integrations/DeepSeek配置完成.md
Normal file
96
docs/integrations/DeepSeek配置完成.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# DeepSeek配置完成 ✅
|
||||
|
||||
## 配置信息
|
||||
|
||||
- **API Key**: `sk-fdf7cc1c73504e628ec0119b7e11b8cc` (已配置)
|
||||
- **Base URL**: `https://api.deepseek.com` (已配置)
|
||||
|
||||
## 配置位置
|
||||
|
||||
### 1. Docker Compose环境变量
|
||||
|
||||
已在 `docker-compose.dev.yml` 中配置：
|
||||
|
||||
```yaml
|
||||
backend:
|
||||
environment:
|
||||
- DEEPSEEK_API_KEY=sk-fdf7cc1c73504e628ec0119b7e11b8cc
|
||||
- DEEPSEEK_BASE_URL=https://api.deepseek.com
|
||||
```
|
||||
|
||||
### 2. 后端服务状态
|
||||
|
||||
- ✅ 后端服务已重启
|
||||
- ✅ DeepSeek API Key已加载
|
||||
- ✅ DeepSeek客户端已初始化
|
||||
|
||||
## 测试步骤
|
||||
|
||||
### 1. 创建工作流
|
||||
|
||||
1. 打开工作流设计器
|
||||
2. 添加LLM节点
|
||||
3. 配置节点：
|
||||
- **提供商**: 选择 "DeepSeek"
|
||||
- **模型**: 选择 "DeepSeek Chat" 或 "DeepSeek Coder"
|
||||
- **提示词**: 输入测试提示词，如 `请用一句话总结：{input}`
|
||||
- **温度**: 0.7
|
||||
|
||||
### 2. 执行测试
|
||||
|
||||
输入测试数据：
|
||||
```json
|
||||
{
|
||||
"input": "人工智能是计算机科学的一个分支"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 验证结果
|
||||
|
||||
- ✅ 执行成功
|
||||
- ✅ 返回DeepSeek的响应
|
||||
- ✅ 无错误信息
|
||||
|
||||
## 支持的模型
|
||||
|
||||
- **DeepSeek Chat** (`deepseek-chat`): 通用对话模型
|
||||
- **DeepSeek Coder** (`deepseek-coder`): 代码生成模型
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **API Key安全**:
|
||||
- API Key已保存在配置文件中
|
||||
- 请勿将API Key提交到Git仓库
|
||||
- 建议将`.env`文件添加到`.gitignore`
|
||||
|
||||
2. **费用**:
|
||||
- DeepSeek按使用量计费
|
||||
- 请注意控制调用频率
|
||||
|
||||
3. **网络**:
|
||||
- 确保服务器可以访问 `https://api.deepseek.com`
|
||||
- 如有防火墙，请开放相应端口
|
||||
|
||||
## 故障排查
|
||||
|
||||
如果遇到问题，可以：
|
||||
|
||||
1. **检查配置**:
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml exec backend python -c "from app.core.config import settings; print('DeepSeek API Key:', settings.DEEPSEEK_API_KEY[:15] + '...' if settings.DEEPSEEK_API_KEY else '未配置')"
|
||||
```
|
||||
|
||||
2. **查看日志**:
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml logs --tail=50 backend
|
||||
```
|
||||
|
||||
3. **重启服务**:
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml restart backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**配置时间**: 2024年
|
||||
**状态**: ✅ 已配置并验证
|
||||
200
docs/integrations/DeepSeek集成说明.md
Normal file
200
docs/integrations/DeepSeek集成说明.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# DeepSeek集成说明
|
||||
|
||||
## ✅ 已完成
|
||||
|
||||
已成功集成DeepSeek API，LLM节点现在可以使用DeepSeek模型。
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 1. DeepSeek支持
|
||||
|
||||
- 兼容OpenAI API格式
|
||||
- 支持DeepSeek Chat和DeepSeek Coder模型
|
||||
- 与OpenAI使用相同的调用接口
|
||||
- 支持自定义API地址
|
||||
|
||||
### 2. 配置
|
||||
|
||||
- 独立的API Key配置
|
||||
- 独立的Base URL配置
|
||||
- 可在节点级别选择提供商
|
||||
|
||||
## 配置方法
|
||||
|
||||
### 1. 设置DeepSeek API Key
|
||||
|
||||
在 `backend/.env` 文件中添加：
|
||||
|
||||
```env
|
||||
DEEPSEEK_API_KEY=your-deepseek-api-key-here
|
||||
DEEPSEEK_BASE_URL=https://api.deepseek.com
|
||||
```
|
||||
|
||||
或者使用环境变量：
|
||||
|
||||
```bash
|
||||
export DEEPSEEK_API_KEY=your-deepseek-api-key-here
|
||||
export DEEPSEEK_BASE_URL=https://api.deepseek.com
|
||||
```
|
||||
|
||||
### 2. 重启后端服务
|
||||
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml restart backend
|
||||
```
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 1. 在工作流中添加LLM节点
|
||||
|
||||
1. 打开工作流设计器
|
||||
2. 从节点工具箱拖拽"LLM"节点到画布
|
||||
3. 配置节点参数
|
||||
|
||||
### 2. 配置LLM节点使用DeepSeek
|
||||
|
||||
在节点配置面板中设置：
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": "deepseek",
|
||||
"prompt": "请处理以下输入：\n{input}",
|
||||
"model": "deepseek-chat",
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 1000
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**：
|
||||
- `provider`: 选择 `deepseek`
|
||||
- `prompt`: 提示词模板，支持变量替换
|
||||
- `model`: 模型名称
|
||||
- `deepseek-chat`: DeepSeek Chat模型（通用对话）
|
||||
- `deepseek-coder`: DeepSeek Coder模型（代码生成）
|
||||
- `temperature`: 温度参数（0-2），默认0.7
|
||||
- `max_tokens`: 最大生成token数，可选
|
||||
|
||||
### 3. 支持的模型
|
||||
|
||||
#### DeepSeek Chat
|
||||
- 模型名称：`deepseek-chat`
|
||||
- 用途：通用对话、文本生成、分析等
|
||||
- 推荐场景：日常对话、内容创作、数据分析
|
||||
|
||||
#### DeepSeek Coder
|
||||
- 模型名称：`deepseek-coder`
|
||||
- 用途：代码生成、代码解释、代码优化
|
||||
- 推荐场景：代码生成、代码审查、技术问答
|
||||
|
||||
## 示例工作流
|
||||
|
||||
### 示例1：使用DeepSeek进行文本处理
|
||||
|
||||
```
|
||||
开始 → LLM节点(DeepSeek) → 结束
|
||||
```
|
||||
|
||||
LLM节点配置：
|
||||
```json
|
||||
{
|
||||
"provider": "deepseek",
|
||||
"prompt": "请将以下文本翻译成英文：{input}",
|
||||
"model": "deepseek-chat",
|
||||
"temperature": 0.7
|
||||
}
|
||||
```
|
||||
|
||||
### 示例2：使用DeepSeek Coder生成代码
|
||||
|
||||
```
|
||||
开始 → LLM节点(DeepSeek Coder) → 结束
|
||||
```
|
||||
|
||||
LLM节点配置：
|
||||
```json
|
||||
{
|
||||
"provider": "deepseek",
|
||||
"prompt": "请用Python编写一个函数，功能是：{input}",
|
||||
"model": "deepseek-coder",
|
||||
"temperature": 0.3
|
||||
}
|
||||
```
|
||||
|
||||
### 示例3：多提供商工作流
|
||||
|
||||
```
|
||||
开始 → LLM节点(OpenAI) → LLM节点(DeepSeek) → 结束
|
||||
```
|
||||
|
||||
可以在同一个工作流中使用不同的提供商，实现：
|
||||
- 成本优化（DeepSeek通常更便宜）
|
||||
- 结果对比
|
||||
- 功能互补
|
||||
|
||||
## 提供商选择建议
|
||||
|
||||
### 选择OpenAI的场景
|
||||
- 需要最新的GPT-4模型
|
||||
- 需要更强的推理能力
|
||||
- 预算充足
|
||||
|
||||
### 选择DeepSeek的场景
|
||||
- 需要高性价比
|
||||
- 代码生成任务（DeepSeek Coder）
|
||||
- 中文场景（DeepSeek对中文支持较好）
|
||||
- 需要更快的响应速度
|
||||
|
||||
## 错误处理
|
||||
|
||||
如果DeepSeek API调用失败，节点会返回错误信息：
|
||||
|
||||
```json
|
||||
{
|
||||
"output": null,
|
||||
"status": "failed",
|
||||
"error": "DeepSeek API调用失败: 具体错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
常见错误：
|
||||
- **API Key未配置**：`DeepSeek API Key未配置，请在环境变量中设置DEEPSEEK_API_KEY`
|
||||
- **API调用失败**：检查网络连接、API Key有效性、余额等
|
||||
- **模型不存在**：检查模型名称是否正确
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **API费用**：DeepSeek通常比OpenAI更便宜，但每次调用仍会产生费用
|
||||
2. **API限制**：注意DeepSeek的速率限制和配额
|
||||
3. **网络连接**：确保服务器可以访问DeepSeek API（https://api.deepseek.com）
|
||||
4. **模型选择**：根据任务类型选择合适的模型
|
||||
5. **兼容性**：DeepSeek兼容OpenAI API格式，但某些高级功能可能不支持
|
||||
|
||||
## 前端配置
|
||||
|
||||
在前端工作流编辑器中，LLM节点配置面板现在包含：
|
||||
|
||||
1. **提供商选择**：下拉菜单选择OpenAI或DeepSeek
|
||||
2. **模型选择**：根据选择的提供商显示对应的模型列表
|
||||
3. **提示词输入**：多行文本输入框
|
||||
4. **温度调节**：滑块控制（0-2）
|
||||
5. **最大Token数**：数字输入框（可选）
|
||||
|
||||
## 测试建议
|
||||
|
||||
1. **配置API Key**：在`.env`文件中设置`DEEPSEEK_API_KEY`
|
||||
2. **创建测试工作流**：添加LLM节点，选择DeepSeek提供商
|
||||
3. **测试不同模型**：分别测试`deepseek-chat`和`deepseek-coder`
|
||||
4. **对比结果**：与OpenAI的结果进行对比
|
||||
5. **检查错误处理**：测试API Key错误、网络错误等情况
|
||||
|
||||
## 后续计划
|
||||
|
||||
- [ ] 支持更多DeepSeek模型
|
||||
- [ ] 支持流式输出（Streaming）
|
||||
- [ ] 添加模型性能对比功能
|
||||
- [ ] 支持自动选择最优提供商
|
||||
|
||||
---
|
||||
|
||||
**状态**: ✅ 已完成
|
||||
**时间**: 2024年
|
||||
200
docs/integrations/OpenAI集成说明.md
Normal file
200
docs/integrations/OpenAI集成说明.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# OpenAI集成说明
|
||||
|
||||
## ✅ 已完成
|
||||
|
||||
已成功集成OpenAI API，LLM节点现在可以真实调用OpenAI模型。
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 1. LLM服务 (`backend/app/services/llm_service.py`)
|
||||
|
||||
- 支持OpenAI API调用
|
||||
- 支持自定义模型、温度、最大token数等参数
|
||||
- 异步调用，提高性能
|
||||
- 错误处理和异常捕获
|
||||
|
||||
### 2. 工作流引擎集成
|
||||
|
||||
- LLM节点现在会真实调用OpenAI API
|
||||
- 支持prompt模板和变量替换
|
||||
- 自动处理输入数据格式化
|
||||
|
||||
## 配置方法
|
||||
|
||||
### 1. 设置OpenAI API Key
|
||||
|
||||
在 `backend/.env` 文件中添加：
|
||||
|
||||
```env
|
||||
OPENAI_API_KEY=your-openai-api-key-here
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
```
|
||||
|
||||
或者使用环境变量：
|
||||
|
||||
```bash
|
||||
export OPENAI_API_KEY=your-openai-api-key-here
|
||||
export OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
```
|
||||
|
||||
### 2. 重启后端服务
|
||||
|
||||
```bash
|
||||
docker-compose -f docker-compose.dev.yml restart backend
|
||||
```
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 1. 在工作流中添加LLM节点
|
||||
|
||||
1. 打开工作流设计器
|
||||
2. 从节点工具箱拖拽"LLM"节点到画布
|
||||
3. 配置节点参数（见下方）
|
||||
|
||||
### 2. 配置LLM节点
|
||||
|
||||
LLM节点支持以下配置（在节点配置面板中设置）：
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": "请处理以下输入：\n{input}",
|
||||
"provider": "openai",
|
||||
"model": "gpt-3.5-turbo",
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 1000
|
||||
}
|
||||
```
|
||||
|
||||
**参数说明**：
|
||||
- `prompt`: 提示词模板，支持变量替换（如 `{input}`, `{key}` 等）
|
||||
- `provider`: LLM提供商，目前支持 `openai`
|
||||
- `model`: 模型名称，如 `gpt-3.5-turbo`, `gpt-4`, `gpt-4-turbo-preview` 等
|
||||
- `temperature`: 温度参数（0-2），控制输出的随机性，默认0.7
|
||||
- `max_tokens`: 最大生成token数，可选
|
||||
|
||||
### 3. Prompt模板示例
|
||||
|
||||
#### 基础模板
|
||||
```
|
||||
请处理以下输入数据：{input}
|
||||
```
|
||||
|
||||
#### 带变量替换
|
||||
```
|
||||
用户输入：{user_input}
|
||||
请根据以上输入生成回复。
|
||||
```
|
||||
|
||||
#### 复杂模板
|
||||
```
|
||||
输入数据：
|
||||
{input}
|
||||
|
||||
请分析以上数据并给出：
|
||||
1. 主要观点
|
||||
2. 关键信息
|
||||
3. 建议
|
||||
```
|
||||
|
||||
### 4. 执行工作流
|
||||
|
||||
1. 保存工作流
|
||||
2. 点击"运行"按钮
|
||||
3. 输入初始数据（JSON格式）
|
||||
4. 查看执行结果
|
||||
|
||||
## 输入数据处理
|
||||
|
||||
LLM节点会自动处理输入数据：
|
||||
|
||||
1. **如果输入是字典**：
|
||||
- 支持在prompt中使用 `{key}` 替换变量
|
||||
- 如果prompt中没有变量，会将整个输入作为JSON附加到prompt
|
||||
|
||||
2. **如果输入是字符串或其他类型**：
|
||||
- 直接替换 `{input}` 占位符
|
||||
- 如果没有占位符，附加到prompt末尾
|
||||
|
||||
## 错误处理
|
||||
|
||||
如果OpenAI API调用失败，节点会返回错误信息：
|
||||
|
||||
```json
|
||||
{
|
||||
"output": null,
|
||||
"status": "failed",
|
||||
"error": "LLM调用失败: 具体错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
常见错误：
|
||||
- **API Key未配置**：`OpenAI API Key未配置，请在环境变量中设置OPENAI_API_KEY`
|
||||
- **API调用失败**：检查网络连接、API Key有效性、余额等
|
||||
- **模型不存在**：检查模型名称是否正确
|
||||
|
||||
## 支持的模型
|
||||
|
||||
目前支持所有OpenAI Chat模型：
|
||||
- `gpt-3.5-turbo`
|
||||
- `gpt-4`
|
||||
- `gpt-4-turbo-preview`
|
||||
- `gpt-4-32k`
|
||||
- 其他OpenAI兼容的模型（如果使用自定义base_url）
|
||||
|
||||
## 示例工作流
|
||||
|
||||
### 示例1：简单文本处理
|
||||
|
||||
```
|
||||
开始 → LLM节点 → 结束
|
||||
```
|
||||
|
||||
LLM节点配置：
|
||||
```json
|
||||
{
|
||||
"prompt": "请将以下文本翻译成英文：{input}",
|
||||
"model": "gpt-3.5-turbo"
|
||||
}
|
||||
```
|
||||
|
||||
输入：
|
||||
```json
|
||||
{
|
||||
"input": "你好，世界"
|
||||
}
|
||||
```
|
||||
|
||||
### 示例2：数据分析
|
||||
|
||||
```
|
||||
开始 → LLM节点 → 条件节点 → 输出
|
||||
```
|
||||
|
||||
LLM节点配置：
|
||||
```json
|
||||
{
|
||||
"prompt": "分析以下数据：\n{input}\n\n请判断数据是否正常（返回true或false）",
|
||||
"model": "gpt-4",
|
||||
"temperature": 0.3
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **API费用**：每次调用都会产生费用，请注意控制调用频率
|
||||
2. **API限制**：注意OpenAI的速率限制和配额
|
||||
3. **网络连接**：确保服务器可以访问OpenAI API
|
||||
4. **错误处理**：建议在工作流中添加错误处理节点
|
||||
|
||||
## 后续计划
|
||||
|
||||
- [ ] 支持更多LLM提供商（Anthropic Claude、本地模型等）
|
||||
- [ ] 支持流式输出（Streaming）
|
||||
- [ ] 支持函数调用（Function Calling）
|
||||
- [ ] 支持多轮对话上下文
|
||||
- [ ] 添加模型选择UI组件
|
||||
|
||||
---
|
||||
|
||||
**状态**: ✅ 已完成
|
||||
**时间**: 2024年
|
||||
205
docs/integrations/数据库查询工具实现总结.md
Normal file
205
docs/integrations/数据库查询工具实现总结.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# 数据库查询工具实现总结
|
||||
|
||||
## ✅ 完成状态
|
||||
|
||||
**任务**: 数据库查询工具实现
|
||||
**状态**: ✅ 已完成
|
||||
**完成时间**: 2026-01-23
|
||||
|
||||
---
|
||||
|
||||
## 📋 实现功能
|
||||
|
||||
### 1. 核心功能
|
||||
|
||||
- ✅ **默认数据库查询**
|
||||
- 使用SQLAlchemy连接默认数据库
|
||||
- 支持所有SELECT查询操作
|
||||
- 自动格式化查询结果为JSON
|
||||
|
||||
- ✅ **指定数据源查询**
|
||||
- 支持通过`data_source_id`参数查询外部数据库
|
||||
- 自动使用数据源连接器（MySQL、PostgreSQL等）
|
||||
- 支持多种数据库类型
|
||||
|
||||
- ✅ **SQL注入防护**
|
||||
- 只允许SELECT查询
|
||||
- 禁止INSERT、UPDATE、DELETE、DROP等危险操作
|
||||
- 检查危险关键字（INSERT、UPDATE、DELETE、DROP、TRUNCATE、ALTER等）
|
||||
- 禁止多语句查询
|
||||
- 自动清理SQL注释
|
||||
|
||||
- ✅ **查询超时控制**
|
||||
- 默认超时时间：30秒
|
||||
- 最大超时时间：300秒
|
||||
- 使用asyncio实现异步超时控制
|
||||
|
||||
- ✅ **结果格式化**
|
||||
- 返回JSON格式结果
|
||||
- 包含查询状态、行数、数据内容
|
||||
- 自动处理日期时间等特殊类型
|
||||
|
||||
---
|
||||
|
||||
## 🔧 技术实现
|
||||
|
||||
### 文件修改
|
||||
|
||||
1. **`backend/app/services/builtin_tools.py`**
|
||||
- 实现 `database_query_tool` 函数
|
||||
- 实现 `_validate_sql_query` SQL验证函数
|
||||
- 实现 `_execute_default_db_query` 默认数据库查询
|
||||
- 实现 `_execute_data_source_query` 数据源查询
|
||||
- 更新 `DATABASE_QUERY_SCHEMA` 工具定义
|
||||
|
||||
2. **`backend/app/main.py`**
|
||||
- 注册 `database_query_tool` 到工具注册表
|
||||
|
||||
### 核心代码
|
||||
|
||||
```python
|
||||
async def database_query_tool(
|
||||
query: str,
|
||||
database: str = "default",
|
||||
data_source_id: Optional[str] = None,
|
||||
timeout: int = 30
|
||||
) -> str:
|
||||
"""
|
||||
数据库查询工具
|
||||
|
||||
- 只允许SELECT查询
|
||||
- 支持默认数据库和指定数据源
|
||||
- 包含SQL注入防护和超时控制
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试结果
|
||||
|
||||
### 测试用例
|
||||
|
||||
1. ✅ **SQL验证测试**
|
||||
- 正常SELECT查询 ✅
|
||||
- INSERT/UPDATE/DELETE/DROP查询被拒绝 ✅
|
||||
- 多语句查询被拒绝 ✅
|
||||
- 带WHERE和别名的复杂查询 ✅
|
||||
|
||||
2. ✅ **数据库查询测试**
|
||||
- 默认数据库查询成功 ✅
|
||||
- SQL注入防护生效 ✅
|
||||
- 复杂SELECT查询成功 ✅
|
||||
- 超时控制生效 ✅
|
||||
|
||||
### 测试脚本
|
||||
|
||||
- 文件: `test_database_query_tool.py`
|
||||
- 所有测试用例通过 ✅
|
||||
|
||||
---
|
||||
|
||||
## 📊 工具Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "database_query",
|
||||
"description": "执行数据库查询（只允许SELECT查询，支持默认数据库和指定数据源）",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"query": {
|
||||
"type": "string",
|
||||
"description": "SQL查询语句（只允许SELECT查询）"
|
||||
},
|
||||
"data_source_id": {
|
||||
"type": "string",
|
||||
"description": "数据源ID（可选，如果提供则使用指定的数据源）"
|
||||
},
|
||||
"timeout": {
|
||||
"type": "integer",
|
||||
"description": "查询超时时间（秒，默认30秒，最大300秒）",
|
||||
"default": 30,
|
||||
"minimum": 1,
|
||||
"maximum": 300
|
||||
}
|
||||
},
|
||||
"required": ["query"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 安全特性
|
||||
|
||||
1. **SQL注入防护**
|
||||
- 只允许SELECT查询
|
||||
- 关键字黑名单检查
|
||||
- 禁止多语句执行
|
||||
|
||||
2. **超时控制**
|
||||
- 防止长时间运行的查询
|
||||
- 可配置超时时间
|
||||
|
||||
3. **错误处理**
|
||||
- 详细的错误信息
|
||||
- 不泄露敏感信息
|
||||
|
||||
---
|
||||
|
||||
## 📝 使用示例
|
||||
|
||||
### 示例1: 查询默认数据库
|
||||
|
||||
```python
|
||||
result = await database_query_tool(
|
||||
query="SELECT id, username, email FROM users LIMIT 10",
|
||||
timeout=30
|
||||
)
|
||||
```
|
||||
|
||||
### 示例2: 查询指定数据源
|
||||
|
||||
```python
|
||||
result = await database_query_tool(
|
||||
query="SELECT * FROM products WHERE price > 100",
|
||||
data_source_id="your-data-source-id",
|
||||
timeout=60
|
||||
)
|
||||
```
|
||||
|
||||
### 示例3: 在LLM节点中使用
|
||||
|
||||
在LLM节点的工具配置中启用 `database_query` 工具，LLM可以自动调用：
|
||||
|
||||
```
|
||||
用户: "查询一下有多少个用户"
|
||||
LLM: 调用 database_query(query="SELECT COUNT(*) as count FROM users")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步
|
||||
|
||||
根据待完善功能清单，接下来可以：
|
||||
|
||||
1. **工具调用可视化** - 显示工具调用过程
|
||||
2. **监控和告警前端界面** - 后端API已完成，需要前端实现
|
||||
3. **工具动态注册机制** - 支持HTTP工具、工作流工具的动态注册
|
||||
|
||||
---
|
||||
|
||||
## 📊 统计
|
||||
|
||||
- **代码行数**: 约200行
|
||||
- **测试用例**: 8个
|
||||
- **测试通过率**: 100%
|
||||
- **工具总数**: 9个（新增1个）
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2026-01-23
|
||||
**文档版本**: v1.0
|
||||
170
docs/integrations/数据库迁移说明-模板市场.md
Normal file
170
docs/integrations/数据库迁移说明-模板市场.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 数据库迁移说明 - 模板市场功能
|
||||
|
||||
## 📋 概述
|
||||
|
||||
模板市场功能需要创建3个新的数据库表：
|
||||
1. `workflow_templates` - 工作流模板表
|
||||
2. `template_ratings` - 模板评分表
|
||||
3. `template_favorites` - 模板收藏表
|
||||
|
||||
## 🔧 迁移方式
|
||||
|
||||
### 方式一：执行SQL脚本（推荐）
|
||||
|
||||
**SQL脚本位置**: `backend/create_template_market_tables.sql`
|
||||
|
||||
**执行命令**:
|
||||
```bash
|
||||
# 使用MySQL客户端
|
||||
mysql -h [数据库地址] -u [用户名] -p [数据库名] < backend/create_template_market_tables.sql
|
||||
|
||||
# 例如（根据您的配置）:
|
||||
mysql -h gz-cynosdbmysql-grp-d26pzce5.sql.tencentcdb.com -P 24936 -u root -p agent_db < backend/create_template_market_tables.sql
|
||||
```
|
||||
|
||||
### 方式二：重启后端服务（自动创建）
|
||||
|
||||
如果后端服务配置了自动创建表（使用 `Base.metadata.create_all`），重启服务后会自动创建表。
|
||||
|
||||
**重启命令**:
|
||||
```bash
|
||||
# Docker方式
|
||||
docker-compose restart backend
|
||||
|
||||
# 或直接重启uvicorn进程
|
||||
```
|
||||
|
||||
### 方式三：通过Python脚本创建
|
||||
|
||||
```python
|
||||
from app.core.database import engine, Base
|
||||
from app.models.workflow_template import WorkflowTemplate, TemplateRating, TemplateFavorite
|
||||
|
||||
# 创建表
|
||||
Base.metadata.create_all(bind=engine)
|
||||
```
|
||||
|
||||
## ✅ 验证表是否创建成功
|
||||
|
||||
### 方法一：通过MySQL客户端查询
|
||||
|
||||
```sql
|
||||
SHOW TABLES LIKE 'workflow_template%';
|
||||
SHOW TABLES LIKE 'template_%';
|
||||
```
|
||||
|
||||
应该看到：
|
||||
- `workflow_templates`
|
||||
- `template_ratings`
|
||||
- `template_favorites`
|
||||
|
||||
### 方法二：通过API测试
|
||||
|
||||
```bash
|
||||
# 登录获取token
|
||||
curl -X POST http://101.43.95.130:8037/api/v1/auth/login \
|
||||
-d "username=test_user&password=test_password123"
|
||||
|
||||
# 测试模板市场API
|
||||
curl -X GET http://101.43.95.130:8037/api/v1/template-market \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
如果返回200状态码和空数组 `[]`，说明表已创建成功。
|
||||
|
||||
## 📊 表结构说明
|
||||
|
||||
### workflow_templates（工作流模板表）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | CHAR(36) | 模板ID（主键） |
|
||||
| name | VARCHAR(100) | 模板名称 |
|
||||
| description | TEXT | 模板描述 |
|
||||
| category | VARCHAR(50) | 分类 |
|
||||
| tags | JSON | 标签列表 |
|
||||
| nodes | JSON | 节点配置 |
|
||||
| edges | JSON | 边配置 |
|
||||
| thumbnail | VARCHAR(500) | 缩略图URL |
|
||||
| is_public | BOOLEAN | 是否公开 |
|
||||
| is_featured | BOOLEAN | 是否精选 |
|
||||
| view_count | INT | 查看次数 |
|
||||
| use_count | INT | 使用次数 |
|
||||
| rating_count | INT | 评分次数 |
|
||||
| rating_avg | FLOAT | 平均评分 |
|
||||
| user_id | CHAR(36) | 创建者ID（外键） |
|
||||
| created_at | DATETIME | 创建时间 |
|
||||
| updated_at | DATETIME | 更新时间 |
|
||||
|
||||
### template_ratings（模板评分表）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | CHAR(36) | 评分ID（主键） |
|
||||
| template_id | CHAR(36) | 模板ID（外键） |
|
||||
| user_id | CHAR(36) | 用户ID（外键） |
|
||||
| rating | INT | 评分（1-5） |
|
||||
| comment | TEXT | 评论 |
|
||||
| created_at | DATETIME | 创建时间 |
|
||||
| updated_at | DATETIME | 更新时间 |
|
||||
|
||||
**唯一约束**: `(template_id, user_id)` - 每个用户对每个模板只能评分一次
|
||||
|
||||
### template_favorites（模板收藏表）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | CHAR(36) | 收藏ID（主键） |
|
||||
| template_id | CHAR(36) | 模板ID（外键） |
|
||||
| user_id | CHAR(36) | 用户ID（外键） |
|
||||
| created_at | DATETIME | 创建时间 |
|
||||
|
||||
**唯一约束**: `(template_id, user_id)` - 每个用户对每个模板只能收藏一次
|
||||
|
||||
## 🐛 常见问题
|
||||
|
||||
### 问题1: 表创建失败 - 外键约束错误
|
||||
|
||||
**原因**: `users` 表不存在或结构不匹配
|
||||
|
||||
**解决**: 确保 `users` 表已存在且 `id` 字段类型为 `CHAR(36)`
|
||||
|
||||
### 问题2: JSON字段不支持
|
||||
|
||||
**原因**: MySQL版本过低（需要5.7+）
|
||||
|
||||
**解决**: 升级MySQL版本或使用 `TEXT` 类型替代 `JSON`
|
||||
|
||||
### 问题3: 表已存在错误
|
||||
|
||||
**原因**: 表已经创建过
|
||||
|
||||
**解决**: 使用 `CREATE TABLE IF NOT EXISTS` 可以安全地重复执行
|
||||
|
||||
## 📝 迁移检查清单
|
||||
|
||||
- [ ] SQL脚本已创建
|
||||
- [ ] 执行SQL脚本或重启后端服务
|
||||
- [ ] 验证表是否创建成功
|
||||
- [ ] 测试模板市场API
|
||||
- [ ] 测试前端模板市场页面
|
||||
|
||||
## 🎯 迁移完成后
|
||||
|
||||
迁移完成后，您可以：
|
||||
|
||||
1. **使用模板市场功能**:
|
||||
- 分享工作流模板
|
||||
- 搜索和浏览模板
|
||||
- 收藏和评分模板
|
||||
- 使用模板创建工作流
|
||||
|
||||
2. **使用批量操作功能**（不依赖新表）:
|
||||
- 批量执行工作流
|
||||
- 批量导出工作流
|
||||
- 批量删除工作流
|
||||
|
||||
---
|
||||
|
||||
**SQL脚本位置**: `backend/create_template_market_tables.sql`
|
||||
**最后更新**: 2024年1月17日
|
||||
Reference in New Issue
Block a user