CoPaw 技能系统详解#

概述#

CoPaw 的技能系统是一个可扩展的插件系统，允许你为 CoPaw 添加各种功能。技能从工作区自动加载，内置定时调度，是一等公民 —— 可发现、可组合、可独立部署。

技能系统概述#

什么是技能#

技能是 CoPaw 的功能扩展模块，可以为 CoPaw 添加新的能力。

技能特点：

可发现：可以通过 CLI 命令发现和安装
可组合：多个技能可以组合使用
可独立部署：技能可以独立开发和部署
无厂商锁定：完全开源，无厂商限制

技能类型#

类型	说明	示例
内置技能	CoPaw 自带的基本技能	天气查询、计算器
自定义技能	用户自己开发的技能	数据分析、报告生成
社区技能	社区共享的技能	网络爬虫、内容生成

技能目录结构#

PRTCL // PLAINTEXT

1
~/.copaw/workspace/skills/
2
├── builtin/              # 内置技能
3
│   ├── weather/
4
│   │   └── SKILL.md
5
│   ├── calculator/
6
│   │   └── SKILL.md
7
│   └── ...
8
├── customized/           # 自定义技能
9
│   ├── my-skill/
10
│   │   ├── SKILL.md
11
│   │   ├── main.py
12
│   │   └── config.yaml
13
│   └── ...
14
└── active/               # 激活的技能
15
    ├── weather -> ../builtin/weather
16
    ├── calculator -> ../builtin/calculator
17
    └── my-skill -> ../customized/my-skill

技能管理#

技能 CLI 命令#

查看可用技能：

PRTCL // BASH

1
# 列出所有可用技能
2
copaw skills list
3

4
# 列出已安装技能
5
copaw skills installed
6

7
# 列出激活的技能
8
copaw skills active

安装技能：

PRTCL // BASH

1
# 从本地安装
2
copaw skills install path/to/skill
3

4
# 从 Git 仓库安装
5
copaw skills install git+https://github.com/user/skill.git
6

7
# 从 PyPI 安装
8
copaw skills install skill-name

移除技能：

PRTCL // BASH

1
# 移除技能
2
copaw skills remove skill-name
3

4
# 强制移除
5
copaw skills remove skill-name --force

更新技能：

PRTCL // BASH

1
# 更新技能
2
copaw skills update skill-name
3

4
# 更新所有技能
5
copaw skills update --all

激活 / 停用技能：

PRTCL // BASH

1
# 激活技能
2
copaw skills activate skill-name
3

4
# 停用技能
5
copaw skills deactivate skill-name

技能搜索#

搜索技能：

PRTCL // BASH

1
# 搜索技能
2
copaw skills search keyword
3

4
# 搜索天气相关技能
5
copaw skills search weather
6

7
# 搜索计算相关技能
8
copaw skills search calculator

技能信息#

查看技能详情：

PRTCL // BASH

1
# 查看技能详情
2
copaw skills info skill-name
3

4
# 查看技能配置
5
copaw skills config skill-name
6

7
# 查看技能依赖
8
copaw skills dependencies skill-name

技能结构#

SKILL.md 文件#

基础结构：

PRTCL // MARKDOWN

1
# 技能名称
2

3
## 描述
4
简要描述技能的功能和用途。
5

6
## 版本
7
1.0.0
8

9
## 作者
10
Your Name
11

12
## 依赖
13
- numpy >= 1.20.0
14
- requests >= 2.25.0
15

16
## 配置
17
```yaml
18
param1: value1
19
param2: value2

使用方法#

说明如何使用该技能。

示例#

PRTCL // PLAINTEXT

1
用户：查询北京的天气
2
CoPaw：[调用天气技能] 北京今天天气晴朗，温度 25°C

PRTCL // PLAINTEXT

1
** 高级结构 **：
2
```markdown
3
# 高级数据分析技能
4

5
## 描述
6
提供强大的数据分析功能，包括统计分析、数据可视化和报告生成。
7

8
## 版本
9
2.1.0
10

11
## 作者
12
Data Team
13

14
## 依赖
15
- pandas >= 1.5.0
16
- numpy >= 1.23.0
17
- matplotlib >= 3.5.0
18
- plotly >= 5.0.0
19

20
## 配置
21
```yaml
22
output_format: "markdown"
23
chart_theme: "plotly"
24
max_rows: 1000
25
cache_enabled: true
26
cache_ttl: 3600

功能#

数据加载和清洗
统计分析
数据可视化
报告生成

使用方法#

PRTCL // PLAINTEXT

1
用户：分析销售数据
2
CoPaw：[调用数据分析技能] 正在分析销售数据...

示例#

PRTCL // PLAINTEXT

1
用户：分析今年的销售数据并生成报告
2
CoPaw：[调用数据分析技能]
3
- 加载数据：sales_2024.csv
4
- 数据清洗：完成
5
- 统计分析：
6
  * 总销售额：¥1,234,567
7
  * 同比增长：15.3%
8
  * 月均销售额：¥102,880
9
- 数据可视化：生成图表
10
- 报告生成：完成

权限#

read: 读取文件
write: 写入文件
network: 网络访问

限制#

最大文件大小：100MB
最大处理行数：10,000 行

PRTCL // PLAINTEXT

1
### main.py 文件
2

3
** 基础结构 **：
4
```python
5
# main.py
6
from typing import Dict, Any
7
from copaw.skills import Skill
8

9
class MySkill(Skill):
10
    """自定义技能"""
11

12
    def __init__(self, config: Dict[str, Any]):
13
        super().__init__(config)
14
        self.param1 = config.get('param1', 'default_value')
15

16
    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
17
        """执行技能"""
18
        result = self.process(input_data)
19
        return {
20
            'success': True,
21
            'result': result
22
        }
23

24
    def process(self, input_data: Dict[str, Any]) -> Any:
25
        """处理输入数据"""
26
        # 处理逻辑
27
        return processed_result

高级结构：

PRTCL // PYTHON

1
import pandas as pd
2
import matplotlib.pyplot as plt
3
from typing import Dict, Any, List
4
from copaw.skills import Skill
5

6
class DataAnalysisSkill(Skill):
7
    """数据分析技能"""
8

9
    def __init__(self, config: Dict[str, Any]):
10
        super().__init__(config)
11
        self.output_format = config.get('output_format', 'markdown')
12
        self.chart_theme = config.get('chart_theme', 'plotly')
13
        self.max_rows = config.get('max_rows', 1000)
14
        self.cache_enabled = config.get('cache_enabled', True)
15
        self.cache_ttl = config.get('cache_ttl', 3600)
16

17
    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
18
        """执行数据分析"""
19
        try:
20
            # 加载数据
21
            data = self.load_data(input_data)
22

23
            # 数据清洗
24
            cleaned_data = self.clean_data(data)
25

26
            # 统计分析
27
            stats = self.analyze(cleaned_data)
28

29
            # 数据可视化
30
            charts = self.visualize(cleaned_data)
31

32
            # 生成报告
33
            report = self.generate_report(stats, charts)
34

35
            return {
36
                'success': True,
37
                'result': report,
38
                'stats': stats,
39
                'charts': charts
40
            }
41
        except Exception as e:
42
            return {
43
                'success': False,
44
                'error': str(e)
45
            }
46

47
    def load_data(self, input_data: Dict[str, Any]) -> pd.DataFrame:
48
        """加载数据"""
49
        file_path = input_data.get('file_path')
50
        if file_path.endswith('.csv'):
51
            return pd.read_csv(file_path)
52
        elif file_path.endswith('.xlsx'):
53
            return pd.read_excel(file_path)
54
        else:
55
            raise ValueError("不支持的文件格式")
56

57
    def clean_data(self, data: pd.DataFrame) -> pd.DataFrame:
58
        """清洗数据"""
59
        # 去除重复
60
        data = data.drop_duplicates()
61

62
        # 处理缺失值
63
        data = data.fillna(data.mean())
64

65
        # 限制行数
66
        if len(data) > self.max_rows:
67
            data = data.head(self.max_rows)
68

69
        return data
70

71
    def analyze(self, data: pd.DataFrame) -> Dict[str, Any]:
72
        """统计分析"""
73
        stats = {
74
            'count': len(data),
75
            'mean': data.mean().to_dict(),
76
            'std': data.std().to_dict(),
77
            'min': data.min().to_dict(),
78
            'max': data.max().to_dict(),
79
            'median': data.median().to_dict()
80
        }
81
        return stats
82

83
    def visualize(self, data: pd.DataFrame) -> List[str]:
84
        """数据可视化"""
85
        charts = []
86
        # 生成图表
87
        fig, ax = plt.subplots(figsize=(10, 6))
88
        data.plot(kind='bar', ax=ax)
89
        plt.savefig('chart.png')
90
        charts.append('chart.png')
91
        return charts
92

93
    def generate_report(self, stats: Dict[str, Any], charts: List[str]) -> str:
94
        """生成报告"""
95
        report = f"# 数据分析报告\n\n"
96
        report += f"## 统计摘要\n\n"
97
        report += f"- 数据量：{stats['count']}\n"
98
        report += f"- 平均值：{stats['mean']}\n"
99
        report += f"- 标准差：{stats['std']}\n"
100
        report += f"\n## 图表\n\n"
101
        for chart in charts:
102
            report += f"![图表]({chart})\n\n"
103
        return report

config.yaml 文件#

配置示例：

PRTCL // YAML

1
name: "data-analysis"
2
version: "2.1.0"
3
author: "Data Team"
4

5
# 功能配置
6
features:
7
  data_loading: true
8
  data_cleaning: true
9
  statistical_analysis: true
10
  data_visualization: true
11
  report_generation: true
12

13
# 性能配置
14
performance:
15
  max_rows: 1000
16
  max_file_size: 104857600  # 100MB
17
  cache_enabled: true
18
  cache_ttl: 3600
19

20
# 输出配置
21
output:
22
  format: "markdown"
23
  include_charts: true
24
  include_stats: true
25

26
# 权限配置
27
permissions:
28
  read: true
29
  write: true
30
  network: false

创建自定义技能#

创建技能目录#

步骤：

PRTCL // BASH

1
# 创建技能目录
2
mkdir -p ~/.copaw/workspace/skills/customized/my-skill
3

4
# 进入技能目录
5
cd ~/.copaw/workspace/skills/customized/my-skill

创建 SKILL.md#

示例：

PRTCL // MARKDOWN

1
# 我的自定义技能
2

3
## 描述
4
这是一个示例自定义技能，用于演示如何创建 CoPaw 技能。
5

6
## 版本
7
1.0.0
8

9
## 作者
10
Your Name
11

12
## 依赖
13
- requests >= 2.25.0
14

15
## 配置
16
```yaml
17
api_url: "https://api.example.com"
18
timeout: 30

使用方法#

PRTCL // PLAINTEXT

1
用户：执行我的技能
2
CoPaw：[调用我的技能] 执行完成

PRTCL // PLAINTEXT

1
### 创建 main.py
2

3
** 示例 **：
4
```python
5
# main.py
6
import requests
7
from typing import Dict, Any
8
from copaw.skills import Skill
9

10
class MySkill(Skill):
11
    """我的自定义技能"""
12

13
    def __init__(self, config: Dict[str, Any]):
14
        super().__init__(config)
15
        self.api_url = config.get('api_url', 'https://api.example.com')
16
        self.timeout = config.get('timeout', 30)
17

18
    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
19
        """执行技能"""
20
        try:
21
            # 调用 API
22
            response = requests.get(
23
                self.api_url,
24
                params=input_data,
25
                timeout=self.timeout
26
            )
27

28
            # 处理响应
29
            result = response.json()
30

31
            return {
32
                'success': True,
33
                'result': result
34
            }
35
        except Exception as e:
36
            return {
37
                'success': False,
38
                'error': str(e)
39
            }

创建 config.yaml#

示例：

PRTCL // YAML

1
name: "my-skill"
2
version: "1.0.0"
3
author: "Your Name"
4

5
# API 配置
6
api:
7
  url: "https://api.example.com"
8
  timeout: 30
9
  retry: 3
10

11
# 功能配置
12
features:
13
  feature1: true
14
  feature2: false

安装和测试技能#

安装技能：

PRTCL // BASH

1
# 安装技能
2
copaw skills install ~/.copaw/workspace/skills/customized/my-skill
3

4
# 激活技能
5
copaw skills activate my-skill

测试技能：

PRTCL // BASH

1
# 测试技能
2
copaw skills test my-skill
3

4
# 测试技能功能
5
echo '{"param1": "value1"}' | copaw skills run my-skill

技能开发最佳实践#

技能设计原则#

单一职责：

每个技能只做一件事
保持简单和专注
便于维护和测试

可组合性：

技能可以组合使用
提供清晰的接口
支持管道操作

可扩展性：

易于添加新功能
支持配置扩展
预留扩展点

错误处理#

基础错误处理：

PRTCL // PYTHON

1
def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
2
    """执行技能"""
3
    try:
4
        result = self.process(input_data)
5
        return {
6
            'success': True,
7
            'result': result
8
        }
9
    except Exception as e:
10
        return {
11
            'success': False,
12
            'error': str(e),
13
            'error_type': type(e).__name__
14
        }

高级错误处理：

PRTCL // PYTHON

1
import logging
2
from typing import Dict, Any
3

4
class MySkill(Skill):
5
    """我的自定义技能"""
6

7
    def __init__(self, config: Dict[str, Any]):
8
        super().__init__(config)
9
        self.logger = logging.getLogger(__name__)
10

11
    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
12
        """执行技能"""
13
        try:
14
            # 验证输入
15
            self.validate_input(input_data)
16

17
            # 处理数据
18
            result = self.process(input_data)
19

20
            # 验证输出
21
            self.validate_output(result)
22

23
            return {
24
                'success': True,
25
                'result': result
26
            }
27
        except ValueError as e:
28
            self.logger.error(f"验证错误: {e}")
29
            return {
30
                'success': False,
31
                'error': str(e),
32
                'error_type': 'ValidationError'
33
            }
34
        except RuntimeError as e:
35
            self.logger.error(f"运行时错误: {e}")
36
            return {
37
                'success': False,
38
                'error': str(e),
39
                'error_type': 'RuntimeError'
40
            }
41
        except Exception as e:
42
            self.logger.error(f"未知错误: {e}")
43
            return {
44
                'success': False,
45
                'error': str(e),
46
                'error_type': 'UnknownError'
47
            }
48

49
    def validate_input(self, input_data: Dict[str, Any]) -> None:
50
        """验证输入"""
51
        if not isinstance(input_data, dict):
52
            raise ValueError("输入必须是字典")
53
        # 更多验证逻辑
54

55
    def validate_output(self, output: Any) -> None:
56
        """验证输出"""
57
        if output is None:
58
            raise ValueError("输出不能为空")
59
        # 更多验证逻辑

性能优化#

缓存机制：

PRTCL // PYTHON

1
from functools import lru_cache
2
import hashlib
3
import json
4

5
class MySkill(Skill):
6
    """我的自定义技能"""
7

8
    def __init__(self, config: Dict[str, Any]):
9
        super().__init__(config)
10
        self.cache_enabled = config.get('cache_enabled', True)
11
        self.cache_ttl = config.get('cache_ttl', 3600)
12
        self.cache = {}
13

14
    def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
15
        """执行技能"""
16
        # 生成缓存键
17
        cache_key = self.generate_cache_key(input_data)
18

19
        # 检查缓存
20
        if self.cache_enabled and cache_key in self.cache:
21
            cached_result, cached_time = self.cache[cache_key]
22
            if time.time() - cached_time < self.cache_ttl:
23
                return cached_result
24

25
        # 处理数据
26
        result = self.process(input_data)
27

28
        # 更新缓存
29
        if self.cache_enabled:
30
            self.cache[cache_key] = (result, time.time())
31

32
        return result
33

34
    def generate_cache_key(self, input_data: Dict[str, Any]) -> str:
35
        """生成缓存键"""
36
        data_str = json.dumps(input_data, sort_keys=True)
37
        return hashlib.md5(data_str.encode()).hexdigest()

批处理：

PRTCL // PYTHON

1
def process_batch(self, inputs: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
2
    """批处理"""
3
    results = []
4
    for input_data in inputs:
5
        try:
6
            result = self.execute(input_data)
7
            results.append(result)
8
        except Exception as e:
9
            results.append({
10
                'success': False,
11
                'error': str(e)
12
            })
13
    return results

技能发布和共享#

打包技能#

创建 setup.py：

PRTCL // PYTHON

1
from setuptools import setup, find_packages
2

3
setup(
4
    name="copaw-my-skill",
5
    version="1.0.0",
6
    packages=find_packages(),
7
    install_requires=[
8
        "copaw>=1.0.0",
9
        "requests>=2.25.0",
10
    ],
11
    author="Your Name",
12
    description="My CoPaw Skill",
13
    python_requires=">=3.10",
14
)

打包技能：

PRTCL // BASH

1
# 构建 distribution
2
python setup.py sdist bdist_wheel
3

4
# 安装本地包
5
pip install dist/copaw_my_skill-1.0.0-py3-none-any.whl

发布到 PyPI#

注册 PyPI 账户：

访问 https://pypi.org/
注册账户
创建 API Token

发布技能：

PRTCL // BASH

1
# 安装发布工具
2
pip install twine
3

4
# 发布到 PyPI
5
twine upload dist/*
6

7
# 或发布到 TestPyPI
8
twine upload --repository testpypi dist/*

共享技能#

Git 仓库：

PRTCL // BASH

1
# 创建 Git 仓库
2
git init
3
git add .
4
git commit -m "Initial commit"
5

6
# 推送到 GitHub
7
git remote add origin https://github.com/yourusername/copaw-my-skill.git
8
git push -u origin main

通过 URL 安装：

PRTCL // BASH

1
# 从 Git 仓库安装
2
copaw skills install git+https://github.com/yourusername/copaw-my-skill.git

常见问题#

Q1: 技能无法加载？#

解决方案：

PRTCL // BASH

1
# 检查技能配置
2
copaw skills validate my-skill
3

4
# 查看技能日志
5
copaw logs | grep my-skill
6

7
# 重新加载技能
8
copaw skills reload my-skill

Q2: 技能执行失败？#

解决方案：

PRTCL // BASH

1
# 查看技能详情
2
copaw skills info my-skill
3

4
# 检查技能依赖
5
copaw skills dependencies my-skill
6

7
# 测试技能
8
copaw skills test my-skill

Q3: 如何调试技能？#

解决方案：

PRTCL // PYTHON

1
# 启用调试日志
2
import logging
3
logging.basicConfig(level=logging.DEBUG)
4

5
# 添加调试信息
6
self.logger.debug(f"输入数据: {input_data}")
7
self.logger.debug(f"处理结果: {result}")

资源链接#

CoPaw 技能文档: https://copaw.bot/docs/skills
技能示例: https://github.com/modelscope/agentscope/tree/main/skills
技能开发指南: https://copaw.bot/docs/skills/development

最后更新: 2026-03-12 作者: EchoHaoRan

CoPaw 技能系统详解#

概述#

技能系统概述#

什么是技能#

技能类型#

技能目录结构#

技能管理#

技能 CLI 命令#

技能搜索#

技能信息#

技能结构#

SKILL.md 文件#

使用方法#

示例#

功能#

使用方法#

示例#

权限#

限制#

config.yaml 文件#

创建自定义技能#

创建技能目录#

创建 SKILL.md#

使用方法#

创建 config.yaml#

安装和测试技能#

技能开发最佳实践#

技能设计原则#

错误处理#

性能优化#

技能发布和共享#

打包技能#

发布到 PyPI#

共享技能#

常见问题#

Q1: 技能无法加载？#

Q2: 技能执行失败？#

Q3: 如何调试技能？#

资源链接#

CoPaw技能系统详解

CoPaw Agent架构详解

CoPaw记忆系统使用指南

CoPaw常见问题解答

CoPaw快速入门教程

评论