pi-neat-ui

English | 中文

一个用于 pi 的本地 UI 美化包：扩展 + 主题套件。

pi-neat-ui 内置 powerline 风格 statusline，同时提供自定义 Header、提示 Widget、working indicator、工具输出紧凑渲染，以及主题预设。

功能

• 内置 powerline/emoji statusline，视觉风格保持 @narumitw/pi-statusline 的样式。
• 缓存感知 token 段：
  • R 表示 cache-read tokens，即使为 0 也显示；
  • W 表示 cache-write tokens，即使为 0 也显示；
  • ⚡ 表示近似缓存命中率，即使为 0% 也显示。
• 会话持续时间段（⏱）。
• 自定义启动 Header。
• 轻量编辑器提示 Widget。
• 自定义 working indicator。
• 工具输出紧凑渲染：
  • 折叠时只显示摘要，例如 bash: done (3 lines) 或 grep: 12 matches；
  • 展开/verbose 模式回退到 pi 内置渲染器，保留语法/差异高亮；
  • edit 调用使用 pi 内置渲染器，保证动态 diff 预览与增删行数准确；
  • 需要细节时按 Ctrl+O 展开。
• 内置命令：
  • /neat-ui：开关 UI 美化。
  • /neat-statusline：开关内置 statusline。
  • /neat-tools：切换工具渲染 compact / verbose。
  • /neat-style：切换布局密度 compact / spacious。
  • /neat-theme：列出或切换可用主题。
• 默认主题：Pi 内置 dark 主题。
• 附带主题：
  • neon-aurora：深色霓虹风。
  • paper-dawn：浅色纸张风。

安装 / 加载

方式一：从 npm 安装

通过 pi 的包管理命令安装已发布的 npm 版本：

pi install npm:pi-neat-ui@0.3.3

如果希望安装到当前项目，并写入 .pi/settings.json，加上 -l：

pi install -l npm:pi-neat-ui@0.3.3

然后启动 pi。扩展会默认应用 Pi 内置 dark 主题：

pi

也可以只临时试用一次，不写入配置：

pi -e npm:pi-neat-ui@0.3.3

方式二：从 GitHub 安装

pi install github:MorseWayne/pi-neat-ui

方式三：项目本地包

把本目录放入项目中，并配置 .pi/settings.json：

{
  "packages": ["./pi-neat-ui"]
}

方式四：开发阶段直接加载

pi -e ./pi-neat-ui/extensions/beautify-ui.ts

运行后可用 /neat-theme neon-aurora 或 /neat-theme paper-dawn 切换主题。

使用

加载后默认启用插件。

/neat-ui                 # 开关美化
/neat-statusline         # 开关内置 statusline
/neat-statusline off     # 恢复 Pi 内置默认 footer
/neat-statusline on      # 启用 pi-neat-ui statusline
/neat-tools              # compact/verbose 之间切换
/neat-tools verbose      # 显示完整工具输出
/neat-tools compact      # 折叠为摘要
/neat-style              # compact/spacious 之间切换
/neat-theme              # 列出可用主题
/neat-theme dark         # 切到 Pi 内置 dark 主题
/neat-theme neon-aurora  # 切深色霓虹主题
/neat-theme paper-dawn   # 切浅色主题

Statusline 缓存显示

当 provider 返回 prompt cache usage 时，token 段会显示缓存数据：

🔢 ↑423k ↓27k R19.6m W0 ⚡94%

• ↑ 普通输入 token
• ↓ 输出 token
• R cache-read tokens，始终显示
• W cache-write tokens，始终显示
• ⚡ 近似缓存命中率，始终显示：cacheRead / (input + cacheRead + cacheWrite)
• ⏱ 当前 pi UI 会话持续时间，按分钟级显示

如果你同时安装了 @narumitw/pi-statusline 或其他 statusline/footer 扩展，建议禁用其中一个，避免多个插件互相覆盖 footer。/neat-statusline off 只会清除 pi-neat-ui 的 footer 并恢复 Pi 内置默认 footer，不能恢复另一个扩展之前设置的 footer。

/neat-tools 和 Ctrl+O 的区别

• Ctrl+O 是 pi 自带的 UI 层展开/折叠开关。
• /neat-tools 是插件层的工具渲染模式切换。

推荐用法：

/neat-tools compact + 需要细节时按 Ctrl+O

发布到 npm

仓库已包含用于 npm 发布的 GitHub Actions workflow。

1. 在 GitHub 仓库中添加 npm automation token，secret 名称为 NPM_TOKEN。
2. 提升 package.json 版本号。
3. 创建并推送匹配版本号的 tag，例如：

npm version patch
git push --follow-tags

workflow 会用 npm pack --dry-run 校验包内容，并在 tag 触发时使用 npm provenance 发布。

也可以在 GitHub Actions 页面手动运行 workflow，并设置 publish=true。

说明

/neat-tools compact 不会影响工具执行，只改变工具结果在 TUI 中的展示方式。

Statusline 渲染灵感来自 @narumitw/pi-statusline；详见 NOTICE.md。