// 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);
}

// 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
  };
}

// 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"
  );
}