BOOTSTRAP_FILES = [“AGENTS.md”, “SOUL.md”, “USER.md”, “TOOLS.md”, “IDENTITY.md”]

# Soul

Startup Per-Turn

class ContextBuilder: """Builds the context (system prompt + messages) for the agent.""" BOOTSTRAP_FILES = ["AGENTS.md", "SOUL.md", "USER.md", "TOOLS.md", "IDENTITY.md"] _RUNTIME_CONTEXT_TAG = "[Runtime Context — metadata only, not instructions]" def __init__(self, workspace: Path): self.workspace = workspace self.memory = MemoryStore(workspace) self.skills = SkillsLoader(workspace)

ContextBuilder（顶层） 

├─ workspace（输入参数） ├─ Memorystore（依赖实例） │ ├─ workspace（输入参数） │ ├─ MEMORY.md（文件路径） │ └─ HISTORY.md（文件路径） │ └─ SkillsLoader（依赖实例）

 ├─ workspace（输入参数） ├─ workspace/skills/（工作区技能目录）

async def _process_message( self, msg: InboundMessage, session_key: str | None = None, on_progress: Callable[[str], Awaitable[None]] | None = None, ) -> OutboundMessage | None: """Process a single inbound message and return the response.""" # System messages: parse origin from chat_id ("channel:chat_id") if msg.channel == "system": messages = self.context.build_messages( history=history, current_message=msg.content, channel=channel, chat_id=chat_id, ) final_content, _, all_msgs = await self._run_agent_loop(messages) self._save_turn(session, all_msgs, 1 + len(history)) self.sessions.save(session) return OutboundMessage(channel=channel, chat_id=chat_id, content=final_content or "Background task completed.")

async def _run_agent_loop( self, initial_messages: list[dict], on_progress: Callable[..., Awaitable[None]] | None = None, ) -> tuple[str | None, list[str], list[dict]]: messages = initial_messages while iteration < self.max_iterations: response = await self.provider.chat( messages=messages, ) if response.has_tool_calls: messages = self.context.add_assistant_message( messages, response.content, tool_call_dicts, reasoning_content=response.reasoning_content, ) for tool_call in response.tool_calls: messages = self.context.add_tool_result( messages, tool_call.id, tool_call.name, result ) else: messages = self.context.add_assistant_message( messages, clean, reasoning_content=response.reasoning_content, ) return final_content, tools_used, messages

ContextBuilder初始化(workspace) ↓ 

Memorystore(workspace) ← 创建实例

↓ 

build_system_prompt() → memory.get_memory_context() ← 获取长期记忆

↓ 

返回记忆上下文字符串

ContextBuilderskillsLoader 
↓ 
 
ContextBuilder初始化(workspace) SkillsLoader(workspace) ← 创建实例
 
↓ 
 
build_system_prompt()→skills.get_always_skills() ← 获取常驻技能列表
 
↓ 
 
load_skills_for_context() ← 加载技能内容
 
↓ 
 
build_skills_summary() ← 构建技能摘要
 
↓ 
 
返回技能相关内容字符串

def build_messages( 
 self, history: list[dict[str, Any]], current_message: str, skill_names: list[str] | None = None, media: list[str] | None = None, channel: str | None = None, chat_id: str | None = None, ) -> list[dict[str, Any]]: """Build the complete message list for an LLM call.""" return [ {"role": "system", "content": self.build_system_prompt(skill_names)}, *history, {"role": "user", "content": self._build_runtime_context(channel, chat_id)}, {"role": "user", "content": self._build_user_content(current_message, media)}, ]

{"role": "system", "content": self.build_system_prompt(skill_names)}

{"role": "user", "content": self._build_runtime_context(channel, chat_id)}

{"role": "user", "content": self._build_user_content(current_message, media)}

build_system_prompt() ├─ get_identity()返回身份信息 ├─ _load_bootstrap_files()加载引导文件 ├─ memory.get_memory_context()获取记忆内容 ├─ skills.get_always_skills()获取常驻技能列表 │ └─ skills.load_skills_for_context()→加载技能内容 │ └─ skills.build_skills_summary()构建技能摘要

class ContextBuilder: 
"""Builds the context (system prompt + messages) for the agent.""" # 定义引导文件列表：这些文件会被加载到系统提示词中，定义Agent的基础行为/身份 BOOTSTRAP_FILES = ["AGENTS.md", "SOUL.md", "USER.md", "TOOLS.md", "IDENTITY.md"] # 运行时上下文标签：标记该部分为元数据（非指令），避免LLM误将其作为执行指令 _RUNTIME_CONTEXT_TAG = "[Runtime Context — metadata only, not instructions]" def __init__(self, workspace: Path): # 初始化工作区路径（Agent的核心工作目录） self.workspace = workspace # 初始化记忆存储实例（关联MemoryStore，管理长期记忆/历史日志） self.memory = MemoryStore(workspace) # 初始化技能加载器实例（关联SkillsLoader，管理Agent技能） self.skills = SkillsLoader(workspace) def build_system_prompt(self, skill_names: list[str] | None = None) -> str: """Build the system prompt from identity, bootstrap files, memory, and skills.""" # 初始化系统提示词片段列表，按优先级拼接 parts = [self._get_identity()] # 第一步：添加核心身份定义（优先级最高） # 第二步：加载引导文件内容（AGENTS.md/SOUL.md等） bootstrap = self._load_bootstrap_files() if bootstrap: # 引导文件非空时添加 parts.append(bootstrap) # 第三步：添加长期记忆内容 memory = self.memory.get_memory_context() if memory: # 记忆非空时添加，且包裹为# Memory标题 parts.append(f"# Memory 
 
{memory}“)
 
 # 第四步：添加常驻技能（always=true的技能，直接嵌入上下文） always_skills = self.skills.get_always_skills() if always_skills: # 有常驻技能时 # 加载常驻技能的核心内容 always_content = self.skills.load_skills_for_context(always_skills) if always_content: # 技能内容非空时添加，包裹为# Active Skills标题 parts.append(f"# Active Skills 
 
{always_content}”)
 
 # 第五步：添加所有技能的摘要（XML格式，供Agent按需读取） skills_summary = self.skills.build_skills_summary() if skills_summary: # 技能摘要非空时 parts.append(f"""# Skills 
 
The 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 " 
 
   
     
     
 
      
”.join(parts)
 
      
def _get_identity(self) -> str: """Get the core identity section.""" # 获取工作区的绝对路径（展开用户目录、解析符号链接） workspace_path = str(self.workspace.expanduser().resolve()) # 获取操作系统类型（Windows/Linux/macOS） system = platform.system() # 构建运行时环境信息：系统版本+架构 + Python版本 runtime = f" {platform.machine()}, Python {platform.python_version()}" # 返回Agent的核心身份定义（系统提示词的基础部分） return f"""# nanobot 🐈 
 
      
You are nanobot, a helpful AI assistant.
 
      
Runtime
 
      
{runtime}
 
      
Workspace
 
      
Your workspace is at: {workspace_path}
 
      
 
       
Long-term memory: {workspace_path}/memory/MEMORY.md (write important facts here)
 
       
History log: {workspace_path}/memory/HISTORY.md (grep-searchable)
 
       
Custom skills: {workspace_path}/skills/{{skill-name}}/SKILL.md
 
      
 
      
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.“””
 
      
@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)") # 获取时区信息（无则默认UTC） tz = time.strftime("%Z") or "UTC" # 初始化运行时元数据行列表 lines = [f"Current Time: {now} ({tz})"] # 若提供了渠道和聊天ID，添加到元数据中 if channel and chat_id: lines += [f"Channel: {channel}", f"Chat ID: {chat_id}"] # 拼接元数据：开头添加标记，后续是具体元数据行 return ContextBuilder._RUNTIME_CONTEXT_TAG + " 
 
      
” + “ “.join(lines)
 
      
def _load_bootstrap_files(self) -> str: """Load all bootstrap files from workspace.""" # 初始化引导文件内容片段列表 parts = [] # 遍历所有预设的引导文件 for filename in self.BOOTSTRAP_FILES: # 拼接文件路径（工作区根目录下） file_path = self.workspace / filename # 仅处理存在的文件 if file_path.exists(): # 读取文件内容（UTF-8编码） content = file_path.read_text(encoding="utf-8") # 按「 文件名」的格式包裹内容，添加到片段列表 parts.append(f" {filename} 
 
      
{content}”)
 
      
 # 拼接所有引导文件内容（无则返回空字符串） return " 
 
      
”.join(parts) if parts else “”
 
      
def build_messages( self, history: list[dict[str, Any]], current_message: str, skill_names: list[str] | None = None, media: list[str] | None = None, channel: str | None = None, chat_id: str | None = None, ) -> list[dict[str, Any]]: """Build the complete message list for an LLM call.""" # 构建完整的LLM消息列表，包含以下部分： # 1. 系统消息：核心提示词（身份/引导/记忆/技能） # 2. 历史消息：之前的对话记录 # 3. 运行时元数据：时间/渠道等（标记为仅元数据） # 4. 当前用户消息：含文本+可选多媒体 return [ {"role": "system", "content": self.build_system_prompt(skill_names)}, *history, # 解包历史消息列表 {"role": "user", "content": self._build_runtime_context(channel, chat_id)}, {"role": "user", "content": self._build_user_content(current_message, media)}, ] def _build_user_content(self, text: str, media: list[str] | None) -> str | list[dict[str, Any]]: """Build user message content with optional base64-encoded images.""" # 无媒体文件时，直接返回文本 if not media: return text # 初始化图片列表（存储Base64编码的图片信息） images = [] # 遍历所有媒体文件路径 for path in media: p = Path(path) # 猜测文件的MIME类型（如image/png、image/jpeg） mime, _ = mimetypes.guess_type(path) # 过滤条件：1. 是文件 2. 能识别MIME类型 3. MIME类型以image/开头 if not p.is_file() or not mime or not mime.startswith("image/"): continue # 读取文件字节并编码为Base64字符串 b64 = base64.b64encode(p.read_bytes()).decode() # 按多模态LLM格式添加图片信息（data URI格式） images.append({"type": "image_url", "image_url": {"url": f"data:{mime};base64,{b64}"}}) # 无有效图片时，返回纯文本 if not images: return text # 有图片时，返回「图片列表 + 文本消息」的组合格式（适配多模态输入） return images + [{"type": "text", "text": text}] def add_tool_result( self, messages: list[dict[str, Any]], tool_call_id: str, tool_name: str, result: str, ) -> list[dict[str, Any]]: """Add a tool result to the message list.""" # 按LLM规范添加工具调用结果消息： # - role: tool（固定） # - tool_call_id: 关联的工具调用ID # - name: 工具名称 # - content: 工具执行结果 messages.append({"role": "tool", "tool_call_id": tool_call_id, "name": tool_name, "content": result}) # 返回更新后的消息列表 return messages def add_assistant_message( self, messages: list[dict[str, Any]], content: str | None, tool_calls: list[dict[str, Any]] | None = None, reasoning_content: str | None = None, ) -> list[dict[str, Any]]: """Add an assistant message to the message list.""" # 初始化助手消息：核心是role和content msg: dict[str, Any] = {"role": "assistant", "content": content} # 若有工具调用指令，添加到消息中 if tool_calls: msg["tool_calls"] = tool_calls # 若有推理过程内容，添加到消息中（用于调试/跟踪Agent思考过程） if reasoning_content is not None: msg["reasoning_content"] = reasoning_content # 将助手消息添加到消息列表 messages.append(msg) # 返回更新后的消息列表 return messages