Pi Web 完整指南pi 编程智能体的浏览器界面从安装配置到远程加固一篇讲透【免费下载链接】pi-webWeb UI for the pi coding agent项目地址: https://gitcode.com/GitHub_Trending/pi/pi-webPi Web 是 pi 编程智能体的官方浏览器界面也是一个 Next.js 应用。它和终端版 pi 共用同一套本机数据会话 JSONL 文件、模型配置、Provider 凭据都落在~/.pi/agent下你在终端里跑出来的对话直接在 Pi Web 里就能找到并接着聊反过来你在网页上改的模型设置终端里的 pi 立刻可见。本地部署它不需要任何账号一条npx命令就能跑起来。哪种情况你会需要它不用背功能清单看三个具体场景找回三天前的对话会话按项目分组列在侧边栏点开就是当时的完整上下文继续发消息即可不用翻终端历史。换模型不想敲命令网页里登录 Provider 或粘贴 API Key、跑一次模型测试终端里的 pi 同步生效因为两边读的是同一个~/.pi/agent/models.json。不想切窗口看代码文件浏览器直接预览源码、Markdown、图片、音频、PDF 和 DOCX还能看 Git Diff文件一变视图自动刷新。五分钟启动 Pi WebPi Web 怎么启动最短路径就三步。先确认 Node 版本package.json 的engines要求22.19.0 或更高node --version # 低于 v22.19.0 就先升级 npx agegr/pi-weblatest服务就绪后它会尝试拉起系统浏览器没弹出来就手动访问http://127.0.0.1:30141。Pi Web 默认只监听127.0.0.1回环地址局域网里其他机器访问不到。第一次使用打开 Models 面板登录或添加 API Key 就能开聊。另外两条路各一条命令npm install -g agegr/pi-weblatest pi-web # 全局安装卸载npm uninstall -g agegr/pi-web npm install npm run dev # 源码开发同样跑在 http://127.0.0.1:30141继续与分支历史会话新会话和从此处编辑不是一回事Pi Web 的会话文件是 JSONL路径为~/.pi/agent/sessions/编码后的工作目录/时间戳_uuid.jsonl。浏览会话走GET /api/sessions等只读接口直接读文件、不创建任何运行时当你发送消息POST /api/agent/[id]才会在进程内拉起一个AgentSession随后通过GET /api/agent/[id]/events这个 SSE 接口收到流式事件。界面里有两个容易混的分支操作效果完全不同新会话从较早的某条消息 fork 出一条新的.jsonl文件原会话不受影响从此处编辑在当前文件内调用navigate_tree建分支同一文件里多条新条目共享同一个parentId。用错只会浪费一个文件不会丢数据但别养成混用习惯。实现区分在 hooks/useAgentSession.ts会话的只读解析在 lib/session-reader.ts。在网页里管理模型、API Key 和插件模型面板背后就是 pi 的模型、设置与凭据存储模型列表由~/.pi/agent/models.json与 Provider 认证状态合并而来/api/models-config路由直接读写这个文件。也就是说网页改一次终端立刻看到同样的东西不存在两套配置。除模型外插件包和技能也在同一个设置体系里管理会话界面的英文、简中、繁中三语切换见 docs/i18n.md——首次打开跟随浏览器语言之后可从顶部栏手动切换。文件浏览与 Git worktree 切换文件面板不是通用文件浏览器它只能进你在 Pi Web 里选过的工作目录以及已识别的项目或会话根目录白名单细节后文安全部分再展开。文件变化后视图自动刷新源码、Markdown、图片、音频、PDF、DOCX 都有预览Git Diff 也能直接看。worktree 适合同一仓库、多个分支并行开发的场景从侧边栏切换 checkout同一仓库不同 worktree 的会话会被归到一组展示。切换器何时出现、创建与删除的影响docs/worktrees.zh-CN.md 写得很细把 linked worktree 解析回主仓库根的逻辑在 lib/worktree.ts操作走/api/worktrees规则与文件接口一致。参数与环境变量一张表配好 Pi Web命令行参数优先于同名环境变量解析逻辑集中在 bin/pi-web-options.js。端口必须是 0~65535 的整数填错直接启动失败布尔型环境变量额外接受true、yes、on。参数 / 环境变量作用默认值-h/--help打印启动选项后以退出码 0 结束不启动服务—-p/--port或PORTPi Web 端口30141-H/--hostname或PI_WEB_HOSTNAME监听主机名127.0.0.1--no-open或PI_WEB_NO_OPEN1不自动打开浏览器自动打开PI_WEB_PASSWORD启用密码登录API 客户端可用用户名pi的 Basic Auth不启用PI_WEB_ALLOWED_HOSTS额外允许的代理/自定义主机名逗号分隔精确匹配未设置PI_WEB_SKIP_VERSION_CHECK设为1关闭更新检查开启PI_WEB_IDLE_TIMEOUT_MS会话空闲超时毫秒0禁用60000010 分钟组合示例——改端口并关掉自动开浏览器pi-web -p 8080 --no-open走 HTTP 代理时服务端的模型和 API 请求读标准的三个代理变量HTTP_PROXYhttp://127.0.0.1:7890 \ HTTPS_PROXYhttp://127.0.0.1:7890 \ NO_PROXYlocalhost,127.0.0.1 \ npx agegr/pi-weblatest Pi Web 远程访问暴露出去之前必须做的事监听非回环地址等于把一个能执行高权限操作的智能体交出去。bin/pi-web.js启动时会检查这一点非回环且没设密码直接打 listening without authentication 警告设了密码也会提醒你 HTTP 是明文——明文 HTTP 会把密码原样传出去设密码不等于加密连接。Pi Web 远程访问的必做清单密码用足够长的随机串例如PI_WEB_PASSWORD足够长的随机密码 pi-web --hostname 0.0.0.0用可信反向代理提供HTTPS或挂在可信 VPN里别把明文 HTTP 暴露到互联网反向代理如果改写Origin或传递外部主机名把这个主机名逐字加进PI_WEB_ALLOWED_HOSTS。白名单只信任localhost及*.localhost、IP 字面量和显式配置的名字IP 字面量因为浏览器在 Host 头里保留字面地址天然防 DNS rebinding它只管请求放行不会改变 Pi Web 自己的监听地址。密码认证本身不复杂中间件 proxy.ts 接管/、/login和/api/*未登录的浏览器请求被重定向到/login未登录的 API 请求收到401加WWW-Authenticate: Basic realmPi Weblib/web-auth.ts 里 Basic Auth 用户名固定为pi比较走 SHA-256 摘要后的timingSafeEqual防时序侧信道登录成功签发 HMAC-SHA256 签名的pi_web_sessionCookie默认 30 天lib/request-security.ts 同时拒绝跨站浏览器 API 请求来防 CSRF并兼容代理改写Origin的同源场景。文件访问的边界是显式白名单lib/file-access.ts 把会话 cwd、解析出的项目根、~/pi-cwd-*目录和显式添加的根收集为可访问根所有路径判断统一收敛到 lib/path-security.ts 的isPathWithinRoots()——白名单之外的路径一个都读不到。给想深入的人代码在仓库哪里app/ Next.js 页面和 API 路由 components/ React 界面组件 hooks/ 客户端状态与交互 lib/ 会话、智能体、模型、文件、Git 与安全逻辑 bin/ CLI 入口与参数解析 docs/ 专题文档三个最值得先看的关键文件CLI 入口 bin/pi-web.jsNode 版本检查、拉起next start子进程、按系统调用cmd /c start/open/xdg-open开浏览器会话只读解析 lib/session-reader.ts浏览不建运行时路径安全边界 lib/path-security.ts。消息发送侧则是 lib/rpc-manager.ts 的startRpcSession()在进程内创建AgentSession。更完整的架构与文件地图在 AGENTS.md。⚠️ 动手前先看的五个高频坑浏览器没自动打开不奇怪尤其无桌面环境时。手动访问http://127.0.0.1:30141即可或用--no-open明确关掉这个行为。两个next dev抢锁开发服务器卡住时先lsof -nP -iTCP:30141 -sTCP:LISTEN找一个健康的已有进程复用。换端口再开一个next dev没用两个进程争的是同一个.next/dev/lock。开发期别跑npm run buildnext build会写入.next/并打断next dev构建只属于发布流程。容器/远程主机里读不到会话Pi Web 必须和 pi 在同一个文件系统里运行否则它只能看到空目录——容器里读到的是容器内的~/.pi不是宿主机的。AGENTS.md 里多出一段BEGIN:nextjs-agent-rules那是next dev自动追加的工具输出检查git status别把它带进无关提交。结尾Pi Web 采用 MIT 许可证。想从源码玩起仓库在https://gitcode.com/GitHub_Trending/pi/pi-webgit clone之后npm install npm run dev就能进开发模式。浏览器界面只是皮共享的那份~/.pi数据才是它和终端版 pi 真正长在一起的原因。【免费下载链接】pi-webWeb UI for the pi coding agent项目地址: https://gitcode.com/GitHub_Trending/pi/pi-web创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考