<div align="center">

# ◌ @zhcsyncer/pi-glance

[English](./README.md)

**为 [Pi](https://github.com/earendil-works/pi-mono) 提供安静、可组合的输入界面**

用圆角多行编辑器替换默认输入框，在边框中展示 Git、费用、Reply speed、context、可选 tokens 和模型，同时不隐藏其他扩展发布的状态。

本包是 [`pi-glance`](https://github.com/LinYS77/pi-glance) 0.5.3 的维护 fork，增加 StatusOnly Footer、Follow Pi 主题、右下角 context / 自动压缩详情，以及可开关的 Claude-inspired working indicator。上游 0.5.3 不包含 working indicator。

</div>

---

## 安装

```bash
pi install npm:@zhcsyncer/pi-glance
```

然后重启 Pi 或执行 `/reload`。

需要 Pi 0.80.4 或更新。

## 使用

```text
/glance
/diff
```

`/glance` 打开设置和实时输入界面预览。`/diff` 先让你选择 Working tree、Branch vs main 或 Compare revisions，再把终端临时交给可选的 [`revdiff`](https://revdiff.com/) 审阅；annotations 只回填编辑器供你确认，不会自动发送。缺少 revdiff 时，仅 `/diff` 显示安装提示。

`Ctrl+Shift+S` 收起或拿回当前输入框草稿。`Ctrl+Shift+U` 连按两次丢掉暂存。确认提示出现在输入框下方，带草稿开头，超时后消失。槽里还有未取回内容时，左边框会挂醒目的 `!stash`。同一会话 `/reload` 或 resume 后，若输入框是空的会自动倒回。

### 审阅改动

- `/diff worktree` — 审阅已暂存、未暂存和未跟踪改动。
- `/diff branch [base]` — 从基线与 HEAD 的共同祖先开始，按 MR 方式审阅。选择 **Committed only**（仅已提交）或 **Include working tree**（包含工作区及未跟踪文件）。默认基线优先使用本地已有的 `origin/main`，其次本地 `main`；`/diff` 不会 fetch。两者都不存在时请指定基线。
- `/diff compare [from] [to]` — 比较两个已提交版本的端点，不包含工作区改动。缺少的端点会打开可搜索选择器，列出本地/远端分支、tag 和 HEAD 最近 50 次提交；可按名称、SHA 或提交主题搜索，也可粘贴版本并选择 **Use typed ref/SHA**。

Fullscreen 模式下，可点击 Git 状态栏或右下边框中末尾带强调色加粗 `›` 的改动摘要，直接审阅工作区。Regular 模式请使用 `/diff worktree`。只有实际显示的摘要可点击，分支名和空白边框不是链接。

子命令支持补全。↑↓ 选择、Enter 确认，Esc 取消且不改动草稿。批注追加到回填时的当前草稿（空编辑器则直接填入）；取消或没有批注时不改动草稿。审阅需要空闲的 Pi TUI 和 Git 工作区。revdiff 原生的主题、compact、wrap 等外观偏好保持不变；比较范围由所选审阅模式决定，原生 include/exclude 文件过滤仍然有效。原配置不会被修改；在 `/diff` 内按 `T` 切换主题只对本次审阅有效。若要保存主题偏好，请单独运行 revdiff 或编辑其原生配置。

## 你会看到什么

![pi-glance demo](./assets/demo.png)

- **圆角编辑器**：最小 2 / 3 / 4 行，顶部 0 / 1 / 2 行间距。
- **工作区标题**：目录名，或安全的 `~/...` 路径。
- **顶部状态**：Git、费用、Reply speed、context、可选 tokens、模型。
- **Working Tree**：文件数和 tracked `+N −N`，在顶栏 Git 或底边右侧。
- **`/glance` 面板**：通用设置、segment 顺序和各项选项。
- **失焦变暗**：滚动聊天时界面变安静。
- **主题**：默认跟随 Pi theme tokens，也可选 22 套 Glance 配色。
- **输入暂存**：`Ctrl+Shift+S` 收起/拿回，`Ctrl+Shift+U` 连按两次丢掉；边框用 `!stash` 提示未取回的草稿。
- **Working indicator**：spinner、当前活动、本 cycle 输出和耗时。

其他扩展的 `ctx.ui.setStatus()` 仍显示在输入框下方。Glance 不恢复 Pi 那两行信息 Footer。

## 设置

打开 `/glance`：

- **General** — 新安装 `Color source` 为 `Follow Pi`。选 `Glance palette` 使用 22 套内置配色。当前 Pi 主题不可用时，用 `Light palette` / `Dark palette`。`Icons` 默认 `plain`；`nerd` 需要 Nerd Font。图标变成方框就改回 `plain`。`Workspace label` 为 `name`、`smart` 或 `path`。
- **Working indicator** — 一级菜单只有一个 `Enabled: on/off`。`off` 恢复 Pi 默认 working row。
- **Git** — `Enabled` 会停掉 Glance 的全部 git 读取、`fetch`、`/diff` 和 worktree 计数，不只是隐藏状态行。然后是 `Dirty marker`（文件计数可见时不亮灯，冲突保留）、`Ahead / behind`、`Behind main`、`SHA`、`Working tree`（`status` 或 `border right`）、`Polling`。
- **Reply speed** — 默认开启。按输出 token 数 / 服务端推理时间（thinking 思考 + 正文生成）显示：`?` 未知，`~42 tok/s` 临时，`42 tok/s` 最终。排除本地工具执行和每段回复开始前的等待，慢工具不再拖低速度；同样的输出，思考越久，速度越低。在支持的 Pi 版本中，等待阻塞 UI 提示的时间也不计入。`Precision` 为 `auto`、1 位或 0 位。这是回复体验指标，不是性能基准（benchmark）。不发通知、不从文本估算 token。
- **Tokens** — 可选的会话累计用量。`Display` 选择输入/输出或总数。`Cache` 可循环选择 `auto`（完整宽度才显示读写数量）、`show`（始终显示数量）、`hide` 和 `Hit rate`（命中率，配置值 `rate`）。命中率显示提示 token 中从缓存读取的比例，四舍五入为 `42%` 这样的百分比，不受输出 token 数影响。窄布局优先保留百分比；尚无提示 token 时不显示百分比。默认仍为 `auto`，已有设置不变。
- **Context** — 百分比 / tokens 文本，可选右下角 `Progress bar`（`track` 或 `border`，`one third` 或 `remaining`）。未用部分细线 `─`，已用部分粗线 `━`。低于 70% 正常，70%（含）到 85%（不含）warning，85% 及以上 error。
- **Bottom details** — 可隐藏自动压缩标记。Nerd Font 显示 `󰁄 auto`。

Git 保持安静：

- 干净仓库只显示分支名。
- 脏仓库加 `*` / `●`；文件计数已可见时不亮灯，例如 `main Δ6 +123 −99`。
- 窄屏隐藏文件计数摘要时，已启用的 dirty marker 会恢复。冲突 `!` / `⚠` 始终独立保留。
- 上游计数形如 `↑2 ↓1`。
- 落后上次拿到的 `origin/main` 时显示高亮 `main↓N`。计数为 0、没有 `origin/main`、或上游 `↓N` 已经在报同一件事时不显示。

`/diff` 是可选的。没有 revdiff 时，Glance 和 Working Tree 概要仍可用。

## Working indicator

**Fork 差异：** 由本包提供；上游 `pi-glance` 0.5.3 不包含该功能。

高层 cycle 活跃时显示主题化 spinner、稳定动词、当前活动（`requesting`、thinking、高亮的 `responding`，或 running 某工具）、本 cycle 输出，以及满 3 秒后的耗时（`3s`、`47s`、`3m 08s`）。五分钟及以上耗时使用主题 warning 色。它不是 Anthropic 官方组件，也不改变 Agent、prompt、模型、工具、消息或 session 行为。

Working row 是当前 cycle 的 output。顶边框 Tokens 是当前 session 累计 usage。Context 是 context window 占用。空 partial 保持隐藏，不显示 `↓ ~0 tokens`。

## 许可证

MIT。原始 `pi-glance` 版权 © 2026 linys77。见 [UPSTREAM_SOURCE.md](./UPSTREAM_SOURCE.md)、[UPSTREAM_LICENSE](./UPSTREAM_LICENSE) 和 [UPSTREAM_README.md](./UPSTREAM_README.md)。