3.1 dispatch 层只负责启动压缩#

在 slash_dispatch.rs 中，Compact 分支做了几件很具体的事情：清空当前 token 统计，设置“正在压缩”的状态，标记用户 turn 已排队，最后发送 AppEvent::Compact。它不会在 TUI 里拼接摘要，也不会直接读取 transcript。

1
SlashCommand::Compact => {
2
    if self.blocks_direct_input {
3
        self.add_error_message(PARENT_OWNED_INPUT_MESSAGE.to_string());
4
        return;
5
    }
6
    self.clear_token_usage();
7
    if !self.bottom_pane.is_task_running() {
8
        self.bottom_pane.set_task_running(/*running*/ true);
9
    }
10
    self.bottom_pane.ensure_status_indicator();
11
    self.set_status(
12
        compaction::COMPACTION_HEADER.to_string(),
13
        Some(compaction::COMPACTION_DETAILS.to_string()),
14
        StatusDetailsCapitalization::Preserve,
15
        STATUS_DETAILS_DEFAULT_MAX_LINES,
16
    );
17
    self.input_queue.user_turn_pending_start = true;
18
    self.app_event_tx.compact();
19
}

上面是 Compact 的 TUI dispatch 分支 的真实节选。应用层收到事件后，经由 thread_routing.rs 调用 thread_compact_start(thread_id)，再由 app-server 的 ThreadCompactStart 处理器 提交 Op::Compact。这样设计的好处是手动压缩和远程客户端发起的压缩可以复用同一个线程入口。

3.2 核心任务有三种实现选择#

core/src/tasks/compact.rs 把压缩建模成 SessionTask，任务类型是 TaskKind::Compact。run 方法按能力和配置选择实现：

1. 启用 TokenBudget 路径时，使用 token budget 专用实现。
2. provider 支持 remote compaction V2 时，把当前 prompt 和历史交给远端压缩接口。
3. 其他情况使用本地压缩：调用普通模型，携带 SUMMARIZATION_PROMPT，再由本地会话安装结果。

1
let result = match ctx.provider.capabilities().remote_compaction {
2
    RemoteCompactionSupport::V2 => {
3
        crate::compact_remote_v2::run_remote_compact_task(session.clone(), ctx).await
4
    }
5
    RemoteCompactionSupport::Unsupported => {
6
        let input = vec![UserInput::Text {
7
            text: ctx.config.compact_prompt.as_deref()
8
                .unwrap_or(crate::compact::SUMMARIZATION_PROMPT).to_string(),
9
            text_elements: Vec::new(),
10
        }];
11
        crate::compact::run_compact_task(session.clone(), ctx, input).await
12
    }
13
};

这是 CompactTask 选择逻辑 的结构节选。它省去了 token-budget 提前返回、埋点和错误收尾；实际函数先检查该 feature，再选择远程或本地路径。重要的不是分支名字，而是压缩并非固定由某一个模型或某一种 API 完成。

3.3 本地压缩的 prompt 是一个交接摘要契约#

本地路径把当前历史作为模型输入，并使用内置的 SUMMARIZATION_PROMPT。模板要求输出给“下一个继续任务的 LLM”，至少覆盖进度、关键决策、约束和偏好、剩余步骤，以及继续工作所需的资料。

1
You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM.

完整模板还要求摘要覆盖进度、关键决策、约束和偏好、剩余步骤及关键资料，见 compact/prompt.md。这里的“交接”很关键：摘要不是给用户看的总结，而是下一次模型调用的工作记忆。它应该保留可执行状态，不需要复述每一次工具调用。

3.4 replace_compacted_history 才是压缩的核心动作#

摘要生成后，core/src/compact.rs 会从最后一条 assistant 消息生成 summary 文本，并从历史中挑选预算内的用户消息。它把这些消息、摘要和可选的初始上下文装成新 history，再调用 Session::replace_compacted_history，记录窗口编号、压缩 response id 和模型 hash，最后重新计算 token 使用量。下面只保留关键调用，变量来自同一函数的前置步骤。

1
let summary_text = format!("{SUMMARY_PREFIX}\n{summary_suffix}");
2
let user_messages = collect_annotated_user_messages(history_items, identity);
3
let mut new_history = build_compacted_history(Vec::new(), &user_messages, &summary_text);
4
// 这里还会按 initial_context_injection 插入初始上下文。
5
sess.replace_compacted_history(
6
    new_history,
7
    reference_context_item,
8
    world_state_baseline,
9
    CompactedHistoryMetadata {
10
        message: summary_text,
11
        window_number,
12
        window_ids,
13
        compaction_response_id: Some(compaction_response_id),
14
        compaction_model_hash: turn_context.model_info().comp_hash.clone(),
15
    },
16
).await;
17
sess.recompute_token_usage(&turn_context).await;

这段逻辑见 本地 compaction 的历史替换流程，持久化 checkpoint 的细节见 Session::replace_compacted_history。因此，压缩有两个同时成立的事实：

• transcript 或 rollout 中仍可以记录压缩边界和替换历史，压缩不是把会话文件物理清空。
• 模型下一轮看到的是新历史，旧的工具输出和中间推理如果没有进入摘要，就不能再作为当前上下文中的可靠事实。

远程 V2 路径也遵守同一个安装契约。它从远端响应拿到 compaction_output，构造新的 history，调用 replace_compacted_history，写入 response id 和 compaction model hash，再重新计算 token。远程和本地的差别在“摘要在哪里生成”，不是在会话如何接受摘要。

3.5 失败处理、Hook 和自动压缩#

压缩本身也可能撞上上下文限制。compact.rs 在压缩请求再次触发 context exceeded 时，会移除较早的 history item 后重试；成功后再安装替换历史。代码还在压缩前后运行 compact hooks，并记录 local、remote、fallback 等 analytics 信息。

这解释了两个使用现象：

• /compact 会短暂显示为一个正在运行的任务，而不是瞬间完成的字符串操作。
• 手动压缩和自动压缩共享历史替换逻辑，但触发原因不同。自动路径使用 CompactionTrigger::Auto，手动路径使用 CompactionTrigger::Manual 和 CompactionReason::UserRequested；监控和统计可以据此区分它们。

/compact 的边界也很清楚：它不能恢复未被摘要保留的逐字细节，不能替代 Git 或外部状态存储，也不能解决固定系统提示词、工具 schema 本身占用过大的问题。若窗口主要被一次巨大的日志输出占满，先限制工具输出比反复压缩更有效。

4.1 为什么 /simplify 在源码里找不到#

当前版本在 slash command 功能启用、输入从行首开始时，parser 只接受 SlashCommand 枚举中的名字；rg 搜索整个 TUI 也找不到 SlashCommand::Simplify 或 /simplify 的注册。输入 /simplify 时，按这条解析链会被当作未知 slash command，而不是进入一个名为 simplify 的 Rust handler。

当前分析环境安装的 Skill 文件是 /root/.codex/skills/simplify/SKILL.md，它不是上游 Codex 仓库内置的 Rust handler。文件 frontmatter 把 simplify 声明为一个 Skill，描述是“审查最近修改的代码，关注复用、质量和效率，并应用高置信度、保持行为的简化”。在支持 Skill 的宿主环境里，常见触发方式是显式写 $simplify、直接提到 simplify，或由任务与 Skill 描述匹配后按 Skill 规则加载；具体输入别名由宿主版本决定。

它的入口实际上就是普通的 Markdown 元数据：

1
---
2
name: simplify
3
description: Review changed code for reuse, quality, and efficiency, then apply high-confidence behavior-preserving simplifications.
4
---

这个区别不是文字游戏。slash command 的行为由枚举和 dispatch 代码决定；Skill 的行为由目录发现、元数据预算、SKILL.md 读取以及模型遵循指令决定。

4.2 Skill 的源码链是“发现、读取、注入”#

Codex 的 Skill extension 大致有三层：

1. catalog.rs 发现 Skill 元数据，生成名称、描述和路径。
2. render.rs 按预算把可用 Skill 列表渲染进系统提示词，并对描述做截断或轮询分配。
3. host_prompt.rs 对被选中的 Skill 读取完整 SKILL.md，生成 SkillInstructions 上下文片段，注入当前模型 prompt。

这里的预算不是无限的：默认 Skill 元数据预算是 8,000 个字符，配置为 token 预算时上限是 10,000 tokens；按上下文窗口计算时默认占 2%，目录中的单条描述最多 1,024 个字符，被选中的 agent-plugin 主 prompt 最多 8,000 字节。超预算时，系统会截短描述或移除部分描述，但不会因此把 simplify 变成一个独立执行器。

显式提及还要经过一条和 slash parser 完全不同的路径：input_submission.rs 从文本中提取 Skill 名称或路径，匹配当前启用的 Skill 后，向 UserInput 追加 Skill { name, path }。同时，Skill 目录 prompt 会把“用户点名 Skill，或任务匹配 Skill 描述时必须使用”写入模型可见指令；后者由模型依据描述做选择，不是 Rust 代码里的字符串路由。可对照 Skill mention 的输入转换 和 Skill 的触发规则模板。

host_prompt.rs 的关键代码很短：它遍历 selected skills，读取文本，必要时截断，构造 SkillInstructions，并记录注入结果。它没有调用 AST、编译器或独立的“简化引擎”。

1
let (contents, truncated) = if self.outcome().is_agent_plugin_skill(skill) {
2
    truncate_main_prompt_contents(&contents)
3
} else {
4
    (contents, false)
5
};
6
if truncated {
7
    prompts.warnings.push(format!(
8
        "Skill `{}` exceeded the main prompt context limit and was truncated.",
9
        skill.name
10
    ));
11
}
12
prompts.fragments.push(Box::new(SkillInstructions {
13
    name: skill.name.clone(),
14
    path: skill.path_to_skills_md.to_string_lossy().into_owned(),
15
    contents,
16
    resource_access: None,
17
}));
18
prompts.injected.push(skill.clone());

见 host prompt 的 Skill 注入实现。这段节选省略了外层读取和错误分支。官方对 Skill 的定义也是“包含指令和资源的可复用工作流”，它与工具能力互补，而不是替代工具执行。可以参考 Skills 概念文档 对发现、读取和资源边界的说明。

4.3 simplify Skill 实际要求模型做什么#

当前 Skill 文件把流程拆成三个审查视角：复用、质量、效率。它要求先看 git status 和 diff，排除生成物、vendor、缓存和锁文件，再只修复“高置信度、保持行为”的问题；没有明确要求时不启动子 Agent，也不把一般性的代码润色当成简化任务。

因此，一次 simplify 调用的实际链路更接近下面这样：

这里没有一个保证“代码一定更简单”的系统事务。模型是否真正修改文件，取决于它对 diff、项目规则和验证结果的判断；Skill 只提供决策约束。它也不自动拥有跳过权限确认、跳过测试或批量修改生成文件的能力。

这正是把 simplify 错写成 slash command 后容易漏掉的边界：若需要确定性的重构，应使用编译器重写、静态分析器、格式化器或测试约束；Skill 适合把工程师的判断框架稳定地带入一次模型任务。

5.1 命令语法和事件分支#

goal_display.rs 给出的使用形式是：

1
Usage: /goal [<objective>|clear|edit|pause|resume]

裸 /goal 打开目标菜单；/goal <objective> 创建或更新目标；clear 清除目标；edit 修改目标；pause 和 resume 改变生命周期状态。dispatch 层会把这些动作分别转成 OpenThreadGoalMenu、SetThreadGoalDraft、ClearThreadGoal 和 SetThreadGoalStatus 等应用事件，具体分支见 slash dispatch 的 Goal 实现 和 行内参数处理。

对象太长时，TUI 不会把所有文本硬塞进数据库的一行。goal_files.rs 会把粘贴内容写入 $CODEX_HOME/attachments/<UUID>/；超过目标字符上限的 objective 会写成 goal-objective.md，数据库里的目标改为“请先读取这个文件”的引用。这样既保留完整目标，又避免每一轮都复制超长文本。

5.2 数据库存什么#

Goal extension 使用独立的 state 数据库。0.155.1 的迁移文件定义了一个以 thread_id 为主键的 thread_goals 表，以及一个记录续跑暂缓状态的 thread_goal_continuation_deferrals 表。

1
CREATE TABLE thread_goals (
2
    thread_id TEXT PRIMARY KEY NOT NULL,
3
    goal_id TEXT NOT NULL,
4
    objective TEXT NOT NULL,
5
    status TEXT NOT NULL CHECK(status IN (
6
        'active', 'paused', 'blocked', 'usage_limited',
7
        'budget_limited', 'complete'
8
    )),
9
    token_budget INTEGER,
10
    tokens_used INTEGER NOT NULL DEFAULT 0,
11
    time_used_seconds INTEGER NOT NULL DEFAULT 0,
12
    created_at_ms INTEGER NOT NULL,
13
    updated_at_ms INTEGER NOT NULL
14
);

完整迁移见 thread goals 的 0001 migration。这里有一个重要的工程判断：目标是 thread 级持久化状态，不是全局“记住我想做什么”的模型记忆。换一个 thread，不会因为模型参数相同就自动继承这个 goal。

state/src/runtime/goals.rs 还负责几个状态不变量：替换目标时生成新的 goal_id 并清零 tokens/time；account_thread_goal_usage 会把负的 token/time 增量钳制为零，并在达到 token budget 时从 active 转为 budget_limited；更新时携带 expected goal id，避免旧的异步事件覆盖新目标。

5.3 设置目标的服务端路径#

TUI 事件最终进入 app-server 的 thread_goal_processor.rs。处理器会检查 feature flag，解析 thread 和状态，读取最大预算，调用 GoalService::set_thread_goal，写入 rollout 的 ThreadGoalUpdated 事件，再把变更发送给客户端并应用 runtime effects。

这种拆分把持久化和运行时分开：数据库回答“目标是什么、花了多少、现在是什么状态”，runtime 回答“当前线程是否已经空闲，是否应该立即再启动一轮”。

5.4 续跑不是定时器，而是一个有门槛的 idle 检查#

ext/goal/src/runtime.rs 的 continue_if_idle 是 /goal 最容易被低估的部分。它不会无条件创建一个后台循环，而是依次检查：工具是否仍可用、目标状态是否为 active、数据库中是否标记了 continuation deferral、线程是否存在并且当前确实 idle。条件满足后，runtime 构造一条内部 goal steering item，调用 thread.start_turn_if_idle；成功启动后才把这轮标记为 goal continuation。

下面是保留关键条件的伪代码，省略了 state DB、线程管理器和错误处理的完整限定名；真实调用见上面的源码链接。

1
let Some(goal) = state_dbs.thread_goals().get_thread_goal(thread_id).await? else {
2
    return Ok(());
3
};
4
if goal.status != ThreadGoalStatus::Active || continuation_deferred(thread_id).await? {
5
    return Ok(());
6
}
7
let item = continuation_steering_item(&protocol_goal_from_state(goal), update_plan_enabled);
8
match thread
9
    .start_turn_if_idle(
10
        TurnInputRequest::new(TurnInput::ResponseItem(item)).on_start(TurnStartOptions {
11
            turn_trigger: Some("goal".to_string()),
12
            ..start_options
13
        }),
14
    )
15
    .await
16
{
17
    Ok(StartIfIdleSubmission::Started { turn_id }) => {
18
        accounting_state.mark_goal_continuation(turn_id);
19
    }
20
    _ => {}
21
}

这段是 Goal runtime 的 idle continuation 的压缩节选，省略了状态锁、线程管理器和错误日志。它回答了一个实际问题：为什么模型发完一条看似完成的回复后，有时还会继续工作。只要目标仍为 active、线程回到 idle、没有续跑暂缓，系统就可能用内部 steering 再启动一轮。

5.5 steering prompt 如何限制模型的“完成”判断#

续跑不是把原始 objective 再贴一遍。steering.rs 使用 continuation.md 模板，把 XML 转义后的 objective、已用 token、预算和剩余预算填入内部上下文片段。模板明确要求模型：

• 以当前目标作为持续任务，不要擅自缩小成功条件。
• 根据工作区或外部系统中的证据继续推进，而不是凭“看起来完成”停止。
• 没有进展时先重新验证，不要在同一阻塞条件上无限循环。
• 只有逐项核对权威证据后，才把目标标为 complete。
• 相同阻塞条件连续重复达到规定次数后，才能进入 blocked。

其中 objective 会经过 escape_xml_text，避免用户目标中的 <、> 和 & 破坏模板结构。这是模板结构保护的一部分，不能单独阻止 prompt 注入；真正的文件、网络和进程限制仍由工具权限和沙箱负责。

完整规则在 Goal continuation 模板，prompt 的渲染和 XML 转义见 steering.rs。

5.6 预算和终止状态如何产生#

Goal runtime 会在 turn 结束或异常时记录 token 和时间增量。状态更新使用 expected goal id，防止旧 turn 的异步完成事件污染新目标。典型状态转移如下：

complete 和 blocked 不是用户界面上的装饰标签。它们会阻止后续自动续跑；budget_limited 和 usage_limited 则把资源边界显式传给下一次交互。官方 Cookbook 也把 Goal 描述为附着在线程上的持久目标，并强调基于证据的完成判断，见 Using Goals in Codex。