第 9 讲系统提示词、上下文组装与压缩（Compaction）

// buildSystemPromptSections() 主体（节选，省略段名校验与选项归一化）
const promptSections: Record<string, string> = {};
if (customPrompt) {
  promptSections.preamble = customPrompt;          // .pi/SYSTEM.md：整体替换默认前缀
} else {
  promptSections.preamble =
    "You are a coding assistant running inside pi, a coding agent harness. ...";
  promptSections.tools   = `${tools}\n\nAdditional tools may be available.`;
  promptSections.rules   = buildRules(declaredTools, toolGuidelines, promptGuidelines);
  promptSections.docs    = `Pi documentation (read only when the user asks about ...)`;
}
if (appendSystemPrompt) promptSections.addendum = appendSystemPrompt;
if (contextFiles.length > 0) promptSections.project_context = renderProjectContext(contextFiles);
if (skillFileReadTool && skills.length > 0) {
  promptSections.skills = formatSkillsForPrompt(skills, skillFileReadTool).trim();
}
promptSections.cwd = cwd.replace(/\\/g, "/");
for (const [name, content] of Object.entries(customSections)) {
  if (content) promptSections[name] = content;    // 扩展自定义段落
}
// 输出：preamble 裸文本，其余段落用同名标签包裹（节选结束）
const sections: SystemPromptSections = { preamble: promptSections.preamble };
for (const [name, content] of Object.entries(promptSections)) {
  if (name !== "preamble") sections[name] = `<${name}>\n${content}\n</${name}>`;
}

/** 模型当前已有的 sections（从 transcript 重放，永不为 null）与期望 sections 求差，
 *  返回 SystemMessage.sections 补丁；无变化返回 undefined。 */
export function diffSystemPromptSections(
  previous: Record<string, string | null>,
  current: SystemPromptSections,
): Record<string, string | null> | undefined {
  const patch: Record<string, string | null> = {};
  for (const [name, text] of Object.entries(current)) {
    if (previous[name] !== text) patch[name] = text;      // 内容不同，记录新版本
  }
  for (const name of Object.keys(previous)) {
    if (current[name] === undefined) patch[name] = null;   // 段落消失，null 表示删除
  }
  return Object.keys(patch).length > 0 ? patch : undefined;
}

function loadContextFileFromDir(dir: string): { path: string; content: string } | null {
  const candidates = ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
  for (const filename of candidates) {
    const filePath = join(dir, filename);
    if (existsSync(filePath)) {
      try {
        if (!statSync(filePath).isFile()) continue;
        return { path: filePath, content: stripBom(readFileSync(filePath, "utf-8")) };
      } catch (error) {
        console.error(chalk.yellow(`Warning: Could not read ${filePath}: ${error}`));
      }
    }
  }
  return null;
}

// loadProjectContextFiles() 主体（节选）
const contextFiles: Array<{ path: string; content: string }> = [];
const seenPaths = new Set<string>();
const globalContext = loadContextFileFromDir(resolvedAgentDir);   // 全局 ~/.pi/agent
if (globalContext) { contextFiles.push(globalContext); seenPaths.add(globalContext.path); }

const ancestorContextFiles: Array<{ path: string; content: string }> = [];
let currentDir = resolvedCwd;
while (true) {                                                    // cwd 向上到根
  const contextFile = loadContextFileFromDir(currentDir);
  if (contextFile && !isShadowed && !seenPaths.has(contextFile.path)) {
    ancestorContextFiles.unshift(contextFile);                    // unshift：根在前，cwd 在后
    seenPaths.add(contextFile.path);
  }
  const parentDir = dirname(currentDir);
  if (parentDir === currentDir) break;                            // 到达文件系统根
  currentDir = parentDir;
}
contextFiles.push(...ancestorContextFiles);

export function formatSkillsForPrompt(skills: Skill[], fileReadTool: "read" | "bash" | "indirect" = "read"): string {
  const visibleSkills = skills.filter((s) => !s.disableModelInvocation);   // 命令专属技能不进提示词
  if (visibleSkills.length === 0) return "";
  const lines = [
    "\n\nThe following skills provide specialized instructions for specific tasks.",
    fileReadTool === "read"
      ? "Use the read tool to load a skill's file when the task matches its description."
      : fileReadTool === "bash"
        ? "Use bash to load a skill's file when the task matches its description."
        : "Load a skill's file when the task matches its description.",
    "Resolve relative paths against the skill's directory (parent of SKILL.md). Use absolute paths in tool calls.",
    "", "<available_skills>",
  ];
  for (const skill of visibleSkills) {
    lines.push("  <skill>");
    lines.push(`    <name>${escapeXml(skill.name)}</name>`);
    lines.push(`    <description>${escapeXml(skill.description)}</description>`);
    lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);
    lines.push("  </skill>");
  }
  lines.push("</available_skills>");
  return lines.join("\n");
}

export interface CompactionSettings {
  enabled: boolean;
  reserveTokens: number;      // 剩余空间警戒线
  keepRecentTokens: number;   // 保留边界：近期消息预算
}

export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
  enabled: true,
  reserveTokens: 16384,
  keepRecentTokens: 20000,
};

export function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean {
  if (!settings.enabled) return false;
  return contextTokens > contextWindow - settings.reserveTokens;   // 128k 窗口约 111.6k 触发
}

// findCutPoint() 核心回溯（节选）
let accumulatedTokens = 0;
let cutIndex = cutPoints[0];                       // 兜底：从第一条可切消息保起
for (let i = endIndex - 1; i >= startIndex; i--) {
  const messageTokens = sessionEntryToContextMessages(entries[i])
    .reduce((sum, m) => sum + estimateTokens(m), 0);
  if (messageTokens === 0) continue;
  accumulatedTokens += messageTokens;
  if (accumulatedTokens >= keepRecentTokens) {
    cutIndex = cutPoints.find((c) => c >= i) ?? cutPoints[cutPoints.length - 1];
    break;
  }
}
// 切点不是回合起点时 isSplitTurn = true，turnStartIndex 指向该回合的 user 消息

interface CompactionEntry<T = unknown> {
  type: "compaction";
  id: string;
  parentId: string | null;
  timestamp: string;
  summary: string;
  firstKeptEntryId: string;   // 保留消息从哪条开始
  tokensBefore: number;
  usage?: Usage;              // 生成摘要的 LLM 用量，计入会话总账
  fromHook?: boolean;         // 扩展提供时为 true（兼容旧字段名）
  details?: T;                // 默认 { readFiles, modifiedFiles }，扩展可存任意 JSON
  systemMessage?: SystemMessage;  // 压缩边界处的完整提示词与工具状态快照
}

/** 摘要响应无法安全持久化时返回错误信息；length 截断 = 半截 checkpoint，绝不能落盘 */
export function getSummarizationFailure(response: AssistantMessage, label: string): string | undefined {
  if (response.stopReason === "error") {
    return `${label} failed: ${response.errorMessage || "Unknown error"}`;
  }
  if (response.stopReason === "length") {
    return `${label} failed: generation hit the token cap and the summary is incomplete`;
  }
  return undefined;
}

// completeSummarization()：一次性摘要不写缓存；未传 sessionId 时生成新路由 ID
const requestOptions: SimpleStreamOptions = {
  ...options,
  cacheRetention: "none",
  sessionId: options.sessionId ?? uuidv7(),
};

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000,
    "modelOverrides": {
      "some-provider/big-model": { "reserveTokens": 400000 }
    }
  }
}

private _installAgentForcedPromptProjection(): void {
  const previousTransformContext = this.agent.transformContext;      // 链式：先跑上一层
  this.agent.transformContext = async (messages, signal) => {
    const transformed = previousTransformContext
      ? await previousTransformContext(messages, signal) : messages;
    const forced = this._runSystemPromptOptions?.forceSystemPrompt;
    if (forced === undefined) return transformed;
    const current = getCurrentSystemMessage(transformed);
    const head: SystemMessage = {
      role: "system",
      content: forced,
      ...(current?.toolsAdded ? { toolsAdded: current.toolsAdded } : {}),
      timestamp: current?.timestamp ?? Date.now(),
    };
    return [head, ...transformed.filter((message) => message.role !== "system")];
  };
}

transformContext: async (messages) => {
  const runner = extensionRunnerRef.current;
  if (!runner) return messages;
  return runner.emitContext(messages);   // 每个扩展可裁剪 / 注入 / 替换出站消息
},

pi.on("session_before_compact", async (event, ctx) => {
  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;
  // preparation: messagesToSummarize / turnPrefixMessages / previousSummary
  //              fileOps / tokensBefore / firstKeptEntryId / settings
  // reason: "manual" | "threshold" | "overflow"

  return { cancel: true };                 // 取消本次压缩
  // 或提供自定义摘要：
  // return { compaction: { summary, firstKeptEntryId: preparation.firstKeptEntryId,
  //                        tokensBefore: preparation.tokensBefore, usage, details } };
});

pi.on("session_compact_failed", async (event, ctx) => {
  const { reason, errorMessage, aborted, willRetry, fromExtension } = event;
});