企业官网建设流程全解析

WaveTerm 插件完整指南：一条 JSON 配出终端里的自定义面板

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

写长任务时想盯着 CPU 曲线，却总要在浏览器和终端之间来回切？用 WaveTerm 插件就能把面板直接钉在终端侧栏，不用离开窗口。WaveTerm 插件开发其实只有两条路：一段widgets.json配置，或一个 Tsunami（Go 框架）小应用。

插件体系怎么分工

WaveTerm 的扩展分两层，先分清自己属于哪层，少走弯路：

• widgets.json 声明式配置：把终端命令、网页、系统监控等封装成 widget bar 上的按钮，适合"点开即用"的场景，不写代码，改完即生效。
• Tsunami 插件框架：基于 VDOM 的 Go 框架，负责带状态、带交互的应用（按钮、倒计时、图表刷新），适合 JSON 表达不了的逻辑。

简单记：能配置解决的，别写代码；要交互的，再上 Go。

一条 JSON 配出 3 分钟构建监控面板

新建一个 widget 只需要在<WAVETERM_HOME>/config/widgets.json的对象里加一个键值对，下面是完整可复制的最小示例——一个 3 分钟窗口的 CPU+内存监控面板：

"3min-build" : { "icon": "gauge", "label": "构建监控", "blockdef": { "meta": { "view": "sysinfo", "graph:numpoints": 180, "sysinfo:type": "CPU + Mem" } } }

字段逐个说：

• icon/label/color：widget bar 上的图标（Font Awesome 图标名）、文字和颜色，纯外观字段，缺省也有默认值。
• blockdef.meta：真正的行为定义，view决定打开什么视图。
• view: "sysinfo"：打开系统监控面板，内置CPU、Mem、CPU + Mem、All CPU四种图（区分大小写）。
• graph:numpoints: 180：图表保留 180 个数据点，也就是 3 分钟窗口，正好盖住一次中等长度的构建。
• sysinfo:type: "CPU + Mem"：默认同时绘制 CPU 和内存两条曲线。

保存后 widget bar 会多出一个按钮，点开就是这个效果：

同样的结构换几行配置，还能挂dua磁盘分析器、speedtest 测速、甚至固定打开某个网页——完整字段表和每种视图（term / web / sysinfo）的选项都在自定义插件文档里。

配置不够用时上 Go

JSON 只能"声明一个面板"，一旦要按钮、倒计时、状态切换这类逻辑，就该用 Tsunami 插件框架写 Go 了。仓库自带一套可直接抄的示例插件（番茄钟、Todo、GitHub Actions 监控等），每个目录就是一个独立 Go 模块：

tsunami/demo/pomodoro/ ├── app.go # 组件与状态逻辑 ├── go.mod / go.sum └── static/tw.css

核心代码就几行（摘自 pomodoro 示例）：

remainingSecondsAtom = app.DataAtom("remainingSeconds", 25*60, &app.AtomMeta{ Desc: "Remaining seconds in current pomodoro timer", }) var App = app.DefineComponent("App", func(_ struct{}) any { app.UseTicker(time.Second, func() { /* 每秒把剩余秒数更新到 atom */ }, []any{}) return vdom.H("div", nil, ...) // 渲染 UI })

白话说：DefineComponent声明一个组件，UseTicker挂了一个每秒执行一次的定时器去改数据，数据一变 UI 自动重渲染——和前端框架的响应式套路一致，只是状态写在 Go 里。

打包与安装只要两条命令

开发阶段可以直接跑：

• tsunami run tsunami/demo/pomodoro—— 构建并启动应用
• tsunami package tsunami/demo/pomodoro—— 把整个目录打成一个自包含的.tsapp文件

装到本机：把构建出的应用放进~/.waveapps/local/<应用名>/（waveappstore 就是从这个目录发现本地应用），重启 WaveTerm 后即可从应用栏启动。

⚠️ 两个常见坑：

• tsunami run需要在开发环境跑，它依赖TSUNAMI_SCAFFOLDPATH/TSUNAMI_SDKREPLACEPATH等环境变量（见 tsunami CLI），嫌麻烦就直接拷一个 demo 目录改代码。
• 改了代码要重新构建，WaveTerm 不会热加载~/.waveapps下的旧产物。

继续往下挖

• docs/docs/customwidgets.mdx：官方文档，覆盖 widgets.json 全部字段，含 term / web / sysinfo 三类视图。
• tsunami/demo/：示例插件合集，抄一个 pomodoro 改一改是最快的上手方式。
• tsunami/app/：Tsunami 框架核心 API（App、DefineComponent、DataAtom、UseTicker 都在这）。

建议从 pomodoro 那份app.go读起，改完跑一遍tsunami run，你就有第一个自己的 WaveTerm 终端扩展了。

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