企业官网建设流程全解析

WaveTerm 自定义 Widget 插件开发指南：10 分钟做出第一个终端扩展

【免费下载链接】wavetermAn open-source, AI-integrated, cross-platform terminal for seamless workflows项目地址: https://gitcode.com/GitHub_Trending/wa/waveterm

想在 WaveTerm 里加一个一键启动 speedtest 的按钮，或者一块盯着 CPU 和内存的监控面板吗？只需往widgets.json里加几行 JSON，不写一行代码就能做到。跟着本文操作，前 10 分钟跑通第一个 Widget，整体约 30 分钟，门槛就是会复制粘贴配置。

先看它解决什么麻烦

你在终端里跑了一次speedtest-go，下次还想看网速，又得翻命令历史，敲一遍完整命令。

你跑了一次 3 分钟的编译，中途 CPU 飙到 90%，但 WaveTerm 默认的系统监控面板只保留 100 秒窗口，想复看整段峰值，历史早被截掉了。

这类"固定动作"和"固定视角"，本来就不该靠手。WaveTerm 的 Widget 机制把动作和面板变成 Widget 栏上的图标，点一下就开，这就是你今天要掌握的东西。

动手前 5 项自检清单

• WaveTerm 已安装并能启动：运行wsh version有版本输出，即通过
• 定位到真实配置目录：运行wsh editconfig能看到打开的配置路径；注意配置目录由WAVETERM_CONFIG_HOME决定，默认在~/.config/waveterm/（Linux），别凭记忆猜位置
• config/widgets.json文件存在：首次启动后该文件会自动生成；用wsh editconfig或编辑器打开能看到 JSON 内容，即通过
• 目标命令本机已装：如要建 speedtest Widget，先跑speedtest-go --unix确认有输出，即通过
• 编辑器保存后文件有实际变化：配置热加载由文件监听触发（见 pkg/wconfig/filewatcher.go），保存动作本身要真的写盘

5 分钟跑通第一个 Widget：一键 speedtest

第 1 步，备份并查看现有配置。复制一份~/.config/waveterm/config/widgets.json作备份，防止改坏后无处还原。然后查看里面已有几项——文件不存在就新建一个空 JSON 对象{}。

第 2 步，添加你的第一个 Widget。下面这段定义了一个名为speedtest的 Widget：view: term表示它打开一个终端块，controller: cmd表示"一次性命令"模式，点图标就自动执行speedtest-go --unix；cmd:clearonstart让每次重跑时先清空旧输出。

{ "speedtest": { "icon": "gauge-high", "label": "speed", "blockdef": { "meta": { "view": "term", "controller": "cmd", "cmd": "speedtest-go --unix", "cmd:clearonstart": true } } } }

把它合并进widgets.json的大括号内（已有内容就加逗号并列）。这一条配置的含义：WaveTerm 把它当成一张"配方"，按meta里的参数生成一个现成的终端块——你不用记命令，点图标就是执行。

第 3 步，保存并验证。保存文件即可，不用重启 WaveTerm。配置目录有文件监听器盯着，保存后自动广播配置更新事件（实现见 pkg/wconfig/filewatcher.go），Widget 栏会立刻多出一个量杯图标。

点它，速度测试立刻开跑。跑完想再看一次：右键该块的标题栏，选Force Controller Restart即可重跑——cmd模式自带这个刷新入口，这是它和shell模式最实用的区别。

到这里最小闭环就通了：一份 JSON = 一个按钮。

完整实战：给 3 分钟编译开一块 3 分钟窗口的监控面板

场景更具体一点：你的构建脚本要跑 3 分钟，你希望监控窗口正好覆盖全程，同时看 CPU 和内存两条曲线。这依然只是改配置，但多两个关键参数。

第 1 步，确认默认监控的局限。打开默认 sysinfo 面板看一眼：它只保留 100 秒数据，3 分钟的构建尾巴会被截掉。

第 2 步，定制一个"3 分钟监控"Widget。这段配置里，graph: numpoints把窗口拉宽到 180 个点（即 180 秒，1 点 1 秒），sysinfo:type指定显示内容，可选值区分大小写："CPU"、"Mem"、"CPU + Mem"、"All CPU"。

{ "3min-info": { "icon": "circle-3", "label": "3mininfo", "blockdef": { "meta": { "view": "sysinfo", "graph:numpoints": 180, "sysinfo:type": "CPU + Mem" } } } }

第 3 步，保存、点击、对照。保存后 Widget 栏出现新图标，点开它，CPU 与内存两条曲线同时滚动，窗口恰好容纳一次完整构建。跑一次你的构建命令，回看这块面板，峰值出现在哪个时间段一目了然。

可选加分项：给远程连接也放一个入口。在meta里加一行"connection"，值写连接规范名（WSL 形如wsl://Ubuntu，SSH 形如user@远程主机名），Widget 就会在该连接的远程终端里启动，而不是本地。

高频踩坑与修复：4 个现象对号入座

现象：改完保存，Widget 栏没变化。原因：JSON 语法错误，整份配置被丢弃回退。 解决：把文件内容贴给任意 JSON 校验工具确认；最常见的漏项是并列条目之间的逗号，或多余逗号。改好后重新保存。

现象：块打开了，但提示命令找不到。原因：命令没装，或不在 PATH 里。 解决：先在普通终端跑一次目标命令，command not found就先安装；装上了但which speedtest-go的路径不在常规位置，就在meta里用绝对路径替换cmd里的命令名。

现象：本地 Widget 正常，远程连接下打开却行为不对。原因：term:localshellpath、cmd:cwd这类键只对本地生效（官方文档明确标注 "Only works locally"）。 解决：远程终端 Widget 用"connection"指定连接，不要指望本地 shell 路径参数。

现象：明明保存了，热加载没触发。原因：监听器只认文件真实变更事件，且文件名需符合*.json命名规则；有些编辑器"保存"走临时文件替换，事件可能被过滤。 解决：直接重跑wsh editconfig用内置编辑器再保存一次，或重启 WaveTerm 兜底。

下一步：由浅入深 3 个方向

1. 换默认 Widget、清理 Widget 栏：内置 5 个默认 Widget 名为defwidget@terminal等，在widgets.json里把对应键设为null即可移除，同名覆盖可改行为；适合想把栏位让给自己常用项的人
2. 做个性化 shell 入口：controller换成shell，配合term:localshellpath指到fish、pwsh的绝对路径，一键开特定 shell；适合多 shell 用户
3. 写会动的交互 Widget：前面的 JSON 只能"打开即执行"，要做实时数据、按钮、图表这类交互逻辑，就上 tsunami/demo/cpuchart/ 里那种 Go + Tsunami 框架写法，仓库内 tsunami/demo/ 下有 6 个可运行的参考应用；适合需要自定义界面的进阶需求

配置类 Widget 五分钟一个，交互类 Widget 一个下午起步。先把你的日常操作整理成清单，逐条变成图标，用着用着就知道哪条值得升级成 Go 应用。

更多细节看仓库内文档：docs/docs/customwidgets.mdx（Widget 全量参数表）、docs/docs/config.mdx（配置键说明）、schema/widgets.json（配置结构校验规则）。

【免费下载链接】wavetermAn open-source, AI-integrated, cross-platform terminal for seamless workflows项目地址: https://gitcode.com/GitHub_Trending/wa/waveterm