Deer-Flow 的技能系统与 Gateway API

Deer-Flow 的技能系统与 Gateway API

学习目标

• 理解 Deer-Flow 的技能加载机制和 .skill 归档格式
• 掌握 Gateway API 的双路由设计（LangGraph 兼容 + 原生 REST）
• 学会分析 RunManager/RunStore 契约

---

项目实践

技能系统

技能格式

每个技能是一个包含 SKILL.md 的目录：

skills/public/my-skill/
└── SKILL.md          # YAML frontmatter + Markdown 内容

SKILL.md 的 frontmatter 包含：

---
name: my-skill
description: 技能的简要描述
license: MIT
allowed-tools: ["bash", "read_file"]
---

# 技能内容...

按需加载

技能不是在启动时全部加载，而是在任务需要时才加载。这保持了上下文窗口精简，使 Deer-Flow 在 Token 敏感的模型下也能工作。

.skill 归档安装

通过 Gateway API 安装外部技能：

POST /api/skills/install
Content-Type: multipart/form-data

file: my-skill.skill    # ZIP 归档

• 解压到 skills/custom/ 目录
• 接受标准可选 frontmatter 元数据（version、author、compatibility）
• 安装后通过 extensions_config.json 的 skills 键管理启用状态

Gateway API 双路由设计

Deer-Flow 的 Gateway 同时暴露两种路由：

RunManager / RunStore 契约

• RunManager.get() 是异步的，调用者必须 await
• 持久化 RunStore 配置时，get() 和 list_by_thread() 从 Store 回填历史运行
• 内存记录优先 — 同一 run_id 的内存记录覆盖 Store 记录
• cancel() 和 create_or_reject() 通过 RunStore.update_status() 持久化中断状态

安全增强

• 产出物服务（/api/artifacts）强制将活动内容类型（text/html、application/xhtml+xml、image/svg+xml）作为下载附件，降低 XSS 风险
• 意外失败返回通用 500 详情，不暴露内部错误信息

---

问题与规避

技能名称冲突

安装外部技能时可能与内置技能重名。

规避：安装时检测名称冲突，提示用户重命名或覆盖。

LangGraph 兼容路由的路由重写

Nginx 将 /api/langgraph/* 重写为 Gateway 的 /api/* 路由。路径不匹配可能导致 404。

规避：在 Gateway 端保持 LangGraph 兼容的路径映射。

---

参考来源

• Deer-Flow CLAUDE.md — Skills System 和 Gateway API 章节
• packages/harness/deerflow/skills/ — 技能系统源码
• app/gateway/ — Gateway API 源码