// ContextPart = 一个可独立管理的上下文块。
// 先拆块，后面才能按优先级裁剪、压缩和 debug。
export type ContextPart = {
  name: string; // 块名，例如 memory、project_instructions。
  role: "system" | "user" | "assistant" | "tool"; // 放进模型 messages 时的角色。
  priority: number; // 数字越小优先级越高，越不该丢。
  content: string; // 上下文正文。
  estimatedTokens: number; // 估算 token，用于预算判断。
  compressible: boolean; // 超预算时是否允许摘要压缩。
};

// ContextBudget = 本次模型请求的上下文预算。
export type ContextBudget = {
  maxInputTokens: number;       // 最大输入 token。
  reservedOutputTokens: number; // 给模型输出预留的 token。
};

// availableInputTokens = 实际可用于 messages 的输入 token。
export function availableInputTokens(budget: ContextBudget) {
  return budget.maxInputTokens - budget.reservedOutputTokens;
}

// buildContext = 上下文构建总入口。
// 它不直接拼一个大 prompt，而是先构造 ContextPart，再按预算选择。
export async function buildContext(input: BuildContextInput): Promise<Message[]> {
  // 根据模型上下文窗口创建预算。
  const budget = createBudget(input.model);

  // 每个来源都是一个 ContextPart。
  const parts: ContextPart[] = [
    await systemPart(),
    await projectInstructionsPart(input.cwd),
    await memoryPart(input.userInput),
    await transcriptPart(input.sessionId),
    await retrievalPart(input.userInput),
    currentUserPart(input.userInput)
  ];

  // 在预算内选择/压缩上下文块。
  const selected = await fitPartsIntoBudget(parts, budget);

  // 保存 debug 快照，方便排查模型到底看到了什么。
  await saveContextDebug(input.sessionId, selected);

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

// fitPartsIntoBudget = 上下文预算裁剪函数。
async function fitPartsIntoBudget(
  parts: ContextPart[],
  budget: ContextBudget
): Promise<ContextPart[]> {
  // 可用输入 token。
  const max = availableInputTokens(budget);

  // 按优先级选择，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 = await compressPart(part, max - used);
      if (compressed) {
        selected.push(compressed);
        used += compressed.estimatedTokens;
      }
    }
  }

  // 输出时恢复正确上下文顺序，不按 priority 排列。
  return restoreContextOrder(selected);
}

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

// projectInstructionsPart = 读取项目规则文件。
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",               // 项目规则属于 system 级约束。
    priority: 1,                   // 高优先级。
    content,                       // 规则正文。
    estimatedTokens: estimateTokens(content), // token 估算。
    compressible: true             // 可摘要，但不应完全丢。
  };
}

// Memory = 长期记忆，不是聊天记录。
export 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);

  // 记忆要带 scope/type，让模型知道这是偏好、事实还是任务项。
  const content = ranked.map(memory =>
    `- [${memory.scope}/${memory.type}] ${memory.content}`
  ).join("\n");

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

最近 8-12 条原样保留
更早历史压缩成 summary

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

  // 最近 12 条原样保留。
  const recent = transcript.slice(-12);

  // 更早部分准备压缩。
  const older = transcript.slice(0, -12);

  // 有旧历史才生成/读取 summary。
  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
  };
}

// formatToolResult = 工具结果上下文格式化。
// 目标：不要让超长工具输出挤爆上下文。
function formatToolResult(result: ToolResult) {
  const max = 16_000;

  // 不超限就完整放入。
  if (result.content.length <= max) {
    return result.content;
  }

  // 超限就截断，并明确提示模型“这不是完整输出”。
  return [
    result.content.slice(0, max),
    `\n[Tool output truncated. Summary: ${result.summary}]`
  ].join("");
}

// saveContextDebug = 保存最终上下文快照。
// 调试时最重要的问题是：模型到底看到了什么？
async function saveContextDebug(sessionId: string, parts: ContextPart[]) {
  await writeFile(
    `.agent/debug/${sessionId}-context.json`,
    JSON.stringify(parts.map(part => ({
      name: part.name,                    // 哪个上下文块。
      priority: part.priority,            // 优先级。
      estimatedTokens: part.estimatedTokens, // 估算 token。
      contentPreview: part.content.slice(0, 500) // 只保存预览，避免 debug 文件太大。
    })), null, 2),
    "utf8"
  );
}