pub(crate) const BEGIN_PATCH_MARKER: &str = "*** Begin Patch"; // 补丁起始标记：模型输出的第一行必须是它，否则直接判非法pub(crate) const END_PATCH_MARKER: &str = "*** End Patch"; // 补丁结束标记：最后一行必须是它（流式解析的 finish() 会强制检查）pub(crate) const ADD_FILE_MARKER: &str = "*** Add File: "; // 新增文件指令前缀，冒号后跟相对路径pub(crate) const DELETE_FILE_MARKER: &str = "*** Delete File: "; // 删除文件指令前缀pub(crate) const UPDATE_FILE_MARKER: &str = "*** Update File: "; // 修改文件指令前缀（最常用）pub(crate) const MOVE_TO_MARKER: &str = "*** Move to: "; // 重命名目标路径，出现在 UpdateFile hunk 内部pub(crate) const CHANGE_CONTEXT_MARKER: &str = "@@ "; // chunk 定位上下文行：通常是一个函数/类定义，用来缩小搜索范围pub enum Hunk { // 一个补丁块 = 对单个文件的一种操作；整个补丁是 Hunk 的有序列表    AddFile { path: PathBuf, contents: String }, // 新增文件：路径 + 完整内容（覆盖已有文件也算 Add）    DeleteFile { path: PathBuf }, // 删除文件：只需要路径，内容在验证阶段从磁盘读取    UpdateFile { path: PathBuf, move_path: Option<PathBuf>, chunks: Vec<UpdateFileChunk> }, // 修改/重命名：move_path 非空即 rename；chunks 必须按文件内先后顺序排列}

const PARSE_IN_STRICT_MODE: bool = false; // 全局开关：当前默认走 Lenient（宽容）模式pub fn parse_patch(patch: &str) -> Result<ApplyPatchArgs, ParseError> { // 入口：把补丁文本解析成 ApplyPatchArgs（hunks + workdir + environment_id）    let mode = if PARSE_IN_STRICT_MODE { ParseMode::Strict } else { ParseMode::Lenient }; // 按开关选模式；生产环境恒为 Lenient    parse_patch_text(patch, mode) // 先校验 Begin/End 边界标记，再逐行解析 hunk}

pub struct StreamingPatchParser { // 流式解析器：delta 按任意边界切分，它负责拼回完整行    line_buffer: String, // 半行缓冲：一个 delta 经常在行中间截断，攒到换行为止才处理    state: StreamingParserState, // 当前模式 + 已完成的 hunks 列表 + environment_id（多环境路由用）    line_number: usize, // 行号计数：报错时告诉模型"第 N 行错了"，方便它自我修正}enum StreamingParserMode { // 五态状态机：每一行该被谁消费、什么算非法，全由当前模式决定    NotStarted, // 还没看到 *** Begin Patch——此时任何内容都直接判错（fail fast）    StartedPatch, // 已开始，等待 hunk 头（Add/Delete/Update）、Environment ID 或 End Patch    AddFile, // 正在收集新增文件的内容行；遇到下一个 hunk 头才切换    DeleteFile, // 删除文件：后面不应再有内容行，出现即报错    UpdateFile { hunk_line_number: usize }, // 正在解析 chunk（@@/+/− 行）；记下起始行号用于精确报错    EndedPatch, // 已收尾：之后再来任何输入都是非法的}pub fn push_delta(&mut self, delta: &str) -> Result<Vec<Hunk>, ParseError> { // 每收到一段流式增量调用一次    for ch in delta.chars() { // 逐字符扫描：delta 边界可能落在任意位置，不能假设按行切分        if ch == '\n' { // 遇到换行 → 一行完整了，可以处理            let mut line = std::mem::take(&mut self.line_buffer); // 取出半行缓冲并清空（零拷贝交换）            line.truncate(line.strip_suffix('\r').map_or(line.len(), str::len)); // 剥掉 CRLF 的 \r：兼容 Windows 风格换行的模型输出            self.line_number += 1; // 行号 +1，供后续报错定位            self.process_line(&line)?; // 按当前状态机模式消费这一行；出错立即上抛        } else {            self.line_buffer.push(ch); // 非换行字符继续攒进半行缓冲        }    }    Ok(self.state.hunks.clone()) // 返回"目前为止已完成的 hunks"——注意是 clone：调用方拿去做流式事件，解析器自己保留状态}

pub enum MaybeApplyPatchVerified { // 校验结果四态：调用方必须逐一处理，不能笼统当"成功/失败"二分    Body(ApplyPatchAction), // 合法补丁：changes 已按绝对路径解析好、UpdateFile 已算出新内容，可直接进入安全裁决    ShellParseError(ExtractHeredocError), // shell 命令无法解析（heredoc 提取失败）——这不是补丁错误，shell 拦截路径应放行给真 shell    CorrectnessError(ApplyPatchError), // 确实是 apply_patch 但内容不合法：找不到行、重复目标、文件不存在等    NotApplyPatch, // 明确不是 apply_patch 调用：直接放行，别误伤普通命令}// invocation.rs —— try_verify_apply_patch_args() 的核心循环（节选）for hunk in hunks { // 逐个 hunk 校验并转成"绝对路径 → 变更"的映射表    let path = hunk.resolve_path(&effective_cwd)?; // 相对路径拼上 cwd；非法路径直接报错，不进入后续流程    if changes.contains_key(&path) { // 同一文件被两个 hunk 操作（如先删后加）→ 拒绝：语义歧义，宁可让模型重写补丁        return Err(ParseError::InvalidPatchError(format!("multiple operations target {}", path.inferred_native_path_string())).into()); // 报错带上冲突路径：模型可据此把两个 hunk 合并成一个再重试    }

pub fn assess_patch_safety( // 补丁安全裁决：输入"补丁+策略+沙箱状态"，输出三选一    action: &ApplyPatchAction, // 已干跑校验的补丁动作（含全部目标绝对路径）    policy: AskForApproval, // 用户配置的审批策略：Never/OnRequest/UnlessTrusted/Granular    permission_profile: &PermissionProfile, // 权限档案：Managed / Disabled / External    file_system_sandbox_policy: &FileSystemSandboxPolicy, // 文件系统沙箱策略：可写根集合、全盘写等    context: &FileSystemSandboxPolicyContext<'_>, // 策略上下文（cwd、workspace roots），路径判定依赖它    sandbox_route: PatchSandboxRoute, // 沙箱路由：Platform(本地平台沙箱) or ExecutorManaged(executor 托管)) -> SafetyCheck { // 三选一裁决结果：放行 / 问用户 / 拒绝，调用方必须穷尽处理    if action.is_empty() { // 空补丁直接拒绝——不给模型"试探边界"的机会，也不浪费一次审批弹窗        return SafetyCheck::Reject { reason: "empty patch".to_string() }; // 原因字符串直接回传模型——"空补丁"是它可自我修正的明确信号    }    match policy { // 按用户审批策略分流：先排除"必须问人"的模式，再争取自动放行        AskForApproval::Never | AskForApproval::OnRequest | AskForApproval::Granular(_) => {} // 这三种策略不直接问人，继续走"可写路径"检查争取自动放行        AskForApproval::UnlessTrusted => return SafetyCheck::AskUser, // "除非可信"模式：一律先问用户（源码 TODO 注明作者对顺序也有保留）    }    let rejects_sandbox_approval = matches!(policy, AskForApproval::Never) // Never：连沙箱审批弹窗都不允许        || matches!(policy, AskForApproval::Granular(granular_config) if !granular_config.sandbox_approval); // Granular 且显式关掉 sandbox_approval：同上    let sandbox_available = match sandbox_route { // 当前环境到底有没有可用的兜底沙箱？        PatchSandboxRoute::ExecutorManaged => true, // executor 托管（远程执行）默认视为有沙箱能力        PatchSandboxRoute::Platform(windows_sandbox_level) => get_platform_sandbox(windows_sandbox_level != WindowsSandboxLevel::Disabled).is_some(), // 本地：按平台探测（bwrap/Landlock/Seatbelt/Windows），Disabled 级别直接算没有    };    if is_write_patch_constrained_to_writable_paths(action, file_system_sandbox_policy, context) // 所有目标路径都在可写根内？（含 rename 的源+目的两个路径）        && (matches!(permission_profile, PermissionProfile::Disabled | PermissionProfile::External { .. }) || sandbox_available) // 且：本就无外层沙箱（Disabled/External），或平台沙箱可用兜底    {        SafetyCheck::AutoApprove // 两个条件都满足 → 自动放行，不打扰用户    } else if rejects_sandbox_approval { // 越界 + 用户禁止审批弹窗 → 直接拒绝（不浪费一次注定被拒的询问）        SafetyCheck::Reject { reason: patch_rejection_reason(permission_profile, file_system_sandbox_policy, context).to_string() } // 越界 + 用户禁止审批 → 直接拒绝，原因区分"只读沙箱拦截"和"项目外写入"    } else {        SafetyCheck::AskUser // 其余情况：弹审批让用户决定（含缓存的"始终允许"）    }}

match assess_patch_safety(&action, step_context.settings.approval_policy(), turn_environment.permission_profile(), file_system_sandbox_policy, context, sandbox_route) { // 调用第五节的三向裁决    SafetyCheck::AutoApprove => Ok(ApplyPatchRuntimeInvocation { action, auto_approved: true, exec_approval_requirement: ExecApprovalRequirement::Skip { bypass_sandbox: false, proposed_execpolicy_amendment: None } }), // 自动放行：跳过审批弹窗，但 bypass_sandbox=false——沙箱照常生效，"免审批"不等于"免管控"    SafetyCheck::AskUser => Ok(ApplyPatchRuntimeInvocation { action, auto_approved: false, exec_approval_requirement: ExecApprovalRequirement::NeedsApproval { reason: None, proposed_execpolicy_amendment: None } }), // 需要用户点头：审批流交给 orchestrator，与 shell/unified_exec 的审批机制完全同构（含"始终允许"缓存）    SafetyCheck::Reject { reason } => Err(FunctionCallError::RespondToModel(format!("patch rejected: {reason}"))), // 直接拒绝：错误信息回传模型——注意是 RespondToModel，让模型读到原因后自行调整策略}

// 一次失败的写入可能已经改动了目标（比如先 truncate 再 ENOSPC），// 所以失败后累计的 delta 不再"精确"——用 exact 标志诚实标记这件事macro_rules! try_write { // 自定义宏：统一处理"写文件"的错误路径    ($result:expr) => { match $result { Ok(value) => value, Err(error) => { delta.exact = false; return Err(anyhow::Error::from(error)); } } }; // 成功透传；失败先把 exact 置 false（delta 可能不完整），再上抛错误}Hunk::AddFile { contents, .. } => { // 新增文件分支：先读旧内容，再写新内容    let overwritten_content = read_optional_file_text_for_delta(&path_uri, fs, follow_symlinks, sandbox, &mut delta.exact).await; // 若目标已存在（覆盖场景），读出被覆盖的原文存进 delta——这是"覆盖可回滚"的数据基础    try_write!(write_file_with_missing_parent_retry(fs, &path_uri, contents.clone().into_bytes(), follow_symlinks, sandbox).await); // 写文件；父目录不存在时自动补建后重试（见下块）    delta.changes.push(AppliedPatchChange { path: path_uri, change: AppliedPatchFileChange::Add { content: contents.clone(), overwritten_content } }); // 记入已提交增量：路径 + 新内容 + 被覆盖的旧内容，三者齐备才能完整回滚    added.push(affected_path); // 汇总"新增"清单，最后打印 git 风格摘要（A/M/D）}

async fn write_file_with_missing_parent_retry( // 写文件 + 父目录缺失自动重试：模型经常给"新模块/新测试"这类不存在的子路径    fs: &dyn ExecutorFileSystem, path: &PathUri, contents: Vec<u8>, follow_symlinks: bool, sandbox: Option<&FileSystemSandboxContext>, // 全部走 executor 文件系统抽象：本地/远程同一套代码；sandbox 上下文决定这次写是否受沙箱约束) -> anyhow::Result<()> { // 返回 anyhow：错误可携带路径上下文，最终被 try_write! 捕获并标记 exact=false    match fs.write_file(path, contents.clone(), WriteFileOptions { follow_symlinks }, sandbox).await { // 先直接写一次（快路径）        Ok(()) => Ok(()), // 成功就完事，不做任何多余操作        Err(err) if err.kind() == io::ErrorKind::NotFound => { // 仅当 ENOENT（父目录不存在）才进入重试分支——权限错误等不在此列            if let Some(parent) = path.parent() { fs.create_directory(&parent, CreateDirectoryOptions { recursive: true, follow_symlinks }, sandbox).await.with_context(|| format!("Failed to create parent directories for {}", path.inferred_native_path_string()))?; } // 递归创建缺失的祖先目录（等价 mkdir -p），同样受沙箱约束            fs.write_file(path, contents, WriteFileOptions { follow_symlinks }, sandbox).await.with_context(|| format!("Failed to write file {}", path.inferred_native_path_string()))?; // 第二次写：这次父目录已就位，失败则带上下文上抛            Ok(()) // 重试成功 → "建目录 + 写入"整体视为一次原子操作返回        }        Err(err) => Err(err).with_context(|| format!("Failed to write file {}", path.inferred_native_path_string())), // 其他错误原样上抛（附路径上下文），交给沙箱/审批链路处理    }}

for chunk in chunks { // 按顺序处理每个 chunk：定位 → 记录替换区间（依赖 chunk 顺序单调推进）    if let Some(ctx_line) = &chunk.change_context { // 有 @@ 上下文行时，先用它把搜索起点推进到正确位置——避免同名代码块匹配错地方        if let Some(idx) = seek_sequence::seek_sequence(original_lines, std::slice::from_ref(ctx_line), line_index, /*eof*/ false, update_file_mode) { line_index = idx + 1; } else { return Err(ApplyPatchError::ComputeReplacements(format!("Failed to find context '{ctx_line}' in {path}"))); } // 上下文找不到 → 整个补丁失败（fail loud，错误带路径和上下文行）    }    if chunk.old_lines.is_empty() { // 纯插入 chunk（old_lines 为空）：定位到文件末尾附近插入        let insertion_idx = match update_file_mode { NormalizeToLf => { ... } PreserveLineEndings => original_lines.len() }; // 两种换行模式对"末尾空行"的语义不同，分别处理        replacements.push((insertion_idx, 0, chunk.new_lines.clone())); // (起点, 旧长度=0, 新行) —— 零长度替换即插入        continue; // 纯插入无需后续匹配逻辑，直接处理下一个 chunk    }    let mut pattern: &[String] = &chunk.old_lines; // 先按原样匹配 old_lines    let mut found = seek_sequence::seek_sequence(original_lines, pattern, line_index, chunk.is_end_of_file, update_file_mode); // 带 eof 标志的模糊搜索（见下块）    if found.is_none() && pattern.last().is_some_and(String::is_empty) { // 没找到、且模式以空行结尾 → 去掉这个"终止换行哨兵"再试一次        pattern = &pattern[..pattern.len() - 1]; // old_lines 末尾的空串代表区域结束换行，SourceFile 里并不存在这一行        if new_slice.last().is_some_and(String::is_empty) { new_slice = &new_slice[..new_slice.len() - 1]; } // new_lines 同理：保持两侧对称，避免插入多余空行        found = seek_sequence::seek_sequence(original_lines, pattern, line_index, chunk.is_end_of_file, update_file_mode); // 第二次搜索：这是"文件末尾修改"场景的关键容错    }    if let Some(start_idx) = found { replacements.push((start_idx, pattern.len(), new_slice.to_vec())); line_index = start_idx + pattern.len(); } else { return Err(ApplyPatchError::ComputeReplacements(format!("Failed to find expected lines in {}:\n{}", path, chunk.old_lines.join("\n")))); } // 找到 → 记录替换区间并推进搜索起点；找不到 → 报错时把期望的行内容原样带回给模型}fn apply_replacements(mut lines: Vec<String>, replacements: &[Replacement]) -> Vec<String> { // 把所有 (起点, 旧长度, 新行) 应用到原文，产出新文件内容    for (start_idx, old_len, new_segment) in replacements.iter().rev() { // 倒序应用：先改文件后面的区间，前面的下标才不会因插入/删除而错位        for _ in 0..old_len { if start_idx < lines.len() { lines.remove(start_idx); } } // 逐行删掉旧内容（越界保护：start_idx 超出长度时跳过）        for (offset, new_line) in new_segment.iter().enumerate() { lines.insert(start_idx + offset, new_line.clone()); } // 在原位置按序插入新内容    }    lines}

pub(crate) fn seek_sequence( // 在 lines 里从 start 起找 pattern：四级宽松度逐级降级，返回命中下标    lines: &[String], pattern: &[String], start: usize, eof: bool, update_file_mode: crate::ApplyPatchFileUpdateMode, // eof=true 表示该 chunk 声明"必须在文件末尾"（*** End of File）) -> Option<usize> { // None = 四级宽松度全部落空：调用方必须报错，绝不能猜位置    if pattern.is_empty() { return Some(start); } // 空模式 = no-op，直接命中（兼容纯插入 chunk 的边界情况）    if pattern.len() > lines.len() { return None; } // 模式比文件还长 → 不可能匹配；提前返回避免搜索循环越界 panic（源码注明这是 2025-04 前的真实 bug）    let search_start = if eof && lines.len() >= pattern.len() { /* 从文件尾部开始找 */ } else { start }; // is_end_of_file=true 时优先锚定 EOF：模型说"改文件末尾"就该在末尾找，而不是全文乱撞    for i in search_start..=lines.len().saturating_sub(pattern.len()) { // 第一遍：逐字符精确匹配（最快路径）        if lines[i..i + pattern.len()] == *pattern { return Some(i); } // 切片相等即命中，返回下标（最快路径）    }    // 第二遍：rstrip 后比较——容忍行尾空白差异（模型最常见的"不精确"）    // 第三遍：两侧 trim 后比较——容忍缩进/前导空格差异    // 第四遍：Unicode 标点归一化（全角破折号→ASCII、弯引号→直引号等），对齐 git apply 的模糊行为

let result = codex_apply_patch::apply_patch_with_options(&req.action.patch, ApplyPatchOptions { update_file_mode: req.action.update_file_mode(), // 沿用验证阶段选定的换行模式，保证"校验过的内容"和"落盘的内容"一致    follow_symlinks: attempt.sandbox_requested || !attempt.manager.should_sandbox(attempt.permissions, self.sandbox_preference(), attempt.enforce_managed_network), // 只有当"本应沙箱化却被绕过"时才拒绝跟随符号链接——防止模型用 symlink 把写入引到可写根之外；executor 托管沙箱可能合法地 SandboxType::None，不在此列}, &req.action.cwd, &mut stdout, &mut stderr, fs.as_ref(), sandbox.as_ref()).await; // 真正落盘：stdout/stderr 收进内存 buffer（不是真终端），sandbox 上下文由本次 attempt 决定let exit_code = if failed { 1 } else { 0 }; // 统一成"命令退出码"语义——TUI/事件流无需区分工具类型，apply_patch 和 shell 共用一套展示逻辑self.committed_delta.append(delta); // 把本次增量并入累计 delta：同一 turn 多次调用、多文件变更都能完整追踪let sandbox_denied = failed && if attempt.sandbox == SandboxType::None { attempt.sandbox_requested && is_likely_executor_managed_sandbox_denied(&output) } else { is_likely_sandbox_denied(attempt.sandbox, &output) }; // 从输出文本嗅探"沙箱拒绝"特征（如 bwrap/landlock 的典型报错）——区分"文件写失败"和"被沙箱拦了"，两者后续处理完全不同if sandbox_denied { if attempt.sandbox != SandboxType::None { record_filesystem_sandbox_violation(attempt.sandbox, &output); } // 记违规遥测：哪个沙箱引擎、什么输出触发的拒绝，供安全分析    return Err(ToolError::Codex(CodexErr::Sandbox(SandboxErr::Denied { output: Box::new(output), network_policy_decision: None }))); // 以 Sandbox(Denied) 上抛 → orchestrator 据此决定是否提权重试（escalate_on_failure=true，见第 120-122 行）}

const APPLY_PATCH_ARGUMENT_DIFF_BUFFER_INTERVAL: Duration = Duration::from_millis(500); // 节流窗口：两次进度事件至少间隔 500ms，防止 token 流把事件通道打爆fn push_delta(&mut self, call_id: String, delta: &str) -> Option<PatchApplyUpdatedEvent> { // 模型每吐一段 token 就调用一次；返回 Some(event) 表示该发事件    let hunks = self.parser.push_delta(delta).ok()?; // 流式解析推进；出现非法行则放弃本次事件（最终 finish() 仍会报错，这里不提前炸）    if hunks.is_empty() { return None; } // 还没有完整 hunk → 不发事件：空 diff 只会让 UI 闪烁，没有信息量    let event = PatchApplyUpdatedEvent { call_id, changes: convert_apply_patch_hunks_to_protocol(&hunks) }; // 转成协议层 FileChange（Add/Delete/Update），TUI 据此实时渲染"正在改哪些文件"    match self.last_sent_at { // 500ms 节流判定        Some(last_sent_at) if now.duration_since(last_sent_at) < APPLY_PATCH_ARGUMENT_DIFF_BUFFER_INTERVAL => { self.pending = Some(event); None } // 距上次发送不足 500ms → 压进 pending，本次不发（用最新事件覆盖旧的）        Some(_) | None => { self.pending = None; self.last_sent_at = Some(now); Some(event) } // 窗口已过 → 正常发出并刷新时间戳    }}fn finish_update_on_complete(&mut self) -> Result<Option<PatchApplyUpdatedEvent>, FunctionCallError> { // 流结束时的收尾：补发被节流压住的事件，保证 UI 最终看到完整状态    self.parser.finish().map_err(|err| FunctionCallError::RespondToModel(format!("failed to parse apply_patch: {err}")))?; // finish() 强制检查 *** End Patch；缺了就把解析错误回传模型    let event = self.pending.take(); if event.is_some() { self.last_sent_at = Some(Instant::now()); } Ok(event) // pending 里压着的事件在这里补发一次，然后清空}

apply_patch 全链路（模型输出 → 磁盘落盘）

▼

▼

▼

▼

▼