安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install gen-asyncapi
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 gen-asyncapi。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

gen-asyncapi 是一款代码生成工具，适用于使用 AsyncAPI 3 文档描述消息 API 的项目。它会生成单个 Go 或 TypeScript 源文件，其中包含类型安全的消息模型、严格解码与验证、消息分发功能，以及适用于所选语言的客户端。
生成的代码是常规源代码，你可以将其与规范一同提交，并在规范变更时重新生成。对于探索 Openclaw Skills 的开发者，此技能提供了一条从 AsyncAPI 契约到可用客户端代码的实用路径。它仅支持 AsyncAPI 3，不支持 AsyncAPI 2.x 或 OpenAPI 规范。

应用场景

为遵循 AsyncAPI 3 契约的服务或客户端生成类型安全的 Go 模型和 WebSocket 客户端。
为 Web 前端创建 TypeScript 接口、验证器、消息分发功能和浏览器 WebSocket 客户端。
更改 AsyncAPI 文档或生成器配置后，重新生成已提交的源代码。
通过配置 JSON-pointer 消息匹配器，区分形状相同的传入消息。
go generate
gen.go
为现有 Go 项目添加生成步骤。

工作原理

提供 AsyncAPI 3 规范，并在需要时提供生成器配置。
使用 Go 工具链运行生成器，选择 Go 或 TypeScript 输出以及输出路径。
生成器会读取规范、引用文件和配置；它不会执行规范中的代码。
生成器会写入一个生成的源文件，其中包含适用于相应语言的类型、解码与验证、消息分发功能和客户端功能。
在应用代码中使用生成的客户端发送消息并处理传入帧；规范或配置变更后重新生成。

配置指南

使用 Go 工具链安装并运行生成器。对于 Go 项目，将此工具添加到项目中，并在 gen.go 旁创建配置文件：
go get -tool github.com/psyb0t/gen-asyncapi/cmd/gen-asyncapi@latest

config.yaml

package: chat
output: chat.gen.go
添加指向 AsyncAPI 文档的生成指令。配置和命令行中的路径均相对于包含 gen.go 的目录：
// gen.go
package chat
//go:generate go tool gen-asyncapi --config=config.yaml ../../api/asyncapi.yaml
使用以下命令生成 Go 输出：
go generate ./...
直接生成 TypeScript 时，指定语言和输出文件：
go run github.com/psyb0t/gen-asyncapi/cmd/gen-asyncapi@latest -language=typescript -o=src/chat.gen.ts asyncapi.yaml
必须安装 Go 工具链。按版本安装或运行时会通过网络获取模块；生成过程本身可离线进行。不要手动编辑生成的 .gen.go 或 .gen.ts 文件：请修改规范或配置后重新生成。

数据架构

生成器会读取 AsyncAPI 3 文档、文档引用的所有文件及其配置。它会将一个源文件写入配置的输出路径，或通过 -o 指定的路径。
输出 生成的元素
Go 具有严格 UnmarshalJSON 和 Validate 的结构体；具名枚举类型和常量；带有 FromX、AsX 和 Value 的联合类型；Message 常量；DecodeReceivedMessage；Handler 接口和 UnimplementedHandler；Dispatch；以及具有各消息专用发送方法和 Run 的客户端。
TypeScript 一个无依赖的 .ts 文件，其中包含接口、字面量联合类型、validate 断言函数、decodeReceivedMessage、dispatch，以及接受浏览器 WebSocket 的客户端。
Go 输出使用 asyncapirt 运行时及其 gorilla/websocket 传输层。规范中的操作名称决定 Go 发送方法的名称；处理器方法遵循 Handle 模式。TypeScript 验证错误包含 path，未匹配的帧可通过 handleUnknownMessage 处理，或使用 UnknownMessageError 拒绝。
如果无法通过 const 属性或严格解码区分消息，请使用 JSON pointers 配置 output-options.message-matchers。匹配器的值可以是列表；空列表会导致生成失败。凭据应放在客户端传输设置中，而非规范或生成器配置中。

高级特性

Go 结构体提供严格的 JSON 解组和验证；解码错误会包装通信错误哨兵，例如
commerr.ErrValidationFailed
commerr.ErrRequiredFieldNotSet
。
Go 联合类型提供
FromX
、
AsX
Value
辅助方法，而生成的消息常量和
const
属性可用于消息识别与封送。
Go 客户端提供各消息专用的发送方法、用于读取和分发消息直至上下文结束或连接断开的
Run
，以及支持选择性实现处理器的
UnimplementedHandler
。
TypeScript 验证会报告带有路径的
ValidationError
；未匹配的帧可以路由到
handleUnknownMessage
，或使用
UnknownMessageError
拒绝。
配置 JSON-pointer 消息匹配器，以区分原本相似的传入消息；列表值会匹配其中任意条目。
生成过程只会写入配置的输出文件，绝不会运行规范中的代码。只有应用代码发起拨号时，生成的客户端才会连接；通过
gorillaws.WithBearerToken
等传输选项传递 bearer token，绝不要将其放入规范或配置中。
对于 Openclaw Skills 用户，此工作流同时适用于直接 CLI 生成和可重复执行的 Go
go generate
流水线。

name: gen-asyncapi description: Code generator that turns an AsyncAPI 3 spec into Go or TypeScript. github.com/psyb0t/gen-asyncapi/cmd/gen-asyncapi runs from go generate (or go run) with a small YAML config and writes one file. Go output has structs with strict UnmarshalJSON and Validate, enums as named types with constants, unions with FromX/AsX/Value, Message constants, DecodeReceivedMessage, a Handler interface with UnimplementedHandler, Dispatch, and a Client with one send method per message plus Run, over the asyncapirt runtime and its gorilla/websocket transport. TypeScript output (language: typescript) is one dependency-free .ts file with interfaces, literal unions, validate assert functions, decodeReceivedMessage, dispatch and a Client that takes a browser WebSocket. Use when a project needs typed models or a WebSocket client generated from an AsyncAPI 3 spec, or already has a gen.go calling gen-asyncapi. homepage: https://github.com/psyb0t/gen-asyncapi
user-invocable: true