技能加载器¶

📎 引用文件

本文引用的文件 - skills.py - frontmatter.py - load_skill_tool.py - skill_writer_tool.py - SKILL.md（根） - strategy-generate/SKILL.md - tushare/SKILL.md

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考量
故障排查指南
结论
附录：开发指南与示例

简介¶

本文件为 Vibe-Trading 技能系统的技术文档，聚焦“技能加载器”的架构设计与实现。内容涵盖： - 技能定义格式与元数据解析 - 动态加载、版本控制与热重载机制 - 技能与工具的集成方式及技能间协作模式 - 技能开发规范（SKILL.md、脚本编写、测试方法） - 内置技能特性与使用示例 - 自定义技能的发布与分发流程

项目结构¶

技能系统围绕“文档即实现”的理念构建：每个技能是一个独立目录，包含 SKILL.md（主文档）以及可选的 references/templates/examples/assets 等辅助资源。运行时通过 SkillsLoader 扫描并加载内置与用户技能，LoadSkillTool 提供按需分页与章节定位能力，Skill Writer Tools 支持创建、修补、删除与辅助文件管理。

graph TB A["SkillsLoader 扫描与合并"] --> B["Skill 对象 name/description/category/body/metadata"] A --> C["frontmatter 解析 YAML-like 元数据"] D["LoadSkillTool 分页/大纲/章节"] --> E["split_sections/find_sections 标题树与路径定位"] F["Skill Writer Tools save/patch/delete/file"] --> G["~/.vibe-trading/skills/user/<skill>/"] H["内置技能目录 agent/src/skills/*"] --> A I["用户技能目录 USER_SKILLS_DIR"] --> A

图表来源 - skills.py:100-136 - frontmatter.py:16-48 - load_skill_tool.py:150-306 - skill_writer_tool.py:48-370

章节来源 - skills.py:1-136 - frontmatter.py:1-49 - load_skill_tool.py:1-306 - skill_writer_tool.py:1-370

核心组件¶

Skill 数据模型：封装技能名称、描述、分类、正文、目录路径与元数据，并提供按需加载辅助文件的能力。
SkillsLoader：负责从用户目录与内置目录扫描并去重加载技能；按类别排序输出摘要；支持会话中新增的用户技能即时发现。
frontmatter 解析器：轻量 YAML-like 解析，提取 name/description/category/dependencies/env/mcp 等字段。
LoadSkillTool：将技能文档以“完整/大纲/章节/分页”四种模式返回，解决大文档不可用问题。
Skill Writer Tools：提供 save_skill、patch_skill、delete_skill、skill_file 四个工具，完成用户技能的 CRUD 与辅助文件管理。

章节来源 - skills.py:22-94 - skills.py:100-189 - frontmatter.py:16-48 - load_skill_tool.py:150-306 - skill_writer_tool.py:48-370

架构总览¶

技能加载器采用“分层+按需”的设计： - 元数据层：frontmatter 解析出技能声明式配置（名称、版本、依赖、环境变量、MCP 命令）。 - 装载层：SkillsLoader 合并用户与内置技能，优先用户覆盖同名内置技能。 - 呈现层：LoadSkillTool 根据文档大小与头部结构智能返回“完整/大纲/章节”，并通过 offset 分页。 - 管理层：Skill Writer Tools 维护用户技能生命周期与辅助文件。

sequenceDiagram participant U as "调用方" participant LST as "LoadSkillTool" participant SL as "SkillsLoader" participant FM as "frontmatter 解析" participant FS as "split_sections/find_sections" U->>LST : 调用 load_skill(name, section?, offset?) LST->>SL : get_content(name) SL->>FM : 读取 SKILL.md 并解析 frontmatter FM-->>SL : 元数据 + 正文 SL-->>LST : XML 包裹的 skill body alt 需要章节或分页 LST->>FS : split_sections(document) FS-->>LST : 章节列表 LST->>FS : find_sections(sections, wanted) FS-->>LST : 匹配章节 LST-->>U : 返回章节/大纲/分页结果 else 直接返回完整文档 LST-->>U : 返回完整文档 end

图表来源 - load_skill_tool.py:196-306 - skills.py:166-189 - skills.py:229-386 - frontmatter.py:16-48

详细组件分析¶

技能定义与元数据解析¶

SKILL.md 顶部使用 --- 分隔的 frontmatter 块，支持字符串、列表与布尔值。
关键字段包括 name、description、category、version、dependencies、env、mcp 等。
解析器对空元数据与无 frontmatter 的情况均兼容处理。

flowchart TD Start(["读取 SKILL.md"]) --> CheckFM{"是否包含 frontmatter?"} CheckFM -- 否 --> BodyOnly["返回空元数据 + 正文"] CheckFM -- 是 --> Parse["逐行解析键值对"] Parse --> ListVal{"值是否为列表?"} ListVal -- 是 --> ToList["转为列表项"] ListVal -- 否 --> BoolVal{"值为 true/false?"} BoolVal -- 是 --> ToBool["转为布尔"] BoolVal -- 否 --> KeepStr["保持字符串"] ToList --> Done["返回 {元数据, 正文}"] ToBool --> Done KeepStr --> Done BodyOnly --> Done

图表来源 - frontmatter.py:10-48

章节来源 - frontmatter.py:16-48 - SKILL.md（根）:1-22

技能动态加载与覆盖策略¶

加载顺序：先用户目录，后内置目录；同名技能以后者被前者覆盖。
仅识别包含 SKILL.md 的子目录作为有效技能。
会话期间新增的用户技能可通过 get_content 的磁盘回退路径即时发现并追加到内存列表。

classDiagram class SkillsLoader { +skills_dir : Path +_user_skills_dir : Path +skills : List[Skill] +__init__(skills_dir, user_skills_dir) -_load() void +get_descriptions() str +get_content(name) str } class Skill { +name : str +description : str +category : str +body : str +dir_path : Path +metadata : Dict +load_support_file(filename) str? } SkillsLoader --> Skill : "创建/聚合"

图表来源 - skills.py:22-94 - skills.py:100-189

章节来源 - skills.py:100-189

文档大纲与章节定位¶

split_sections：忽略代码围栏内的标题，提取 ATX 标题层级，计算每节起止位置与首行摘要。
ancestor_titles/qualified_path：生成“父 > 子”路径，解决重复标题歧义。
find_sections/find_section：支持精确与前缀匹配，结合祖先路径进行定位。

flowchart TD S["输入文档"] --> Scan["逐行扫描 跳过围栏内标题"] Scan --> Headings["收集标题(level,title,start)"] Headings --> Summaries["为每个标题记录首行摘要"] Summaries --> EndCalc["计算每节结束位置(下一个同级或更浅标题)"] EndCalc --> Sections["输出 SkillSection 列表"]

图表来源 - skills.py:229-278 - skills.py:294-386

章节来源 - skills.py:229-386

技能加载工具（分页与大纲）¶

小文档：一次性返回完整内容。
大文档：首次返回“大纲 + 开头文本”，后续可按 section 或 offset 继续读取。
页大小自适应：根据序列化后的 JSON 长度动态调整，保证不超过工具结果限制。

sequenceDiagram participant T as "LoadSkillTool" participant L as "SkillsLoader" participant P as "分页/大纲逻辑" T->>L : get_content(name) L-->>T : skill body alt 未指定 section 且可分页 T->>P : split_sections + _render_outline P-->>T : 大纲 + 起始片段 T-->>调用方 : mode=outline/document else 指定 section T->>P : find_sections(section) P-->>T : 目标章节 T-->>调用方 : mode=section (offset/next_offset) end

图表来源 - load_skill_tool.py:55-147 - load_skill_tool.py:196-306

章节来源 - load_skill_tool.py:1-306

技能管理与辅助文件¶

save_skill：创建或覆盖用户技能，自动补齐 frontmatter。
patch_skill：在用户目录查找或复制内置技能后进行替换修补。
delete_skill：删除用户技能目录。
skill_file：在受允许的 subdirs（references/templates/examples/assets）下写/删/列文件，防止路径穿越。

classDiagram class SaveSkillTool { +execute(**kwargs) str } class PatchSkillTool { +execute(**kwargs) str } class DeleteSkillTool { +execute(**kwargs) str } class SkillFileTool { +execute(**kwargs) str -_list_files(...) -_write_file(...) -_remove_file(...) } SaveSkillTool --> "写入 ~/.vibe-trading/skills/user/<slug>/SKILL.md" PatchSkillTool --> "用户目录或复制内置后替换" DeleteSkillTool --> "删除用户技能目录" SkillFileTool --> "受限子目录读写"

图表来源 - skill_writer_tool.py:48-370

章节来源 - skill_writer_tool.py:48-370

依赖关系分析¶

SkillsLoader 依赖 frontmatter 解析器与文件系统。
LoadSkillTool 依赖 SkillsLoader 与章节解析工具。
Skill Writer Tools 依赖 SkillsLoader 暴露的用户目录常量与文件系统安全校验。
根 SKILL.md 定义了全局依赖（Python 版本、pip 包、环境变量、MCP 命令），用于技能清单与运行环境约束。

graph LR FM["frontmatter.py"] --> SL["skills.py"] SL --> LST["load_skill_tool.py"] SW["skill_writer_tool.py"] --> SL ROOT["agent/SKILL.md"] --> SL

图表来源 - frontmatter.py:16-48 - skills.py:100-189 - load_skill_tool.py:196-306 - skill_writer_tool.py:48-370 - SKILL.md（根）:1-22

章节来源 - skills.py:100-189 - load_skill_tool.py:196-306 - skill_writer_tool.py:48-370 - SKILL.md（根）:1-22

性能考量¶

渐进式披露：系统提示仅注入技能一行摘要，全文按需加载，降低上下文占用。
大纲优先：大文档首次返回大纲与开头文本，避免盲目翻页。
自适应分页：根据序列化长度动态调整页大小，确保不超出工具结果限制。
章节定位：通过标题树与路径定位，减少无关内容传输。
用户覆盖优先：同名用户技能覆盖内置，便于快速迭代与补丁。

[本节为通用指导，无需特定文件引用]

故障排查指南¶

未知技能名：检查技能是否存在于用户或内置目录，确认 SKILL.md 存在且 frontmatter 含 name。
章节不存在或歧义：使用 outline 中的“父 > 子”路径精确定位；若多个匹配，需提供更完整路径。
偏移越界：确认当前章节或文档长度，使用 next_offset 继续读取。
辅助文件路径非法：确保路径以允许的子目录开头，且不发生路径穿越。
补丁失败：确认待替换文本存在，或先保存/复制技能再执行补丁。

章节来源 - load_skill_tool.py:227-273 - skill_writer_tool.py:143-186 - skill_writer_tool.py:270-370

结论¶

Vibe-Trading 的技能加载器以“文档即实现”为核心，通过轻量 frontmatter、健壮的分页与章节定位、灵活的用户覆盖机制，实现了高可用、可扩展的技能生态。配合 Skill Writer Tools，开发者可以便捷地创建、修补与管理技能，满足复杂金融研究场景的需求。

[本节为总结性内容，无需特定文件引用]

附录：开发指南与示例¶

SKILL.md 文件格式规范¶

必须包含 frontmatter 块，至少提供 name；建议补充 description、category、version、dependencies、env、mcp。
正文建议使用 ATX 标题组织章节，便于 split_sections 解析。
可在技能目录下放置 references/templates/examples/assets 等辅助资源，并通过 load_support_file 按需加载。

章节来源 - frontmatter.py:16-48 - skills.py:22-94 - SKILL.md（根）:1-22

脚本编写规范（以策略生成为例）¶

遵循 SignalEngine 契约：generate(data_map) -> Dict[str, Series]，信号范围 [-1, 1]。
严格对齐索引、纯 pandas/numpy 实现、不含外部库、不硬编码日期与代码。
config.json 指定 source/codes/时间范围/初始资金/手续费/优化器等参数。
多市场策略使用 CompositeEngine 自动对齐日历与共享资金。

章节来源 - strategy-generate/SKILL.md:45-160 - strategy-generate/SKILL.md:196-200

测试方法¶

单元测试：针对 load_skill 分页、章节定位、错误处理等路径进行断言。
端到端：验证技能加载、大纲生成、章节读取与辅助文件访问。
回归：确保同名用户技能覆盖内置行为稳定。

[本节为通用指导，无需特定文件引用]

内置技能特性与使用示例¶

tushare：提供丰富的财经数据接口说明与环境变量配置指引，适合 A 股与多资产数据获取。
strategy-generate：完整的策略设计、编码、回测与评估工作流，支持多市场与组合策略。

章节来源 - tushare/SKILL.md:1-50 - strategy-generate/SKILL.md:7-43

自定义技能的发布与分发流程¶

创建：使用 save_skill 写入用户目录，自动生成 frontmatter。
修补：使用 patch_skill 对现有技能进行精准替换，必要时先复制到用户目录。
管理：使用 skill_file 管理 references/templates/examples/assets，注意路径白名单与安全校验。
分发：将用户技能目录打包或通过版本管理共享；运行时自动发现并优先加载。

章节来源 - skill_writer_tool.py:48-370

← Agent核心循环核心组件 →