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
parent 56ce18167e
commit 4a58b83acc
31 changed files with 3491 additions and 454 deletions
@@ -0,0 +1,163 @@
+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!`""
@@ -0,0 +1,129 @@
+#!/bin/sh
+set -eu
+
+package="nanobot-ai"
+main_source="https://github.com/HKUDS/nanobot/archive/refs/heads/main.zip"
+install_target="$package"
+install_source="PyPI"
+dry_run="0"
+
+info() {
+  printf '%s\n' "$*"
+}
+
+fail() {
+  printf 'Error: %s\n' "$*" >&2
+  exit 1
+}
+
+install_failure_hint() {
+  printf '%s\n' "Error: pip could not install nanobot from $install_source." >&2
+  printf '%s\n' "If pip mentioned externally-managed-environment, install in a virtual environment or use uv/pipx." >&2
+  printf '%s\n' "You can also run manually:" >&2
+  printf '  %s\n' "$python_bin -m pip install --upgrade $install_target" >&2
+  printf '%s\n' "Then start setup with:" >&2
+  printf '  %s\n' "$python_bin -m nanobot onboard --wizard" >&2
+  exit 1
+}
+
+usage() {
+  cat <<'EOF'
+Usage: install.sh [--dev] [--dry-run]
+
+By default this installs or upgrades nanobot-ai from PyPI.
+Use --dev to install from the current main branch on GitHub.
+Use --dry-run to print what would happen without installing or starting the wizard.
+EOF
+}
+
+find_python() {
+  for candidate in python3 python; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+      if "$candidate" - <<'PY' >/dev/null 2>&1
+import sys
+raise SystemExit(0 if sys.version_info >= (3, 11) else 1)
+PY
+      then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+    fi
+  done
+  return 1
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --dev)
+      install_target="$main_source"
+      install_source="GitHub main"
+      ;;
+    --dry-run)
+      dry_run="1"
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      fail "Unknown option: $1"
+      ;;
+  esac
+  shift
+done
+
+python_bin="${PYTHON:-}"
+
+if [ -n "$python_bin" ]; then
+  command -v "$python_bin" >/dev/null 2>&1 || fail "PYTHON=$python_bin was not found"
+  "$python_bin" - <<'PY' >/dev/null 2>&1 || fail "nanobot requires Python 3.11 or newer"
+import sys
+raise SystemExit(0 if sys.version_info >= (3, 11) else 1)
+PY
+else
+  python_bin="$(find_python)" || fail "Python 3.11 or newer was not found. Install Python first, then rerun this command."
+fi
+
+info "Using Python: $("$python_bin" --version 2>&1)"
+
+if ! "$python_bin" -m pip --version >/dev/null 2>&1; then
+  if [ "$dry_run" = "1" ]; then
+    info "Dry run: pip was not found. Install would try: $python_bin -m ensurepip --upgrade"
+  else
+    info "pip was not found for this Python. Trying ensurepip..."
+    "$python_bin" -m ensurepip --upgrade >/dev/null 2>&1 || fail "pip is not available. Install pip for $python_bin, then rerun this command."
+  fi
+fi
+
+if [ "$dry_run" = "1" ]; then
+  info "Dry run: would install or upgrade nanobot from $install_source."
+  info "Dry run: would run: $python_bin -m pip install --upgrade $install_target"
+  info "Dry run: if that fails because system site-packages are not writable, would retry: $python_bin -m pip install --user --upgrade $install_target"
+  if [ "${NANOBOT_SKIP_WIZARD:-}" = "1" ]; then
+    info "Dry run: would skip setup wizard because NANOBOT_SKIP_WIZARD=1."
+  else
+    info "Dry run: would run: $python_bin -m nanobot onboard --wizard"
+  fi
+  info "Dry run: no changes made."
+  exit 0
+fi
+
+info "Installing or upgrading nanobot from $install_source..."
+if ! "$python_bin" -m pip install --upgrade "$install_target"; then
+  info "Install failed. Retrying as a user install..."
+  "$python_bin" -m pip install --user --upgrade "$install_target" || install_failure_hint
+fi
+
+info "Installed nanobot:"
+"$python_bin" -m nanobot --version
+
+if [ "${NANOBOT_SKIP_WIZARD:-}" = "1" ]; then
+  info "Skipping setup wizard because NANOBOT_SKIP_WIZARD=1."
+  info "Run this later: $python_bin -m nanobot onboard --wizard"
+  exit 0
+fi
+
+info "Starting setup wizard..."
+"$python_bin" -m nanobot onboard --wizard
+
+info "Done. Try: $python_bin -m nanobot agent -m \"Hello!\""