527 lines
13 KiB
Markdown
527 lines
13 KiB
Markdown
蔡叔叔,早上好!婉儿来详细解释创建技能的原理和方法。
|
||
|
||
## 🎯 创建技能的原理
|
||
|
||
### 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吗?** 🐈
|
||
|