From 0dda2b23e632748f1387f024bec22af048973670 Mon Sep 17 00:00:00 2001 From: who96 <825265100@qq.com> Date: Sun, 15 Mar 2026 15:24:21 +0800 Subject: [PATCH 1/4] fix(heartbeat): inject current datetime into Phase 1 prompt Phase 1 _decide() now includes "Current date/time: YYYY-MM-DD HH:MM UTC" in the user prompt and instructs the LLM to use it for time-aware scheduling. Without this, the LLM defaults to 'run' for any task description regardless of whether it is actually due, defeating Phase 1's pre-screening purpose. Closes #1929 --- nanobot/heartbeat/service.py | 12 ++++++++- tests/test_heartbeat_service.py | 44 +++++++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 1 deletion(-) diff --git a/nanobot/heartbeat/service.py b/nanobot/heartbeat/service.py index 2242802..2b8db9d 100644 --- a/nanobot/heartbeat/service.py +++ b/nanobot/heartbeat/service.py @@ -3,6 +3,7 @@ from __future__ import annotations import asyncio +from datetime import datetime, timezone from pathlib import Path from typing import TYPE_CHECKING, Any, Callable, Coroutine @@ -87,10 +88,19 @@ class HeartbeatService: Returns (action, tasks) where action is 'skip' or 'run'. """ + now_str = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC") + response = await self.provider.chat_with_retry( messages=[ - {"role": "system", "content": "You are a heartbeat agent. Call the heartbeat tool to report your decision."}, + {"role": "system", "content": ( + "You are a heartbeat agent. Call the heartbeat tool to report your decision. " + "The current date/time is provided so you can evaluate time-based conditions. " + "Choose 'run' if there are active tasks to execute. " + "Choose 'skip' if the file has no actionable tasks, if blocking conditions " + "are not yet met, or if tasks are scheduled for a future time that has not arrived yet." + )}, {"role": "user", "content": ( + f"Current date/time: {now_str}\n\n" "Review the following HEARTBEAT.md and decide whether there are active tasks.\n\n" f"{content}" )}, diff --git a/tests/test_heartbeat_service.py b/tests/test_heartbeat_service.py index 2a6b20e..e330d2b 100644 --- a/tests/test_heartbeat_service.py +++ b/tests/test_heartbeat_service.py @@ -250,3 +250,47 @@ async def test_decide_retries_transient_error_then_succeeds(tmp_path, monkeypatc assert tasks == "check open tasks" assert provider.calls == 2 assert delays == [1] + + +@pytest.mark.asyncio +async def test_decide_prompt_includes_current_datetime(tmp_path) -> None: + """Phase 1 prompt must contain the current date/time so the LLM can judge task urgency.""" + + captured_messages: list[dict] = [] + + class CapturingProvider(LLMProvider): + async def chat(self, *, messages=None, **kwargs) -> LLMResponse: + if messages: + captured_messages.extend(messages) + return LLMResponse( + content="", + tool_calls=[ + ToolCallRequest( + id="hb_1", name="heartbeat", + arguments={"action": "skip"}, + ) + ], + ) + + def get_default_model(self) -> str: + return "test-model" + + service = HeartbeatService( + workspace=tmp_path, + provider=CapturingProvider(), + model="test-model", + ) + + await service._decide("- [ ] check servers at 10:00 UTC") + + # System prompt should mention date/time awareness + system_msg = captured_messages[0] + assert system_msg["role"] == "system" + assert "date/time" in system_msg["content"].lower() + + # User prompt should contain a UTC timestamp + user_msg = captured_messages[1] + assert user_msg["role"] == "user" + assert "Current date/time:" in user_msg["content"] + assert "UTC" in user_msg["content"] + From 5d1528a5f3256617a6a756890623c9407400cd0e Mon Sep 17 00:00:00 2001 From: Xubin Ren Date: Mon, 16 Mar 2026 02:47:45 +0000 Subject: [PATCH 2/4] fix(heartbeat): inject shared current time context into phase 1 --- nanobot/agent/context.py | 8 +++----- nanobot/heartbeat/service.py | 13 +++---------- nanobot/utils/helpers.py | 8 ++++++++ tests/test_heartbeat_service.py | 13 +++---------- 4 files changed, 17 insertions(+), 25 deletions(-) diff --git a/nanobot/agent/context.py b/nanobot/agent/context.py index e47fcb8..2e36ed3 100644 --- a/nanobot/agent/context.py +++ b/nanobot/agent/context.py @@ -3,11 +3,11 @@ import base64 import mimetypes import platform -import time -from datetime import datetime from pathlib import Path from typing import Any +from nanobot.utils.helpers import current_time_str + from nanobot.agent.memory import MemoryStore from nanobot.agent.skills import SkillsLoader from nanobot.utils.helpers import build_assistant_message, detect_image_mime @@ -99,9 +99,7 @@ Reply directly with text for conversations. Only use the 'message' tool to send @staticmethod def _build_runtime_context(channel: str | None, chat_id: str | None) -> str: """Build untrusted runtime metadata block for injection before the user message.""" - now = datetime.now().strftime("%Y-%m-%d %H:%M (%A)") - tz = time.strftime("%Z") or "UTC" - lines = [f"Current Time: {now} ({tz})"] + lines = [f"Current Time: {current_time_str()}"] if channel and chat_id: lines += [f"Channel: {channel}", f"Chat ID: {chat_id}"] return ContextBuilder._RUNTIME_CONTEXT_TAG + "\n" + "\n".join(lines) diff --git a/nanobot/heartbeat/service.py b/nanobot/heartbeat/service.py index 2b8db9d..7be81ff 100644 --- a/nanobot/heartbeat/service.py +++ b/nanobot/heartbeat/service.py @@ -3,7 +3,6 @@ from __future__ import annotations import asyncio -from datetime import datetime, timezone from pathlib import Path from typing import TYPE_CHECKING, Any, Callable, Coroutine @@ -88,19 +87,13 @@ class HeartbeatService: Returns (action, tasks) where action is 'skip' or 'run'. """ - now_str = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC") + from nanobot.utils.helpers import current_time_str response = await self.provider.chat_with_retry( messages=[ - {"role": "system", "content": ( - "You are a heartbeat agent. Call the heartbeat tool to report your decision. " - "The current date/time is provided so you can evaluate time-based conditions. " - "Choose 'run' if there are active tasks to execute. " - "Choose 'skip' if the file has no actionable tasks, if blocking conditions " - "are not yet met, or if tasks are scheduled for a future time that has not arrived yet." - )}, + {"role": "system", "content": "You are a heartbeat agent. Call the heartbeat tool to report your decision."}, {"role": "user", "content": ( - f"Current date/time: {now_str}\n\n" + f"Current Time: {current_time_str()}\n\n" "Review the following HEARTBEAT.md and decide whether there are active tasks.\n\n" f"{content}" )}, diff --git a/nanobot/utils/helpers.py b/nanobot/utils/helpers.py index 5ca06f4..d937b6e 100644 --- a/nanobot/utils/helpers.py +++ b/nanobot/utils/helpers.py @@ -2,6 +2,7 @@ import json import re +import time from datetime import datetime from pathlib import Path from typing import Any @@ -33,6 +34,13 @@ def timestamp() -> str: return datetime.now().isoformat() +def current_time_str() -> str: + """Human-readable current time with weekday and timezone, e.g. '2026-03-15 22:30 (Saturday) (CST)'.""" + now = datetime.now().strftime("%Y-%m-%d %H:%M (%A)") + tz = time.strftime("%Z") or "UTC" + return f"{now} ({tz})" + + _UNSAFE_CHARS = re.compile(r'[<>:"/\\|?*]') def safe_filename(name: str) -> str: diff --git a/tests/test_heartbeat_service.py b/tests/test_heartbeat_service.py index e330d2b..8f563cf 100644 --- a/tests/test_heartbeat_service.py +++ b/tests/test_heartbeat_service.py @@ -253,8 +253,8 @@ async def test_decide_retries_transient_error_then_succeeds(tmp_path, monkeypatc @pytest.mark.asyncio -async def test_decide_prompt_includes_current_datetime(tmp_path) -> None: - """Phase 1 prompt must contain the current date/time so the LLM can judge task urgency.""" +async def test_decide_prompt_includes_current_time(tmp_path) -> None: + """Phase 1 user prompt must contain current time so the LLM can judge task urgency.""" captured_messages: list[dict] = [] @@ -283,14 +283,7 @@ async def test_decide_prompt_includes_current_datetime(tmp_path) -> None: await service._decide("- [ ] check servers at 10:00 UTC") - # System prompt should mention date/time awareness - system_msg = captured_messages[0] - assert system_msg["role"] == "system" - assert "date/time" in system_msg["content"].lower() - - # User prompt should contain a UTC timestamp user_msg = captured_messages[1] assert user_msg["role"] == "user" - assert "Current date/time:" in user_msg["content"] - assert "UTC" in user_msg["content"] + assert "Current Time:" in user_msg["content"] From 5a220959afd7e497cb9e8a2bbfc9031433bc96a7 Mon Sep 17 00:00:00 2001 From: chengyongru <2755839590@qq.com> Date: Sun, 15 Mar 2026 02:30:09 +0800 Subject: [PATCH 3/4] docs: add branching strategy and CONTRIBUTING guide - Add CONTRIBUTING.md with detailed contribution guidelines - Add branching strategy section to README.md explaining main/nightly branches - Include maintainer information and development setup instructions --- CONTRIBUTING.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 9 +++++ 2 files changed, 100 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..626c8bb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,91 @@ +# Contributing to nanobot + +Thank you for your interest in contributing! This guide will help you get started. + +## Maintainers + +| Maintainer | Focus | +|------------|-------| +| [@re-bin](https://github.com/re-bin) | Project lead, `main` branch | +| [@chengyongru](https://github.com/chengyongru) | `nightly` branch, experimental features | + +## Branching Strategy + +nanobot uses a two-branch model to balance stability and innovation: + +| Branch | Purpose | Stability | +|--------|---------|-----------| +| `main` | Stable releases | Production-ready | +| `nightly` | Experimental features | May have bugs or breaking changes | + +### Which Branch Should I Target? + +**Target `nightly` if your PR includes:** + +- New features or functionality +- Refactoring that may affect existing behavior +- Changes to APIs or configuration + +**Target `main` if your PR includes:** + +- Bug fixes with no behavior changes +- Documentation improvements +- Minor tweaks that don't affect functionality + +**When in doubt, target `nightly`.** It's easier to cherry-pick stable changes to `main` than to revert unstable changes. + +### How Does Nightly Get Merged to Main? + +We don't merge the entire `nightly` branch. Instead, stable features are **cherry-picked** from `nightly` into individual PRs targeting `main`: + +``` +nightly ──┬── feature A (stable) ──► PR ──► main + ├── feature B (testing) + └── feature C (stable) ──► PR ──► main +``` + +This happens approximately **once a week**, but the timing depends on when features become stable enough. + +### Quick Summary + +| Your Change | Target Branch | +|-------------|---------------| +| New feature | `nightly` | +| Bug fix | `main` | +| Documentation | `main` | +| Refactoring | `nightly` | +| Unsure | `nightly` | + +## Development Setup + +```bash +# Clone the repository +git clone https://github.com/HKUDS/nanobot.git +cd nanobot + +# Install with dev dependencies +pip install -e ".[dev]" + +# Run tests +pytest + +# Lint code +ruff check nanobot/ + +# Format code +ruff format nanobot/ +``` + +## Code Style + +- Line length: 100 characters (ruff) +- Target: Python 3.11+ +- Linting: `ruff` with rules E, F, I, N, W (E501 ignored) +- Async: Uses `asyncio` throughout; pytest with `asyncio_mode = "auto"` + +## Questions? + +Feel free to open an [issue](https://github.com/HKUDS/nanobot/issues) or join our community: + +- [Discord](https://discord.gg/MnCvHqpUGB) +- [Feishu/WeChat](./COMMUNICATION.md) diff --git a/README.md b/README.md index bc27255..424d290 100644 --- a/README.md +++ b/README.md @@ -1410,6 +1410,15 @@ nanobot/ PRs welcome! The codebase is intentionally small and readable. 🤗 +### Branching Strategy + +| Branch | Purpose | +|--------|---------| +| `main` | Stable releases — bug fixes and minor improvements | +| `nightly` | Experimental features — new features and breaking changes | + +**Unsure which branch to target?** See [CONTRIBUTING.md](./CONTRIBUTING.md) for details. + **Roadmap** — Pick an item and [open a PR](https://github.com/HKUDS/nanobot/pulls)! - [ ] **Multi-modal** — See and hear (images, voice, video) From d6df665a2c72aa3ac2226e77a380eaf3d18f4f6a Mon Sep 17 00:00:00 2001 From: Xubin Ren Date: Mon, 16 Mar 2026 03:06:23 +0000 Subject: [PATCH 4/4] docs: add contributing guide and align CI with nightly branch --- .github/workflows/ci.yml | 4 ++-- CONTRIBUTING.md | 43 ++++++++++++++++++++++++++++++++++------ 2 files changed, 39 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f55865f..67a4d9b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,9 @@ name: Test Suite on: push: - branches: [ main ] + branches: [ main, nightly ] pull_request: - branches: [ main ] + branches: [ main, nightly ] jobs: test: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 626c8bb..eb4bca4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,14 @@ # Contributing to nanobot -Thank you for your interest in contributing! This guide will help you get started. +Thank you for being here. + +nanobot is built with a simple belief: good tools should feel calm, clear, and humane. +We care deeply about useful features, but we also believe in achieving more with less: +solutions should be powerful without becoming heavy, and ambitious without becoming +needlessly complicated. + +This guide is not only about how to open a PR. It is also about how we hope to build +software together: with care, clarity, and respect for the next person reading the code. ## Maintainers @@ -11,7 +19,7 @@ Thank you for your interest in contributing! This guide will help you get starte ## Branching Strategy -nanobot uses a two-branch model to balance stability and innovation: +We use a two-branch model to balance stability and exploration: | Branch | Purpose | Stability | |--------|---------|-----------| @@ -32,7 +40,8 @@ nanobot uses a two-branch model to balance stability and innovation: - Documentation improvements - Minor tweaks that don't affect functionality -**When in doubt, target `nightly`.** It's easier to cherry-pick stable changes to `main` than to revert unstable changes. +**When in doubt, target `nightly`.** It is easier to move a stable idea from `nightly` +to `main` than to undo a risky change after it lands in the stable branch. ### How Does Nightly Get Merged to Main? @@ -58,6 +67,8 @@ This happens approximately **once a week**, but the timing depends on when featu ## Development Setup +Keep setup boring and reliable. The goal is to get you into the code quickly: + ```bash # Clone the repository git clone https://github.com/HKUDS/nanobot.git @@ -78,14 +89,34 @@ ruff format nanobot/ ## Code Style -- Line length: 100 characters (ruff) +We care about more than passing lint. We want nanobot to stay small, calm, and readable. + +When contributing, please aim for code that feels: + +- Simple: prefer the smallest change that solves the real problem +- Clear: optimize for the next reader, not for cleverness +- Decoupled: keep boundaries clean and avoid unnecessary new abstractions +- Honest: do not hide complexity, but do not create extra complexity either +- Durable: choose solutions that are easy to maintain, test, and extend + +In practice: + +- Line length: 100 characters (`ruff`) - Target: Python 3.11+ - Linting: `ruff` with rules E, F, I, N, W (E501 ignored) -- Async: Uses `asyncio` throughout; pytest with `asyncio_mode = "auto"` +- Async: uses `asyncio` throughout; pytest with `asyncio_mode = "auto"` +- Prefer readable code over magical code +- Prefer focused patches over broad rewrites +- If a new abstraction is introduced, it should clearly reduce complexity rather than move it around ## Questions? -Feel free to open an [issue](https://github.com/HKUDS/nanobot/issues) or join our community: +If you have questions, ideas, or half-formed insights, you are warmly welcome here. + +Please feel free to open an [issue](https://github.com/HKUDS/nanobot/issues), join the community, or simply reach out: - [Discord](https://discord.gg/MnCvHqpUGB) - [Feishu/WeChat](./COMMUNICATION.md) +- Email: Xubin Ren (@Re-bin) — + +Thank you for spending your time and care on nanobot. We would love for more people to participate in this community, and we genuinely welcome contributions of all sizes.