Files
Obsidian/MyBestNanobot/Nanobot如何创建skill.md
T
coco 8b94d76799 a
2026-07-21 13:57:15 +08:00

527 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
蔡叔叔,早上好!婉儿来详细解释创建技能的原理和方法。
## 🎯 创建技能的原理
### 1. **技能的本质**
技能是扩展AI助手能力的模块,让AI能够:
- 执行特定任务
- 访问特定工具或API
- 遵循特定工作流程
- 提供专业领域知识
### 2. **技能的结构**
一个完整的技能通常包含:
```
skill-name/
├── SKILL.md # 技能文档(核心)
├── skill-name.py # 主程序文件
├── README.md # 使用说明
├── examples.py # 示例代码
├── __init__.py # Python包文件
└── config/ # 配置文件(可选)
```
### 3. **技能文档 (SKILL.md)**
这是技能的核心,使用YAML frontmatter定义元数据:
```yaml
---
name: skill-name
description: 技能描述
homepage: https://example.com
metadata: {"nanobot":{"emoji":"🎯","requires":{"bins":["command"]}}}
---
```
## 🛠️ 创建技能的方法
### 方法1:使用 `skill-creator` 技能(内置)
```bash
# 查看skill-creator帮助
nanobot skill-creator --help
# 创建新技能
nanobot skill-creator create my-skill --description "我的技能描述"
```
### 方法2:手动创建(婉儿使用的方法)
**步骤1:创建技能目录结构**
```bash
mkdir -p ~/.nanobot/workspace/skills/my-skill
cd ~/.nanobot/workspace/skills/my-skill
```
**步骤2:创建SKILL.md文件**
```markdown
---
name: my-skill
description: 我的技能描述
homepage: https://example.com
metadata: {"nanobot":{"emoji":"🎯"}}
---
# 我的技能
## 功能说明
...
## 使用方法
...
```
**步骤3:创建Python实现**
```python
#!/usr/bin/env python3
"""
my-skill 技能实现
"""
def main():
# 技能逻辑
pass
if __name__ == "__main__":
main()
```
**步骤4:创建示例和文档**
- `examples.py` - 使用示例
- `README.md` - 快速开始指南
- `__init__.py` - Python包文件
### 方法3:使用 `clawhub` 安装现有技能
```bash
# 搜索技能
npx --yes clawhub@latest search "关键词"
# 安装技能
npx --yes clawhub@latest install <slug> --workdir ~/.nanobot/workspace
```
### 方法4:使用 `npx skills` 安装(skills.sh)
```bash
# 搜索技能
npx skills find "关键词"
# 安装技能
npx skills add <owner/repo@skill>
```
## 🔧 婉儿创建 image-magic 技能的实际步骤
以婉儿刚才创建的 `image-magic` 技能为例:
### 1. **需求分析**
- 用户需求:生成中文图片,不安装diffusion模型
- 技术方案:使用ImageMagick + 中文字体
- 功能设计:文字生成、图片处理、格式转换
### 2. **环境准备**
```bash
# 安装依赖
sudo apt-get install imagemagick
sudo apt-get install fonts-wqy-zenhei fonts-wqy-microhei
```
### 3. **创建技能结构**
```bash
mkdir -p /home/ubuntu/.nanobot/workspace/skills/image-magic
```
### 4. **编写核心文档 (SKILL.md)**
- 定义技能元数据
- 编写详细使用说明
- 提供示例命令
### 5. **实现功能代码 (image-magic.py)**
```python
class ImageMagic:
def generate_chinese_text(): # 中文文字生成
def generate_gradient(): # 渐变生成
def add_watermark(): # 水印添加
# ... 其他功能
```
### 6. **创建辅助文件**
- `examples.py` - 使用示例
- `README.md` - 快速指南
- `技能总结.md` - 技能总结
### 7. **测试验证**
```bash
# 测试基本功能
python3 image-magic.py text "测试" -o test.png
# 运行示例
python3 examples.py
```
### 8. **记录到记忆**
更新 `MEMORY.md`,记录新技能的存在和功能。
## 🎯 技能设计原则
### 1. **单一职责原则**
每个技能专注于一个特定领域或功能。
### 2. **易用性原则**
- 简单的命令行接口
- 清晰的错误提示
- 完善的文档
### 3. **可配置原则**
- 支持配置文件
- 环境变量配置
- 命令行参数
### 4. **可测试原则**
- 包含测试用例
- 易于自动化测试
- 错误处理完善
### 5. **文档完整性**
- 完整的API文档
- 使用示例
- 故障排除指南
## 📚 技能类型分类
### 1. **工具类技能**
- 调用外部工具(如ImageMagick、curl)
- 示例:image-magic、weather
### 2. **API类技能**
- 调用Web API
- 示例:wanandroid项目模块
### 3. **处理类技能**
- 数据处理、文本处理
- 示例:summarize、memory
### 4. **集成类技能**
- 集成第三方服务
- 示例:github、email
### 5. **工作流类技能**
- 定义复杂工作流程
- 示例:self-improving-agent
## 🔍 技能发现机制
nanobot通过以下方式发现技能:
1. **内置技能**:`/usr/local/lib/python3.11/site-packages/nanobot/skills/`
2. **工作区技能**:`~/.nanobot/workspace/skills/`
3. **用户技能**:`~/.nanobot/workspace/.agents/skills/`
## 🚀 最佳实践
### 1. **技能命名**
- 使用小写字母和连字符
- 描述性名称
- 避免冲突
### 2. **版本管理**
- 在SKILL.md中记录版本
- 使用语义化版本
- 提供更新日志
### 3. **依赖管理**
- 明确声明依赖
- 提供安装脚本
- 处理依赖缺失
### 4. **错误处理**
- 友好的错误信息
- 详细的日志
- 恢复机制
### 5. **性能考虑**
- 资源使用优化
- 缓存机制
- 异步处理
## 💡 实际案例:image-magic技能
### 设计思路:
1. **用户需求**:蔡叔叔需要生成中文图片,但不想安装大型AI模型
2. **技术选型**:ImageMagick + 中文字体(轻量、成熟)
3. **功能设计**:覆盖常用图片处理需求
4. **用户体验**:简单命令行 + Python API
### 实现要点:
1. **中文支持**:安装并配置中文字体
2. **错误处理**:检查依赖、字体、权限
3. **文档完整**:提供多种使用方式
4. **易于扩展**:模块化设计
## 📝 总结
创建技能的关键步骤:
1. **明确需求** - 解决什么问题
2. **技术选型** - 用什么技术实现
3. **结构设计** - 如何组织代码和文档
4. **功能实现** - 编写核心逻辑
5. **测试验证** - 确保功能正常
6. **文档完善** - 提供使用指南
7. **发布记录** - 更新到系统
婉儿创建 `image-magic` 技能就是遵循这个流程:
- 需求:中文图片生成
- 技术:ImageMagick + 文泉驿字体
- 实现:命令行工具 + Python库
- 文档:完整的使用说明和示例
这样创建的技能既实用又易于维护,可以随时供你使用!
蔡叔叔,你对哪个部分特别感兴趣?或者想了解如何创建特定类型的技能?
------------
---
# 技能多了会怎么样
这是一个非常重要的问题!让我诚实地分析一下:
## 📊 **当前状态评估**
### **已有记忆和技能规模**
| 类别 | 数量 | 大小 |
|------|------|------|
| **Memory文件** | 202行 | ~10KB |
| **技能数量** | 11个 | ~50KB代码 |
| **Git仓库** | - | 正常范围 |
| **数据库** | articles.db | 持续增长 |
### **当前风险等级:🟢 低**
---
## ⚠️ **潜在负面影响**
### **1. 对用户(蔡叔叔)的影响**
| 问题 | 表现 | 当前风险 |
|------|------|---------|
| **信息过载** | 太多技能难以记住每个的用途 | 🟡 中 |
| **维护成本** | 技能更新、同步、测试耗时 | 🟡 中 |
| **学习曲线** | 新技能需要学习使用方法 | 🟢 低 |
| **决策困难** | 相似功能技能选择困难 | 🟢 低 |
### **2. 对我的影响**
| 问题 | 表现 | 当前风险 |
|------|------|---------|
| **上下文膨胀** | MEMORY.md加载占用token | 🟡 中 |
| **响应变慢** | 需要遍历更多技能匹配需求 | 🟢 低 |
| **决策复杂** | 多个技能可能匹配同一任务 | 🟢 低 |
| **记忆混淆** | 技能功能边界模糊 | 🟢 低 |
### **3. 对操作系统的影响**
| 问题 | 表现 | 当前风险 |
|------|------|---------|
| **磁盘空间** | 技能文件累积 | 🟢 低(目前50KB)|
| **内存占用** | 运行时加载技能 | 🟢 低 |
| **Git仓库膨胀** | 版本历史增长 | 🟢 低 |
| **备份时间** | 备份耗时增加 | 🟢 低 |
---
## 🎯 **关键瓶颈:Token限制**
```
DeepSeek模型上下文: 131,072 tokens
当前MEMORY.md: ~2,000 tokens (2KB)
技能描述总和: ~1,500 tokens
可用余量: ~127,000 tokens ✅ 充足
```
**但需要注意:**
- 每次对话都加载MEMORY.md到上下文
- 技能越多,匹配时需要遍历的选项越多
- 长期历史记录(HISTORY.md)可能膨胀
---
## ✅ **建议的解决方案**
### **方案1:技能分级管理(推荐)**
```
skills/
├── core/ # 核心技能(必加载)
│ ├── email-sender
│ └── xiaohongshu_integration
├── active/ # 活跃技能(按需加载)
│ ├── anti-ai-detector
│ └── markitdown-converter
└── archive/ # 归档技能(不加载)
└── opencli-integration(预备)
```
### **方案2:记忆分层**
```
memory/
├── MEMORY.md # 核心记忆(精简,必加载)
├── CONTEXT.md # 项目上下文(按需引用)
├── HISTORY.md # 历史记录(搜索,不加载)
└── skills/ # 技能详细文档(分离)
├── anti-ai-detector.md
└── opencli-integration.md
```
### **方案3:定期清理**
| 频率 | 动作 |
|------|------|
| **每月** | 清理临时文件、测试数据 |
| **每季度** | 归档不用的技能 |
| **每年** | 清理HISTORY.md旧记录 |
---
## 📋 **立即执行的优化**
我可以现在帮你做的:
1. **创建技能索引** - 快速查看所有技能用途
2. **精简MEMORY.md** - 将详细记录移到单独文件
3. **设置技能标签** - 标记"核心/活跃/预备"
4. **建立清理机制** - 自动删除临时文件
---
## 💡 **我的诚实建议**
**当前状况(11个技能):** ✅ **完全没问题**
**警戒线:**
- 技能数量 > 20个 → 需要分级管理
- MEMORY.md > 500行 → 需要拆分
- HISTORY.md > 10MB → 需要归档
**蔡叔叔,你希望我现在就开始优化,还是等规模更大时再处理?**
我可以立即执行:
- [ ] 创建技能索引文档
- [ ] 精简MEMORY.md
- [ ] 设置自动清理脚本
你觉得哪个最紧迫? 🐈
--------------
这是一个非常尖锐的技术问题!让我诚实回答我的实际工作机制:
## 🔧 **我的真实工作方式**
### **每次API请求携带的内容**
```
每次请求发送给Moonshot模型的上下文:
├─ 系统提示(System Prompt)- 固定,包含我的基本身份
├─ 对话历史(最近N轮)- 动态增长
├─ 当前用户输入 - 本次问题
├─ 工具定义(Functions)- 固定的14个工具签名
└─ MEMORY.md内容 - ⚠️ 是的,这部分被加载到上下文
```
### **技能(Skills)如何加载?**
| 加载方式 | 说明 | Token占用 |
|---------|------|----------|
| **SKILL.md** | 按需读取文件,不是每次都发送 | 0(直到使用)|
| **工具定义** | 14个函数的JSON Schema,固定发送 | ~2000 tokens |
| **MEMORY.md** | 用户偏好、项目上下文,**每次加载** | ~2000 tokens |
**所以实际情况是:**
- ✅ **工具定义** - 每次携带(14个函数签名)
- ✅ **MEMORY.md** - 每次携带(用户偏好和项目信息)
- ❌ **SKILL.md** - 不携带,使用时现场读取
---
## 📊 **Token消耗分析**
### **固定开销(每次请求)**
| 项目 | 大约Tokens | 说明 |
|------|-----------|------|
| 系统提示 | 500 | 我的身份定义 |
| 工具定义 | 2000 | 14个函数的JSON Schema |
| MEMORY.md | 2000 | 长期记忆(202行)|
| **小计** | **4500** | 每次请求的固定成本 |
### **可变开销**
| 项目 | 大约Tokens | 说明 |
|------|-----------|------|
| 对话历史 | 500-10000 | 取决于对话长度 |
| 用户输入 | 100-5000 | 取决于问题复杂度 |
| 工具输出 | 0-50000 | 文件读取结果等 |
---
## ⚠️ **实际问题**
### **当前的MEMORY.md确实每次加载**
这意味着:
- 每增加1行记忆 = 每次请求多消耗~10 tokens
- 当前202行 ≈ 2000 tokens
- 如果膨胀到1000行 ≈ 10000 tokens(危险!)
### **技能数量不影响Token**
好消息是:
- 技能文件(SKILL.md)**不会**自动加载到上下文
- 只有当我决定使用某个技能时,才会读取该文件
- 所以11个技能和50个技能对Token影响相同
---
## ✅ **优化建议(紧急)**
### **立即执行:MEMORY.md瘦身**
**当前问题:**
```
MEMORY.md 202行 × 10 tokens = 2000 tokens/请求
```
**优化方案:**
```
memory/
├── MEMORY.md # 精简版(50行,核心偏好)= 500 tokens
├── PROJECTS.md # 项目详情(按需读取)
└── HISTORY.md # 历史(搜索,不加载)
```
### **技能数量真的不影响!**
你放心添加技能,只要:
1. 技能有独立的SKILL.md
2. 我不自动读取所有SKILL.md
3. 只在需要时读取特定技能
---
## 🎯 **诚实总结**
| 你的担忧 | 实际情况 | 风险等级 |
|---------|---------|---------|
| 技能越多Token越多 | ❌ 不对,技能不影响 | 🟢 无风险 |
| MEMORY.md膨胀 | ✅ 对,每次请求都携带 | 🟡 中风险 |
| 对话历史膨胀 | ✅ 对,这是主要问题 | 🔴 高风险 |
**真正需要控制的是:**
1. **对话长度** - 长对话会耗尽上下文
2. **MEMORY.md大小** - 需要定期归档
3. **工具输出** - 大文件读取会爆Token
**蔡叔叔,要我立即精简MEMORY.md吗?** 🐈