内置工具

应用把高频能力打包成「内置 Skill」，随安装包一起发布：每个 Skill 是一个目录，含一份SKILL.md（YAML frontmatter + Markdown 正文）、一个声明 id 与依赖工具的manifest.json，需要时还会带 references/、scripts/、 templates/、data/。本页按真实目录逐个列出当前内置的全部 17 个 Skill，并给出各自真实的 id、版本、分类、配套工具与踩坑点。

目录位置：开发态 apps/desktop/resources/skills/，打包后 process.resourcesPath/skills；只读，随应用升级更新。

1. 内置 Skill 怎么生效

1. 进库：每次技能列表被请求时会重新扫描内置目录（ensureBuiltInSkills()）， 按 manifest.json 里的 id（形如 builtin:<目录名>）写入 / 更新skills 表，scope=system。改完文件不用手动同步。
2. 分配给 Agent：技能靠 Agent 配置里的 skillIds 生效。到左侧「Agent」页编辑 目标 Agent，在 Skills 一栏点「管理 Skills」勾选；被列入 disabledSkillIds 的则从该 Agent 的可用集里剔除。新装技能后应用会弹「技能已就绪，是否现在分配给 Agent」的提示，就是因为 这一步不做的话技能不会自动参与对话。
3. 进上下文的是目录：system prompt 里只有 id + 名称 + 截断描述， 并提示 Agent「需要时用 mcp__spark_platform__skills_load 取完整指令」。 这就是渐进式披露：17 个技能全开也只占一份目录的体积，正文按需加载。
4. 手动点名：会话输入框的「+ → 技能」菜单会列出可用技能（含当前工作区扫描到的 项目级技能），点击把 @技能名 插入输入框，用来在单轮里显式指定要用哪个技能。
5. 启用 / 停用与删除：内置技能不能删除（删除接口明确拒绝builtin: 前缀），只能通过 skills_toggle（或界面开关）把enabled 置 0 停用。

2. 17 个内置 Skill 总览

表中「—」表示该 SKILL.md 的 frontmatter 只声明了 name 与 description（部分还带 license），没有 version / author，入库时版本落到 0.0.0。带 LICENSE.txt 的 （claude-api、frontend-design）是随包分发的第三方技能。

两个容易看错的字段：分类只从 frontmatter 的 category 读（缺省按 utility 入库），manifest.json 里的 category 不参与入库——例如 react 目录的 manifest 写的是 coding， 但它的 frontmatter 没有 category，所以入库分类是 utility； 同理 manifest.json 只负责提供 id、requiredTools、parameters，其余元信息都来自 SKILL.md。

3. 编程与工程类

3.1 claude-api

覆盖 Claude API / Anthropic SDK 应用的构建、调试与优化：prompt caching、tool use、 batch、files、citations、memory、thinking、compaction，以及把老代码迁移到当前模型、 替换已退役模型。目录里有 45 个文件、17 个子目录，按语言给出示例（python、typescript、go、java、php、ruby、csharp、curl、shared）。

• 触发：代码里 import anthropic / @anthropic-ai/sdk，或问 prompt caching 命中率、thinking、batch、Managed Agents、模型迁移。
• 跳过：代码 import openai 或其它厂商 SDK、文件名形如 *-openai.py / *-generic.py、provider-neutral 代码。
• 配套工具：无（requiredTools 为空），纯说明 + 代码示例。

3.2 commit

分析 git diff / git status，把变更按逻辑分组，生成 Conventional Commits 格式的提交信息：<type>(<scope>): <subject>。 type 枚举为 feat、fix、refactor、style、docs、test、chore、perf、ci； subject 建议不超过 50 字符、不以句号结尾。

• 配套工具：Bash（跑 git 命令）。
• 关键约束：生成信息后必须展示给用户确认再执行提交，不会自动 commit。
• 典型提示词：「按 conventional commits 规范提交我的改动」「把这次改动拆成几个合理的 commit」。

3.3 react

面向 @lobehub/ui + antd 技术栈的 React 组件写作约定：复杂样式用antd-style、简单场景用 inline style；布局优先用 Flexbox / Center；组件优先级为 src/components > 已安装包 > @lobehub/ui > antd； zustand 用 selector 取值。路由部分区分 Next.js App Router（登录 / 注册 / OAuth）与 react-router-dom 主 SPA（desktopRouter.config.tsx），并强调 SPA 内用 Link / useNavigate 而不是 next/link。

• 配套文件：references/layout-kit.md；@lobehub/ui 组件清单在技能正文里。
• 注意：这些约定来自 @lobehub/ui 生态（含具体文件路径），换到其它 React 技术栈时只有通用部分可参考。

3.4 frontend-design

先做设计判断、再写代码：明确用途与受众、选定一个明确的美学方向（极简 / 极大主义 / 复古未来 / 编辑风 / 工业风等）、再落到字体、色彩、动效、空间构图与背景质感。 明确禁止通用 AI 审美——不用 Inter / Roboto / Arial 之类默认字体，不用「白底紫渐变」， 也不要每次都收敛到同一套选择。

• 典型场景：「做一个有质感的 SaaS landing page」「把这个 dashboard 做得不那么 AI 味」。
• 配套工具：无。产出是可运行的 HTML/CSS/JS 或 React 代码，写文件靠宿主 Agent 自身能力。

3.5 skill-creator

创建和改进 Skill 的完整工作流：捕获意图 → 访谈补齐输入 / 输出格式与边界 → 写草稿 → 造测试 prompt → 生成量化 eval → 用评测脚本看结果 → 按反馈重写 → 扩大测试集； 最后还有专门的 description 优化步骤，用于提升技能触发的准确率。

• 配套文件：19 个文件（含 eval-viewer/generate_review.py 之类的评测脚本与模板）。
• 典型提示词：「帮我创建一个 sql-explain 技能」「我的技能总在错误的场景被触发，帮我改 description」。

3.6 spark-workflow-generator

把自然语言需求编译成 Spark 可导入的 WorkflowGraph JSON，节点种类是封闭枚举的 13 种：input、plan、route、 agent、subagent、skill、tool、 mcp、approval、verify、review、 artifact、loop。产物是「待审草案 + 校验报告」， 需要人工确认后才导入。

• 配套文件：references/schema-freeze.md（schema 与 preflight 错误码）、references/node-spec.md（13 种节点规格）、4 个模板（线性 / 条件路由 / 迭代循环 / 审批+MCP）、demos/ 示例。
• 离线校验：生成后先跑 node scripts/validate.mjs <生成的.json>，错误码与导入前的 preflight 对齐。
• 硬性规则：绑定类字段（agentId / skillIds / toolIds / mcpServerIds / ruleIds / modelId / providerProfileId / toolServerId）必须留空，跨环境写死必然失效；坐标 x / y 在节点顶层而不在 config 里；分支条件必须互斥且各自独立收尾，不能汇合；loop 不嵌套、maxIterations ≤ 50；每张图恰有一个 input 起点、每条链以 artifact 收尾。
• 分工：实时操作当前画布请用 canvas-studio，视频转码剪辑请用 video-workflow，本技能只负责生成 / 修改工作流定义 JSON。

4. 联网与浏览器类

4.1 multi-search-engine

用内置 spark_search MCP 的 web_search / fetch_url 检索网络并抓取正文，综合多来源给出带出处的答案。因为搜索在本地子进程里自己发 HTTP， 与模型供应商解耦，走第三方 OpenAI 兼容 API 时同样有效（SDK 自带的 WebSearch / WebFetch 在第三方供应商下会被剥离）。

• 配套工具：mcp__spark_search__web_search、mcp__spark_search__fetch_url（写在 manifest 的 requiredTools 里）。
• 用法与后端配置：见 联网搜索（免密默认链 + keyed 后端）。
• 行为约定：按时效性判断要不要搜；优先一手权威来源；片段不够就抓正文；材料冲突要显式调和；不得把「没搜到」当成「不存在」。

4.2 browser-use

通过 Playwright MCP 驱动真实浏览器完成导航、点击、输入、截图与数据提取。核心方法论：browser_navigate 之后立刻 browser_snapshot 拿到可访问性树， 每个可交互元素带 ref 编号；后续一律基于 ref 操作 （element="ref=3"），不要写 CSS selector；每次动作后再 snapshot 确认； 复杂视觉页面才截图辅助；收尾调 browser_close 释放资源。

• 配套工具（manifest 声明 7 个）：mcp__playwright__browser_navigate / snapshot / click / type / press_key / take_screenshot / close。
• 运行参数：mode 可选 headful（默认，显示窗口）/ headless。
• 环境兜底：会话里没有 mcp__playwright__browser_* 时，先用 mcp__spark_platform__mcp_status 检查内置 playwright MCP 是否被停用 （停用就让用户去启用，不要自己重启进程）；确实缺失才自行安装并注册 scope=project、type=stdio、command=npx、args=["-y","@playwright/mcp"] 的 MCP。网络受限时切 registry.npmmirror.com 与 PLAYWRIGHT_DOWNLOAD_HOST， 且不要写进全局 ~/.npmrc。
• chromium 按需下载：仅当确认没有可用的系统 Chrome/Edge / Playwright 缓存时才下载，且要先告知用户约 150MB。
• 另一条路：需要应用内可见窗口、本地 file:// 调试、console / network 观察或保留登录态时，用内置的 mcp__spark_browser__*（见 浏览器自动化）。

5. 画布、多媒体与内容生产类

5.1 canvas-studio（画布工作室）

用 mcp__spark_canvas__* 工具直接读写当前打开的画布项目。工具清单以canvas.tools.ts 注册为准（当前 53 个），只有画布弹窗 attach 到当前会话时 才注入——没有画布绑定时，Agent 看不到这些工具。

• 节点类型：内容节点 image / audio / video / text / prompt / group，加上 AI 操作节点 text_to_image、image_to_image、image_edit、image_compose、panorama_360、text_generate、text_rewrite、prompt_optimize、text_to_video、image_to_video、video_edit、video_extend、text_to_audio、audio_transcribe。
• 影视语义：node.data.pipelineRole 表达流水线角色（style_bible / screenplay / character / scene / shot / keyframe / clip 等）；node.data.productionState 走 empty → drafting → draft → confirmed，上游变更后下游可标 stale。
• 黄金规则：编辑前先 canvas_get_project_summary；宽泛目标先 canvas_get_production_plan；针对某节点先 canvas_get_available_actions；多节点流程必须用 canvas_create_reusable_workflow_graph 原子创建（不要拼低层创建后漏连线）；只操作当前画布，不创建 / 切换多画板；破坏性操作先问用户；保存工作流是独立动作（canvas_workflow_extract_selection），不会自动落库。
• 常见坑：画布工具必须由主 Agent 直接调用，不要委派给子 Agent（子 Agent 没有 attach 上下文）；工具返回「无输出」不等于画布断连，先读回验证再决定是否重试；参数字段不确定时用 canvas_describe_tool 取精确 schema。

5.2 multimedia-use（多媒体使用）

把创作意图翻译成可执行的图片 / 视频 / 音频任务。覆盖文生图、图生图、图片编辑与局部重绘、 多图合成、文生视频、图生视频、首尾帧视频、视频编辑与扩展、TTS / 配音、音频转写， 以及模型能力与参数约束的查询。

• 画布会话：优先用 mcp__spark_canvas__*——canvas_list_media_models 选模型 → canvas_create_operation_node 建可检查的操作节点 → 用户明确要求立即执行时才 canvas_run_operation → canvas_list_tasks 跟进。
• 普通会话：用 mcp__spark_media__*——先 list_models，再 describe_model 看参数 schema，最后调 generate_image / edit_image / generate_video / generate_audio / transcribe_audio；异步任务用 get_task / cancel_task；Provider 文件用 upload_file / get_file / list_files / delete_file（删除前必须确认）。
• 常见坑：不得静默改用默认模型——用户指定模型时要原样传 list_models 返回的 selectionKey；不要把适配器模板里的模型 ID 当成真实模型 ID；工具没注入时如实说明，不要假装已生成。

5.3 video-workflow

纯本地 ffmpeg 处理，不经过大模型：关键帧提取（场景突变 / I 帧 / 均匀采样）、转码、 剪辑、合并、变速、倒放、裁剪、加水印、烧字幕、生成 GIF、分割视频。

• 配套工具：Bash（调 ffmpeg / ffprobe）。
• 前置检查：每次处理前先 ffmpeg -version / ffprobe -version；不可用时不要自行安装，引导用户到「设置 → 完整性 → 视频处理 (FFmpeg) → 下载 FFmpeg」。
• 路径线索：Spark 管理的 ffmpeg 落在应用 userData 的 bin/<版本>/ 下（macOS 形如 ~/Library/Application Support/spark-desktop/bin/<版本>/ffmpeg）。
• 流程约定：先 ffprobe 探明时长 / 分辨率 / 编码再决定参数；产物文件名带操作语义放在工作目录；长任务告知预计耗时。

5.4 spark-web-tool

三类内容产物，全部先过一遍澄清再动手：

1. 交互式课件（courseware）：澄清 → 大纲确认 → 内容脚本 → 产物生成，输出 PPTX / HTML / DOCX / Markdown。
2. 专题讲解（explain）：澄清 → 理解 → 研究 → 验证 → 脚本 → 产物生成，输出 HTML 幻灯片 / 自定义网页 / PPTX / DOCX。
3. 数据分析（data-analysis）：读 CSV / Excel → 分析 → 产出带图表的 HTML 报告。

• 澄清协议：Stage 0 会生成 7~12 个问题，覆盖「内容」「设计方向」「视觉细节」三组，配色题给色板选项、版式题给预览；用户已经说过的信息不重复问。
• 配套工具：Read、Write、Bash、mcp__spark_search__web_search、mcp__spark_search__fetch_url。
• 参数：taskType、outputFormats、style、includeQuiz、dataFileName、dataFileUrl、chartTypes、designSystem。
• 配套文件：33 个文件，references/ 下按 clarify / courseware / explain / data-analysis / snippets 分目录，另有 README.md。
• 典型提示词：「做一份《光合作用》的交互式课件」「把这份 CSV 变成数据报告」「讲解一下快速排序，要能互动的网页」。

5.5 echarts

生成可直接使用的 ECharts 配置：按数据特征选图型（趋势 → 折线 / 面积，占比 → 饼 / 环形， 分布 → 散点 / 气泡，多维 → 雷达，层级 → 矩形树图 / 旭日图，流向 → 桑基 / 漏斗， 时序 → K 线，地理 → 地图 / 热力，关系 → 关系图），并带上默认样式约定。

• 默认样式：色板 ['#5470c6','#91cc75','#fac858','#ee6666','#73c0de','#3ba272','#fc8452','#9a60b4','#ea7ccc']；开 tooltip、legend，grid 留白 top 60 / right 40 / bottom 40 / left 60；配 resize 监听。
• 组合用法：可以单独使用，也可以作为 spark-web-tool 数据分析报告里的图表子任务。

6. UI / 设计类

6.1 ui-ux-pro-max

一个带数据的本地设计知识库：data/*.csv 存知识，scripts/search.py 做 BM25 检索，scripts/design_system.py 生成成套设计系统建议。 技能自述的规模是「50+ 风格 / 161 色板 / 57 字体配对 / 161 产品类型 / 99 UX 准则 / 25 图表 / 10 技术栈」， 按随包数据的实际行数核对如下：

检索脚本的真实用法（在技能目录下执行）：

# 生成成套设计系统建议
python3 scripts/search.py "<产品类型> <行业> <关键词>" --design-system -p "项目名"

# 落盘到 design-system/MASTER.md（可再为单页生成覆盖文件）
python3 scripts/search.py "<关键词>" --design-system --persist -p "项目名" --page "dashboard"

# 按域查询明细
python3 scripts/search.py "<关键词>" --domain <domain> -n 5

# 技术栈专属查询（当前仅 react-native）
python3 scripts/search.py "<关键词>" --stack react-native

• 可用 domain（脚本的真实可选值）：style、color、chart、landing、product、ux、typography、icons、react、web、google-fonts。
• 输出控制：--format ascii|markdown、--json、--output-dir。
• 注意：仓库里 scripts/search.py 的 --help 文案仍写着 html-tailwind / react / nextjs，但 STACK_CONFIG 实际只实现了 react-native；其它栈请用 --domain 查询。

7. 调试与平台管理类

7.1 spark-debug

「假设驱动 + 人在回路」的调试闭环。核心原则是Agent 不复现 bug： 它负责假设、插桩、读日志、修复、清理，用户负责操作复现；每插一轮桩就结束 turn 把控制权交回用户。

• 挂载条件：不是常驻技能。会话里打开「调试模式」开关（per-session，不继承全局偏好）后，运行时才挂载 mcp__spark_debug__* 并注入状态机提示词。
• 工具：begin（拿 sid / 端口 / 轮次与插桩上报器）、read（拉本轮日志）、status（看本轮条数与假设台账）、next_round（推进轮次）、finish（清空日志并返回待删除的插桩标记）。
• 参数：bugDescription（必填，现象 + 复现步骤 + 期望 vs 实际）、targetRuntime（browser 默认 / node / other，决定用哪套语言的上报器模板）。
• 插桩规范：日志块必须用 // __SPARK_DEBUG_START__ ... // __SPARK_DEBUG_END__ 包裹；status.thisRound === 0 时不要硬分析空日志，改插桩点或复现步骤。
• 护栏：约 6 轮仍未定位就收口总结；交付的硬条件是 finish 后全仓 grep __SPARK_DEBUG 零残留；报告中还要说明日志证据。

7.2 find-skills

技能发现与推荐：解析任务需要什么能力（编码 / 设计 / 搜索 / 数据处理）与技术栈，用 mcp__spark_platform__skills_search 搜远程技能库，再结合已安装列表给出推荐， 每条说明「匹配原因 / 如何使用 / 来源是已安装还是需要安装」。推荐策略偏保守： 基础编程任务不额外推荐、用户已指定工具时不推替代品、优先已安装的技能， 并在需要多种能力时给组合（如前端页面 → frontend-design + react）。

7.3 platform-manager（平台管理）

用 mcp__spark_platform__* 管理应用内的平台数据（本机 SQLite + JSON 文件， 不是全局 Claude 配置）。工具清单以packages/agent-runtime/src/tools/platform-management-mcp-server.mjs 注册为准， 当前共 124 个（技能正文里写的「94 个」是历史值），分组如下：

破坏性操作（删除、卸载、发布、启用）在工具描述里都要求先向用户确认； Agent 侧只管平台数据，不替代画布 UI 操作。详见Agent 工作流 / Platform 管理工具。

8. 按任务挑选

组合建议：一次会话里 2~4 个技能足够。技能越多，system prompt 里的技能目录越长， 而且在技能职责重叠时模型更容易选错（例如截图任务同时开 browser-use 和canvas-studio）。

9. 自己写一个 Skill

三条落地路径，按「是否要跟随项目 / 是否要分享」选：

frontmatter 真实字段：name（必填，非空字符串）和 description（必填）是硬性要求；version / author / category / tags / license 可选；requiredTools 与 tools 会被合并成依赖工具清单（写在这里只是声明， 不会自动帮你装上对应的 MCP）。category 的常见取值为 coding / writing / analysis / workflow / utility； 内置技能里还出现过 debugging。

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

## 何时使用
…

## 工作流
1. …

## 注意
- …

想让技能被稳定触发，关键在 description：写清「做什么 + 什么场景加载 + 什么场景不要加载」。 内置技能的 description 普遍是这个写法（例如 claude-api 明确列出 TRIGGER 与 SKIP）， 可以直接参考。写完用 skill-creator 跑一轮评测和 description 优化。

注意：内置技能的内容在安装目录里是只读的，改本机副本会在升级时被覆盖； 想长期保留自己的版本请用独立 slug 放到 {userData}/skills/。