扩展 Deva 能力:SKILL.md 技能与 MCP 服务接入完全教程

原创2026-11-07 16:20:281,930 阅读

扩展 Deva 能力:SKILL.md 技能与 MCP 服务接入完全教程

Deva 是一款以对话为唯一入口的桌面 AI Agent 客户端。除了内置的文件读写、命令执行等能力外,它还提供了两套强大的扩展机制:SKILL.md 技能与 MCP 服务。本文带你从零开始掌握这两者的安装、配置与使用,让 Deva 按需获得新能力,且全部数据保存在本机。

Deva AI 助手桌面客户端图标:支持 SKILL.md 技能与 MCP 服务扩展

为什么需要扩展:技能与 MCP 的分工

Deva 的扩展体系分两层,解决不同类型的问题:

扩展方式 本质 适合场景
SKILL.md 技能 一份写给模型的操作指令文档 教会 Deva "某类任务该怎么做"
MCP 服务 连接外部工具服务器 让 Deva "获得新的工具"
  • 技能是知识:比如"处理 PDF 文件时按这套流程操作"。
  • MCP是工具:比如连接一个数据库查询服务、搜索服务,其暴露的工具会自动出现在 Deva 的可用工具列表中。

两者都可以限定只对某些角色可用,从而形成角色专属能力。相关实现可参考 skills.ts 与 mcp.ts。

一、SKILL.md 技能:结构与格式

1. 技能放在哪里

每个技能是技能目录下的一个文件夹,入口文件为 SKILL.md:

~/.deva/skills/<技能名>/
├── SKILL.md       (必需)frontmatter + 正文
├── scripts/       (可选)可执行脚本
├── references/    (可选)参考文档
└── assets/        (可选)模板、图标等产出素材

目录有实时监听,手动放入或修改文件后即时生效,无需重启。

2. frontmatter 字段速查

SKILL.md 第一行是 ---,随后是 YAML frontmatter,正文即完整操作指令:

---
name: pdf-tools
description: 处理 PDF 文件:旋转、合并、拆分、提取文字。用户要编辑或转换 PDF 时使用。
trigger: (可选)触发方式的补充说明
allowed-tools: run_command, read_file
---

# PDF 工具
(操作步骤,用祈使句写……)
字段 必填 说明
name ✅ 显示名,/技能名 与自动匹配都靠它
description ✅ 决定技能何时被触发,必须写在一行内
trigger ❌ 触发方式的补充说明
allowed-tools ❌ 建议工具清单,仅作提示,不授予权限

💡 模型平时只看到技能的 name + description 清单;当任务匹配或你输入 /技能名 时,才会加载完整正文。这种渐进式披露让技能再多也不额外占用上下文。

二、安装技能的三种方式

方式一:对话创建(推荐新手)

在输入框输入内置技能命令:

/create-skill

Deva 会引导你从具体用例出发,规划脚本与参考文档,校验后自动落盘并启用。单文件技能由 create_skill 工具创建;多文件技能会直接写进技能目录。

方式二:上传技能包

进入 设置 → 扩展 页,点击上传按钮,选择:

  • .zip 技能包:解压后需包含 SKILL.md(位于包根目录或唯一顶层目录下),附带文件一并导入;
  • 单个 SKILL.md 文件:导入后自动启用。

导入设有安全限额:总解压体积 20 MB、最多 200 个文件、单文件不超过 10 MB,并会拒绝不安全的文件路径。

方式三:直接写入技能目录

开发者可以把技能文件夹直接拷贝到 ~/.deva/skills/ 下。目录变动被监听器捕获后,技能清单自动刷新。

三、调用技能与日常管理

  • 自动触发:任务与 description 描述的场景匹配时,模型自动加载;
  • 显式调用:输入框输入 /<技能名> 立即触发;
  • 启停与删除:在 设置 → 扩展 页可随时关闭、启用或删除技能(删除是移入回收站,可还原)。

四、MCP 服务接入:三种传输方式

MCP(Model Context Protocol)服务对外暴露一组工具,接入并连接后,这些工具会自动并入 Deva 的工具表。Deva 支持三种传输方式:

传输 适用场景 必填字段
stdio 本地子进程(最常见,如 npx、uvx 启动的服务器) command + args
sse 远程 SSE 服务 url
http 远程 Streamable HTTP 服务 url

服务配置保存在 ~/.deva/mcp.json,沿用 Claude Desktop 的 mcpServers 结构,方便已有配置直接迁移。结构定义见 mcp-config.ts。

用对话接入:输入 /create-mcp

最简单的方式是对话创建:

  1. 输入 /create-mcp,描述你想接入的服务(提供什么能力、从哪获取);
  2. Deva 会与你确认传输方式、命令/地址、参数,并只收集密钥字段名(如 GITHUB_TOKEN),绝不索要真实密钥值;
  3. 确认后调用 create_mcp 工具写入配置,自动启用并在后台连接,其工具从下一条消息起可用;
  4. 若有密钥占位字段,去 扩展 页填写真实密钥(加密存储),填好后自动重连,无需其他操作。

🔐 安全设计:敏感的环境变量与请求头以 { "secretRef": "..." } 占位,真实值经系统 safeStorage 加密保存在 ~/.deva/secrets.json,明文永不落配置文件、不回传界面。

扩展页管理 MCP 服务

设置 → 扩展 页可以查看每个服务的实时状态:

状态 含义 处理建议
disconnected 未启用 打开启用开关
needs_config 配置不完整 补齐 command 或 url
needs_secret 缺密钥 为缺的字段填入密钥
connecting / connected 连接中 / 已连接 等待即可
error 连接失败 查看中文错误提示并点"重试"

常见错误会被翻译成明确提示,例如:找不到启动命令(ENOENT):请检查 command 是否已安装、是否在系统 PATH 中、鉴权失败(401/403):请检查密钥 / 令牌是否正确。映射逻辑见 mcp.ts。

此外,意外断开时 Deva 会自动退避重连:远程服务最多 5 次,stdio 子进程最多 2 次,用尽后停在 error 状态等你手动重试。

五、进阶:把技能与 MCP 限定给特定角色

在扩展页可以为每个技能、每个 MCP 服务设置可用角色:

  • 不限定时,全部角色可用;
  • 限定后,只有选中角色的对话中才能看到该技能/工具,形成角色专属能力;
  • 启用开关仍是总闸,且 MCP 的连接与角色无关(启用即连接)。

相关实现见 ext-roles.ts。

六、常见问题速答

Q:技能写完后多久生效? 目录变动即时刷新,下一轮对话即可进入技能清单,无需重启。

Q:description 怎么写才容易被触发? 写清"做什么 + 什么时候用",包含场景、文件类型和用户的典型说法。它是常驻模型视野的唯一信息。

Q:MCP 显示 error,一直连不上怎么办? 先看中文错误提示:ENOENT 检查命令是否安装;401/403 检查密钥;然后点"重试"。stdio 服务确认启动命令在系统 PATH 中。

Q:从 Claude Desktop 迁移 MCP 配置可行吗? 可行。~/.deva/mcp.json 沿用 mcpServers 键名,可直接对照迁移,密钥字段需在扩展页重新填入。

总结

目标 操作
教会 Deva 新流程 /create-skill 或上传 .zip / SKILL.md
给 Deva 加新工具 /create-mcp 或编辑 ~/.deva/mcp.json
控制能力范围 扩展页设置可用角色
排错 扩展页查看状态与中文错误提示

掌握 SKILL.md 技能 与 MCP 服务接入,你就能像搭积木一样扩展 Deva:技能沉淀方法论,MCP 接入外部世界,且一切配置本地保存、按需对角色生效。快去给你的 Agent 装上第一块扩展吧 🚀

登录后查看全文
deva