claude-to-deerflow

DeerFlow 技能

通过 HTTP API 与运行中的 DeerFlow 实例通信。DeerFlow 是一个基于 LangGraph 构建的 AI Agent 平台，可协调子 Agent 执行研究、代码运行、网页浏览等任务。

架构

DeerFlow 通过 Nginx 反向代理提供两个 API 接口：

服务	直连端口	经代理访问	用途
网关 API	8001	$DEERFLOW_GATEWAY_URL	REST 端点和内嵌 Agent 运行时
兼容 LangGraph 的 API	8001	$DEERFLOW_LANGGRAPH_URL	Agent 线程、运行和流式传输

环境变量

所有 URL 均可通过环境变量配置。发出任何请求前，请先读取这些环境变量。

变量	默认值	描述
DEERFLOW_URL	http://localhost:2026	统一代理基础 URL
DEERFLOW_GATEWAY_URL	${DEERFLOW_URL}	网关 API 基础 URL（模型、技能、记忆、上传）
DEERFLOW_LANGGRAPH_URL	${DEERFLOW_URL}/api/langgraph	LangGraph API 基础 URL（线程、运行）

执行 curl 调用时，始终按以下方式解析 URL：

# Resolve base URLs from env (do this FIRST before any API call)
DEERFLOW_URL="${DEERFLOW_URL:-http://localhost:2026}"
DEERFLOW_GATEWAY_URL="${DEERFLOW_GATEWAY_URL:-$DEERFLOW_URL}"
DEERFLOW_LANGGRAPH_URL="${DEERFLOW_LANGGRAPH_URL:-$DEERFLOW_URL/api/langgraph}"

可用操作

1. 健康检查

确认 DeerFlow 正在运行：

curl -s "$DEERFLOW_GATEWAY_URL/health"

2. 发送消息（流式传输）

这是主要操作。它会创建一个线程，并流式传输 Agent 的响应。

步骤 1：创建线程

curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads" \
  -H "Content-Type: application/json" \
  -d '{}'

响应：{"thread_id": "<uuid>", ...}

步骤 2：流式传输一次运行

curl -s -N -X POST "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/runs/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "lead_agent",
    "input": {
      "messages": [
        {
          "type": "human",
          "content": [{"type": "text", "text": "YOUR MESSAGE HERE"}]
        }
      ]
    },
    "stream_mode": ["values", "messages-tuple"],
    "stream_subgraphs": true,
    "config": {
      "recursion_limit": 1000
    },
    "context": {
      "thinking_enabled": true,
      "is_plan_mode": true,
      "subagent_enabled": true,
      "thread_id": "<thread_id>"
    }
  }'

响应是一个 SSE 流。每个事件的格式如下：

event: <event_type>
data: <json_data>

主要事件类型：

• metadata — 运行元数据，包括 run_id
• values — 包含 messages 数组的完整状态快照
• messages-tuple — 增量消息更新（AI 文本片段、工具调用、工具结果）
• end — 流式传输已完成

上下文模式（通过 context 设置）：

• Flash 模式：thinking_enabled: false, is_plan_mode: false, subagent_enabled: false
• Standard 模式：thinking_enabled: true, is_plan_mode: false, subagent_enabled: false
• Pro 模式：thinking_enabled: true, is_plan_mode: true, subagent_enabled: false
• Ultra 模式：thinking_enabled: true, is_plan_mode: true, subagent_enabled: true

3. 继续对话

要发送后续消息，请复用步骤 2 中的同一个 thread_id，并附上新消息再次 POST 一次运行。

4. 列出模型

curl -s "$DEERFLOW_GATEWAY_URL/api/models"

返回：{"models": [{"name": "...", "provider": "...", ...}, ...]}

5. 列出技能

curl -s "$DEERFLOW_GATEWAY_URL/api/skills"

返回：{"skills": [{"name": "...", "enabled": true, ...}, ...]}

6. 启用/禁用技能

curl -s -X PUT "$DEERFLOW_GATEWAY_URL/api/skills/<skill_name>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

7. 列出 Agent

curl -s "$DEERFLOW_GATEWAY_URL/api/agents"

返回：{"agents": [{"name": "...", ...}, ...]}

8. 获取记忆

curl -s "$DEERFLOW_GATEWAY_URL/api/memory"

返回用户上下文、事实和对话历史摘要。

9. 将文件上传到线程

curl -s -X POST "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads" \
  -F "files=@/path/to/file.pdf"

支持 PDF、PPTX、XLSX、DOCX，并会自动转换为 Markdown。

10. 列出已上传文件

curl -s "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads/list"

11. 获取线程历史记录

curl -s "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/history"

12. 列出线程

curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads/search" \
  -H "Content-Type: application/json" \
  -d '{"limit": 20, "sort_by": "updated_at", "sort_order": "desc"}'

使用脚本

若要发送消息并收集完整响应，请使用辅助脚本：

bash /path/to/skills/claude-to-deerflow/scripts/chat.sh "Your question here"

实现方式请参阅 scripts/chat.sh。该脚本会：

1. 检查健康状态
2. 创建线程
3. 流式传输运行并收集最终 AI 响应
4. 输出结果

解析 SSE 输出

流会返回 SSE 事件。要从 values 事件中提取最终 AI 响应：

• 找到最后一个 event: values 块
• 解析其中的 data JSON
• messages 数组包含所有消息；最后一条 type: "ai" 的消息就是响应
• 该消息的 content 字段是 AI 的文本回复

错误处理

• 如果健康检查失败，说明 DeerFlow 未运行。告知用户需要启动它。
• 如果流返回错误事件，请提取并显示错误消息。
• 常见问题：端口未开放、服务仍在启动、配置错误。

提示

• 对于简单问题，使用 flash 模式（速度最快，无需规划）。
• 对于研究任务，使用 pro 或 ultra 模式（支持规划和子 Agent）。
• 你可以先上传文件，然后在消息中引用它们。
• 线程 ID 会持续保留，因此你可以稍后继续对话。