nanobot/scripts/install.ps1
chengyongru 4a58b83acc
docs: make onboarding friendlier for beginners (#4177)
* docs: make onboarding friendlier for beginners

* docs: build clearer documentation paths

Maintainer edit: turn the onboarding follow-up into a layered docs structure for first-time setup, provider selection, troubleshooting, CLI reference, and source-level architecture. This keeps quick start focused while giving advanced users precise reference paths.

* docs: render architecture flow with mermaid

Maintainer edit: replace the ASCII architecture sketch with a GitHub-rendered Mermaid flowchart so the core runtime path is easier to scan in the PR and README docs.

* docs: recommend model presets for model config

Maintainer edit: make named modelPresets the primary model configuration path and expand fallback preset examples so string fallbacks are clearly preset names, not raw model IDs.

* docs: document api base urls and langfuse setup

Maintainer edit: explain when users need apiBase/base URL in quick start and provider docs, and add Langfuse tracing setup with troubleshooting links.

* docs: use python module pip consistently

Maintainer edit: keep install commands tied to the active Python interpreter by using python -m pip in the Azure optional dependency notes too.

* docs: add non-technical getting started path

Maintainer edit: add a wizard-first guide for users without terminal or JSON background, including a text TUI menu example and links from the main docs entrypoints.

* docs: avoid hard-wrapped prose in user docs

Maintainer edit: unwrap ordinary prose across user-facing documentation while preserving markdown structure, code blocks, tables, lists, and prompt/template files.

* docs: keep desktop list continuations nested

Maintainer edit: preserve list nesting after unwrapping prose in the desktop WebUI sync guide.

* docs: add one-command installer

Maintainer edit: add auditable macOS/Linux and Windows install scripts that install nanobot-ai and start the onboarding wizard, then document the commands in the main onboarding entrypoints.

* docs: add installer dry run mode

Maintainer edit: add --dry-run to the one-command installer scripts so users can preview Python detection, install source, pip command, and wizard behavior without changing their environment.

* docs: clean installer error output

Maintainer edit: make PowerShell installer failures print a concise Error: message instead of Write-Error call-site details.

* docs: add provider setup cookbook

Maintainer edit: add pasteable provider recipes for common hosted, local, fallback, runtime switching, and Langfuse setups, then link the cookbook from onboarding and troubleshooting entrypoints.

* docs: address review feedback

* docs: clarify reader paths

* docs: explain terminal basics for beginners

* docs: clarify wizard navigation

* docs: avoid duplicate onboarding steps

* docs: add setup status check

* docs: explain status output

* docs: remove provider recommendation wording

* docs: explain status diagnostics

* docs: reduce hard-wrapped guidance

* docs: migrate config examples to presets

* docs: clarify python command fallbacks

* docs: improve installer failure recovery

* docs: expand install troubleshooting

* docs: cover installer download failures

* docs: put stable install paths first

* docs: add bundled webui quick path

* docs: clarify provider-neutral setup

* docs: clarify gateway setup for chat surfaces

* docs: improve docs navigation paths

* docs: add configuration quick jump

* docs: clarify provider secret variables

* chore: request PR review acknowledgement

Empty commit: please read the PR review comments and reply on the PR to confirm that you have received them.

This commit intentionally changes no files; it exists only to notify the remote Codex run so it can end its active goal.

* docs: add README start here guide

* docs: avoid provider recommendation wording

* docs: guide next steps after first reply

* docs: explain merging JSON snippets

* docs: add CLI command chooser

* docs: add configuration task map

* docs: add deployment readiness guide

* docs: simplify WebUI entry paths

* docs: add provider recipe chooser

* docs: fix provider factual references

Update OpenRouter and LongCat model examples, align Bedrock guidance, and make fallback snippets schema-valid.

Also correct group policy wording and image-generation provider lists to match the current code.

* fix: keep PowerShell installer from closing caller shell

* docs: mention self-guided configuration
2026-06-10 00:36:22 +08:00

164 lines
4.8 KiB
PowerShell

param(
[switch]$Dev,
[switch]$DryRun,
[Parameter(ValueFromRemainingArguments = $true)]
[string[]]$RemainingArgs
)
$ErrorActionPreference = "Stop"
$Package = "nanobot-ai"
$MainSource = "https://github.com/HKUDS/nanobot/archive/refs/heads/main.zip"
$InstallTarget = $Package
$InstallSource = "PyPI"
function Write-Info {
param([string]$Message)
Write-Host $Message
}
function Fail {
param([string]$Message)
throw "Error: $Message"
}
function Show-InstallFailureHint {
[Console]::Error.WriteLine("Error: pip could not install nanobot from $InstallSource.")
[Console]::Error.WriteLine("If pip mentioned externally-managed-environment, install in a virtual environment or use uv/pipx.")
[Console]::Error.WriteLine("You can also run manually:")
[Console]::Error.WriteLine(" $Python -m pip install --upgrade $InstallTarget")
[Console]::Error.WriteLine("Then start setup with:")
[Console]::Error.WriteLine(" $Python -m nanobot onboard --wizard")
throw "pip could not install nanobot from $InstallSource"
}
function Show-Usage {
Write-Host "Usage: install.ps1 [-Dev|--dev] [-DryRun|--dry-run]"
Write-Host ""
Write-Host "By default this installs or upgrades nanobot-ai from PyPI."
Write-Host "Use --dev to install from the current main branch on GitHub."
Write-Host "Use --dry-run to print what would happen without installing or starting the wizard."
}
function Test-Python {
param([string]$Command)
try {
& $Command -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)" *> $null
return $LASTEXITCODE -eq 0
} catch {
return $false
}
}
function Find-Python {
if ($env:PYTHON) {
if (Get-Command $env:PYTHON -ErrorAction SilentlyContinue) {
if (Test-Python $env:PYTHON) {
return $env:PYTHON
}
Fail "PYTHON=$env:PYTHON is not Python 3.11 or newer."
}
Fail "PYTHON=$env:PYTHON was not found."
}
foreach ($Candidate in @("python", "py")) {
if (Get-Command $Candidate -ErrorAction SilentlyContinue) {
if (Test-Python $Candidate) {
return $Candidate
}
}
}
Fail "Python 3.11 or newer was not found. Install Python first, then rerun this command."
}
foreach ($Arg in $RemainingArgs) {
switch ($Arg) {
"--dev" {
$Dev = $true
}
"--dry-run" {
$DryRun = $true
}
"-h" {
Show-Usage
return
}
"--help" {
Show-Usage
return
}
default {
Fail "Unknown option: $Arg"
}
}
}
if ($Dev) {
$InstallTarget = $MainSource
$InstallSource = "GitHub main"
}
$Python = Find-Python
$Version = & $Python --version
Write-Info "Using Python: $Version"
try {
& $Python -m pip --version *> $null
} catch {}
if ($LASTEXITCODE -ne 0) {
if ($DryRun) {
Write-Info "Dry run: pip was not found. Install would try: $Python -m ensurepip --upgrade"
} else {
Write-Info "pip was not found for this Python. Trying ensurepip..."
& $Python -m ensurepip --upgrade *> $null
if ($LASTEXITCODE -ne 0) {
Fail "pip is not available. Install pip for $Python, then rerun this command."
}
}
}
if ($DryRun) {
Write-Info "Dry run: would install or upgrade nanobot from $InstallSource."
Write-Info "Dry run: would run: $Python -m pip install --upgrade $InstallTarget"
Write-Info "Dry run: if that fails because system site-packages are not writable, would retry: $Python -m pip install --user --upgrade $InstallTarget"
if ($env:NANOBOT_SKIP_WIZARD -eq "1") {
Write-Info "Dry run: would skip setup wizard because NANOBOT_SKIP_WIZARD=1."
} else {
Write-Info "Dry run: would run: $Python -m nanobot onboard --wizard"
}
Write-Info "Dry run: no changes made."
return
}
Write-Info "Installing or upgrading nanobot from $InstallSource..."
& $Python -m pip install --upgrade $InstallTarget
if ($LASTEXITCODE -ne 0) {
Write-Info "Install failed. Retrying as a user install..."
& $Python -m pip install --user --upgrade $InstallTarget
if ($LASTEXITCODE -ne 0) {
Show-InstallFailureHint
}
}
Write-Info "Installed nanobot:"
& $Python -m nanobot --version
if ($LASTEXITCODE -ne 0) {
Fail "nanobot was installed, but the command could not be started."
}
if ($env:NANOBOT_SKIP_WIZARD -eq "1") {
Write-Info "Skipping setup wizard because NANOBOT_SKIP_WIZARD=1."
Write-Info "Run this later: $Python -m nanobot onboard --wizard"
return
}
Write-Info "Starting setup wizard..."
& $Python -m nanobot onboard --wizard
if ($LASTEXITCODE -ne 0) {
Fail "Setup wizard did not complete."
}
Write-Info "Done. Try: $Python -m nanobot agent -m `"Hello!`""