AI Helper 文档中心

主题

Skill 技能系统 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与资源管理
  8. 故障排查指南
  9. 结论
  10. 附录：技能示例与开发指南

引言 ​

本文件系统性梳理 Agent 端的 Skill 技能系统，覆盖以下主题：

  • 技能定义格式：SKILL.md 文件结构、元数据字段、参数规范与执行上下文。
  • Markdown 技能加载器：文件扫描、YAML frontmatter 解析、正文处理、资源扫描与导入导出。
  • 技能执行框架：步骤 DAG、拓扑排序并行执行、条件分支、超时控制、结果聚合。
  • 模板引擎：变量插值、对象递归渲染、条件逻辑。
  • 注册表与依赖管理：Workflow 与 Agent 两类技能的统一注册、启用/停用持久化、内置种子技能。
  • 与 MCP 协议的集成：Skill 与 MCP 的边界、组合方式与最佳实践。
  • 开发指南：从简单文本处理到复杂业务流程自动化，含调试技巧与性能优化建议。

项目结构 ​

Agent 端 Skill 子系统位于 agent/src/skill，包含加载、执行、模板、注册等模块；Chrome 扩展侧通过工具定义暴露 agent_skill 能力，由 background 工具执行器桥接到 Agent 服务。MCP 子系统独立于 Skill，但可在对话中协同使用。

graph TB
subgraph "Agent 端"
ML["markdown-loader.js<br/>Markdown 技能加载"]
LDR["loader.js<br/>Workflow + Agent 加载"]
REG["registry.js<br/>技能注册表"]
EXE["executor.js<br/>技能执行引擎"]
TPL["template.js<br/>模板引擎"]
MCP_REG["mcp/registry.js<br/>MCP 工具注册表"]
end
subgraph "扩展端"
AT["tools/agent-tools.js<br/>agent_skill 工具定义"]
TE["tool-executor.js<br/>工具执行分发"]
end
AT --> TE
TE --> REG
REG --> LDR
REG --> ML
REG --> EXE
EXE --> TPL
MCP_REG -.->|可选协同| REG

图表来源

章节来源

核心组件 ​

  • Markdown 技能加载器：负责 SKILL.md 扫描、frontmatter 解析、正文清洗、资源扫描、Zip/URL 导入与安全校验。
  • Workflow/Agent 加载器：统一加载 JSON/YAML Workflow 与 Agent SKILL.md，并输出标准化技能定义。
  • 技能注册表：维护内存中的技能映射、启用状态持久化、内置种子技能、查询与执行入口。
  • 技能执行引擎：解析步骤 DAG、拓扑排序并行执行、条件 with when、模板渲染、工具调用封装、超时与部分成功处理。
  • 模板引擎：支持 {{var}} 插值、{{#if}}...{{/if}} 条件、对象递归渲染。
  • 扩展端工具桥接：agent_skill 工具定义与 background 执行器，将 AI 的工具调用路由到 Agent 技能。
  • MCP 工具注册表：独立于 Skill，提供第三方工具发现与调用，可与 Skill 协同工作。

章节来源

架构总览 ​

Skill 系统采用“加载—注册—执行”三段式架构，配合模板引擎与安全检查，对外暴露统一的 agent_skill 工具接口。

sequenceDiagram
participant AI as "AI 模型"
participant BG as "Background 工具执行器"
participant REG as "技能注册表"
participant LDR as "技能加载器"
participant EXE as "技能执行引擎"
participant SEC as "安全校验"
participant FS as "文件系统/命令执行"
AI->>BG : 调用 agent_skill(action=run/load, name, params?)
BG->>REG : 查询/加载技能
REG->>LDR : 扫描并解析 Workflow/Agent 技能
LDR-->>REG : 返回标准化技能定义
alt action=runWorkflow
REG->>EXE : executeSkill(skill, params)
EXE->>SEC : checkPath/checkCommand
SEC-->>EXE : 允许/拒绝
EXE->>FS : 文件读写/搜索/命令执行
FS-->>EXE : 结果
EXE-->>REG : 步骤结果/状态
REG-->>BG : 执行结果
else action=loadAgent
REG-->>BG : 返回 Agent Prompt 摘要
BG-->>AI : 注入 Agent 指令上下文
end

图表来源

详细组件分析 ​

Markdown 技能加载器 ​

职责：

  • 扫描 skills 目录下子目录的 SKILL.md。
  • 解析 YAML frontmatter（name/description/version/enabled 等）。
  • 清理正文标题行，保留 fullPrompt 与 prompt。
  • 扫描 scripts/templates/assets/references 等资源目录，过滤构建产物与语言包缓存。
  • 支持 Zip 导入（纯 JS ZIP 解压，路径穿越防护）、URL 下载（HTTP/HTTPS，重定向限制与主机白名单）。
  • 名称校验与目标路径越界检查，避免命令注入与路径穿越。

关键流程（Zip 导入）：

flowchart TD
Start(["开始"]) --> ParseUrl["解析 URL 与协议校验"]
ParseUrl --> HostCheck["DNS 解析与内网地址拦截"]
HostCheck --> Download["下载 ZIP限大小、限重定向次数"]
Download --> Extract["纯 JS 解压 ZIP"]
Extract --> FindMd["查找顶层目录或根目录中的 SKILL.md"]
FindMd --> SanitizeName["名称安全校验"]
SanitizeName --> PathGuard["目标路径越界检查"]
PathGuard --> CopyDir["复制至 skills 目录"]
CopyDir --> Reload["重新加载技能"]
Reload --> End(["结束"])

图表来源

章节来源

Workflow/Agent 加载器 ​

职责：

  • 加载 Workflow 技能（JSON/YAML），进行基础 Schema 校验（name/description/steps 等）。
  • 加载 Agent 技能（通过 markdown-loader）。
  • 统一输出 type=workflow 或 type=agent 的技能定义。
  • 提供保存、删除、种子写入 skill-creator 的能力。

要点：

  • Workflow 默认 enabled=true，steps 必须为数组且每个 step 需 id 与 tool。
  • Agent 技能通过 loadAllMarkdownSkills 合并进统一列表。
  • seedSkillCreator 在首次运行或版本升级时写入内置 skill-creator。

章节来源

技能注册表 ​

职责：

  • 初始化时加载文件系统技能与内置种子技能。
  • 恢复内置技能与用户手动停用的技能状态（持久化到 JSON 文件）。
  • 提供 getSkillList/getSkill/runSkill/getAgentSkillPrompts/getAgentSkillPrompt/importSkill/removeSkill/toggleSkill/reloadSkills 等 API。
  • 对 Agent 技能提供三级模糊匹配（精确 name、目录名、归一化 slug）。

关键点：

  • disabled_skills.json 与 builtin_skills_state.json 分别记录用户停用与内置启用状态。
  • toggleSkill 优先更新持久化文件，再尝试回写源文件（best-effort）。
  • getAgentSkillPrompts 生成注入 System Prompt 的轻量描述，便于 AI 按需加载完整内容。

章节来源

技能执行引擎 ​

职责：

  • 参数校验与类型转换（兼容 JSON Schema properties/required）。
  • 构建步骤 DAG，拓扑排序并行执行。
  • 支持 when 条件跳过、模板渲染参数、步骤结果注入变量上下文。
  • 封装内部工具调用（agent_file/agent_exec/agent_search 等），结合安全策略。
  • 超时控制（默认 5 分钟）、部分成功（partial）与错误聚合。

执行时序：

sequenceDiagram
participant REG as "注册表"
participant EXE as "执行引擎"
participant TPL as "模板引擎"
participant SEC as "安全校验"
participant IO as "文件/搜索/命令"
REG->>EXE : executeSkill(skill, params)
EXE->>EXE : 参数校验与默认值填充
EXE->>EXE : 构建 DAG 与就绪队列
loop 每批就绪步骤
EXE->>TPL : render(when/args)
TPL-->>EXE : 渲染后条件/参数
EXE->>SEC : checkPath/checkCommand
SEC-->>EXE : 允许/拒绝
EXE->>IO : 执行工具调用
IO-->>EXE : 结果
EXE->>EXE : 写入 variables.step.<id>
end
EXE-->>REG : 返回 results/partial/error

图表来源

章节来源

模板引擎 ​

功能：

  • 变量插值：{{variable}}，支持点号路径 a.b.c。
  • 条件渲染：{{#if variable}}...{{/if}} 与取反 !variable。
  • 对象递归渲染：renderObject 遍历字符串值进行模板替换。

复杂度：

  • 单次模板渲染 O(n)，n 为模板长度；对象递归渲染 O(m)，m 为对象节点数。

章节来源

扩展端工具桥接与执行 ​

  • agent_skill 工具定义在扩展端 tools/agent-tools.js，暴露 action=name/run 与 name/params。
  • background 工具执行器 tool-executor.js 将 agent_skill 路由到对应 handler，最终调用 Agent 端注册表。

注意：

  • 当 Agent 绑定技能时，background 会自动加入 agent_skill 工具，除非全局关闭 skillsEnabled。

章节来源

MCP 协议集成 ​

  • MCP 工具注册表独立于 Skill，负责连接多个 MCP Server，扁平化工具列表，并提供 callMcpTool。
  • Skill 与 MCP 的区别：Skill 是预定义工作流或 AI 自主调用的指令集；MCP 是动态工具生态。
  • 两者可组合：在 Workflow 或 Agent 步骤中调用 MCP 工具，实现外部系统交互。

章节来源

依赖关系分析 ​

graph LR
REG["registry.js"] --> LDR["loader.js"]
REG --> EXE["executor.js"]
EXE --> TPL["template.js"]
EXE --> SEC["security.js"]
EXE --> SEARCH["search.js"]
LDR --> ML["markdown-loader.js"]
AT["agent-tools.js"] --> TE["tool-executor.js"]
TE --> REG
MCP_REG["mcp/registry.js"] -.->|可选协同| REG

图表来源

章节来源

性能与资源管理 ​

  • 执行并发：DAG 同层步骤并行执行，提升吞吐；通过 ready 队列与 completed 集合避免重复执行。
  • 超时与清理：EXECUTION_TIMEOUT 防止长时间阻塞；activeExecutions 定期清理已完成/错误任务，上限 MAX_ACTIVE_EXECUTIONS。
  • 资源扫描：scanResources 排除 node_modules、pycache、dist 等目录，减少无效文件统计。
  • 下载限制：MAX_SKILL_DOWNLOAD_SIZE 限制 ZIP 大小，重定向最多 5 次，每次重定向均校验主机。
  • 模板渲染：对象递归渲染避免深层嵌套导致的重复计算；条件渲染先于变量插值，减少无用模板展开。

[本节为通用性能讨论，不直接分析具体文件]

故障排查指南 ​

常见问题与定位：

  • 技能未加载：检查 skills 目录是否存在、SKILL.md 是否有效、frontmatter 是否缺失必要字段。
  • 导入失败：确认 ZIP 结构包含顶层目录或根目录 SKILL.md；名称仅允许字母数字下划线短横线；目标路径未越界。
  • 下载失败：URL 协议仅限 http/https；主机非内网/环回；重定向次数不超过限制；响应体不超过 20MB。
  • 执行失败：检查 when 条件是否为真；参数类型是否正确；路径/命令是否被安全策略拒绝；命令灰名单需要确认。
  • 状态不一致：toggleSkill 优先更新 disabled_skills.json；若源文件写入失败不影响状态。

章节来源

结论 ​

Skill 系统通过 Markdown 驱动的 Agent 技能与 JSON/YAML 驱动的 Workflow 技能，形成“确定性自动化 + AI 自主决策”的双轨能力。加载器保证安全与健壮性，执行引擎提供并行与条件控制，注册表统一管理生命周期与状态。与 MCP 协议互补，Skill 聚焦“怎么做”，MCP 提供“用什么工具做”。开发者可基于现有示例快速构建从简单文本处理到复杂业务流程自动化的技能。

[本节为总结性内容，不直接分析具体文件]

附录：技能示例与开发指南 ​

SKILL.md 结构与元数据 ​

  • 必需字段：name、description、version。
  • 可选字段：enabled（默认启用）、parameters（JSON Schema 风格 properties/required）。
  • 正文：以 # 标题开头，随后说明何时使用、执行步骤、输出格式、参数说明等。

参考示例：

章节来源

参数规范与执行上下文 ​

  • parameters.properties 定义参数类型与必填项；executor 会进行类型转换与必填校验。
  • 执行上下文变量：
    • 用户传入的 params。
    • 前序步骤结果：variables.step.<stepId>、variables.step.<stepId>.success、variables.step.<stepId>.content。
  • when 条件：使用模板引擎评估布尔表达式，为假则跳过该步骤。

章节来源

开发最佳实践 ​

  • 明确何时使用：在 SKILL.md 的“何时使用”段落给出触发场景与关键词。
  • 步骤最小化：尽量将复杂流程拆分为多个小步骤，便于并行与重试。
  • 安全优先：避免敏感路径与危险命令；必要时走确认流程。
  • 资源组织：scripts/templates/assets/references 分类清晰，避免引入无关构建产物。
  • 可观测性：在步骤中输出结构化结果，便于前端展示与日志追踪。

[本节为通用指导，不直接分析具体文件]

调试技巧 ​

  • 查看步骤状态：getSkillExecutionStatus 返回 execId、status、steps、elapsed。
  • 逐步验证：先用简单的 echo/cat 命令验证环境，再逐步增加复杂操作。
  • 条件调试：打印 when 条件渲染后的值，确认布尔语义。
  • 资源调试：使用 scanResources 输出资源清单，确认目录结构正确。

章节来源

性能优化 ​

  • 并行化：将无依赖的步骤放入同一批次执行。
  • 限制结果规模：searchFiles/searchContent 设置 maxResults 与 contextLines。
  • 模板优化：避免在大型对象上反复渲染，必要时缓存中间结果。
  • 下载与导入：ZIP 体积控制在 20MB 以内，避免大文件拖慢启动。

章节来源

与 MCP 的组合使用 ​

  • 在 Workflow 步骤中调用 MCP 工具，完成数据库查询、代码仓库操作等外部系统交互。
  • 在 Agent 技能中引导 AI 选择合适的 MCP 工具，结合本地文件与命令执行，形成端到端自动化。
  • 注意区分 Skill 与 MCP 的职责边界：Skill 定义流程与策略，MCP 提供工具能力。

章节来源