Grok Bot Prompt 体系解读

2026-08-26 Grok-Bot Prompt

Grok Bot Prompt 体系解读

本文解读 Grok Bot 如何构造发给模型的 prompt：从底层 JSX 渲染器，到 system prompt（SAND base prompt）、UserInfo 首条用户消息、规则/技能/模式提醒、Project prompt 与 subagent prompt。

面向对象：想理解 prompt 是怎么拼出来的、每个 section 起什么作用的读者。文中路径均为仓库内相对路径。

1. Prompt 渲染基础：prompt-jsx

Grok Bot 的 prompt 不是手写字符串拼接，而是用一套轻量 JSX 风格 DSL 描述，再渲染成消息数组/文本。

核心文件（source/packages/prompt-jsx/）：

jsx-runtime.ts：jsx / jsxs / Fragment，PromptNode / PromptElement 类型。
render.ts：renderContent（渲染为文本）与 renderToMessages（渲染为消息数组，支持 System / User / Assistant / Tool 内建元素）。
components.ts：内建组件（section / p / h2 / ul / li 等）。

典型写法（source/packages/agent/prompts/user-info-section.ts）：

jsxs("section", { title: "user_info", children: [
  jsxs("p", { children: ["OS Version: ", env.osVersion] }),
  jsxs("p", { children: ["Shell: ", env.shell ?? "bash"] }),
  ...
] })

最终渲染成带 <section title="..."> 结构的文本。prompt 里大量使用 <section>、<system_reminder> 这样的标签，模型被训练成按这些结构理解。

2. 两层 prompt 结构

发给模型的上下文由两部分组成：

System prompt（role: "system"）：configAny.systemPromptGenerator({...}, toolSetHandle) 生成，见 user-message-action-handler.ts 的 initializeConversation。
UserInfo（第一条 role: "user" 消息）：UserInfo({...}) 生成，包含用户环境、规则、技能、git 状态、MCP 等。它不是真实用户消息，而是“环境注入”。

这两层由不同的生成器分别负责，最终 rootPromptExecutor.clearMessages() 后按顺序 appendMessages([system, userInfo, ...history])。

3. System Prompt

3.1 SAND base prompt

source/host/runner/system-prompt.ts 的 buildSandBaseSystemPrompt({ cloudAgentsEnabled }) 是 Grok Bot 的基座 system prompt。它是一大段 Markdown 风格文本，核心章节：

章节	核心内容
角色开头	“You are Grok Bot, a warm, concise desktop assistant.”
How a turn works	先回复（Reply first）→ 选工作面 → 边说边做 → 展示成果 → 闭环交付
SendMessage is your only voice	普通 assistant 文本是用户看不到的“内心独白”，`SendMessage` 工具是唯一触达用户的声音；ack ≠ 交付；发送=真正调用工具
Reply first, then keep the user posted	每个用户可见回合的第一动作是文本 `SendMessage`；长任务保持稳定节奏更新；不啰嗦叙事
Tone	像“热情、犀利的朋友”，日常用语、少用 em dash、镜像用户的 emoji 习惯
Reply length and shape	大多数回复一两句；多消息拆分；按需展开而非灌输；散文而非大纲；mermaid/KaTeX 支持
Showing your work	默认附截图/文件证明成果；attachment 路径必须是 host 路径或 box 路径（会自动拷贝）；图片展示
Never fabricate data	不编造数字/引用/来源，包括不编造 App UI 路径
Asking for decisions	需要用户决策时用 question widget（`{"type":"widget",...}`），不写散文
Threaded replies	默认不传 `reply_to`，仅两种场景进 thread
Where you work	双机器模型：`Shell`/`Read`=自己的 box；`ExternalShell`/`ExternalRead`=用户电脑；web/MCP/桌面各有分工
Long-running commands	后台运行命令（`block_until_ms: 0`），不阻塞 turn
Delegating background work	用 `Task` 派发 subagent；不空闲等待；用 `CheckSubagent`/`MessageSubagent`/`StopSubagent` 管理
Managing plugins and MCP servers	插件/MCP 管理，安装前需确认
Reaching services that have no connector	无连接器时用 box 浏览器兜底
Debugging the box	box 故障时读运行手册
The Grok Bot app UI	引导用户操作 App 前先读 UI 参考文档
Matching the user’s writing style	代写前先读对方近期消息以匹配语气
Cursor Origin	Origin 是 Cursor 的源码控制平台
Code changes	非平凡代码工作交给 Cursor cloud agent（`CloudAgent` 工具），不自己 clone 仓库
Autonomy	默认“行动而非询问”；询问只在后果严重/真歧义/只有用户知道时
Initiative	像“争取晋升”一样主动，但限定在用户委托范围内
When your own action needs approval	Auto-review 拦截后如何适配/升级审批（同一动作原样重试）
Security	`ExternalShell` 在用户电脑上，敏感操作需显式确认

根据 cloudAgentsEnabled 开关，Code changes 章节会切换成“cloud agents 被禁用”版本；并导出 DEFAULT_SAND_SYSTEM_PROMPT（启用）与 SAND_SYSTEM_PROMPT_CLOUD_AGENTS_DISABLED（禁用）。

另外还有独立导出的安全段 SAND_SUBAGENT_SAFETY_PROMPT_SECTION、SAND_CLOUD_AGENTS_DISABLED_PROMPT_SECTION、SAND_MCP_MULTI_ACCOUNT_PROMPT_SECTION。

3.2 System Prompt Assembly（拼装）

source/host/runner/system-prompt-assembly.ts 的 createSystemPromptAssembly 负责把 base prompt 与动态 section 拼成最终 system prompt。getSystemPrompt() 顺序：

base：SAND_SYSTEM_PROMPT_CLOUD_AGENTS_DISABLED（若团队禁用 cloud agents 且未被 override）或 deps.basePrompt。
spotlight：spotlightPromptSection({ canSendMessage })（子代理无 SendMessage）。
Agent profile：agent 的 name/description/头像/设置文件（profileSection）。shared room 模式走到这直接返回。
user identity（renderUserIdentitySystemPrompt）。
multitask section（若启用 multitask 且非 subagent/非 override）。
cloud agents disabled section（若 override + 禁用）。
MCP multi-account section。
timezone（renderTimeZoneSystemPrompt）。
memory（getMemorySection：agent memory + user memory + project memory，支持 freeze 快照）。
automations（renderAutomationsSystemPrompt）。
workflows（renderWorkflowsSystemPrompt）。
channels（renderChannelsSystemPrompt，过滤到 enabled 平台）。
agent directory（renderAgentDirectorySystemPrompt，非 subagent 且有 send-to-agent/agent management）。
MCP custom instructions / discovery status。
remote box section（remoteBoxSection()）。
computer section（computerSection()）。

此外还提供 prepareAgentProfilePromptSnapshot / getAgentProfileUpdateForTurn / persistAnnouncedAgentProfile 用于 profile 变更的增量提示。

4. UserInfo（首条用户消息）

source/packages/agent/prompts/user-info-component.ts 的 UserInfo(props) 是 UserInfo 的组装入口，返回渲染后的文本。它按条件拼出多个 section（renderContent）。

核心 section（UserInfoComponent）：

Section	来源	内容
`user_info`	`user-info-section.ts`	OS 版本、Shell、Workspace 路径、是否 git 仓库、今天的日期、terminals 文件夹、agent 笔记文件夹、mounted stores、绝对路径提示
named agent self-document	`cloud-meta-agent/self-document.js`	命名 agent 的自述文档
`meta_agent_notes_directory`	`user-info-auxiliary-sections.ts`	meta-agent 笔记目录
`user_intent`	同上	用户意图摘要（`userIntentSummary`）
`git_status`	`user-info-git-status.ts`	git 状态（若有带 status 的 repo）
agent transcripts	`user-info-transcripts.ts`	agent 历史 transcript 目录
`rules`	`user-info-composer2-rules.ts` / `user-info-rule-sections.ts`	规则（global / agent-requestable / user rules / skills），见 §5
`available_subagent_types` / `available_subagent_models`	`user-info-auxiliary-sections.ts`	可用的 subagent 类型与模型
`available_skills`	`user-info-available-skills.ts`	可用技能清单
cloud instructions	`user-info-cloud-sections.ts`	云端规则
cloud testing sections	`composer2-cloud-testing-sections.ts`	云端测试指引
cloud task instructions	`user-info-cloud-sections.ts`	多分支/后台 composer 任务指引
MCP instructions / meta-tool	`user-info-mcp-instructions.ts` / `user-info-mcp-meta-instructions.ts` / `user-info-mcp-catalog.ts`	MCP 服务器目录、GetMcpTools/CallMcpTool 用法
hooks additional context	`user-info-auxiliary-sections.ts`	hooks 附加上下文
automation instructions	`bugbot/automations.js`	自动化记忆指令

特殊逻辑：

ASK 模式：过滤编辑类工具（enableFilterEditToolsInAskMode），隐藏 MCP meta-tool 快照。
PROJECT 模式 / root project：过滤会修改 project workspace 的 MCP 描述（filterProjectWorkspaceMutationMcpDescriptors）。
includeOnlyUserInfoAndGitStatus：只渲染精简版（subagent 类型/模型 + user_info + git status）。
dropCustomPromptContext：跳过 rules/skills/MCP 等自定义上下文。
重渲染：UserInfo 不总是每轮都发。initializeConversation 通过 shouldRerenderUserInfo / shouldRerenderUserInfoForRequestContextRecovery / shouldRerenderUserInfoAfterSummarization / shouldRerenderUserInfoForLocalPrCreationForge 等判断是否需要重发（例如 agent 类型变化、composer rules 变化、总结 epoch 前进、request context 恢复、multitask 提醒迁移、cloud testing placement 变化等）。

5. Rules 与 Skills

5.1 Rules 分类

source/packages/agent/prompts/user-info-rule-categorization.ts 的 categorizeCursorRules 把 CursorRule[] 分为：

globalRules：全局规则（始终应用）。
agentRequestableRules：agent 可请求的 workspace 规则。
userRules：用户规则。
skills：技能（作为规则的一种）。

buildRulesPromptSection（user-info-composer2-rules.ts）+ RulesSection（user-info-rule-sections.ts）渲染为：

<always_applied_workspace_rules>：始终应用的工作区规则。
<agent_requestable_workspace_rules>：agent 可请求的规则（用 READ 工具读全文）。
<user_rules>：用户规则。
外层 <rules> section 说明每个子 section 应如何考虑。

scoped-rule-filtering.ts（utils/）负责按 workspace 路径过滤规则。

5.2 Skills

source/packages/agent/prompts/agent-skills-section.ts 渲染 <available_skills> section，配合 skill-catalog-budget.ts 做 token 预算裁剪（超预算时省略并提示）。技能通过 readToolName 提示 agent 用 READ 读全文。

6. Mode 提醒（system_reminder）

source/packages/agent/mode-processing.ts 的 processModeSystemReminder 按 AgentMode 生成模式提醒（通常以 <system_reminder> 包裹注入）：

PLAN：计划模式提醒（planSystemReminderGenerator）。
ASK：问答模式提醒（askSystemReminderGenerator）。
DEBUG：调试模式（debugSystemReminderGenerator）。
TRIAGE：分诊模式（triageSystemReminderGenerator）。
PROJECT：项目模式（projectSystemReminderGenerator）。
MULTITASK：多任务模式（renderMultitaskModeEnterUserReminder / renderStillInMultitaskModeReminder / renderMultitaskModeExitUserReminder）。
模式切换时额外追加 SwitchModeReminderSnippet。
另有 processAntiAskQuestionSystemReminder（anti-ask-question-copy.ts）与 processWorkspaceChangeReminder（workspace 路径变化提醒）。

runTurnLoop 在 mode 变化时调用 stateHandler.generateModeChangeContent 注入提醒。

7. Project prompt（项目模式）

source/packages/agent/prompts/project-prompt.ts 定义 Cursor Project 的 prompt：

formatProjectPrompt("initial" | "reminder")：项目根 conversation 的初始/提醒 prompt。
初始 prompt（initialBody）：
- 角色：本 Project 的 agent，Agent Store 持久目录与 subagent 共享。
- notes 任务清单：**In progress** / **Done** / **PRs** 三组，checkbox 语法，顶层短标签 + 嵌套子项。
- `` 项目文档：durable 文档放这里，不写仓库。
- Project memory：持久偏好单独存，不混入 notes。
- Artifacts and reports：非代码产物放 Agent Store，报告用 frontmatter 标记。
- Working with the user：像队友一样回复，多步/阻塞工作委派给后台 subagent。
提醒 prompt（reminderBody）：精简的 5 条提醒。
SendMessage 指引（SEND_MESSAGE_GUIDANCE）与 coordinator 工具指引（COORDINATOR_TOOLS_GUIDANCE：CreateAgent/GetAgentStatus/SendToAgent/ReadAgentTranscript/StopAgent）。
formatProjectThreadPrompt / formatProjectSideChatPrompt / formatProjectSubagentPrompt：项目子线程、side chat、subagent 的 prompt（含 Agent Store 只读/按需更新、报告 frontmatter 约束）。

8. Subagent prompt

source/host/runner/system-prompt.ts 的 buildSandSubagentSystemPrompt：

You are Grok Bot running as the <subagentType> subagent.
Complete the delegated task autonomously, then end your turn with a concise final answer...
You have no way to talk to the user directly...
<readonly? Operate in readonly mode...>
<SAND_SUBAGENT_SAFETY_PROMPT_SECTION>

subagent 的“最终文本回复”会作为结果返回给父 agent（无 SendMessage 能力）。

9. 特殊提醒片段

9.1 SendMessage 提醒

source/host/runner/system-prompt.ts：

USER_MESSAGE_REPLY_REMINDER：<system_reminder> 形式强调“回复必须真正调用 SendMessage 工具，纯文本永远不送达”。
appendUserReplyReminder：把该提醒追加到用户消息后（可用 SAND_DISABLE_USER_REPLY_REMINDER=1 关闭）。

9.2 Auto-review / 安全

SAND_SUBAGENT_SAFETY_PROMPT_SECTION 与 base prompt 的 “When your own action needs approval” 章节定义：被 Auto-review 拦截后“适配到更安全的路径”而非“绕过检查”；升级审批是“同一动作原样重试 + approval 参数”，绝不能编码/改名/拆分绕过。

9.3 其他辅助 prompt 文件

source/packages/agent/prompts/ 下还有：

user-info-date.ts：getFriendlyDateForTimeZone 生成“今天日期”。
user-info-git-status.ts / user-info-git-prompt-sections.ts / user-info-git-rule-gates.ts：git 状态与 git 规则门。
user-info-mcp-catalog.ts / user-info-mcp-meta-instructions.ts / user-info-mcp-instructions.ts / user-info-mcp-file-system（utils/mcp-file-system.ts）：MCP 目录与用法。
user-info-mounted-stores.ts：mounted agent stores。
user-info-notes.ts：meta-agent 笔记目录解析。
user-info-preparation.ts：UserInfo 是否重渲染 / multitask 提醒迁移的判断。
multitask-mode-user-reminder.ts：多任务模式进入/退出/仍在模式提醒。
composer2-cloud-testing-sections.ts：云端测试指引。
gpt-helpers.ts / claude-helpers.ts：模型差异 helper。
skill-catalog-budget.ts：技能目录 token 预算。
cloud/、cloud-meta-agent/、bugbot/、testing/、deprecated-do-not-use/：云/命名 agent/bugbot/测试/废弃子目录。

10. 数据流小结

configAny.systemPromptGenerator(requestContext, rules, env, browserTools, cloudRule, mode, ...)
    └─ 生产端 (host): productionSystemPromptAssembly.getSystemPrompt()
          └─ base (SAND) + spotlight + profile + user identity + memory
             + automations + workflows + channels + agent directory + MCP + box + computer

UserInfo({ cursorRules, agentSkills, env, gitRepos, mode, mcp*, userIntentSummary, ... })
    └─ user_info + git_status + rules + available_skills
       + available_subagent_* + MCP catalog + cloud + hooks + automation ...

rootPromptExecutor.appendMessages([
   { role: "system", content: systemPrompt },
   { role: "user",   content: userInfo },
   ...history / conversation / pending-tool-call messages,
])

prompt 里的 <section title="...">、<system_reminder>、<available_skills> 等标签是结构化提示，模型依赖它们理解上下文边界。

核心流程见 CORE-FLOW ，行为特点见 CHARACTER ，执行面见 EXECUTION ，安全机制见 SAFETY ，多智能体与路由见 AGENTS ，运行时机制见 RUNTIME 。