pi-web-xyy

基于 agegr/pi-web 的个人定制版 —— pi coding agent 的浏览器工作台。核心代码跟随上游同步，叠加个人扩展，本地打包使用（不发 npm registry、不发 GitHub Release）。

历史文档归档于 docs/old/（英文/日文/俄文/旧中文版 README）。

版本规则

<上游版本>-0.<序号>

• 0.8.6-0.1：基于上游 0.8.6 的第 1 次定制发布
• 0.8.6-0.2：上游未更新，自己新增扩展后的第 2 次发布
• 0.8.7-0.1：同步上游新版本后，序号重新起算

快速开始

需要 Node.js 22.19.0 或更高。

本机已全局安装（~/.nvm/versions/node/v24.16.0/lib/node_modules/pi-web-xyy），直接启动：

pi-web-xyy --no-open -p 7001

打开 http://127.0.0.1:7001。默认监听 127.0.0.1。

启动选项：

pi-web-xyy --port 8080            # 自定义端口
pi-web-xyy --hostname 0.0.0.0     # 暴露到可信网络
pi-web-xyy -p 8080 -H 0.0.0.0     # 组合使用
pi-web-xyy --no-open              # 不自动打开浏览器

PORT=8080 pi-web-xyy              # 环境变量同样支持
PI_WEB_HOSTNAME=0.0.0.0 pi-web-xyy
PI_WEB_ALLOWED_HOSTS=pi-web.internal pi-web-xyy   # 允许的反向代理/自定义主机名
PI_WEB_PASSWORD='长随机密码' pi-web-xyy           # 启用 Basic Auth（用户名固定 pi）
PI_WEB_NO_OPEN=1 pi-web-xyy       # 后台服务场景

设置 PI_WEB_PASSWORD 可对 Web 界面和所有 API 端点启用 HTTP Basic Auth，用户名固定为 pi，不设置则关闭鉴权。Basic Auth 不加密传输，请勿将明文 HTTP 暴露到公网；远程访问请走 HTTPS 反向代理或可信 VPN。

HTTP 代理

服务端模型/API 请求读取标准 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 环境变量：

HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
NO_PROXY=localhost,127.0.0.1 \
pi-web-xyy

功能特性

• 接续会话：按项目浏览历史 pi 会话，不必翻终端历史或会话路径。
• 安全试错：从任意早期消息继续，或 fork 会话到独立路线。
• 跨分支工作：侧边栏直接切换 Git worktree，新会话与文件浏览器跟随所选检出。
• 项目旁聊：左侧浏览文件、右侧预览源码/文档/图片/音频/PDF，agent 同时在干活。
• 会话状态一目了然：顶栏展示上下文用量、费用、压缩状态、系统提示词详情。
• 少碰终端：Web 界面管理模型、登录/API 密钥、模型测试、技能开关。
• 界面多语言：顶栏切换界面语言。

本地打包与升级

日常升级流程（详见 docs/release.md）：

git fetch origin && git merge origin/main   # 1. 同步上游核心
npm version <上游版本>-0.<序号> --no-git-tag-version  # 2. 版本号
npm run build                               # 3. 构建预编译 .next
npm run pack                                # 4. 本地打包 → dist/pi-web-xyy-<版本>.tgz
npm i -g ./dist/pi-web-xyy-<版本>.tgz       # 5. 全局安装
pi-web-xyy --no-open -p 7001                # 6. 重启实例

回滚：重新安装旧版本 tarball 即可。

注意事项

• 数据目录：默认读取 ~/.pi/agent/sessions，可用 PI_CODING_AGENT_DIR 指向其他 pi agent 目录。
• 会话文件：~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl。
• 模型配置：Models 面板读写 pi agent 目录下的 models.json。
• 文件访问：文件浏览/预览限定在所选项目目录与会话中出现的工作目录。
• Fork vs 分支：Fork 创建新的 .jsonl 文件；"从此处编辑"在同一会话文件内新建分支。
• 下游会话右键菜单 Hook（上游 0.8.8）：Electron 等下游集成可监听 pi-web:session-row-contextmenu 浏览器事件并同步 preventDefault() 接管会话行右键菜单，事件 detail 含 { id, path, cwd, name, clientX, clientY, refresh }。
• 现有 systemd 服务：本机 pi-web-xyy.service（指向源码目录 /home/<USER>/app/github/pi-web，端口 7000）禁止停止、禁止修改；本包的开发者实例使用其他端口（如 7001）。Ubuntu 24.04 注册 systemd 开机自启的示例见 docs/systemd.md。

开发

npm install --include=dev   # 注意: 本机 npm 配置了 omit=dev, 必须带此参数
npm run dev                 # http://127.0.0.1:30141

常规检查：

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

日常开发不要跑 next build（会写 .next/ 干扰 dev server），构建只留给发布流程。

项目结构

app/
  api/
    agent/          # 创建/驱动 AgentSession, 暴露 SSE 事件
    auth/           # OAuth 与 API 密钥管理
    cwd/            # 工作目录浏览与校验
    files/          # 文件列表、读取、预览、监听
    home/           # 用户主目录
    models/         # 可用模型、默认模型、思考级别
    models-config/  # 读写 models.json 与模型测试
    sessions/       # 会话读取、重命名、删除、上下文、HTML 导出
    skills/         # 技能列表、搜索、安装、启停
components/
  AppShell.tsx        # 主布局、URL 状态、顶栏、文件标签
  SessionSidebar.tsx  # 项目选择、会话树、文件浏览器
  ChatWindow.tsx      # 消息、SSE、拖拽、minimap
  ChatInput.tsx       # 输入栏、模型/工具/思考/压缩/斜杠控制
  MessageView.tsx     # 消息、思考、工具调用/结果渲染
  ModelsConfig.tsx    # 模型与鉴权配置面板
  SkillsConfig.tsx    # 技能管理面板
  FileExplorer.tsx    # 文件树
  FileViewer.tsx      # 源码、diff、图片、音频、PDF、DOCX 预览
lib/
  rpc-manager.ts      # AgentSessionWrapper 生命周期与全局注册表
  session-reader.ts   # 解析 .jsonl 会话文件与分支上下文
  normalize.ts        # toolCall 字段名归一化
  file-access.ts      # 文件读取安全边界
  markdown.ts         # Markdown/Mermaid/KaTeX 插件配置
hooks/
  useAgentSession.ts  # 会话加载、命令发送、SSE 状态机
  useAudio.ts         # 完成音效
  useTheme.ts         # 主题切换
bin/
  pi-web.js           # npm CLI 启动器