pi-open-tui 0.4.1 → 0.4.3

package/README.zh-CN.md

@@ -4,28 +4,28 @@
 
 [English](./README.md) | **简体中文**
 
-一个为 [Pi](https://pi.dev) 编程代理打造的终端界面扩展，将 pi-haiku、pi-claude-code-tui 与 pi-zentui 的优秀设计整合为统一、可配置的使用体验。
+一个为 [Pi](https://pi.dev) 编程代理打造的终端界面扩展。
 
 ![pi-open-tui 预览](https://raw.githubusercontent.com/OldSuns/pi-open-tui/main/assets/preview_dashboard_1.png)
 
-Pi 1.4.0 的真实终端截图。
-
 ## 功能亮点
 
 - **Pi 顶栏**：显示模型、思考等级、当前目录和常用斜杠命令提示
-- **自适应底栏**：集中展示 Git 状态、运行环境、上下文用量、Token、费用和扩展状态
-- **带边框的编辑器**：支持块状、竖线和下划线三种光标样式；保留其它扩展已安装的兼容编辑器
-- **项目环境感知**：识别 50 多种运行环境，并展示 ahead/behind、已暂存、已修改、未跟踪、stash 和 detached HEAD 等 Git 状态
-- **单轮遥测**：展示 TPS、首 Token 延迟（TTFT）、耗时、停顿、Token 数量和模型标价速率
-- **思考预览**：模型工作时，在 Pi 隐藏思考块的 `Thinking...` 位置显示实时字幕，展示推理内容的末尾片段
-- **交互式设置**：通过 `/open-tui` 配置，并支持英文和简体中文界面
+- **自适应底栏**：展示 Git 状态、运行环境、上下文用量、Token、费用和扩展状态
+- **带边框的编辑器**：支持块状、竖线和下划线光标，保留其他扩展的兼容编辑器
+- **项目环境感知**：识别 50 多种运行环境，并展示 ahead/behind、已暂存、已修改、未跟踪、stash 和分离 HEAD 等 Git 状态
+- **单轮遥测**：展示生成速度、首 Token 延迟、耗时、停顿、Token 数量和费用速率
+- **思考预览**：模型工作时实时预览隐藏的推理内容
+- **紧凑工具视图**：提供编辑/写入预览，可选支持扩展和 MCP 工具
+- **全屏复制按钮**：一键复制代码块和用户消息
+- **交互式设置**：通过 `/open-tui` 使用英文或简体中文界面
 
 ## 环境要求
 
-- Pi 1.2.0 或更高版本
+- Pi 1.5.0 或更高版本
 - Node.js 22.19.0 或更高版本（Pi 的最低要求）
 - 支持 UTF-8 和彩色输出的终端
-- 使用完整图标集时需要 [Nerd Font](https://www.nerdfonts.com/font-downloads)（可选；内置可移植 Unicode 图标）
+- 使用完整图标集时需要 [Nerd Font](https://www.nerdfonts.com/font-downloads)（可选，也可使用 Unicode 或 ASCII 模式）
 
 ## 安装
 
@@ -43,132 +43,64 @@ pi -e npm:pi-open-tui
 
 ## 字体与图标
 
-可从 [Nerd Fonts 官方下载页](https://www.nerdfonts.com/font-downloads)或 [GitHub 最新版本](https://github.com/ryanoasis/nerd-fonts/releases/latest)下载任意已修补字体。安装后，请在终端配置中选择该字体，并重启终端。
-
-默认的 `auto` 模式检查终端环境，而不是已安装的字体文件。在支持 UTF-8 的交互式 TTY 中，它会使用 Nerd Font 图标，即使 Pi 运行在 runner 或子 shell 中。如果图标显示为方框、乱码或错误符号，请打开 `/open-tui`，在**外观**页选择合适的模式：
-
-- `nerd`：终端已配置 Nerd Font 时，强制使用 Nerd Font 图标
-- `unicode`：可移植 Unicode 图标（文件夹、分支、笔记本电脑、灯泡、插头、沙漏等），无需修补字体；emoji 字形通过终端的 emoji 回退渲染
-- `ascii`：使用纯文本图标，无需安装修补字体
-- `auto`：在支持 UTF-8 的交互式 TTY 中使用 Nerd Font 图标；SSH 会话使用可移植 Unicode 图标（字体由客户端终端决定，通常没有 Nerd Font）；非交互式输出、`TERM=dumb` 或明确配置为非 UTF-8 的 locale 使用 ASCII
+使用完整图标集时，请安装 [Nerd Font](https://www.nerdfonts.com/font-downloads)，在终端配置中选中它并重启终端。使用 VS Code、Windows Terminal 等应用时，只在操作系统中安装字体还不够。
 
-如果已经安装字体，但 `auto` 仍选择 ASCII，请手动切换为 `nerd`。使用 VS Code、Windows Terminal 等应用时，只在操作系统中安装字体还不够，还需要在对应的终端配置中选中该字体。如果 SSH 客户端终端确实安装了 Nerd Font 并希望在 SSH 下使用完整图标，请将模式显式设为 `nerd`。
+`/open-tui` 的**外观 → 图标**提供 `auto`、`nerd`、`unicode` 和 `ascii`。默认 `auto` 检查终端环境，并不检查实际字体；图标显示为方框时可选 `unicode`，终端已配置 Nerd Font 时可强制选 `nerd`，SSH 会话同样适用。
 
-如果较宽的 Nerd Font 图标占用了图标与文字之间的间隔（例如在 Kitty 中），可开启 `footerSegments.nerdIconSpacing`（`/open-tui` 中的 **底栏 → Nerd 图标后额外留空**）。开启后底栏会在 Nerd Font 图标后额外预留一格空白，包括运行环境图标，常规底栏和内嵌底栏的宽度计算都包含这格留白；Unicode/ASCII 图标与紧凑的 Git 状态标记不受影响。Kitty 用户也可以在 `kitty.conf` 中设置 `narrow_symbols U+E000-U+F8FF 1`。
+自动选择规则和 Kitty 的间距选项见[图标检测与间距](./docs/configuration.md#图标)。
 
 ## 配置
 
-运行 `/open-tui` 打开设置窗口，其中包含**常规**、**外观**、**底栏**和**遥测**四个页面，并会适应终端尺寸。设置保存在 Pi 的 agent 目录内的 `open-tui.json` 中；默认目录为 `~/.pi/agent`，可通过 `PI_CODING_AGENT_DIR` 覆盖。保存失败时会提示：修改仅在当前会话生效。
-
-配置示例：
-
-```json
-{
-  "enabled": true,
-  "header": true,
-  "inlineFooter": false,
-  "copyButtons": true,
-  "settingsLanguage": "zh",
-  "cursorStyle": "block",
-  "icons": {
-    "mode": "auto"
-  },
-  "footerSegments": {
-    "cwd": true,
-    "hostname": false,
-    "sessionName": false,
-    "gitBranch": true,
-    "gitStatus": true,
-    "gitCommit": false,
-    "runtime": true,
-    "context": true,
-    "tokens": true,
-    "cost": true,
-    "liveTps": true,
-    "extensionStatuses": true,
-    "capitalizeProviderName": true,
-    "nerdIconSpacing": false
-  },
-  "telemetry": {
-    "enabled": true,
-    "tps": true,
-    "ttft": true,
-    "duration": true,
-    "tokens": true,
-    "stalls": true,
-    "cost": true
-  },
-  "thinkingPeek": {
-    "lines": 1
-  },
-  "toolView": {
-    "mode": "native"
-  }
-}
-```
+运行 `/open-tui` 打开设置窗口，包含**常规**、**外观**、**底栏**和**遥测**四个页面，支持英文和简体中文，并适应终端尺寸。Tab/Shift+Tab 或 ←/→ 切页，↑/↓ 移动，Enter/Space 修改值，Esc/q 关闭。
 
-主要选项：
+设置保存在 Pi 的 agent 目录内的 `open-tui.json` 中，默认目录是 `~/.pi/agent`，可通过 `PI_CODING_AGENT_DIR` 覆盖。保存失败时会提示：修改仅在当前会话生效。
 
-| 选项 | 可选值 | 说明 |
+| 设置 | 位置 | 默认值 |
 | --- | --- | --- |
-| `settingsLanguage` | `en`、`zh` | 切换 `/open-tui` 设置界面的语言 |
-| `header` | `true`、`false` | 决定是否用 open-tui 顶部信息栏覆盖 Pi 的 Header；设为 `false` 时把顶部栏位置留给 Pi 或其他扩展 |
-| `inlineFooter` | `true`、`false` | 将两条主要 Footer 信息行移入编辑器上下边框以节省垂直空间，默认关闭；扩展状态行仍显示在编辑器外 |
-| `copyButtons` | `true`、`false` | 全屏模式下给代码块加圆角边框，并在代码块和用户消息上显示可点击的 `[Copy]` 标签，默认开启；见[复制按钮](#复制按钮) |
-| `cursorStyle` | `block`、`bar`、`underline` | `bar` 和 `underline` 需要终端支持光标形状转义序列 |
-| `icons.mode` | `auto`、`nerd`、`unicode`、`ascii` | 控制底栏和遥测通知使用的图标 |
-| `footerSegments` | 布尔开关 | 分别控制底栏中的各项数据 |
-| `footerSegments.capitalizeProviderName` | 布尔开关 | 将底栏中提供商名称的首字母大写；设为 `false` 时保留原始大小写 |
-| `footerSegments.nerdIconSpacing` | 布尔开关 | 在底栏 Nerd Font 图标后额外留一格空白；默认 `false` |
-| `telemetry` | 布尔开关 | 控制遥测总开关和各项指标 |
-| `thinkingPeek.lines` | `0`、`1`、`2` | 关闭、单行或双行思考预览 |
-| `toolView.mode` | `native`、`compact` | Pi 原生卡片（默认），或带编辑/写入成功预览的紧凑调用与摘要行。只对切换后新建的行生效 |
-
-`sessionName` 仅在会话有名称时显示；`hostname` 会显示主机名的短名称（主机名的第一个标签，例如从 `mba.example.com` 显示为 `mba`），并使用服务器图标；处于分离 HEAD（detached HEAD）状态时，`gitBranch` 会显示 `HEAD` 和短提交哈希，`gitCommit` 会在其后追加指向该提交的标签，且仅在开启 `gitBranch` 时生效；关闭 `extensionStatuses` 会隐藏整行扩展状态，其中也包括 MCP 状态。每条状态会保留其扩展通过 `ctx.ui.theme.fg()` 设置的颜色；未设置颜色的状态使用 muted 主题色显示。
+| 顶栏与设置语言 | 常规 → 界面 | 顶栏开启、英文 |
+| 思考预览 | 常规 → 消息与工具 | 单行 |
+| 复制按钮 | 常规 → 消息与工具 | 开启，仅全屏模式 |
+| 工具视图 | 常规 → 消息与工具 | 原生 |
+| 底栏嵌入输入框 | 常规 → 底栏 | 关闭 |
+| 图标与光标样式 | 外观 | 自动图标、块状光标 |
+| 底栏字段与遥测指标 | 底栏 / 遥测 | 可分别设置 |
 
-底栏的 Token 和费用总计包含助手回复、工具报告的用量、压缩与分支摘要以及缓存预热；缓存命中百分比表示最近一条助手回复，而非整个会话的累计比例。
+选择**工具视图：紧凑**后，才会显示子选项**紧凑显示扩展工具**；切回原生时隐藏该选项并保留其值。完整 JSON 默认配置、所有选项和工具排除列表见[配置参考](./docs/configuration.md#简体中文)。
 
-底栏第一行宽度不足时，先隐藏运行环境和上下文条，然后依次隐藏 Git、会话名称、主机名和计时器；当前目录保留到最后，并缩短为文件夹名。
+## 顶栏、底栏与编辑器
 
-开启 `inlineFooter` 后，两条常规 Footer 信息行会移入编辑器边框，从而节省垂直空间。顶部边框左侧显示 Git 分支，右侧信息组以当前目录开头；开启 `sessionName` 时，会话标题也会显示在左侧。Header 和扩展状态行保持独立显示；终端较窄时优先截断低优先级 Footer 数据，保留右侧统计信息和边框角。
+顶栏提供模型、项目环境和命令提示。两条主底栏集中显示位置、Git 状态、运行环境、工作/完成计时器、上下文用量、模型详情、Token 和费用。可单独开关各项字段；终端变窄时，布局会缩短或隐藏低优先级信息。
 
-open-tui 会给保留 Pi 原生编辑器布局及光标、鼠标、内边距接口的编辑器加边框，包括基于 `CustomEditor` 的扩展。装饰直接作用于同一实例，因此灰字建议、按键处理、补全和提交回调能够保留。通过当前 `ctx.ui.setEditorComponent()` 接口注册的编辑器扩展可以排在 `pi-open-tui` 前面或后面，运行时替换编辑器也会自动加框，包括在持有新 UI 上下文的快捷键回调中替换。替换后的实例在 Pi 挂载时直接装饰，不会再次调用扩展的创建函数；临时对话框保持原样。装饰前，open-tui 会按终端宽度渲染一次编辑器，检查是否存在可识别的原生上下边界。每次加框也会检查本次实际输出；没有这些边界时按完整请求宽度重新渲染，不应用边框的鼠标坐标偏移，原生边界恢复后再继续加框。缺少这些能力或边界、或在布局检测时抛出异常的编辑器保持原样，即使开启 `inlineFooter`，底栏也会独立显示。关闭 open-tui 会撤销装饰、恢复注册接口，并保留最新的编辑器工厂，包括后注册的扩展包装。
+底栏 Token 和费用总计包含助手回复、工具报告的用量、压缩与分支摘要以及缓存预热；缓存命中率表示最近一条助手回复。其他扩展可以使用独立状态行，也可以[直接向主底栏添加内容](./docs/footer-segments.md)。
 
-顺序无关的保证针对编辑器注册，不包含顶栏或底栏的替换。如果扩展调用预先保存的旧注册函数，或直接替换注册接口本身，则不在此保证范围内。
+开启**底栏嵌入输入框**，可把两条主信息行移入编辑器上下边框，扩展状态行仍显示在编辑器下方。兼容编辑器会保留输入行为、补全和灰字建议；无法加框的编辑器继续使用独立底栏。集成边界见[编辑器兼容性与布局](./docs/implementation.md#编辑器与布局)。
 
 ## 单轮遥测
 
-每次 Agent 完整运行结束后，pi-open-tui 会显示一条临时结果，并将其中的多个工具调用轮次合并统计：
+每次 Agent 完整运行结束后，pi-open-tui 会合并其中的助手轮次，显示一条临时结果：
 
 ```text
 > TPS 42.5 tok/s | ~ TTFT 1.2s | + 29.7s | ↑ 567 | ↓ 1.2k | ! stall 1x / 4.3s | $ $3.60/M
 ```
 
-TPS 的计算方式是：将本次运行中服务商报告的全部 Assistant 输出 Token，除以各个生成轮次的总耗时。计时范围从 `turn_start` 到 Assistant 的 `message_end`，包含 TTFT、隐藏推理、缓冲和停顿，但不包含轮次之间的工具执行时间。没有输出 Token 或无法测得生成时间时，会显示 `TPS —`。
+TPS 用服务商报告的输出 Token 除以生成时间，包含等待和停顿，不包含轮次之间的工具执行时间。流式输出期间，工作计时器还会显示 `~54 tok/s` 这样的实时估算速度。`$ / M` 表示本次运行每百万 Token 的综合费率，底栏则显示会话累计费用。
 
-回复流式输出时，工作计时器还会显示当前的估算速度，例如 `working 12.3s · ~54 tok/s`。`~` 表示估算值：它是最近 2 秒内流式输出的正文、思考内容和工具调用参数的速率，按拉丁文本和代码约 4 个字符 1 个 Token、中日韩字符每字 1 个 Token 估算。停顿时数值会逐渐降向零；工具执行期间和消息之间以暗色保留上一个值。由**底栏 → 实时 TPS**（`footerSegments.liveTps`）控制，与遥测通知的开关互不影响。运行结束后不再显示，以上面的精确 TPS 为准。
-
-`$ / M` 表示根据 `usage.cost.total` 得到的模型标价速率，不是底栏中的会话累计费用。所有遥测字段都可以在**遥测**页单独开关。
+可在**遥测 → 测量指标**中开关通知字段，在**底栏 → 运行环境 → 实时 TPS**中控制实时速度。计算公式、计时边界和缓存统计见[指标定义](./docs/implementation.md#用量与遥测)。
 
 ## 思考预览
 
-开启 Pi 的 **Hide thinking** 后，任务运行期间 pi-open-tui 会在原生隐藏思考块的 `Thinking...` 位置显示紧凑的实时字幕。`/open-tui` 中提供**关闭、单行、双行**三种模式：
-
-- 模型推理时，思考内容的末尾片段会随 spinner 滚动（`~ think ⠋ …`）；
-- 开始输出正文时定格为对勾（`~ think ✓`）；
-- 双行模式中，上一条和最新一条思考内容使用相同的文字缩进；如果最新一行超出宽度，则两行随新 Token 持续显示它的最新末尾片段，不再保留上一条；
-- 任务结束后恢复原生 `Thinking...` 标签。
+开启 Pi 的 **Hide thinking** 后，模型工作时 pi-open-tui 会用最新推理片段替换隐藏思考块的 `Thinking...` 标签：
 
 ```text
 ~ think ⠋ 上一条思考
           最新一条思考
 ```
 
-该字幕仅在模型真正输出推理内容后出现，非推理模型不会显示。可见性由 Pi 自身的 Hide thinking 开关控制，切换后立即生效。每一行都按*显示宽度*截断（全角字符计 2 列），因此包含中文的思考文本也不会溢出终端。可在 `/open-tui` 的**常规 → 思考预览**中切换，或直接修改 `open-tui.json` 中的 `thinkingPeek.lines`。
+在**常规 → 消息与工具 → 思考预览**中选择**关闭、单行或双行**。字幕仅在模型真正输出推理时出现，正文开始后变为对勾，任务结束后恢复原生标签。可见性随 Pi 的 Hide thinking 开关立即变化，文字会按可用宽度截断。
 
 ## 工具视图
 
-默认仍为**原生**模式。将**常规 → 工具视图**设为**紧凑**（`toolView.mode: "compact"`）后，Pi 内置工具（`read`、`bash`、`powershell`、`edit`、`write`、`grep`、`find`、`ls`）显示为一行调用加一行摘要，编辑和写入成功时附带预览：
+默认使用**原生**模式。在**常规 → 消息与工具 → 工具视图**中选择**紧凑**后，Pi 内置工具（`read`、`bash`、`powershell`、`edit`、`write`、`grep`、`find`、`ls`）显示为调用行和摘要行：
 
 ```text
 ● Read(extensions/open-tui/footer.ts:1-120)
@@ -179,18 +111,17 @@ TPS 的计算方式是：将本次运行中服务商报告的全部 Assistant
   └  Done · 131 lines · 6.4s
 ```
 
-- 成功后调用与摘要文字变暗，圆点为绿色；等待时圆点变暗，运行时圆点每秒在主题强调色与暗色之间切换。错误继续显示红色圆点与摘要。Shell 失败摘要保留最后一行输出；运行中显示最新 3 行输出和已用时间。
-- `edit` 成功预览解析 Pi 的真实 diff，分别对旧代码和新代码做语法高亮。删除/新增行使用红/绿整行背景色带，在终端右边缘前留出两列。仅相邻且配对、共享非空白内容至少占 30% 的删除/新增行使用更强的变更词背景；超出匹配预算时回退到整行高亮。没有有效 diff 时保留摘要。
-- `write` 成功预览使用正常、中性的终端背景，显示行号和语法高亮，不带 `+` 号。新建与覆盖写入显示相同，不对比旧文件。部分结果和错误不显示成功预览。
-- 预览正文最多显示 16 行；超过时显示前 16 行，加上隐藏行数与 `Ctrl+O` 提示。编辑的上下文行和省略行也计入行数。仅紧凑模式下，长行以 `…` 横向截断，不自动换行。
-- 点击某行只展开这一行为 Pi 原生卡片，`Ctrl+O` 展开全部行；原生展开视图的完整输出、diff 和截断提示保持不变。各次调用独立显示，不分组，也不增加配置项。
-- 只改变显示：工具、参数、结果以及模型看到的内容都不受影响。仅接管 Pi 确认来源为内置的工具；第三方和 MCP 工具（包括替换内置同名工具的扩展）保持各自的渲染。
-- 紧凑摘要会标记输出截断，包括 grep 的长行截断；方括号正文和失败信息会保留，不会被误当成工具通知删除。
-- 模式在 Pi 创建某行时确定，因此切换只影响新建的行；执行 `/reload` 或新开会话后整个记录都会应用。
+- `edit` 和 `write` 成功后显示带语法高亮的预览，最多 16 行，较长输出会提示展开。
+- Shell 运行时显示近期输出和已用时间；出错时保留错误摘要。
+- 点击某行展开其原生卡片，`Ctrl+O` 展开全部行。工具、参数、结果和模型看到的内容都不改变。
+- 开启**紧凑显示扩展工具**可包含扩展和 MCP 工具；需要保留原生显示的工具可写入配置文件中的 `toolView.exclude`。识别到的 `@ff-labs/pi-fff` 工具使用专门的搜索摘要。
+- 切换模式只影响新建的行；执行 `/reload` 或新开会话后，整个记录都会应用。
+
+预览规则、扩展摘要和渲染器兼容性见[工具渲染细节](./docs/implementation.md#工具渲染)。
 
 ## 复制按钮
 
-全屏模式（Pi 的 `tuiMode: "fullscreen"`）下，每个代码块都会画在圆角边框里，顶边显示语言和始终可见的 `[Copy]` 标签；每条用户消息也有 `[Copy]` 标签。点击即可把原始文本放入剪贴板，Pi 会短暂提示 `Copied!`。
+全屏模式（Pi 的 `tuiMode: "fullscreen"`）下，完成的代码块会在宽度足够时，在圆角边框中显示可点击的 `[Copy]` 标签；用户消息也有复制标签。点击后复制原文，Pi 会短暂提示 `Copied!`。
 
 ```text
 ╭─ sh ─────────────── [Copy] ╮
@@ -198,15 +129,16 @@ TPS 的计算方式是：将本次运行中服务商报告的全部 Assistant
 ╰────────────────────────────╯
 ```
 
-- 代码块：边框替代了上下两行围栏，代码块高度不变；过长的行在边框内换行。标签复制不含围栏的代码，保留缩进和制表符。用户消息和助手回复里的代码块都适用。
-- 用户消息：标签位于气泡最后一行，复制你输入的原文。
-- 整条助手回复没有标签，请使用 Pi 的 `/copy`。
-- 回复输出过程中代码块只有边框、没有标签，避免复制到不完整的代码；边框太窄时也不显示标签；思考块保留 Pi 原生的围栏。
-- 普通模式不捕获鼠标，代码块保留 Pi 原生的围栏。
-- 拖动选择经过边框时会包含边框字符和 `[Copy]` 文字。
-- 如果同时安装了 pi-pretty-tui，则保留它自己的代码块边框和复制按钮，不再绘制这些内容。
+代码标签复制不含围栏的代码，保留缩进和制表符；用户消息标签复制输入原文。流式代码块会在输出结束后显示标签；普通模式和思考块保留 Pi 原生围栏。复制整条助手回复请使用 Pi 的 `/copy`。
+
+可在**常规 → 消息与工具 → 复制按钮**中开关此功能。宽度限制、代码块缓存和与其他渲染器共存的细节见[复制按钮说明](./docs/implementation.md#复制按钮行为)。
+
+## 文档
 
-可在 `/open-tui` 的**常规 → 复制按钮**中切换，或直接修改 `open-tui.json` 中的 `copyButtons`。
+- [配置参考](./docs/configuration.md#简体中文) — 完整默认值、配置项和图标选择规则
+- [实现与兼容性](./docs/implementation.md#简体中文) — 指标公式、布局、渲染和生命周期
+- [扩展底栏接口（英文）](./docs/footer-segments.md) — 面向扩展开发者的公开事件和接入示例
+- [更新日志](./CHANGELOG.md) — 已发布和待发布的改动
 
 ## 本地开发
 
@@ -217,7 +149,7 @@ npm run typecheck
 pi -e .
 ```
 
-CI 在 Linux、Windows、macOS 上，使用 Node.js 22.19.0 和 24，检查 Pi 1.2.0 及最新版本。核对兼容性时应让各个 Pi 包保持同一版本。自动化测试不能替代通过 `pi -e .` 检查终端字体、鼠标交互和光标支持。
+CI 在 Linux、Windows、macOS 上，使用 Node.js 22.19.0 和 24 检查 Pi 1.5.0 及最新版本。核对兼容性时应让所有 Pi 包保持同一版本。终端字体、鼠标交互和光标支持可通过 `pi -e .` 实际检查。
 
 ## 致谢
 
@@ -227,6 +159,7 @@ CI 在 Linux、Windows、macOS 上，使用 Node.js 22.19.0 和 24，检查 Pi 1
 - **[pi-claude-code-tui](https://github.com/Phoobobo/pi-claude-code-tui)** — Pi Logo 图案与圆角编辑器边框技术
 - **[pi-zentui](https://github.com/lmilojevicc/pi-zentui)** — Starship 风格底栏、运行环境检测、会话生命周期和设置界面模式
 - **[pi-tps](https://github.com/monotykamary/pi-tps)** — 单轮计时、停顿检测和保守的 TPS 计算方式
+- **[pi-polish](https://github.com/Pringled/pi-extensions/blob/main/packages/pi-polish)** — 紧凑的工具调用行和带语法高亮的编辑 diff
 
 Logo 图案源自 Pi 官方安装脚本（`pi.dev/install.sh`）。运行环境检测和 Git porcelain 解析借鉴了 `pi-zentui` 的结构。
 

package/docs/configuration.md

@@ -0,0 +1,245 @@
+# Configuration reference / 配置参考
+
+[English](#english) | [简体中文](#简体中文) | [Default JSON / 默认 JSON](#default-json)
+
+## English
+
+For installation and feature examples, see the [README](../README.md). This reference covers all settings accepted by `open-tui.json`. The sources are [config.ts](../extensions/open-tui/config.ts), [settings-command.ts](../extensions/open-tui/settings-command.ts), and [icons.ts](../extensions/open-tui/icons.ts).
+
+### Storage and loading
+
+The file is stored in Pi's agent directory: `~/.pi/agent/open-tui.json` by default, or `<PI_CODING_AGENT_DIR>/open-tui.json` when that environment variable is set. The extension creates the file with defaults if it is missing and the directory is writable.
+
+You only need to specify values you want to change; missing fields inherit [the defaults](#default-json). Flags must be JSON booleans, not strings such as `"false"`. Invalid known values fall back to their defaults, and unreadable or malformed JSON falls back to the default configuration with a warning. Direct file edits are loaded on `/reload` or a new session. If saving from `/open-tui` fails, the new values still apply to the current session and a warning asks you to check directory permissions and free space.
+
+### Settings dialog
+
+| Tab | Sections |
+| --- | --- |
+| General | Extension, Interface, Messages & tools, Footer |
+| Appearance | Icons, Editor |
+| Footer | Location, Git, Runtime, Usage, Other |
+| Telemetry | Enabled (standalone master switch), Measurements |
+
+Tab/Shift+Tab or ←/→ switches tabs; ↑/↓ or Page Up/Page Down moves between settings; Enter/Space changes a value; Esc/q closes the dialog. Dim section headings occupy rows but cannot be selected or changed. The scroll position counts both headings and settings.
+
+**Compact extension tools** appears only while **Tool view** is Compact. Switching to Native hides it while retaining its value. Installing or removing the UI through the **Enabled** switch is deferred until the dialog closes. Existing configuration files need no migration.
+
+### General options
+
+| Key | Default | Values and behavior |
+| --- | --- | --- |
+| `enabled` | `true` | Master switch for open-tui |
+| `header` | `true` | Replaces the header; disable to leave that slot to Pi or another extension |
+| `inlineFooter` | `false` | Moves the two main footer rows into a compatible editor's borders; extension status rows remain separate |
+| `copyButtons` | `true` | Code-block and user-message Copy labels in fullscreen mode |
+| `settingsLanguage` | `"en"` | `"en"` or `"zh"`; changes the settings interface language |
+| `cursorStyle` | `"block"` | `"block"`, `"bar"`, or `"underline"`; the latter two need terminal cursor-shape support |
+| `icons.mode` | `"auto"` | `"auto"`, `"nerd"`, `"unicode"`, or `"ascii"`; see [Icons](#icons) |
+| `thinkingPeek.lines` | `1` | `0` (off), `1`, or `2`; visible while Pi's Hide thinking setting is on and reasoning is streamed |
+| `toolView.mode` | `"native"` | `"native"` or `"compact"`; selected when Pi creates each tool row |
+| `toolView.extensionTools` | `false` | In compact mode, includes extension, MCP, and replacement tools |
+| `toolView.exclude` | `[]` | Exact tool names that keep native rendering, including built-ins; edited in the JSON file only |
+
+For example, `"toolView": { "mode": "compact", "extensionTools": true, "exclude": ["edit", "subagent_wait"] }` enables compact rendering while preserving those two tools' native cards. Use `/reload` or a new session to rebuild existing rows with the new tool-view settings.
+
+### Footer options
+
+All keys below are booleans inside `footerSegments`.
+
+| Key | Default | Content or effect |
+| --- | --- | --- |
+| `cwd` | `true` | Current working directory, shortened when needed |
+| `hostname` | `false` | Short host name (before the first dot) with a server icon |
+| `sessionName` | `false` | Session name, when one is set |
+| `gitBranch` | `true` | Branch name, or `HEAD` and a short commit hash in detached HEAD state |
+| `gitStatus` | `true` | Conflicted, deleted, modified, renamed, staged, untracked, stashed, and ahead/behind counts |
+| `gitCommit` | `false` | Tag pointing at the detached HEAD commit; only used when `gitBranch` is on |
+| `runtime` | `true` | Detected project runtime and its version when available |
+| `context` | `true` | Context bar, percentage, and token usage |
+| `tokens` | `true` | Cumulative input/output tokens and the latest assistant cache-hit percentage |
+| `cost` | `true` | Cumulative session cost reported by Pi |
+| `liveTps` | `true` | Estimated streaming speed beside the working timer |
+| `extensionStatuses` | `true` | Separate `ctx.ui.setStatus()` rows, including MCP status |
+| `extensionSegments` | `true` | Contributions embedded in the main rows through the [footer event API](./footer-segments.md) |
+| `capitalizeProviderName` | `true` | Capitalizes the provider's first character; disable to retain original casing |
+| `nerdIconSpacing` | `false` | Adds one blank cell after Nerd Font icons, including runtime icons |
+
+The provider/model and working/done timer do not have separate visibility switches; `liveTps` controls only the speed estimate. `extensionSegments` controls visibility, so hidden contributions still receive updates and their lifecycle stays available. It is independent of `extensionStatuses`.
+
+### Telemetry options
+
+All keys below are booleans inside `telemetry` and default to `true`.
+
+| Key | Effect |
+| --- | --- |
+| `enabled` | Master switch for the end-of-run notification |
+| `tps` | Provider-based output tokens per second |
+| `ttft` | Time to first output |
+| `duration` | Full agent-run duration |
+| `tokens` | Assistant input/output counts for measured turns |
+| `stalls` | Stream pauses, shown only when detected |
+| `cost` | Effective dollar rate per million reported tokens |
+
+The footer's live-speed estimate has its own `footerSegments.liveTps` switch. See [usage and telemetry](./implementation.md#usage-and-telemetry) for measurement definitions and limitations.
+
+### Icons
+
+| `icons.mode` | Selection |
+| --- | --- |
+| `auto` | ASCII when stdout is not a TTY, `TERM=dumb`, or the first configured locale (`LC_ALL`, `LC_CTYPE`, `LANG`) is not UTF-8. Otherwise Unicode when `SSH_TTY` or `SSH_CONNECTION` is set, and Nerd Font locally. An unset locale passes the UTF-8 check |
+| `nerd` | Always use Nerd Font glyphs |
+| `unicode` | Portable Unicode symbols; emoji use the terminal's own fallback font |
+| `ascii` | Plain-text symbols |
+
+Auto detection does not inspect installed fonts. Configure a Nerd Font in the terminal profile or choose `unicode`/`ascii` if symbols are missing. If the SSH client terminal has a Nerd Font, select `nerd` explicitly.
+
+For wide Nerd glyphs that consume the gap before a label, enable **Footer → Other → Extra space after Nerd icons** (`footerSegments.nerdIconSpacing`). This affects regular and inline footers; Unicode/ASCII icons and compact Git flags are unchanged. In Kitty, `narrow_symbols U+E000-U+F8FF 1` in `kitty.conf` is an alternative.
+
+## 简体中文
+
+安装和功能示例见 [README](../README.zh-CN.md)。本参考列出 `open-tui.json` 接受的全部设置，依据为 [config.ts](../extensions/open-tui/config.ts)、[settings-command.ts](../extensions/open-tui/settings-command.ts) 和 [icons.ts](../extensions/open-tui/icons.ts)。
+
+### 存储与加载
+
+配置位于 Pi 的 agent 目录，默认路径为 `~/.pi/agent/open-tui.json`；设置 `PI_CODING_AGENT_DIR` 后则使用 `<PI_CODING_AGENT_DIR>/open-tui.json`。文件不存在且目录可写时，扩展会创建默认配置。
+
+只需填写要修改的值，缺失字段会补入[默认值](#default-json)。布尔开关应使用 JSON 布尔值，不能写成 `"false"` 这样的字符串。已知字段的无效值会回退到默认值；无法读取或解析 JSON 时，会提示警告并使用默认配置。直接编辑文件后，执行 `/reload` 或新开会话加载。如果从 `/open-tui` 保存失败，新值仍在当前会话生效，并提示检查目录权限和可用空间。
+
+### 设置窗口
+
+| 页面 | 分组 |
+| --- | --- |
+| 常规 | 扩展、界面、消息与工具、底栏 |
+| 外观 | 图标、输入框 |
+| 底栏 | 位置、Git、运行环境、用量、其他 |
+| 遥测 | 启用（独立总开关）、测量指标 |
+
+Tab/Shift+Tab 或 ←/→ 切页，↑/↓ 或 Page Up/Page Down 移动，Enter/Space 修改值，Esc/q 关闭。暗色分组标题占一行，但不能选中或修改；滚动位置同时统计标题行和设置行。
+
+**紧凑显示扩展工具**仅在**工具视图**为紧凑时显示；切回原生后隐藏，但保留开关值。通过**启用**开关安装或移除界面会延迟到窗口关闭后执行。现有配置文件无需迁移。
+
+### 常规选项
+
+| 键 | 默认值 | 可选值与行为 |
+| --- | --- | --- |
+| `enabled` | `true` | open-tui 总开关 |
+| `header` | `true` | 替换顶栏；关闭后把位置留给 Pi 或其他扩展 |
+| `inlineFooter` | `false` | 将两条主底栏行移入兼容编辑器的边框，扩展状态行保持独立 |
+| `copyButtons` | `true` | 全屏模式中代码块和用户消息的复制标签 |
+| `settingsLanguage` | `"en"` | `"en"` 或 `"zh"`，控制设置界面的语言 |
+| `cursorStyle` | `"block"` | `"block"`、`"bar"` 或 `"underline"`，后两种需要终端支持光标形状控制 |
+| `icons.mode` | `"auto"` | `"auto"`、`"nerd"`、`"unicode"` 或 `"ascii"`，见[图标](#图标) |
+| `thinkingPeek.lines` | `1` | `0`（关闭）、`1` 或 `2`；Pi 开启 Hide thinking 且模型输出推理时可见 |
+| `toolView.mode` | `"native"` | `"native"` 或 `"compact"`，每条工具行创建时确定 |
+| `toolView.extensionTools` | `false` | 紧凑模式下包含扩展、MCP 和替换内置工具的扩展 |
+| `toolView.exclude` | `[]` | 保持原生渲染的完整工具名，可包含内置工具；仅在 JSON 文件中编辑 |
+
+例如 `"toolView": { "mode": "compact", "extensionTools": true, "exclude": ["edit", "subagent_wait"] }` 会启用紧凑模式，并让这两个工具保留原生卡片。执行 `/reload` 或新开会话，可让已有工具行按新设置重建。
+
+### 底栏选项
+
+下面各键均为 `footerSegments` 内的布尔值。
+
+| 键 | 默认值 | 内容或作用 |
+| --- | --- | --- |
+| `cwd` | `true` | 当前工作目录，必要时缩短 |
+| `hostname` | `false` | 主机短名称，即第一个点之前的部分，配合服务器图标 |
+| `sessionName` | `false` | 会话名称，仅在已设置名称时显示 |
+| `gitBranch` | `true` | 分支名称；分离 HEAD 时显示 `HEAD` 和短提交哈希 |
+| `gitStatus` | `true` | 冲突、删除、修改、重命名、已暂存、未跟踪、stash 和 ahead/behind 数量 |
+| `gitCommit` | `false` | 指向分离 HEAD 提交的标签，仅在 `gitBranch` 开启时使用 |
+| `runtime` | `true` | 检测到的项目运行环境，以及可获取时的版本号 |
+| `context` | `true` | 上下文进度条、百分比和 Token 用量 |
+| `tokens` | `true` | 累计输入/输出 Token，以及最新助手回复的缓存命中率 |
+| `cost` | `true` | Pi 报告的会话累计费用 |
+| `liveTps` | `true` | 工作计时器旁的流式速度估算 |
+| `extensionStatuses` | `true` | 独立的 `ctx.ui.setStatus()` 状态行，包括 MCP 状态 |
+| `extensionSegments` | `true` | 扩展通过[底栏事件接口](./footer-segments.md)嵌入主信息行的内容 |
+| `capitalizeProviderName` | `true` | 将服务商名称首字母大写；关闭后保留原始大小写 |
+| `nerdIconSpacing` | `false` | Nerd Font 图标后额外留一格，包括运行环境图标 |
+
+服务商/模型和工作/完成计时器没有独立显示开关，`liveTps` 仅控制速度估算。`extensionSegments` 只控制可见性，隐藏内容仍接收更新，生命周期仍保持可用；它与 `extensionStatuses` 相互独立。
+
+### 遥测选项
+
+下面各键均为 `telemetry` 内的布尔值，默认全部为 `true`。
+
+| 键 | 作用 |
+| --- | --- |
+| `enabled` | 运行结束通知的总开关 |
+| `tps` | 基于服务商用量的每秒输出 Token |
+| `ttft` | 首次输出延迟 |
+| `duration` | Agent 完整运行耗时 |
+| `tokens` | 被统计轮次的助手输入/输出数量 |
+| `stalls` | 流式输出停顿，仅检测到时显示 |
+| `cost` | 每百万报告 Token 的综合美元费率 |
+
+底栏实时速度使用独立的 `footerSegments.liveTps` 开关。指标定义和限制见[用量与遥测](./implementation.md#用量与遥测)。
+
+### 图标
+
+| `icons.mode` | 选择规则 |
+| --- | --- |
+| `auto` | stdout 不是 TTY、`TERM=dumb`，或首个已设置的 locale（依次为 `LC_ALL`、`LC_CTYPE`、`LANG`）不是 UTF-8 时使用 ASCII。否则，存在 `SSH_TTY` 或 `SSH_CONNECTION` 时使用 Unicode，本地使用 Nerd Font。未设置 locale 时通过 UTF-8 检查 |
+| `nerd` | 始终使用 Nerd Font 字形 |
+| `unicode` | 可移植 Unicode 图标，emoji 使用终端自身的回退字体 |
+| `ascii` | 纯文本图标 |
+
+自动检测不会检查已安装字体。图标缺失时，请在终端配置中选中 Nerd Font，或切换到 `unicode`/`ascii`。SSH 客户端终端已配置 Nerd Font 时，可显式选择 `nerd`。
+
+如果较宽的 Nerd Font 图标占用了标签前的间隔，可开启**底栏 → 其他 → Nerd 图标后额外留空**（`footerSegments.nerdIconSpacing`）。普通和内嵌底栏都适用，Unicode/ASCII 图标和紧凑 Git 状态标记不受影响。Kitty 用户也可在 `kitty.conf` 中设置 `narrow_symbols U+E000-U+F8FF 1`。
+
+## Default JSON
+
+The complete default configuration is shared by both language references. Set `settingsLanguage` to `"zh"` for the Chinese settings interface.
+
+以下为两种语言共用的完整默认配置。将 `settingsLanguage` 改为 `"zh"` 即可使用中文设置界面。
+
+```json
+{
+  "enabled": true,
+  "header": true,
+  "inlineFooter": false,
+  "copyButtons": true,
+  "settingsLanguage": "en",
+  "cursorStyle": "block",
+  "icons": {
+    "mode": "auto"
+  },
+  "footerSegments": {
+    "cwd": true,
+    "hostname": false,
+    "sessionName": false,
+    "gitBranch": true,
+    "gitStatus": true,
+    "gitCommit": false,
+    "runtime": true,
+    "context": true,
+    "tokens": true,
+    "cost": true,
+    "liveTps": true,
+    "extensionSegments": true,
+    "extensionStatuses": true,
+    "capitalizeProviderName": true,
+    "nerdIconSpacing": false
+  },
+  "telemetry": {
+    "enabled": true,
+    "tps": true,
+    "ttft": true,
+    "duration": true,
+    "tokens": true,
+    "stalls": true,
+    "cost": true
+  },
+  "thinkingPeek": {
+    "lines": 1
+  },
+  "toolView": {
+    "mode": "native",
+    "extensionTools": false,
+    "exclude": []
+  }
+}
+```