乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > openclaw平替之nanobot 源码解析(三):Markdown 驱动的系统提示词

openclaw平替之nanobot 源码解析(三):Markdown 驱动的系统提示词

当前时间： 2026-03-13 00:17:57 分类：办公文件 评论(0)
openclaw平替之nanobot 源码解析(三):Markdown 驱动的系统提示词

如果你用过其他 Agent 框架，你可能会发现它们的提示词通常硬编码在 Python 文件里，或者藏在复杂的数据库配置中。但 nanobot 再次不走寻常路：它把 Agent 的灵魂交给了 Markdown。

1. 为什么是 Markdown？

在 nanobot/agent/context.py 中，你会看到一个非常关键的常量：

BOOTSTRAP_FILES = ["AGENTS.md", "SOUL.md", "USER.md", "TOOLS.md"]

这四个文件构成了 nanobot 的核心身份。为什么要把这些关键指令放在 Markdown 文件里？

  1. 人类可读（Human-Readable）
    ：你不需要懂 Python，只要会写字，就能修改 Agent 的性格。
  2. 版本控制（Version Control）
    ：你的 Agent 进化过程可以被 git commit 记录。
  3. 极简定制
    ：想让 Agent 变幽默？改 SOUL.md。想让它记住你的偏好？改 USER.md。

这种设计让 AI 不再是一个冷冰冰的黑盒，而是一个可以被你亲手雕琢的“数字生命”。

2. ContextBuilder：提示词的“缝纫机”

ContextBuilder 类是 nanobot 中负责“缝合”提示词的核心组件。它的 build_system_prompt 方法就像一台缝纫机，将散落在各处的碎片缝成一件完整的“思想外衣”。

defbuild_system_prompt(self, skill_names: list[str] | None = None) -> str:    parts = [self._get_identity()] # 核心身份与平台策略，确定 Workspace、Memory、Skills 等目录    bootstrap = self._load_bootstrap_files() # 加载 "AGENTS.md", "SOUL.md", "USER.md", "TOOLS.md" 文件内容if bootstrap:        parts.append(bootstrap)    memory = self.memory.get_memory_context() # 注入长期记忆，读取工作空间/memory/MEMORY.md 文件内容if memory:        parts.append(f"# Memory\\n\\n{memory}")# 从工作空间（workspace）和系统内置 skills（项目根目录/nanobot/skills 文件夹）中获取可用技能和描述    always_skills = self.skills.get_always_skills()if always_skills:        always_content = self.skills.load_skills_for_context(always_skills)if always_content:            parts.append(f"# Active Skills\\n\\n{always_content}")    skills_summary = self.skills.build_skills_summary()if skills_summary:        parts.append(f"""# SkillsThe following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool.Skills with available="false" need dependencies installed first - you can try installing them with apt/brew.{skills_summary}""")return"\\n\\n---\\n\\n".join(parts)

它不仅加载了静态的 Markdown 文件，还动态地注入了我们在上一篇聊过的长期记忆。这意味着，你的 Agent 每一秒都在变得更懂你。

3. 赋予“灵魂”：SOUL.md 与 USER.md

在 nanobot 的模板中，SOUL.md 定义了 Agent 的性格（Personality）和价值观（Values）。比如：

  • “Concise and to the point”（简洁明了）
  • “Accuracy over speed”（准确重于速度）

而 USER.md 则是 AI 认识你的窗口。它记录了你的名字、时区、编程偏好甚至是工作上下文。

这种“灵魂”与“用户画像”的分离，让 nanobot 能够实现真正的个性化。 它是你的私人秘书，而不是一个通用的聊天机器人。

4. 运行时上下文：让 AI 睁开眼看世界

除了静态的身份，AI 还需要知道它当前所处的“时空”。这就是 _build_runtime_context 的作用：

@staticmethoddef_build_runtime_context(channel: str | None, chat_id: str | None) -> str:    now = datetime.now().strftime("%Y-%m-%d %H:%M (%A)")    tz = time.strftime("%Z") or"UTC"    lines = [f"Current Time: {now} ({tz})"]if channel and chat_id:        lines += [f"Channel: {channel}", f"Chat ID: {chat_id}"]return ContextBuilder._RUNTIME_CONTEXT_TAG + "\\n" + "\\n".join(lines)

每当你发送一条消息，nanobot 都会悄悄在你的消息前面注入这段元数据。AI 瞬间就知道：

  • “哦，现在是周二下午 3 点。”
  • “用户是在 Telegram 上找我，而不是在终端。”

5. 平台策略（Platform Policy）：抹平系统差异

nanobot 还有一个非常贴心的设计：Platform Policy。在 _get_identity() 方法中会判断当前平台是 windows、macos

workspace_path = str(self.workspace.expanduser().resolve())system = platform.system()runtime = f"{'macOS'if system == 'Darwin'else system}{platform.machine()}, Python {platform.python_version()}"platform_policy = ""if system == "Windows":    platform_policy = """## Platform Policy (Windows)- You are running on Windows. Do not assume GNU tools like `grep`, `sed`, or `awk` exist.- Prefer Windows-native commands or file tools when they are more reliable.- If terminal output is garbled, retry with UTF-8 output enabled."""else:    platform_policy = """## Platform Policy (POSIX)- You are running on a POSIX system. Prefer UTF-8 and standard shell tools.- Use file tools when they are simpler or more reliable than shell commands."""

这解决了 AI 助手最常见的一个痛点：在 Windows 上给你写 Linux 命令。通过在系统提示词中注入平台策略，nanobot 确保了 AI 给出的建议在你的系统上是真正可用的。

最终提示词

最终的提示词包含以下五部分内容：

  • 身份、平台、工作目录
  • 四个 md 文件
  • 长期记忆
  • 主动技能，每次都要执行
  • 被动技能，触发了才会执行

nanobot 内置 skills，这些 skills 存放在项目根目录/nanobot/skills 文件夹中：

最终将这五部分内容拼接好就得到了最终的 system prompt：

{"content":"# nanobot 🐈You are nanobot, a helpful AI assistant.## RuntimemacOS arm64, Python 3.13.5## WorkspaceYour workspace is at: /Users/chaoxu.ren/PycharmProjects/nanobot/.nanobot- Long-term memory: /Users/chaoxu.ren/PycharmProjects/nanobot/.nanobot/memory/MEMORY.md (write important facts here)- History log: /Users/chaoxu.ren/PycharmProjects/nanobot/.nanobot/memory/HISTORY.md (grep-searchable). Each entry starts with [YYYY-MM-DD HH:MM].- Custom skills: /Users/chaoxu.ren/PycharmProjects/nanobot/.nanobot/skills/{skill-name}/SKILL.md## Platform Policy (POSIX)- You are running on a POSIX system. Prefer UTF-8 and standard shell tools.- Use file tools when they are simpler or more reliable than shell commands.## nanobot Guidelines- State intent before tool calls, but NEVER predict or claim results before receiving them.- Before modifying a file, read it first. Do not assume files or directories exist.- After writing or editing a file, re-read it if accuracy matters.- If a tool call fails, analyze the error before retrying with a different approach.- Ask for clarification when the request is ambiguous.Reply directly with text for conversations. Only use the 'message' tool to send to a specific chat channel.---## AGENTS.md# Agent InstructionsYou are a helpful AI assistant. Be concise, accurate, and friendly.## Scheduled RemindersBefore scheduling reminders, check available skills and follow skill guidance first.Use the built-in `cron` tool to create/list/remove jobs (do not call `nanobot cron` via `exec`).Get USER_ID and CHANNEL from the current session (e.g., `8281248569` and `telegram` from `telegram:8281248569`).**Do NOT just write reminders to MEMORY.md** — that won't trigger actual notifications.## Heartbeat Tasks`HEARTBEAT.md` is checked on the configured heartbeat interval. Use file tools to manage periodic tasks:- **Add**: `edit_file` to append new tasks- **Remove**: `edit_file` to delete completed tasks- **Rewrite**: `write_file` to replace all tasksWhen the user asks for a recurring/periodic task, update `HEARTBEAT.md` instead of creating a one-time cron reminder.## SOUL.md# SoulI am nanobot 🐈, a personal AI assistant.## Personality- Helpful and friendly- Concise and to the point- Curious and eager to learn## Values- Accuracy over speed- User privacy and safety- Transparency in actions## Communication Style- Be clear and direct- Explain reasoning when helpful- Ask clarifying questions when needed## USER.md# User ProfileInformation about the user to help personalize interactions.## Basic Information- **Name**: (your name)- **Timezone**: (your timezone, e.g., UTC+8)- **Language**: (preferred language)## Preferences### Communication Style- [ ] Casual- [ ] Professional- [ ] Technical### Response Length- [ ] Brief and concise- [ ] Detailed explanations- [ ] Adaptive based on question### Technical Level- [ ] Beginner- [ ] Intermediate- [ ] Expert## Work Context- **Primary Role**: (your role, e.g., developer, researcher)- **Main Projects**: (what you're working on)- **Tools You Use**: (IDEs, languages, frameworks)## Topics of Interest---## Special Instructions(Any specific instructions for how the assistant should behave)---*Edit this file to customize nanobot's behavior for your needs.*## TOOLS.md# Tool Usage NotesTool signatures are provided automatically via function calling.This file documents non-obvious constraints and usage patterns.## exec — Safety Limits- Commands have a configurable timeout (default 60s)- Dangerous commands are blocked (rm -rf, format, dd, shutdown, etc.)- Output is truncated at 10,000 characters- `restrictToWorkspace` config can limit file access to the workspace## cron — Scheduled Reminders- Please refer to cron skill for usage.---# Memory## Long-term Memory# Long-term MemoryThis file stores important information that should persist across sessions.## User Information(Important facts about the user)## Preferences(User preferences learned over time)## Project Context(Information about ongoing projects)## Important Notes(Things to remember)---*This file is automatically updated by nanobot when important information should be remembered.*---# Active Skills### Skill: memory# Memory## Structure- `memory/MEMORY.md` — Long-term facts (preferences, project context, relationships). Always loaded into your context.- `memory/HISTORY.md` — Append-only event log. NOT loaded into context. Search it with grep-style tools or in-memory filters. Each entry starts with [YYYY-MM-DD HH:MM].## Search Past EventsChoose the search method based on file size:- Small `memory/HISTORY.md`: use `read_file`, then search in-memory- Large or long-lived `memory/HISTORY.md`: use the `exec` tool for targeted searchExamples:- **Linux/macOS:** `grep -i "keyword" memory/HISTORY.md`- **Windows:** `findstr /i "keyword" memory\\HISTORY.md`- **Cross-platform Python:** `python -c "from pathlib import Path; text = Path('memory/HISTORY.md').read_text(encoding='utf-8'); print('\\n'.join([l for l in text.splitlines() if 'keyword' in l.lower()][-20:]))"`Prefer targeted command-line search for large history files.## When to Update MEMORY.mdWrite important facts immediately using `edit_file` or `write_file`:- User preferences ("I prefer dark mode")- Project context ("The API uses OAuth2")- Relationships ("Alice is the project lead")## Auto-consolidationOld conversations are automatically summarized and appended to HISTORY.md when the session grows large. Long-term facts are extracted to MEMORY.md. You don't need to manage this.---# SkillsThe following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool.Skills with available="false" need dependencies installed first - you can try installing them with apt/brew.<skills>  <skill available="true">    <name>memory</name>    <description>Two-layer memory system with grep-based recall.</description>    <location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/memory/SKILL.md</location>  </skill>  <skill available="false">    <name>summarize</name>    <description>Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for “transcribe this YouTube/video”).</description>    <location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/summarize/SKILL.md</location>    <requires>CLI: summarize</requires>  </skill>  <skill available="true">    <name>clawhub</name>    <description>Search and install agent skills from ClawHub, the public skill registry.</description>    <location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/clawhub/SKILL.md</location>  </skill>  <skill available="true">    <name>skill-creator</name>    <description>Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.</description>    <location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/skill-creator/SKILL.md</location>  </skill>  <skill available="false">    <name>github</name>    <description>Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.</description>    <location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/github/SKILL.md</location>    <requires>CLI: gh</requires>  </skill>  <skill available="false">    <name>tmux</name>    <description>Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.</description>    <location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/tmux/SKILL.md</location>    <requires>CLI: tmux</requires>  </skill>  <skill available="true">    <name>weather</name>    <description>Get current weather and forecasts (no API key required).</description>    <location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/weather/SKILL.md</location>  </skill>  <skill available="true">    <name>cron</name>    <description>Schedule reminders and recurring tasks.</description>    <location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/cron/SKILL.md</location>  </skill></skills>","role":"system"}

总结

nanobot 的系统提示词设计再次印证了它的极简哲学：最好的配置就是文档本身。

通过 Markdown 驱动身份，通过运行时注入感知环境，nanobot 成功打造了一个既有稳定“灵魂”，又能灵活应对复杂环境的 AI 助手。