mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-08-06 17:38:35 +00:00
41 lines
2.6 KiB
Markdown
41 lines
2.6 KiB
Markdown
# Common Gotchas
|
|
|
|
## Do not use `ruff format`
|
|
|
|
`CONTRIBUTING.md` mentions `ruff format`, but **do not run it** — it destroys git blame history. Only `ruff check` should be used.
|
|
|
|
## Config `${VAR}` References
|
|
|
|
`load_config()` and `FileConfigRepository.load_raw()` preserve `${VAR}` patterns so Settings can safely edit and save the persisted representation. Runtime entry points use `load_effective_config()` / `load_effective()` to resolve them in an isolated snapshot. This is **not** a shell-like default-value syntax. If a referenced variable is missing, effective loading raises `ValueError`.
|
|
|
|
Example valid usage:
|
|
```json
|
|
{ "providers": { "openrouter": { "apiKey": "${OPENROUTER_KEY}" } } }
|
|
```
|
|
|
|
## Windows Compatibility
|
|
|
|
nanobot explicitly supports Windows. Key differences to keep in mind:
|
|
- `ExecTool` defaults to PowerShell on Windows (`pwsh` when available, otherwise Windows PowerShell); pass `shell="cmd"` for cmd.exe syntax or cmd built-ins (`shell.py`).
|
|
- `cli/commands.py` forces `sys.stdout`/`stderr` to UTF-8 on startup to handle emoji and multilingual input.
|
|
- MCP stdio server commands are normalized for Windows path separators (`mcp.py`).
|
|
- Always use `pathlib.Path` for path manipulation; do not assume `/` separators.
|
|
|
|
## Prompt Templates
|
|
|
|
Agent system prompts and scenario-specific instructions live in `nanobot/templates/` as Jinja2 markdown files (`identity.md`, `platform_policy.md`, `HEARTBEAT.md`, `SOUL.md`, etc.). Changing these files alters agent behavior as directly as changing Python code. They are loaded by `utils/prompt_templates.py`.
|
|
|
|
Tool descriptions, skills, and replayed session history also shape model behavior. Treat changes to those surfaces like runtime code: keep them narrow, add a focused regression test when possible, and avoid teaching the model to repeat internal markers, local paths, or tool-call text.
|
|
|
|
## Context Pollution Persists
|
|
|
|
Anything written into memory, session history, or prompt inputs can be replayed into future LLM calls. Metadata such as timestamps, local media paths, tool-call echoes, and raw fallback dumps must be bounded and sanitized before they become examples for the model to imitate.
|
|
|
|
## Skills as Extension Point
|
|
|
|
Built-in skills live in `nanobot/skills/` (markdown + YAML frontmatter format). Agent capabilities that are "know-how" rather than code should be added as skills, not hardcoded into the agent loop. External skills can be published to and installed from ClawHub.
|
|
|
|
## Atomic Session Writes
|
|
|
|
`agent/memory.py` writes `history.jsonl` atomically (temp file + fsync + rename + directory fsync). This guarantees durability across crashes. Do not replace this with a plain `open(..., "w")` write.
|