Files

T

Redredchen01 5b35551434 Release v0.3.11: position repo as Grok plugin with clearer install

Document plugin-first packaging (manifest, commands, skills, hooks) and
have install.sh build the CLI, install the tmux dashboard, and register
the plugin so clone-and-setup matches how the project is shipped.

2026-07-17 16:45:10 +08:00

9.9 KiB

Raw Blame History

grok-build-hud

Grok Build 官方插件格式的实时状态条

English: README.en.md

在同一个 Terminal 标签页底部常驻显示（tmux 状态栏，不另开窗口）：

Grok 4.5 · AI FILM SPACE/0717 · ●
窗 ██████░░░░ 50% (252k/500k) · 入 2,189,879  出 9,468  缓 2,172,032 99% · 额 24% · 轮7 · 具212
◐ read_file… · ✓ grep ×3 · ▸ 待办

能力	说明
上下文	窗口占用 % 与 token 数
配额	周/月用量（需已 `grok login`）
Token 明细	入 / 出 / 缓存 / 推理（来自会话 `turn_completed`）
活动	工具、agent、todos
主题	跟随 Grok `[ui].theme`，不锁死
多终端	每个标签页独立 session，互不串线
语言	默认简体中文，可切英文 / 繁體

仓库：http://172.238.15.154:3000/Redredchen01/grok-hud
插件名：grok-build-hud · 版本见 plugin.json

这是什么

层级	说明
交付形态	Grok 插件（`plugin.json` + `commands/` + `skills/` + `hooks/`）
运行时	Node CLI（`grok-hud` / `grok-build-hud`）+ 同窗口 tmux 状态条
Skill	插件内附带，方便会话里被 agent 识别与调用

一句话： 给 Grok Build 用的底部状态栏——上下文、配额、token、工具与待办，一眼看到。

依赖

依赖	说明
Grok Build	已安装 CLI，并 `grok login`
Node.js 18+	`node -v`
npm	随 Node 安装
tmux	同窗口 HUD 必需；macOS：`brew install tmux`
终端	Terminal / iTerm 等

安装（推荐一键）

从 Gitea 克隆后执行安装脚本：编译 CLI → 装 tmux 状态条 → 注册为 Grok 插件。

git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
cd grok-hud
bash scripts/install.sh

脚本会依次：

npm install + npm run build
npm link（grok-hud / grok-build-hud 进 PATH）
--install-dashboard（hooks + tmux 多行状态条 + grok wrapper）
主题跟随 + 预设 full
grok plugin install . --trust 并 enable（若本机有 grok）

完成后：

grok                 # 同窗口底部出现状态条
grok-hud status      # 打印一次完整状态
grok-hud settings    # 语言 / 预设 / 行数

在 Grok 内执行 /hooks 后按 r 重载 hooks（若提示未加载）。

命令找不到时

写入 ~/.zshrc：

export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$PATH"

然后 source ~/.zshrc，再 which grok-hud。

安装拆解

只想分步做时：

1）仅 CLI + 同窗口状态条（无心功能）

cd /path/to/grok-hud
npm install && npm run build && npm link
npm run install-local
# 等价于：--install-dashboard + --theme auto + --preset full

2）注册为 Grok 插件（斜杠命令 + skill + session hooks）

须先完成编译（插件 hooks 依赖 dist/）：

cd /path/to/grok-hud
npm install && npm run build
grok plugin install . --trust
grok plugin enable grok-build-hud

校验：

grok plugin validate .
grok plugin details grok-build-hud

3）从本机已有源码目录更新

cd /path/to/grok-hud
git pull
bash scripts/install.sh
# 或：grok plugin update grok-build-hud

注意： 只装插件、不跑 install-dashboard 时，会话里会有 /hud 等命令与 scrollback 注解，但不会出现底部多行 tmux 状态条。完整体验请用一键 install.sh。

日常使用

# 1. 打开 Terminal（会自动确保 HUD 后台更新器）
# 2. 输入：
grok

底部即出现状态条。

# 不要 HUD 的裸命令（脚本 / 打印模式）
GROK_NO_HUD=1 grok -p "hello"

# 兼容旧入口
grok-hud-run

生命周期：开 Terminal 即就绪；不是电脑开机自启。
并行开发：每个标签页独立 Grok session，各自 grok 即可。

会话内斜杠命令

插件启用后，在 Grok 会话中可用：

命令	作用
`/hud`	状态条相关说明
`/status`	打印当前状态
`/quota`	配额相关
`/preset`	切换 full / essential / minimal
`/settings`	语言、预设、行数
`/setup`	安装 / 修复 dashboard
`/watch`	保持 HUD 实时更新说明

也可在 shell：

grok-hud status
grok-hud settings
grok-hud lang zh|en|tw
grok-build-hud --preset full|essential|minimal
grok-build-hud --theme auto
grok-hud stop

设定（语言 / 预设）

# 交互设定（默认界面为中文）
grok-hud settings

# 快捷切语言
grok-hud lang zh    # 简体中文（默认）
grok-hud lang en    # English
grok-hud lang tw    # 繁體中文

改完配置后若条未变，在 tmux 内：

tmux source-file ~/.grok/hud/tmux.conf && tmux refresh-client -S

状态条说明

行	内容
第 1 行	模型 · 项目 · git · 在线 · 标题 · effort
第 2 行	窗进度条 + token · 额配额 · 入/出/缓 · 轮次 · 工具 · 错误
第 3 行	最近工具 · agents · todos · GrokBuild 占比

中文标签：窗 / 额 / 入 / 出 / 缓 / 思 / 轮 / 具
英文标签：ctx / use / i / o / c / r / t / ⚙

宽度会随窗口自适应：窄窗自动减行、丢次要字段，避免挤出屏外。
会话开启时约每秒刷新。

配置

文件：~/.grok/hud/config.json

预设	行数	内容
full（默认）	3	全部信息
essential	2	模型/git + 上下文/配额 + 活动
minimal	1	单行压缩

常用字段：

language：zh-Hans（默认）/ en / zh-Hant
bold: true — 粗体数值
barWidth: 14 — 进度条宽度

字号由 Terminal 字体决定，状态栏无法单独放大。

主题

HUD 跟随 Grok，不锁死某一套色：

Grok：/theme 或 ~/.grok/config.toml → [ui] theme = "…"
theme = "auto" 时：系统深色 → auto_dark_theme，浅色 → auto_light_theme
约 1 秒内重绘状态条

可选临时锁色（一般不必）：

GROK_HUD_LOCK=1 grok-build-hud --theme tokyonight
# 恢复跟随：
grok-build-hud --theme auto

浅色（如 grokday）使用纸色底 + 深字，避免白底看不清。

插件结构

本仓库按 Grok 插件清单组织，可直接 grok plugin install .：

grok-hud/                      # Gitea 仓库目录名
├── plugin.json                # 插件清单（name / commands / skills / hooks）
├── .grok-plugin/
│   └── marketplace.json       # 本地 marketplace 元数据
├── commands/                  # 会话斜杠命令（/hud /status /settings …）
├── skills/
│   └── grok-build-hud/        # Agent 可触发的 skill 说明
├── hooks/
│   └── hooks.json             # SessionStart / PostToolUse 等注解
├── bin/                       # CLI 入口
├── src/                       # TypeScript 源码
├── scripts/install.sh         # 一键：CLI + dashboard + 插件
├── README.md                  # 中文主文档（本文件）
└── README.en.md

组件	路径	作用
Manifest	`plugin.json`	插件名、版本、组件入口
Commands	`commands/*.md`	Grok 内 `/…` 命令
Skills	`skills/*/SKILL.md`	会话技能描述
Hooks	`hooks/hooks.json`	会话生命周期注解
CLI / HUD	`bin/` + `src/`	真正画状态条与查配额

工作原理

读本机 ~/.grok/sessions/**（signals / updates / summary）
用已有 Grok 登录查配额
后台 daemon 写入 ~/.grok/hud/ 与按 tmux 会话隔离的状态文件
同窗口 tmux 状态栏 展示

不上传你的代码。

卸载

# 状态条 + shell hooks
grok-build-hud --uninstall-dashboard
grok-build-hud --uninstall-hooks

# Grok 插件
grok plugin uninstall grok-build-hud

# CLI（若用过 npm link）
npm unlink -g grok-build-hud

可选删除：~/.grok/hud/、~/.grok/hooks/grok-build-hud.json。

常见问题

现象	处理
`command not found`	检查 PATH；或 `node bin/grok-hud.js status`
底部没有状态条	用 `grok` 启动；已装 tmux；执行 `bash scripts/install.sh` 或 `--install-dashboard`
只有斜杠命令没有底栏	只装了插件；请再跑 dashboard 安装
插件未出现	`grok plugin list`；`grok plugin enable grok-build-hud`；`/hooks` → `r`
配额显示 `—`	先 `grok login`，再 `grok-hud status`
颜色不对	`grok-build-hud --theme auto`，与 Grok 主题一致
状态不更新	`grok-hud stop` 后重新 `grok`
多终端串会话	更新到新版；每标签独立 `grok`
字太小	放大 Terminal 字体；保持 `bold` / `barWidth`
`build missing`	`npm install && npm run build` 后再装插件

开发

npm install
npm test          # 编译 + 单元测试
npm run build
npm run plugin:validate   # 需本机有 grok CLI

Commit message 用英文
用户文档以中文 README 为主，英文见 README.en.md
贡献说明：CONTRIBUTING.md

License

MIT。第三方工具，与 xAI 无官方从属关系；配额接口以 xAI 实际 API 为准，可能变更。

9.9 KiB Raw Blame History Unescape Escape