# pi-web

[pi 编程智能体](https://github.com/badlogic/pi-mono) 的网页界面。在浏览器中浏览会话、与智能体对话、分叉对话、切换消息分支。

## 快速开始

**无需安装，直接运行：**

```bash
npx @agegr/pi-web@latest
```

**或全局安装后使用：**

```bash
npm install -g @agegr/pi-web
pi-web
```

启动后打开 [http://localhost:30141](http://localhost:30141)。

**可选参数：**

```bash
pi-web --port 8080               # 自定义端口
pi-web --hostname 127.0.0.1      # 仅本机访问
pi-web -p 8080 -H 127.0.0.1     # 组合使用

PORT=8080 pi-web                 # 也支持环境变量
```

## 功能介绍

- **会话浏览器** — 按工作目录分组展示所有 pi 会话
- **实时对话** — 通过 SSE 流式输出与智能体实时交互
- **会话分叉** — 从任意用户消息创建独立的新会话分支
- **会话内分支** — 回退到任意节点继续对话，在同一文件内创建分支
- **分支导航器** — 可视化切换同一会话内的各个分支
- **模型切换** — 对话中途随时切换模型
- **工具面板** — 控制智能体可使用的工具
- **压缩会话** — 对长会话进行摘要，节省上下文窗口
- **引导 / 追加** — 打断正在运行的智能体，或在其完成后追加消息

## 注意事项

- **数据目录** — 默认读取 `~/.pi/agent/sessions` 下的会话文件。可通过环境变量 `PI_CODING_AGENT_DIR` 指定其他目录。
- **模型配置** — 从智能体数据目录下的 `models.json` 读取可用模型，可在侧边栏的「Models」面板中编辑。
- **文件浏览** — 侧边栏内置文件浏览器，可在标签页中查看当前工作目录下的文件。

## 开发

```bash
npm install
npm run dev   # 端口 30141
```

## 部署（pm2）

项目内置 `ecosystem.config.cjs`（pm2 配置）与 `appctl.sh`（运维脚本），支持以常驻进程方式部署到服务器。

**前置条件：** 服务器需安装 [Node.js](https://nodejs.org/) 与 pm2（`npm install -g pm2`）。

### 首次部署

```bash
git clone <仓库地址> pi-web && cd pi-web
./appctl.sh build        # 安装依赖 + 构建（产物输出到 .next/）
./appctl.sh start        # 通过 pm2 启动
./appctl.sh startup      # 保存进程列表 + 配置开机自启
```

启动后访问 `http://<服务器IP>:30141`。

### 更新部署

```bash
./appctl.sh deploy                 # git pull + install + build + restart
./appctl.sh deploy --no-install    # 依赖无变化时跳过安装
```

### 常用命令

| 命令 | 作用 |
| --- | --- |
| `./appctl.sh start` / `stop` / `restart` / `reload` | 启动 / 停止 / 重启 / 零停机重载 |
| `./appctl.sh status` | 查看运行状态 |
| `./appctl.sh logs` | 实时日志（Ctrl+C 退出） |
| `./appctl.sh build` / `install` | 构建 / 安装依赖 |
| `./appctl.sh delete` | 从 pm2 列表移除 |
| `./appctl.sh help` | 查看全部命令 |

### 配置说明

`ecosystem.config.cjs` 默认监听端口 `30141`、对外开放（`-H 0.0.0.0`），按需修改 `args`：

- **监听地址** — 改 `args` 中的 `-H`：`0.0.0.0`（对外，默认）/ `127.0.0.1`（仅本机）/ 指定网卡 IP
- **端口** — 改 `args` 中的 `-p`
- **会话数据目录** — 取消注释 `PI_CODING_AGENT_DIR`（默认 `~/.pi`）
- **包管理器** — 脚本自动检测（有 `bun.lock` 用 bun，否则 npm），可用 `PKG_MGR` 环境变量覆盖

## 项目结构

```
app/
  api/
    sessions/      # 读写会话文件
    agent/         # 发送命令、SSE 事件流
    files/         # 文件内容读取
    models/        # 可用模型列表与默认模型
    models-config/ # 读写 models.json
components/        # UI 组件
lib/
  session-reader.ts  # 解析 .jsonl 会话文件
  rpc-manager.ts     # 管理 AgentSession 生命周期
  normalize.ts       # 规范化 toolCall 字段名
  types.ts
```

会话文件存储路径：`~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl`