message flow

本章介绍 Claude Code 中消息的构建、发送和处理机制。

消息类型

Anthropic API 消息格式

type Message = {
  role: 'user' | 'assistant';
  content: string | ContentBlock[];
};

type ContentBlock =
  | { type: 'text'; text: string }
  | { type: 'tool_use'; id: string; name: string; input: any }
  | { type: 'tool_result'; tool_use_id: string; content: string };

内部消息格式

interface InternalMessage {
  id: string;
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp: number;
  metadata?: {
    tokenCount?: number;
    compressed?: boolean;
    toolCalls?: ToolCall[];
  };
}

消息构建流程

1

用户输入处理

function processUserInput(input: string): Message {
  // 1. 解析上下文引用 (#File, #Folder)
  const references = parseContextReferences(input);
  
  // 2. 读取引用的文件内容
  const contextBlocks = await loadReferences(references);
  
  // 3. 构建消息
  return {
    role: 'user',
    content: [
      { type: 'text', text: input },
      ...contextBlocks,
    ],
  };
}

2

System Prompt 构建

async function buildSystemPrompt(
  tools: Tool[],
  config: Config
): Promise<string> {
  const parts = [
    // 静态部分 (缓存)
    IDENTITY_PROMPT,
    CAPABILITIES_PROMPT,
    RULES_PROMPT,
    
    // 动态部分
    buildToolsPrompt(tools),
    buildSkillsPrompt(config.skills),
    buildSteeringPrompt(config.steering),
  ];
  
  return parts.join('\n\n');
}

3

工具结果处理

function formatToolResult(result: ToolResult): ContentBlock {
  if (result.success) {
    return {
      type: 'tool_result',
      tool_use_id: result.id,
      content: truncateIfNeeded(result.output, MAX_TOOL_RESULT_SIZE),
    };
  } else {
    return {
      type: 'tool_result',
      tool_use_id: result.id,
      content: `Error: ${result.error}`,
      is_error: true,
    };
  }
}

消息压缩

Tool Result Budget

限制单个工具结果的大小：

const MAX_TOOL_RESULT_SIZE = 50000; // 字符

function truncateToolResult(content: string): string {
  if (content.length <= MAX_TOOL_RESULT_SIZE) {
    return content;
  }
  
  // 保留开头和结尾
  const head = content.slice(0, MAX_TOOL_RESULT_SIZE * 0.7);
  const tail = content.slice(-MAX_TOOL_RESULT_SIZE * 0.3);
  
  return `${head}\n\n[... truncated ${content.length - MAX_TOOL_RESULT_SIZE} characters ...]\n\n${tail}`;
}

Microcompact

压缩工具调用历史：

function microcompact(messages: Message[]): Message[] {
  return messages.map(msg => {
    if (msg.role === 'assistant' && hasToolCalls(msg)) {
      // 只保留工具调用，移除思考过程
      return {
        ...msg,
        content: msg.content.filter(
          block => block.type === 'tool_use'
        ),
      };
    }
    return msg;
  });
}

Context Collapse

折叠旧对话轮次：

function contextCollapse(messages: Message[]): Message[] {
  const recent = messages.slice(-10); // 保留最近 10 条
  const old = messages.slice(0, -10);
  
  // 将旧消息折叠为摘要
  const summary = {
    role: 'user',
    content: `[Earlier conversation summary: ${summarize(old)}]`,
  };
  
  return [summary, ...recent];
}

消息路由

本地执行

// 直接调用 Anthropic API
const response = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  messages: messages,
  tools: tools,
});

Bridge 模式

// 通过 WebSocket 发送到远程
await bridge.send({
  type: 'query',
  messages: messages,
  tools: tools,
});

// 接收流式响应
for await (const event of bridge.receive()) {
  yield event;
}

下一步

• 了解 System Prompt 的详细构建

• 查看 上下文管理 的压缩策略

• 探索 工具系统 的执行机制