mirror of https://github.com/HKUDS/nanobot.git synced 2026-06-15 07:14:08 +00:00

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

4.1 KiB

Raw Blame History

Desktop Development Guide

This guide is for GitHub contributors who want to change the desktop app. If you are using nanobot rather than developing it, the important bit is simpler: desktop runs the local engine for you and shows the same chat, settings, apps, skills, and workspace UI as the browser WebUI.

desktop is the native host for the shared nanobot WebUI. It is not a fork of the WebUI, and it should not grow a second copy of product UI.

The healthy mental model is:

nanobot core  -> agent runtime, gateway, providers, tools, memory
webui         -> shared product UI and runtime-aware UI
desktop       -> native host, engine lifecycle, secure host capabilities

Development Workflow

Use this when developing from a source checkout.

Run the shared WebUI dev server:

cd desktop
bun run dev:webui

Run the Electron host in another terminal:

cd desktop
bun run dev:app

In development, Electron loads http://127.0.0.1:5173, so changes under webui/src hot reload. Changes under desktop/src require restarting dev:app.

For source checkouts, the host starts the engine with local python3 and injects the repository root into PYTHONPATH. This means Python changes under nanobot/ are picked up from the current checkout.

Where Code Goes

Use this table before adding a desktop feature:

Change	Location
Agent behavior, tools, providers, memory, config schema	`nanobot/`
Shared chat UI, settings UI, reusable product UI	`webui/`
Runtime-aware UI rows, such as native engine status or open logs buttons	`webui/`
The implementation behind native capabilities	`desktop/src/main.ts`
The trusted renderer bridge contract	`desktop/src/preload.cts` and `desktop/docs/host-contract.md`
Electron window, app protocol, native menus, lifecycle, packaging	`desktop/src` and `desktop/package.json`
WebSocket-over-Unix-socket bridge	`desktop/src/unixWebSocket.ts`
Bundled Python runtime preparation	`desktop/scripts/prepare-engine.mjs`

For example, if desktop Settings needs an "Open logs" button, the button belongs in the shared WebUI settings page because it is product UI. The actual filesystem operation belongs in the desktop host and is exposed through window.nanobotHost.

Host Contract

The shared WebUI talks to desktop through window.nanobotHost. WebUI code may check for host capabilities, but it must not import Electron, Node.js modules, or desktop source files.

Prefer capability-driven UI:

if host can open logs -> show Open logs
if host can restart engine -> show Restart engine

Avoid platform-driven UI:

if desktop -> run Electron-specific logic in WebUI

This keeps the WebUI usable in browsers and leaves room for future native hosts without rewriting product screens.

Adding A Desktop Feature

Before implementing, answer these questions:

Is this product UI or a native capability?
Can the WebUI express it through a generic capability instead of a desktop flag?
Does the host API validate trusted origins and accepted URL schemes?
Does browser WebUI still work when window.nanobotHost is missing?
Does the engine behavior belong in nanobot core instead of Electron?
Does packaged mode use app data for user state instead of app resources?

Anti-Patterns

Do not copy or fork webui/src into desktop/.
Do not import Electron or Node.js modules from webui/src.
Do not add provider-specific onboarding screens to desktop/.
Do not duplicate WebUI settings or login flows in Electron-owned HTML.
Do not make desktop/src/main.ts own agent behavior.
Do not commit desktop/node_modules, desktop/build, desktop/dist, DMGs, or desktop/resources/nanobot-engine.

Release Shape

Release builds assemble three existing parts:

the shared WebUI build from nanobot/web/dist,
the Python engine prepared under desktop/resources/nanobot-engine,
the Electron host compiled from desktop/src.

User config, logs, sessions, workspace state, and the default workspace live in the platform app data directory, not inside the app bundle.

4.1 KiB Raw Blame History