@wjbfks/pi-web-space

v0.1.9

Published

a month ago

Pi Web Space — a browser workspace for the pi coding agent

0High
0Medium
0Low

wjbfks

Pi Web Space

基于 agegr/pi-web 的工作空间增强分支，保留上游来源和 MIT 许可证。

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

pi 编程智能体的本地浏览器界面。Pi Web Space 与 pi 共用本机配置和会话文件，可在浏览器中查找和继续对话、运行智能体、配置模型与资源，并查看项目文件。

本分支新增

工作区与临时会话选择、可配置的临时目录、支持逐项复制的工作区及会话信息卡片。
对话、轨迹、上下文视图；可拖动调整的聊天宽度、文件预览和底部终端。
会话轮数、轨迹步数、Token 用量、缓存命中率、成本及平均输出速度估算。tok/s 的活跃时长包含工具执行和等待时间，不代表模型纯解码速度。
工作区命名、归档及外观偏好保存在当前浏览器，不跨设备同步。
设置 → 关于提供本仓库链接；建立独立发布流程前隐藏上游更新提示。

功能

会话工作区：按项目查找、继续、重命名、导出和删除对话，并查看运行状态、上下文占用、花费和压缩信息。
两种分支方式：新会话会从较早的消息创建独立会话文件；从此处编辑会在当前会话内创建分支。
项目文件工具：浏览和上传文件、查看 Git Diff，并预览源码、Markdown、图片、音频、PDF 和 DOCX；文件变化后会自动刷新。
Git worktree：从侧边栏切换 checkout，同时把同一仓库不同 worktree 的会话归在一起。
网页配置：无需离开 Pi Web Space，即可管理 Provider 登录和 API Key、模型、模型测试、插件包及技能。
英文、简体中文和繁体中文界面：Pi Web Space 首次打开时跟随浏览器语言，也可从顶部栏切换语言。

快速开始

npm 包名为 @wjbfks/pi-web-space（首次发布准备中）。发布后可使用：

npm install -g @wjbfks/pi-web-space
pws
# Equivalent alias / 等效别名
pi-web-space

需要 Node.js 22.19.0 或更高版本。从本仓库源码运行：

git clone https://github.com/WJBFks/pi-web-space.git
cd pi-web-space
npm ci
npm run dev

打开 http://127.0.0.1:40141。

在设置 → 模型中配置 Provider。上游 npm 包 @agegr/pi-web 不包含本分支改动；现有环境变量和存储键保留，以兼容已有配置。

配置

主命令为 pws，pi-web-space 是参数完全相同的别名。在本仓库执行 npm link 可注册这两个命令。CLI 启动服务需要生产构建产物；开发时继续使用 npm run dev。

以下启动参数适用于已构建源码的启动器（pws）。开发模式端口为 40141；npm run dev:lan 用于局域网访问。

端口和主机名以命令行参数为准，优先于对应的环境变量。--no-open 与 PI_WEB_NO_OPEN=1 中任意一个都会关闭自动打开浏览器。运行 pws --help（或 -h）可打印启动选项并以退出码 0 结束，不会启动服务；未知参数会报错并以退出码 1 结束。

| 参数或环境变量 | 用途 | 默认值 | | --- | --- | --- | | --help、-h | 打印启动选项并退出 | — | | --port <端口>、-p <端口> 或 PORT | 服务端口 | 40141 | | --hostname <主机>、-H <主机> 或 PI_WEB_HOSTNAME | 监听主机名 | 127.0.0.1 | | --no-open 或 PI_WEB_NO_OPEN=1 | 不自动打开浏览器 | 自动打开 | | PI_WEB_ALLOWED_HOSTS | 额外允许的代理或自定义主机名，多个值用逗号分隔，必须精确匹配 | 未设置 | | PI_WEB_PASSWORD | 启用浏览器密码登录；API 客户端可使用用户名为 pi 的 Basic Auth | 不启用认证 |

例如：

pws --help
pws -p 8080 -H 0.0.0.0 --no-open

远程访问

监听非回环地址会暴露一个可执行高权限操作的智能体。在可信局域网中使用时，请设置足够长的随机密码：

PI_WEB_PASSWORD='足够长的随机密码' pws --hostname 0.0.0.0

密码认证不会加密连接。不要通过明文 HTTP 将 Pi Web Space 暴露到互联网；远程访问应使用可信反向代理提供 HTTPS，或通过可信 VPN。如果反向代理传递外部主机名，请把该名称精确加入 PI_WEB_ALLOWED_HOSTS。这个白名单不会改变 Pi Web Space 的监听地址。

HTTP 代理

服务端的模型和 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 \
npm run dev

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"
npm run dev

注意事项

智能体数据：Pi Web Space 默认读取 ~/.pi/agent 下的 pi 数据，包括 sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl 中的会话文件。可通过 PI_CODING_AGENT_DIR 指定其他 pi agent 目录。
文件系统访问：Pi Web Space 必须能读取智能体数据目录及会话记录中的工作目录。与现有 pi 会话共用数据时，请让 Pi Web Space 运行在与 pi 相同的文件系统环境中。
共享配置：模型面板使用 pi 的模型、设置和凭据存储，因此两种界面都能看到相关更改。
文件访问边界：文件浏览器仅能访问在 Pi Web Space 中选择过的工作目录，以及它已识别的项目或会话根目录；它不是通用的文件系统浏览器。
Git worktree：切换器何时显示、如何创建 worktree，以及删除会产生什么影响，见 Pi Web Space 里的 Worktree。

开发

npm install
npm run dev

开发服务器运行在 http://127.0.0.1:40141。常用检查命令：

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

日常开发时不要运行 next build 或 npm run build。它们会写入 .next/，可能干扰开发服务器；仅在发布流程中执行构建。

贡献者文档：国际化和发布流程。

仓库结构

app/             Next.js 界面和 API 路由
components/      React 界面组件
hooks/           客户端状态和交互 hooks
lib/             会话、智能体、模型、文件、Git 和安全逻辑
public/          静态资源和 PWA 文件
bin/             npm CLI 入口及启动参数解析
docs/            面向用户和贡献者的专题文档

架构说明和详细文件地图见 AGENTS.md。

许可证

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme