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

触发压缩 → trySessionMemoryCompaction() (快速路径)
              │ 成功 → 使用 session memory 作为摘要
              │ 失败 ↓
         → compactConversation() (传统路径)
              → 现场调用 summarizer 生成摘要

1
2
3
4

You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary
for another LLM that will resume the task.
Include: progress, context, next steps, critical data.
Be concise, structured, and focused on helping the next LLM seamlessly continue.

1

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

1

压缩后历史 = [摘要] + [post-compact 附件] + [最近消息片段]