System Prompt

MushroomAgent 每次 LLM 调用前都会组装一个由多层构成的系统 prompt。本文档记录每一层的内容。

组装顺序

系统 prompt 由 assemble_system_prompt_messages() 按固定顺序构建。靠前的层在上下文窗口中更靠前。共 5 层：

第一层：固定骨架

由 build_fixed_system_prompt() 函数定义。核心 prompt 结构：

You are a conversational AI assistant.

条件性段落 — 仅当相关数据存在时才包含：

段落	包含条件	内容
User	已知用户名时	"You are currently talking to: {user_name}"
Persona	配置了人设时	配置的人设描述
Skills	skills 启用时	可用 skills 列表及选择规则（见下方）
Knowledge Context	记忆检索返回知识时	权威检索知识摘要
Conversation Summary	昨日对话被摘要时	过去对话主题的结构化摘要
Response Format	response_format="json_object" 时	返回合法 JSON 的指令

第二层：运行时事实

作为 ## Runtime Facts 块注入。包含当前轮次的实时信息：

• Agent ID 和名称
• 远程用户 ID 和名称
• 来源渠道、渠道用户 ID、聊天类型、群组 ID
• 当前时间和时区
• 工作区路径
• 心跳运行标记
• 消息中的自定义 turn 变量

第三层：工作区上下文

如果工作区上下文文件存在且未设置 agent.skip_context_files，其内容被注入：

# Workspace Context
- Workspace root: /path/to/workspace
- These files are raw workspace context. Apply them when relevant.

## AGENTS.md
- Purpose: project rules, operating constraints, and execution boundaries.
\{内容}

## SOUL.md
- Purpose: persona and tone. If present, embody its voice and style.
\{内容}

## IDENTITY.md
- Purpose: canonical self-identity, role, and self-description.
\{内容}

文件按顺序加载，受截断限制（每文件 4000 字符，总计 12000 字符）。

第四层：心跳上下文

仅对心跳触发的轮次注入。包含心跳协议指导，指示 agent 评估是否需要主动交互。如无必要，agent 应回复 HEARTBEAT_OK。

第五层：临时系统 prompt

来自配置中的 agent.ephemeral_system_prompt。用于：

• 子 agent：delegate_task 工具设置此项来定义任务范围
• 临时覆盖：任何不应持久化的单次指令

此层不会持久化到对话历史。

Prompt 中的 Skills

当 skills 启用时，骨架中包含：

## Skills
Treat skills as instruction documents, not callable tools or functions.

### Selection Rules
- Scan <available_skills> descriptions before deciding.
- Never call a skill name as a tool.
- If exactly one skill clearly applies: read its SKILL.md...
- Never read more than one skill up front.

### Available Skills
<available_skills>
  <skill>
    <name>skill_name</name>
    <description>...</description>
    <location>/path/to/SKILL.md</location>
  </skill>
</available_skills>

Skills 列表经 allowlist/blocklist 过滤，仅包含启用的 skills。Agent 被指示按需用 read 加载相关 SKILL.md — skills 不会预先加载到 prompt 中。

自定义

• 人设：通过配置或 SOUL.md 工作区文件设置
• 规则与约束：在工作区中编写 AGENTS.md
• 身份：在工作区中编写 IDENTITY.md
• 临时指令：在配置中设置 agent.ephemeral_system_prompt
• 跳过工作区上下文：设置 agent.skip_context_files: true