MCP 与 Skills

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

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

维度	Skill	MCP Server
载体	SKILL.md（YAML frontmatter + Markdown 正文），可带references/、scripts/、templates/	本地子进程（stdio）或远程端点（http / sse），配置存在数据库里
生效方式	元信息（id + 名称 + 描述）进 system prompt；正文按需加载后作为指令执行	进程连接后，工具以mcp__<serverName>__<toolName>进入工具列表
作用对象	按 Agent 配置的skillIds/disabledSkillIds决定（builtin:*、skill:catalog:*等）	所有enabled的 server 默认挂到所有会话，不按 Agent 过滤
典型例子	builtin:browser-use教 Agent 用 snapshot 的 ref 而不是 CSS selector 操作页面	playwright（managed）提供mcp__playwright__browser_*工具

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

命名空间	提供什么	挂载条件
mcp__spark_platform__	Skills / MCP / Providers / Agents / Teams / Workflows / 看板 / GitHub / Artifacts / 设置等平台管理工具	默认挂载
mcp__spark_search__	web_search/fetch_url联网检索与抓取	默认挂载
mcp__spark_memory__	search_memory/recall_memory长期记忆检索	记忆总开关打开时
mcp__spark_canvas__	画布节点、素材、任务、媒体模型等画布操作	会话绑定画布时
mcp__spark_media__/mcp__spark_image__	图片 / 视频 / 音频生成与转写	配置了多媒体 Provider 时
mcp__spark_browser__	应用内可见浏览器窗口（open / navigate / eval / screenshot 等）	浏览器自动化能力启用时
mcp__spark_debug__	begin/read/next_round/status/ finish调试闭环	该会话打开「调试模式」时
mcp__spark_session__	set_worktree_state上报 worktree 状态	默认挂载
mcp__spark_files__/mcp__spark_ui__/ mcp__spark_tool_results__	文件卡片、图表 / HTML 渲染、超长工具结果读取	默认挂载
mcp__spark_app__	子应用（桌面宠物 / 悬浮窗等）的创建与管理	默认挂载
mcp__spark_team__	团队 / goal / 工作流的成员派发与协作	团队、goal、工作流相关会话
mcp__spark_plugins__	插件运行时暴露的工具	有可用插件时
mcp__spark_computer__	电脑操作（Computer Use）	该会话开启电脑操作时

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

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

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

来源	磁盘位置	scope	id 形态
应用内置（随安装包分发、只读）	开发态apps/desktop/resources/skills/；打包后 process.resourcesPath/skills	system	builtin:<slug>（取自该目录manifest.json的 id）
从市场 / 精选目录安装、本地文件或目录导入	{userData}/skills/<slug>/	user	skill:catalog:<指纹>/skill:skillhub:<slug>/ local:<source>:<hash>
宿主机软链自动导入	软链放在{userData}/skills/_links/	user	local:linked:*
项目级（跟随工作区，不入全局列表）	工作区根目录下按优先级扫描：.claude/skills→.codex/skills→ .cursor/skills→.trae/skills→.qoder/skills→ .windsurf/skills→.github/skills→ .agents/skills→skills	—（实时扫描，不落库）	project:*
团队注册中心（Nacos）	安装后落到{userData}/skills/<slug>/	user	skill:team:*

项目级技能的扫描规则：会话绑定的第一个工作区根目录为扫描起点，上面目录名 的先后顺序就是同名技能的优先级（先发现者优先，重名只保留一个）。项目级技能不出现在 「技能」页的通用列表里，它们只在该会话的输入框 「+ → 技能」菜单里可见——所以「我在项目里放了 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有三种形态，安装时按下面的顺序生效：

source.type	怎么装	适用
artifact（当前 33 项全部使用）	从 Spark 自建安装源 manifest 找artifact.id = skill.<slug>，下载 zip → SHA-256 校验 → 落盘；默认 manifest 地址 https://minio.yiqibyte.com/spark-desktop/artifact-repository/v1/index.json（可用环境变量SPARK_INSTALL_MANIFEST_URL覆盖）	国内可达、可带平台专属依赖（如 ppt-master 的 wheelhouse）
tarball（作为 artifact 的 fallback）	下载https://codeload.github.com/<repo>/tar.gz/refs/heads/<ref>，系统tar解压失败时回落纯 JS 的 POSIX tar 解析，再取path 子目录复制到{userData}/skills/<slug>/	突破 GitHub Contents API 的 60 文件 / 单文件 1MB 限制；codeload 直连失败会依次尝试国内镜像前缀
github（小技能路径）	走installFromGithub()逐文件下载（Contents API）	≤60 文件、单文件 ≤1MB；不支持进度回调，进度条不会动

安装链路（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 时要按下面的规则来：

字段	用途	约束
transport或type	传输类型	二者等价，transport优先；写别的值会按可用字段推断
command+args	stdio 的启动命令与参数数组	stdio 必须有command，否则保存被拒（stdio 传输需要填写 command（启动命令））
url	http / sse 端点	协议必须是http/https/ws/wss；缺 url 保存被拒
env	stdio 子进程环境变量	只在 stdio 生效；值以明文存在本地spark.db，不要在里面塞长期密钥
cwd	stdio 子进程工作目录	可选，界面没有对应输入框，需直接改配置
headers	http / sse 的自定义请求头	可选，界面没有对应输入框，需直接改配置
auth	OAuth 2.0 配置：type/scope/dcr/ clientId/hasClientSecret	仅auth.type === 'oauth2'时走 OAuth 流程
description	卡片上显示的一句话说明	可选，缺省时卡片副标题显示transport · 端点
tools	历史字段，卡片上的「工具数」读的是它的长度	不是实时工具数，要查真实工具列表用mcp:server-tools 或平台工具mcp_status

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

5.2 OAuth 2.0（http / sse）

远程 MCP 需要授权时：认证方式选OAuth 2.0，按需填 OAuthscope； 「动态注册」默认开（走 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 的挂载关系

• 默认全挂：构建会话的 MCP 配置时，代码取的是listServers() 里所有enabled的 server，逐个解析传输并注入， 不区分scope，也不看当前 Agent 是谁。所以「加好 MCP，所有会话都能用」是成立的。
• Agent 的mcpServerIds是兼容字段：Agent 配置里虽然还有这个字段， 但运行时不再据此过滤 MCP（平台工具文档里直接标注「兼容字段，运行时忽略」）。 历史数据不会报错，只是不起作用。
• 两个例外：工作流里的「工具 / MCP 节点」成员如果显式配置过 MCP 选择， 会按它自己的mcpServerIds白名单加载（这就是「只给这个节点挂某个 MCP」的用法）； 只读原子成员则从空能力集开始，不加载用户自定义 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__* 工具，其中直接相关的是：

工具	作用
mcp_list	列出 MCP 配置（可按 scope 过滤）
mcp_create/mcp_update/mcp_delete	增删改 MCP 配置
mcp_status	查看连接状态与工具数（排查「连不上 / 零工具」的第一站）
skills_list	列出已安装技能（含内置、应用内安装、宿主软链）
skills_load	按 id 取某个技能的完整 SKILL.md 正文（渐进式披露的加载入口）
skills_search/skills_search_github	在远程技能商店 / GitHub 上搜含 SKILL.md 的仓库
skills_install/skills_install_github	按注册表条目或owner/name（可带 ref / path）安装技能
skills_toggle/skills_uninstall	启用停用 / 卸载技能

可以直接这样对 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. 常见坑与排查

现象	真实原因 / 处理
保存 MCP 报「stdio 传输需要填写 command（启动命令）」	传输选了 stdio 却没填命令。要么补command，要么切到 http / sse 并填 URL
远程 MCP 连不上、工具数为 0	先确认transport/type没写反（历史上 http 配置被当成 stdio 跑过npx）；再确认 URL 协议合法；最后看是否 OAuth 未授权
卡片显示「3 工具」但实际能用 12 个	卡片数字读的是配置里的历史tools字段，不是实时值。用 mcp_status或mcp:server-tools看真实工具
刚加完 MCP，当前这轮对话里 Agent 还是说没这个工具	工具清单在下一轮才刷新（MCP 版本变化会强制开新会话）。结束当前轮再发一条即可
技能装了但 Agent 不用	技能必须分配给 Agent；确认目标 Agent 的 Skills 勾选里包含它，且该技能 enabled=1
项目里放了.agents/skills/x/SKILL.md，「技能」页看不到	项目级技能只在会话内实时扫描（输入框「+ → 技能」可见），不进全局技能列表
精选技能安装成功但跑不起来	看postInstallHint提示的运行时依赖（Python / Node / wheelhouse）。安装只负责落盘，不装依赖
卸载精选技能后同名技能也被删了	正常不会：卸载按磁盘路径与来源指纹精确匹配。若确实发生，检查该技能是否就是用同名 slug 安装的
环境变量里的密钥安全吗	它只注入 stdio 子进程，不会进 prompt；但以明文存在本地配置里，长期密钥建议放到 Keychain 管理的 Provider 凭据，而不是 MCP env

10. 关键代码位置

文件	作用
packages/agent-runtime/src/services/mcp-server.service.ts	MCP 生命周期：CRUD、启停、状态、managed 保护、MANAGED_MCP_SCOPE/ PLAYWRIGHT_MCP_NAME
packages/agent-runtime/src/mcp/config-normalize.ts	配置归一化与写入校验（resolveMcpConfig/validateMcpConfigJson），http / sse / stdio 的唯一判定入口
packages/agent-runtime/src/services/session/session-mcp-tooling.ts	buildMcpServersForSDK()：把库里所有 enabled 的 server 变成 SDK 配置；内置 spark_search与spark_memory的解析也在这里
packages/agent-runtime/src/services/session/spark-engine-runtime.ts	会话级内置 MCP server 名单（spark_platform / spark_search / spark_browser / spark_debug / spark_memory 等）
packages/storage/src/repositories/mcp-server.repository.ts	mcp_servers表读写，含bundle_id
packages/storage/src/repositories/skill.repository.ts	skills表读写（scope / root_path / manifest_json / enabled）
packages/agent-runtime/src/services/skill.service.ts	ensureBuiltInSkills()：内置技能扫描、进库、清理下架记录
packages/agent-runtime/src/services/local-skill-importer.ts	SKILL.md 解析与 frontmatter 校验（name / description 必填），本地导入与内置扫描共用
packages/agent-runtime/src/services/runtime-composition.service.ts	[Available Skills Catalog]目录注入与「按需 skills_load」的提示词
packages/agent-runtime/src/services/skill-registry/installable-catalog.ts	精选目录清单INSTALLABLE_SKILL_CATALOG与默认 manifest 地址
packages/agent-runtime/src/services/skill-registry/index.ts	listInstallableCatalog()/installFromCatalog()/ uninstallFromCatalog()，artifact / tarball / github 三条安装路径
packages/agent-runtime/src/services/skill-registry/tarball-installer.ts	tarball / zip 下载、镜像回退、系统 tar 与纯 JS 解包
packages/agent-runtime/src/services/project-context.service.ts	项目级技能扫描目录清单与优先级顺序
apps/desktop/src/main/services/AppSkillsManager.ts	内置目录resources/skills、用户目录 {userData}/skills、宿主软链与托管插件目录的路径真相
apps/desktop/src/main/services/PlaywrightMcpRegistration.ts	managedplaywright的自动注册
apps/desktop/src/renderer/design/views/McpView.tsx	「扩展中心」MCP 页：卡片、筛选、抽屉表单、OAuth 授权
apps/desktop/src/renderer/design/views/SkillStoreView.tsx	技能页四个 Tab（在线市场 / 精选推荐 / 已安装 / 创建）与安装进度
packages/agent-runtime/src/tools/platform-management-mcp-server.mjs	mcp__spark_platform__*工具定义与 bridge 方法映射

速查表

项目	内容
MCP 配置存储	{userData}/spark.db 的 mcp_servers 表（config_json 明文）
传输类型	stdio（需 command）/ http / sse（需 url，协议限 http/https/ws/wss）
作用域枚举	system / user / project / team / session（另有不对用户开放的 managed）
会话挂载规则	所有 enabled 的 server 默认挂到所有会话，不按 scope / Agent 过滤
热更新时机	下一个 turn 起新会话；in-flight turn 不变
内置技能目录	resources/skills（dev）/ process.resourcesPath/skills（prod），id 形如 builtin:<slug>
用户技能目录	{userData}/skills/<slug>/（scope=user）
项目级技能目录	.claude/skills → … → .agents/skills → skills（在工作区内扫描）
精选目录规模	33 项：ppt-master / playwright / 14 superpowers / 6 gitnexus / 11 影视叙事
渐进式披露入口	mcp__spark_platform__skills_load（原生 Skill 工具可用时等同）
MCP 管理工具	mcp__spark_platform__mcp_list / mcp_create / mcp_update / mcp_delete / mcp_status

上手清单：在 Spark Work 中接入一个 MCP 并确认可用

从新建 MCP 到验证工具清单与下一轮生效

1. 打开左侧「扩展中心」→「MCP」页签，点右上角「添加 MCP」
2. 填名称（决定 mcp__<名称>__* 前缀）与描述，保持不变的作用域标签即可
3. 选传输：本地进程用 stdio 并填命令与空格分隔的参数；远程用 http / sse 并填 URL
4. stdio 如需注入环境变量，在「环境变量」里加 KEY/value（仅 stdio 生效）
5. 远程需要授权时把认证方式切成 OAuth 2.0，保存后点卡片上的授权按钮完成登录
6. 保存后确认卡片状态不是「配置不完整」，必要时用 mcp__spark_platform__mcp_status 查看 connected 与 toolCount
7. 结束当前回合，再发一条消息——新一轮会带着新工具清单启动

常见问题

Skill 和 MCP 到底有什么区别？

Skill 是给 Agent 读的「说明书」（一份 SKILL.md，告诉它按什么步骤做），MCP 是给 Agent 调的「工具集」（连上后工具以 mcp__<名称>__<工具> 出现）。两者独立启用：装好 MCP 才有工具，装好 Skill 才有方法，常见组合是一个 Skill 点名要求用它配套的 MCP 命名空间。

Skill 会一直占用上下文吗？

不会。system prompt 里只放技能目录（id + 名称 + 截断的描述），并提示 Agent「需要时用 mcp__spark_platform__skills_load 取完整指令」。完整 SKILL.md 正文只有被加载时才进上下文。

能装第三方 Skill 吗？从哪儿装？

能。四条路：①「技能 → 在线市场」搜 SkillHub 并安装；②「技能 → 精选推荐」装官方的 33 项可安装技能；③「技能 → 创建 → 文件/目录导入 / 软链接」装本地已有的技能；④ 让 Agent 调 mcp__spark_platform__skills_search_github 搜仓库、skills_install_github 安装。界面里没有独立的「从 GitHub 安装」按钮。

技能装完为什么 Agent 还是不用？

技能必须分配给 Agent 才生效。到「Agent」页编辑目标 Agent，在 Skills 一栏点「管理 Skills」勾选它；同时确认这个技能没有被 skills_toggle 关成 enabled=0。安装成功时应用会弹提示引导分配。

MCP 保存后多久生效？

保存会立刻建立连接，但工具清单在「下一轮对话」才刷新——运行时发现 MCP 版本变化会强制开一个全新会话，因为 SDK 在启动时就冻结了工具列表。当前正在执行的那一轮不受影响。

为什么我新建的 MCP 在别的会话里也生效了？

因为会话默认加载所有 enabled 的 server，不按作用域或 Agent 过滤（Agent 的 mcpServerIds 已是运行时忽略的兼容字段）。想限制范围只有一条路：在工作流的工具 / MCP 节点成员上显式配置 MCP 白名单。