@hhyy668/pi-desktop-ui

v1.3.4

Published

2 days ago

A native desktop GUI for pi — full chat window with real-time streaming, markdown rendering, and workspace management

0High
0Medium
0Low

hhyy668

pi-package

Pi Desktop UI

pi 的原生桌面 GUI。它提供一个完整的聊天窗口，可以实时镜像终端会话，并支持流式输出、Markdown 渲染和工作区管理。

Pi Desktop - Chat View

Pi Desktop - Code Diffs & Tools

功能特性

完整的双向聊天：可以从桌面窗口或终端发送消息，两边会保持同步
实时流式输出：助手回复按 token 流式显示，并带有 thinking 状态提示
Markdown 渲染：支持带语法高亮的代码块
Mermaid 图表：流程图、序列图、状态机等会渲染为 SVG；默认中性主题，深色模式通过 CSS 适配
LaTeX 数学公式：通过 KaTeX 渲染行内 $...$ 和块级 $$...$$ 公式
取消流式生成：生成中发送按钮会变为停止按钮，也支持 Escape / Ctrl+C 快捷键
工具执行展示：可以查看工具调用，例如 bash、read、edit、write；edit 会以内联 diff 展示
侧边栏导航：
- Threads：浏览并切换会话线程
- Skills & Extensions：查看已安装的技能和已加载的扩展
- Settings：查看模型信息、token 统计和费用跟踪
- Explorer：浏览项目文件
- Workspaces：浏览所有 pi 工作区及其会话；系统临时目录中的工作区会保留在默认折叠的“临时会话”分组中
Slash 命令面板：可以从窗口访问所有 pi 命令
文件附件：支持拖拽文件，或将文件附加到消息中
终端自定义 footer 和 widget：显示项目、分支、模型和 token 统计

安装

从 Git 安装（推荐）

pi install git:gitee.com/hhyy668/pi-desktop-ui

手动安装

将仓库克隆到 pi 扩展目录：

git clone https://gitee.com/hhyy668/pi-desktop-ui ~/.pi/agent/extensions/pi-desktop-ui
cd ~/.pi/agent/extensions/pi-desktop-ui
npm install

然后重新加载 pi：

/reload

使用方式

启动时自动打开

pi --desktop

这会启动 pi 并自动打开桌面窗口。你也可以使用随项目提供的 pi-desktop.cmd（Windows）或 pi-desktop.sh（macOS/Linux）脚本创建快捷方式。

在会话中手动打开

| 方式 | 操作 | | ------------ | ---------- | | Ctrl+Alt+N | 键盘快捷键 | | /desktop | Slash 命令 | | /nav | Slash 命令别名 |

窗口会和终端并排打开。你可以在任意一边输入，消息、工具调用和回复都会实时同步。

模型提供方配置

桌面端可以管理任意 OpenAI 或 Anthropic 兼容代理。支持以下 API 类型：

OpenAI Chat Completions (openai-completions)
OpenAI Responses (openai-responses)
Anthropic Messages (anthropic-messages)

可以通过以下入口打开同一个配置页面：

Settings 中的 Manage model providers
模型选择器顶部的设置项
在桌面输入框执行 /setup-model
模型切换因缺少认证失败时的配置操作

Provider 和模型定义保存在 ~/.pi/agent/models.json，API Key 保存在 ~/.pi/agent/auth.json。已保存的密钥不会返回 WebView；重新打开页面时密钥输入框始终为空，留空保存会保留原密钥，只有显式选择清除才会删除。

敏感自定义 Header 的值同样保存在 auth.json 的 Provider env 中，models.json 只保存环境变量引用。普通 Header 直接保存在 models.json。

Fetch models 会从 Provider 的 <baseUrl>/models 获取模型 ID。无法提供兼容模型列表接口时，可使用 Add model 手工添加；新模型默认使用 128K 上下文、16384 最大输出 Token、文本输入、关闭推理和零成本参数，保存前均可编辑。

OAuth Provider 不在此页面编辑凭据，请使用 /login。

左侧工作区列表会把操作系统临时目录中的会话集中到“临时会话”分组。展开或收起该分组只影响界面显示，不会删除 ~/.pi/agent/sessions/ 中的历史记录。

Desktop UI Language

The desktop UI supports English and Simplified Chinese.

Use the language button immediately to the left of the theme button to switch languages. The current window updates immediately after the setting is saved, and the selected language persists when /desktop is reopened.

Alternatively, configure the language directly in ~/.pi/agent/settings.json:

{
  "language": "zh-CN"
}

This forbiddenUiStrings list is a targeted regression guard for high-value UI strings. It is not a full text extractor; new user-visible strings should still be added to EN_US, ZH_CN, and REQUIRED_I18N_KEYS during implementation review.

Supported values:

en-US
zh-CN

Invalid or missing values fall back to en-US. Reopen /desktop or restart pi --desktop after editing the file manually.

安全性

该扩展实现了多层防护：

XSS 防护：所有 Markdown 输出都会通过 DOMPurify 清洗，并使用严格的标签/属性白名单
内容安全策略（CSP）：default-src 'none'，connect-src 'none' 完全禁止外部网络请求，object-src、base-uri、form-action 均置为 none，仅允许自身来源的内联脚本与样式
本地内联资源：所有第三方前端资源（Tailwind、marked、DOMPurify、KaTeX、highlight.js 样式等）都通过 npm run vendor 从 node_modules 复制到 web/vendor/，并在构建 WebView HTML 时内联注入，运行时不加载任何 CDN 或远程脚本
路径穿越防护：文件浏览器、线程查看器和工作区处理逻辑会校验路径必须位于允许目录内，例如 cwd 和 ~/.pi/agent/sessions/
凭据隔离：API Key 与敏感 Header 仅保存在 ~/.pi/agent/auth.json，不会回传 WebView；Provider 发现请求会做 SSRF 校验
附件限制：上传文件最大 25 MB，并会清洗文件名
输入校验：限制消息长度，严格校验持久化配置结构，并拒绝所有用户提供路径中的穿越尝试

依赖

前端第三方资源全部随包 vendor 到 web/vendor/ 并在运行时内联，不依赖 CDN。

glimpseui：从 Node.js 打开原生 webview 窗口
Tailwind CSS（浏览器版）：界面样式
marked：Markdown 解析
mermaid：图表渲染
KaTeX：LaTeX 数学公式渲染
DOMPurify：HTML 清洗
highlight.js：语法高亮
ws：WebSocket 支持

要求

pi coding agent（针对 v0.80.x 开发与测试）
Node.js（运行 npm install 以拉取 glimpseui 及其余依赖）

工作原理

该扩展接入 pi 的事件系统，用于捕获完整的 agent 生命周期：

session_start：初始化自定义 footer 和上下文 widget
message_start / message_update / message_end：将助手回复流式发送到窗口
tool_execution_start / tool_execution_end：展示工具调用、参数和结果
agent_start / agent_end：显示加载状态，并更新 token 统计

用户在桌面窗口输入的消息会通过 pi.sendUserMessage() 发送给 pi，回复再通过同一组事件钩子流式返回窗口。

包结构

pi-desktop-ui/
|-- assets/                      # 截图
|-- web/
|   |-- index.html               # 桌面窗口 HTML 外壳（含内联标记占位符）
|   |-- app.js                   # 前端应用：侧边栏、聊天、文件浏览器、主题等
|   |-- language-toggle-utils.js # 语言切换工具
|   |-- model-provider-state.js  # 模型提供方配置界面状态
|   |-- request-id-utils.js      # 请求 ID 关联工具
|   |-- temporary-workspace-utils.js  # 临时工作区分组逻辑
|   `-- vendor/                  # 本地内联的第三方资源（由 npm run vendor 生成）
|-- index.ts                     # 扩展入口：事件、命令、窗口管理、HTML 构建
|-- model-provider-utils.js      # 模型提供方持久化与校验
|-- workspace-utils.js           # 工作区枚举工具
|-- i18n-utils.js                # 国际化辅助
|-- compact-utils.js             # footer / widget 压缩显示工具
|-- desktop-command-utils.js     # slash 命令解析工具
|-- skill-package-utils.js       # 技能 / 扩展展示工具
|-- scripts/                     # vendor 脚本与 verify/test 校验脚本
|-- docs/                        # 设计计划与文档
|-- package.json                 # Pi 包清单和依赖
|-- pi-desktop.cmd / pi-desktop.sh          # 启动快捷脚本（Windows / macOS-Linux）
|-- pi-desktop-dev.cmd / pi-desktop-dev.sh  # 开发模式启动脚本
`-- README.md

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme