PiTTy

一个快速、原生终端的 OpenTUI 前端，专为 Pi 编码 agent 设计。

可滚动的对话 · 可搜索的 session 和模型 · 实时主题 · 丰富的工具输出 · 可选的 subagent、Todo 和 MCP 视图

## 安装 ### Linux、macOS 和 WSL ``` curl -fsSL https://raw.githubusercontent.com/mistrjirka/PiTTy/main/install.sh | sh ``` 然后在当前项目中启动 PiTTy： ``` pitty ``` 要求：Node.js 22.19 或更高版本、npm 以及 Pi CLI。安装程序会验证它们，下载带有版本号的发布版本，要求并验证所选归档文件在发布版 `SHA256SUMS` 文件中对应的 SHA-256 条目，安装 PiTTy 的本地 Bun runtime，并创建 `pitty` 和 `pitty-resume` 启动器。 ### Windows PowerShell ``` irm https://raw.githubusercontent.com/mistrjirka/PiTTy/main/install.ps1 -OutFile $env:TEMP\pitty-install.ps1 & $env:TEMP\pitty-install.ps1 -WithPlugins ```

安装程序选项和手动源码安装

POSIX 安装程序可以在不提示的情况下包含或跳过可选集成： ``` curl -fsSL https://raw.githubusercontent.com/mistrjirka/PiTTy/main/install.sh -o /tmp/pitty-install.sh sh /tmp/pitty-install.sh --yes --with-plugins sh /tmp/pitty-install.sh --without-plugins ``` 通过安装程序标志或 `PITTY_INSTALL_DIR`、`PITTY_BIN_DIR`、`PITTY_VERSION` 和 `PITTY_REPO` 支持自定义路径和版本。 直接从源码运行： ``` git clone https://github.com/mistrjirka/PiTTy.git cd PiTTy npm ci --ignore-scripts --no-audit --no-fund node node_modules/bun/install.js npm run typecheck node bin/pitty.mjs ```

## 常见问题

PiTTy 是常规的 Pi 扩展还是 pi -e pitty 的别名？

不是。`pitty` 会启动一个独立的 OpenTUI 前端，并使用 `--mode rpc` 启动已安装的 Pi CLI。Pi 拥有 agent runtime；PiTTy 拥有终端界面。

PiTTy 是如何构建的，它的 UI 是声明式/响应式的吗？

PiTTy 使用 TypeScript 编写，采用 OpenTUI 的 SolidJS 绑定，并在本地 Bun runtime 中运行。UI 由 JSX 组合而成，并通过 Solid signals 进行更新，因此它采用的是声明式、细粒度的响应式模型，而不是手动重绘组件树。

为什么不将其构建为常规的 Pi 扩展？

Pi 扩展可以替换 header、footer、widget 和编辑器，添加 overlay，并渲染扩展自带的工具和消息。它们目前没有提供受支持的 hook 来完全替换 Pi 的整个根布局或每个内置的 transcript 行。 PiTTy 需要控制整个屏幕，以实现其固定的编辑器、独立可滚动和窗口化的 transcript、持久的侧边栏、独立的 subagent 对话，以及全局焦点和鼠标行为。固定编辑器和滚动扩展可以改善 Pi 现有的 TUI；而 PiTTy 则是替换了整个前端。

PiTTy 会干扰正常的 Pi 安装吗？

不会。PiTTy 是独立安装的，不会替换 `pi` 可执行文件。它有意共享 Pi 的配置、凭据、模型、扩展和 session，因此 `pi` 和 `pitty` 可以同时配合使用。 安装程序可以选择通过 `pi install` 安装 `pi-subagents` 和 `@juicesharp/rpiv-todo`；这可以通过 `--without-plugins` 跳过。卸载 PiTTy 不会卸载 Pi 或这些包。

PiTTy 支持现有的 Pi 扩展吗，目前有哪些不支持？

我们的目标是支持 Pi 现有的扩展生态系统，而不是创建一个不兼容的替代品。PiTTy 目前支持通过 RPC 暴露的命令、工具、prompt 模板、技能、通知、状态更新、文本 widget、编辑器预填充，以及标准的 select、confirm、input 和编辑器对话框。 任意的 `pi-tui` 组件树不会通过 RPC 进行序列化，因此扩展自带的自定义渲染器、header、footer、编辑器、overlay 和自动补全 UI 目前无法像在 Pi 中那样准确显示。不过，它们的命令和工具通常仍可以通过 PiTTy 的通用渲染机制正常工作。原生的交互式 `/login` 目前也必须在常规的 Pi 中完成。

PiTTy 有自己的 UI 插件 API 吗？

目前没有。PiTTy 内部有针对 `pi-subagents` 和 `rpiv-todo` 的 adapter，但并未暴露稳定的第三方 UI API 来添加面板或渲染器。 创建第二个不兼容的插件生态系统并不是我们的目标。首要任务是稳定前端并支持开发过程中使用的 Pi 扩展。未来的工作应优先考虑与原有 Pi 扩展的兼容性，仅在 RPC 无法承载足够 UI 结构的地方添加 adapter。

## PiTTy 是什么 PiTTy 是 [Pi 编码 agent](https://github.com/earendil-works/pi) 的一个独立前端。它保留了 Pi 的身份验证、provider、模型、session、工具、技能、prompt 模板和扩展，同时用一个可滚动且可检查的 OpenTUI 应用程序取代了 Pi 内置的交互式终端界面。 它直接在常规聊天中启动。空的对话会显示一个被动仪表板，其中包含常用命令和最近的 session，同时 prompt 保持聚焦且可输入。

## 为什么使用 PiTTy 而不是 Pi 内置的 TUI？ - **独立检查 subagent 聊天。** 打开每个子 agent 的实时 transcript 而不会丢失主对话，活跃的 agent 优先分组，且每个组内保持稳定的排序。 - **在运行时控制工作。** 发送 steering 指令，查看其排队状态直到 pi-subagents 接管，将可编辑的后续任务加入队列，并从同一界面暂停或停止受支持的基于文件的 subagent。 - **保持工作区更宁静。** Prompt 保持固定，而 transcript 独立滚动；thinking、工具输出、待处理输入、建议、Todo 和侧边栏保持受限或可折叠状态，而不会占据整个终端。 - **更清晰地阅读代码变更。** 编辑/写入工具拥有专属的 diff 视图，任意工具保留结构化的卡片，冗长的流式对话采用稳定的窗口化渲染。 - **导航更快。** 搜索模型和 session，就地恢复工作，在早前的请求之间跳转，并从 session 本地历史记录中恢复已提交或已清除的 prompt。 - **保留 Pi 的生态系统。** PiTTy 仍然通过 RPC 使用 Pi 的身份验证、provider、模型、session、工具、技能、prompt 模板和扩展。 ## 亮点 | 领域 | PiTTy 增加的功能 | | --- | --- | | 对话 | 固定的 prompt，独立可滚动的 transcript，Markdown 输出，可折叠的 thinking，以及长 session 的窗口化 | | 工具 | 可展开的工具卡片、计时、易读的错误、编辑/写入 diff，以及针对任意 Pi 工具的通用回退机制 | | 导航 | 可搜索的模型选择器、`/sessions` 和 `/resume`、请求映射、命令自动补全，以及按需加载的旧历史记录 | | 工作流 | 即时 steering 及可见的排队指导，可编辑的本地后续任务，prompt 焦点恢复，以及诊断包 | | 设置 | Pi 权威的模型、thinking 和 session 控制；进程本地的显示偏好；十种实时主题预设以及完整的颜色编辑 | | 可选视图 | 并行的 subagent 检查/控制、活跃/已完成的 Todo 面板，以及在其 Pi 包安装时可用的安全 MCP 服务器管理 | ## 界面预览

## 快速使用 ``` pitty # start in the current directory pitty -C /path/to/project # choose a project directory pitty -c # continue the newest Pi session pitty --session /path/to/file.jsonl pitty-resume -C /path/to/project # open the session picker immediately pitty --help ``` 在 PiTTy 内部： ``` /settings open PiTTy Settings /resume browse and switch current-project sessions /model show or change the current model /thinking show or change reasoning effort /commands list Pi extensions, templates, and skills /help show PiTTy commands and controls ``` 查看完整的[使用与控制指南](docs/USAGE.md)。 ## 控制操作 | 按键 | 操作 | | --- | --- | | `Enter` | 优先接受高亮的斜杠命令建议；否则立即提交或 steer | | `Shift+Enter` | 插入换行符 | | `Alt+Enter` | 将一个可编辑的本地后续任务加入队列 | | `Alt+Up` | 将最近的本地后续任务恢复到编辑器中 | | 在空的单行 prompt 上按 `Up` / `Down` | 浏览 session 本地的 prompt 历史记录 | | `Ctrl+C`（带有非空草稿时） | 清除草稿并将其保存到 prompt 历史记录中 | | 鼠标滚轮 / `PgUp` / `PgDn` | 滚动当前活跃的 transcript | | `Ctrl+Home` / `Ctrl+End` | 跳转到开头或最新消息 | | `Ctrl+P` | 打开可搜索的模型选择器；PiTTy 每次打开时都会向 Pi 请求当前列表 | | `Ctrl+X` | 打开设置：模型、thinking、session、主题、记忆和 MCP 控制 | | `Ctrl+T` / `Shift+Tab` | 切换 thinking 强度 | | `Ctrl+R` | 打开请求映射 | | `Ctrl+M` | 浏览、搜索和移除持久化记忆（需要 `pi-hermes-memory`；在无法将其与 Enter 明确区分的终端上，请改用设置 > 记忆或 `/memory`） | | `Ctrl+S` | 切换侧边栏 | | `Ctrl+O` | 展开或折叠工具和 thinking 的详细信息 | | `Ctrl+I` | 打开或关闭选定的 subagent 检查器 | | `F6` / `Shift+F6` | 选择下一个或上一个 subagent（活跃的优先分组，组内保持稳定） | | `Esc` | 关闭当前活跃的对话框/检查器，或中止当前的 Pi 轮次 | ## 设置、主题和 MCP 使用 `Ctrl+X` 或 `/settings` 打开设置。对模型、thinking 强度和 session 的更改使用 Pi 的权威 RPC 状态；如果操作失败，设置会保留之前的权威值并显示内联错误。设置中还提供了“记忆”入口，因此那些将 `Ctrl+M` 作为普通 Enter 按键发送的终端（例如 Konsole）仍然可以访问记忆浏览器。 主题选择和颜色编辑是仅适用于 PiTTy 的用户全局偏好设置。您可以从十种预设中选择一种，或者编辑每一个语义颜色 token；有效的 `#RRGGBB` 颜色会立即应用，而无效的中间输入则会保留在输入框中，不会更改当前的活动调色板。请参阅[主题来源、对比度指南和存储详情](docs/THEMES.md)。 MCP 服务器管理被特意限制在标准的项目级 `.mcp.json` 和全局 `~/.config/mcp/mcp.json` 作用域内。设置会显示受影响的路径和更改前后的预览，保留未知的配置内容，在执行命令或显示明文值之前发出警告，并在保存后重启相同的 Pi session。它绝不会通过 RPC 发送 adapter 的 `/mcp` 或 `/mcp setup` 自定义面板。 ## 可选集成 PiTTy 无需额外的 Pi 包即可工作。安装后，这些集成会添加专门的面板： | 包 | 添加内容 | | --- | --- | | `npm:pi-subagents` | 并行的子 agent 列表、实时 transcript 检查、暂停/停止，以及排队的 steering 可见性 | | `npm:@juicesharp/rpiv-todo` | 受限的活跃和已完成 Todo 面板 | | `npm:pi-mcp-adapter` | 供设置用于激活标准 MCP 配置更改的可选 adapter | ``` pi install npm:pi-subagents pi install npm:@juicesharp/rpiv-todo pi install npm:pi-mcp-adapter ``` 安装程序和升级会根据选定的插件偏好提供缺失的可选集成。缺少集成项不会影响通用聊天的正常使用。 ## 兼容性 PiTTy 的 RPC 层处理标准的 user、assistant、thinking、tool-call 和 tool-result 事件；任意工具；Pi 扩展命令；prompt 模板和技能；扩展对话框；通知；状态更新；终端标题更改；以及编辑器预填充。 渲染任意直接 TUI 组件的 Pi 扩展无法被精确重现，因为这些组件树不会通过 RPC 进行序列化。它们的命令和工具事件仍然可以通过 PiTTy 的通用回退机制正常工作，而更丰富的行为则需要可选的 adapter。 请参阅[开源准备与架构](docs/OPEN_SOURCE_READINESS.md)。 ## 更新和升级 PiTTy 会在启动时异步检查 GitHub Releases；设置 `PITTY_NO_UPDATE_CHECK=1` 可禁用此功能。 ``` pitty upgrade --check # inspect availability pitty upgrade # stage the newest stable release pitty upgrade --version 0.4.1 # choose an explicit version ``` 升级需要在 `SHA256SUMS` 中包含所选归档文件的 SHA-256 条目，在同级 `.pending` 目录中进行暂存替换，在下一次正常启动时激活，并在激活验证失败时回滚。 ## 卸载 已安装的可选 Pi 包将被保留。 ``` # Linux, macOS, WSL ~/.local/share/pitty/uninstall.sh ``` ``` # Windows PowerShell & "$env:LOCALAPPDATA\PiTTy\app\uninstall.ps1" ``` 自定义安装可以设置 `PITTY_INSTALL_DIR` 和 `PITTY_BIN_DIR`，或者向 `uninstall.ps1` 传递 `-InstallDir` 和 `-BinDir`。 ## 诊断和隐私 诊断信息在以下位置： ``` ~/.local/state/pitty/ ``` 正常的 RPC 日志会省略 prompt 文本、工具输出和源代码内容；它们会保留元数据、长度和短哈希值。但绝对路径和错误片段仍可能出现，因此在共享之前请先检查诊断包。 ``` npm run diagnostics ``` 请勿发布 Pi 凭据、session transcript、私有源代码或未经审查的 `--verbose-rpc-logs` 输出。安全报告指南请见 [SECURITY.md](SECURITY.md)。 ## 开发 ``` npm ci --ignore-scripts --no-audit --no-fund node node_modules/bun/install.js npm run typecheck npm run test:unit ``` 较大的公共行为更改应包含位于 `openspec/changes/` 下的 OpenSpec 更改。贡献者指南请见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 文档 - [使用与控制](docs/USAGE.md) - [主题](docs/THEMES.md) - [架构与兼容性](docs/OPEN_SOURCE_READINESS.md) - [文档索引](docs/README.md) - [更新日志](CHANGELOG.md) ## 平台状态 | 平台 | 状态 | | --- | --- | | Linux | 主要开发平台 | | macOS | 包含在 CI 中，并由 POSIX 安装程序支持 | | Windows | 包含在 CI 中并由 `install.ps1` 支持；终端行为仍有待于更广泛的实际测试 | | WSL | 通过 POSIX 安装程序和 Linux runtime 支持 | 带标签的发布版本由 GitHub Actions 打包为 `pitty-.tar.gz`、`pitty-.zip` 和 `SHA256SUMS`。 ## 许可证 MIT。请见 [LICENSE](LICENSE)。 PiTTy 与 Pi 或 OpenCode 维护者没有任何附属关系。

标签：AI编程助手, GNU通用公共许可证, MITM代理, Node.js, TUI, 前端, 终端界面, 自动化攻击