@pananfly/pi-web 0.8.1

package/README.zh-CN.md

@@ -0,0 +1,136 @@
+# Pi Web
+
+[English](./README.md)
+
+[pi 编程智能体](https://github.com/badlogic/pi-mono) 的本地网页界面。它会读取本机的 pi 会话文件，在浏览器里提供会话管理、实时对话、模型配置、技能管理和项目文件预览。
+
+## 快速开始
+
+**无需安装，直接运行：**
+
+```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     # 组合使用
+pi-web --no-open                # 不自动打开浏览器
+
+PORT=8080 pi-web                # 也支持环境变量
+PI_WEB_NO_OPEN=1 pi-web         # 适用于后台服务或开机自启
+```
+
+## HTTP 代理
+
+Pi Web 的服务端模型请求和 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
+```
+
+## 功能介绍
+
+- **把历史工作接回来**：打开网页就能按项目找到以前的 pi 对话，不必在终端里翻文件或记住会话路径。
+- **放心试不同方向**：可以从某条历史消息重新开始，也可以复制出一条独立的新路线，探索方案时不怕弄乱原来的对话。
+- **跨分支工作**：在侧边栏切换 Git worktree，让新会话和 Explorer 跟随你选择的 checkout。
+- **边聊边看项目文件**：左侧浏览项目文件，右侧打开源码、文档、图片、音频和 PDF；文件变化会自动刷新，适合边让 agent 改边检查结果。
+- **随时掌握会话状态**：在顶部就能看到上下文占用、花费、压缩结果和系统提示，长会话不再像黑箱。
+- **少离开当前界面**：模型、登录/API key、模型测试和技能开关都能在网页里处理，配置 agent 时不用在多个工具之间来回切换。
+
+## 注意事项
+
+- **数据目录**：默认读取 `~/.pi/agent/sessions` 下的会话文件。可通过环境变量 `PI_CODING_AGENT_DIR` 指定其他 pi agent 目录。
+- **会话文件**：路径形如 `~/.pi/agent/sessions/<编码后的工作目录>/<时间戳>_<uuid>.jsonl`。
+- **模型配置**：Models 面板读写 pi agent 目录下的 `models.json`，模型列表和默认模型由 pi 的配置解析得到。
+- **文件访问**：文件浏览和预览面向当前选择的项目目录，以及会话中已出现过的工作目录。
+- **Git worktree**：什么时候显示切换器、新建目录在哪里、删除会影响什么，见 [Pi Web 里的 Worktree](./docs/worktrees.zh-CN.md)。
+- **Fork 与会话内分支不同**：Fork 会创建新的 `.jsonl` 文件；“Edit from here” 是同一会话文件里的分支。
+
+## 开发
+
+```bash
+npm install
+npm run dev
+```
+
+本地开发端口为 [http://localhost:30141](http://localhost:30141)。
+
+常用检查：
+
+```bash
+node_modules/.bin/tsc --noEmit
+npm run lint
+```
+
+开发时不要运行 `next build` / `npm run build`，它会写入 `.next/`，容易影响正在运行的 dev server。发布流程再执行构建。
+
+## 项目结构
+
+```
+app/
+  api/
+    agent/          # 创建/驱动 AgentSession，提供 SSE 事件流
+    auth/           # OAuth 和 API key 管理
+    cwd/validate/   # 自定义工作目录校验
+    default-cwd/    # 获取 pi 默认工作目录
+    files/          # 文件列表、读取、预览、watch
+    home/           # 当前用户 home 目录
+    models/         # 可用模型、默认模型、thinking levels
+    models-config/  # 读写 models.json、测试模型
+    sessions/       # 会话读取、重命名、删除、上下文、HTML 导出
+    skills/         # skills 列表、搜索、安装、启停
+components/
+  AppShell.tsx        # 主布局、URL 状态、顶部面板、文件标签
+  SessionSidebar.tsx  # 项目选择、会话树、Explorer
+  ChatWindow.tsx      # 消息区、SSE、拖拽图片、minimap
+  ChatInput.tsx       # 输入栏、模型/工具/thinking/compact/slash controls
+  MessageView.tsx     # 消息、thinking、tool call/result 渲染
+  ModelsConfig.tsx    # 模型和认证配置面板
+  SkillsConfig.tsx    # 技能管理面板
+  FileExplorer.tsx    # 文件树
+  FileViewer.tsx      # 源码、diff、图片、音频、PDF、DOCX 预览
+lib/
+  http-dispatcher.ts  # 服务端 fetch 的 HTTP(S) 代理配置
+  rpc-manager.ts      # AgentSessionWrapper 生命周期和全局 registry
+  session-reader.ts   # 解析 .jsonl 会话文件和分支上下文
+  normalize.ts        # 规范化 toolCall 字段名
+  file-access.ts      # 文件读取安全边界
+  file-paths.ts       # 文件路径编码/相对路径工具
+  markdown.ts         # Markdown/Mermaid/KaTeX 插件配置
+  pi-types.ts         # pi 相关类型
+hooks/
+  useAgentSession.ts  # 会话加载、发送命令、SSE 状态机
+  useAudio.ts         # 完成提示音
+  useDragDrop.ts      # 图片拖拽
+  useTheme.ts         # 主题切换
+bin/
+  pi-web.js           # npm CLI 入口
+instrumentation.ts    # 初始化服务端 HTTP dispatcher
+```

package/bin/pi-web-options.js

@@ -0,0 +1,45 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseArgs } = require("util");
+
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+
+function isEnabled(value) {
+  return typeof value === "string" && TRUE_VALUES.has(value.trim().toLowerCase());
+}
+
+function parseLaunchOptions(args = process.argv.slice(2), env = process.env) {
+  const { values: cliArgs } = parseArgs({
+    args,
+    options: {
+      port:      { type: "string", short: "p" },
+      hostname:  { type: "string", short: "H" },
+      "no-open": { type: "boolean" },
+      auth:      { type: "boolean" },
+      "no-auth": { type: "boolean" },
+      dev:       { type: "boolean" },
+    },
+    strict: false,
+  });
+
+  // Determine auth mode: CLI flag > env var > default (false)
+  let authEnabled = false;
+  if (cliArgs.auth) {
+    authEnabled = true;
+  } else if (cliArgs["no-auth"]) {
+    authEnabled = false;
+  } else if (isEnabled(env.PI_WEB_AUTH)) {
+    authEnabled = true;
+  }
+
+  return {
+    port: cliArgs.port ?? env.PORT ?? "30141",
+    hostname: cliArgs.hostname ?? env.HOSTNAME ?? null,
+    openBrowser: !cliArgs["no-open"] && !isEnabled(env.PI_WEB_NO_OPEN),
+    authEnabled,
+    dev: cliArgs.dev ?? false,
+  };
+}
+
+module.exports = { parseLaunchOptions };

package/bin/pi-web.js

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { spawn } = require("child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require("fs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const readline = require("readline");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { parseLaunchOptions } = require("./pi-web-options");
+
+const pkgDir = path.join(__dirname, "..");
+const nextDir = path.join(pkgDir, ".next");
+
+// Resolve next's CLI entry directly to avoid relying on .bin symlinks (which
+// may not exist when installed via npx).
+let nextBin;
+try {
+  nextBin = require.resolve("next/dist/bin/next", { paths: [pkgDir] });
+} catch {
+  // Fallback: locate next package root and derive the bin path manually.
+  try {
+    const nextPkg = require.resolve("next/package.json", { paths: [pkgDir] });
+    nextBin = path.join(path.dirname(nextPkg), "dist", "bin", "next");
+  } catch {
+    nextBin = path.join(pkgDir, "node_modules", "next", "dist", "bin", "next");
+  }
+}
+
+const { port, hostname, openBrowser, authEnabled, dev } = parseLaunchOptions();
+
+async function setupAuth() {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const auth = require("../lib/auth-cli");
+  const config = auth.getAuthConfig();
+
+  if (config) {
+    console.log("Auth already configured.");
+    return;
+  }
+
+  console.log("\nPi Web - Authentication Setup");
+  console.log("==============================\n");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const question = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+  try {
+    const username = await question("Enter username: ");
+    const password = await question("Enter password: ");
+    const confirmPassword = await question("Confirm password: ");
+
+    if (password !== confirmPassword) {
+      console.error("Passwords do not match.");
+      process.exit(1);
+    }
+
+    const validation = auth.validatePasswordStrength(password);
+    if (!validation.valid) {
+      console.error(`Invalid password: ${validation.error}`);
+      process.exit(1);
+    }
+
+    console.log("\n✓ Password meets requirements.\n");
+
+    const passwordHash = await auth.hashPassword(password);
+    const totpSecret = auth.generateTOTPSecret();
+
+    console.log("Generating 2FA secret...");
+    console.log("Scan this QR code with your authenticator app:\n");
+
+    // Generate QR code as ASCII art
+    const totpUri = auth.generateTOTPDatauri(totpSecret);
+    const qrCode = await auth.generateQRCode(totpUri);
+    console.log(qrCode);
+    console.log(`\nTOTP URI: ${totpUri}\n`);
+
+    const code = await question("Enter 2FA code to verify: ");
+
+    const valid = auth.verifyTOTP(totpSecret.base32, code);
+    if (!valid) {
+      console.error("Invalid 2FA code.");
+      process.exit(1);
+    }
+
+    console.log("✓ 2FA verified. Authentication enabled.\n");
+
+    auth.saveAuthConfig({
+      username,
+      passwordHash,
+      totpSecret: totpSecret.base32,
+      totpEnabled: true,
+      createdAt: new Date().toISOString(),
+    });
+
+    console.log(`✓ auth.json created at ${auth.getAuthConfigPath()}\n`);
+  } finally {
+    rl.close();
+  }
+}
+
+async function setup2FA() {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const auth = require("../lib/auth-cli");
+  const config = auth.getAuthConfig();
+
+  if (!config) {
+    console.error("No auth configured. Run with --auth first.");
+    process.exit(1);
+  }
+
+  console.log("\nPi Web - 2FA Reset");
+  console.log("===================\n");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const question = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+  try {
+    const password = await question("Enter password to verify identity: ");
+
+    const valid = await auth.verifyPassword(password, config.passwordHash);
+    if (!valid) {
+      console.error("Invalid password.");
+      process.exit(1);
+    }
+
+    console.log("✓ Password verified.\n");
+
+    const totpSecret = auth.generateTOTPSecret();
+
+    console.log("Generating new 2FA secret...");
+    console.log("Scan this QR code with your authenticator app:\n");
+
+    const totpUri = auth.generateTOTPDatauri(totpSecret);
+    const qrCode = await auth.generateQRCode(totpUri);
+    console.log(qrCode);
+    console.log(`\nTOTP URI: ${totpUri}\n`);
+
+    const code = await question("Enter 2FA code to verify: ");
+
+    const validCode = auth.verifyTOTP(totpSecret.base32, code);
+    if (!validCode) {
+      console.error("Invalid 2FA code.");
+      process.exit(1);
+    }
+
+    console.log("✓ 2FA verified and updated.\n");
+
+    auth.saveAuthConfig({
+      ...config,
+      totpSecret: totpSecret.base32,
+      totpEnabled: true,
+    });
+  } finally {
+    rl.close();
+  }
+}
+
+async function reset2FA() {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const auth = require("../lib/auth-cli");
+  const config = auth.getAuthConfig();
+
+  if (!config) {
+    console.error("No auth configured.");
+    process.exit(1);
+  }
+
+  console.log("\nPi Web - 2FA Reset");
+  console.log("===================\n");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const question = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+  try {
+    const password = await question("Enter password to verify identity: ");
+
+    const valid = await auth.verifyPassword(password, config.passwordHash);
+    if (!valid) {
+      console.error("Invalid password.");
+      process.exit(1);
+    }
+
+    console.log("✓ Password verified.\n");
+
+    auth.saveAuthConfig({
+      ...config,
+      totpSecret: "",
+      totpEnabled: false,
+    });
+
+    console.log("✓ 2FA has been reset. You will need to set it up again on next --auth start.\n");
+  } finally {
+    rl.close();
+  }
+}
+
+async function resetPassword() {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const auth = require("../lib/auth-cli");
+  const config = auth.getAuthConfig();
+
+  if (!config) {
+    console.error("No auth configured.");
+    process.exit(1);
+  }
+
+  console.log("\nPi Web - Password Reset");
+  console.log("======================\n");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const question = (query) => new Promise((resolve) => rl.question(query, resolve));
+
+  try {
+    const currentPassword = await question("Enter current password: ");
+
+    const valid = await auth.verifyPassword(currentPassword, config.passwordHash);
+    if (!valid) {
+      console.error("Invalid password.");
+      process.exit(1);
+    }
+
+    console.log("✓ Password verified.\n");
+
+    const newPassword = await question("Enter new password: ");
+    const confirmPassword = await question("Confirm new password: ");
+
+    if (newPassword !== confirmPassword) {
+      console.error("Passwords do not match.");
+      process.exit(1);
+    }
+
+    const validation = auth.validatePasswordStrength(newPassword);
+    if (!validation.valid) {
+      console.error(`Invalid password: ${validation.error}`);
+      process.exit(1);
+    }
+
+    const passwordHash = await auth.hashPassword(newPassword);
+
+    auth.saveAuthConfig({
+      ...config,
+      passwordHash,
+    });
+
+    console.log("✓ Password updated successfully.\n");
+  } finally {
+    rl.close();
+  }
+}
+
+if (!fs.existsSync(nextDir)) {
+  console.error("Build artifacts not found. Please report this issue.");
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+
+if (args.includes("setup-2fa")) {
+  setup2FA().catch(console.error);
+  process.exit(0);
+}
+
+if (args.includes("reset-2fa")) {
+  reset2FA().catch(console.error);
+  process.exit(0);
+}
+
+if (args.includes("reset-password")) {
+  resetPassword().catch(console.error);
+  process.exit(0);
+}
+
+if (authEnabled) {
+  setupAuth().then(() => {
+    startServer();
+  }).catch(console.error);
+} else {
+  startServer();
+}
+
+function startServer() {
+  const nextCommand = dev ? "dev" : "start";
+  const nextArgs = [nextCommand, "-p", port];
+  if (hostname) nextArgs.push("-H", hostname);
+
+  // Always run next's JS entry with node directly — avoids .bin symlink issues
+  // and path-with-spaces problems on Windows when shell: true is used.
+  const child = spawn(process.execPath, [nextBin, ...nextArgs], {
+    cwd: pkgDir,
+    stdio: ["inherit", "pipe", "inherit"],
+    env: {
+      ...process.env,
+      PI_WEB_AUTH: authEnabled ? "true" : "false",
+    },
+  });
+
+  let browserOpened = false;
+  const url = `http://${hostname ?? "localhost"}:${port}`;
+
+  child.stdout.on("data", (chunk) => {
+    const text = chunk.toString();
+    process.stdout.write(text);
+    if (openBrowser && !browserOpened && text.includes("Ready")) {
+      browserOpened = true;
+      const isWindows = process.platform === "win32";
+      const isMac = process.platform === "darwin";
+      const openCmd = isWindows ? "start" : isMac ? "open" : "xdg-open";
+      const opener = spawn(openCmd, [url], {
+        shell: isWindows,
+        stdio: "ignore",
+        detached: true,
+      });
+
+      opener.on("error", (error) => {
+        console.warn(`Could not open browser automatically: ${error.message}`);
+      });
+
+      opener.unref();
+    }
+  });
+
+  child.on("exit", (code) => process.exit(code ?? 0));
+}

package/lib/auth-cli.js

@@ -0,0 +1,115 @@
+"use strict";
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const bcrypt = require("bcryptjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const OTPAuth = require("otpauth");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fs = require("fs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const path = require("path");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const qrcode = require("qrcode-terminal");
+
+const BCRYPT_COST = 12;
+
+function getAuthConfigPath() {
+  return path.join(process.env.HOME || "~", ".pi", "agent", "auth.json");
+}
+
+function getAuthConfig() {
+  const configPath = getAuthConfigPath();
+  if (!fs.existsSync(configPath)) return null;
+  const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+  // Check if auth fields are present
+  if (!config.username || !config.passwordHash || !config.totpSecret || config.totpEnabled === undefined) {
+    return null;
+  }
+  return config;
+}
+
+function saveAuthConfig(config) {
+  const configPath = getAuthConfigPath();
+  const dir = path.dirname(configPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+async function hashPassword(password) {
+  return bcrypt.hash(password, BCRYPT_COST);
+}
+
+async function verifyPassword(password, hash) {
+  return bcrypt.compare(password, hash);
+}
+
+function validatePasswordStrength(password) {
+  if (password.length < 8) {
+    return { valid: false, error: "Password must be at least 8 characters" };
+  }
+  if (!/[A-Z]/.test(password)) {
+    return { valid: false, error: "Password must contain at least one uppercase letter" };
+  }
+  if (!/[a-z]/.test(password)) {
+    return { valid: false, error: "Password must contain at least one lowercase letter" };
+  }
+  if (!/[0-9]/.test(password)) {
+    return { valid: false, error: "Password must contain at least one number" };
+  }
+  if (!/[!@#$%^&*()_+\-=\[\]{};':"\\|,.<>\/?]/.test(password)) {
+    return { valid: false, error: "Password must contain at least one special character" };
+  }
+  return { valid: true };
+}
+
+function generateTOTPSecret() {
+  return new OTPAuth.Secret({ size: 20 });
+}
+
+function generateTOTPDatauri(secret) {
+  const totp = new OTPAuth.TOTP({
+    issuer: "Pi Web",
+    label: "admin",
+    algorithm: "SHA1",
+    digits: 6,
+    period: 30,
+    secret,
+  });
+  return totp.toString();
+}
+
+async function generateQRCode(text) {
+  return new Promise((resolve) => {
+    qrcode.generate(text, { small: true }, (qr) => {
+      resolve(qr);
+    });
+  });
+}
+
+function verifyTOTP(secret, token) {
+  const totp = new OTPAuth.TOTP({
+    issuer: "Pi Web",
+    label: "admin",
+    algorithm: "SHA1",
+    digits: 6,
+    period: 30,
+    secret: OTPAuth.Secret.fromBase32(secret),
+  });
+  const delta = totp.validate({ token, window: 1 });
+  return delta !== null;
+}
+
+module.exports = {
+  getAuthConfigPath,
+  getAuthConfig,
+  saveAuthConfig,
+  hashPassword,
+  verifyPassword,
+  validatePasswordStrength,
+  generateTOTPSecret,
+  generateTOTPDatauri,
+  generateQRCode,
+  verifyTOTP,
+};

package/next.config.ts

@@ -0,0 +1,37 @@
+import type { NextConfig } from "next";
+import { readFileSync } from "fs";
+import { join } from "path";
+
+const { version } = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8")) as { version: string };
+let piVersion = "unknown";
+try {
+  const piPkgPath = join(__dirname, "node_modules/@earendil-works/pi-coding-agent/package.json");
+  piVersion = (JSON.parse(readFileSync(piPkgPath, "utf8")) as { version: string }).version;
+} catch { /* package not found, use default */ }
+
+const nextConfig: NextConfig = {
+  serverExternalPackages: [
+    "undici",
+    "@earendil-works/pi-coding-agent",
+    "@earendil-works/pi-agent-core",
+    "@earendil-works/pi-ai",
+    "@earendil-works/pi-tui",
+  ],
+  allowedDevOrigins: ['192.168.*.*', '[2408:8256:1a]'],
+  async headers() {
+    return [
+      {
+        source: "/",
+        headers: [
+          { key: "Cache-Control", value: "private, no-cache, max-age=0, must-revalidate" },
+        ],
+      },
+    ];
+  },
+  env: {
+    NEXT_PUBLIC_APP_VERSION: version,
+    NEXT_PUBLIC_PI_VERSION: piVersion,
+  },
+};
+
+export default nextConfig;