mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-06-15 07:14:08 +00:00
4a58b83acc
* 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
102 lines
4.1 KiB
Markdown
102 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
cd desktop
|
|
bun run dev:webui
|
|
```
|
|
|
|
Run the Electron host in another terminal:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```text
|
|
if host can open logs -> show Open logs
|
|
if host can restart engine -> show Restart engine
|
|
```
|
|
|
|
Avoid platform-driven UI:
|
|
|
|
```text
|
|
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:
|
|
|
|
1. Is this product UI or a native capability?
|
|
2. Can the WebUI express it through a generic capability instead of a desktop flag?
|
|
3. Does the host API validate trusted origins and accepted URL schemes?
|
|
4. Does browser WebUI still work when `window.nanobotHost` is missing?
|
|
5. Does the engine behavior belong in nanobot core instead of Electron?
|
|
6. 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:
|
|
|
|
1. the shared WebUI build from `nanobot/web/dist`,
|
|
2. the Python engine prepared under `desktop/resources/nanobot-engine`,
|
|
3. 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.
|