主题
Day 6 — Skills 设计文档
设计目标：用 Markdown 文件定义可复用的 Agent 行为模式（技能），支持关键词触发匹配和动态激活，将 system_prompt 注入与工具需求声明解耦。
一、核心接口设计
1.1 Skill 数据结构
| 字段 | 类型 | 说明 |
|---|---|---|
| name | str | 技能唯一标识 |
| description | str | 技能描述 |
| triggers | List[str] | 触发关键词列表 |
| required_tools | List[str] | 依赖的工具名列表 |
| system_prompt | str | 注入的提示词（Markdown 正文） |
1.2 SkillLoader
| 方法 | 签名 | 说明 |
|---|---|---|
| load_file | load_file(path: str) -> Skill | 从单个 Markdown 文件加载技能 |
| load_directory | load_directory(dir: str) -> List[Skill] | 从目录批量加载所有 .md 文件 |
1.3 SkillManager
| 方法 | 签名 | 说明 |
|---|---|---|
| register | register(skill: Skill) | 注册技能 |
| match | match(text: str) -> Optional[Skill] | 匹配文本中的触发词 |
| activate | activate(name: str) | 激活指定技能 |
| deactivate | deactivate(name: str) | 取消激活 |
| get_active_prompts | get_active_prompts() -> List[str] | 获取所有激活技能的提示词 |
| get_required_tools | get_required_tools() -> List[str] | 获取所有激活技能需要的工具名 |
二、关键流程图
技能加载流程
技能匹配与激活流程
三、设计决策与权衡
决策 1：Markdown + Front Matter 格式
| 方案 | 优点 | 缺点 |
|---|---|---|
| Markdown + Front Matter（选择） | 正文即提示词，所见即所得；非技术人员也能编辑 | 不适合复杂逻辑定义 |
| Python 类定义 | 灵活，可以内嵌逻辑 | 改提示词要改代码 |
| JSON/YAML 文件 | 结构清晰 | 长文本提示词编写体验差 |
| 数据库存储 | 适合大量技能、动态管理 | 需要管理后台、额外基础设施 |
选择理由：技能的核心价值是 system_prompt（长文本），Markdown 是编写长文本最友好的格式。Front Matter 补充结构化元信息，两者结合完美。
决策 2：关键词匹配 vs 语义匹配
| 方案 | 优点 | 缺点 |
|---|---|---|
| 关键词包含匹配（选择） | 简单直观，零延迟 | 不够智能（"请转化成英文"匹配不到"翻译"） |
| LLM 语义匹配 | 最智能，理解同义词 | 每次匹配都要调 LLM，成本高 |
| 向量相似度 | 比关键词智能，比 LLM 便宜 | 需要向量模型和索引 |
选择理由：教学阶段用关键词匹配足够理解概念。理解了机制后，替换为语义匹配只需改 match() 方法内部实现。
决策 3：支持多技能同时激活
| 方案 | 优点 | 缺点 |
|---|---|---|
| 多技能激活（选择） | 灵活，可以叠加能力（"翻译 + 正式语气"） | 多个 prompt 可能冲突 |
| 单技能激活 | 简单，不会冲突 | 无法组合能力 |
权衡：多技能激活更灵活，但需要注意 prompt 拼接顺序和冲突处理。当前实现按注册顺序拼接。
决策 4：技能提示词是"叠加"而非"替换"
技能的 system_prompt 追加到基础 system_prompt 后面，而不是替换：
最终 system_prompt = 基础人设 + "\n\n" + 技能1提示词 + "\n\n" + 技能2提示词理由：基础人设（如安全规则、回复格式）应该始终生效，技能只是额外增强。
四、与前序章节的集成点
- 依赖 Day 5：
required_tools引用 ToolRegistry 中的工具名 - 被 Day 4 依赖：
get_active_prompts()的结果注入到 AgentRuntime 的消息构建中 - 被 Day 7 依赖：SystemPromptBuilder 将 Skill prompts 作为组装层之一
五、与真实生产系统的对比
| 维度 | miniOpenClaw | 生产级实现 |
|---|---|---|
| 技能定义 | 本地 Markdown 文件 | 数据库 + 管理后台 |
| 匹配方式 | 关键词包含 | LLM 意图识别 + 向量召回 |
| 版本管理 | 文件级（Git） | 技能版本控制 + A/B 测试 |
| 冲突处理 | 无（按顺序拼接） | 优先级排序 + 冲突检测 |
| 权限 | 无 | 按用户/团队分配可用技能 |
| 动态更新 | 重启加载 | 热更新（不重启生效） |