system prompt
project instructions
memory
recent transcript
retrieved docs
tool results
current user input

// ContextBudget = 一次模型请求的上下文预算。
// 重点：输入不能把上下文窗口塞满，要给模型输出预留空间。
type ContextBudget = {
  maxInputTokens: number;        // 模型上下文窗口最大输入 token。
  reservedOutputTokens: number;  // 给模型回答预留的 token。
  systemTokens: number;          // system prompt 预计占用。
  memoryTokens: number;          // 记忆预计占用。
  historyTokens: number;         // 历史对话预计占用。
  retrievalTokens: number;       // 检索资料预计占用。
  toolResultTokens: number;      // 工具结果预计占用。
};

// getAvailableInputTokens = 当前真正可用于输入 messages 的 token。
function getAvailableInputTokens(budget: ContextBudget) {
  return budget.maxInputTokens - budget.reservedOutputTokens;
}

// buildContext = 上下文构建总入口。
// 它把 system、项目规则、记忆、检索、历史、当前用户输入拼成 messages。
export async function buildContext(input: BuildContextInput): Promise<Message[]> {
  // 根据模型上下文窗口创建预算。
  const budget = createBudget(input.model);

  // 每一块上下文都先抽象成 ContextPart，带优先级和 token 估算。
  const parts: ContextPart[] = [
    await systemPart(),
    await projectInstructionsPart(input.cwd),
    await memoryPart(input.userInput),
    await retrievalPart(input.userInput),
    await recentTranscriptPart(input.sessionId),
    currentUserPart(input.userInput)
  ];

  // 根据预算选择哪些块完整保留、哪些压缩、哪些丢弃。
  const selected = fitPartsIntoBudget(parts, budget);

  // 最终转成模型 messages。
  return selected.map(part => ({
    role: part.role,
    content: part.content
  }));
}

// ContextPart = 一个可独立选择/压缩的上下文块。
// 例如 system rules、memory、retrieved docs、recent transcript 都是 part。
type ContextPart = {
  name: string; // 块名称，例如 "memory"、"retrieval"。
  role: "system" | "user" | "assistant" | "tool"; // 放进 messages 时的 role。
  priority: number; // 数字越小优先级越高，越不能丢。
  content: string; // 这块上下文正文。
  estimatedTokens: number; // 估算 token，用于预算选择。
  compressible: boolean; // 超预算时是否允许摘要压缩。
};

// fitPartsIntoBudget = 在预算内选择上下文块。
// 策略：先按优先级选，高优先级保留；低优先级必要时压缩或丢弃。
function fitPartsIntoBudget(parts: ContextPart[], budget: ContextBudget) {
  // 计算输入可用 token。
  const max = getAvailableInputTokens(budget);

  // 按 priority 排序，P0/P1 先处理。
  const sorted = [...parts].sort((a, b) => a.priority - b.priority);

  const selected: ContextPart[] = [];
  let used = 0;

  for (const part of sorted) {
    // 如果完整放得下，直接保留。
    if (used + part.estimatedTokens <= max) {
      selected.push(part);
      used += part.estimatedTokens;
      continue;
    }

    // 如果放不下但允许压缩，就尝试压缩到剩余预算内。
    if (part.compressible) {
      const compressed = compressPartToFit(part, max - used);
      if (compressed) {
        selected.push(compressed);
        used += compressed.estimatedTokens;
      }
    }
  }

  // 选择时按优先级，但输出 messages 时要恢复合理顺序。
  // 例如 system 仍然要在 user 前面。
  return selected.sort((a, b) => originalOrder(a.name) - originalOrder(b.name));
}

// estimateTokens = 粗略 token 估算。
// 中文/英文/tokenizer 差异很大，这只是入门兜底。
function estimateTokens(text: string) {
  return Math.ceil(text.length / 2);
}

// projectInstructionsPart = 读取项目规则文件。
// 这些规则会影响 Agent 如何读写代码，所以优先级高。
async function projectInstructionsPart(cwd: string): Promise<ContextPart> {
  // 常见项目规则来源。
  const candidates = ["AGENTS.md", "CLAUDE.md", "README.md"];
  const chunks: string[] = [];

  for (const file of candidates) {
    // 文件不存在就跳过。
    const content = await readFileIfExists(resolve(cwd, file));
    if (content) {
      // 每个规则文件都限长，防止 README 巨大。
      chunks.push(`# ${file}\n${content.slice(0, 12_000)}`);
    }
  }

  const content = chunks.join("\n\n");

  return {
    name: "project_instructions",
    role: "system",
    priority: 1,
    content,
    estimatedTokens: estimateTokens(content),
    compressible: true
  };
}

// Memory = 长期记忆的一条记录。
// 记忆不是聊天历史，而是跨任务可复用的稳定事实/偏好/决策。
type Memory = {
  id: string; // 记忆 ID。
  scope: "user" | "project"; // 用户级还是项目级。
  type: "preference" | "fact" | "decision" | "todo"; // 记忆类型。
  content: string; // 记忆正文。
  updatedAt: string; // 更新时间，用于排序和淘汰旧信息。
};

// memoryPart = 选出与当前任务相关的记忆，拼成上下文块。
async function memoryPart(userInput: string): Promise<ContextPart> {
  // 加载所有记忆，但不会全量塞给模型。
  const memories = await loadAllMemory();

  // 按相关性排序，只取前 12 条。
  const ranked = rankMemory(memories, userInput).slice(0, 12);

  // 带上 type，模型能区分偏好、事实、决策、任务项。
  const content = ranked
    .map(memory => `- [${memory.type}] ${memory.content}`)
    .join("\n");

  return {
    name: "memory",
    role: "system",
    priority: 2,
    content: `Relevant long-term memory:\n${content}`,
    estimatedTokens: estimateTokens(content),
    compressible: true
  };
}

// rankMemory = 入门版记忆相关性排序。
// 用查询词和记忆内容的词重叠数打分。
function rankMemory(memories: Memory[], query: string) {
  // 把用户输入切词成集合。
  const words = new Set(query.toLowerCase().split(/\s+/));

  return memories
    .map(memory => ({
      memory,
      // 统计 memory.content 中有多少词出现在 query 里。
      score: memory.content
        .toLowerCase()
        .split(/\s+/)
        .filter(word => words.has(word)).length
    }))
    // 分数高的排前面。
    .sort((a, b) => b.score - a.score)
    .map(item => item.memory);
}

保留最近 8-12 条
更早历史压成 summary
summary 只保留目标、决策、修改、失败、下一步

// recentTranscriptPart = 构建会话历史上下文块。
// 策略：最近消息原文保留，更早历史压成 summary。
async function recentTranscriptPart(sessionId: string): Promise<ContextPart> {
  // 读取完整会话记录。
  const transcript = await loadTranscript(sessionId);

  // 最近 12 条保留原文，保证连续性。
  const recent = transcript.slice(-12);

  // 更早的消息进入摘要。
  const older = transcript.slice(0, -12);

  // 如果有旧消息，加载或创建摘要。
  const summary = older.length
    ? await loadOrCreateSummary(sessionId, older)
    : "";

  const content = [
    summary ? `Previous summary:\n${summary}` : "",
    `Recent messages:\n${formatMessages(recent)}`
  ].filter(Boolean).join("\n\n");

  return {
    name: "transcript",
    role: "system",
    priority: 3,
    content,
    estimatedTokens: estimateTokens(content),
    compressible: true
  };
}

Summarize the previous agent session for continuation.

Keep:
1. User's goal.
2. Files inspected.
3. Files modified.
4. Commands run and meaningful results.
5. Decisions made.
6. Failed attempts and why they failed.
7. Current next step.

Drop:
1. Chit-chat.
2. Repeated logs.
3. Full command output unless essential.
4. Outdated speculation.

// formatToolResult = 控制工具结果放进上下文的长度。
// 工具输出很容易超长，例如 grep、test、日志。
function formatToolResult(result: ToolResult) {
  const max = 16_000;

  // 不超限就原样返回。
  if (result.content.length <= max) {
    return result.content;
  }

  // 超限时截断，并附上 summary 告诉模型这不是完整输出。
  return [
    result.content.slice(0, max),
    `\n[Tool output truncated. Summary: ${result.summary}]`
  ].join("");
}

// RetrievedChunk = RAG 检索出来的一段资料。
// 必须保留来源，否则模型回答无法追溯。
type RetrievedChunk = {
  sourcePath: string; // 来源文件路径。
  titlePath: string;  // 文档标题路径或层级标题。
  content: string;    // 片段正文。
  score: number;      // 检索相关性分数。
};

// formatRetrievedChunks = 把 RAG 片段格式化给模型。
function formatRetrievedChunks(chunks: RetrievedChunk[]) {
  return chunks.map((chunk, index) => `
[Source ${index + 1}]
path: ${chunk.sourcePath}
title: ${chunk.titlePath}
score: ${chunk.score}
content:
${chunk.content}
`).join("\n");
}

Answer using the provided sources.
If the sources do not contain the answer, say you are not sure.
Cite source paths when making factual claims.

1. system base rules
2. safety and permission rules
3. project instructions
4. relevant memory
5. previous summary
6. recent transcript
7. retrieved sources
8. latest tool result
9. current user input

// saveContextDebug = 保存最终发给模型的 messages。
// 它是排查“模型到底看到了什么”的关键工具。
async function saveContextDebug(sessionId: string, messages: Message[]) {
  await writeFile(
    `.agent/debug/${sessionId}-context.json`,
    JSON.stringify(messages, null, 2),
    "utf8"
  );
}

// selectMemories = 从长期记忆里选出本轮真正该给模型看的部分。
function selectMemories(memories: MemoryRecord[], task: TaskContext) {
  return memories
    .filter(m => m.scope === "global" || m.scope === task.projectId) // 不跨项目乱带
    .filter(m => !m.expiresAt || m.expiresAt > task.now)             // 过期记忆不进上下文
    .map(m => ({
      memory: m,
      score: relevance(m, task) + recencyBoost(m) + confidenceBoost(m)
    }))
    .filter(item => item.score >= task.memoryThreshold)
    .sort((a, b) => b.score - a.score)
    .slice(0, task.maxMemories)
    .map(item => item.memory);
}