★ FEATURED ARTICLE 从零到一跑通 Pi WebPi 编程智能体 Web 界面实战指南【免费下载链接】pi-webWeb UI for the pi coding agent项目地址: https://gitcode.com/GitHub_Trending/pi/pi-webPi Web 是 pi 编程智能体的官方本地浏览器界面Web UI与 pi 共用本机配置和会话文件让你在浏览器里查找、继续历史对话管理模型与 Provider浏览项目文件。本文覆盖安装启动、启动参数与环境变量配置速查以及密码认证、主机白名单、文件访问边界背后的安全加固原理读完即可直接部署。给 pi 智能体一个浏览器Pi Web 的定位pi 智能体原本是终端工具会话以 JSONL 形式落在~/.pi/agent/sessions/编码后的工作目录/时间戳_uuid.jsonl配置散落在~/.pi/agent/models.json等文件里。Pi Web 不另起炉灶它是一层架在同一份数据之上的薄 Next.js 壳浏览器通过只读 API 解析会话文件发消息时在 Node 进程内创建AgentSession再用 SSE 收流式输出。这个定位带来两点直接价值零割裂终端里聊到一半的对话浏览器里接着聊模型配置改一处两个界面都看得见。数据始终在磁盘上浏览会话不创建运行时纯解析.jsonlPi Web 不是会反锁你数据的第三套存储。3 分钟跑起来Pi Web 安装与首次启动环境要求Node.js 22.19.0 或更高package.json 的engines字段有约束先node --version确认。npx 一次性运行npx agegr/pi-weblatest终端出现Ready后会自动打开浏览器没自动打开就手动访问http://127.0.0.1:30141。默认只监听回环地址127.0.0.1不会暴露到局域网。尚未配置 Provider 时打开Models面板登录或添加 API Key 即可。全局安装、更新与卸载npm install -g agegr/pi-weblatest pi-web全局安装后多出一组子命令pi-web version打印版本、pi-web status列出运行中的服务、pi-web stop [--port N]停服、pi-web update更新先stop再执行。卸载npm uninstall -g agegr/pi-web。从源码启动开发服务器git clone https://gitcode.com/GitHub_Trending/pi/pi-web cd pi-web npm install npm run dev开发服务器同样运行在 http://127.0.0.1:30141。日常检查三连npm test单元测试、node_modules/.bin/tsc --noEmit类型检查、npm run lintESLint。⚠️ 开发期间不要运行next build或npm run build它们写入.next/会直接干扰开发服务器构建只属于发布流程。能力地图浏览器里都能干什么会话工作区按项目查找、继续、重命名、导出、删除对话运行状态、上下文占用、花费、压缩信息实时可见 → lib/session-reader.ts两种分支新会话产生独立.jsonl文件从此处编辑在同一文件内分支多个条目共享parentId语义在 hooks/useAgentSession.ts 中明确区分切勿混淆项目文件工具浏览与上传文件、查看 Git Diff预览源码、Markdown、图片、音频、PDF、DOCX文件变化自动刷新 → app/api/files/Git worktree侧边栏切换 checkout同一仓库不同 worktree 的会话归组展示 → lib/worktree.ts详见 docs/worktrees.zh-CN.md网页配置Provider 登录与 API Key、模型管理、模型测试、插件包、技能无需离开页面 → app/api/models-config/三语界面英文、简体中文、繁体中文首次打开跟随浏览器语言顶部栏可切换 → docs/i18n.md启动配置速查表参数优先级与环境变量规则先说清命令行参数优先于同名环境变量端口必须是 065535 的整数否则启动直接报错传入未知参数会报错并以退出码 1 结束。参数 / 环境变量作用默认值备注--help/-h打印启动选项并退出—退出码 0不启动服务--port 端口/-p或PORT服务端口30141必须为 065535 整数--hostname 主机/-H或PI_WEB_HOSTNAME监听主机名127.0.0.1非回环会触发安全警告--no-open或PI_WEB_NO_OPEN1不自动打开浏览器自动打开环境变量接受1/true/yes/onPI_WEB_APP_NAMEPWA manifest 的名称Pi Web启动前设置重启生效PI_WEB_PASSWORD启用浏览器密码登录不启用API 客户端可用用户名pi的 Basic AuthPI_WEB_ALLOWED_HOSTS额外允许的主机名未设置逗号分隔精确匹配PI_WEB_SKIP_VERSION_CHECK关闭更新检查开启设为1PI_WEB_IDLE_TIMEOUT_MS会话空闲超时毫秒6000000表示禁用PI_WEB_SHUTDOWN_DEADLINE_MS关闭时等待扩展毫秒5000HTTP_PROXY/HTTPS_PROXY/NO_PROXY模型与 API 请求走代理系统默认仅服务端请求读取场景示例# 局域网访问8080 端口、监听 0.0.0.0、不自动开浏览器 pi-web -p 8080 -H 0.0.0.0 --no-open # 服务端模型/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$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-weblatest安全加固密码认证、主机白名单与文件访问边界⚠️ 监听非回环地址等于把一个可执行高权限操作的智能体暴露出去。切勿通过明文 HTTP 把 Pi Web 挂到互联网上——密码认证只验证身份不加密连接。认证链路由 proxy.ts 中间件统一接管matcher 为/、/login、/api/:path*未设PI_WEB_PASSWORD时/login直接重定向回/其余请求放行Host 检查仍会执行启用密码后未认证的浏览器页面重定向到/login未认证的 API 请求返回401并携带WWW-Authenticate: Basic realmPi Web头API 客户端按 Basic Auth 接入即可登录成功后签发pi_web_sessionCookieHMAC-SHA256 签名有效期 30 天后续请求凭它通过校验。密码校验细节在 lib/web-auth.tsBasic Auth 用户名固定为pi密码经 SHA-256 摘要后用timingSafeEqual比较消除时序侧信道。lib/auth-throttle.ts 的限流器让登录表单与 API 共享失败计数连续失败返回429封禁期内即使密码正确也会被拒——否则答对即解封本身会泄漏信息。主机白名单与 CSRF 在 lib/request-security.tsAPI 请求的 Host 只信任localhost含*.localhost、IP 字面量或操作者显式配置的主机名。IP 字面量天然抗 DNS rebinding——浏览器会在 Host 头中保留字面地址。Origin/Fetch Metadata 检查直接拒绝cross-site的浏览器跨站请求并给反向代理改写 Origin 但仍是同源的场景留了兼容通路。文件访问边界是独立的允许列表lib/file-access.ts 收集所有会话的 cwd、解析出的项目根目录以及显式添加的根带 5 秒 TTL 缓存路径判定统一收敛到 lib/path-security.ts 的isPathWithinRoots()。文件浏览器因此不是通用文件浏览器没在 Pi Web 里选过的工作目录就是读不到。可信局域网部署的推荐命令PI_WEB_PASSWORD足够长的随机密码 pi-web --hostname 0.0.0.0入口脚本 bin/pi-web.js 检测到非回环监听且未启用密码时会打印 without authentication 警告即使已设密码也会提示 HTTP 不保护传输中的密码。走反向代理时务必让它提供 HTTPS并把外部主机名精确加入PI_WEB_ALLOWED_HOSTS——白名单不改监听地址只做匹配。源码导读目录结构与关键模块app/ Next.js 界面与 API 路由 components/ React 界面组件 hooks/ 客户端状态与交互 lib/ 会话、智能体、模型、文件、Git、安全逻辑 public/ 静态资源与 PWA 文件 bin/ npm CLI 入口及启动参数解析 docs/ 面向用户与贡献者的专题文档 demo/ 静态演示站关键模块bin/pi-web.js — Node 版本检查、参数解析、拉起next start子进程、输出Ready后打开浏览器Windows 用cmd /c start、macOS 用open、Linux 用xdg-open启动前还会轮换包内预置的 preview 密钥bin/pi-web-options.js — 参数与环境变量解析、端口校验、--help文本lib/rpc-manager.ts —startRpcSession()在进程内创建AgentSession维护注册表与生命周期lib/session-reader.ts — 直读.jsonl会话文件纯只读浏览不产生运行时lib/agent-client.ts — 面向/api/agent命令的类型化 fetch 封装proxy.ts lib/web-auth.ts lib/request-security.ts — 认证入口、会话令牌、Host 白名单、跨站检查lib/file-access.ts lib/path-security.ts —/api/files的允许根安全边界lib/worktree.ts — 把 linked worktree 解析回主仓库根供侧边栏归组一次发消息的流转POST /api/agent/[id]→startRpcSession()创建AgentSession→session.prompt()浏览器从GET /api/agent/[id]/events的 SSE 流实时消费事件。而浏览会话只走GET /api/sessions列目录与GET /api/sessions/[id]经 SDK 的SessionManager工具解析.jsonl全程不碰运行时。避坑清单部署时最容易踩的六个坑坑跑过next build后npm run dev报错→ 构建产物污染了.next/开发图 → 开发期不构建已污染就清掉.next再重启。坑两个next dev进程互相打架、端口占用→ 它们争用同一个.next/dev/lock→ 先lsof -nP -iTCP:30141 -sTCP:LISTEN确认已有健康进程并复用切勿换个端口开第二个。坑浏览器里看不到历史会话→ Pi Web 跑在容器或远程主机上读的是另一台机器的本地路径 → 让 Pi Web 与 pi 运行在同一文件系统环境换 agent 目录用PI_CODING_AGENT_DIR。坑挂上反向代理后 API 返回 403 Untrusted request→ 代理传的外部主机名不在信任列表 → 把它精确加入PI_WEB_ALLOWED_HOSTS逗号分隔不支持通配符。坑API 客户端反复收到 429→ 认证限流器累计了连续失败封禁期内正确密码也拒绝 → 用用户名pi的 Basic Auth 正常重试即可不要做循环爆破。坑文件浏览器读不到某个目录→ 这是 allow-list 设计的边界不是权限 bug → 在 Pi Web 中把该目录选为工作目录或让它成为已识别的项目根/会话根。许可证Pi Web 采用 MIT 许可证文本见 LICENSE。完整的架构说明与文件地图在 AGENTS.md要参与开发先读 docs/CONTRIBUTING.zh-CN.md 确认改动范围贡献者文档还有 docs/i18n.md国际化与 docs/release.md发布流程。【免费下载链接】pi-webWeb UI for the pi coding agent项目地址: https://gitcode.com/GitHub_Trending/pi/pi-web创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
