Skill: braveheartzjh/deer-flow-manager (version 1.0.0)

--- name: deer-flow-manager description: | DeerFlow 2.0（字节跳动开源 Deep Research 框架）管理技能。 用于安装、配置、更新、卸载 DeerFlow 2.0，以及排查启动问题。 触发词：DeerFlow部署、DeerFlow安装、DeerFlow配置、DeerFlow更新、DeerFlow卸载、DeerFlow启动、deer-flow --- # DeerFlow 2.0 管理技能 本技能用于管理 DeerFlow 2.0 的完整生命周期：安装、配置、更新、卸载、启动。 ## 使用场景 1. 首次安装 DeerFlow 2.0 2. 配置或更换大模型 3. 更新 DeerFlow 到最新版本 4. 卸载 DeerFlow 5. 排查启动问题 --- ## 第一步：收集大模型配置信息 在开始安装前，需要向用户收集大模型配置信息。 ### 询问用户 > 你好！在安装 DeerFlow 2.0 之前，我需要确认大模型配置。请提供以下信息： 1. **模型来源**：你想使用哪个大模型？ - OpenCode Zen big-pickle（免费，无需 API Key） - OpenAI（GPT-4o, GPT-4o-mini 等） - Anthropic（Claude 3.5 Sonnet 等） - Google（Gemini 2.5 Pro 等） - DeepSeek - Ollama（本地模型） - 其他 OpenAI 兼容接口 2. **API 信息**（根据选择的模型）： - API Key（如需要） - API Base URL（如使用第三方接口） - 模型名称 ### 配置模板 根据用户选择，按以下模板配置 `config.yaml` 中的 models 部分： #### OpenCode Zen big-pickle（免费） ```yaml models: - name: big-pickle display_name: Big Pickle (OpenCode Zen) use: langchain_openai:ChatOpenAI model: big-pickle api_key: "" base_url: https://opencode.ai/zen/v1 request_timeout: 600.0 max_retries: 2 max_tokens: 8192 ``` #### OpenAI ```yaml models: - name: gpt-4o display_name: GPT-4o use: langchain_openai:ChatOpenAI model: gpt-4o [REDACTED_SECRET] request_timeout: 600.0 max_retries: 2 max_tokens: 4096 ``` #### Claude ```yaml models: - name: claude-3-5-sonnet display_name: Claude 3.5 Sonnet use: langchain_anthropic:ChatAnthropic model: claude-sonnet-4-20250514 [REDACTED_SECRET] default_request_timeout: 600.0 max_retries: 2 ``` #### Ollama 本地模型 ```yaml models: - name: qwen3-local display_name: Qwen3 32B (Ollama) use: langchain_ollama:ChatOllama model: qwen3:32b base_url: http://localhost:11434 num_predict: 8192 temperature: 0.7 ``` --- ## 第二步：安装流程 ### 1. 检测操作系统 ```bash # 检测操作系统类型 OS=$(uname -s | tr '[:upper:]' '[:lower:]') echo "Detected OS: $OS" ``` ### 2. 环境检测 ```bash echo "=== Node.js ===" && node --version echo "=== pnpm ===" && pnpm --version echo "=== uv ===" && uv --version echo "=== Python ===" && python3 --version echo "=== nginx ===" && nginx -v echo "=== Docker ===" && docker --version echo "=== Git ===" && git --version echo "=== make ===" && make --version ``` ### 3. 依赖安装（按系统） **macOS:** ```bash # 安装 Homebrew（如未安装） /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 安装依赖 brew install node pnpm uv python@3.12 nginx git make ``` **Linux (Ubuntu/Debian):** ```bash # 安装系统依赖 sudo apt update sudo apt install -y curl git make nginx python3.12 python3-pip # 安装 Node.js 和 pnpm curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs npm install -g pnpm # 安装 uv curl -fsSL https://astral.sh/uv/install.sh | sh ``` **Windows (WSL2 推荐):** ```bash # 使用 WSL2 或 PowerBox # 推荐在 WSL2 Ubuntu 环境下安装 wsl --install -d Ubuntu ``` ### 4. 安装步骤 ```bash # 1. 确定安装目录 INSTALL_DIR="$HOME/deer-flow" # 2. 克隆仓库 git clone https://github.com/bytedance/deer-flow.git "$INSTALL_DIR" cd "$INSTALL_DIR" # 3. 创建配置文件 cp .env.example .env cp config.example.yaml config.yaml # 4. 编辑 config.yaml，添加模型配置 # 使用第一步收集的信息，编辑 config.yaml 中的 models 部分 # 5. 安装依赖 make check make install ``` ### 5. 验证安装 ```bash cd "$INSTALL_DIR" make doctor ``` ### 6. 启动服务 ```bash cd "$INSTALL_DIR" make dev ``` 服务启动后，访问 **http://localhost:2026**。 --- ## 第三步：更新流程 ```bash # 确定安装目录 INSTALL_DIR="$HOME/deer-flow" cd "$INSTALL_DIR" # 1. 拉取最新代码 git pull origin main # 2. 合并新配置字段 make config-upgrade # 3. 重建 venv cd backend && rm -rf .venv && uv sync && cd .. # 4. 重新安装依赖 make install ``` --- ## 第四步：卸载流程 ```bash # 确定安装目录 INSTALL_DIR="$HOME/deer-flow" cd "$INSTALL_DIR" # 1. 停止服务 make stop # 2. 清理临时文件 make clean # 3. 删除目录 rm -rf "$INSTALL_DIR" ``` --- ## 第五步：常见问题排查 ### LangGraph 启动卡住 **问题**：LangGraph 服务启动在 2024 端口等待超时。 **原因**：可能是 venv 路径问题（项目迁移后 shebang 失效）。 **解决**： ```bash cd "$INSTALL_DIR/backend" rm -rf .venv uv sync cd .. make dev ``` ### 模型连接失败 **问题**：大模型 API 调用失败。 **排查**： 1. 检查 `config.yaml` 中的模型配置是否正确 2. 检查 API Key 是否有效（环境变量或直接填写） 3. 检查 base_url 是否可访问 ### 端口被占用 **问题**：2024/8001/3000/2026 端口被占用。 **排查**： ```bash # Linux/macOS lsof -i :2024 lsof -i :2026 # Windows netstat -ano | findstr "2024" ``` **解决**：停止占用进程或修改 `config.yaml` 中的端口配置。 --- ## 输出常用命令表格 在完成安装或更新后，向用户输出以下常用命令表格： --- ### 🦌 DeerFlow 2.0 常用命令速查表 #### 📦 安装与初始化 | 命令 | 说明 | 场景 | |------|------|------| | `make setup` | 交互式安装向导（推荐新手） | 首次安装引导 | | `make check` | 检查系统依赖是否齐全 | 安装前验证 | | `make install` | 安装前后端全部依赖 | 手动安装依赖 | | `make config` | 生成配置文件（需手动编辑） | 高级用户手动配置 | | `make config-upgrade` | 合并模板新字段到现有配置 | 配置升级 | | `make doctor` | 检查配置和系统要求 | 诊断问题 | | `make setup-sandbox` | 预拉取沙箱容器镜像 | Docker 模式准备 | #### 🚀 启动与运行 | 命令 | 说明 | 端口 | 场景 | |------|------|------|------| | `make dev` | 开发模式（热重载） | localhost:2026 | 本地开发（推荐） | | `make dev-pro` | 开发模式 + Gateway | localhost:2026 | 实验特性 | | `make dev-daemon` | 后台开发模式 | localhost:2026 | 守护进程 | | `make start` | 生产模式（无热重载） | localhost:2026 | 正式运行 | | `make start-pro` | 生产模式 + Gateway | localhost:2026 | 实验特性 | | `make start-daemon` | 后台生产模式 | localhost:2026 | 守护进程 | #### ⏹ 停止与管理 | 命令 | 说明 | |------|------| | `make stop` | 停止所有运行中的服务 | | `make clean` | 停止服务��清理临时文件 | #### 🐳 Docker 模式 | 命令 | 说明 | 场景 | |------|------|------| | `make up` | 构建并启动生产 Docker | 生产部署（推荐） | | `make up-pro` | 生产 Docker + Gateway | 实验特性 | | `make down` | 停止并移除容器 | 清理 | #### ⚙️ 配置文件位置 | 文件 | 说明 | |------|------| | `config.yaml` | 主配置文件（模型、工具、沙箱等） | | `.env` | 环境变量（API Keys） | | `logs/` | 运行日志目录 | #### 🔌 服务端口映射 | 服务 | 端口 | 说明 | |------|------|------| | LangGraph | 2024 | Agent 运行时 | | Gateway | 8001 | REST API | | Frontend | 3000 | Next.js 前端 | | Nginx | 2026 | 反向代理（主入口） | --- ### 快速启动 ```bash cd ~/deer-flow && make dev ``` 访问 **http://localhost:2026** 即可使用 DeerFlow 2.0。 --- ## 文件位置（动态获取） - **安装目录**：`~/deer-flow/` - **配置文件**：`~/deer-flow/config.yaml` - **环境变量**：`~/deer-flow/.env` - **日志目录**：`~/deer-flow/logs/` 详细命令参考见 `references/deer-flow-commands.md`。

path: references/deer-flow-commands.md
content: # DeerFlow 2.0 常用命令速查表

## 📦 安装与初始化

| 命令 | 说明 | 场景 |
|------|------|------|
| `make setup` | 交互式安装向导（推荐新手） | 首次安装引导 |
| `make check` | 检查系统依赖是否齐全 | 安装前验证 |
| `make install` | 安装前后端全部依赖 | 手动安装依赖 |
| `make config` | 生成配置文件（需手动编辑） | 高级用户手动配置 |
| `make config-upgrade` | 合并模板新字段到现有配置 | 配置升级 |
| `make doctor` | 检查配置和系统要求 | 诊断问题 |
| `make setup-sandbox` | 预拉取沙箱容器镜像 | Docker 模式准备 |

## 🚀 启动与运行

| 命令 | 说明 | 端口 | 场景 |
|------|------|------|------|
| `make dev` | 开发模式（热重载） | localhost:2026 | 本地开发（推荐） |
| `make dev-pro` | 开发模式 + Gateway | localhost:2026 | 实验特性 |
| `make dev-daemon` | 后台开发模式 | localhost:2026 | 守护进程 |
| `make start` | 生产模式（无热重载） | localhost:2026 | 正式运行 |
| `make start-pro` | 生产模式 + Gateway | localhost:2026 | 实验特性 |
| `make start-daemon` | 后台生产模式 | localhost:2026 | 守护进程 |

## ⏹ 停止与管理

| 命令 | 说明 |
|------|------|
| `make stop` | 停止所有运行中的服务 |
| `make clean` | 停止服务并清理临时文件 |

## 🐳 Docker 模式

| 命令 | 说明 | 场景 |
|------|------|------|
| `make up` | 构建并启动生产 Docker | 生产部署（推荐） |
| `make up-pro` | 生产 Docker + Gateway | 实验特性 |
| `make down` | 停止并移除容器 | 清理 |
| `make docker-init` | 拉取沙箱镜像 | 初始化 |
| `make docker-start` | 启动 Docker 开发 | 开发模式 |
| `make docker-stop` | 停止 Docker 开发 | 停止 |
| `make docker-logs` | 查看 Docker 日志 | 调试 |

## 🔧 常用操作

| 操作 | 命令 |
|------|------|
| **查看帮助** | `make help` |
| **进入目录** | `cd ~/deer-flow` |
| **手动启动** | `./scripts/serve.sh --dev` |
| **手动停止** | `./scripts/serve.sh --stop` |
| **查看日志** | `tail -f ~/deer-flow/logs/langgraph.log` |

## ⚙️ 配置文件位置

| 文件 | 说明 |
|------|------|
| `config.yaml` | 主配置文件（模型、工具、沙箱等） |
| `.env` | 环境变量（API Keys） |
| `logs/` | 运行日志目录 |

## 📋 手动部署步骤（极简版）

### 前置条件

| 依赖 | 要求 |
|------|------|
| Python | ≥3.12 |
| Node.js | ≥22 |
| pnpm | 包管理器 |
| uv | Python包管理 |
| nginx | Web服务器 |
| Git | 版本控制 |

### 部署步骤

```bash
# 1. 克隆仓库
git clone https://github.com/bytedance/deer-flow.git ~/deer-flow
cd ~/deer-flow

# 2. 创建配置文件（从模板复制）
cp .env.example .env
cp config.example.yaml config.yaml

# 3. 编辑 config.yaml，添加模型配置
# （配置 big-pickle：base_url=https://opencode.ai/zen/v1，api_key 留空）

# 4. 安装依赖
make check    # 检查环境
make install  # 安装前后端

# 5. 启动服务
make dev
```

### 卸载步骤

```bash
cd ~/deer-flow

# 1. 停止服务
make stop

# 2. 清理临时文件
make clean

# 3. 删除目录
cd ~ && rm -rf ~/deer-flow
```

### 更新步骤

```bash
cd ~/deer-flow

# 1. 拉取最新代码
git pull origin main

# 2. 合并新配置字段
make config-upgrade

# 3. 重新安装依赖
cd backend && rm -rf .venv && uv sync && cd ..
make install
```

## 🔌 服务端口映射

| 服务 | 端口 | 说明 |
|------|------|------|
| LangGraph | 2024 | Agent 运行时 |
| Gateway | 8001 | REST API |
| Frontend | 3000 | Next.js 前端 |
| Nginx | 2026 | 反向代理（主入口） |

## 🖥️ 多平台支持

### 检测脚本

```bash
# 自动检测操作系统
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case "$OS" in
    darwin*)     echo "macOS" ;;
    linux*)     echo "Linux" ;;
    mingw*|nt*) echo "Windows" ;;
    *)          echo "Unknown: $OS" ;;
esac
```

### 路径变量

```bash
# 统一使用 $HOME 或 ~
INSTALL_DIR="$HOME/deer-flow"
CONFIG_FILE="$INSTALL_DIR/config.yaml"
ENV_FILE="$INSTALL_DIR/.env"
LOG_DIR="$INSTALL_DIR/logs"
```

### 常用命令差异

| 操作 | macOS/Linux | Windows (PowerShell) |
|------|-------------|---------------------|
| 查看进程 | `lsof -i :端口` | `netstat -ano | findstr "端口"` |
| 终止进程 | `kill -9 PID` | `taskkill /PID PID` |
| 环境变量 | `echo $VAR` | `$env:VAR` |

> **Windows 用户注意**：推荐使用 WSL2 运行 DeerFlow。在 PowerShell 中安装 WSL：
> ```powershell
> wsl --install -d Ubuntu
> ```
> 安装后进入 WSL Ubuntu 环境，所有命令与 Linux 一致。

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)