第 31 章 — 实现 Agent Runtime 与工具执行

// src/agent/system-prompt.ts
 
export function buildSystemPrompt(params: {
  config: MiniOpenClawConfig;
  tools: ToolDefinition[];
  memoryManager: MemoryManager;
  skillsLoader: SkillsLoader;
}): string {
  const sections: string[] = [];
 
  // 1. 身份
  sections.push(
    'You are an AI assistant powered by Mini OpenClaw.',
    'You can read files, execute commands, and help users with various tasks.',
    '',
  );
 
  // 2. SOUL.md（Agent 人设）
  const soulPath = path.join(config.workspaceDir, '.openclaw', 'SOUL.md');
  const soulContent = tryReadFile(soulPath);
  if (soulContent) {
    sections.push('## Identity & Personality', '', soulContent.trim(), '');
  }
 
  // 3. TOOLS.md（工具使用指南）
  const toolsDocPath = path.join(config.workspaceDir, '.openclaw', 'TOOLS.md');
  const toolsDoc = tryReadFile(toolsDocPath);
  if (toolsDoc) {
    sections.push('## Tool Usage Guidelines', '', toolsDoc.trim(), '');
  }
 
  // 4. Memory 上下文
  const memoryContext = memoryManager.getContextForPrompt();
  if (memoryContext) {
    sections.push('## Memory', '', memoryContext, '');
  }
 
  // 5. Skills 索引
  const skillsContext = skillsLoader.getSkillsIndexForPrompt();
  if (skillsContext) {
    sections.push(skillsContext, '');
  }
 
  // 6. 运行时信息
  sections.push(
    '## Runtime Information', '',
    `- Current time: ${new Date().toISOString()}`,
    `- Working directory: ${config.workspaceDir}`,
    `- Platform: ${process.platform}`,
    '',
  );
 
  // 7. 可用工具列表
  // ...
 
  return sections.join('\n');
}

// src/agent/runtime.ts
 
export class AgentRuntime {
  private client: Anthropic;
  private tools: Map<string, ToolDefinition> = new Map();
  // ...
 
  async run(input: AgentRunInput): Promise<AgentRunResult> {
    const { sessionId, userMessage, onChunk, onToolStart, onToolDone } = input;
 
    // 1. 加载历史消息，截取最近 N 条
    const history = this.sessionStore.loadMessages(sessionId);
    const recentHistory = history.slice(-this.config.maxContextMessages);
 
    // 2. 组装 system prompt
    const systemPrompt = buildSystemPrompt({ ... });
 
    // 3. 构建消息序列
    const messages = this.buildAnthropicMessages(recentHistory, userMessage);
 
    // 4. 构建工具定义
    const toolDefs = this.buildAnthropicTools();
 
    // 5. Agent 循环
    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
      const response = await this.callModel({ systemPrompt, messages, tools, onChunk });
 
      const toolUseBlocks = response.content.filter(
        (block) => block.type === 'tool_use',
      );
 
      if (toolUseBlocks.length === 0) {
        // 没有工具调用，返回文本
        break;
      }
 
      // 执行工具，结果送回模型
      for (const toolUse of toolUseBlocks) {
        onToolStart(toolUse.name);
        const result = await tool.execute(toolUse.input);
        onToolDone(toolUse.name, result.output);
      }
 
      // 追加助手消息和工具结果，继续下一轮
      currentMessages = [...currentMessages, assistantMsg, toolResultMsg];
    }
  }
}

private async callModel(params: {
  systemPrompt: string;
  messages: Anthropic.MessageParam[];
  tools: Anthropic.Tool[];
  onChunk: (chunk: string) => void;
}): Promise<Anthropic.Message> {
  const stream = this.client.messages.stream({
    model: this.config.model,
    max_tokens: 4096,
    system: params.systemPrompt,
    messages: params.messages,
    tools: params.tools.length > 0 ? params.tools : undefined,
  });
 
  // 监听流式文本事件
  stream.on('text', (text) => {
    params.onChunk(text);
  });
 
  const response = await stream.finalMessage();
  return response;
}

private buildAnthropicTools(): Anthropic.Tool[] {
  return Array.from(this.tools.values()).map((tool) => ({
    name: tool.name,
    description: tool.description,
    input_schema: {
      type: 'object' as const,
      properties: Object.fromEntries(
        Object.entries(tool.parameters).map(([key, param]) => [
          key,
          { type: param.type, description: param.description },
        ]),
      ),
      required: Object.entries(tool.parameters)
        .filter(([, param]) => param.required !== false)
        .map(([key]) => key),
    },
  }));
}

// src/tools/bash.ts
 
export function createBashTool(workspaceDir: string): ToolDefinition {
  return {
    name: 'bash',
    description:
      'Execute a bash command in the workspace directory. ' +
      'Use this for running scripts, installing packages, checking file status, etc.',
    parameters: {
      command: {
        type: 'string',
        description: 'The bash command to execute',
        required: true,
      },
    },
    execute: async (params): Promise<ToolResult> => {
      const command = params.command as string;
      return new Promise((resolve) => {
        exec(command, {
          cwd: workspaceDir,
          timeout: 30_000,    // 30 秒超时
          maxBuffer: 1024 * 1024,
          shell: '/bin/bash',
        }, (error, stdout, stderr) => {
          let output = stdout || '';
          if (stderr) output += `\nSTDERR: ${stderr}`;
 
          // 截断过长输出
          if (output.length > 10_000) {
            output = output.slice(0, 10_000) + '\n... (输出已截断)';
          }
 
          resolve({
            success: !error,
            output: output || '（命令执行成功，无输出）',
            error: error?.message,
          });
        });
      });
    },
  };
}

// src/tools/read-file.ts
 
export function createReadFileTool(workspaceDir: string): ToolDefinition {
  return {
    name: 'read_file',
    description: 'Read the contents of a file. Returns the file content with line numbers.',
    parameters: {
      file_path: {
        type: 'string',
        description: 'Path to the file to read',
        required: true,
      },
      offset: {
        type: 'number',
        description: 'Line number to start reading from (1-based)',
        required: false,
      },
      limit: {
        type: 'number',
        description: 'Maximum number of lines to read (default: 2000)',
        required: false,
      },
    },
    execute: async (params): Promise<ToolResult> => {
      const filePath = params.file_path as string;
      const resolvedPath = path.isAbsolute(filePath)
        ? filePath
        : path.resolve(workspaceDir, filePath);
 
      // 路径检查、大小检查...
 
      const content = fs.readFileSync(resolvedPath, 'utf-8');
      const lines = content.split('\n');
      const selectedLines = lines.slice(startIdx, endIdx);
 
      // 添加行号（模仿 cat -n 格式）
      const numberedLines = selectedLines.map(
        (line, i) => `${String(startIdx + i + 1).padStart(6, ' ')}  ${line}`,
      );
 
      return { success: true, output: numberedLines.join('\n') };
    },
  };
}

// src/tools/index.ts
 
export function createBuiltinTools(workspaceDir: string): ToolDefinition[] {
  return [
    createBashTool(workspaceDir),
    createReadFileTool(workspaceDir),
    createWriteFileTool(workspaceDir),
  ];
}

private buildAnthropicMessages(
  history: Message[],
  userMessage: string,
): Anthropic.MessageParam[] {
  const messages: Anthropic.MessageParam[] = [];
 
  for (const msg of history) {
    if (msg.role === 'user') {
      messages.push({ role: 'user', content: msg.content });
    } else if (msg.role === 'assistant') {
      messages.push({ role: 'assistant', content: msg.content });
    }
    // system 消息在 system prompt 中处理，不放进 messages
  }
 
  messages.push({ role: 'user', content: userMessage });
  return messages;
}