mirror of
https://github.com/HKUDS/nanobot.git
synced 2026-06-13 22:34:06 +00:00
fe2af64e04
Remove standalone nanobot/heartbeat/ service and replace it with an auto-registered system cron job on gateway startup. Key behaviors preserved: - HeartbeatConfig (enabled, interval_s, keep_recent_messages) remains in GatewayConfig for backward compatibility. - On startup, if enabled, a system cron job "heartbeat" is registered with schedule derived from interval_s. - HEARTBEAT.md is checked on each tick; empty/template-identical files skip to avoid wasting LLM calls. - Post-run evaluate_response and session history truncation (keep_recent_messages) are retained. - Delivery target selection, deliverable filtering, and preamble guidance are preserved. Files removed: - nanobot/heartbeat/__init__.py - nanobot/heartbeat/service.py - tests/heartbeat/* - tests/agent/test_heartbeat_service.py Templates and docs updated to reflect cron-based usage.
41 lines
2.4 KiB
Markdown
41 lines
2.4 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
|
|
|
|
`config/loader.py` resolves `${VAR}` patterns in `config.json` at load time. This is **not** a shell-like default-value syntax. If the environment variable is missing, `load_config` raises `ValueError` and the agent falls back to default configuration.
|
|
|
|
Example valid usage:
|
|
```json
|
|
{ "providers": { "openrouter": { "apiKey": "${OPENROUTER_KEY}" } } }
|
|
```
|
|
|
|
## Windows Compatibility
|
|
|
|
nanobot explicitly supports Windows. Key differences to keep in mind:
|
|
- `ExecTool` uses `cmd /c` on Windows instead of `sh -c` (`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.
|