WaveTerm 插件开发指南：30分钟跑通你的第一个自定义终端扩展

WaveTerm 插件开发指南30分钟跑通你的第一个自定义终端扩展【免费下载链接】wavetermAn open-source, AI-integrated, cross-platform terminal for seamless workflows项目地址: https://gitcode.com/GitHub_Trending/wa/waveterm正在跑编译想在旁边的分屏里固定挂一个实时资源监控面板WaveTerm 插件开发刚好解决这件事几行 JSON 就能让终端长出 CPU 监控窗口用 Go 再能做出带图表、带按钮的交互插件。这篇文章面向刚接触 WaveTerm 的新手两个实战的代码都能直接照抄运行跟着走就能出第一个可用的终端扩展。先看插件体系你需要的是哪一种WaveTerm 的插件官方叫 Widget就是出现在窗口顶部图标栏里、点一下就能打开对应面板的入口。所有插件都写在WAVETERM_HOME/config/widgets.json一个文件里按能力分成四类类型能力难度适用场景终端/CLI 插件开一个终端跑指定 shell 或命令低纯 JSON一键启动 fish、pwsh 等非默认 shell固定跑某条命令Web 插件在终端里嵌一个网页低纯 JSON把常用网页服务变成栏上一键图标系统信息插件CPU、内存实时曲线图低纯 JSON编译、部署时盯着资源占用Go 插件Tsunami图表、按钮、定时器等完整交互界面中Go 语言需要状态和交互的监控台、小工具前三类改配置就行第四类才写代码。本文的实战正好各取一个先用 JSON 声明一个 CPU 监控面板再用 Go 写一个会自己采样的交互应用。环境准备装好 WaveTerm找到配置目录从源码构建只需要三步详细步骤见仓库的BUILD.mdgit clone https://gitcode.com/GitHub_Trending/wa/waveterm cd waveterm # 按 BUILD.md 完成编译安装也可直接装官方预编译包装好后认准一个路径WAVETERM_HOME/config/widgets.json。其中 Linux 是~/.config/WavemacOS 是~/Library/Application Support/WaveWindows 是%USERPROFILE%\.config\Wave。这个文件存在就打开编辑不存在就新建。实战一用一段 JSON 声明一个 CPU 监控面板目标在插件栏加一个图标点它打开所有 CPU 核心的实时曲线图。1. 往 widgets.json 里加这段文件已有内容时把all-cpu整块合并进大括号里即可{ all-cpu: { icon: chart-scatter, label: all-cpu, blockdef: { meta: { view: sysinfo, // 窗口类型系统信息 sysinfo:type: All CPU, // 图表集合大小写敏感 graph:numpoints: 180 // 图表窗口长度180 秒 } } } }2. 逐项拆开看view决定开出来的是什么窗口系统信息固定写sysinfosysinfo:type大小写敏感合法值只有四个CPU、Mem、CPU Mem、All CPUgraph:numpoints等价于回看多少秒不写默认 100icon是 Font Awesome 图标名label是图标下方的文字。3. 保存后看效果插件栏立刻出现新图标点开就是滚动更新的曲线。4. 顺手改个参数把sysinfo:type换成CPU Mem再保持graph:numpoints: 180就得到一个CPU内存、回看 3 分钟的面板——跑 3 分钟的编译全程都在图里。JSON 这条线到这就通了改配置、存文件、点图标没有任何编译步骤。实战二用 Tsunami 框架开发一个 Go 交互插件Tsunami 是 WaveTerm 官方的 Go 语言 UI 框架——用 Go 写界面和逻辑框架负责渲染和交互。不想从零写的话仓库自带完整示例 tsunami/demo/本文直接以其中的cpuchart为骨架它做的就是每秒采样一次 CPU、滚动画图。目标看懂一个最小可用 Go 插件的四个组成部分应用元信息、数据原子、定时器、界面。1. 应用元信息 数据原子对照tsunami/demo/cpuchart/app.go// AppMeta 是应用基本信息每个插件都必须有 var AppMeta app.AppMeta{ Title: CPU Usage Monitor, ShortDesc: Real-time CPU usage monitoring and charting, } // 数据原子Atom带名字的状态存储值一变界面自动重渲染 var cpuDataAtom app.DataAtom(cpuData, []CPUDataPoint{}) var currentCpuUsageAtom app.DataAtom(currentCpuUsage, 0.0)2. 根组件 定时器var App app.DefineComponent(App, func(_ struct{}) any { // UseTicker每秒采样一次窗口关闭时自动清理 app.UseTicker(time.Second, func() { point : generateCPUDataPoint() // 采集一个 CPU 使用率样本 cpuDataAtom.SetFn(func(data []CPUDataPoint) []CPUDataPoint { data append(data, point) return data[len(data)-60:] // 只保留最近 60 秒 }) }, []any{}) // vdom.H(...)用类 HTML 的嵌套调用描述界面 return vdom.H(div, map[string]any{className: p-6}, CPU Monitor) })3. 关键点app.DefineComponent定义组件名字叫App的是根组件插件从它开始渲染vdom.H(标签名, 属性map, 子节点...)就是用 Go 拼 HTML属性里可以直接挂onClick这类事件函数SetFn是对数据原子做函数式更新改完自动触发重绘——不需要任何手动刷新逻辑完整示例里还有 gopsutil 采样、Recharts 图表照抄tsunami/demo/cpuchart/即可。从构建到验证的可复现命令链Go 插件的调试与打包是两条命令tsunamiCLI 随开发环境构建命令定义见 tsunami/cmd/# 1. 本地调试编译 启动边改边看 tsunami run tsunami/demo/cpuchart # 2. 打包把插件目录压成单个 .tsapp 文件 tsunami package -o cpuchart.tsapp tsunami/demo/cpuchartJSON 插件不需要这条链它自己的安装就是保存widgets.json。装成功的三个检查点JSON 插件插件栏出现新图标且label正确点击后对应窗口打开系统信息插件窗口里的曲线随时间滚动点图可切换图表集合Go 插件tsunami run编译通过、窗口打开图表每秒刷新打包后在指定路径生成了.tsapp文件。⚠️ 新手高频的三个坑现象一找不到 widgets.json打开~/.config/Wave却空空如也。原因是 WAVETERM_HOME 因系统而异Windows 和 macOS 都不在这个位置。解决按上面环境准备一节对照系统找路径实在不行find ~ -name widgets.json搜一下。现象二改了配置没生效插件栏纹丝不动。多半是 JSON 语法错误多一个逗号、少一个引号导致整个文件解析失败。解决先把文件喂给python3 -m json.tool校验报错定位到行修完保存——WaveTerm 会监视该文件修正后自动生效。现象三Go 插件构建失败报找不到 tsunami 模块go build提示github.com/wavetermdev/waveterm/tsunami解析失败。原因是 Tsunami SDK 是主仓库里的本地目录不会从公共 Go 代理下载仓库示例的 go.mod 里就有这条 replace。解决在插件项目目录执行go mod edit -replace github.com/wavetermdev/waveterm/tsunami/你的路径/waveterm/tsunami再go mod tidy。延伸学习到这里JSON 声明式和 Go 开发式两条插件路线都已经跑通后续往哪个方向深挖都可以。官方文档Widget 配置全字段参考docs/docs/customwidgets.mdx可直接照抄的示例插件集tsunami/demo/Tsunami 框架源码组件、定时器、数据原子的实现tsunami/engine/【免费下载链接】wavetermAn open-source, AI-integrated, cross-platform terminal for seamless workflows项目地址: https://gitcode.com/GitHub_Trending/wa/waveterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考