pi-path-bar

English | 简体中文

Pi 底栏扩展。支持简短路径、目录别名和随主题调整的 Git 状态颜色。

 ~/C/P/demo-app ( main)
 Projects/demo-app ( main +2 !1 ?3)
 demo ( main ⇡1)

功能

• 简短、自动和完整路径显示模式。
• 为任意文件夹设置显示别名，不改变实际路径或环境变量。
• 随主题调整的别名颜色，以及 Tide 风格的 Git 状态标记。
• 交互式设置菜单，自动保存配置。
• 保留用量统计、模型信息和其他扩展的状态行。
• 支持中文等 Unicode 目录名和别名。

安装

首次发布到 npm 后，可以从 npm 安装：

pi install npm:pi-path-bar
# 或仅在本次启动中使用：
pi -e npm:pi-path-bar

首次发布前，或需要使用 Git 来源时，从 GitHub 安装：

pi install git:github.com/johnbitcn/pi-path-bar

在已运行的 Pi 中执行 /reload，再输入 /path-bar。

仅在本次启动中使用：

pi -e git:github.com/johnbitcn/pi-path-bar

本地开发时，在项目目录执行：

pi install "$PWD"
# 或仅在本次启动中加载扩展：
pi -e ./src/index.ts

只加载一份扩展。切换安装来源前，先移除已有的本地或 Git 安装。目录图标需要 Nerd Font；也可在设置中关闭图标。

设置

执行 /path-bar。上下键选择，Enter 或空格切换设置或打开操作，Esc 退出。修改立即生效，并自动保存。扩展界面使用英文。

设置项	默认值	可选值
Path display（路径显示）	Short	Short、Auto、Full、Native footer
Folder icon（目录图标）	On	On、Off
Git status（Git 状态）	On	On、Off
Session name（会话名称）	On	On、Off
Add folder alias（添加目录别名）	—	输入文件夹路径和名称
Manage folder aliases（管理目录别名）	—	修改或删除别名

Native footer 恢复 Pi 原生底栏。其他显示设置会保留，但在该模式下不生效。

路径显示模式

• **Short：**始终将中间目录缩写为首个字素，支持中文等 Unicode 名称。
• **Auto：**宽度足够时显示完整路径，否则缩写。
• **Full：**不缩写，超出宽度时截断。

Short 和 Auto 在宽度不足时将中间目录折叠为 …。极窄时，先省略起点与图标，再截断最后一级目录名。

主目录显示为 ~。~ 和目录别名等命名起点前显示目录图标。以 / 开头的绝对路径不显示图标。

目录别名

选择 Add folder alias，可以给任意文件夹命名。输入绝对路径或 ~/ 开头的路径。路径留空直接按 Enter，则使用当前目录。目标必须存在且为文件夹。

例如，将 ~/CloudDrive 命名为 Cloud：

 Cloud
 Cloud/P/demo-app

也可以将 ~/CloudDrive/Projects/demo-app 命名为 demo。该目录显示为  demo，其子目录显示为  demo/src。

匹配和编辑规则

• 别名匹配该目录及其子目录，按目录边界匹配。
• 多个别名同时匹配时，使用最长路径。父级和子级别名不会叠加。
• 宽度允许时保留完整别名。其后的目录按所选模式处理。
• 没有匹配时，使用 ~ 或绝对路径。
• 保存时规范化路径并展开 ~，但不解析符号链接。
• 路径和名称不能重复。名称不能为空、~、. 或 ..，不能包含斜杠、反斜杠、换行或控制字符。
• 修改时，字段留空表示保留原值。Esc 取消。
• 删除别名不会删除实际文件夹。磁盘暂时离线时，已有别名仍会保留。

仅命中的别名名称使用 Pi 主题的 mdLink 色。内置暗色主题使用较亮的蓝色，亮色主题使用较深的蓝色。自定义主题以其链接色为准。图标、子目录和会话名使用灰色；Git 信息使用状态色。切换主题后颜色同步更新。

别名只影响底栏，不改变工作目录、工具访问路径或环境变量。

Git 状态

借用 Tide 的标记形式，但使用 Pi 主题文字色，不使用背景色。扩展不会修改 fish 或 Tide。

状态	主题色	内置主题效果
初次读取或查询失败	text	默认文字色，显示 ?
工作区干净	mdLink	蓝色
有已暂存、未暂存或未跟踪变更	warning	黄色
有冲突或正在进行 Git 操作	error	红色

优先级：红色 > 黄色 > 蓝色。不在 Git 仓库时隐藏 Git 信息。目录别名颜色不受 Git 状态影响。

 demo ( main ⇣2 ⇡1 *1 ~2 +3 !4 ?5)

标记	含义
⇣N	落后上游 N 个提交
⇡N	领先上游 N 个提交
*N	N 条 stash
~N	N 个冲突文件，覆盖 DD AU UD UA DU AA UU
+N	N 个已暂存条目
!N	N 个未暂存条目
?N	N 个未跟踪条目

数量为零时不显示。未跟踪目录按 Git 默认行为合并为一个条目。冲突文件不重复计入已暂存或未暂存数量。领先、落后和 stash 本身不改变颜色。没有上游时，不显示领先和落后。

显示 merge、rebase、cherry-pick、revert、bisect 等操作。可用时显示 rebase 进度。分离 HEAD 时显示 #标签 或 @提交短哈希。支持 linked worktree。

查询异步执行，并设有超时。每 5 秒刷新一次，也在工具执行完成、agent 回复完成或分支变化时刷新。关闭 Git 状态或选择 Native footer 后，停止扩展查询。

配置

配置在各项目间共用，保存到：

~/.pi/agent/pi-path-bar.json

若设置了 PI_CODING_AGENT_DIR，则使用该目录。扩展不会设置或修改此变量。

{
  "mode": "short",
  "icon": true,
  "branch": true,
  "session": true,
  "aliases": [
    { "path": "/home/example/Projects", "name": "Projects" }
  ]
}

branch 字段控制 Git 状态显示。配置在重启或 /reload 后保留。打开菜单时重新读取文件。保存使用临时文件和原子替换。其他已运行的 Pi 实例需要重新打开菜单或重新加载，才能同步修改。

新文件不存在时，会读取旧的 pi-show-dir.json。下次保存时写入新文件，并保留旧文件。配置损坏时会提示错误，不会覆盖原文件。

限制

• Pi 的公开 API 会替换整个底栏。其他扩展也调用 setFooter() 时，最后设置的底栏生效。
• 公开 API 不提供自动压缩开关，因此自定义底栏不显示原生 (auto) 标记。
• 这是非官方 Pi 扩展，与 Pi 或 Tide 项目无隶属或背书关系。

开发

需要 Node.js 22.19 或更新版本。Git 状态和集成测试需要 Git。

npm install --ignore-scripts
npm test
npm run check

许可证与致谢

本项目采用 MIT 许可证。Pi 和 Tide 的版权及许可文本见第三方声明。发布包不包含宿主依赖或字体文件。

维护者可参阅 npm 发布指南，了解登录、打包检查、发布和验证流程。