Skip to content
60 changes: 59 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -290,7 +290,7 @@ https://github.com/user-attachments/assets/a7245467-ee3c-4939-a055-c56576ac56d1

## 📦 Installation & Quick Start

We provide a one-line installer for macOS / Linux, plus a source-based workflow for developers.
We provide one-line installers for macOS / Linux and Windows PowerShell, plus a source-based workflow for developers.

### Option A: One-line install (recommended, macOS / Linux)

Expand All @@ -305,6 +305,64 @@ pilotdeck # starts the server at http://localhost:3001
pilotdeck status # check runtime status
```

To open PilotDeck again later on macOS / Linux, run `pilotdeck` in a terminal and open the printed URL in your browser. If your shell has not picked up the PATH update yet, open a new terminal or source your shell profile first.

```bash
pilotdeck
# then open http://localhost:3001, or the URL printed by the command
```

### Option A2: One-line install (Windows PowerShell)

Run PowerShell as a normal user, then execute:

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/OpenBMB/PilotDeck/main/install.ps1 | iex"
```

The PowerShell installer uses Windows-native paths under `%USERPROFILE%\.pilotdeck`, checks Node.js 22.13+ with `node:sqlite`, installs missing prerequisites with `winget` when available, builds PilotDeck, and creates a `pilotdeck.cmd` launcher in `%USERPROFILE%\.pilotdeck\bin`. Git LFS media assets are optional for the core app; if Git LFS is unavailable or times out, the installer continues without demo videos/GIFs.

After installation, the script starts PilotDeck and prints the UI URL, usually `http://localhost:3001`. It does not automatically open a browser, so copy that URL into your browser to finish onboarding (provider + API key). You can also open it from PowerShell:

```powershell
Start-Process http://localhost:3001
```

If this is your first install, open a new PowerShell window after the script updates your user `PATH`, then run:

```powershell
pilotdeck # starts the server at http://localhost:3001
pilotdeck status # check runtime status
```

To open PilotDeck again later, run `pilotdeck` from a new PowerShell window, then open the printed URL in your browser. If `pilotdeck` is not yet on `PATH`, run the launcher directly:

```powershell
& "$HOME\.pilotdeck\bin\pilotdeck.cmd"
```

#### Windows PowerShell FAQ

**`npm.ps1` cannot be loaded because running scripts is disabled**

This can still happen when you run development commands such as `npm run dev` directly in Windows PowerShell for the first time. PowerShell may resolve `npm` to `npm.ps1`, and the default execution policy can block that shim.

Fix it once for the current user, then reopen PowerShell:

```powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```

If you do not want to change the user policy, run the cmd shim explicitly instead:

```powershell
npm.cmd run dev
```

**Native dependency build errors (`node-gyp`, `MSBuild`, or Python not found)**

The installer normally uses prebuilt packages for native dependencies such as `node-pty`, `sqlite3`, `better-sqlite3`, and `sharp`. On a fresh Windows machine, if npm cannot download a matching prebuild and falls back to compiling from source, install Visual Studio Build Tools with the C++ workload and Python, then rerun the installer.

### Option B: From source (for developers)

**1. Clone and install dependencies**
Expand Down
60 changes: 59 additions & 1 deletion README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -290,7 +290,7 @@ https://github.com/user-attachments/assets/a7245467-ee3c-4939-a055-c56576ac56d1

## 📦 安装与快速开始

我们提供了 macOS/Linux 下的一键安装脚本,以及适合开发者的源码启动方式。
我们提供了 macOS/Linux 与 Windows PowerShell 下的一键安装脚本,以及适合开发者的源码启动方式。

### 方式一:一键安装 (推荐, macOS/Linux)

Expand All @@ -305,6 +305,64 @@ pilotdeck # 在 http://localhost:3001 启动服务
pilotdeck status # 查看运行状态
```

之后如果想在 macOS / Linux 上再次打开 PilotDeck,请在终端运行 `pilotdeck`,然后在浏览器中打开终端打印的地址。如果当前 shell 还没有刷新 PATH,请新开一个终端,或先 source 对应的 shell 配置文件。

```bash
pilotdeck
# 然后打开 http://localhost:3001,或命令打印的地址
```

### 方式一补充:一键安装 (Windows PowerShell)

在普通用户 PowerShell 中执行:

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/OpenBMB/PilotDeck/main/install.ps1 | iex"
```

PowerShell 安装脚本会使用 `%USERPROFILE%\.pilotdeck` 下的 Windows 原生路径,检查 Node.js 22.13+ 与 `node:sqlite`,在可用时通过 `winget` 安装缺失依赖,构建 PilotDeck,并在 `%USERPROFILE%\.pilotdeck\bin` 生成 `pilotdeck.cmd` 启动器。Git LFS 媒体资源对核心功能是可选的;如果 Git LFS 不可用或下载超时,安装脚本会跳过演示视频/GIF 并继续安装。

安装完成后,脚本会启动 PilotDeck 并打印 UI 地址,通常是 `http://localhost:3001`。脚本不会自动打开浏览器,请把该地址复制到浏览器中完成初始化配置(Provider + API key)。也可以在 PowerShell 中打开:

```powershell
Start-Process http://localhost:3001
```

如果脚本刚刚更新了用户 `PATH`,请新开一个 PowerShell 窗口后运行:

```powershell
pilotdeck # 在 http://localhost:3001 启动服务
pilotdeck status # 查看运行状态
```

之后如果想再次打开 PilotDeck,请在新的 PowerShell 窗口运行 `pilotdeck`,然后在浏览器中打开终端打印的地址。如果当前窗口还识别不到 `pilotdeck`,可以直接运行启动器:

```powershell
& "$HOME\.pilotdeck\bin\pilotdeck.cmd"
```

#### Windows PowerShell FAQ

**首次运行 `npm run dev` 报错:`npm.ps1` 因系统禁止运行脚本而无法加载**

这个问题现在仍可能出现:当你在 Windows PowerShell 中直接运行 `npm run dev` 等开发命令时,PowerShell 可能优先解析到 `npm.ps1`,而默认执行策略会阻止该脚本。

对当前用户设置一次执行策略,然后重新打开 PowerShell:

```powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```

如果不想修改用户执行策略,也可以显式调用 cmd shim:

```powershell
npm.cmd run dev
```

**原生依赖构建失败(提示 `node-gyp`、`MSBuild` 或 Python 缺失)**

安装脚本通常会使用 `node-pty`、`sqlite3`、`better-sqlite3`、`sharp` 等原生依赖的预编译包。全新的 Windows 机器上,如果 npm 无法下载匹配的预编译包并回退到源码编译,请先安装带 C++ 工作负载的 Visual Studio Build Tools 和 Python,然后重新运行安装脚本。

### 方式二:源码启动 (适合开发者)

**1. 克隆代码与安装依赖**
Expand Down
Loading