$ cat ~/map/pi-vterm.md

pi-vterm

在按项目划分的 Emacs vterm 缓冲区运行 pi：会话恢复、@file 补全插入、复制模式改进。

tools✓ 9月14日

事实速查

安装

用 use-package 配 package-vc 从 https://github.com/snowiow/pi-vterm 安装（或本地 checkout 走 :load-path）；需 Emacs 28.1+、emacs-libvterm 与 exec-path 上的 pi 可执行文件

## 速览

把 pi 运行在按项目划分的 Emacs vterm 缓冲区里：保留 pi 原生终端界面，补上按项目命名、@file 补全插入与更接近普通缓冲区的复制模式。

## 要点

$在当前 project.el 项目里启动 pi，并生成可辨识的按项目缓冲区名；M-x pi-vterm 新建会话，M-x pi-vterm-resume 携带 pi 的恢复参数（默认 -r）恢复上次会话。
$M-x pi-vterm-insert-file 用 Emacs 补全选文件，并把相对路径的 @file 提及插入 pi。
$vterm-copy-mode 改进：复制 TUI 输出时保留所显示的换行，行移动、光标与区域的行为更接近普通 Emacs 缓冲区；照常选中文本后按 RET 即复制所选内容并退出复制模式。
$M-x pi-vterm-mode 可在已经跑着 pi 的既有 vterm 缓冲区里启用这些复制模式改进。
$经 customize-group pi-vterm 可配置 pi-vterm-executable、pi-vterm-arguments、pi-vterm-resume-arguments、pi-vterm-buffer-name、pi-vterm-project-buffer-name-format 与 pi-vterm-remap-region-face。
$该包有意不定义任何默认全局按键。

## 常见问题

Q pi-vterm 会替换 pi 的 TUI 吗？

不会——pi 的原生终端界面原样保留在 vterm 缓冲区里；这个包改进的是外围的 Emacs 集成，比如项目化缓冲区、文件插入与复制模式行为。

Q 有默认按键绑定吗？

没有——它有意不定义默认全局绑定；README 的 use-package 示例把 pi-vterm、pi-vterm-resume 与 pi-vterm-insert-file 绑在 C-c a 前缀下。

## 参考链接

## 相关条目

## 教程

最后更新: 2026年9月14日