MCP 与 Skills

Spark Work 的能力扩展分两层：Skill 是写给 Agent 读的「操作说明书」（一份SKILL.md），MCP 是给 Agent 调的「外部工具集」（JSON-RPC 服务）。 一句话区分：Skill 决定「怎么做」，MCP 决定「能用什么工具」。两者独立启用、可以叠加， 同一个 Skill 常常会点名要用某个 MCP 命名空间。

1. 能力层：Skill 与 MCP 各管什么

除数据库里配置的 MCP 之外，应用还有一批「会话级内置 MCP server」，它们不占用mcp_servers 表、由运行时代码直接注入，按会话能力开关出现或隐藏：

这些内置 server 不受 MCP 管理界面控制（界面里搜不到它们），也不要去mcp_servers 表里找。

2. Skill 的真实来源与落盘位置

技能可以来自七个地方，落盘位置和 skills 表的 scope 各不相同：

项目级技能的扫描规则：会话绑定的第一个工作区根目录为扫描起点，上面目录名 的先后顺序就是同名技能的优先级（先发现者优先，重名只保留一个）。项目级技能不出现在 「技能」页的通用列表里，它们只在该会话的输入框 「+ → 技能」菜单里可见——所以「我在项目里放了 SKILL.md，为什么技能页看不到」属于预期行为。

SKILL.md 的硬性要求：文件必须以 --- 开头、以 --- 结束的 YAML frontmatter 起始，且 name、description 都是非空字符串。 缺 frontmatter、YAML 解析失败、缺 name / description 的目录会被直接跳过并在扫描结果里记为 issue，不会出现在技能列表中。可选字段为 version、author、 category、tags、license、requiredTools、tools；其中 requiredTools 与 tools 会被合并成该技能的 依赖工具清单。

---
name: sql-explain
description: "把 SQL 查询拆成执行步骤并解释代价。用户粘贴 EXPLAIN 输出或问「这条 SQL 为什么慢」时加载。"
version: 1.0.0
author: Your Name
category: coding
tags: [sql, explain, performance]
---

（正文：触发场景、工作流、注意事项）

3. 内置 Skill 怎么进库、怎么进上下文

1. 启动扫描：每次 skill:list（打开技能页、会话取技能列表）都会调用 ensureBuiltInSkills()。它重新读取内置目录里的每个 SKILL.md， 与数据库比对：已存在就更新名称 / 版本 / 路径 / manifest 内容，不存在就新建， 老格式（local:bundled:*）和已下架（builtin:* 但文件没了）的行会被清掉。 所以修改 resources/skills/<slug>/SKILL.md 后不需要手动同步，重开技能页即可。
2. 进 prompt 的只有目录：system prompt 里注入的是技能目录（[Available Skills Catalog]：每条只有 id、名称、截断后的描述）， 并明确告知「完整指令未加载，需要时用 mcp__spark_platform__skills_load 按 id 取」。 这就是「渐进式披露」——装 20 个技能也只占一份目录的体积。
3. 谁会被列出来：会话按当前 Agent 的 skillIds 与 disabledSkillIds 计算可用技能集；团队成员的技能集来自成员自身配置， 不是 Host 的。原生 Claude SDK 路径还会把启用的技能做成托管插件目录 （{userData}/skills/_plugin/）交给 SDK 原生技能发现，失败时回落到 skills_load 工具路径。
4. 手动点名一个技能：会话输入框的「+ → 技能」子菜单里点技能名，会把 @技能名 插进输入框；也可以直接让 Agent 调用 skills_load。

常见坑：技能从市场装完不会自动生效。「Skill 必须分配给 Agent 才能在对话中 生效」——应用在安装成功后会弹提示引导你去分配。到「Agent」页编辑目标 Agent，在 Skills 一栏点 「管理 Skills」勾选即可。另外，如果某个技能被 skills_toggle 关成了 enabled=0，它也不会进入任何会话。

4. 精选可安装目录（33 项）

「技能 → 精选推荐」Tab 里的卡片来自一份写死在代码里的清单INSTALLABLE_SKILL_CATALOG。它不落库、不依赖联网， 新机器装完就能看到卡片；点「安装」时才真正下载技能内容。

当前清单共 33 项，分四组：

• ppt-master（Hugo He）：PDF / DOCX / URL / Markdown → SVG → 原生可编辑 PPTX
• playwright（Microsoft）：playwright-cli 终端浏览器自动化技能
• 14 项 superpowers-* 工程流程技能（brainstorming / writing-plans / test-driven-development / systematic-debugging / using-git-worktrees 等）
• 6 项 gitnexus-* 代码智能技能（cli / exploring / impact-analysis / debugging / refactoring / guide）
• 11 项影视与叙事技能（screenwriting-lab、ai-film-production、hyperframes*、gsap-animation、scroll-storyteller、nano-banana、illustrated-slides-with-nano-banana 等）

每条目的 source 有三种形态，安装时按下面的顺序生效：

安装链路（renderer ↔ 主进程 ↔ runtime）：

技能页「精选推荐」Tab
  ├─ invoke skill:list-installable        → SkillRegistryService.listInstallableCatalog()（附 installed 状态）
  ├─ invoke skill:install-catalog {slug}  → installFromCatalog(slug, onProgress)
  │     └─ 进度经 stream:skill:install-progress 推回渲染层（payload: slug / source / downloaded / total）
  ├─ invoke skill:uninstall-catalog {slug}→ 删磁盘目录 + 删 DB 行
  └─ invoke skill:install-status          → 全局安装状态（含 failed 与错误信息）

新增一条精选技能，只改 installable-catalog.ts 一个文件：

{
  id: 'my-skill',          // 卡片唯一标识（不进 DB）
  slug: 'my-skill',        // 落盘目录名；安装状态与去重都按它判定
  name: 'My Skill',
  description: '一句话描述',
  icon: '🧩',
  author: '作者',
  tags: ['tag1', 'tag2'],
  source: {
    type: 'artifact',
    artifactId: 'skill.my-skill',
    manifestUrl: DEFAULT_SPARK_INSTALL_MANIFEST_URL,
    fallback: { type: 'tarball', repo: 'owner/name', ref: 'main', path: 'skills/my-skill' },
  },
  homepageUrl: 'https://github.com/owner/name',
  postInstallHint: '可选：安装后依赖提示（如 pip install -r requirements.txt）',
}

装机后的身份：技能落到 {userData}/skills/<slug>/， DB 行 scope=user、enabled=1，id 为来源指纹 skill:catalog:<hash>。artifact 来源的条目同时把 tarball 兜底来源的指纹一起登记， 因此「先装 artifact、后装 fallback」不会产生两行。卸载只删「root_path 恰好等于{userData}/skills/<slug>」或「id 命中上述指纹」的那一行， 不会误删你手动导入的同名技能。安装完成若有 postInstallHint，会单独弹一条 提示（例如 ppt-master 需要 Python / Node / wheelhouse 依赖），它只是文字提示，不会自动装依赖。

5. 添加 / 配置 MCP 服务器

入口：左侧导航「扩展中心」→「MCP」页签 → 右上角「添加 MCP」。 同页签另有「自定义工具 / 连接器 / 团队商店」三个 Tab，别和 MCP 列表混淆。 点卡片进入右侧抽屉「添加 MCP 服务器 / 编辑 MCP 服务器」，分三组字段：

• 基本信息：名称（工具列表里的标识，也是 mcp__<名称>__* 的前缀）、 作用域、描述、启用开关。
• 启动配置：传输三选一 stdio / http / sse。 stdio 下填「启动命令」与「参数」（参数框按空格切分后写入 args 数组）； http / sse 下填 URL。
• 认证方式（仅 http / sse 显示）：无 或 OAuth 2.0。
• 环境变量（标注「仅 stdio 模式生效」）：KEY / value 行，写入配置的 env。

卡片的「作用域」筛选提供五个值：system、user、project、team、session。需要注意：

• 作用域是标签和筛选维度。会话加载 MCP 时取的是「所有enabled 的 server」，并不按作用域过滤（见第 7 节）， 所以不要指望把某个 server 标成 session 就只对它生效。
• 另有一个 managed 作用域不在下拉里：它由应用自动注册 （当前是 playwright），不允许改名，也不允许删除，只能启用 / 停用或改配置。 界面上你只会看到它显示为 managed 标签。

5.1 配置 JSON 的真实字段

抽屉保存时写入的就是这段 JSON（存在 mcp_servers.config_json）。读取端做了字段兼容 与自愈，直接编辑配置或让 Agent 建 server 时要按下面的规则来：

已知自愈行为：某条配置声明了 stdio 但没有 command 却带 url，读取时会按 http 处理；反之如果既没有可识别的传输、 也没有 url / command，这个 server 会被跳过（日志里写 no valid transport in config）， 而不是退化成一个跑 npx 的空进程。

5.2 OAuth 2.0（http / sse）

远程 MCP 需要授权时：认证方式选 OAuth 2.0，按需填 OAuth scope； 「动态注册」默认开（走 DCR 自动注册客户端），关掉时必须填 Client ID （Client Secret 可选）。授权状态有五个取值：unconfigured / needs-auth / authorizing / authorized / failed，对应卡片上的 「需要授权 / 授权中 / 已授权 / 授权失败」标签。令牌由主进程的 MCP OAuth 服务保管并自动刷新， 调用时以 Authorization: Bearer 头注入；未授权时该 server 会被跳过， 不会阻塞会话。普通（无 OAuth）MCP 的卡片状态标签是「本地配置 / 配置不完整 / 未启用」。

6. 存储、状态与热更新

• 存哪儿：MCP 配置存在本地 SQLite（{userData}/spark.db）的 mcp_servers 表，字段为 id / scope / name / config_json / enabled / bundle_id / created_at / updated_at。bundle_id 非空表示它由某个工作流包导入。
• 创建即启动：新建 server 时若 enabled 不是 false， 后台会异步发起连接（OAuth 类型的除外，需先授权）。启动失败不回滚 DB 行， 失败原因通过状态查询暴露，避免「保存成功但连不上」时丢配置。
• 改配置会重连：更新一个已连接的 server，会先停后启； 从未连接的 server 由「停用 → 启用」触发启动。卡片的开关直接调 mcp:update 写 enabled。
• 状态查询：mcp:server-status 返回 { connected, toolCount, error?, authStatus? }；mcp:server-tools 返回该服务器真实的工具名 / 描述 / 入参 schema。 这两个 channel 只对「已连接」的 server 有数据，断开或未启动时 toolCount 为 0。
• 热更新是「下一轮生效」而不是「立刻生效」：MCP 的 create / update / delete / start / stop / tools-changed 都会让运行时的 MCP 版本号 +1。 下一轮对话开始时发现版本变化，就会强制开一个全新会话（不复用旧会话上下文）， 让新工具清单生效。原因很实际：SDK 在 query 启动时就冻结了工具列表，无法在飞行中修改。 正在跑的那一轮不受影响。
• managed 保护：playwright 这类 managed server 不能改名、不能删除， 想让它消失只能在界面上停用。

7. MCP 与会话 / Agent 的挂载关系

• 默认全量挂载：Agent 未在编辑页「MCP 服务」区块做任何点选时，构建会话 MCP 配置取的是 listServers() 里所有 enabled 的 server，逐个解析 传输并注入，不区分 scope。所以「加好 MCP，所有会话都能用」对默认 Agent 依然成立，后续新增 server 也会自动纳入。
• 按 Agent 按需挂载：Agent 的 mcpServerIds 是按需挂载的载体 ——部分点选后该 Agent 的会话、团队成员与工作流节点只挂载所选 MCP（自定义 server 按 DB 行 id、内置服务按 builtin:spark_* 合成 id 存储）；会话基础能力 （文件交付 / 结果回读 / 记忆检索 / 会话服务）始终保留，平台管理等重型内置在 Spark / Codex 引擎下强制挂载（技能加载依赖）。
• 只读原子成员例外：工作流里的只读原子成员（输入 / 路由 / 计划 / 复核 / 产物节点）从空能力集开始，不加载任何用户自定义 MCP。
• 被静默跳过的情形：配置解析不出有效传输、OAuth server 未授权（拿不到 token）、 配置 JSON 不合法。跳过只写日志，不中断会话——排查「启用了却没有工具」先看这三条。
• 名称就是工具前缀：server 名称决定工具命名空间 mcp__<name>__<tool>。同名 server 会互相覆盖， 所以别把自建 server 命名成 spark_search、spark_platform 这类内置名字。

8. 让 Agent 管理 MCP 与 Skill

内置技能 builtin:platform-manager 暴露了 mcp__spark_platform__* 工具，其中直接相关的是：

可以直接这样对 Agent 说：

• 「帮我把 https://mcp.example.com/mcp 加成一个 MCP，名字叫 doc-search」
• 「检查一下 playwright 这个 MCP 的状态，连上了但工具是 0 的话告诉我原因」
• 「用 skills_load 读一下 builtin:spark-workflow-generator，然后帮我生成一个工作流 JSON」

注意：平台工具里没有启动 / 停止单个 MCP 的工具（Web 侧的 mcp:start-server / mcp:stop-server 只给界面用）， Agent 想恢复连接得走「启用开关」这条路径。

9. 常见坑与排查

10. 关键代码位置