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_NO_OPEN=1 pi-web         # 适用于后台服务或开机自启

Pi Web 没有应用层身份验证，并且可以调用高权限智能体。请勿将其暴露到互联网；仅在可信网络中使用非 loopback 监听地址。 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 @agegr/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 @agegr/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。
模型配置：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

6.4 KiB Raw Permalink Blame History Unescape Escape

Pi Web

快速开始

HTTP 代理

功能介绍

注意事项

开发

项目结构

6.4 KiB

Raw Permalink Blame History