# @agegr/pi-web 中文文档 规范地址：https://npmcn.com/package/%40agegr/pi-web/ 版本：0\.15\.0 npm 元数据更新时间：2026-11-03T16:33:13.384Z 中文译文更新时间：2026-11-05T20:32:44.113Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40agegr/pi-web 原文对照：https://npmcn.com/package/%40agegr/pi-web/?lang=original 项目主页：https://github.com/agegr/pi-web#readme 源码仓库：https://github.com/agegr/pi-web ## 关键信息（来自 npm 元数据） - 包体积（解压后）：36.2 MB，773 个文件 - TypeScript 类型：未声明 - Node.js 要求：\>=22\.19\.0 - 运行依赖：20 个 - 首次发布：2026-03-24T06:11:40.879Z - 最新版本发布：2026-11-03T16:33:13.027Z - 近 30 天下载量：26176（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：110（近 12 个月 110 个） ## 中文简介 用于 pi 编码代理的 Web UI ## 安装 ```sh npm install @agegr/pi-web ``` 也可以使用：`pnpm add @agegr/pi-web`、`yarn add @agegr/pi-web`、`bun add @agegr/pi-web` ## README # Pi 网络 [中文文档](https://npmcn.com/package/%40agegr/pi-web/docs/README.zh-CN.md) | [日本語](https://npmcn.com/package/%40agegr/pi-web/docs/README.ja.md) | [Русский](https://npmcn.com/package/%40agegr/pi-web/docs/README.ru.md) 本地浏览器用户界面 [pi 编码代理](https://github.com/earendil-works/pi). Pi Web 使用与 pi 相同的本地配置和会话文件,因此您可以浏览并恢复对话,运行代理转会,配置模型和资源,并从浏览器检查项目文件. **[尝试交互式演示 ~](https://agegr.github.io/pi-web/)** 真实的 Pi Web UI 完全运行在您的浏览器中,有样本会话,文件和模型. 没有什么可以安装的;答复是预先写的,也没有叫模型. ![Pi Web displaying a pi session with structured Markdown, tool calls, and project navigation](https://raw.githubusercontent.com/agegr/pi-web/main/docs/screenshot2.png) ## 特征 - **会话工作空间**:浏览,恢复,重命名,导出,并删除按项目分组的对白,包含运行状态,上下文使用,成本,和压缩细节. - **两个分支方式**数字 : **新会话** 从更早的信件创建独立的会话文件; **从这里编辑** 在当前会话内创建一个分支. - **项目文件工具**:浏览并上传文件,检查Git diffs,以及预览源,Markdown,图像,音频,PDFs,以及自动刷新的DOCX文件. - **Git 工作树**:从侧边栏切换取出,同时将会话保存在组合在一起的同一寄存器上. - **基于网络的配置**:管理提供者登录和API密钥,模型,模型测试,插件包,以及技能而不离开Pi Web. - **英语、简化中文和传统中文UI**: Pi Web最初遵循浏览器语言,并在上行提供语言切换器. ## 快速启动 Pi Web需要节点.js 22.19.0或更新. 检查您的版本 `node --version`,然后运行 : ```bash npx @agegr/pi-web@latest ``` CLI在服务器准备好后打开了浏览器. 如果不打开 [页:1](http://127.0.0.1:30141/)。 Pi Web 只收听于 `127.0.0.1` 默认. 如果尚未配置模型提供者,请打开 **模型** 要签名或添加 API 密钥的面板. 安装 `pi-web` 全局命令 : ```bash npm install -g @agegr/pi-web@latest pi-web ``` 图标 : ```bash pi-web version # print the installed version pi-web status # list running servers pi-web stop [--port N] # stop a running server pi-web open [--port N] # open a running server in the browser pi-web update [--check] # update a global npm install ``` 要更新, 请运行 `pi-web stop`,则 `pi-web update` (或再次运行相同的安装命令). 要卸载, 运行 `npm uninstall -g @agegr/pi-web`。 。 。 . ## 配置 对于端口和主机名,命令行选项会覆盖相应的环境变量. 无论是 `--no-open` 或者说 `PI_WEB_NO_OPEN=1` 禁用自动浏览器打开。 运行 `pi-web --help` (或 `-h`在不启动服务器的情况下打印启动选项并退出。 未知选项有错误退出 . | 选项或环境变量 | 目的 | 默认 | | --- | --- | --- | | `--help`, (中文(简体) ), `-h` | 打印启动选项并退出 | —— 说 | | `--port `, (中文(简体) ), `-p `,或 `PORT` | 服务器端口 | `30141` | | `--hostname `, (中文(简体) ), `-H `,或 `PI_WEB_HOSTNAME` | 绑定主机名 | `127.0.0.1` | | `--no-open` 或者说 `PI_WEB_NO_OPEN=1` | 不要自动打开浏览器 | 浏览器打开 | | `PI_WEB_APP_NAME` | PWA 清单 `name` 财务报告和审定财务报表 `short_name`; 周围的白空间被修剪,空值使用默认值 | `Pi Web` | | `PI_WEB_SKIP_VERSION_CHECK=1` | 禁用 Pi 网络更新检查 | 未设置 | | `PI_WEB_ALLOWED_HOSTS` | 其它精确的代理或自定义主机名, 逗号分隔 | 未设置 | | `PI_WEB_PASSWORD` | 启用浏览器密码登录; API 客户端可能使用带有用户名的 Basic Auth `pi` | 认证已禁用 | | `PI_WEB_IDLE_TIMEOUT_MS` | 会话闲置超时, 以毫秒计, 最多 `2147483647`· ; `0` 禁用闲置关机; 无效或超出范围值使用默认值 | `600000` (10分钟) | | `PI_WEB_SHUTDOWN_DEADLINE_MS` | 需要多久的扩展处理 `session_shutdown` 在最后会话被处理之前,以毫秒计,最多不超过 `2147483647`· ; `0`,无效或超出范围值使用默认值 | `5000` (第5条) | | `PI_CODEMODE_MAX_WORKERS` | pi对一次运行的代码脚本的限制,由服务器中的每个会话和子代理共享; pi 自身的默认是 `2`,和 pi-web 集 `8` 当变量未设置或为空时。 每个脚本最多可使用 256 MB | `8` | 设定 `PI_WEB_APP_NAME` 在启动服务器之前( 例如, ), `PI_WEB_APP_NAME='Work Pi' pi-web`) (中文(简体) ). 更改后, 重新启动服务器以服务新运单; 不需要重建 。 已经安装的 PWA 名称的更新由浏览器管理,不能保证立即出现. 这不会改变页面标题或图标 . 例如: ```bash pi-web --help pi-web -p 8080 -H 0.0.0.0 --no-open ``` ### 远程访问 绑定在非回放地址上会暴露一个可以执行高优先动作的代理人. 在信任的局域网上,需要长的随机密码: ```bash PI_WEB_PASSWORD='a-long-random-password' pi-web --hostname 0.0.0.0 ``` 密码认证不加密连接 。 不要将 Pi Web 通过普通的 HTTP 暴露到互联网上; 通过信任的倒置代理或信任的 VPN 使用 HTTPS 。 如果一个反向代理发送一个外部主机名, 请添加该确切名称到 `PI_WEB_ALLOWED_HOSTS`。此允许列表不会更改地址 Pi Web 绑定. ### 夹克 每个版本发布一个图像到 `ghcr.io/agegr/pi-web`。见 [在多克运行 Pi Web](https://npmcn.com/package/%40agegr/pi-web/docs/docker.md) 对于它,作曲的例子和 哪些卷子要保存. ### HTTP 代理服务器 服务器侧模式和 API 请求遵守标准 `HTTP_PROXY`, (中文(简体) ), `HTTPS_PROXY`,以及 `NO_PROXY` 环境变量. 在 macOS 或 Linux 上: ```bash 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 上显示: ```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 ``` ## 页:1 - **代理数据**: Pi Web 读取 pi 数据 `~/.pi/agent` 默认情况下,包括会话文件 `sessions//_.jsonl`设置 `PI_CODING_AGENT_DIR` 要使用另一个 pi 代理目录. - **文件系统访问**: Pi Web 必须能够读取代理数据目录及其会话所记录的工作目录. 在共享已有会话时运行 Pi Web 与 pi 在同一文件系统环境中 . - **共享配置**:Models面板使用pi的模型,设置,和证书存储,因此两个界面都可以看到变化. 当您再次选择模型时, 开放式会话会应用其模型的保存编辑 . - **文件访问边界**:文件浏览器仅限于在Pi Web和项目或会话根已经知道的工作目录;它不是一个通用的文件系统浏览器. - **Git 工作树**: 见 [皮网的工作树](https://npmcn.com/package/%40agegr/pi-web/docs/worktrees.md) 对于切换器的能见度,工作树的创建,以及去除行为. ### 下游会话背景菜单 电子包装和其他下游集成可以提供会话排行 不补丁的上下文菜单 `SessionSidebar`。可取消的选项 `pi-web:session-row-contextmenu` 浏览器事件和调用 `preventDefault()` 整合处理时同步: ```js window.addEventListener("pi-web:session-row-contextmenu", (event) => { event.preventDefault(); const { id, path, cwd, name, clientX, clientY, refresh } = event.detail; void openSessionMenu({ id, path, cwd, name, clientX, clientY }).then((changed) => { if (changed) refresh(); }); }); ``` 细节对象包含 `id`, (中文(简体) ), `path`, (中文(简体) ), `cwd`选项 `name`,指针 坐标和a `refresh()` 调用更改会话的动作 列表中选择一个选项。 如果没有听众取消扩展事件, Pi Web 将打开其内置 会话菜单( pin, 重命名, 叉子, 标记已读或未读, 归档, 以新方式打开) 选项卡,删除)位于指针,而不是浏览器的本地上下文菜单. 这行的 `⋯` 按钮总是打开内置菜单,而不发送 活动。 尚未保存到磁盘的会话没有内置菜单, 所以本地菜单 仍然出现在他们身上。 这个钩子是浏览器侧面, 独立于 Pi 代理 扩展. ### 扩展会话活性 服务器侧 Pi 扩展, 带有可拆卸的工作可以防止自动闲置 通过版本的全球登记册进行分区拆解: ```js const liveness = globalThis[Symbol.for("@agegr/pi-web/session-liveness/v1")]; const release = liveness?.version === 1 ? liveness.register({ name: "my-extension", sessionId, sessionFile: sessionFile || undefined, isActive: () => detachedJobs.size > 0, }) : () => {}; ``` 每个活动扩展会话注册一次,并呼叫返回的同位素 `release` 函数在会话关闭、替换或重装时. `isActive` 必须是同步的,廉价的,范围为所提供准确的会话编号或 文档。 提供方错误通过保存该会话而安全失效 。 只有这个租约 影响自动闲置拆迁;明确关闭并停止倒置清理 仍然处于优先位置. ## 发展 ```bash npm install npm run dev ``` 开发服务器运行于 [页:1](http://127.0.0.1:30141/)。进行常见检查时使用: ```bash npm test node_modules/.bin/tsc --noEmit npm run lint ``` 不运行 `next build` 或者说 `npm run build` 在正常发育期间。 它写给 `.next/` 并且可以干扰开发服务器; 假期构建用于发布工作. 在开始一个功能之前, 读取 [捐款](https://npmcn.com/package/%40agegr/pi-web/CONTRIBUTING.md) 范围与拉动请求清单. 贡献者指南 : [国际化](https://npmcn.com/package/%40agegr/pi-web/docs/i18n.md) 财务报告和审定财务报表 [释放过程](https://npmcn.com/package/%40agegr/pi-web/docs/release.md)。 。 。 . ## 仓库布局 ```text app/ Next.js UI and API routes components/ React UI components hooks/ Client state and interaction hooks lib/ Session, agent, model, file, Git, and security logic public/ Static assets and PWA files bin/ npm CLI entrypoint and launch option parsing docs/ Focused user and contributor guides demo/ Static browser demo published to GitHub Pages (see demo/README.md) ``` 见 [一般事务人员(其他职等)](https://npmcn.com/package/%40agegr/pi-web/AGENTS.md) 用于架构注释和详细文件地图. ## 许可证 [麻省理工学院](https://npmcn.com/package/%40agegr/pi-web/LICENSE) ## 常见问题 ### @agegr/pi-web 是什么？ 用于 pi 编码代理的 Web UI ### 如何安装 @agegr/pi-web？ 在项目目录运行 npm install @agegr/pi-web，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 pi-web，可以用 npx pi-web 直接运行。 ### @agegr/pi-web 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/agegr\_\_pi-web 是否存在。 ### @agegr/pi-web 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @agegr/pi-web 可以商用吗？ @agegr/pi-web 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @agegr/pi-web 的下载量有多少？ 根据 npm 官方下载统计，@agegr/pi-web 在 2026/10/05 – 2026/11/03 这 30 天内被下载 26,176 次，日均约 873 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @agegr/pi-web 还在维护吗？ 最新版本 0\.15\.0 发布于 2026/11/04（2 天前）；至今共发布 110 个版本，其中过去 12 个月发布了 110 个；首次发布于 2026/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。