1. 项目概述从零开始构建你的专属技能最近在折腾一些自动化流程发现很多重复性的查询和操作其实可以封装成更便捷的“技能”就像给一个智能助手增加新的能力模块。OpenCode Skills这个概念简单来说就是一种允许开发者或有一定技术基础的用户通过编写特定格式的代码或配置来扩展一个系统核心功能的方法。它不同于简单的脚本而是一种结构化的、可复用、可分享的“能力包”。想象一下你每天需要从十几个不同的数据源汇总信息手动操作繁琐且易错。如果有一个自定义技能你只需要输入一个指令它就能自动完成数据抓取、清洗、整合并生成报告这效率提升是巨大的。这个项目适合谁呢首先它面向有一定编程基础比如熟悉Python或JavaScript的开发者、运维工程师或技术爱好者。其次也适合那些业务中有固定流程希望将其自动化、智能化的团队负责人或产品经理。即使你不是资深程序员但只要能看懂基础代码逻辑按照步骤也能成功创建出实用的技能。本指南将带你从理解技能的基本结构开始一步步完成环境搭建、代码编写、测试调试直到最终部署和分享。我们会避开那些华而不实的理论直接切入最核心的实操环节分享我在构建几十个自定义技能过程中踩过的坑和总结出的最佳实践。2. 技能架构设计与核心思路拆解在动手写代码之前我们必须先搞清楚一个自定义技能到底由哪些部分组成以及它们是如何协同工作的。这就像盖房子先画图纸能避免后期返工。2.1 技能的核心组件与数据流一个典型的OpenCode Skill通常包含以下几个核心部分技能描述文件Manifest这是一个JSON或YAML格式的配置文件是技能的“身份证”和“说明书”。它定义了技能的基本元信息例如技能的唯一标识符ID、名称、版本、作者、描述以及最关键的部分——技能的触发指令Invocation Phrase和权限声明Permissions。触发指令就是用户用来激活这个技能的关键词或短语。权限声明则告诉系统这个技能需要访问哪些资源比如读取用户文件、调用外部API、发送网络请求等。没有正确的权限声明技能在运行时会被系统安全机制拦截。核心逻辑处理器Handler这是技能的大脑包含了主要的业务逻辑代码。当用户的指令匹配到技能的触发短语后系统会将用户的输入可能包含参数传递给这个处理器。处理器负责解析输入、执行计算、调用外部服务、处理数据并最终生成返回给用户的响应。这部分通常用Python、Node.js等语言编写取决于技能运行时的支持环境。依赖管理文件例如Python的requirements.txt或Node.js的package.json。它列出了技能运行所必需的所有第三方库。这确保了技能在任何兼容的环境中被部署时都能获得一致的功能。静态资源可选部分。包括技能图标、说明文档、示例数据或本地配置文件等。数据流的逻辑是这样的用户发出指令 - 系统解析指令匹配到某个技能的触发短语 - 系统加载该技能的Manifest文件检查权限 - 系统初始化技能运行环境安装依赖 - 将用户输入传入核心处理器Handler- 处理器执行逻辑可能调用外部API或处理内部数据 - 处理器生成文本、数据或结构化响应 - 系统将响应格式化后呈现给用户。2.2 方案选型轻量脚本 vs. 容器化部署在实现技能时我们面临一个基础架构选择是写成轻量级脚本还是采用容器化部署这取决于技能的复杂度和性能要求。对于绝大多数查询类、信息处理类、简单自动化类的技能轻量脚本模式是首选。它的优点是开发速度快、资源消耗低、部署简单。技能代码直接运行在系统提供的沙箱环境中你只需要关心业务逻辑。我早期的大部分技能都采用这种模式非常适合快速验证想法。然而如果你的技能涉及复杂的机器学习模型、需要常驻内存的大数据计算、或者对运行环境有特殊依赖比如特定版本的系统库那么容器化部署就更合适。你可以将技能及其完整运行环境打包成一个Docker镜像。这样技能在任何支持容器的平台上都能以完全一致的方式运行隔离性好但也带来了镜像构建、存储和启动开销的增加。注意对于新手我强烈建议从轻量脚本模式开始。它让你能更专注于技能逻辑本身而不是基础设施。本指南也将主要围绕这种模式展开。当你需要处理更复杂的场景时再考虑向容器化迁移那时你已有足够经验来应对额外的复杂度。3. 开发环境准备与工具链配置工欲善其事必先利其器。一个顺畅的开发环境能极大提升效率减少不必要的干扰。3.1 基础运行环境搭建首先你需要确保本地有一个代码编辑器或集成开发环境IDE。Visual Studio Code (VSCode) 是目前最流行的选择它轻量、免费并且拥有海量插件能完美支持后续的步骤。当然如果你习惯使用PyCharm、Sublime Text或Vim也完全没问题。接下来是运行时环境。由于大多数技能逻辑使用Python编写你需要安装Python。建议使用Python 3.8或以上版本这是目前主流库广泛支持的版本。为了避免不同项目间的依赖冲突强烈建议使用虚拟环境。这里我推荐使用venvPython内置或conda。使用venv创建虚拟环境的步骤如下# 在你的项目目录下 python -m venv skill_env # 激活虚拟环境 (Windows) skill_env\Scripts\activate # 激活虚拟环境 (macOS/Linux) source skill_env/bin/activate激活后你的命令行提示符前会出现(skill_env)字样表示你已进入该虚拟环境所有后续的pip install操作都只会影响这个环境。3.2 核心SDK与调试工具安装OpenCode通常会提供一个官方的软件开发工具包SDK它封装了与系统交互的常用函数比如接收输入、发送输出、记录日志、管理状态等。假设这个SDK包名为opencode-sdk你可以通过pip安装pip install opencode-sdk安装后最好再安装一些开发辅助工具Black代码格式化工具让代码风格保持一致。Pylint或Flake8代码静态检查工具帮助发现潜在的错误和不规范的写法。pytest单元测试框架用于编写和运行技能的自动化测试。你可以一次性安装它们pip install black pylint pytest此外为了模拟技能运行环境进行本地调试OpenCode可能还提供了一个本地测试工具或模拟器。这个工具至关重要它允许你在不真正部署到生产环境的情况下测试技能的完整流程。请务必查阅官方文档找到并安装这个测试工具。通常它可能是一个命令行工具比如opencode-cli。4. 创建你的第一个技能从Manifest开始让我们从一个最简单的“Hello World”式技能开始熟悉整个创建流程。这个技能的功能是当用户说“打个招呼”时它随机回复一句问候语。4.1 编写技能清单manifest.json在你的项目根目录例如my_greeting_skill下创建一个名为manifest.json的文件。这是技能的入口点。{ skill_id: com.example.my_greeting_skill, version: 1.0.0, name: 随机问候技能, author: 你的名字, description: 一个简单的演示技能随机返回不同的问候语。, invocation_phrase: 打个招呼, permissions: [], handler: main.handler }关键字段解析skill_id技能的全局唯一标识符通常采用反向域名格式确保不会与他人冲突。invocation_phrase用户用来唤醒技能的短语。这里设置为“打个招呼”。在实际使用中用户可能需要说“让[技能名]打个招呼”或直接说“打个招呼”具体语法取决于系统设计但核心触发词是这个短语。permissions权限数组。由于这个技能不访问网络、文件或任何外部资源所以留空。如果需要网络请求这里可能需要加入network等。handler指定核心逻辑代码的位置。main.handler表示在main.py文件中有一个名为handler的函数。4.2 实现核心逻辑main.py在同一个目录下创建main.py文件。import random from opencode_sdk.skill import Skill, Request, Response # 初始化技能对象 app Skill() # 定义问候语库 GREETINGS [ 你好今天天气真不错。, 嗨很高兴见到你, 欢迎回来有什么可以帮你的吗, 向你致以诚挚的问候, 嘿朋友一切顺利吗 ] app.handle(intentgreet) # 关联到一个意图与manifest中的invocation_phrase对应 def handler(request: Request) - Response: 处理打招呼请求。 request对象中包含用户的输入等信息。 # 从问候语库中随机选择一条 selected_greeting random.choice(GREETINGS) # 构建并返回响应 response Response( textselected_greeting, # 返回的文本内容 # 可以附加更多数据例如卡片、建议操作等 ) return response # 将handler函数暴露出来供manifest.json引用 handler app.handler代码逻辑解读我们从SDK中导入必要的类Skill技能基类、Request请求对象、Response响应对象。创建一个Skill实例app。定义一个装饰器app.handle(intentgreet)将下面的handler函数注册为处理“greet”意图的处理器。这个意图需要与后续的配置或系统识别逻辑关联在更复杂的技能中意图管理会更精细。在handler函数内部我们从预定义的列表中随机选取一条问候语。用选中的问候语创建一个Response对象并返回。最后将app.handler赋值给模块级的handler变量这样manifest.json中指定的main.handler就能正确找到这个入口函数。实操心得在编写handler函数时务必做好异常处理。例如如果技能需要调用一个可能失败的外部API一定要用try...except包裹并返回友好的错误提示如“抱歉服务暂时不可用请稍后再试。”而不是让技能崩溃。良好的错误处理是生产级技能的基本素养。5. 本地测试与调试技巧实录代码写完了但在部署前必须在本地充分测试。这是保证技能质量、节省后期排查时间的关键步骤。5.1 使用模拟器进行端到端测试假设你已安装了本地测试工具opencode-cli。在项目根目录下运行模拟测试# 启动本地技能服务器 opencode-cli serve --manifest ./manifest.json # 在另一个终端窗口模拟用户请求 opencode-cli invoke --phrase 打个招呼你应该能看到终端输出随机的一条问候语。多运行几次invoke命令确认问候语是随机变化的。这个模拟器通常会启动一个本地HTTP服务器你的技能代码运行在其中。invoke命令会向这个服务器发送一个结构化的请求模拟真实环境下的调用。这是最接近真实环境的测试方法。5.2 单元测试与集成测试对于逻辑更复杂的技能需要编写自动化测试。使用pytest为你的核心函数编写单元测试。在项目根目录创建tests文件夹并在其中新建test_main.pyimport sys import os sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), ..))) from main import handler from opencode_sdk.skill import Request import json def test_handler_returns_greeting(): # 创建一个模拟的Request对象 # 实际SDK中Request的构造可能需要更多参数请参考SDK文档 mock_request Request(intentgreet, text打个招呼) # 调用handler response handler(mock_request) # 断言响应不为空且是Response类型 assert response is not None assert hasattr(response, text) # 断言返回的文本在我们预定义的问候语列表中 from main import GREETINGS assert response.text in GREETINGS def test_handler_structure(): mock_request Request(intentgreet, text) response handler(mock_request) # 检查响应结构是否包含必要的字段根据你的SDK定义调整 assert isinstance(response.text, str) # 可以检查其他字段如 response.card, response.suggestions 等然后在项目根目录运行pytest来执行测试。良好的测试覆盖率能让你在修改代码时更有信心。5.3 日志记录与问题排查在技能代码中添加详细的日志是线上调试的“眼睛”。使用SDK提供的日志接口或Python标准的logging模块。import logging logger logging.getLogger(__name__) def handler(request): logger.info(f收到请求意图: {request.intent}, 原始文本: {request.text}) try: # ... 你的业务逻辑 ... result do_something() logger.debug(f业务逻辑执行结果: {result}) return Response(textresult) except Exception as e: logger.error(f处理请求时发生错误: {e}, exc_infoTrue) return Response(text处理您的请求时出了点问题请稍后再试。)在本地测试时确保日志级别设置正确如DEBUG以便看到所有详细信息。在生产环境可能只记录INFO及以上级别。通过日志你可以清晰地看到请求处理的每一步当技能行为不符合预期时能快速定位问题所在。6. 技能打包、发布与版本管理测试通过后就可以准备发布了。6.1 项目打包与依赖锁定首先生成准确的依赖列表。在激活的虚拟环境中运行pip freeze requirements.txt检查生成的requirements.txt确保只包含技能直接依赖的包移除不必要的或开发专用的包如pytest,black。一个干净的依赖列表能减少技能包体积和潜在的冲突。接下来将整个技能目录打包。通常你需要打包以下文件manifest.jsonmain.py(以及你其他的.py文件)requirements.txt其他必要的资源文件如图标、数据文件避免将虚拟环境文件夹skill_env/、__pycache__/、.git/等目录打包进去。你可以创建一个.gitignore文件来管理这些。6.2 发布到技能平台不同的OpenCode平台有不同的发布方式。常见的有两种命令行工具发布使用平台提供的CLI工具例如opencode-cli publish --package ./my_skill.zip。网页控制台上传在平台的开发者后台提供一个压缩包上传接口。无论哪种方式通常都需要你事先在平台上注册为开发者并可能创建一个“技能”应用来获取相关的API密钥或配置。上传后平台会对你的技能包进行静态分析、安全扫描并可能要求你填写更详细的上架信息如分类、标签、长描述、隐私政策链接等。6.3 版本迭代与更新技能发布后难免需要修复Bug或增加新功能。务必通过更新版本号来管理迭代。在manifest.json中修改version字段遵循 语义化版本规范 是一个好习惯主版本号Major做了不兼容的 API 修改。次版本号Minor向下兼容的功能性新增。修订号Patch向下兼容的问题修正。例如从1.0.0修复一个Bug升级到1.0.1新增一个功能升级到1.1.0。每次更新代码后重复测试、打包、发布的流程。平台通常会保留旧版本以便在出现严重问题时可以快速回滚。清晰的版本更新日志可以在manifest的description或单独的文件中说明对用户和平台审核者都非常友好。7. 进阶技能开发处理复杂输入与状态管理基础技能只能处理简单指令。现实中的需求往往更复杂需要解析用户输入中的参数甚至在不同对话轮次中记住上下文。7.1 解析用户指令与参数提取用户的指令可能包含变量。例如一个查询天气的技能用户可能说“查询北京今天天气”或“上海明天温度怎么样”。我们需要从中提取“城市”和“时间”两个参数。这通常通过“意图识别Intent Recognition”和“实体抽取Entity Extraction”来完成。在简单的技能中我们可以使用正则表达式或简单的字符串匹配来模拟。更复杂的可以使用NLU自然语言理解库但初期建议从规则开始。假设我们的技能触发短语是“查询天气”我们可以这样处理import re app.handle(intentquery_weather) def handler(request): user_text request.text # 用户完整的输入文本如“查询北京今天天气” # 使用正则表达式提取城市和日期 city_pattern r查询(.?)(?:今天|明天|后天|的天气) date_pattern r(今天|明天|后天) city_match re.search(city_pattern, user_text) date_match re.search(date_pattern, user_text) city city_match.group(1).strip() if city_match else 北京 # 默认城市 date date_match.group(1) if date_match else 今天 # 默认今天 # 根据city和date调用天气API # weather_info get_weather_from_api(city, date) weather_info f{date}{city}的天气是晴25度。 # 模拟数据 return Response(textweather_info)这种方式比较原始但对固定格式的指令有效。对于更自由的表达需要考虑使用更强大的NLP工具。7.2 会话状态管理与多轮对话有些技能需要多轮交互。比如一个点餐技能第一轮问“您想点什么”用户回答“披萨”第二轮再问“您要什么口味的”。这就需要技能能记住上下文。OpenCode SDK通常会提供会话状态Session存储。状态可以存储在内存中仅限当前对话或者持久化到数据库中跨对话。from opencode_sdk.skill import Skill, Request, Response from opencode_sdk.session import Session app Skill() app.handle(intentorder_food) def handler(request: Request, session: Session): # 从会话状态中读取点餐进度 order_stage session.get(order_stage, start) # 默认为开始阶段 selected_food session.get(selected_food) if order_stage start: # 第一阶段询问食物类型 session.set(order_stage, select_flavor) return Response(text您想点什么披萨、汉堡还是沙拉, suggestions[披萨, 汉堡, 沙拉]) elif order_stage select_flavor and not selected_food: # 用户刚刚回答了食物类型我们存下来并进入下一阶段 user_choice request.text # 例如“披萨” session.set(selected_food, user_choice) session.set(order_stage, confirm) return Response(textf好的{user_choice}。您要什么口味的, suggestions[海鲜, 牛肉, 蔬菜]) elif order_stage confirm: # 用户回答了口味完成订单 flavor request.text food session.get(selected_food) # 清空或结束会话状态 session.clear() return Response(textf订单确认{flavor}口味的{food}。感谢下单) else: # 处理意外情况 session.clear() return Response(text对话出现异常已重置。请重新开始点餐。)在这个例子中Session对象允许我们在同一用户与技能的多次交互中保存和读取数据。suggestions字段用于在响应中提供快速回复选项提升用户体验。管理好会话的生命周期何时创建、更新、清除是设计多轮对话技能的关键。8. 性能优化与安全考量当技能被大量用户使用时性能和安全性就成为不可忽视的问题。8.1 技能性能优化要点冷启动优化技能在闲置一段时间后首次被调用可能会有一个加载延迟冷启动。为了减少这个时间精简依赖只引入绝对必要的第三方库。定期检查requirements.txt移除未使用的包。延迟加载对于耗时的初始化操作如加载大型模型可以考虑在handler函数被首次调用时才执行而不是在技能加载时。代码精简避免在全局作用域执行复杂计算或进行大量I/O操作。处理耗时操作如果技能需要调用一个响应很慢的外部API比如超过3秒不要让它阻塞主线程。可以考虑异步处理如果技能运行时支持异步IO如Python的asyncio使用异步函数来调用API。快速响应后台任务先立即返回一个“正在处理请稍候”的响应然后通过后台任务或消息队列去执行耗时操作并通过其他方式如推送通知将最终结果告知用户。这需要平台支持更高级的交互模式。缓存策略对于频繁查询且结果变化不频繁的数据如城市列表、产品目录、某些静态信息使用缓存可以极大提升响应速度并降低外部API调用次数。可以使用内存缓存如functools.lru_cache或外部缓存服务如Redis根据技能部署环境决定。8.2 安全开发实践输入验证与清理永远不要信任用户的输入。对所有从request.text或参数中获取的数据进行严格的验证和清理防止注入攻击如SQL注入、命令注入。import re def validate_city_name(city: str) - bool: # 只允许中英文、数字和常见符号 pattern r^[\w\u4e00-\u9fa5\s\-\.]$ return bool(re.match(pattern, city)) and len(city) 50安全地调用外部API如果技能需要调用外部服务使用环境变量管理密钥绝对不要将API密钥、令牌等敏感信息硬编码在代码中。使用平台提供的秘密管理功能或环境变量来存储。HTTPS确保所有外部调用都使用HTTPS协议。限制权限在manifest.json的permissions中只申请技能运行所必需的最小权限。错误信息脱敏当技能内部发生错误时返回给用户的错误信息应该是友好且通用的避免泄露系统内部细节、堆栈跟踪或数据库结构。try: result call_sensitive_operation() except Exception: # 记录详细的错误到日志供开发者排查 logger.exception(敏感操作失败) # 返回给用户模糊的信息 return Response(text服务暂时不可用请稍后再试。)依赖库安全定期更新requirements.txt中的依赖库版本以修复已知的安全漏洞。可以使用工具如safety或pip-audit来扫描项目依赖。遵循这些性能和安全实践能帮助你构建出既高效又可靠的技能赢得用户的长期信任。技能开发是一个持续迭代的过程从简单的“Hello World”开始逐步增加复杂度处理好每一个细节你就能创造出真正有价值的自动化工具。
从零构建OpenCode技能：自动化流程开发实战指南
1. 项目概述从零开始构建你的专属技能最近在折腾一些自动化流程发现很多重复性的查询和操作其实可以封装成更便捷的“技能”就像给一个智能助手增加新的能力模块。OpenCode Skills这个概念简单来说就是一种允许开发者或有一定技术基础的用户通过编写特定格式的代码或配置来扩展一个系统核心功能的方法。它不同于简单的脚本而是一种结构化的、可复用、可分享的“能力包”。想象一下你每天需要从十几个不同的数据源汇总信息手动操作繁琐且易错。如果有一个自定义技能你只需要输入一个指令它就能自动完成数据抓取、清洗、整合并生成报告这效率提升是巨大的。这个项目适合谁呢首先它面向有一定编程基础比如熟悉Python或JavaScript的开发者、运维工程师或技术爱好者。其次也适合那些业务中有固定流程希望将其自动化、智能化的团队负责人或产品经理。即使你不是资深程序员但只要能看懂基础代码逻辑按照步骤也能成功创建出实用的技能。本指南将带你从理解技能的基本结构开始一步步完成环境搭建、代码编写、测试调试直到最终部署和分享。我们会避开那些华而不实的理论直接切入最核心的实操环节分享我在构建几十个自定义技能过程中踩过的坑和总结出的最佳实践。2. 技能架构设计与核心思路拆解在动手写代码之前我们必须先搞清楚一个自定义技能到底由哪些部分组成以及它们是如何协同工作的。这就像盖房子先画图纸能避免后期返工。2.1 技能的核心组件与数据流一个典型的OpenCode Skill通常包含以下几个核心部分技能描述文件Manifest这是一个JSON或YAML格式的配置文件是技能的“身份证”和“说明书”。它定义了技能的基本元信息例如技能的唯一标识符ID、名称、版本、作者、描述以及最关键的部分——技能的触发指令Invocation Phrase和权限声明Permissions。触发指令就是用户用来激活这个技能的关键词或短语。权限声明则告诉系统这个技能需要访问哪些资源比如读取用户文件、调用外部API、发送网络请求等。没有正确的权限声明技能在运行时会被系统安全机制拦截。核心逻辑处理器Handler这是技能的大脑包含了主要的业务逻辑代码。当用户的指令匹配到技能的触发短语后系统会将用户的输入可能包含参数传递给这个处理器。处理器负责解析输入、执行计算、调用外部服务、处理数据并最终生成返回给用户的响应。这部分通常用Python、Node.js等语言编写取决于技能运行时的支持环境。依赖管理文件例如Python的requirements.txt或Node.js的package.json。它列出了技能运行所必需的所有第三方库。这确保了技能在任何兼容的环境中被部署时都能获得一致的功能。静态资源可选部分。包括技能图标、说明文档、示例数据或本地配置文件等。数据流的逻辑是这样的用户发出指令 - 系统解析指令匹配到某个技能的触发短语 - 系统加载该技能的Manifest文件检查权限 - 系统初始化技能运行环境安装依赖 - 将用户输入传入核心处理器Handler- 处理器执行逻辑可能调用外部API或处理内部数据 - 处理器生成文本、数据或结构化响应 - 系统将响应格式化后呈现给用户。2.2 方案选型轻量脚本 vs. 容器化部署在实现技能时我们面临一个基础架构选择是写成轻量级脚本还是采用容器化部署这取决于技能的复杂度和性能要求。对于绝大多数查询类、信息处理类、简单自动化类的技能轻量脚本模式是首选。它的优点是开发速度快、资源消耗低、部署简单。技能代码直接运行在系统提供的沙箱环境中你只需要关心业务逻辑。我早期的大部分技能都采用这种模式非常适合快速验证想法。然而如果你的技能涉及复杂的机器学习模型、需要常驻内存的大数据计算、或者对运行环境有特殊依赖比如特定版本的系统库那么容器化部署就更合适。你可以将技能及其完整运行环境打包成一个Docker镜像。这样技能在任何支持容器的平台上都能以完全一致的方式运行隔离性好但也带来了镜像构建、存储和启动开销的增加。注意对于新手我强烈建议从轻量脚本模式开始。它让你能更专注于技能逻辑本身而不是基础设施。本指南也将主要围绕这种模式展开。当你需要处理更复杂的场景时再考虑向容器化迁移那时你已有足够经验来应对额外的复杂度。3. 开发环境准备与工具链配置工欲善其事必先利其器。一个顺畅的开发环境能极大提升效率减少不必要的干扰。3.1 基础运行环境搭建首先你需要确保本地有一个代码编辑器或集成开发环境IDE。Visual Studio Code (VSCode) 是目前最流行的选择它轻量、免费并且拥有海量插件能完美支持后续的步骤。当然如果你习惯使用PyCharm、Sublime Text或Vim也完全没问题。接下来是运行时环境。由于大多数技能逻辑使用Python编写你需要安装Python。建议使用Python 3.8或以上版本这是目前主流库广泛支持的版本。为了避免不同项目间的依赖冲突强烈建议使用虚拟环境。这里我推荐使用venvPython内置或conda。使用venv创建虚拟环境的步骤如下# 在你的项目目录下 python -m venv skill_env # 激活虚拟环境 (Windows) skill_env\Scripts\activate # 激活虚拟环境 (macOS/Linux) source skill_env/bin/activate激活后你的命令行提示符前会出现(skill_env)字样表示你已进入该虚拟环境所有后续的pip install操作都只会影响这个环境。3.2 核心SDK与调试工具安装OpenCode通常会提供一个官方的软件开发工具包SDK它封装了与系统交互的常用函数比如接收输入、发送输出、记录日志、管理状态等。假设这个SDK包名为opencode-sdk你可以通过pip安装pip install opencode-sdk安装后最好再安装一些开发辅助工具Black代码格式化工具让代码风格保持一致。Pylint或Flake8代码静态检查工具帮助发现潜在的错误和不规范的写法。pytest单元测试框架用于编写和运行技能的自动化测试。你可以一次性安装它们pip install black pylint pytest此外为了模拟技能运行环境进行本地调试OpenCode可能还提供了一个本地测试工具或模拟器。这个工具至关重要它允许你在不真正部署到生产环境的情况下测试技能的完整流程。请务必查阅官方文档找到并安装这个测试工具。通常它可能是一个命令行工具比如opencode-cli。4. 创建你的第一个技能从Manifest开始让我们从一个最简单的“Hello World”式技能开始熟悉整个创建流程。这个技能的功能是当用户说“打个招呼”时它随机回复一句问候语。4.1 编写技能清单manifest.json在你的项目根目录例如my_greeting_skill下创建一个名为manifest.json的文件。这是技能的入口点。{ skill_id: com.example.my_greeting_skill, version: 1.0.0, name: 随机问候技能, author: 你的名字, description: 一个简单的演示技能随机返回不同的问候语。, invocation_phrase: 打个招呼, permissions: [], handler: main.handler }关键字段解析skill_id技能的全局唯一标识符通常采用反向域名格式确保不会与他人冲突。invocation_phrase用户用来唤醒技能的短语。这里设置为“打个招呼”。在实际使用中用户可能需要说“让[技能名]打个招呼”或直接说“打个招呼”具体语法取决于系统设计但核心触发词是这个短语。permissions权限数组。由于这个技能不访问网络、文件或任何外部资源所以留空。如果需要网络请求这里可能需要加入network等。handler指定核心逻辑代码的位置。main.handler表示在main.py文件中有一个名为handler的函数。4.2 实现核心逻辑main.py在同一个目录下创建main.py文件。import random from opencode_sdk.skill import Skill, Request, Response # 初始化技能对象 app Skill() # 定义问候语库 GREETINGS [ 你好今天天气真不错。, 嗨很高兴见到你, 欢迎回来有什么可以帮你的吗, 向你致以诚挚的问候, 嘿朋友一切顺利吗 ] app.handle(intentgreet) # 关联到一个意图与manifest中的invocation_phrase对应 def handler(request: Request) - Response: 处理打招呼请求。 request对象中包含用户的输入等信息。 # 从问候语库中随机选择一条 selected_greeting random.choice(GREETINGS) # 构建并返回响应 response Response( textselected_greeting, # 返回的文本内容 # 可以附加更多数据例如卡片、建议操作等 ) return response # 将handler函数暴露出来供manifest.json引用 handler app.handler代码逻辑解读我们从SDK中导入必要的类Skill技能基类、Request请求对象、Response响应对象。创建一个Skill实例app。定义一个装饰器app.handle(intentgreet)将下面的handler函数注册为处理“greet”意图的处理器。这个意图需要与后续的配置或系统识别逻辑关联在更复杂的技能中意图管理会更精细。在handler函数内部我们从预定义的列表中随机选取一条问候语。用选中的问候语创建一个Response对象并返回。最后将app.handler赋值给模块级的handler变量这样manifest.json中指定的main.handler就能正确找到这个入口函数。实操心得在编写handler函数时务必做好异常处理。例如如果技能需要调用一个可能失败的外部API一定要用try...except包裹并返回友好的错误提示如“抱歉服务暂时不可用请稍后再试。”而不是让技能崩溃。良好的错误处理是生产级技能的基本素养。5. 本地测试与调试技巧实录代码写完了但在部署前必须在本地充分测试。这是保证技能质量、节省后期排查时间的关键步骤。5.1 使用模拟器进行端到端测试假设你已安装了本地测试工具opencode-cli。在项目根目录下运行模拟测试# 启动本地技能服务器 opencode-cli serve --manifest ./manifest.json # 在另一个终端窗口模拟用户请求 opencode-cli invoke --phrase 打个招呼你应该能看到终端输出随机的一条问候语。多运行几次invoke命令确认问候语是随机变化的。这个模拟器通常会启动一个本地HTTP服务器你的技能代码运行在其中。invoke命令会向这个服务器发送一个结构化的请求模拟真实环境下的调用。这是最接近真实环境的测试方法。5.2 单元测试与集成测试对于逻辑更复杂的技能需要编写自动化测试。使用pytest为你的核心函数编写单元测试。在项目根目录创建tests文件夹并在其中新建test_main.pyimport sys import os sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), ..))) from main import handler from opencode_sdk.skill import Request import json def test_handler_returns_greeting(): # 创建一个模拟的Request对象 # 实际SDK中Request的构造可能需要更多参数请参考SDK文档 mock_request Request(intentgreet, text打个招呼) # 调用handler response handler(mock_request) # 断言响应不为空且是Response类型 assert response is not None assert hasattr(response, text) # 断言返回的文本在我们预定义的问候语列表中 from main import GREETINGS assert response.text in GREETINGS def test_handler_structure(): mock_request Request(intentgreet, text) response handler(mock_request) # 检查响应结构是否包含必要的字段根据你的SDK定义调整 assert isinstance(response.text, str) # 可以检查其他字段如 response.card, response.suggestions 等然后在项目根目录运行pytest来执行测试。良好的测试覆盖率能让你在修改代码时更有信心。5.3 日志记录与问题排查在技能代码中添加详细的日志是线上调试的“眼睛”。使用SDK提供的日志接口或Python标准的logging模块。import logging logger logging.getLogger(__name__) def handler(request): logger.info(f收到请求意图: {request.intent}, 原始文本: {request.text}) try: # ... 你的业务逻辑 ... result do_something() logger.debug(f业务逻辑执行结果: {result}) return Response(textresult) except Exception as e: logger.error(f处理请求时发生错误: {e}, exc_infoTrue) return Response(text处理您的请求时出了点问题请稍后再试。)在本地测试时确保日志级别设置正确如DEBUG以便看到所有详细信息。在生产环境可能只记录INFO及以上级别。通过日志你可以清晰地看到请求处理的每一步当技能行为不符合预期时能快速定位问题所在。6. 技能打包、发布与版本管理测试通过后就可以准备发布了。6.1 项目打包与依赖锁定首先生成准确的依赖列表。在激活的虚拟环境中运行pip freeze requirements.txt检查生成的requirements.txt确保只包含技能直接依赖的包移除不必要的或开发专用的包如pytest,black。一个干净的依赖列表能减少技能包体积和潜在的冲突。接下来将整个技能目录打包。通常你需要打包以下文件manifest.jsonmain.py(以及你其他的.py文件)requirements.txt其他必要的资源文件如图标、数据文件避免将虚拟环境文件夹skill_env/、__pycache__/、.git/等目录打包进去。你可以创建一个.gitignore文件来管理这些。6.2 发布到技能平台不同的OpenCode平台有不同的发布方式。常见的有两种命令行工具发布使用平台提供的CLI工具例如opencode-cli publish --package ./my_skill.zip。网页控制台上传在平台的开发者后台提供一个压缩包上传接口。无论哪种方式通常都需要你事先在平台上注册为开发者并可能创建一个“技能”应用来获取相关的API密钥或配置。上传后平台会对你的技能包进行静态分析、安全扫描并可能要求你填写更详细的上架信息如分类、标签、长描述、隐私政策链接等。6.3 版本迭代与更新技能发布后难免需要修复Bug或增加新功能。务必通过更新版本号来管理迭代。在manifest.json中修改version字段遵循 语义化版本规范 是一个好习惯主版本号Major做了不兼容的 API 修改。次版本号Minor向下兼容的功能性新增。修订号Patch向下兼容的问题修正。例如从1.0.0修复一个Bug升级到1.0.1新增一个功能升级到1.1.0。每次更新代码后重复测试、打包、发布的流程。平台通常会保留旧版本以便在出现严重问题时可以快速回滚。清晰的版本更新日志可以在manifest的description或单独的文件中说明对用户和平台审核者都非常友好。7. 进阶技能开发处理复杂输入与状态管理基础技能只能处理简单指令。现实中的需求往往更复杂需要解析用户输入中的参数甚至在不同对话轮次中记住上下文。7.1 解析用户指令与参数提取用户的指令可能包含变量。例如一个查询天气的技能用户可能说“查询北京今天天气”或“上海明天温度怎么样”。我们需要从中提取“城市”和“时间”两个参数。这通常通过“意图识别Intent Recognition”和“实体抽取Entity Extraction”来完成。在简单的技能中我们可以使用正则表达式或简单的字符串匹配来模拟。更复杂的可以使用NLU自然语言理解库但初期建议从规则开始。假设我们的技能触发短语是“查询天气”我们可以这样处理import re app.handle(intentquery_weather) def handler(request): user_text request.text # 用户完整的输入文本如“查询北京今天天气” # 使用正则表达式提取城市和日期 city_pattern r查询(.?)(?:今天|明天|后天|的天气) date_pattern r(今天|明天|后天) city_match re.search(city_pattern, user_text) date_match re.search(date_pattern, user_text) city city_match.group(1).strip() if city_match else 北京 # 默认城市 date date_match.group(1) if date_match else 今天 # 默认今天 # 根据city和date调用天气API # weather_info get_weather_from_api(city, date) weather_info f{date}{city}的天气是晴25度。 # 模拟数据 return Response(textweather_info)这种方式比较原始但对固定格式的指令有效。对于更自由的表达需要考虑使用更强大的NLP工具。7.2 会话状态管理与多轮对话有些技能需要多轮交互。比如一个点餐技能第一轮问“您想点什么”用户回答“披萨”第二轮再问“您要什么口味的”。这就需要技能能记住上下文。OpenCode SDK通常会提供会话状态Session存储。状态可以存储在内存中仅限当前对话或者持久化到数据库中跨对话。from opencode_sdk.skill import Skill, Request, Response from opencode_sdk.session import Session app Skill() app.handle(intentorder_food) def handler(request: Request, session: Session): # 从会话状态中读取点餐进度 order_stage session.get(order_stage, start) # 默认为开始阶段 selected_food session.get(selected_food) if order_stage start: # 第一阶段询问食物类型 session.set(order_stage, select_flavor) return Response(text您想点什么披萨、汉堡还是沙拉, suggestions[披萨, 汉堡, 沙拉]) elif order_stage select_flavor and not selected_food: # 用户刚刚回答了食物类型我们存下来并进入下一阶段 user_choice request.text # 例如“披萨” session.set(selected_food, user_choice) session.set(order_stage, confirm) return Response(textf好的{user_choice}。您要什么口味的, suggestions[海鲜, 牛肉, 蔬菜]) elif order_stage confirm: # 用户回答了口味完成订单 flavor request.text food session.get(selected_food) # 清空或结束会话状态 session.clear() return Response(textf订单确认{flavor}口味的{food}。感谢下单) else: # 处理意外情况 session.clear() return Response(text对话出现异常已重置。请重新开始点餐。)在这个例子中Session对象允许我们在同一用户与技能的多次交互中保存和读取数据。suggestions字段用于在响应中提供快速回复选项提升用户体验。管理好会话的生命周期何时创建、更新、清除是设计多轮对话技能的关键。8. 性能优化与安全考量当技能被大量用户使用时性能和安全性就成为不可忽视的问题。8.1 技能性能优化要点冷启动优化技能在闲置一段时间后首次被调用可能会有一个加载延迟冷启动。为了减少这个时间精简依赖只引入绝对必要的第三方库。定期检查requirements.txt移除未使用的包。延迟加载对于耗时的初始化操作如加载大型模型可以考虑在handler函数被首次调用时才执行而不是在技能加载时。代码精简避免在全局作用域执行复杂计算或进行大量I/O操作。处理耗时操作如果技能需要调用一个响应很慢的外部API比如超过3秒不要让它阻塞主线程。可以考虑异步处理如果技能运行时支持异步IO如Python的asyncio使用异步函数来调用API。快速响应后台任务先立即返回一个“正在处理请稍候”的响应然后通过后台任务或消息队列去执行耗时操作并通过其他方式如推送通知将最终结果告知用户。这需要平台支持更高级的交互模式。缓存策略对于频繁查询且结果变化不频繁的数据如城市列表、产品目录、某些静态信息使用缓存可以极大提升响应速度并降低外部API调用次数。可以使用内存缓存如functools.lru_cache或外部缓存服务如Redis根据技能部署环境决定。8.2 安全开发实践输入验证与清理永远不要信任用户的输入。对所有从request.text或参数中获取的数据进行严格的验证和清理防止注入攻击如SQL注入、命令注入。import re def validate_city_name(city: str) - bool: # 只允许中英文、数字和常见符号 pattern r^[\w\u4e00-\u9fa5\s\-\.]$ return bool(re.match(pattern, city)) and len(city) 50安全地调用外部API如果技能需要调用外部服务使用环境变量管理密钥绝对不要将API密钥、令牌等敏感信息硬编码在代码中。使用平台提供的秘密管理功能或环境变量来存储。HTTPS确保所有外部调用都使用HTTPS协议。限制权限在manifest.json的permissions中只申请技能运行所必需的最小权限。错误信息脱敏当技能内部发生错误时返回给用户的错误信息应该是友好且通用的避免泄露系统内部细节、堆栈跟踪或数据库结构。try: result call_sensitive_operation() except Exception: # 记录详细的错误到日志供开发者排查 logger.exception(敏感操作失败) # 返回给用户模糊的信息 return Response(text服务暂时不可用请稍后再试。)依赖库安全定期更新requirements.txt中的依赖库版本以修复已知的安全漏洞。可以使用工具如safety或pip-audit来扫描项目依赖。遵循这些性能和安全实践能帮助你构建出既高效又可靠的技能赢得用户的长期信任。技能开发是一个持续迭代的过程从简单的“Hello World”开始逐步增加复杂度处理好每一个细节你就能创造出真正有价值的自动化工具。
