OpenCode Skill 入门指南：从零开始构建你的第一个技能插件

共计 2098 个字符，预计需要花费 6 分钟才能阅读完成。

什么是 OpenCode Skill？

OpenCode Skill 是一种可扩展的技能插件框架，允许开发者创建能够响应特定指令或事件的功能模块。简单来说，就像给你的应用程序安装一个 ” 小助手 ”，当用户发出特定指令时，这个小助手就会执行相应的操作。

工作原理

1. 用户发出指令或触发事件
2. OpenCode 平台接收并解析指令
3. 找到匹配的 Skill
4. Skill 处理请求并返回响应
5. 平台将响应呈现给用户

典型应用场景

• 语音助手功能扩展
• 聊天机器人技能
• 自动化任务处理
• 信息查询服务

开发环境配置

在开始开发之前，我们需要准备好开发环境。以下是详细步骤：

1. 安装 Python 3.8 或更高版本
2. 创建虚拟环境（推荐）：

   python -m venv skill_env
   source skill_env/bin/activate  # Linux/Mac
   skill_env\Scripts\activate    # Windows

3. 安装 OpenCode SDK：

   pip install opencode-sdk

4. 安装代码编辑器（推荐 VS Code 或 PyCharm）

天气预报技能开发实战

让我们通过一个实际的天气预报技能来学习 OpenCode Skill 开发的全流程。

项目结构

一个基本的 Skill 包含以下文件：

weather_skill/
├── __init__.py
├── manifest.json
├── skill.py
└── requirements.txt

编写核心代码

以下是 skill.py 的完整实现（使用 Python 3.x）：

# -*- coding: utf-8 -*-
"""天气预报技能示例"""
from opencode.skill import Skill
from opencode.types import Request, Response

class WeatherSkill(Skill):
    """处理天气查询请求"""

    def __init__(self):
        super().__init__(name="weather_skill")

    def handle_request(self, request: Request) -> Response:
        """处理天气查询请求"""
        # 解析用户请求中的城市参数
        city = request.params.get("city", "北京")

        # 这里应该是调用天气 API 的代码
        # 为了示例简化，我们使用模拟数据
        weather_data = {
            "city": city,
            "temperature": "22℃",
            "condition": "晴天",
            "humidity": "45%"
        }

        # 构建响应消息
        message = (f"{city} 的天气情况：\n"
            f"温度：{weather_data['temperature']}\n"
            f"天气：{weather_data['condition']}\n"
            f"湿度：{weather_data['humidity']}"
        )

        return Response(
            text=message,
            data=weather_data
        )

manifest.json 配置

{
  "name": "weather_skill",
  "version": "1.0.0",
  "description": "查询城市天气信息",
  "author": "Your Name",
  "triggers": [
    {
      "type": "command",
      "patterns": ["查询天气", "{city} 天气"]
    }
  ],
  "permissions": ["network"]
}

避坑指南

新手开发时容易遇到以下问题：

1. 忘记在 manifest.json 中声明权限
2. 症状：技能无法访问网络或其他资源

3. 解决：在 permissions 中添加所需权限

4. 未正确处理请求参数

5. 症状：技能崩溃或返回错误结果

6. 解决：总是检查参数是否存在，并提供默认值

7. 响应格式不符合要求

8. 症状：平台无法解析响应

9. 解决：确保返回的 Response 对象格式正确

10. 技能启动失败

11. 症状：技能无法加载
12. 解决：检查 __init__.py 是否存在，并正确导出技能类

部署与测试

本地测试

1. 安装开发工具包：

   pip install opencode-dev-tools

2. 启动测试服务器：

   opencode-dev --skill-dir ./weather_skill

3. 在浏览器打开 http://localhost:8080 进行测试

部署到生产环境

1. 打包技能：

   zip -r weather_skill.zip weather_skill/

2. 上传到 OpenCode 开发者平台

3. 在控制台启用技能

进阶思考

为了帮助你进一步提升技能开发水平，可以尝试以下挑战：

1. 如何实现多语言支持，让技能能根据用户偏好返回不同语言的响应？
2. 如果要添加天气预报的图标显示功能，应该如何扩展响应格式？
3. 如何实现技能的配置界面，让用户可以设置默认城市？

通过这个简单的天气预报技能，我们已经掌握了 OpenCode Skill 开发的基本流程。虽然示例比较简单，但包含了技能开发的核心概念和关键步骤。接下来，你可以尝试开发更复杂的功能，比如集成真实的天气 API，或者添加更多交互功能。

记住，好的技能应该专注于解决特定问题，保持简单易用。在开发过程中，多思考用户会如何使用你的技能，这样才能创造出真正有价值的功能。