pi-cloud 2.0.0

package/README.zh-CN.md

@@ -0,0 +1,134 @@
+# Pi Cloud
+
+[English](README.md) | 简体中文
+
+一个基于 Web、适配移动设备的 [Pi 编程智能体](http://pi.dev)界面。它为以终端为主的 CLI 提供了补充，让智能体会话和开发工作流拥有一个持久化工作区。
+
+| 深色主题                                                           | 浅色主题                                                            |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| ![Pi Cloud 深色主题主窗口](docs/images/main-window-dark-theme.png) | ![Pi Cloud 浅色主题主窗口](docs/images/main-window-white-theme.png) |
+
+**[▶ 观看 Pi Cloud 完成 Git 缺陷修复工作流](https://xianzhon.github.io/pi-cloud-website/assets/videos/demo-git-bugfix-workflow.mp4)**
+
+## 功能特性
+
+- **移动端友好** — 无需本地终端，即可在电脑、手机或平板上使用 Pi。
+- **技能控制** — 配置预设，并为每个会话启用或禁用技能。
+- **会话管理** — 搜索、恢复、重命名和分支会话，并在不同标签页中运行独立会话。
+- **任务队列** — 保存和配置任务，准备就绪后再启动。
+- **完成通知** — 任务完成时接收提示音，并在浏览器标签页中看到铃铛提示。
+- **AI 辅助写作** — 生成或润色提示词、提交信息、拉取请求内容及其他工作流文本。
+- **Git 工作流** — 在 WebUI 中使用 `/branch`、`/commit`、`/push` 等命令。
+- **GitHub 和 Gitea 集成** — 使用 `/pr` 审查更改并创建拉取请求。
+- **记忆支持** — 维护项目级和全局记忆，并可选择自动提取和自适应召回。
+- **消息网关** — 通过简洁的配置接入飞书和微信。
+- **工作区工具** — 浏览和搜索文件、编辑代码，并在对话旁使用内嵌终端。
+- **安全访问** — 使用密码和可选的 TOTP 身份验证保护 WebUI。
+
+## 快速开始
+
+### 前置要求
+
+- Node.js 22 或更高版本
+- pnpm 9 或更高版本（仅从源码开发时需要）
+
+Pi Cloud 已包含 [Pi 编程智能体](http://pi.dev)，因此使用 API 密钥进行身份验证时无需单独安装 `pi`。API 密钥可以在 Agent 配置对话框中设置。
+
+WebUI 目前尚不支持 OAuth 订阅登录；原生 OAuth 支持已列为未来改进计划。现阶段若要使用 OAuth，请安装独立的 Pi CLI，并以运行 Pi Cloud 的同一操作系统用户在终端中完成 `/login`：
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+pi
+# 输入 /login 并选择提供商
+```
+
+之后，Pi Cloud 会检测默认 `~/.pi/agent` 配置中存储的 OAuth 凭据。
+
+### 无需安装直接运行
+
+如果 npm 在构建原生依赖时失败，请安装 `build-essential`、`python3` 等系统构建工具，然后重试。
+
+设置登录凭据，然后运行最新版本：
+
+```bash
+PI_CLOUD_AUTH_USERNAME=pi PI_CLOUD_AUTH_PASSWORD='change-this-password' npx pi-cloud@latest
+```
+
+打开 http://127.0.0.1:3000。服务器准备就绪后，CLI 会自动打开浏览器。
+
+### 全局安装
+
+```bash
+npm install -g pi-cloud
+pi-cloud
+```
+
+首次运行时，Pi Cloud 会创建受保护的配置文件，用户名默认为 `admin`，并仅显示一次随机生成的密码。
+
+请参阅[配置手册](docs/manuals-cn/configuration.md)，了解如何自定义凭据、端口和其他设置。如需远程或公网访问，请参阅[部署手册](docs/manuals-cn/deployment.md)。
+
+### 作为系统服务运行
+
+在 Linux、macOS 或 Windows 上将 Pi Cloud 安装为开机启动服务：
+
+```bash
+pi-cloud service install
+pi-cloud service status
+```
+
+在 Windows 上，防病毒软件可能会阻止 `pi-cloud service install`，因为该命令会创建自动启动的计划任务。允许前请核对防病毒软件的检测内容；请勿禁用防病毒软件，也不要排除整个 npm 目录。
+
+### 从源码运行
+
+```bash
+git clone https://github.com/xianzhon/pi-cloud && cd pi-cloud
+pnpm install
+cp .env.example .env    # 设置 PI_CLOUD_AUTH_USERNAME 和 PI_CLOUD_AUTH_PASSWORD
+pnpm dev
+```
+
+开发期间请打开 http://localhost:5173。生产服务器监听 `PORT`（默认值为 `3000`）。
+
+## 配置
+
+基本设置如下：
+
+| 变量                       | 说明                              |
+| -------------------------- | --------------------------------- |
+| `PI_CLOUD_AUTH_USERNAME` | 登录用户名                        |
+| `PI_CLOUD_AUTH_PASSWORD` | 简单部署所使用的登录密码          |
+| `PORT`                   | 后端端口（默认值：`3000`）      |
+| `HOST`                   | 绑定地址（默认值：`127.0.0.1`） |
+
+生产环境中，请使用 `PI_CLOUD_AUTH_PASSWORD_HASH`，而不是明文密码。有关配置文件、安全、会话、存储、工作区、记忆、提供商和网关设置，请参阅[配置手册](docs/manuals-cn/configuration.md)。
+
+## 部署
+
+有关源码和 npm 软件包部署以及 nginx 反向代理配置，请参阅[部署手册](docs/manuals-cn/deployment.md)。
+
+## 文档
+
+浏览[文档索引](docs/README.md)，查看全部用户手册和开发者参考资料。
+
+## 开发
+
+```bash
+pnpm dev                  # 启动前后端服务器
+pnpm build                # 类型检查并构建前后端
+pnpm test                 # 运行所有测试
+```
+
+- 前端：http://localhost:5173（Vite，将 `/api` 和 `/ws` 代理到后端）
+- 后端：http://localhost:3000（Fastify）
+- 日志：`.logs/`
+- PID 文件：`.pids/`
+
+有关架构、API、本地软件包测试和项目目录结构的说明，请参阅[开发者说明（英文）](docs/to-developers/developer-notes.md)。
+
+## 贡献
+
+欢迎贡献。有关开发环境设置、分支和拉取请求规范、测试、文档要求及安全问题报告方式，请参阅 [CONTRIBUTING.md（英文）](CONTRIBUTING.md)。
+
+## 许可证
+
+本项目采用 Apache License 2.0 许可。详情请参阅 [LICENSE](./LICENSE)。

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,13 @@
+Third-Party Notices
+===================
+
+PDF.js
+------
+
+Copyright 2024 Mozilla Foundation
+
+PDF.js is licensed under the Apache License, Version 2.0.
+A copy of the Apache License is included in the LICENSE file distributed with
+this package.
+
+Source: https://github.com/mozilla/pdf.js

package/bin/pi-cloud.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+import { homedir } from 'node:os';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { loadRuntimeConfig } from './runtime-config.mjs';
+
+function printHelp() {
+  console.log(`Usage: pi-cloud [options]
+
+Options:
+  -p, --port <port>       Listen on this port (default: 3000)
+  -H, --hostname <host>   Bind to this hostname (default: 127.0.0.1)
+      --no-open           Do not open the browser
+  -v, --version           Show the current version
+  -h, --help              Show this help
+
+Environment variables PORT and HOST are also supported.
+
+Service commands:
+  service install          Install and enable automatic startup
+  service start            Start the service
+  service stop             Stop the service
+  service restart          Restart the service
+  service status           Show service status
+  service uninstall        Remove the service
+  update [version]         Update the global npm installation
+  update --check           Check for available updates`);
+}
+
+function parseArgs(args) {
+  const options = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '-h' || arg === '--help') {
+      printHelp();
+      process.exit(0);
+    }
+    if (arg === '-v' || arg === '--version') {
+      console.log(installedVersion());
+      process.exit(0);
+    }
+    if (arg === '--no-open') {
+      options.noOpen = true;
+      continue;
+    }
+    if (arg === '-p' || arg === '--port' || arg === '-H' || arg === '--hostname') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`);
+      options[arg === '-p' || arg === '--port' ? 'port' : 'hostname'] = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+  return options;
+}
+
+const SERVICE_NAME = 'pi-cloud';
+const SERVICE_LABEL = 'com.pi-cloud';
+const NPM_PACKAGE_NAME = 'pi-cloud';
+const scriptPath = fileURLToPath(import.meta.url);
+
+function runCommand(command, args) {
+  const result = spawnSync(command, args, { stdio: 'inherit' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${command} exited with status ${result.status}`);
+}
+
+function spawnNpm(args, options) {
+  if (process.platform === 'win32') {
+    // npm is installed as npm.cmd on Windows, which must run through cmd.exe.
+    return spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', 'npm.cmd', ...args], options);
+  }
+  return spawnSync('npm', args, options);
+}
+
+function runNpm(args) {
+  const result = spawnNpm(args, { stdio: 'inherit' });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`npm exited with status ${result.status}`);
+}
+
+function linuxServicePath() {
+  return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'systemd', 'user', `${SERVICE_NAME}.service`);
+}
+
+function macServicePath() {
+  return join(homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+}
+
+function installLinuxService() {
+  const servicePath = linuxServicePath();
+  mkdirSync(join(servicePath, '..'), { recursive: true });
+  writeFileSync(servicePath, `[Unit]\nDescription=Pi Cloud\nAfter=network-online.target\n\n[Service]\nType=simple\nExecStart="${process.execPath}" "${scriptPath}" --no-open\nWorkingDirectory=${homedir()}\nEnvironment=HOME=${homedir()}\nRestart=on-failure\nRestartSec=5\n\n[Install]\nWantedBy=default.target\n`);
+  runCommand('systemctl', ['--user', 'daemon-reload']);
+  runCommand('systemctl', ['--user', 'enable', '--now', SERVICE_NAME]);
+  console.log(`Installed Linux service at ${servicePath}`);
+  console.log('To start automatically before login, enable user lingering with: sudo loginctl enable-linger "$USER"');
+}
+
+function installMacService() {
+  const servicePath = macServicePath();
+  mkdirSync(join(servicePath, '..'), { recursive: true });
+  const xmlEscape = (value) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+  writeFileSync(servicePath, `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>${SERVICE_LABEL}</string>\n<key>ProgramArguments</key><array><string>${xmlEscape(process.execPath)}</string><string>${xmlEscape(scriptPath)}</string><string>--no-open</string></array>\n<key>WorkingDirectory</key><string>${xmlEscape(homedir())}</string>\n<key>RunAtLoad</key><true/>\n<key>KeepAlive</key><true/>\n</dict></plist>\n`);
+  const domain = `gui/${process.getuid()}`;
+  spawnSync('launchctl', ['bootout', domain, servicePath], { stdio: 'ignore' });
+  runCommand('launchctl', ['bootstrap', domain, servicePath]);
+  console.log(`Installed macOS LaunchAgent at ${servicePath}`);
+}
+
+function installWindowsService() {
+  const taskCommand = `"${process.execPath}" "${scriptPath}" --no-open`;
+  runCommand('schtasks', ['/Create', '/TN', SERVICE_NAME, '/SC', 'ONLOGON', '/TR', taskCommand, '/F']);
+  runCommand('schtasks', ['/Run', '/TN', SERVICE_NAME]);
+  console.log('Installed Windows startup task Pi Cloud.');
+}
+
+function installedVersion() {
+  const packagePath = join(dirname(scriptPath), '..', 'package.json');
+  return JSON.parse(readFileSync(packagePath, 'utf8')).version;
+}
+
+function updateCommand(version) {
+  const currentVersion = installedVersion();
+  if (version === '--check') {
+    const result = spawnNpm(['view', NPM_PACKAGE_NAME, 'version', '--silent'], { encoding: 'utf8' });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error(result.stderr?.trim() || 'Could not check the latest version.');
+    const latestVersion = result.stdout.trim();
+    console.log(`Installed version: ${currentVersion}`);
+    console.log(`Latest version: ${latestVersion}`);
+    console.log(currentVersion === latestVersion ? 'Pi Cloud is up to date.' : 'An update is available. Run: pi-cloud update');
+    return;
+  }
+
+  if (version && !/^[0-9A-Za-z][0-9A-Za-z._+-]*$/.test(version)) {
+    throw new Error(`Invalid version or npm tag: ${version}`);
+  }
+  const packageSpec = version ? `${NPM_PACKAGE_NAME}@${version}` : `${NPM_PACKAGE_NAME}@latest`;
+  runNpm(['install', '-g', packageSpec]);
+  console.log(`Updated ${packageSpec}.`);
+  console.log('If Pi Cloud is running as a service, restart it to use the new version:');
+  console.log('  pi-cloud service restart');
+}
+
+function serviceCommand(action) {
+  if (!action) throw new Error('Usage: pi-cloud service <install|start|stop|restart|status|uninstall>');
+
+  if (process.platform === 'linux') {
+    if (action === 'install') return installLinuxService();
+    if (action === 'start') return runCommand('systemctl', ['--user', 'start', SERVICE_NAME]);
+    if (action === 'stop') return runCommand('systemctl', ['--user', 'stop', SERVICE_NAME]);
+    if (action === 'restart') return runCommand('systemctl', ['--user', 'restart', SERVICE_NAME]);
+    if (action === 'status') return runCommand('systemctl', ['--user', 'status', SERVICE_NAME]);
+    if (action === 'uninstall') {
+      runCommand('systemctl', ['--user', 'disable', '--now', SERVICE_NAME]);
+      rmSync(linuxServicePath(), { force: true });
+      return runCommand('systemctl', ['--user', 'daemon-reload']);
+    }
+  } else if (process.platform === 'darwin') {
+    const domain = `gui/${process.getuid()}`;
+    const servicePath = macServicePath();
+    if (action === 'install') return installMacService();
+    if (action === 'start') return runCommand('launchctl', ['kickstart', `${domain}/${SERVICE_LABEL}`]);
+    if (action === 'stop') return runCommand('launchctl', ['kill', 'SIGTERM', `${domain}/${SERVICE_LABEL}`]);
+    if (action === 'restart') return runCommand('launchctl', ['kickstart', '-k', `${domain}/${SERVICE_LABEL}`]);
+    if (action === 'status') return runCommand('launchctl', ['print', `${domain}/${SERVICE_LABEL}`]);
+    if (action === 'uninstall') {
+      runCommand('launchctl', ['bootout', domain, servicePath]);
+      return rmSync(servicePath, { force: true });
+    }
+  } else if (process.platform === 'win32') {
+    if (action === 'install') return installWindowsService();
+    if (action === 'start') return runCommand('schtasks', ['/Run', '/TN', SERVICE_NAME]);
+    if (action === 'stop') return runCommand('schtasks', ['/End', '/TN', SERVICE_NAME]);
+    if (action === 'restart') {
+      runCommand('schtasks', ['/End', '/TN', SERVICE_NAME]);
+      return runCommand('schtasks', ['/Run', '/TN', SERVICE_NAME]);
+    }
+    if (action === 'status') return runCommand('schtasks', ['/Query', '/TN', SERVICE_NAME]);
+    if (action === 'uninstall') return runCommand('schtasks', ['/Delete', '/TN', SERVICE_NAME, '/F']);
+  }
+
+  throw new Error(`Unknown service action: ${action}`);
+}
+
+function openBrowser(url) {
+  let command;
+  let args;
+  let shell = false;
+
+  if (process.platform === 'darwin') {
+    command = 'open';
+    args = [url];
+  } else if (process.platform === 'win32') {
+    command = 'cmd.exe';
+    args = ['/c', 'start', '', url];
+  } else {
+    command = 'xdg-open';
+    args = [url];
+  }
+
+  const child = spawn(command, args, { detached: true, stdio: 'ignore', shell });
+  child.on('error', (error) => {
+    if (error.code === 'ENOENT') {
+      console.warn(`Could not find ${command}; open ${url} manually or use --no-open.`);
+      return;
+    }
+    console.warn(`Could not open ${url}: ${error.message}`);
+  });
+  child.unref();
+}
+
+try {
+  const args = process.argv.slice(2);
+  if (args[0] === 'service') {
+    serviceCommand(args[1]);
+    process.exit(0);
+  }
+  if (args[0] === 'update') {
+    updateCommand(args[1]);
+    process.exit(0);
+  }
+
+  const options = parseArgs(args);
+  process.env.PI_CLOUD_CLI_IMPORT = '1';
+
+  const { startServer } = await loadRuntimeConfig(options, () => import('../server/dist/index.js'));
+  const app = await startServer();
+  const address = app.server.address();
+  const port = typeof address === 'object' && address ? address.port : process.env.PORT;
+  const url = `http://${process.env.HOST}:${port}`;
+  const configHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config');
+  const configPath = join(configHome, 'pi-cloud', '.env');
+  const databasePath = process.env.PI_CLOUD_DB_PATH ?? join(configHome, 'pi-cloud', 'pi-cloud.sqlite');
+  console.log(`Pi Cloud running at ${url}`);
+  console.log(`Configuration: ${configPath}`);
+  console.log(`Database: ${databasePath}`);
+  console.log('These files are preserved when Pi Cloud is uninstalled.');
+  if (!options.noOpen) openBrowser(url);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+}

package/bin/runtime-config.mjs

@@ -0,0 +1,11 @@
+// CLI options must be visible during module initialization, but defaults must wait until dotenv has loaded.
+export async function loadRuntimeConfig(options, loadServer, env = process.env) {
+  if (options.port !== undefined) env.PORT = options.port;
+  if (options.hostname !== undefined) env.HOST = options.hostname;
+
+  const server = await loadServer();
+
+  env.PORT ??= '3000';
+  env.HOST ??= '127.0.0.1';
+  return server;
+}