HelloAgents Code Agent CLI 补丁失败深度排查：从 “Patch must start with ‘*** Begin Patch‘“ 到安全补丁系统的完整原理

HelloAgents Code Agent CLI 补丁失败深度排查从 Patch must start with *** Begin Patch 到安全补丁系统的完整原理【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents本文以 HelloAgents Code Agent CLI 项目中一条真实运行的失败笔记Patch must start with *** Begin Patch为切入点逐层还原补丁失败现场、解析 Codex 风格补丁的格式规范与源码级解析流程并延伸讲解该 CLI 内置的路径防护、后缀白名单、原子写入、自动备份与人工确认等安全机制帮助你理解智能 Code Agent 为何写文件必须走补丁以及补丁失败后应如何快速定位与修复。一、背景Code Agent 为什么选择补丁式写文件HelloAgents Code Agent CLI 是一个基于 ReAct 范式、面向本地代码仓库的智能命令行工具定位类似 Claude Code / Codex 的交互体验。它的核心主张是安全可控地修改本地代码Agent 不直接执行任意写盘命令而是把要改什么组织成结构化补丁交给独立的执行器统一校验、备份、写入。在该项目的 README.md 中安全补丁系统被列为核心特性之一包括标准化补丁格式*** Begin Patch ... *** End Patch原子化文件操作自动备份存放于.helloagents/backups/白名单文件类型控制人工确认机制同时在 tools.md 的工具使用指南里有一条非常醒目的约束写/改文件必须用补丁*** Begin Patch ...禁止cat file/ Here-Doc / tee / 重定向写盘。也就是说补丁是这个 Agent 唯一的写盘通道。那么当补丁格式不合法时Agent 就会卡在写文件这一步并在笔记系统中留下一条blocker类型的失败记录——这正是本文要解剖的场景。二、失败现场还原一条真实的 blocker 笔记在项目的.helloagents/notes/目录下保存着 Agent 运行过程中自动记录的笔记。其中 note_20251218_191554_7.md 完整记录了这样一次失败标题Patch failed类型blocker阻塞标签hello_agents_forStudy、patch_failed错误信息Error: Patch must start with *** Begin Patch用户输入建一个简单的HTML文件显示helloworld在testDemo文件夹而 Agent 生成的补丁文本本身长这样*** Begin Patch *** Add File: testDemo/helloworld.html !DOCTYPE html html head titleHello World/title /head body h1helloworld/h1 /body /html *** End Patch从表面看这份补丁似乎完全符合规范以*** Begin Patch开头、以*** End Patch结尾、中间是*** Add File操作。但执行器却报出必须以*** Begin Patch开头。这说明对执行器而言看起来正确和解析器严格接受之间可能存在差异比如文本中混入了前导空白、不可见字符、或笔记记录时的执行器版本比当前源码更严格详见后文源码解析。有趣的是打开同一天的笔记序列会发现这是一个典型的反复失败、逐步逼近过程。为了把为什么失败讲透我把同批次的多份失败笔记也调出来对比失败样本 1内容行必须带前缀note_20251218_190919_4.md 中错误为Add File content lines must start with 。也就是说当时执行器要求 Add File 的正文每一行都要以开头diff 风格而模型直接给出了裸 HTML 内容。失败样本 2结束标记被加星号note_20251218_191113_5.md 中错误同样是Patch must start with *** Begin Patch但对比补丁文本可以发现猫腻*** Begin Patch *** *** Add File: testDemo/helloworld.html *** !DOCTYPE html ... *** End Patch模型把*** Begin Patch ***写成了带尾部星号的形式还把*** Add File: xxx ***也加了星号。解析器要求的是整行精确等于*** Begin Patch多一个*就匹配失败。失败样本 3文件后缀被白名单拦截note_20251218_191343_6.md 中错误为Disallowed file suffix for write: .html。这说明当时执行器的可写后缀白名单还没有包含.html补丁本身格式正确却被安全策略拦下。成功样本规范补丁顺利落地与之形成鲜明对比的是 note_20251218_192121_8.md标题为Patch applied类型action标签含patch_applied补丁完全规范最终成功创建了testDemo/hello.html。从这批笔记的时间线19:09 → 19:21可以推断这是开发者在真实使用中不断调试补丁格式、并同步完善执行器容错能力的过程。当前仓库中的执行器源码相比笔记记录的版本已经做了大量宽容处理我们接下来从源码层面逐一验证。三、源码级解析执行器如何校验和解析补丁补丁的解析、校验与执行全部集中在 apply_patch_executor.py 的ApplyPatchExecutor类中。它的类注释明确写着应用 Codex 风格的*** Begin Patch格式补丁并列出 MVP 阶段的安全特性repo_root路径限制防止路径逃逸通过临时文件 os.replace实现原子写入备份到repo_root/.helloagents/backups/timestamp/大小限制最大文件数、最大总变更行数Update File 块的冲突检测精确匹配3.1 解析入口_parse_patchapply()方法的第一步是调用_parse_patch()解析补丁文本源码第 262-341 行。它的核心逻辑可以概括为先找头、再找尾、再逐行解释操作头部宽容处理先跳过前置空行以及、patch、diff、text等代码块围栏行如果第一行仍不是*** Begin Patch继续向下扫描找到第一个 strip 后精确等于*** Begin Patch的行并从那里截取如果始终找不到抛出PatchApplyError(Patch must start with *** Begin Patch)——这正是我们这条笔记记录的错误来源尾部宽容处理跳过结尾的空行/围栏若末尾不是*** End Patch则从后往前找最后一个*** End Patch截断遍历中间每一行识别三类操作*** Add File: path添加新文件*** Delete File: path删除文件*** Update File: path更新文件内容针对 Add File解析器还内置了双格式兼容源码第 311-319 行规范形式正文行以开头此时去掉作为文件内容宽松形式正文行直接给出模型有时省略。这正是对失败样本 1内容行必须以 开头的修复——当前版本已经不再强制前缀。3.2 为什么 *** Begin Patch *** 依然会失败对比失败样本 2_parse_patch中判断头部使用的条件是l.strip() *** Begin Patch源码第 284-289 行这是全字符串精确匹配。*** Begin Patch ***strip 之后是*** Begin Patch ***与*** Begin Patch并不相等因此扫描不到合法头部最终仍会抛出Patch must start with *** Begin Patch。可以推断即使放在当前版本源码上这类多加了星号的补丁依然无法通过头部校验——这是模型生成格式错误而非执行器能力问题。3.3 更新文件hunk 冲突检测与宽松回退对于 Update Filepayload 按分隔符或空行切成多个 hunk_split_hunks每个 hunk 再分离出before空格上下文行 -删除行和after空格上下文行 新增行然后在当前文件中做子序列精确匹配_find_subsequence。匹配失败时会抛出Patch hunk context not found; file changed?并附上recheck_targets提示例如rel_path:search:上下文前80字符方便定位哪个文件的哪段上下文对不上。更贴心的是当所有 hunk 都没有任何/-/空格前缀行时Update 会被视为整文件替换当上下文匹配失败时还会尝试用_hunks_to_after把与空格行合成新文件作为宽松兜底源码第 369-392 行。四、安全机制为什么补丁可以放心地交给 Agent补丁解析通过后apply()还会依次执行四道安全检查与两道写入保障全部都有源码依据4.1 路径逃逸防护_safe_path源码第 185-207 行 规定路径不得以/或~开头拒绝绝对路径解析后的目标必须落在repo_root之内否则抛Path escapes repo_root若目标已存在且是符号链接则拒绝修改Refusing to modify symlink防止通过软链读写仓库外文件。4.2 后缀白名单_enforce_suffix默认允许写入的后缀为源码第 72-84 行.py .md .toml .json .yml .yaml .txt .html .htm .css .js不在列表中的后缀如二进制、.env等敏感文件一律抛Disallowed file suffix for write。可以看到当前版本已包含.html失败样本 3 的后缀问题在现在的源码里已不复存在。4.3 大小限制单补丁最多修改max_files个文件默认 10 个单补丁变更总行数不超过max_total_changed_lines默认 800 行其中 update 只统计/-行add 按内容行数计delete 按 1 行计_estimate_changed_lines。超限会抛出Too many files in patch或Patch too large防止一次补丁失控。4.4 原子写入_atomic_write写入前先在目标同目录创建临时文件写入后flush()os.fsync()强制落盘最后os.replace原子替换目标文件源码第 245-260 行。即使进程中途崩溃也不会留下半截文件。4.5 自动备份每次应用补丁前会创建以时间戳命名的备份目录.helloagents/backups/YYYYMMDD_HHMMSS/被修改/删除的文件以相对路径 .bak后缀备份其中_backup_file。仓库中.helloagents/backups/下的20251218_192253/testDemo/hello.html.bak等文件正是这套备份机制的真实运行产物。4.6 CLI 层的补丁提取、规范化与人工确认在执行器之外CLI 入口 hello_code_cli.py 还做了三层配套工作补丁提取用_extract_patch先从patch/diff/text围栏中提取补丁主体再退回普通正则匹配PATCH_RE源码第 32-43 行格式规范化_normalize_patch会把遗漏***前缀的Add File:/Update File:/Delete File:行自动补全为*** Add File:等源码第 46-60 行人工确认_patch_requires_confirmation规定只要补丁包含删除操作、涉及文件数 ≥ 6、或变更行数 ≥ 400就在应用前弹出⚠️ 检测到高风险补丁删除/大规模变更。是否应用(y/n)征求确认源码第 63-81 行。五、失败闭环blocker 笔记是如何产生的补丁失败后CLI 并没有静默吞掉错误而是把它沉淀为结构化笔记源码第 205-214 行agent.note_tool.run({ action: create, title: Patch failed, content: fError: {e}\n\nUser input:\n{user_in}\n\nPatch:\n\ntext\n{patch_text}\n\n, note_type: blocker, tags: [project, patch_failed], })对应的成功路径同样会记录Patch applied笔记note_type: action、标签patch_applied见 源码第 196-204 行。这带来两个好处可追溯每次用户说了什么 → Agent 生成了什么补丁 → 执行器为什么拒绝/接受都被完整留痕在.helloagents/notes/下配合todos.json.bak等文件可以复盘整段对话可学习blocker类型的笔记是 Agent 迭代提示词与执行器容错能力的绝佳语料——Add File兼容无前缀、_parse_patch跳过代码围栏等宽容逻辑正是从这类失败中沉淀出来的。六、实战指南如何写出一次通过的补丁综合笔记中的失败案例与当前源码的解析规则归纳出一份补丁通过率检查清单检查项要求失败后果对应错误消息起始标记整行精确等于*** Begin Patch不要加尾部星号Patch must start with *** Begin Patch结束标记整行精确等于*** End PatchPatch must end with *** End Patch操作指令*** Add File: 路径/*** Update File: 路径/*** Delete File: 路径冒号后一个空格Unexpected patch lineAdd 正文可带前缀也可直接给正文当前版本兼容旧版本报Add File content lines must start with 文件后缀必须在白名单内.py .md .toml .json .yml .yaml .txt .html .htm .css .jsDisallowed file suffix for write路径相对路径禁止/或~开头禁止越出仓库根目录禁止符号链接Absolute paths are not allowed/Path escapes repo_root/Refusing to modify symlink规模文件数 ≤ 10变更行数 ≤ 800Too many files in patch/Patch too largeUpdate 上下文hunk 的 before 块必须在原文件中精确匹配Patch hunk context not found; file changed?围栏与空行允许包裹在text代码块内允许前后空行当前版本会跳过旧版本报Patch must start with *** Begin Patch当再次遇到 Patch must start with * Begin Patch 时建议按以下顺序排查**检查模型输出是否被包裹在代码块围栏中、或前面有多余空行——当前执行器已能自动跳过若仍失败需检查是否存在不可见字符如全角空格、BOM检查起始行是否被画蛇添足地写成*** Begin Patch ***检查是否把*** Begin Patch写成了其他变体如Begin Patch、*** Begin Patch:查看.helloagents/notes/中对应的blocker笔记比对用户输入与模型生成的补丁原文确认是哪一层解析被卡住。七、总结通过这条Patch failed笔记我们完整看到了 HelloAgents Code Agent CLI 中补丁机制的全貌模型负责按 Codex 风格生成补丁 → CLI 负责提取与规范化 → 执行器负责严格解析、安全校验、原子写入与自动备份 → 失败/成功自动沉淀为结构化笔记。格式上的一处小偏差缺星号、多星号、内容行少了、后缀不在白名单都会以明确的错误消息被拦截而这些错误又反过来推动执行器不断变得宽容。对于想要复现或二次开发的同学建议重点阅读三处源码apply_patch_executor.py补丁解析、安全校验与写入执行的完整实现hello_code_cli.py补丁提取、规范化、人工确认与笔记记录闭环tools.md约束 Agent 写文件必须走补丁的提示词纪律。同时.helloagents/notes/与.helloagents/backups/目录本身就是最生动的运行日志前者记录每一次成功与失败后者为每一次修改留下后悔药。理解这套机制你就掌握了这类 Code Agent 安全写文件的核心设计思路。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考