DeerFlow Skills：SKILL.md 与渐进式加载

让 agent 写「带引用的行业对比报告」时，若没有固定流程，常见结果是随便搜几条、不落盘、格式散。Skills 把可复用步骤写成 Markdown 操作手册：系统提示词里先放技能目录，agent 需要时再读全文，按手册一步步做，报告结构更稳。

SKILL.md、public / custom、allowed-tools

每个技能是一份固定名 SKILL.md，放在 skills/public/<技能名>/ 或 skills/custom/<技能名>/。顶部 YAML front-matter 至少包含 name（唯一标识）与 description（什么时候该用）；正文写工作流、引用规范、落盘路径之类约定。例如 deep-research 可以写：先确认范围、至少搜若干来源、结论加引用、保存到 /mnt/user-data/outputs/、再用 present_files 呈现。

SkillCategory（skills/types.py）区分 public 与 custom。内置目录升级可能被覆盖，用户改过的内容应放 custom/，否则下次升级改动会丢。可选字段 allowed-tools：字段缺失表示不限制工具；空列表表示显式不用工具；给出列表则只能用名单内工具（解析在 parser.py，要求是非空字符串列表）。

技能目录里还可挂 references/、templates/、scripts/、assets/。SKILL.md 引用这些相对路径后，agent 再 read_file 按需加载，这是渐进式加载的第二层。支持文件路径必须落在上述四个子目录内，禁止 ..，最终路径还要落在技能根目录内（ensure_safe_support_path）。

---
name: deep-research
description: 深度调研并生成带引用的报告
---

# 深度调研技能
1. 确认调研范围
2. 搜索并给结论加引用
3. 写入 outputs，再用 present_files 呈现

渐进式加载与缓存

若把全部技能正文塞进系统提示词，上下文很快爆。DeerFlow 只把「名字 + 描述 + 容器路径」拼进提示词，例如 /mnt/skills/public/deep-research/SKILL.md，外面包一层 <available_skills>。agent 决定采用某技能后再读文件，类似图书馆先看索引卡再取书。

加载链路：skill_storage.load_skills 扫描两个目录 → parse_skill_file 用正则抽 --- 之间的 front-matter，只读元数据，不读正文 → 与 ExtensionsConfig 的启用状态合并 → get_skills_prompt_section 生成提示词段。未启用的技能即使文件在磁盘上也不会出现在列表里。

列表生成带 @lru_cache(maxsize=32)，缓存键是技能签名（名、描述、类别、路径等）。启用状态变化时后台线程刷新（_ensure_enabled_skills_cache / _start_enabled_skills_refresh_thread），避免每次请求都扫盘阻塞。首次可能短暂未命中，后续命中；网页上开关技能后能较快反映到后续请求，靠的就是后台刷新。

斜杠命令：SkillActivationMiddleware

用户输入以 /技能名 开头时，例如 /deep-research 调研 Cursor，SkillActivationMiddleware 在调模型前检查最新用户消息，经 parse_slash_skill_reference 解析名称，再读完整 SKILL.md。读文件前会 resolve 并要求相对路径仍在 skills 根下，挡住目录穿越。内容包装成隐藏 HumanMessage（hide_from_ui=True，并标记 slash_skill_activation）插到用户原文前面，同一条用户消息只激活一次。效果是用户点名用哪本手册，不必等模型自己挑。

安装安全与自我演化

从网上下载的 .skill 本质是 ZIP。安装侧会做多层检查：is_unsafe_zip_member 拒绝绝对路径与含 .. 的成员；is_symlink_member 跳过符号链接；safe_extract_skill_archive 限制解压后总大小（源码上限约 512MB），防止 ZIP 炸弹；再用安全审查模型扫描 SKILL.md 以及 scripts/、references/、templates/ 等可扫描文件。判定为 allow / warn / block；任一项 block，整包拒装。审查关注提示词注入、系统角色覆盖、提权一类内容。把来路不明的技能包当普通 Markdown 直接信任，风险太大。

开启 skill evolution 后，提示词会提示：工具调用较多（例如五次以上）、踩过非显然坑、被用户纠正后才做对、发现可复用工作流时，考虑创建或修补 skills/custom/ 下的技能。倾向用小范围替换改差异，少做整文件重写；新建前应先问用户；一次性简单任务可以跳过。配套能力里还有条件装配的 skill_manage_tool。复杂流程做通了，才值得沉淀成手册。

一次「按技能写报告」怎么走

用户说「调研 2026 年最火的 AI 编程工具」时，agent 先在系统提示词的技能目录里看到 deep-research，再 read_file 拉全文，按流程搜、写、加引用，最后落盘并 present_files。系统提示词始终只有元数据；正文按需出现。用户侧感受是报告结构稳定：有引用、有文件、有呈现，少见每次随机发挥。

若用户直接 /deep-research …，中间件会跳过「猜该不该用」这一步，把全文先注入隐藏消息。两种入口共用同一份 SKILL.md，差别只在激活时机：模型自选 vs 用户点名。搜索、读写、跑命令仍走工具层；Skills 管的是步骤约定。