1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

async fn auto_compact_token_status(
    sess: &Session,
    turn_context: &TurnContext,
) -> AutoCompactTokenStatus {
    let active_context_tokens = sess.get_total_token_usage().await;
    let (auto_compact_scope_tokens, auto_compact_scope_limit, full_context_window_limit) =
        match turn_context.config.model_auto_compact_token_limit_scope {
            AutoCompactTokenLimitScope::Total => (
                active_context_tokens,
                turn_context.model_info.auto_compact_token_limit()
                    .unwrap_or(i64::MAX),
                None,
            ),
            AutoCompactTokenLimitScope::BodyAfterPrefix => {
                // 只计算前缀之后的部分（排除缓存前缀）
                let window = sess.auto_compact_window_snapshot().await;
                let baseline = window.prefill_input_tokens.unwrap_or(active_context_tokens);
                (
                    active_context_tokens.saturating_sub(baseline),
                    turn_context.config.model_auto_compact_token_limit
                        .or_else(|| turn_context.model_info.auto_compact_token_limit())
                        .unwrap_or(i64::MAX),
                    turn_context.model_context_window(),
                )
            }
        };
    // ...
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

pub(crate) async fn run_compact_task(
    sess: Arc<Session>,
    turn_context: Arc<TurnContext>,
    input: Vec<UserInput>,
) -> CodexResult<()> {
    // 手动压缩使用 DoNotInject 策略
    run_compact_task_inner(
        sess.clone(), turn_context, input,
        InitialContextInjection::DoNotInject,  // 关键区别
        CompactionTrigger::Manual,
        CompactionReason::UserRequested,
        CompactionPhase::StandaloneTurn,
    ).await
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary
for another LLM that will resume the task.

Include:
- Current progress and key decisions made
- Important context, constraints, or user preferences
- What remains to be done (clear next steps)
- Any critical data, examples, or references needed to continue

Be concise, structured, and focused on helping the next LLM seamlessly
continue the work.

1

pub const SUMMARIZATION_PROMPT: &str = include_str!("../templates/compact/prompt.md");

1
2
3
4
5
6

// TurnContext 中的 compact_prompt 方法
pub(crate) fn compact_prompt(&self) -> &str {
    self.compact_prompt
        .as_deref()
        .unwrap_or(compact::SUMMARIZATION_PROMPT)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

触发压缩（自动/手动）
    │
    ▼
run_pre_compact_hooks()          ← 钩子检查，可能中断
    │
    ▼
run_compact_task_inner_impl()
    │
    ├── 1. 发出 ContextCompactionItem Started 事件
    ├── 2. 克隆当前历史记录
    ├── 3. 将压缩 Prompt 加入历史
    │
    ▼
    ┌──────────────────────────────────┐
    │  loop {                          │
    │    构建 Prompt (history + 指令)   │
    │         │                        │
    │         ▼                        │
    │    ModelClient::stream()         │ ← 调用 OpenAI API
    │         │                        │
    │         ▼                        │
    │    drain_to_completed()          │ ← 流式接收摘要
    │         │                        │
    │    ┌─ Ok → break                 │
    │    ├─ ContextWindowExceeded      │
    │    │   → history.remove_first()  │ ← 逐条删除最旧历史
    │    │   → continue                │
    │    └─ Other Error                │
    │        → retry with backoff      │
    │  }                               │
    └──────────────────────────────────┘
    │
    ├── 4. 提取模型生成的摘要
    ├── 5. 构建 SUMMARY_PREFIX + 摘要
    ├── 6. 收集用户消息（最多 20,000 tokens）
    ├── 7. build_compacted_history()
    ├── 8. 按需注入初始上下文
    ├── 9. replace_compacted_history()
    ├── 10. recompute_token_usage()
    │
    ▼
run_post_compact_hooks()          ← 钩子检查
    │
    ▼
发出 Warning: 多次压缩可能降低准确性

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

async fn run_compact_task_inner_impl(
    sess: Arc<Session>,
    turn_context: Arc<TurnContext>,
    input: Vec<UserInput>,
    initial_context_injection: InitialContextInjection,
) -> CodexResult<String> {
    // 1. 标记压缩开始
    let compaction_item = TurnItem::ContextCompaction(ContextCompactionItem::new());
    sess.emit_turn_item_started(&turn_context, &compaction_item).await;

    // 2. 将压缩请求加入历史
    let initial_input_for_turn: ResponseInputItem = ResponseInputItem::from(input);
    let mut history = sess.clone_history().await;
    history.record_items(&[initial_input_for_turn.into()], ...);

    // 3. 调用模型生成摘要（带重试）
    let mut client_session = sess.services.model_client.new_session();
    loop {
        let turn_input = history.clone().for_prompt(...);
        let prompt = Prompt {
            input: turn_input,
            base_instructions: sess.get_base_instructions().await,
            personality: turn_context.personality,
            ..Default::default()
        };
        match drain_to_completed(&sess, turn_context.as_ref(),
                                 &mut client_session, ..., &prompt).await {
            Ok(()) => break,
            Err(CodexErr::ContextWindowExceeded) => {
                // 压缩时也超限？逐条删除最旧历史
                history.remove_first_item();
                continue;
            }
            Err(e) if retries < max_retries => {
                retries += 1;
                tokio::time::sleep(backoff(retries)).await;
                continue;
            }
            Err(e) => return Err(e),
        }
    }

    // 4. 提取摘要
    let history_snapshot = sess.clone_history().await;
    let summary_suffix = get_last_assistant_message_from_turn(history_snapshot.raw_items())
        .unwrap_or_default();
    let summary_text = format!("{SUMMARY_PREFIX}\n{summary_suffix}");

    // 5. 收集用户消息并构建压缩后历史
    let user_messages = collect_user_messages(history_snapshot.raw_items());
    let mut new_history = build_compacted_history(Vec::new(), &user_messages, &summary_text);

    // 6. 按需注入初始上下文
    if matches!(initial_context_injection, InitialContextInjection::BeforeLastUserMessage) {
        let initial_context = sess.build_initial_context(turn_context.as_ref()).await;
        new_history = insert_initial_context_before_last_real_user_or_summary(
            new_history, initial_context
        );
    }

    // 7. 替换历史
    sess.replace_compacted_history(new_history, reference_context_item, compacted_item).await;
    sess.recompute_token_usage(&turn_context).await;

    // 8. 警告
    sess.send_event(&turn_context, EventMsg::Warning(WarningEvent {
        message: "Heads up: Long threads and multiple compactions can cause the model \
                  to be less accurate. Start a new thread when possible.".to_string(),
    })).await;

    Ok(summary_suffix)
}

1
2
3
4
5
6

Another language model started to solve this problem and produced a summary
of its thinking process. You also have access to the state of the tools that
were used by that language model. Use this to build on the work that has
already been done and avoid duplicating work. Here is the summary produced
by the other language model, use the information in this summary to assist
your own analysis:

1
2

[SUMMARY_PREFIX]
[模型生成的摘要正文]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

fn build_compacted_history_with_limit(
    mut history: Vec<ResponseItem>,
    user_messages: &[String],
    summary_text: &str,
    max_tokens: usize,  // 默认 20,000
) -> Vec<ResponseItem> {
    // 1. 从后往前选取用户消息，最多 max_tokens
    let mut selected_messages: Vec<String> = Vec::new();
    let mut remaining = max_tokens;
    for message in user_messages.iter().rev() {
        if remaining == 0 { break; }
        let tokens = approx_token_count(message);
        if tokens <= remaining {
            selected_messages.push(message.clone());
            remaining = remaining.saturating_sub(tokens);
        } else {
            let truncated = truncate_text(message, TruncationPolicy::Tokens(remaining));
            selected_messages.push(truncated);
            break;
        }
    }
    selected_messages.reverse();

    // 2. 将用户消息加入新历史
    for message in &selected_messages {
        history.push(ResponseItem::Message {
            role: "user".to_string(),
            content: vec![ContentItem::InputText { text: message.clone() }],
            // ...
        });
    }

    // 3. 将摘要作为最后一条用户消息加入
    history.push(ResponseItem::Message {
        role: "user".to_string(),
        content: vec![ContentItem::InputText {
            text: summary_text.to_string()
        }],
        // ...
    });

    history
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

压缩前:                              压缩后:
┌──────────────────────┐            ┌──────────────────────┐
│ System Instructions  │            │ (空，等待下次Turn注入) │
│ Initial Context      │            │                      │
│ User: "fix bug"      │            │ User: "fix bug"      │ ← 保留的
│ Assistant: "..."      │            │ User: "add tests"    │ ← 用户消息
│ Tool: shell output   │            │                      │   (≤20K tokens)
│ User: "add tests"    │            │ User: [SUMMARY_PREFIX│
│ Assistant: "..."      │            │  + 摘要正文]          │ ← 摘要
│ Tool: shell output   │            └──────────────────────┘
│ ... (100+ items)     │
└──────────────────────┘

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

pub(crate) fn insert_initial_context_before_last_real_user_or_summary(
    mut compacted_history: Vec<ResponseItem>,
    initial_context: Vec<ResponseItem>,
) -> Vec<ResponseItem> {
    // 优先插入位置：最后一个真实用户消息之前
    // 备选位置：最后一个摘要消息之前
    // 兜底位置：追加到末尾
    let insertion_index = last_real_user_index
        .or(last_user_or_summary_index)
        .or(last_compaction_index);

    if let Some(insertion_index) = insertion_index {
        compacted_history.splice(insertion_index..insertion_index, initial_context);
    } else {
        compacted_history.extend(initial_context);
    }
    compacted_history
}

1
2
3

pub(crate) fn should_use_remote_compact_task(provider: &ModelProviderInfo) -> bool {
    provider.supports_remote_compaction()
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

async fn run_auto_compact(...) -> CodexResult<bool> {
    if should_use_remote_compact_task(turn_context.provider.info()) {
        if turn_context.features.enabled(Feature::RemoteCompactionV2) {
            run_inline_remote_auto_compact_task_v2(...).await?;
            return Ok(false);
        }
        run_inline_remote_auto_compact_task(...).await?;
    } else {
        run_inline_auto_compact_task(...).await?;
    }
    // ...
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// 压缩前 Hook
let pre_compact_outcome = run_pre_compact_hooks(&sess, &turn_context, trigger).await;
match pre_compact_outcome {
    PreCompactHookOutcome::Continue => {}  // 继续
    PreCompactHookOutcome::Stopped { reason } => {
        return Err(CodexErr::TurnAborted);  // 中断
    }
}

// 压缩后 Hook
let post_compact_outcome = run_post_compact_hooks(&sess, &turn_context, trigger).await;
if let PostCompactHookOutcome::Stopped = post_compact_outcome {
    return Err(CodexErr::TurnAborted);
}

1
2
3

触发压缩 → run_inline_auto_compact_task (本地)
         → run_inline_remote_auto_compact_task (远程 V1)
         → run_inline_remote_auto_compact_task_v2 (远程 V2)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

/compact 命令入口
    │
    ├─ 无自定义指令 → trySessionMemoryCompaction()
    │                    │ 成功 → 使用 session memory 作为摘要（快速路径）
    │                    │ 失败 ↓
    │
    ├─ Reactive-only 模式 → compactViaReactive()
    │
    └─ 传统路径 → microcompactMessages() → compactConversation()
                     │
                     ├─ streamCompactSummary()
                     │    ├─ Forked Agent（共享 Prompt Cache）
                     │    └─ 流式回退（独立 API 调用）
                     │
                     └─ 生成 post-compact 附件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary
for another LLM that will resume the task.

Include:
- Current progress and key decisions made
- Important context, constraints, or user preferences
- What remains to be done (clear next steps)
- Any critical data, examples, or references needed to continue

Be concise, structured, and focused on helping the next LLM seamlessly
continue the work.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

// 源码中的 NO_TOOLS_PREAMBLE（防止模型调用工具）
const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.

- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
- You already have all the context you need in the conversation above.
- Tool calls will be REJECTED and will waste your only turn — you will
  fail the task.
- Your entire response must be plain text: an <analysis> block followed
  by a <summary> block.
`

// 主体 Prompt（BASE_COMPACT_PROMPT）
const BASE_COMPACT_PROMPT = `Your task is to create a detailed summary of the
conversation so far, paying close attention to the user's explicit requests
and your previous actions.

This summary should be thorough in capturing technical details, code patterns,
and architectural decisions that would be essential for continuing development
work without losing context.

Before providing your final summary, wrap your analysis in <analysis> tags
to organize your thoughts and ensure you've covered all necessary points.
In your analysis process:

1. Chronologically analyze each message and section of the conversation.
   For each section thoroughly identify:
   - The user's explicit requests and intents
   - Your approach to addressing the user's requests
   - Key decisions, technical concepts and code patterns
   - Specific details like: file names, full code snippets,
     function signatures, file edits
   - Errors that you ran into and how you fixed them
   - Pay special attention to specific user feedback that you received

2. Double-check for technical accuracy and completeness.

Your summary should include the following sections:

1. Primary Request and Intent
2. Key Technical Concepts
3. Files and Code Sections
4. Errors and fixes
5. Problem Solving
6. All user messages
7. Pending Tasks
8. Current Work
9. Optional Next Step
`

1
2
3
4
5
6

Another language model started to solve this problem and produced a summary
of its thinking process. You also have access to the state of the tools that
were used by that language model. Use this to build on the work that has
already been done and avoid duplicating work. Here is the summary produced
by the other language model, use the information in this summary to assist
your own analysis:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

export function getCompactUserSummaryMessage(
  summary: string,
  suppressFollowUpQuestions?: boolean,
  transcriptPath?: string,
  recentMessagesPreserved?: boolean,
): string {
  const formattedSummary = formatCompactSummary(summary)

  let baseSummary = `This session is being continued from a previous conversation
that ran out of context. The summary below covers the earlier portion of
the conversation.

${formattedSummary}`

  if (transcriptPath) {
    baseSummary += `\n\nIf you need specific details from before compaction
(like exact code snippets, error messages, or content you generated),
read the full transcript at: ${transcriptPath}`
  }

  if (recentMessagesPreserved) {
    baseSummary += `\n\nRecent messages are preserved verbatim.`
  }

  if (suppressFollowUpQuestions) {
    baseSummary += `\nContinue the conversation from where it left off
without asking the user any further questions. Resume directly — do not
acknowledge the summary, do not recap what was happening, do not preface
with "I'll continue" or similar. Pick up the last task as if the break
never happened.`
  }

  return baseSummary
}

1

压缩后历史 = [初始上下文(可选)] + [保留的用户消息(≤20K tokens)] + [摘要]

1
2

压缩后历史 = [boundaryMarker] + [summaryMessages] + [messagesToKeep]
           + [attachments] + [hookResults]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

// 1. 文件附件（最多 5 个文件，总计 50K tokens）
const [fileAttachments, asyncAgentAttachments] = await Promise.all([
  createPostCompactFileAttachments(preCompactReadFileState, context, 5),
  createAsyncAgentAttachmentsIfNeeded(context),
])

// 2. Plan 附件
const planAttachment = createPlanAttachmentIfNeeded(context.agentId)

// 3. Plan Mode 附件
const planModeAttachment = await createPlanModeAttachmentIfNeeded(context)

// 4. Skill 附件（每个最多 5K tokens，总计最多 25K tokens）
const skillAttachment = createSkillAttachmentIfNeeded(context.agentId)

// 5. 工具/MCP/Agent Delta 附件（重新宣告完整集合）
for (const att of getDeferredToolsDeltaAttachment(...)) { ... }
for (const att of getAgentListingDeltaAttachment(...)) { ... }
for (const att of getMcpInstructionsDeltaAttachment(...)) { ... }

1
2
3
4
5

export const POST_COMPACT_MAX_FILES_TO_RESTORE = 5
export const POST_COMPACT_TOKEN_BUDGET = 50_000
export const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000
export const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000
export const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// src/services/compact/compact.ts:1494
export function createSkillAttachmentIfNeeded(
  agentId?: string,
): AttachmentMessage | null {
  const invokedSkills = getInvokedSkillsForAgent(agentId)
  if (invokedSkills.size === 0) return null

  // 按最近调用排序，预算压力下丢弃最久未用的
  let usedTokens = 0
  const skills = Array.from(invokedSkills.values())
    .sort((a, b) => b.invokedAt - a.invokedAt)
    .map(skill => ({
      name: skill.skillName,
      path: skill.skillPath,
      content: truncateToTokens(skill.content, POST_COMPACT_MAX_TOKENS_PER_SKILL),
    }))
    .filter(skill => {
      const tokens = roughTokenCountEstimation(skill.content)
      if (usedTokens + tokens > POST_COMPACT_SKILLS_TOKEN_BUDGET) return false
      usedTokens += tokens
      return true
    })

  return createAttachmentMessage({ type: 'invoked_skills', skills })
}

1
2
3
4
5
6
7

function truncateToTokens(content: string, maxTokens: number): string {
  if (roughTokenCountEstimation(content) <= maxTokens) return content
  const charBudget = maxTokens * 4 - SKILL_TRUNCATION_MARKER.length
  return content.slice(0, charBudget) + SKILL_TRUNCATION_MARKER
  // SKILL_TRUNCATION_MARKER = '[... skill content truncated for compaction;
  //   use Read on the skill path if you need the full text]'
}

1
2
3
4

// src/services/compact/sessionMemoryCompact.ts:484-485
const planAttachment = createPlanAttachmentIfNeeded(agentId)
const attachments = planAttachment ? [planAttachment] : []
// 注意：没有 createSkillAttachmentIfNeeded() 调用

1
2
3
4
5

// src/services/compact/sessionMemoryCompact.ts:571-581
const startIndex = calculateMessagesToKeepIndex(messages, lastSummarizedIndex)
const messagesToKeep = messages
  .slice(startIndex)
  .filter(m => !isCompactBoundaryMessage(m))

1
2
3
4
5
6

// src/services/compact/sessionMemoryCompact.ts:605-614
if (autoCompactThreshold !== undefined &&
    postCompactTokenCount >= autoCompactThreshold) {
  logEvent('tengu_sm_compact_threshold_exceeded', { ... })
  return null  // 放弃，回退到传统路径
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// src/services/compact/compact.ts:1179-1200
if (promptCacheSharingEnabled) {
  const result = await runForkedAgent({
    promptMessages: [summaryRequest],
    cacheSafeParams,
    canUseTool: createCompactCanUseTool(),
    querySource: 'compact',
    forkLabel: 'compact',
    maxTurns: 1,
    skipCacheWrite: true,
    overrides: { abortController: context.abortController },
  })
}