@lyhue1991/pi-web

v0.8.17

Published

5 days ago

Web UI for the pi coding agent

0High
0Medium
0Low

lyhue1991

Pi Web

English | 日本語 | Русский

pi 编程智能体的本地网页界面。它会读取本机的 pi 会话文件，在浏览器里提供会话管理、实时对话、模型配置、技能管理和项目文件预览。

中文微信群：请查看 GitHub Discussions 帖子。

快速开始

Pi Web 要求 Node.js 22.19.0 或更高版本。可通过 node --version 检查当前版本。

无需安装，直接运行：

npx @lyhue1991/pi-web@latest

或全局安装后使用：

# 首次安装或升级
npm install -g @lyhue1991/pi-web@latest
pi-web

卸载全局安装：

npm uninstall -g @agegr/pi-web

启动后打开 http://127.0.0.1:30141。命令行版本会在服务就绪后尝试自动打开浏览器。Pi Web 默认仅监听 127.0.0.1。

可选参数：

pi-web --port 8080              # 自定义端口
pi-web --hostname 0.0.0.0       # 在可信网络中开放访问
pi-web -p 8080 -H 0.0.0.0       # 组合使用
pi-web --no-open                # 不自动打开浏览器

PORT=8080 pi-web                # 也支持环境变量
PI_WEB_HOSTNAME=0.0.0.0 pi-web  # 显式开放网络访问
PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web  # 允许指定的代理或自定义主机名
PI_WEB_PASSWORD='足够长的随机密码' pi-web  # 启用 Basic Auth（用户名固定为 pi）
PI_WEB_NO_OPEN=1 pi-web         # 适用于后台服务或开机自启

设置 PI_WEB_PASSWORD 后，网页和所有 API 端点都会启用 HTTP Basic Auth，用户名固定为 pi。未设置或设置为空值时不启用认证。

Pi Web 可以调用高权限智能体。Basic Auth 不会加密传输中的密码，因此不要把明文 HTTP 暴露到互联网。远程访问时应使用可信反向代理提供 HTTPS，或通过可信 VPN 访问。 API 请求仅接受 loopback 名称、IP 字面量、当前监听主机名，以及 PI_WEB_ALLOWED_HOSTS 中以逗号分隔的精确主机名。可信反向代理使用不同的外部主机名时，请配置该变量。

HTTP 代理

Pi Web 的服务端模型请求和 API 请求会读取标准的 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 环境变量。

macOS 或 Linux：

HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
NO_PROXY=localhost,127.0.0.1 \
npx @lyhue1991/pi-web@latest

Windows PowerShell：

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"
npx @lyhue1991/pi-web@latest

功能介绍

把历史工作接回来：打开网页就能按项目找到以前的 pi 对话，不必在终端里翻文件或记住会话路径。
放心试不同方向：可以从某条历史消息重新开始，也可以复制出一条独立的新路线，探索方案时不怕弄乱原来的对话。
跨分支工作：在侧边栏切换 Git worktree，让新会话和 Explorer 跟随你选择的 checkout。
边聊边看项目文件：左侧浏览项目文件，右侧打开源码、文档、图片、音频和 PDF；文件变化会自动刷新，适合边让 agent 改边检查结果。
随时掌握会话状态：在顶部就能看到上下文占用、花费、压缩结果和系统提示，长会话不再像黑箱。
少离开当前界面：模型、登录/API key、模型测试和技能开关都能在网页里处理，配置 agent 时不用在多个工具之间来回切换。

注意事项

数据目录：默认读取 ~/.pi/agent/sessions 下的会话文件。可通过环境变量 PI_CODING_AGENT_DIR 指定其他 pi agent 目录。
会话文件：路径形如 ~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl。
运行环境：建议 Pi Web 与 pi 使用相同的操作系统或容器，确保会话中的工作目录可用。
模型配置：Models 面板读写 pi agent 目录下的 models.json，模型列表和默认模型由 pi 的配置解析得到。
文件访问：文件浏览和预览面向当前选择的项目目录，以及会话中已出现过的工作目录。
Git worktree：什么时候显示切换器、新建目录在哪里、删除会影响什么，见 Pi Web 里的 Worktree。
Fork 与会话内分支不同：Fork 会创建新的 .jsonl 文件；“Edit from here” 是同一会话文件里的分支。

开发

npm install
npm run dev

本地开发端口为 http://127.0.0.1:30141。

常用检查：

node_modules/.bin/tsc --noEmit
npm run lint

开发时不要运行 next build / npm run build，它会写入 .next/，容易影响正在运行的 dev server。发布流程再执行构建。

项目结构

app/
  api/
    agent/          # 创建/驱动 AgentSession，提供 SSE 事件流
    auth/           # OAuth 和 API key 管理
    cwd/browse/     # 服务端目录浏览
    cwd/validate/   # 自定义工作目录校验
    default-cwd/    # 获取 pi 默认工作目录
    files/          # 文件列表、读取、预览、watch
    home/           # 当前用户 home 目录
    models/         # 可用模型、默认模型、thinking levels
    models-config/  # 读写 models.json、测试模型
    sessions/       # 会话读取、重命名、删除、上下文、HTML 导出
    skills/         # skills 列表、搜索、安装、启停
components/
  AppShell.tsx        # 主布局、URL 状态、顶部面板、文件标签
  SessionSidebar.tsx  # 项目选择、会话树、Explorer
  DirectoryPicker.tsx # 支持浏览和路径输入的工作目录选择器
  ChatWindow.tsx      # 消息区、SSE、拖拽图片、minimap
  ChatInput.tsx       # 输入栏、模型/工具/thinking/compact/slash controls
  MessageView.tsx     # 消息、thinking、tool call/result 渲染
  ModelsConfig.tsx    # 模型和认证配置面板
  SkillsConfig.tsx    # 技能管理面板
  FileExplorer.tsx    # 文件树
  FileViewer.tsx      # 源码、diff、图片、音频、PDF、DOCX 预览
lib/
  directory-browser.ts # 目录规范化和安全枚举工具
  http-dispatcher.ts  # 服务端 fetch 的 HTTP(S) 代理配置
  rpc-manager.ts      # AgentSessionWrapper 生命周期和全局 registry
  session-reader.ts   # 解析 .jsonl 会话文件和分支上下文
  normalize.ts        # 规范化 toolCall 字段名
  file-access.ts      # 文件读取安全边界
  file-paths.ts       # 文件路径编码/相对路径工具
  markdown.ts         # Markdown/Mermaid/KaTeX 插件配置
  pi-types.ts         # pi 相关类型
hooks/
  useAgentSession.ts  # 会话加载、发送命令、SSE 状态机
  useAudio.ts         # 完成提示音
  useDragDrop.ts      # 图片拖拽
  useTheme.ts         # 主题切换
bin/
  pi-web.js           # npm CLI 入口
instrumentation.ts    # 初始化服务端 HTTP dispatcher

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme