# pi-aura

[![omp status](https://omppackages.com/badge/pi-aura.svg)](https://omppackages.com/packages/pi-aura)

[English](./README.md) | **简体中文**

> **本项目由 AI 开发。** 这里的代码、测试和文档全部由 AI 编码代理（Pi 驱动 DeepSeek 模型）在人工提出需求、审阅与验收下生成。人负责需求、验收和发布，代理负责编写与验证。

给 [Pi](https://pi.dev) 编码代理用的终端界面——欢迎页、高密度底栏、带边框的编辑器、遥测、复制按钮和整理过的会话记录。

![pi-aura 预览](https://raw.githubusercontent.com/Sixteen-16-Bai/pi-Aura/main/assets/preview_dashboard_1.png)

## 亮点

| | |
| --- | --- |
| **欢迎页** | 2× 放大的 Pi 品牌图标、按时段变化的问候语、当前模型和信息网格——九行，没有冗余 |
| **底栏** | Git、运行时、上下文、Token、费用、实时 TPS、扩展状态，还有真实的 DeepSeek 余额 |
| **带边框的编辑器** | 块状、竖线、下划线光标；其它扩展的编辑器保持兼容 |
| **单轮遥测** | TPS、首 Token 延迟、耗时、停顿、Token、每百万单价 |
| **复制按钮** | 全屏模式下代码块和你的消息带可点击 `[Copy]` |
| **整理后的会话记录** | 内置 pi-tidy 0.7.3：分组折叠工具调用、圆角框、左右对照 diff |
| **`/aura` 设置** | 五个页面，英文和简体中文，改动实时生效 |

## 安装

```bash
pi install npm:pi-aura
```

单次试用：`pi -e npm:pi-aura` · 本地安装：`pi install /path/to/pi-aura`

需要 Pi 1.2.0+ 和 Node.js 22.19.0+。[Nerd Font](https://www.nerdfonts.com/font-downloads) 能解锁完整图标；`unicode` 和 `ascii` 模式不需要补丁字体。

## 欢迎页

```
╭─ Pi v1.4.0 ────────────────────────────────────────────────╮
│
│   ██████          Good morning, Sixteen · ⌨ Deepseek-flash
│   ██  ██
│   ████  ██        model   Deepseek-flash    tools   16
│   ██    ██        cwd     Z:\               skills  pdf
│                   branch  main              session local-ui
│
╰────────────────────────────────────────────────────────────╯
```

问候语按时段变化；名字依次取 `PI_HEADER_NAME` → `git config user.name` → 系统用户名。信息网格把可用宽度分成两列，窄终端退化为单列。在 `aura.json` 里设 `header: false` 可把位置交还给 Pi。

## 底栏

- **Git**——分支、ahead/behind、已暂存、已修改、未跟踪、stash、detached HEAD
- **运行时**——识别 50 多种运行时并显示图标
- **上下文与 Token**——用量、总数、最近一次回复的缓存命中率
- **费用**——美元或人民币，两位小数，仅显示换算
- **实时 TPS**——流式输出时的估算速度，工具调用期间变暗

行宽不足时依次丢弃：先运行时和上下文，再 Git、会话名、主机名、计时器；cwd 保留最久。

### DeepSeek 余额

provider 为 `deepseek` 时，底栏在费用旁边显示账户余额：`GET https://api.deepseek.com/user/balance` 返回的人民币 `total_balance`。Key 从 `auth.json` 读取，只发往该接口。启动时请求、缓存十分钟、后台刷新、超时十秒——加载中显示 `…`，失败显示 `--`。它属于 `footerSegments.cost` 分组。

## 单轮遥测

```text
> TPS 42.5 tok/s | ~ TTFT 1.2s | + 29.7s | ↑ 567 | ↓ 1.2k | ! stall 1x / 4.3s | ¥ 3.60/M
```

`M` = 每百万 Token；最后一项是每 1M Token 的单价，不是会话累计费用。TPS 等于服务商报告的输出 Token 除以总生成时间。每个字段都能在**遥测**页单独开关。

## 复制按钮

全屏模式下，每个围栏代码块都会套上带语言标记和 `[Copy]` 的框，你的消息同样带一个：

```text
╭─ sh ─────────────── [Copy] ╮
│ pi install npm:pi-aura     │
╰────────────────────────────╯
```

复制时去掉围栏、保留缩进和制表符。流式回复结束后才出现标签。在 **常规 → 复制按钮**（`copyButtons`）开启。

## 工具折叠（pi-tidy）

内置 pi-tidy 0.7.3（MIT，见 `THIRD_PARTY_NOTICES.md`）接管会话记录：分组折叠工具调用并统计失败、按工具上色的圆角框、左右对照 diff、实时后台任务、右对齐的 `User` 消息框，以及带模型名和时间的最终回复框。所有框让出最后一列给 Pi 的滚动条。配置在 `settings.json` 的 `tidy` 键下，或在 `/aura` → **工具折叠** 修改。

## 设置

运行 `/aura`。`Tab`/`←`/`→` 切页，`↑`/`↓` 移动，`Enter`/`Space` 切换，`Esc`/`q` 关闭。

| 页面 | 内容 |
| --- | --- |
| **常规** | 启用、顶部信息栏、语言、货币、底栏嵌入、复制按钮、左键选中即复制 |
| **外观** | 图标模式 |
| **底栏** | 各底栏分段 |
| **遥测** | 遥测及各字段 |
| **工具折叠** | pi-tidy 选项 |

保存在 Pi agent 目录下的 `aura.json`（默认 `~/.pi/agent`，`PI_CODING_AGENT_DIR` 可覆盖）。Tidy 和「左键选中即复制」写入 `settings.json`。

## 配置

```json
{
  "header": true,
  "settingsLanguage": "zh",
  "currency": "cny",
  "currencyRate": 7.2,
  "cursorStyle": "underline",
  "icons": { "mode": "nerd" }
}
```

| 选项 | 可选值 | 默认 |
| --- | --- | --- |
| `enabled` | `true`、`false` | `true` |
| `header` | `true`、`false` | `true` |
| `inlineFooter` | `true`、`false` | `false` |
| `copyButtons` | `true`、`false` | `false` |
| `settingsLanguage` | `en`、`zh` | `zh` |
| `currency` | `usd`、`cny` | `cny` |
| `currencyRate` | 数字 | `7.2` |
| `cursorStyle` | `block`、`bar`、`underline` | `underline` |
| `icons.mode` | `auto`、`nerd`、`unicode`、`ascii` | `nerd` |
| `footerSegments.*` | 布尔 | 各有默认 |
| `telemetry.*` | 布尔 | `true` |
| `tidy`（settings.json） | pi-tidy 选项 | — |
| `fullscreenCopyOnSelect`（settings.json） | 布尔 | — |

`currencyRate` 是美元兑人民币汇率，仅用于显示。`bar` 和 `underline` 光标需要终端支持。完整的 `footerSegments` 和 `telemetry` 块见 `/aura` 写出的 `aura.json`。

## 兼容性

Aura 只为保留 Pi 原生布局、光标、鼠标和 padding API 的编辑器套框，包括 `CustomEditor` 扩展。它装饰同一个实例，幽灵文本、按键处理、补全和提交回调都不受影响；通过 `ctx.ui.setEditorComponent()` 注册的编辑器，无论在 `pi-aura` 之前还是之后，都会被套框。没有原生边框、或探测抛错的编辑器保持原样。

## 开发

```bash
npm install
npm run typecheck
npm test
pi -e .
```

133 项测试，跑在 `node --test` 上。CI 覆盖 Pi 1.2.0 和最新版、Node 22.19.0 和 24，以及 Linux、Windows、macOS。字体、鼠标和光标支持需要真实终端，用 `pi -e .` 检查。

## 致谢

- **[pi-haiku](https://github.com/nnocte/pi-haiku)**——底栏结构、工作计时器
- **[pi-claude-code-tui](https://github.com/Phoobobo/pi-claude-code-tui)**——图标画法、圆角编辑器边框
- **[pi-zentui](https://github.com/lmilojevicc/pi-zentui)**——底栏分段、运行时识别、设置界面
- **[pi-tps](https://github.com/monotykamary/pi-tps)**——轮次计时、停顿检测、TPS
- **[pi-tidy](https://github.com/Andy8647/pi-tidy)**——内置会话记录渲染器（MIT）

图标图案来自 Pi 官方安装脚本。感谢 **[LINUX DO](https://linux.do)** 社区。

## 开发方式

pi-aura 是一次 AI 驱动开发的尝试：需求在对话里提出，由代理实现，提交前用 `tsc`、测试和人工终端检查验证。仓库提交记录保留了真实过程——包括排查 bug、清理死代码和回滚，没有做整理或重写。

## 许可

[MIT](./LICENSE)