企业官网建设流程全解析

10 分钟上手 WaveTerm 插件开发：把常用工具钉进终端侧栏

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

想把 CPU 曲线钉在终端侧边、让 fish shell 一键打开？WaveTerm 插件开发里，这类需求往往只要几行配置。本文先说清它能做什么，再帮你选路、落地第一个插件。

能力全景：能做什么

这一节回答"插件能做哪些形态"。WaveTerm 的插件叫 Widget，分配置型和代码型两条路线：

选路：配置型还是代码型

这一节帮你二选一。标准就一条：能用"开一个窗口跑 X"描述的功能，选配置型；需要按钮交互、数据每秒更新、自定义图表，才上代码型。配置型零代码、改完即用，适合第一次动手；代码型要 Go 环境，但上限高得多。

第一个插件：只改几行配置

这一节让你 5 分钟拿到第一个 Widget。打开<WAVETERM_HOME>/config/widgets.json，在最外层对象里加入下面这段：

{ "fish" : { "icon": "fish", "color": "#4abc39", "label": "fish", "blockdef": { "meta": { "view": "term", "controller": "shell", "term:localshellpath": "/usr/local/bin/fish" } } } }

改哪里、看到什么：

• "fish"顶层键：Widget 的唯一名字，只影响这份 Widget 配置的索引。
• "icon"：Font Awesome 图标名，换成circle-3、gauge-high都行。
• "label"和"color"：widget bar 里显示的文本与颜色，是用户第一眼看到的东西。
• "view": "term"：声明终端类型；改成"web"变网页块，"sysinfo"变系统曲线。
• "controller"："shell"是持久会话；改成"cmd"并加"cmd"字段，就变成一次性的命令行。
• "term:localshellpath"：shell 可执行文件，必须写绝对路径。

预期效果：保存后重启 WaveTerm，widget bar 出现绿色小鱼图标，点击直接开出运行 fish 的新终端。

代码型插件的三个关键动作

这一节以官方 cpuchart 为例，讲清 Tsunami 插件里真正起作用的三处代码。

1. 声明元数据：AppMeta里写插件标题与简介；实时数据放进DataAtom，它是响应式变量，值一变界面自动刷新。
2. 定时采集：在 App 组件里用app.UseTicker(time.Second, ...)注册每秒回调，采一次 CPU 占用写进原子；块关闭时计时器自动清理，不用手动管理。
3. 渲染界面：组件返回一棵vdom.H树描述界面，样式类直接用 Tailwind，也能混入 recharts 这类现成图表组件。

三个动作合起来的骨架（完整版见 tsunami/demo/cpuchart/app.go）：

var AppMeta = app.AppMeta{Title: "CPU Usage Monitor"} var App = app.DefineComponent("App", func(_ struct{}) any { app.UseTicker(time.Second, func() { cpuDataAtom.SetFn(func(d []CPUDataPoint) []CPUDataPoint { return append(d, generateCPUDataPoint()) }) }, []any{}) return vdom.H("div", map[string]any{"className": "min-h-screen p-6"}) })

第一行是元数据，回调体是采集点，返回的 vdom 树就是界面。

打包、安装与验证

📦 这一节回答写完之后怎么跑起来。WaveTerm 插件打包安装对配置型没有额外步骤——widgets.json 本身就是安装位置。代码型用 Go 构建：

cd tsunami/demo/cpuchart # 换成你的插件目录 go build -o cpuchart . ./cpuchart

• 改哪里：把第一行换成你自己的插件目录；-o后的名字决定二进制名。
• 预期效果：构建无报错、产出二进制；运行后打开独立窗口，CPU 曲线每秒跳动。

验证成功的判断标准：

• 配置型：重启后 widget bar 出现新图标，点击能打开对应块——跑着 fish 的终端、指定网页或系统曲线，三者居其一即可。
• 代码型：go build通过、二进制可运行、界面持续刷新。
• 想把代码型插件挂成终端块：在 widgets.json 加一条 term + cmd 条目，命令填插件路径，并设"cmd:jwt": true给它注入鉴权 token。

避坑清单

这一节汇总五个最常见的翻车点，均按"现象 → 原因 → 处理"：

• 改完 widgets.json 后 widget bar 没变化→ 应用仍在读旧配置，或 JSON 语法非法导致整份文件被丢弃 → 先校验 JSON 语法，再完全退出并重启 WaveTerm 验证。
• shell 型插件打开的还是默认 shell→ 目标 shell 不在系统 PATH，相对路径无效 → 把term:localshellpath换成绝对路径，如/usr/local/bin/fish。
• 代码型插件以 widget 打开时报错或空白→ 运行环境缺 JWT 鉴权 token → 在该条目的 meta 里加"cmd:jwt": true。
• sysinfo 曲线始终是 CPU→sysinfo:type区分大小写，且只认"CPU"、"Mem"、"CPU + Mem"、"All CPU"四个值 → 原样复制，别自创写法。
• 图标不显示→ 图标名不在 Font Awesome 库中 → 换成有效名称；品牌图标要加brands@前缀。

延伸入口

这一节是继续深入的地图。

• docs/docs/customwidgets.mdx：自定义 Widget 官方文档，含全部键值表与 Font Awesome 图标写法。
• tsunami/demo/：官方示例插件目录，含 cpuchart、pomodoro 等完整 Go 工程。
• tsunami/app/：Tsunami 框架 API，组件、原子与 hooks 的定义。
• BUILD.md：WaveTerm 本体的编译构建指南。

从几行 Widget 配置起步，你的终端很快就长出自己的形状。

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