用途:为 Hermes TUI(hermes --tui)编写小组件应用,包括停靠在状态栏上方的环境面板,以及接管键盘的模态浮层。小组件是纯 ESM 文件,TUI 启动时加载,无需构建步骤,也不改动仓库。不覆盖桌面应用或网页仪表盘小组件。
适用场景:用户要求在 TUI 中显示实时面板(行情、时钟、倒计时、状态卡、API 读数),或想要绑定到斜杠命令的自定义模态工具(选择器、计算器、查看器)。前提是正在使用 TUI;经典 CLI 或消息平台不渲染小组件。联网小组件需自备 API 凭据,抓取失败必须落到错误阶段而非崩溃。
用法:用 write_file 创建 ~/.hermes/tui-widgets/<name>.mjs。TUI 运行时会在一秒左右热加载(目录被监视),/widgets-reload 强制重扫。小组件 id 自动成为斜杠命令 /<id>,帮助显示在 / 补全弹窗中,无其他注册方式。自动打开需在 register(sdk) 末尾调用 sdk.openWidget(app, app.init('')),仅在用户要求时使用,且每次 /widgets-reload 会重新停靠。
能力:sdk 提供 defineWidgetApp、openWidget、updateWidget、isCtrl、React、h(createElement,.mjs 中无 JSX)、组件 Box、Text、Dialog、Overlay、WidgetGrid、GridAreas,以及 Shimmer、ShimmerRows、useShimmerPhase 加载器。图表为纯字符串构建器:sparkline、sparkRows、gauge、hbars。Accordion 支持点击展开折叠。
限制:ambient 模式不捕获输入,render 返回卡片而非 Overlay;modal 模式接管所有按键,reduce 返回下一状态、同一引用吞掉按键或 null 关闭。停靠区会预留真实空间,不覆盖转录内容。颜色必须用主题色调,不可硬编码十六进制。ambient 小组件应保持小尺寸(约 6 行以内)。register() 抛错会被记录并跳过,可查 ~/.hermes/logs/tui_gateway_crash.log。验证:运行 /widgets-reload,转录行须在 loaded: 下列出该文件,再用 /<id> 启动或移除。