QoderWake插件开发指南 使用官方SDK创建扩展功能

想要为QoderWake开发一个能够满足特定业务需求的定制化插件，却对它的插件架构、开发流程和集成标准感到困惑？这通常源于对最新的SDK设计、插件生命周期管理以及运行时上下文机制不够了解。无需担忧，本文将为你提供一份清晰的入门指南，手把手教你完成一个功能完备的插件开发全流程。

一、搭建插件开发环境

QoderWake插件采用TypeScript作为开发语言，其完整的开发、编译、签名与注册流程，都依赖于官方提供的一站式CLI工具链。首要步骤，是创建一个符合 qoderwake/plugin-spec-v2 规范的项目工程结构，以确保最终生成的插件包能够被QoderWake Agent运行时准确识别并顺利加载。

具体操作可分为四个关键步骤：首先，在终端执行 qodercli plugin init my-custom-connector 命令，该命令会自动生成一个标准项目模板，包含 package.json、核心配置文件 manifest.yml 以及入口文件 src/index.ts。接着，编辑至关重要的 manifest.yml 文件，在其中声明插件的元数据信息，例如设置唯一标识 id 为 com.example.myconnector、版本号 version 为 0.1.0、插件类型 type 为 connector，并明确列出插件运行所需的权限，如 required_permissions: ["read:workspace", "execute:shell"]。然后，运行 npm install @qoderwake/sdk --save-dev 安装最新的官方SDK开发包，其附带的TypeScript类型定义文件将自动集成到项目的编译路径中，提供智能代码提示。最后，执行 qodercli plugin build 命令进行项目构建，输出产物是一个名为 dist/bundle.qwp 的已签名插件包，其中已嵌入了必要的审计证书和SHA256完整性校验指纹。

二、编写核心生命周期函数

每一个QoderWake插件都必须对外导出三个核心的同步函数：onLoad、onActivate 和 onDeactivate。它们分别对应插件被加载、激活就绪以及卸载清理这三个关键的生命周期阶段。SDK会向这些函数注入一个强大的 context 上下文对象，它封装了当前Agent的身份信息、工作区ID以及经过认证的权限令牌，插件可借此安全地调用各类下游服务接口。

实现这些函数非常直观。在 src/index.ts 入口文件中，首先导入SDK类型：import { PluginContext } from '@qoderwake/sdk';。随后，编写 onLoad 函数，它接收 PluginContext 参数，你可以在此处调用 context.logger.info('MyConnector loaded') 来记录插件初始化的日志信息。接下来是 onActivate 函数，你可以从传入的 context 对象中解构出 workspaceId 和 authToken 等关键信息，并利用它们构造形如 Authorization: Bearer ${authToken} 的标准HTTP请求头，向你自己的服务健康检查端点（例如 https://api.example.com/v1/health）发起连接测试，确保依赖服务可用。最后，务必实现 onDeactivate 清理函数，在此调用 context.teardown() 等方法，主动释放所有可能持有的WebSocket长连接、定时器句柄等资源，这是保障插件稳定运行、避免内存泄漏的至关重要的一环。

三、注册自定义工具供Agent调用

插件核心能力的重要体现，在于能够将自定义的JavaScript/TypeScript函数注册为Agent可直接调用的“工具”。通过调用 context.registerTool 方法，任何符合签名的函数都能被注册。SDK会自动为注册的函数生成标准的OpenAPI 3.0接口描述、执行严格的参数校验，并在一个安全的沙箱环境中运行函数逻辑，从而确保了调用的安全性、可观测性与可维护性。

举例说明，假设你定义了一个异步函数 fetchCustomerProfile(customerId: string)，用于根据传入的客户ID查询并返回详细的会员档案信息。你需要在插件的 onActivate 生命周期函数中，调用 context.registerTool 来注册它，同时提供工具的唯一名称、函数引用、功能描述以及详细的参数定义。成功注册后，在QoderWake的命令行终端中执行 qwake tools list 命令，即可确认 fetchCustomerProfile 已经出现在可用工具列表中，并且状态显示为 enabled。此时，你便可以在智能体交互模式下直接输入自然语言指令，例如“请调用fetchCustomerProfile工具查询ID为100012345678的客户完整信息”，随后观察控制台输出的结构化响应数据以及精确的执行耗时，从而完成端到端的调用测试与验证。

四、接入外部事件并驱动自动化任务

除了被动响应Agent的指令调用，QoderWake插件还支持主动监听外部系统事件，实现真正的事件驱动型自动化流程。通过调用 context.subscribeEvent 方法，插件可以订阅平台预定义或自定义的多种事件类型（例如 github.pull_request.opened、slack.message.posted）。当匹配的事件被触发并到达时，插件可以自动发起一个复杂的Quest（任务）流程，形成从事件感知到自动执行的完整闭环。

具体实现流程如下：在插件的 onActivate 函数中订阅目标事件，例如 context.subscribeEvent('github.pull_request.opened', async (event) => { ... })。在事件回调函数内部，你可以从 event.payload 载荷中解析出所需的全部字段，例如PR编号、源分支名称、目标仓库全名等。随后，调用 context.startQuest({ spec: { task: 'review-pr', params: { prNumber: event.payload.pr.number, repo: event.payload.pr.base.repo.full_name } } }) 接口，提交一个自动化的代码审查任务。任务提交后，你可以立即在QoderWake的Quest任务控制台界面中，确认新的审查任务已被成功创建，并且其初始状态显示为 Pending Context Injection，这标志着来自GitHub事件的相关上下文信息已经成功注入到了该任务的初始执行环境中。

五、本地调试与生产签名验证

安全性是QoderWake插件生态的基石。平台强制要求所有部署至生产环境的插件包，必须携带由官方证书颁发机构（CA）签发的有效数字签名。任何未签名或签名验证失败的插件，都会被运行时环境直接拒绝加载。当然，在本地开发与调试阶段，你可以启用开发者模式来临时绕过严格的签名检查，但在正式发布上线前，必须完成官方的签名流程。

进行本地调试时，首先需要在QoderWake用户设置页面中，勾选 Developer Mode → Enable unsigned plugin loading 选项以启用开发者模式。然后，在终端执行 qodercli plugin load ./dist/bundle.qwp 命令来加载本地构建的插件包，并观察QoderWake界面右下角的状态栏，确认你的插件名称是否显示且状态为 Active。若需要进行深入的代码级调试，可以在VS Code中打开插件项目，使用官方扩展 Debugger for QoderWake 启动调试会话，并在源代码的关键位置（例如 onActivate 函数的第一行）设置断点。当所有功能测试均通过，准备正式发布前，执行生产签名命令：qodercli plugin sign --cert-path ./certs/prod.crt --key-path ./certs/prod.key ./dist/bundle.qwp，该命令将生成一个最终的、可用于生产环境部署的 bundle.qwp.signed 签名文件。