DeerFlow 技能

通过其 HTTP API 与正在运行的 DeerFlow 实例通信。DeerFlow 是一个基于 LangGraph 构建的 AI 智能体平台，用于编排子智能体进行研究、代码执行、网页浏览等操作。

架构

DeerFlow 在 Nginx 反向代理后面暴露两个 API 接口：

环境变量

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

在进行 curl 调用时，始终像这样解析 URL：

# 从环境变量解析基础 URL（在任何 API 调用之前执行）
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. 发送消息（流式传输）

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

步骤 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": "你的消息"}]
        }
      ]
    },
    "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: <事件类型>
data: <json_data>

关键事件类型：

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

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

• 闪电模式：thinking_enabled: false, is_plan_mode: false, subagent_enabled: false
• 标准模式：thinking_enabled: true, is_plan_mode: false, subagent_enabled: false
• 专业模式：thinking_enabled: true, is_plan_mode: true, subagent_enabled: false
• 超级模式：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/<技能名称>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

7. 列出智能体

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/<线程ID>/uploads" \
  -F "files=@/path/to/file.pdf"

支持 PDF、PPTX、XLSX、DOCX —— 自动转换为 Markdown。

10. 列出已上传的文件

curl -s "$DEERFLOW_GATEWAY_URL/api/threads/<线程ID>/uploads/list"

11. 获取线程历史

curl -s "$DEERFLOW_LANGGRAPH_URL/threads/<线程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 "你的问题"

有关实现，请参阅 scripts/chat.sh。该脚本：

1. 检查健康状态
2. 创建一个线程
3. 流式运行并收集最终的 AI 响应
4. 打印结果

解析 SSE 输出

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

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

错误处理

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

提示

• 对于简单问题，使用闪电模式（最快，无规划）。
• 对于研究任务，使用专业模式或超级模式（启用规划和子智能体）。
• 可以先上传文件，然后在消息中引用它们。
• 线程 ID 是持久的 —— 你可以稍后返回对话。