Make Chinese README primary; ship English as README.en.md
Restructure docs so README.md is full Chinese documentation with TOC. English content moves to README.en.md; drop README.zh-CN.md. Align CONTRIBUTING, install script, package/plugin descriptions, and skill links.
This commit is contained in:
@@ -1,5 +1,12 @@
|
|||||||
# Changelog
|
# Changelog
|
||||||
|
|
||||||
|
## 0.3.10
|
||||||
|
|
||||||
|
### Docs / repo
|
||||||
|
- **中文 README 为主**：`README.md` 为完整中文文档；英文移至 `README.en.md`。
|
||||||
|
- 删除 `README.zh-CN.md`，避免双主文档分叉。
|
||||||
|
- CONTRIBUTING、package/plugin 描述、skill 链接同步中文优先。
|
||||||
|
|
||||||
## 0.3.9
|
## 0.3.9
|
||||||
|
|
||||||
### Docs / positioning
|
### Docs / positioning
|
||||||
|
|||||||
+22
-18
@@ -1,6 +1,8 @@
|
|||||||
# Contributing
|
# 贡献指南
|
||||||
|
|
||||||
## Setup
|
> English notes: keep commit messages in English. Primary docs are Chinese ([README.md](./README.md)); English summary: [README.en.md](./README.en.md).
|
||||||
|
|
||||||
|
## 环境
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
|
git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
|
||||||
@@ -9,29 +11,31 @@ npm install
|
|||||||
npm test
|
npm test
|
||||||
```
|
```
|
||||||
|
|
||||||
## Layout
|
## 目录结构
|
||||||
|
|
||||||
| Path | Role |
|
| 路径 | 作用 |
|
||||||
|------|------|
|
|------|------|
|
||||||
| `src/` | TypeScript sources (session, billing, status, tmux, theme, CLI) |
|
| `src/` | TypeScript 源码（session、billing、status、tmux、theme、CLI） |
|
||||||
| `bin/` | CLI entrypoints (`grok-build-hud`, `grok-hud`, `grok-hud-run`, hook) |
|
| `bin/` | 入口：`grok-build-hud`、`grok-hud`、`grok-hud-run`、hook |
|
||||||
| `tests/` | Node built-in test runner (`node --test`) |
|
| `tests/` | Node 内置测试 (`node --test`) |
|
||||||
| `fixtures/` | Session + billing samples for tests |
|
| `fixtures/` | 测试用 session / billing 样例 |
|
||||||
| `commands/` / `skills/` | Grok plugin surface |
|
| `commands/` / `skills/` | Grok 插件表面 |
|
||||||
| `scripts/install.sh` | One-shot local install |
|
| `scripts/install.sh` | 一键安装 |
|
||||||
|
| `README.md` | **中文主文档** |
|
||||||
|
| `README.en.md` | 英文简版 |
|
||||||
|
|
||||||
## Rules of thumb
|
## 约定
|
||||||
|
|
||||||
- Prefer reading **local** `~/.grok/sessions/**` over inventing APIs.
|
- 优先读本机 `~/.grok/sessions/**`，不臆造 API
|
||||||
- Billing must **degrade gracefully** when offline / unauthenticated (never throw in render path).
|
- 配额接口离线 / 未登录时**优雅降级**（渲染路径不抛错）
|
||||||
- Keep the HUD **same-window** (tmux status). Do not require a second Terminal window by default.
|
- HUD 保持**同窗口**（tmux status），默认不另开 Terminal
|
||||||
- Add or update a test when changing parse/normalize/render behaviour.
|
- 改解析 / 渲染逻辑请补测试
|
||||||
- Commit messages in English; user-facing docs may be EN + ZH.
|
- **Commit message 用英文**；用户文档以中文为主
|
||||||
|
|
||||||
## Before a PR
|
## 提交前
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm test
|
npm test
|
||||||
```
|
```
|
||||||
|
|
||||||
All 40 tests should pass.
|
全部测试通过后再 push。
|
||||||
|
|||||||
+125
@@ -0,0 +1,125 @@
|
|||||||
|
# grok-hud
|
||||||
|
|
||||||
|
**Live multi-line status strip for [Grok Build](https://x.ai/cli)**
|
||||||
|
|
||||||
|
> 中文文档（主 README）：[README.md](./README.md)
|
||||||
|
|
||||||
|
Always-on strip at the bottom of the **same Terminal tab** (tmux status — not a second window):
|
||||||
|
|
||||||
|
```text
|
||||||
|
Grok 4.5 · my-project · ●
|
||||||
|
ctx ██████░░░░ 50% (252k/500k) · i … o … c 99% · use 24% · t7 · ⚙212
|
||||||
|
◐ read_file… · ✓ grep ×3 · ▸ todos
|
||||||
|
```
|
||||||
|
|
||||||
|
| Feature | Description |
|
||||||
|
|---------|-------------|
|
||||||
|
| Context | Window % and token counts |
|
||||||
|
| Quota | Weekly/monthly usage (`grok login` required) |
|
||||||
|
| Tokens | Input / output / cache / reasoning from `turn_completed` |
|
||||||
|
| Activity | Tools, agents, todos |
|
||||||
|
| Theme | Follows Grok `[ui].theme` (not locked) |
|
||||||
|
| Multi-terminal | Independent session per tab |
|
||||||
|
| Language | Default **简体中文**; English / 繁體 available |
|
||||||
|
|
||||||
|
Repo: http://172.238.15.154:3000/Redredchen01/grok-hud
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Node.js 18+
|
||||||
|
- tmux (`brew install tmux` on macOS)
|
||||||
|
- Grok Build signed in (`grok login`)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Install
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
|
||||||
|
cd grok-hud
|
||||||
|
bash scripts/install.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
Or:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install && npm run build && npm link
|
||||||
|
npm run install-local
|
||||||
|
```
|
||||||
|
|
||||||
|
Optional plugin:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grok plugin install . --trust
|
||||||
|
grok plugin enable grok-build-hud
|
||||||
|
```
|
||||||
|
|
||||||
|
PATH (if commands missing):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$PATH"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Daily use
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grok # Grok + bottom HUD (same tab)
|
||||||
|
GROK_NO_HUD=1 grok -p "hi" # bare CLI
|
||||||
|
grok-hud status
|
||||||
|
grok-hud settings # language / preset / rows
|
||||||
|
grok-hud lang en # English labels
|
||||||
|
grok-hud lang zh # 简体中文 (default)
|
||||||
|
grok-build-hud --theme auto # follow Grok theme
|
||||||
|
grok-hud stop
|
||||||
|
```
|
||||||
|
|
||||||
|
Each Terminal tab gets an **independent** Grok session (unique tmux name).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
`~/.grok/hud/config.json`
|
||||||
|
|
||||||
|
| Preset | Rows | Contents |
|
||||||
|
|--------|------|----------|
|
||||||
|
| **full** (default) | 3 | All fields |
|
||||||
|
| **essential** | 2 | Model/git + context/usage + activity |
|
||||||
|
| **minimal** | 1 | Dense single row |
|
||||||
|
|
||||||
|
`language`: `zh-Hans` (default) / `en` / `zh-Hant`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How it works
|
||||||
|
|
||||||
|
Reads local `~/.grok/sessions/**`, uses existing Grok auth for billing, writes status files under `~/.grok/hud/`, displays via same-window tmux. Does **not** upload your code.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Uninstall
|
||||||
|
|
||||||
|
```bash
|
||||||
|
grok-build-hud --uninstall-dashboard
|
||||||
|
grok-build-hud --uninstall-hooks
|
||||||
|
npm unlink -g grok-build-hud
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Develop
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
Primary documentation is **Chinese** ([README.md](./README.md)). Commit messages in English.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT. Unofficial third-party tool; not affiliated with xAI.
|
||||||
@@ -1,33 +1,61 @@
|
|||||||
# grok-build-hud
|
# grok-hud
|
||||||
|
|
||||||
**Live multi-line status strip for [Grok Build](https://x.ai/cli).**
|
**[Grok Build](https://x.ai/cli) 实时多行状态条**
|
||||||
|
|
||||||
> 中文安装与使用说明：[README.zh-CN.md](./README.zh-CN.md)
|
> English: [README.en.md](./README.en.md)
|
||||||
|
|
||||||
Always-on strip in the **same Terminal window** (tmux status — not a second window):
|
在**同一个 Terminal 标签页底部**常驻显示（tmux 状态栏，**不另开窗口**）：
|
||||||
|
|
||||||
```text
|
```text
|
||||||
[Grok 4.5] · my-project git:(main*) · ●
|
Grok 4.5 · AI FILM SPACE/0717 · ●
|
||||||
窗/ctx ██████████░░░░ 70% (351k/500k) · 入/i · 出/o · 缓/c · 额/use 23% · 轮/t 16
|
窗 ██████░░░░ 50% (252k/500k) · 入 2,189,879 出 9,468 缓 2,172,032 99% · 额 24% · 轮7 · 具212
|
||||||
◐ read_file… · ✓ grep ×3 · ▸ todos
|
◐ read_file… · ✓ grep ×3 · ▸ 待办
|
||||||
```
|
```
|
||||||
|
|
||||||
Built for Grok Build sessions: context window, quota, **input/output/cache tokens**, tools, todos, git — with Chinese/English UI and theme follow.
|
| 能力 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| 上下文 | 窗口占用 % 与 token 数 |
|
||||||
|
| 配额 | 周/月用量（需已 `grok login`） |
|
||||||
|
| Token 明细 | 入 / 出 / 缓存 / 推理（来自会话 `turn_completed`） |
|
||||||
|
| 活动 | 工具、agent、todos |
|
||||||
|
| 主题 | 跟随 Grok `[ui].theme`，不锁死 |
|
||||||
|
| 多终端 | 每个标签页**独立** session，互不串线 |
|
||||||
|
| 语言 | 默认**简体中文**，可切英文 / 繁體 |
|
||||||
|
|
||||||
|
仓库：http://172.238.15.154:3000/Redredchen01/grok-hud
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Requirements
|
## 目录
|
||||||
|
|
||||||
- **Node.js 18+**
|
1. [依赖](#依赖)
|
||||||
- **tmux** (`brew install tmux` on macOS)
|
2. [安装](#安装)
|
||||||
- **Grok Build** CLI signed in (`grok login`)
|
3. [日常使用](#日常使用)
|
||||||
- Any terminal that can host tmux (tested on Apple Terminal / iTerm)
|
4. [设定（语言 / 预设）](#设定语言--预设)
|
||||||
|
5. [状态条说明](#状态条说明)
|
||||||
|
6. [配置](#配置)
|
||||||
|
7. [主题](#主题)
|
||||||
|
8. [工作原理](#工作原理)
|
||||||
|
9. [卸载](#卸载)
|
||||||
|
10. [常见问题](#常见问题)
|
||||||
|
11. [开发](#开发)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Install
|
## 依赖
|
||||||
|
|
||||||
### A. One-shot script (recommended)
|
| 依赖 | 说明 |
|
||||||
|
|------|------|
|
||||||
|
| **Node.js 18+** | `node -v` |
|
||||||
|
| **tmux** | macOS：`brew install tmux` |
|
||||||
|
| **Grok Build** | 已登录：`grok login` |
|
||||||
|
| 终端 | Terminal / iTerm 等（在 tmux 内运行即可） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 安装
|
||||||
|
|
||||||
|
### 方式 A：从 Gitea 克隆（推荐）
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
|
git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
|
||||||
@@ -35,76 +63,91 @@ cd grok-hud
|
|||||||
bash scripts/install.sh
|
bash scripts/install.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
This runs `npm install` → `build` → `npm link` → dashboard + hooks → `--theme auto` → `--preset full`.
|
会自动：`npm install` → 编译 → `npm link` → 装 dashboard / hooks → 主题跟随 → 预设 full → 语言中文。
|
||||||
|
|
||||||
### B. Manual steps
|
### 方式 B：已有源码目录
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
|
|
||||||
cd grok-hud
|
|
||||||
npm install
|
|
||||||
npm run build
|
|
||||||
npm link # puts grok-build-hud / grok-hud / grok-hud-run on PATH
|
|
||||||
npm run install-local
|
|
||||||
```
|
|
||||||
|
|
||||||
### C. From an already-cloned path
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd /path/to/grok-hud
|
cd /path/to/grok-hud
|
||||||
bash scripts/install.sh
|
bash scripts/install.sh
|
||||||
|
# 或：
|
||||||
|
npm install && npm run build && npm link
|
||||||
|
npm run install-local
|
||||||
```
|
```
|
||||||
|
|
||||||
### D. As a Grok plugin (optional)
|
### 方式 C：作为 Grok 插件（可选）
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd /path/to/grok-build-hud
|
cd /path/to/grok-hud
|
||||||
npm install && npm run build
|
npm install && npm run build
|
||||||
grok plugin install . --trust
|
grok plugin install . --trust
|
||||||
grok plugin enable grok-build-hud
|
grok plugin enable grok-build-hud
|
||||||
```
|
```
|
||||||
|
|
||||||
In Grok: `/hooks` → press `r` to reload.
|
在 Grok 内执行 `/hooks` 后按 `r` 重载 hooks。
|
||||||
|
|
||||||
### PATH fix (`command not found`)
|
### 命令找不到时
|
||||||
|
|
||||||
|
写入 `~/.zshrc`：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# add to ~/.zshrc or ~/.bashrc
|
|
||||||
export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$PATH"
|
export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$PATH"
|
||||||
```
|
```
|
||||||
|
|
||||||
Then `source ~/.zshrc` and verify: `which grok-hud-run`.
|
然后：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source ~/.zshrc
|
||||||
|
which grok-hud
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Daily use (same window — no second pane)
|
## 日常使用
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Start Grok with the multi-line HUD at the bottom of THIS tab
|
# 1. 打开 Terminal（会自动确保 HUD 后台更新器）
|
||||||
|
# 2. 输入：
|
||||||
grok
|
grok
|
||||||
# (or: grok-hud-run)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
| Row | Content |
|
底部即出现状态条。
|
||||||
|-----|---------|
|
|
||||||
| 1 | Model · project · git · live · title · effort |
|
|
||||||
| 2 | **Context** bar + tokens · **Usage/quota** · time · turns · tools · errors · diff |
|
|
||||||
| 3 | Tool activity · agents · todos · GrokBuild product share |
|
|
||||||
|
|
||||||
The strip refreshes about once per second while the session is open.
|
|
||||||
|
|
||||||
### Useful commands
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
grok-build-hud --once --follow-active # print full HUD once
|
# 不要 HUD 的裸命令（脚本 / 打印模式）
|
||||||
grok-hud status # same
|
GROK_NO_HUD=1 grok -p "hello"
|
||||||
grok-hud stop # stop background updater
|
|
||||||
grok-build-hud --preset full|essential|minimal
|
# 兼容旧入口
|
||||||
grok-build-hud --theme auto # follow Grok [ui].theme
|
grok-hud-run
|
||||||
grok-build-hud --theme tokyonight # lock palette
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Refresh tmux after config change
|
**生命周期**：开 **Terminal** 即就绪；不是电脑开机自启。
|
||||||
|
**并行开发**：每个标签页独立 Grok session，各自 `grok` 即可。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 设定（语言 / 预设）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 交互设定（默认界面为中文）
|
||||||
|
grok-hud settings
|
||||||
|
|
||||||
|
# 快捷切语言
|
||||||
|
grok-hud lang zh # 简体中文（默认）
|
||||||
|
grok-hud lang en # English
|
||||||
|
grok-hud lang tw # 繁體中文
|
||||||
|
```
|
||||||
|
|
||||||
|
| 命令 | 作用 |
|
||||||
|
|------|------|
|
||||||
|
| `grok-hud status` | 打印当前完整状态一次 |
|
||||||
|
| `grok-hud stop` | 停后台刷新 |
|
||||||
|
| `grok-build-hud --preset full` | 三行全开（默认） |
|
||||||
|
| `grok-build-hud --preset essential` | 两行 |
|
||||||
|
| `grok-build-hud --preset minimal` | 一行 |
|
||||||
|
| `grok-build-hud --theme auto` | 跟随 Grok 主题（推荐） |
|
||||||
|
|
||||||
|
改完配置后若条未变，在 tmux 内：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
tmux source-file ~/.grok/hud/tmux.conf && tmux refresh-client -S
|
tmux source-file ~/.grok/hud/tmux.conf && tmux refresh-client -S
|
||||||
@@ -112,138 +155,113 @@ tmux source-file ~/.grok/hud/tmux.conf && tmux refresh-client -S
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Configuration
|
## 状态条说明
|
||||||
|
|
||||||
### Display preset & toggles
|
| 行 | 内容 |
|
||||||
|
|----|------|
|
||||||
|
| 第 1 行 | 模型 · 项目 · git · 在线 · 标题 · effort |
|
||||||
|
| 第 2 行 | **窗**进度条 + token · **额**配额 · 入/出/缓 · 轮次 · 工具 · 错误 |
|
||||||
|
| 第 3 行 | 最近工具 · agents · todos · GrokBuild 占比 |
|
||||||
|
|
||||||
`~/.grok/hud/config.json`
|
中文标签：`窗 / 额 / 入 / 出 / 缓 / 思 / 轮 / 具`
|
||||||
|
英文标签：`ctx / use / i / o / c / r / t / ⚙`
|
||||||
|
|
||||||
| Preset | Rows | Contents |
|
宽度会随窗口自适应：窄窗自动减行、丢次要字段，避免挤出屏外。
|
||||||
|--------|------|----------|
|
|
||||||
| **full** (default) | 3 | Everything |
|
|
||||||
| **essential** | 2 | Model/git + context/usage + activity |
|
|
||||||
| **minimal** | 1 | Dense single row |
|
|
||||||
|
|
||||||
Key options:
|
会话开启时约每秒刷新。
|
||||||
|
|
||||||
```json
|
---
|
||||||
{
|
|
||||||
"preset": "full",
|
|
||||||
"statusLines": 3,
|
|
||||||
"bold": true,
|
|
||||||
"barWidth": 14,
|
|
||||||
"pathLevels": 2,
|
|
||||||
"display": {
|
|
||||||
"showContextBar": true,
|
|
||||||
"contextValue": "both",
|
|
||||||
"showUsage": true,
|
|
||||||
"showToolActivity": true,
|
|
||||||
"showTodos": true,
|
|
||||||
"showAgents": true,
|
|
||||||
"showDiffStats": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Theme (matches Grok UI)
|
## 配置
|
||||||
|
|
||||||
Reads `~/.grok/config.toml`:
|
文件：`~/.grok/hud/config.json`
|
||||||
|
|
||||||
```toml
|
| 预设 | 行数 | 内容 |
|
||||||
[ui]
|
|------|------|------|
|
||||||
theme = "tokyonight" # also: groknight, grokday, rosepinemoon, oscuramindnight, auto
|
| **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 秒内重绘状态条
|
||||||
|
|
||||||
|
可选临时锁色（一般不必）：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
grok-build-hud --theme auto # follow Grok config (default)
|
GROK_HUD_LOCK=1 grok-build-hud --theme tokyonight
|
||||||
|
# 恢复跟随：
|
||||||
|
grok-build-hud --theme auto
|
||||||
```
|
```
|
||||||
|
|
||||||
### Readability
|
浅色（如 grokday）使用纸色底 + 深字，避免白底看不清。
|
||||||
|
|
||||||
- `bold: true` — bold values (default)
|
|
||||||
- `barWidth: 14` — thicker progress bars
|
|
||||||
|
|
||||||
True **font size** is Terminal’s font (tmux cannot set a separate size for the status strip).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## How it works
|
## 工作原理
|
||||||
|
|
||||||
```text
|
1. 读本机 `~/.grok/sessions/**`（signals / updates / summary）
|
||||||
Grok sessions ──► ~/.grok/sessions/**/signals.json
|
2. 用已有 Grok 登录查配额
|
||||||
──► updates.jsonl (tools / agents / todos)
|
3. 后台 daemon 写入 `~/.grok/hud/` 与按 tmux 会话隔离的状态文件
|
||||||
──► summary.json (title, effort, model)
|
4. 同窗口 **tmux 状态栏** 展示
|
||||||
auth.json ──► cli-chat-proxy billing (weekly quota + monthly)
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
dashboard daemon (~500ms)
|
|
||||||
│
|
|
||||||
┌───────────┼───────────┐
|
|
||||||
▼ ▼ ▼
|
|
||||||
tmux-lines.txt status.txt hooks annotations
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
same-window tmux status (1–3 rows)
|
|
||||||
```
|
|
||||||
|
|
||||||
No second window. No cloud upload of your code by this tool (read-only local session files + your existing Grok auth for billing).
|
**不上传**你的代码。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Settings (language)
|
## 卸载
|
||||||
|
|
||||||
```bash
|
|
||||||
grok-hud settings # interactive UI
|
|
||||||
grok-hud lang zh # 简体中文 (default)
|
|
||||||
grok-hud lang en # English
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Uninstall
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
grok-build-hud --uninstall-dashboard
|
grok-build-hud --uninstall-dashboard
|
||||||
grok-build-hud --uninstall-hooks
|
grok-build-hud --uninstall-hooks
|
||||||
npm unlink -g grok-build-hud # if you used npm link
|
npm unlink -g grok-build-hud # 若用过 npm link
|
||||||
```
|
```
|
||||||
|
|
||||||
Optional cleanup: `~/.grok/hud/`, `~/.grok/hooks/grok-build-hud.json`.
|
可选删除：`~/.grok/hud/`、`~/.grok/hooks/grok-build-hud.json`。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Troubleshooting
|
## 常见问题
|
||||||
|
|
||||||
| Symptom | Fix |
|
| 现象 | 处理 |
|
||||||
|---------|-----|
|
|------|------|
|
||||||
| `command not found` | Fix PATH (above) or run `node bin/grok-hud-run.js` |
|
| `command not found` | 检查 PATH；或 `node bin/grok-hud.js status` |
|
||||||
| No bottom strip | Use `grok-hud-run`; install tmux; re-run `--install-dashboard` |
|
| 底部没有状态条 | 用 `grok` 启动；已装 tmux；执行 `--install-dashboard` |
|
||||||
| Usage shows `—` | `grok login`, then `grok-hud status` |
|
| 配额显示 `—` | 先 `grok login`，再 `grok-hud status` |
|
||||||
| Colors clash with TUI | `grok-build-hud --theme auto` |
|
| 颜色不对 | `grok-build-hud --theme auto`，与 Grok 主题一致 |
|
||||||
| Stale numbers | `grok-hud stop` then `grok-hud-run` |
|
| 状态不更新 | `grok-hud stop` 后重新 `grok` |
|
||||||
| Text too small | Increase Terminal font; keep `bold` / `barWidth` |
|
| 多终端串会话 | 更新到新版；每标签独立 `grok`，勿共用旧 `grok-hud` tmux 名 |
|
||||||
|
| 字太小 | 放大 Terminal 字体；保持 `bold` / `barWidth` |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Development
|
## 开发
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install
|
npm install
|
||||||
npm test # build + 40 unit tests
|
npm test # 编译 + 单元测试
|
||||||
npm run build
|
npm run build
|
||||||
grok plugin validate . # if Grok CLI is available
|
|
||||||
```
|
```
|
||||||
|
|
||||||
See [CHANGELOG.md](./CHANGELOG.md) and [CONTRIBUTING.md](./CONTRIBUTING.md).
|
- Commit message 用英文
|
||||||
|
- 用户文档以**中文 README 为主**，英文见 [README.en.md](./README.en.md)
|
||||||
|
- 贡献说明：[CONTRIBUTING.md](./CONTRIBUTING.md)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT
|
MIT。第三方工具，与 xAI 无官方从属关系；配额接口以 xAI 实际 API 为准，可能变更。
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Disclaimer
|
|
||||||
|
|
||||||
Third-party tool. Billing/quota display depends on xAI session auth and API shapes that may change. Not affiliated with xAI.
|
|
||||||
|
|||||||
-205
@@ -1,205 +0,0 @@
|
|||||||
# grok-build-hud
|
|
||||||
|
|
||||||
**[Grok Build](https://x.ai/cli) 的实时多行状态条。**
|
|
||||||
|
|
||||||
在**同一个 Terminal 窗口底部**常驻显示（tmux 状态栏，不另开窗口）：
|
|
||||||
|
|
||||||
```text
|
|
||||||
[Grok 4.5] · my-project git · ●
|
|
||||||
窗 ██████░░░░ 70% (351k/500k) · 入 … 出 … 缓 … · 额 23% · 轮 16
|
|
||||||
◐ read_file… · ✓ grep ×3 · ▸ todos
|
|
||||||
```
|
|
||||||
|
|
||||||
专为 Grok Build 会话设计：上下文窗口、配额、**入/出/缓存 token**、工具、待办、git；支持中英文 UI，主题跟随 Grok。
|
|
||||||
|
|
||||||
中文说明见本页；英文见 [README.md](./README.md)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 需要什么
|
|
||||||
|
|
||||||
| 依赖 | 说明 |
|
|
||||||
|------|------|
|
|
||||||
| **Node.js 18+** | `node -v` 检查 |
|
|
||||||
| **tmux** | macOS：`brew install tmux` |
|
|
||||||
| **Grok Build** | 已登录：`grok login` |
|
|
||||||
| 终端 | Apple Terminal / iTerm 等（在 tmux 里跑） |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 安装（三选一）
|
|
||||||
|
|
||||||
### 方式 A：从 GitHub 克隆（推荐别人安装时用）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
|
|
||||||
cd grok-hud
|
|
||||||
bash scripts/install.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
`install.sh` 会自动：`npm install` → 编译 → `npm link` → 装 dashboard/hooks → 主题 auto → preset full。
|
|
||||||
|
|
||||||
### 方式 B：本机已有源码目录
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd /path/to/grok-build-hud
|
|
||||||
bash scripts/install.sh
|
|
||||||
# 或分步：
|
|
||||||
npm install && npm run build && npm link
|
|
||||||
npm run install-local
|
|
||||||
```
|
|
||||||
|
|
||||||
### 方式 C：当 Grok 插件（可选）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd /path/to/grok-build-hud
|
|
||||||
npm install && npm run build
|
|
||||||
grok plugin install . --trust
|
|
||||||
grok plugin enable grok-build-hud
|
|
||||||
```
|
|
||||||
|
|
||||||
在 Grok 里执行 `/hooks` 后按 `r` 重载 hooks。
|
|
||||||
|
|
||||||
### 命令找不到时
|
|
||||||
|
|
||||||
把 npm 全局 bin 和 `~/.local/bin` 放进 PATH（写进 `~/.zshrc`）：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export PATH="$(npm prefix -g)/bin:$HOME/.local/bin:$PATH"
|
|
||||||
```
|
|
||||||
|
|
||||||
然后 `source ~/.zshrc`，再试 `which grok-hud-run`。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 日常使用
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 1) 打开 Terminal（会自动确保 HUD 后台更新器）
|
|
||||||
# 2) 直接输入：
|
|
||||||
grok
|
|
||||||
|
|
||||||
# 底部状态条会显示：
|
|
||||||
# CTX … │ TOK IN 974,820 · OUT 15,706 · CACHE 944,000 (97%) │ USE …
|
|
||||||
# （input / output / cache 精确数字，来自本会话 turn_completed）
|
|
||||||
|
|
||||||
# 不要 HUD 的裸命令（脚本 / -p 打印模式）
|
|
||||||
GROK_NO_HUD=1 grok -p "hello"
|
|
||||||
|
|
||||||
# 旧名字仍然可用
|
|
||||||
grok-hud-run
|
|
||||||
```
|
|
||||||
|
|
||||||
**生命周期**：开 **Terminal** 就绪，不是电脑开机自启。
|
|
||||||
`~/.zshrc` 里会装一段 interactive hook；输入 `grok` 即带 HUD。
|
|
||||||
|
|
||||||
**并行开发**：每个 Terminal 标签页是**独立** Grok session（独立 tmux 名，互不 attach）。
|
|
||||||
多开几个终端，各自 `grok` 即可同时干活，不会串会话。
|
|
||||||
|
|
||||||
## 设定（语言 / 预设）
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 交互设定界面（默认中文）
|
|
||||||
grok-hud settings
|
|
||||||
|
|
||||||
# 快捷切换语言
|
|
||||||
grok-hud lang zh # 简体中文（默认）
|
|
||||||
grok-hud lang en # English
|
|
||||||
grok-hud lang tw # 繁體中文
|
|
||||||
```
|
|
||||||
|
|
||||||
状态条标签会跟着语言变：中文 `窗/额/入/出/缓`，英文 `ctx/use/i/o/c`。
|
|
||||||
|
|
||||||
| 行 | 内容 |
|
|
||||||
|----|------|
|
|
||||||
| 第 1 行 | 模型 · 项目 · git · 是否在线 · 标题 · effort |
|
|
||||||
| 第 2 行 | **上下文**进度条 + token · **配额** · 时长 · 轮次 · 工具数 · 错误 · diff |
|
|
||||||
| 第 3 行 | 最近工具 · agents · todos · GrokBuild 用量占比 |
|
|
||||||
|
|
||||||
会话开着时，状态条约每秒刷新一次。
|
|
||||||
|
|
||||||
### 常用命令
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grok-hud status # 打印当前完整 HUD 一次
|
|
||||||
grok-build-hud --once --follow-active # 同上
|
|
||||||
grok-hud stop # 停后台刷新
|
|
||||||
grok-build-hud --preset full # 三行全开（默认）
|
|
||||||
grok-build-hud --preset essential # 两行
|
|
||||||
grok-build-hud --preset minimal # 一行精简
|
|
||||||
grok-build-hud --theme auto # 跟随 Grok 主题（推荐）
|
|
||||||
grok-build-hud --theme tokyonight # 锁定某套色
|
|
||||||
```
|
|
||||||
|
|
||||||
改完 preset/theme 后若条没变，在 tmux 里：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
tmux source-file ~/.grok/hud/tmux.conf && tmux refresh-client -S
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 配置
|
|
||||||
|
|
||||||
配置文件：`~/.grok/hud/config.json`
|
|
||||||
|
|
||||||
| Preset | 行数 | 内容 |
|
|
||||||
|--------|------|------|
|
|
||||||
| **full**（默认） | 3 | 全部信息 |
|
|
||||||
| **essential** | 2 | 模型/git + 上下文/配额 + 活动 |
|
|
||||||
| **minimal** | 1 | 单行压缩 |
|
|
||||||
|
|
||||||
可读性相关：
|
|
||||||
|
|
||||||
- `bold: true` — 粗体数值（默认开）
|
|
||||||
- `barWidth: 14` — 进度条宽度
|
|
||||||
字号由 Terminal 字体决定，tmux 状态栏不能单独放大。
|
|
||||||
|
|
||||||
主题跟 Grok：`~/.grok/config.toml` 里 `[ui] theme = "tokyonight"` 等；HUD 用 `--theme auto` 会跟着走。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 工作原理（一句话）
|
|
||||||
|
|
||||||
读本机 `~/.grok/sessions/**` 的 signals / updates / summary，用你已有的 Grok 登录去查周配额；后台 daemon 写状态文件，由 **同窗口 tmux 状态栏**显示。不上传你的代码。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 卸载
|
|
||||||
|
|
||||||
```bash
|
|
||||||
grok-build-hud --uninstall-dashboard
|
|
||||||
grok-build-hud --uninstall-hooks
|
|
||||||
npm unlink -g grok-build-hud # 若用过 npm link
|
|
||||||
```
|
|
||||||
|
|
||||||
可选删除：`~/.grok/hud/`、`~/.grok/hooks/grok-build-hud.json`。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 常见问题
|
|
||||||
|
|
||||||
| 现象 | 处理 |
|
|
||||||
|------|------|
|
|
||||||
| `command not found: grok-hud-run` | 检查 PATH（见上文）；或用 `node bin/grok-hud-run.js` |
|
|
||||||
| 底部没有状态条 | 确认用 `grok-hud-run` 启动；本机已装 tmux；`grok-build-hud --install-dashboard` |
|
|
||||||
| 配额显示 `—` / n/a | 先 `grok login`；再 `grok-hud status` 看是否有 weekly |
|
|
||||||
| 颜色和 Grok 界面打架 | `grok-build-hud --theme auto`，并与 Grok `[ui].theme` 一致 |
|
|
||||||
| 状态条不更新 | `grok-hud stop` 后 `grok-hud-run`；或 `ensure` 用 `--dashboard-start` |
|
|
||||||
| 字太小 | 放大 Terminal 字体；配置里 `bold`/`barWidth` 已尽量加粗加宽 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 开发
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm install
|
|
||||||
npm test # 编译 + 40 个单元测试
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
MIT。第三方工具，与 xAI 无官方从属关系；配额接口以 xAI 实际 API 为准，可能变更。
|
|
||||||
+3
-3
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"name": "grok-build-hud",
|
"name": "grok-build-hud",
|
||||||
"version": "0.3.9",
|
"version": "0.3.10",
|
||||||
"description": "Live multi-line status strip for Grok Build: context, quota, tokens, tools, todos, git — same-window tmux bar with theme sync and Chinese/English UI",
|
"description": "Grok Build 实时多行状态条：上下文、配额、入出缓存 token、工具与待办；同窗口 tmux、主题跟随、中英文 UI",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"main": "dist/src/index.js",
|
"main": "dist/src/index.js",
|
||||||
"bin": {
|
"bin": {
|
||||||
@@ -18,7 +18,7 @@
|
|||||||
"plugin.json",
|
"plugin.json",
|
||||||
".grok-plugin/",
|
".grok-plugin/",
|
||||||
"README.md",
|
"README.md",
|
||||||
"README.zh-CN.md",
|
"README.en.md",
|
||||||
"CHANGELOG.md",
|
"CHANGELOG.md",
|
||||||
"LICENSE",
|
"LICENSE",
|
||||||
"scripts/",
|
"scripts/",
|
||||||
|
|||||||
+2
-2
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"name": "grok-build-hud",
|
"name": "grok-build-hud",
|
||||||
"version": "0.3.9",
|
"version": "0.3.10",
|
||||||
"description": "Live multi-line status strip for Grok Build: context, quota, tokens, tools, todos, git",
|
"description": "Grok Build 实时状态条：上下文、配额、token、工具、待办（同窗口 tmux）",
|
||||||
"author": {
|
"author": {
|
||||||
"name": "Redredchen01"
|
"name": "Redredchen01"
|
||||||
},
|
},
|
||||||
|
|||||||
+13
-12
@@ -28,30 +28,31 @@ if [[ "$NODE_MAJOR" -lt 18 ]]; then
|
|||||||
exit 1
|
exit 1
|
||||||
fi
|
fi
|
||||||
|
|
||||||
echo "==> Installing dependencies"
|
echo "==> 安装依赖"
|
||||||
npm install
|
npm install
|
||||||
|
|
||||||
echo "==> Building"
|
echo "==> 编译"
|
||||||
npm run build
|
npm run build
|
||||||
|
|
||||||
echo "==> Linking CLI onto PATH (npm link)"
|
echo "==> 链接 CLI 到 PATH (npm link)"
|
||||||
npm link
|
npm link
|
||||||
|
|
||||||
echo "==> Installing dashboard (hooks + tmux conf + shims)"
|
echo "==> 安装 dashboard（hooks + tmux + shims）"
|
||||||
node bin/grok-build-hud.js --install-dashboard
|
node bin/grok-build-hud.js --install-dashboard
|
||||||
node bin/grok-build-hud.js --theme auto
|
node bin/grok-build-hud.js --theme auto
|
||||||
node bin/grok-build-hud.js --preset full
|
node bin/grok-build-hud.js --preset full
|
||||||
|
|
||||||
echo ""
|
echo ""
|
||||||
VER="$(node -e "import('node:fs').then(fs=>console.log(JSON.parse(fs.readFileSync('package.json','utf8')).version))" 2>/dev/null || echo 0.3.0)"
|
VER="$(node -e "import('node:fs').then(fs=>console.log(JSON.parse(fs.readFileSync('package.json','utf8')).version))" 2>/dev/null || echo 0.3.0)"
|
||||||
echo "Done. grok-build-hud v${VER}"
|
echo "完成。grok-build-hud v${VER}"
|
||||||
echo ""
|
echo ""
|
||||||
echo " Start Grok with HUD (same window): grok-hud-run"
|
echo " 启动 Grok + 底部 HUD： grok"
|
||||||
echo " One-shot snapshot: grok-hud status"
|
echo " 看当前状态一次： grok-hud status"
|
||||||
echo " Preset: grok-build-hud --preset full"
|
echo " 设定（语言/预设）： grok-hud settings"
|
||||||
echo " Theme: grok-build-hud --theme auto"
|
echo " 主题跟随 Grok： grok-build-hud --theme auto"
|
||||||
echo " Stop updater: grok-hud stop"
|
echo " 停止后台刷新： grok-hud stop"
|
||||||
echo ""
|
echo ""
|
||||||
echo "中文说明: README.zh-CN.md"
|
echo "文档（中文）：README.md"
|
||||||
echo "If command not found, add to PATH and re-open the shell:"
|
echo "English: README.en.md"
|
||||||
|
echo "若提示 command not found，把下面加入 PATH 后重开终端："
|
||||||
echo " export PATH=\"\$(npm prefix -g)/bin:\$HOME/.local/bin:\$PATH\""
|
echo " export PATH=\"\$(npm prefix -g)/bin:\$HOME/.local/bin:\$PATH\""
|
||||||
|
|||||||
@@ -1,11 +1,11 @@
|
|||||||
---
|
---
|
||||||
name: grok-build-hud
|
name: grok-build-hud
|
||||||
description: Explain and operate the Grok Build live status HUD (same-window multi-line context, quota, tokens, tools, todos, theme sync, Chinese/English settings).
|
description: Grok Build 实时状态条（同窗口多行：上下文、配额、token、工具、待办；主题跟随；中英文设定）。
|
||||||
---
|
---
|
||||||
|
|
||||||
# grok-build-hud
|
# grok-build-hud
|
||||||
|
|
||||||
Always-on status strip for **Grok Build**: multi-line bar in the **same Terminal tab** (tmux status) plus optional scrollback annotations. Reads local session files and your Grok auth for quota — no second window required.
|
**Grok Build** 同窗口实时状态条（tmux）：上下文、配额、入/出/缓存 token、工具与待办。读本机会话文件与已有登录查配额，不另开窗口。
|
||||||
|
|
||||||
## What it shows
|
## What it shows
|
||||||
|
|
||||||
@@ -48,4 +48,4 @@ grok-hud stop # stop dashboard daemon
|
|||||||
|
|
||||||
`~/.grok/hud/config.json` — language, presets, `bold`, `barWidth`, display toggles.
|
`~/.grok/hud/config.json` — language, presets, `bold`, `barWidth`, display toggles.
|
||||||
|
|
||||||
Full docs: [README.md](../../README.md) · 中文: [README.zh-CN.md](../../README.zh-CN.md)
|
文档（中文主文档）：[README.md](../../README.md) · English: [README.en.md](../../README.en.md)
|
||||||
|
|||||||
+1
-1
@@ -278,7 +278,7 @@ Theme: always tracks Grok [ui].theme (auto → OS light/dark maps).
|
|||||||
Language: default 简体中文; switch in settings or: grok-hud lang en
|
Language: default 简体中文; switch in settings or: grok-hud lang en
|
||||||
|
|
||||||
Lifecycle: Terminal open → ready (not machine boot).
|
Lifecycle: Terminal open → ready (not machine boot).
|
||||||
Docs: README.md · README.zh-CN.md
|
文档: README.md（中文）· README.en.md（English）
|
||||||
`;
|
`;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user