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.
2026-07-17 16:32:20 +08:00
parent 18c04f5874
commit e32e0df209
10 changed files with 338 additions and 388 deletions
@@ -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
-[Grok 4.5] · my-project git:(main*) · ●
-窗/ctx ██████████░░░░ 70% (351k/500k) · 入/i · 出/o · 缓/c · 额/use 23% · 轮/t 16
-◐ read_file… · ✓ grep ×3 · ▸ todos
+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 · ▸ 待办
 ```

-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+**
- **tmux** (`brew install tmux` on macOS)
- **Grok Build** CLI signed in (`grok login`)
- Any terminal that can host tmux (tested on Apple Terminal / iTerm)
+1. [依赖](#依赖)
+2. [安装](#安装)
+3. [日常使用](#日常使用)
+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
 git clone http://172.238.15.154:3000/Redredchen01/grok-hud.git
@@ -35,76 +63,91 @@ cd grok-hud
 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
-
-```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
+### 方式 B：已有源码目录

 ```bash
 cd /path/to/grok-hud
 bash scripts/install.sh
+# 或：
+npm install && npm run build && npm link
+npm run install-local
 ```

-### D. As a Grok plugin (optional)
+### 方式 C：作为 Grok 插件（可选）

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

-In Grok: `/hooks` → press `r` to reload.
+在 Grok 内执行 `/hooks` 后按 `r` 重载 hooks。

-### PATH fix (`command not found`)
+### 命令找不到时
+
+写入 `~/.zshrc`：

 ```bash
-# add to ~/.zshrc or ~/.bashrc
 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
-# Start Grok with the multi-line HUD at the bottom of THIS tab
+# 1. 打开 Terminal（会自动确保 HUD 后台更新器）
+# 2. 输入：
 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
-grok-build-hud --once --follow-active   # print full HUD once
-grok-hud status                         # same
-grok-hud stop                           # stop background updater
-grok-build-hud --preset full|essential|minimal
-grok-build-hud --theme auto             # follow Grok [ui].theme
-grok-build-hud --theme tokyonight       # lock palette
+# 不要 HUD 的裸命令（脚本 / 打印模式）
+GROK_NO_HUD=1 grok -p "hello"
+
+# 兼容旧入口
+grok-hud-run
 ```

-### 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
 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
-grok-build-hud --theme auto    # follow Grok config (default)
+GROK_HUD_LOCK=1 grok-build-hud --theme tokyonight
+# 恢复跟随：
+grok-build-hud --theme auto
 ```

-### Readability
-
- `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).
+浅色（如 grokday）使用纸色底 + 深字，避免白底看不清。

 ---

-## How it works
+## 工作原理

-```text
-Grok sessions ──► ~/.grok/sessions/**/signals.json
-              ──► updates.jsonl (tools / agents / todos)
-              ──► summary.json  (title, effort, model)
-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)
-```
+1. 读本机 `~/.grok/sessions/**`（signals / updates / summary）  
+2. 用已有 Grok 登录查配额  
+3. 后台 daemon 写入 `~/.grok/hud/` 与按 tmux 会话隔离的状态文件  
+4. 同窗口 **tmux 状态栏** 展示  

-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
 grok-build-hud --uninstall-dashboard
 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` |
-| No bottom strip | Use `grok-hud-run`; install tmux; re-run `--install-dashboard` |
-| Usage shows `—` | `grok login`, then `grok-hud status` |
-| Colors clash with TUI | `grok-build-hud --theme auto` |
-| Stale numbers | `grok-hud stop` then `grok-hud-run` |
-| Text too small | Increase Terminal font; keep `bold` / `barWidth` |
+| 现象 | 处理 |
+|------|------|
+| `command not found` | 检查 PATH；或 `node bin/grok-hud.js status` |
+| 底部没有状态条 | 用 `grok` 启动；已装 tmux；执行 `--install-dashboard` |
+| 配额显示 `—` | 先 `grok login`，再 `grok-hud status` |
+| 颜色不对 | `grok-build-hud --theme auto`，与 Grok 主题一致 |
+| 状态不更新 | `grok-hud stop` 后重新 `grok` |
+| 多终端串会话 | 更新到新版；每标签独立 `grok`，勿共用旧 `grok-hud` tmux 名 |
+| 字太小 | 放大 Terminal 字体；保持 `bold` / `barWidth` |

 ---

-## Development
+## 开发

 ```bash
 npm install
-npm test          # build + 40 unit tests
+npm test          # 编译 + 单元测试
 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

-MIT
-
---
-
-## Disclaimer
-
-Third-party tool. Billing/quota display depends on xAI session auth and API shapes that may change. Not affiliated with xAI.
+MIT。第三方工具，与 xAI 无官方从属关系；配额接口以 xAI 实际 API 为准，可能变更。