# PiCometixLine

> 为 [pi-agent](https://pi.dev) 打造的高性能状态栏扩展，移植自 [CCometixLine](https://github.com/Haleclipse/CCometixLine)（ccline）。

PiCometixLine（简称 piccline）把 CCometixLine 那套「模型 | 目录 | Git | 上下文窗口」的 Claude Code 状态栏体验，搬到了 pi-agent 的 footer 上。pi 没有 Claude Code 那样的 `statusLine` 机制，但提供了 `ctx.ui.setFooter()` 自定义底栏的能力——这就是 pi 版的 statusline。

![pi-agent](https://img.shields.io/static/v1?label=for&message=pi-agent&color=blue&style=flat-square)
![Language:TypeScript](https://img.shields.io/static/v1?label=Language&message=TypeScript&color=3178c6&style=flat-square)
![License:MIT](https://img.shields.io/static/v1?label=License&message=MIT&color=blue&style=flat-square)

状态栏显示：`Model • Thinking | Directory | Git 分支状态 | (Session) | 上下文窗口 | Tokens | Cache | Cost`

## 功能

### 核心段（Segment）

| 段 | 显示内容 | pi 数据来源 | CCometixLine 对应 |
|----|---------|------------|------------------|
| **Model** | 简化模型名（如 `Sonnet 4.5`）；多 provider 时带 `(provider)` 前缀 | `ctx.model` + 内置 Claude 家族识别 + `models.json` 映射 | `model` 段 |
| **Thinking** | 思考强度（如 `high`；关闭时显示 `off`，默认常驻） | `ctx.thinkingLevel` | pi 独有，CCometixLine 无 |
| **Directory** | 当前目录名 | `ctx.cwd` | `directory` 段 |
| **Git** | 分支 + 状态(✓/●/⚠) + ↑n/↓n + 可选 SHA | `footerData.getGitBranch()` + 后台 `git` 命令 | `git` 段 |
| **Session** | 会话名（默认关闭） | `ctx.sessionManager.getSessionName()` | pi footer 第一行 |
| **Context Window** | 上下文占用百分比 · 已用/上限（如 `45.2% · 90.4k/200k`，未知时 `?/200k`） | `ctx.getContextUsage()` | `context_window` 段 |
| **Tokens** | ↑输入 ↓输出 token 累计（含工具、压缩/分支摘要用量） | 汇总 session entries 的 usage | 替代 CCometixLine 的 `usage` 段 |
| **Cache** | `R`缓存读 `W`缓存写 + `CH`缓存命中率（对齐 pi footer 的 R/W/CH） | 同上 | CCometixLine 无 |
| **Cost** | 会话累计成本 `$x.xxx`（位数可配） | 汇总 session entries 的 `usage.cost.total` | `cost` 段 |

默认启用：Model / Thinking / Directory / Git / Context Window（Session / Tokens / Cache / Cost 可在配置中开启）。段顺序也会按主题规范（`Model • Thinking` 在前，统计段在后）自动对齐 pi footer。

### 主题系统

内置 9 套主题，覆盖 Plain / NerdFont / Powerline 三种风格：

- **cometix**（默认）— NerdFont + 16 色，忠实移植
- **default** — Plain emoji + 16 色
- **minimal** — Plain + 低饱和 + 细分隔符 `│`
- **nord** — NerdFont + Nord 调色板
- **gruvbox** — NerdFont + Gruvbox 调色板
- **powerline-dark** — Powerline 箭头分隔符 + 深色背景
- **powerline-light** — Powerline 箭头 + 浅色背景
- **powerline-rose-pine** — Powerline + Rose Pine
- **powerline-tokyo-night** — Powerline + Tokyo Night

Powerline 主题使用 `` 箭头分隔符，并通过相邻段背景色实现颜色过渡（与 CCometixLine 一致）。

### 实时刷新

- Git 分支变化：订阅 `footerData.onBranchChange`
- Git 状态(ahead/behind/dirty)：每轮结束（`turn_end`）后台异步刷新，带 15 秒节流
- 模型/思考级别变化：`model_select` / `thinking_level_select` 事件
- 会话名变化：`session_info_changed` 事件
- Token/Cost/上下文：pi 自动重绘 footer 时实时读取 session 数据

## 安装

> 扩展与 pi 使用哪种 shell（bash / PowerShell / cmd / WSL）无关：状态栏直接调用 `git` 可执行文件，所有平台行为一致。

### 方式一：npm（推荐，所有平台通用）

```bash
pi install npm:pi-cometixline           # 最新版
pi install npm:pi-cometixline@1.1.0     # 固定版本
```

### 方式二：本地路径 / git 仓库

| 平台 | 命令 |
|------|------|
| PowerShell（Windows） | `pi install E:\gitProjects\pi-packages\packages\pi-cometixLine` |
| cmd（Windows） | `pi install E:\gitProjects\pi-packages\packages\pi-cometixLine` |
| bash / zsh / fish（macOS、Linux） | `pi install ~/gitProjects/pi-packages/packages/pi-cometixLine` |
| Git Bash / WSL | `pi install /e/gitProjects/pi-packages/packages/pi-cometixLine` |
| git 仓库（需独立仓库） | `pi install git:github.com/<your>/pi-cometixLine` |

> 路径含空格时加引号：PowerShell 用 `pi install "D:\my packages\pi-cometixLine"`。
> 注意：`pi install git:...` 以仓库根目录为包，不支持 monorepo 子目录；从 git 安装需将本包拆为独立仓库，或直接用 npm 发布（见文末「发布」）。

### 方式三：手动放置

把 `extensions/ccline/` 目录复制到全局扩展目录（`~/.pi/agent/extensions/ccline/`，Windows 为 `%USERPROFILE%\.pi\agent\extensions\ccline\`），pi 会自动发现 `index.ts`。

### 方式四：临时试用

| 平台 | 命令 |
|------|------|
| PowerShell / cmd | `pi -e "E:\gitProjects\pi-packages\packages\pi-cometixLine"` |
| bash / zsh / fish | `pi -e ~/gitProjects/pi-packages/packages/pi-cometixLine` |
| Git Bash / WSL | `pi -e /e/gitProjects/pi-packages/packages/pi-cometixLine` |

> 安装后无需额外配置，pi-agent 启动即显示状态栏。若默认 footer 未变化，确认 pi 已加载该扩展（`pi list`）。

### 平台支持

| 平台 | 状态 | 说明 |
|------|------|------|
| Windows 10/11 | ✅ | PowerShell 5.1 / PowerShell 7 / cmd / Git Bash / WSL 均可；需 [Git for Windows](https://git-scm.com/download/win) 且 `git` 在 `PATH` 中 |
| macOS | ✅ | 需 git（`xcode-select --install` 或 Homebrew） |
| Linux | ✅ | 需 git（发行版包管理器安装） |
| 终端 | — | NerdFont / Powerline 主题需 **Nerd Fonts v3+**（v2 旧码点已不再使用）；建议 Windows Terminal / iTerm2 / WezTerm / Kitty，tmux 下需终端支持真彩色 |

## 使用

### 命令

在 pi-agent 中输入：

| 命令 | 作用 |
|------|------|
| `/ccline` | 打开主题选择对话框 |
| `/ccline theme <名称>` | 直接切换主题 |
| `/ccline on` / `off` | 开启 / 关闭状态栏（恢复 pi 默认 footer） |
| `/ccline init` | 初始化默认配置文件 |
| `/ccline status` | 查看当前状态 |

### 配置文件

配置目录：`~/.pi/agent/ccline/`（Windows 下为 `%USERPROFILE%\.pi\agent\ccline\`）

#### `config.json` — 主题与段配置

```json
{
  "version": 3,
  "theme": "cometix",
  "enabled": true,
  "style": { "mode": "nerdFont", "separator": " | " },
  "segments": [
    {
      "id": "model", "enabled": true,
      "icon": { "plain": "🤖", "nerdFont": "" },
      "colors": { "icon": { "c16": 14 }, "text": { "c16": 14 } },
      "styles": { "textBold": true },
      "options": {}
    }
  ]
}
```

- `version`：配置版本（当前 3）。旧配置首次加载时会自动迁移：补齐新增段（Cache/Session）、把未改过的段按下发版本默认值调整（Thinking 常驻，Tokens/Cache/Cost 默认关闭），并修复 Nerd Fonts v3 已移除的旧图标码点（如 thinking 的 `U+F5DC` → `U+F09D1`）
- `theme`：主题名（加载该预设，再用 `style`/`segments` 覆盖）
- `enabled`：总开关（`false` 则不显示，等同 `/ccline off`）
- `style`：覆盖分隔符/模式
- `segments`：完整覆盖段配置数组（省略字段用默认）；缺段会自动补齐
- 颜色格式：`{ "c16": n }`（16色）/ `{ "c256": n }`（256色）/ `{ "r":, "g":, "b": }`（RGB）

段选项（`segments[].options`）：

| 段 | 选项 | 默认 | 说明 |
|----|------|------|------|
| `model` | `show_provider` | `true` | 多 provider 可用时显示 `(provider)` 前缀（对齐 pi footer） |
| `git` | `show_sha` | `false` | 显示 7 位短 SHA |
| `contextWindow` | `show_total` | `true` | 显示 `已用/上限`（如 `45.2% · 90.4k/200k`） |
| `cache` | `show_hit_rate` | `true` | 显示 `CH` 缓存命中率 |
| `cost` | `decimals` | `3` | 成本小数位（0-6） |
| `thinking` | `hide_when_off` | `false` | 关闭思考时隐藏该段（否则常驻显示 `off`） |

> 提示：最简单的方式是用 `/ccline` 选主题后，配置文件会自动保存。需要微调个别段再手编 `segments`。

#### `models.json` — 模型映射（可选）

用于识别非 Claude 模型、覆盖上下文窗口、或追加上下文修饰符后缀：

```json
{
  "models": [
    { "pattern": "glm-4.5", "displayName": "GLM-4.5", "contextLimit": 128000 },
    { "pattern": "kimi-k2", "displayName": "Kimi K2", "contextLimit": 128000 }
  ],
  "contextModifiers": [
    { "pattern": "[1m]", "displaySuffix": " 1M", "contextLimit": 1000000 }
  ]
}
```

- `models`：子串匹配，优先级高于内置 Claude 家族识别
- `contextModifiers`：独立匹配，可组合（如 `Opus 4` + ` 1M` = `Opus 4 1M`），覆盖 contextLimit
- Claude 模型（Sonnet/Opus/Haiku）自动识别并提取版本号，无需配置

## 与 CCometixLine 的区别

| 维度 | CCometixLine | PiCometixLine |
|------|-------------|---------------|
| 目标 | Claude Code statusline | pi-agent footer |
| 语言 | Rust | TypeScript（pi 扩展） |
| 触发 | stdin JSON → stdout | `ctx.ui.setFooter()` |
| 上下文窗口 | 解析 transcript JSONL | `ctx.getContextUsage()`（pi 原生，显示 `% · 已用/上限`） |
| 用量段 | Anthropic OAuth API（5h/7d 利用率） | Tokens 段（↑输入 ↓输出）+ Cache 段（R/W/CH，对齐 pi footer） |
| 思考级别 | 无 | 有（`ctx.thinkingLevel`，默认常驻显示） |
| 配置 | TOML + TUI 配置器 | JSON + `/ccline` 命令 |
| Patch 工具 | 有（禁用 Claude 警告） | 无（pi 不需要） |

> pi 没有类似 Anthropic OAuth usage API 的能力，故用「累计 token」段替代 CCometixLine 的「5h/7d 利用率」段。

## 要求

- **pi-agent**：`@earendil-works/pi-coding-agent`（通过 peerDependencies 声明）
- **Git**：1.5+（2.22+ 推荐），需在 `PATH` 中——Windows 用 [Git for Windows](https://git-scm.com/download/win)，macOS 用 `xcode-select --install` 或 Homebrew，Linux 用发行版包管理器
- **Nerd Font**：Plain 主题用 emoji；NerdFont / Powerline 主题需终端安装 **Nerd Fonts v3+** 字体（如 [JetBrains Mono Nerd Font](https://www.nerdfonts.com/font-downloads)、FiraCode Nerd Font）。v2 旧版字体缺少部分新码点（如 `U+F09D1` brain），会显示缺字
- **shell**：与 bash / PowerShell / cmd 无关，扩展直接调用 `git`

## 项目结构

```
pi-cometixLine/
├── package.json              # pi package 清单
├── extensions/ccline/
│   ├── index.ts              # 扩展入口：footer 注册、事件、命令
│   ├── config.ts             # 配置加载/保存
│   ├── themes.ts             # 9 套主题预设
│   ├── segments.ts           # 段数据收集（pi 数据源映射）
│   ├── render.ts             # 状态栏渲染（Powerline 箭头过渡）
│   ├── git.ts                # Git 状态异步缓存
│   ├── ansi.ts               # ANSI 颜色工具
│   └── types.ts              # 类型定义
└── README.md
```

## 开发

```bash
# 临时加载测试（bash / zsh / Git Bash）
pi -e ./extensions/ccline/index.ts
```

```powershell
# PowerShell
pi -e .\extensions\ccline\index.ts
```

> 修改后用 `/reload` 热重载（需先 `pi install` 或放到全局 extensions 目录）。

## 发布（维护者）

本包已按 [pi package](https://pi.dev/packages) 规范就绪（`pi-package` 关键词 + `pi.extensions` 清单 + `files` 白名单），可直接发布到 npm（包名 `pi-cometixline` 当前未被占用）：

```bash
cd packages/pi-cometixLine

# 1. 预检：查看 npm 产物内容 / 不实际上传
npm pack --dry-run
npm publish --dry-run

# 2. 登录 npm（首次）
npm login

# 3. 正式发布
npm publish
```

- 发布后所有平台统一安装：`pi install npm:pi-cometixline`
- 打上 `pi-package` 关键词后会被 [pi.dev/packages](https://pi.dev/packages) 画廊收录
- 后续版本：`npm version patch|minor|major` 后重新 `npm publish`
- 想在 GitHub 上直接 `pi install git:...`，需把本包拆成独立仓库（pi 的 git 安装不支持 monorepo 子目录）

## 许可证

MIT License — 见 [LICENSE](LICENSE)

## 致谢

- [CCometixLine](https://github.com/Haleclipse/CCometixLine) by Haleclipse — 原始 Rust 实现，本项目的参考蓝本
- [pi-agent](https://pi.dev) by Earendil Works — 提供扩展与 footer 自定义能力