pios-web

Local-first AI coding workspace for pi — 本地优先的 pi 智能编程工作台

让 pi 成为一个可观察、可操作、可持续运行的编程工作台。 数据留本地，凭据在服务端，一套界面覆盖手机到桌面。

Requires Node.js ≥ 22.19 and a configured pi environment.

Install / 安装

npm install -g pios-web
pios-web                      # http://localhost:8787
npx pios-web                  # 免安装直接跑

npm 12+ 需放行原生模块：npm install -g --allow-scripts=node-pty,@google/genai,protobufjs pios-web@latest

What you get / 核心功能

| 功能 | 说明 | |------|------| | 💬 流式对话 | 思考块、工具调用卡片、bash 输出实时状态；steer 插队；多对话并发运行 | | 📎 附件 & 图片 | inline / reference / lines 三种模式；粘贴/拖拽图片；视觉桥（纯文本模型也能看图） | | 🖥️ 内置终端 | xterm.js + node-pty，Windows 自动选 Git Bash；终端内直接跑 git commit/push/pull | | 📁 文件 & Git | 行号预览、选中行添加到对话、实时文件树、Git 状态/diff/提交面板 | | 🎯 目标复核 | 设置目标 + 审查模型，AI 自动迭代直到达标 | | 📱 手机适配 | 响应式布局，触摸优化，同一 Wi-Fi 下手机浏览器直连，无需 App |

Screenshots / 截图

Desktop view / 桌面端视图

File tree & chat interface / 文件树与对话界面

Integrated terminal & conversation history / 内置终端与对话历史

System management dashboard / 系统管理面板

Settings panel / 设置面板

Mobile view / 移动端视图

Built-in terminal with on-screen keyboard / 移动端内置终端

Chat input navigation buttons / 对话导航按钮

Message navigation controls / 消息导航控件

Quick start / 快速上手

pios-web                              # 启动（首次打开 http://localhost:8787 按引导配置）
PORT=9000 PI_WEB_CWD=/path pios-web   # 指定端口和工作目录
pios-web --no-browser                 # 无浏览器自动打开
pios-web server install               # 安装为系统服务（开机自启）
pios-web server status/restart/stop   # 服务管理

Access token / 访问令牌

首次启动时，终端会输出生成好的访问令牌：

    auth token  : user@hostname@A1B2C3D4E5F6G7H8I9J0

将此值复制到浏览器登录页即可访问。令牌保存在 <data-dir>/auth-token，默认位于当前用户主目录下的 .pi-web/auth-token，重启不会改变。

Access token / How to get it:

When you start the server, the terminal prints an access token:

    auth token  : user@hostname@A1B2C3D4E5F6G7H8I9J0

Copy this value into the browser login page. The token is persisted in <data-dir>/auth-token, which defaults to ~/.pi-web/auth-token in your user home directory, and remains unchanged across restarts.

Security / 安全

• 默认只绑 127.0.0.1，不暴露网络
• WebSocket Origin/Host 同权威校验，跨源 403
• 凭据永不下发浏览器（headers 保留在服务端）
• pios-web server quiesce 排空模式（拒绝新工作，存量跑完）

Reverse proxy / 反向代理

Browser access & upgrades / 浏览器访问与更新

同机 nginx 反代（无需改 PI_WEB_HOST）。浏览器访问和在线更新都走同一个配置：

location /pi/ {
    proxy_pass http://127.0.0.1:8787/;
    proxy_set_header Host $http_host;   # 必须保留端口
}
location /ws {
    proxy_pass http://127.0.0.1:8787;
    proxy_set_header Host $http_host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
}

In-app updates / 应用内更新

前端「立即更新」按钮会在可见终端中运行 npm i -g pios-web@latest，完成后执行 pios-web server restart 生效。如果配置了反向代理，确保 / 路径能正确转发到后端静态文件服务（web/dist），否则更新后可能无法加载新版本的 UI。

完整示例：deploy/nginx-pios.conf。

License / 许可证

MIT