扩展 Deva 能力:SKILL.md 技能与 MCP 服务接入完全教程
扩展 Deva 能力:SKILL.md 技能与 MCP 服务接入完全教程
Deva 是一款以对话为唯一入口的桌面 AI Agent 客户端。除了内置的文件读写、命令执行等能力外,它还提供了两套强大的扩展机制:SKILL.md 技能与 MCP 服务。本文带你从零开始掌握这两者的安装、配置与使用,让 Deva 按需获得新能力,且全部数据保存在本机。
为什么需要扩展:技能与 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
最简单的方式是对话创建:
- 输入
/create-mcp,描述你想接入的服务(提供什么能力、从哪获取); - Deva 会与你确认传输方式、命令/地址、参数,并只收集密钥字段名(如
GITHUB_TOKEN),绝不索要真实密钥值; - 确认后调用
create_mcp工具写入配置,自动启用并在后台连接,其工具从下一条消息起可用; - 若有密钥占位字段,去 扩展 页填写真实密钥(加密存储),填好后自动重连,无需其他操作。
🔐 安全设计:敏感的环境变量与请求头以
{ "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 装上第一块扩展吧 🚀