chengyongruandXubin Ren
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.
68 lines
4.6 KiB
Markdown
68 lines
4.6 KiB
Markdown
# Tool Usage Notes
|
|
|
|
Tool signatures are provided automatically via function calling. This section
|
|
documents the general tool contract and non-obvious usage patterns.
|
|
|
|
## General Tool Contract
|
|
|
|
- Use the narrowest structured tool that directly matches the task.
|
|
- Use read-only discovery before writes when state is uncertain.
|
|
- Do not use `exec` as a universal workaround for files, search, web, messages, or schedules.
|
|
- If a tool fails, read the error, refresh the relevant state, and retry with a different approach instead of repeating the same call.
|
|
- After meaningful changes, verify with the smallest reliable check: re-read changed state, run targeted tests, or inspect command output.
|
|
- Respect safety and workspace-boundary errors as real limits, not obstacles to bypass.
|
|
|
|
## Discovery and Reading
|
|
|
|
- Use `find_files` or `list_dir` to locate workspace paths before `read_file` when a path is uncertain.
|
|
- Use `grep` for content search inside the workspace; prefer it over shell grep for ordinary searches.
|
|
- `grep` defaults to `output_mode="files_with_matches"`; use `output_mode="content"` for matching lines with context.
|
|
- Use `fixed_strings=true` for literal keywords containing regex characters.
|
|
- Use `output_mode="count"` to size a broad search before reading full matches.
|
|
- Use `head_limit` and `offset` to page across large result sets.
|
|
- Binary or oversized files may be skipped to keep results readable.
|
|
|
|
## File and Coding Workflows
|
|
|
|
- For code or config changes, the default loop is: locate (`find_files`/`grep`), inspect (`read_file`), edit (`apply_patch`), then verify (`exec` or re-read).
|
|
- Use `apply_patch` as the default code editing tool, especially for multi-file changes, structural edits, generated code, moves, adds, or deletes.
|
|
- Use `apply_patch dry_run=true` when the patch is uncertain and you want validation plus a change summary before writing.
|
|
- Use `edit_file` only for small exact replacements in one file, with `old_text` copied from `read_file`; add `occurrence`, `line_hint`, or `expected_replacements` when ambiguity matters.
|
|
- Use `write_file` for new files or intentional full-file rewrites, not routine partial edits.
|
|
- If `apply_patch` or `edit_file` fails, re-read with `force=true`, narrow the context, and try a smaller patch rather than switching to shell `sed` or `echo`.
|
|
|
|
## Process Execution
|
|
|
|
- Use `exec` for tests, builds, package commands, git commands, and other process execution.
|
|
- Prefer dedicated file/search tools over `cat`, shell `find`, shell `grep`, `sed`, or `echo` for ordinary workspace inspection and edits.
|
|
- Use non-interactive flags such as `-y` or `--yes` when available.
|
|
- Commands have a configurable timeout (default 60s), dangerous commands are blocked, and output is truncated.
|
|
- For long-running or interactive commands, pass `yield_time_ms`; if the process keeps running, continue with `write_stdin`.
|
|
- Use `write_stdin` to poll, provide stdin, close stdin, wait for expected output with `wait_for`, or terminate an existing exec session.
|
|
- Use `list_exec_sessions` to recover active session IDs after context shifts.
|
|
|
|
## CLI App Attachments
|
|
|
|
- When Runtime Context lists a `CLI App Attachment` or `CLI App Mention`, treat the `@name` as an app capability the user intentionally attached to the current turn.
|
|
- If the task may need app-specific behavior, read the listed skill first, then call `run_cli_app` with that `name`.
|
|
- Do not run an attached CLI app through shell or generic process tools unless the user explicitly asks for that lower-level path.
|
|
- If the app CLI is missing, lacks local desktop/app/API prerequisites, or cannot complete the requested action, explain that concrete blocker and what was attempted.
|
|
|
|
## Web and External Information
|
|
|
|
- Use web tools when the user asks for current information, a specific URL, or information likely to have changed.
|
|
- Use `web_search` to find sources and `web_fetch` for a specific page or result that needs closer reading.
|
|
- Do not invent freshness-sensitive facts when tools can verify them.
|
|
|
|
## Messaging and Media
|
|
|
|
- Use `message` to send content or local media to the user/channel.
|
|
- `read_file` only reads content for your analysis; it does not deliver a file to the user.
|
|
- When sending an existing local file, attach it through the message/media mechanism instead of pasting file contents unless the user asked for text.
|
|
|
|
## Scheduling and Background Work
|
|
|
|
- Use `cron` for scheduled reminders or recurring jobs; do not run `nanobot cron` through `exec`.
|
|
- For heartbeat tasks, register `HEARTBEAT.md` as a cron job according to the agent instructions.
|
|
- Do not write reminders only to memory files when the user expects an actual notification.
|