openclaw 的 embedded-system-prompt 翻译

提示词翻译文档

元信息

  • 原文件位置: src/agents/pi-embedded-runner/system-prompt.ts
  • 变量名称: buildEmbeddedSystemPrompt()
  • 功能模块: 嵌入式 Agent 运行时提示词
  • 调用场景: 在 Pi 嵌入式运行时中构建系统提示词

概述

此模块提供嵌入式运行时的系统提示词构建功能。它是对核心 buildAgentSystemPrompt() 函数的包装器，专门用于嵌入式 Agent 场景。

中文翻译

主要函数：buildEmbeddedSystemPrompt()

构建嵌入式系统提示词，用于 Pi 嵌入式运行时。

export function buildEmbeddedSystemPrompt(params: {
  workspaceDir: string;
  defaultThinkLevel?: ThinkLevel;
  reasoningLevel?: ReasoningLevel;
  extraSystemPrompt?: string;
  ownerNumbers?: string[];
  ownerDisplay?: "raw" | "hash";
  ownerDisplaySecret?: string;
  reasoningTagHint: boolean;
  heartbeatPrompt?: string;
  skillsPrompt?: string;
  docsPath?: string;
  ttsHint?: string;
  reactionGuidance?: {
    level: "minimal" | "extensive";
    channel: string;
  };
  workspaceNotes?: string[];
  promptMode?: PromptMode;
  runtimeInfo: {
    agentId?: string;
    host: string;
    os: string;
    arch: string;
    node: string;
    model: string;
    provider?: string;
    capabilities?: string[];
    channel?: string;
    channelActions?: string[];
    repoRoot?: string;
    shell?: string;
    defaultModel?: string;
  };
  messageToolHints?: string[];
  sandboxInfo?: EmbeddedSandboxInfo;
  tools: AgentTool[];
  modelAliasLines: string[];
  userTimezone: string;
  userTime?: string;
  userTimeFormat?: ResolvedTimeFormat;
  contextFiles?: EmbeddedContextFile[];
  memoryCitationsMode?: MemoryCitationsMode;
}): string

函数：createSystemPromptOverride()

创建一个系统提示词覆盖函数，用于完全替换默认提示词。

export function createSystemPromptOverride(
  systemPrompt: string,
): (defaultPrompt?: string) => string

用途: 当需要完全控制 Agent 的系统提示词时使用此函数。返回的函数会忽略任何默认提示词，始终返回指定的覆盖内容。

函数：applySystemPromptOverrideToSession()

将系统提示词覆盖应用到 Agent 会话。

export function applySystemPromptOverrideToSession(
  session: AgentSession,
  override: string | ((defaultPrompt?: string) => string),
): void

功能:

  1. 解析覆盖内容（字符串或函数）
  2. 调用 session.agent.setSystemPrompt() 设置提示词
  3. 同时更新内部 _baseSystemPrompt 和 _rebuildSystemPrompt 字段

参数详解

核心参数

参数 类型 必填 说明
workspaceDir string ✅ Agent 的工作空间目录
tools AgentTool[] ✅ 可用工具列表
runtimeInfo object ✅ 运行时环境信息
userTimezone string ✅ 用户时区（如 "Asia/Shanghai"）
reasoningTagHint boolean ✅ 是否显示推理格式提示

思考与推理参数

参数 类型 说明
defaultThinkLevel ThinkLevel 默认思考级别
reasoningLevel ReasoningLevel 推理显示级别
reasoningTagHint boolean 是否启用推理标签提示

所有者与安全参数

参数 类型 说明
ownerNumbers string[] 授权发送者列表
ownerDisplay "raw"| "hash" 所有者 ID 显示方式
ownerDisplaySecret string 用于哈希的密钥

上下文与记忆参数

参数 类型 说明
contextFiles EmbeddedContextFile[] 要注入的上下文文件
memoryCitationsMode MemoryCitationsMode 记忆引用模式
skillsPrompt string 技能提示词块
extraSystemPrompt string 额外系统提示词

运行时信息 (runtimeInfo)

字段 类型 说明
agentId string Agent 标识符
host string 主机名
os string 操作系统
arch string 架构 (x64, arm64 等)
node string Node.js 版本
model string 当前模型名称
provider string 模型提供商
capabilities string[] 通道能力列表
channel string 当前消息通道
channelActions string[] 支持的通道操作 (react, edit, unsend 等)
repoRoot string Git 仓库根目录
shell string 默认 Shell
defaultModel string 默认模型名称

反应指导 (reactionGuidance)

控制 Agent 在消息通道上的表情反应行为：

reactionGuidance?: {
  level: "minimal" | "extensive";  // 反应级别
  channel: string;                 // 目标通道
}
  • minimal: 仅在真正相关时反应（每 5-10 次对话最多 1 次）
  • extensive: 自由地大量反应，随时表达情感

沙箱信息 (sandboxInfo)

当 Agent 在沙箱环境中运行时提供：

sandboxInfo?: {
  enabled: boolean;
  workspaceDir?: string;
  containerWorkspaceDir?: string;
  workspaceAccess?: "rw" | "ro";
  agentWorkspaceMount?: string;
  browserBridgeUrl?: string;
  browserNoVncUrl?: string;
  hostBrowserAllowed?: boolean;
  elevated?: {
    allowed: boolean;
    defaultLevel: "on" | "off" | "ask" | "full";
  };
}

与 buildAgentSystemPrompt() 的关系

buildEmbeddedSystemPrompt() 是 buildAgentSystemPrompt() 的适配器：

graph LR A[调用方] --> B[buildEmbeddedSystemPrompt] B --> C[提取 toolNames] B --> D[构建 toolSummaries] C --> E[buildAgentSystemPrompt] D --> E E --> F[系统提示词字符串]

主要区别:

  1. 接收 tools: AgentTool[] 而非 toolNames: string[]
  2. 自动从工具数组提取名称和摘要
  3. 添加了 reactionGuidance 支持
  4. 添加了 channelActions 支持

相关代码上下文

调用位置

文件 场景
src/agents/pi-embedded-runner/run/attempt.ts 运行尝试时构建提示词
src/agents/pi-embedded-runner/compact.ts 压缩会话时重建提示词

相关类型

// 来自 pi-coding-agent
type AgentTool = {
  name: string;
  description?: string;
  input_schema: object;
  handler: Function;
};

// 上下文文件
type EmbeddedContextFile = {
  path: string;
  content: string;
};

// 提示词模式
type PromptMode = "full" | "minimal" | "none";

使用示例

基本用法

const systemPrompt = buildEmbeddedSystemPrompt({
  workspaceDir: "/home/user/.openclaw/workspace",
  tools: codingTools,
  runtimeInfo: {
    host: "macbook-pro",
    os: "darwin",
    arch: "arm64",
    node: "v22.0.0",
    model: "claude-3-opus",
  },
  userTimezone: "America/New_York",
  reasoningTagHint: false,
});

应用覆盖

// 创建覆盖
const override = createSystemPromptOverride("你是一个专门的编码助手。");

// 应用到会话
applySystemPromptOverrideToSession(session, override);
posted @ 2026-03-13 16:31  枫叶流华  阅读(76)  评论(0)    收藏  举报