pi-better-btw-plus

English | 简体中文

面向 pi（编码 agent）的侧聊浮层扩展。主线 agent 继续干活的同时，/btw 把当前会话 fork 到一个独立浮层——查个 API 细节、验证一个思路，拿到答案就关掉。主线全程不受打扰。

功能

侧聊

• 不抢占主线的 fork——侧聊是从当前会话克隆出的独立 agent，渲染在顶部浮层；主编辑器保持可见，主线照常运行。
• 默认只读——越权工具调用会被直接拦截（第二次违规升级并中止该轮）；peek_main 按需读取主线近期活动；Alt+T 切换编辑模式。
• 前缀缓存友好——侧聊请求与主线共享上下文，能命中网关前缀缓存，更快更省。
• 会话工具——从最新主线上下文重新 fork（Alt+R）、开启空白对话（Alt+N）、后台化不丢状态（Alt+W）、导出对话记录（Alt+E）、用 prompt pack 覆盖任意注入提示。
• 文件冲突防护——侧聊打开期间主线写过的文件会受到保护：向这些路径写入前会先要求确认。

与 pi 官方保持一致

不引入自创的交互语言，快捷键与行为都遵循 pi 官方惯例，侧聊用起来和主会话完全一样：

• 快捷键与主会话一致——复制/清空、粘贴、复制消息、模型选择、键位表均遵循 pi 官方绑定（tui.input.copy、app.clear、app.clipboard.pasteImage、app.message.copy、app.model.select、app.tools.expand）；键位冲突时让位给 pi：Alt+T 切换模式，把 Ctrl+T 留给 pi 的思考开关。
• 行为与主会话一致——重试、溢出判断、剪贴板、模型选择的行为与 pi 本身一致，浮层布局也沿用 pi 的窗口几何。

终端肌肉记忆，浮层内重新实现

侧聊打开期间独占终端鼠标，主会话从 Windows Terminal 或 AgentSession 继承的那些便利，需要在浮层里重新实现：

功能	说明
输入框选区	输入框内拖选实时反色高亮；双击选词、三击选中整行。Ctrl+C / Ctrl+Shift+C 复制。
右键复制与粘贴	聊天区拖选后右键复制（延续 Windows Terminal 肌肉记忆）；输入框右键把系统剪贴板内容粘贴进来，通过编辑器自带的粘贴逻辑。
Fork 模型切换（Ctrl+L）	侧聊内可随时换用任意已配置的模型，无需重建 fork；只对侧聊生效，主线模型不受影响。
单轮自动重试	与主会话共用 settings.retry 预算；服务商出现暂时性错误时自动退避重试，带实时倒计时，Esc 可取消。
Ctrl+C 清空输入	无选区时 Ctrl+C 清空输入框；复制成功后选区消失，下一次 Ctrl+C 恢复清空行为。
Alt+Shift+C 复制整个草稿	复制全部草稿文本，粘贴标记展开——与真正提交给 agent 的内容完全一致；不支持 kitty 协议的终端也能用。
键位表弹窗（Ctrl+O）	底部提示条只显示高频键；按 Ctrl+O 弹出完整键位表，按功能分组。
功能开关	features.rightClickCopyPaste / modelSwitch / retry / editorSelection 按配置层逐项关闭。

浮层打开期间会接管全部鼠标操作：滚轮滚动、拖拽选择、右键复制/粘贴；Alt+W 后台化后鼠标交还给终端。

输入框选区

• 拖选——反色高亮实时跟随（约 30fps）。
• 双击——选中光标下的词；三击——选中整行。
• 选区是临时的：打字或移动光标即消失；不会跨过 [paste #N …] 粘贴标记；自动补全弹窗打开时禁用。

安装与快速上手

pi install npm:pi-better-btw-plus

pi TUI 中用 /btw（或原名 /side）或 Alt+W 打开。提问、Enter 发送、Esc 关闭；重新打开继续同一段对话。

[!NOTE] 已验证与 pi 1.3.0 兼容。

快捷键

按键	作用
Alt+W	打开（关闭时）/ 后台化（显示时）/ 恢复（隐藏时）
Ctrl+O	弹出完整的键位表
Enter / Esc	发送 / 中断流式输出或取消重试等待；空闲时关闭
Alt+T	切换只读 / 编辑模式
Alt+R	从最新主线上下文重新 fork
Alt+N	开始空白对话
Alt+E	导出对话到 $CWD/.agents/eval/pi-better-btw-<timestamp>.md
Ctrl+L	Fork 模型选择器（↑/↓ 选择，Enter 确认，Esc 取消）
Ctrl+C / Ctrl+Shift+C	复制当前选区（聊天区或输入框）；无选区时 Ctrl+C 清空输入
Ctrl+X	复制最后一条侧聊助手消息
Alt+Shift+C	复制输入框全部文本（粘贴标记展开）
Ctrl+V / Alt+V	把系统剪贴板内容粘贴进输入框
PgUp / PgDn、Shift+↑ / Shift+↓、鼠标滚轮	滚动聊天历史
鼠标拖拽 / 双击	选择聊天文本（反色高亮）/ 选中整行
鼠标右键	复制保留的选区（聊天区）/ 粘贴（输入框）

命令

• /btw、/side——打开侧聊（两个命令均已注册、效果相同；/btw 与项目同名，/side 是沿用旧名）。
• peek_main——仅侧聊 agent 可用；按需读取主线会话近期活动。lines（默认 20，最大 50）、since_fork（仅显示侧聊打开之后的活动）。

配置

config.json 从三层读取，按键由后层覆盖前层：

层	位置
Bundle（默认）	包内 config.json
用户	~/.pi/agent/pi-better-btw/config.json
项目	<project>/.pi/pi-better-btw/config.json

• features——功能开关，每项默认 true：rightClickCopyPaste、modelSwitch、retry、editorSelection。
• readOnlyExtensionAllowlist——只读模式下允许调用的扩展工具；各层取并集，内置 read/grep/find/ls 与 peek_main 始终包含。
• readOnlyExtensionAllowlistExclude——移除内置默认项。
• promptPack——用你自己的 markdown 文件覆盖任意注入提示（如 framing、焦点锚、越界提醒），缺失的键回退到包内自带 prompts/。

{
  "readOnlyExtensionAllowlist": ["pi-vision-helper"],
  "features": { "editorSelection": false }
}

工作原理

• 侧聊是把当前会话克隆出的独立 agent，渲染在顶部浮层——主编辑器保持可见，主线照常运行。
• 只读模式（默认开启）强制生效：越权工具调用被直接拦截，第二次违规升级并中止该轮。peek_main 按需读取主线近期活动。
• 浮层打开期间会接管鼠标：滚轮滚动、拖拽选择、右键复制/粘贴；Alt+W 后台化后鼠标交还给终端。

开发

pi 直接加载 TypeScript，无构建步骤。把 pi 的扩展加载器指向 ./srcs/index.ts（入口；srcs/ 其余文件为浮层、越界拦截、重试与剪贴板相关代码），改完 /reload 即可。

bun install
bun run typecheck
bun test

限制

• 同一时间只能开一个侧聊；无法在另一个可见浮层之上打开。
• 不会把消息合并回主线会话。
• bash 写入冲突检测是启发式的——覆盖常见写模式，并非全部。
• peek_main 按需读取，非实时。
• 鼠标交互仅在常规（非全屏）TUI 模式下可用。

License 与起源

MIT —— 见 LICENSE。本项目是 @yceachan/pi-better-btw 的持续维护 fork，其上游是 nicobailon/pi-side-chat。保留全部三行版权：Nico Bailon、yceachan、hu3rror。