HelloAgents Code Agent CLI 补丁落盘机制解析从*** Begin Patch到安全文件写入【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents导读本文以 HelloAgents Code Agent CLI 项目内一份真实的Patch applied行动笔记为线索深入剖析这套类 Claude Code / Codex 的本地代码智能助手如何将 LLM 生成的补丁安全、可控地落到真实文件系统。读者将掌握 Codex 风格补丁的完整格式规范、CLI 侧的提取与确认流程、ApplyPatchExecutor的路径防护与原子写入实现并通过一个创建文件→确认→删除文件→自动备份的完整案例理解其安全边界设计。一份真实的 Patch applied 笔记在仓库的 notes 目录 中保存了一条由 CLI 自动生成的结构化行动笔记它是整个补丁机制最直观的缩影id: note_20251219_191656_22 title: Patch applied type: action tags: [hello_agents_forStudy, patch_applied] # Patch applied User input: 在testDem新建一个一个文档 写上 我讨厌java Patch: *** Begin Patch *** Add File: testDemo/我讨厌java.txt 我讨厌java *** End Patch Files: - testDemo/我讨厌java.txt这条笔记揭示了完整链路用户用自然语言提出在 testDemo 新建一个文档写上内容智能体将其翻译为一条标准补丁经 CLI 校验后落盘并把整个过程作为action类型笔记回写到.helloagents/notes/下供后续会话检索。值得注意的是笔记中还保留了模型犯错的宽容处理痕迹——Add File后的正文直接书写我讨厌java而非带前缀的规范形式这正是执行器宽松解析设计要兼容的场景见后文源码分析。补丁格式规范写在系统提示词中的写盘唯一通道项目在 code_agent/prompts/system.md 中为模型定义了严格的补丁格式其核心理念是补丁是写盘的唯一通道明确禁止cat 、tee、Here-Doc、重定向等终端写法。标准格式*** Begin Patch *** Add File: path/to/new_file.py 文件内容... 可以多行... *** Update File: path/to/existing_file.py 更新后的完整文件内容... *** Delete File: path/to/old_file.py *** End Patch关键规则来自 system.md第一行必须是*** Begin Patch前面不能有任何文字最后一行必须是*** End Patch操作行格式为*** Add File: path/*** Update File: path/*** Delete File: pathAdd/Update后面跟完整文件内容Delete不需要内容不要在补丁外包裹 markdown 代码块不要用路径相对于仓库根目录。系统提示词还给出了明确的错误与正确示例例如第一行写成这是一个补丁再跟*** Begin Patch即视为错误格式。与系统级安全准则的关系system.md 同时规定了工作区边界所有路径必须在 repo_root 内resolve 后校验前缀拒绝逃逸模型应按需探索优先ls/rg --files/sed -n等小范围命令避免无端全库扫描高风险操作删除/覆盖大量文件、rm/chmod/git reset --hard必须说明风险并征求确认最终执行由 CLI 裁决。补丁机制正是这些安全准则在写盘环节的落地载体。CLI 侧的补丁提取与规范化当模型在 ReAct 循环中输出补丁后code_agent/hello_code_cli.py 负责把它从回复文本中捞出来并清洗主要经历两个阶段1. 提取_extract_patch使用两个正则hello_code_cli.pyPATCH_RE re.compile(r\s*\*\*\* Begin Patch[\s\S]*?\*\*\* End Patch, re.MULTILINE) PATCH_FENCE_RE re.compile( r(?:patch|diff|text)?\s*(\*\*\* Begin Patch[\s\S]*?\*\*\* End Patch)\s*, re.MULTILINE, )提取策略是优先匹配代码围栏内的补丁patch/diff/text围栏匹配不到再退回普通模式允许前导空白。这也解释了笔记中补丁被包在text围栏内的原因——两种写法都会被正确识别。2. 规范化_normalize_patch为宽容处理模型的格式错误CLI 会检测形如Add File:/Update File:/Delete File:但缺少前导***的操作行并自动补全为***前缀hello_code_cli.py确保交给执行器的补丁始终是标准 Codex 风格。3. 空补丁过滤若提取出的补丁仅为*** Begin Patch\n*** End Patch空壳会被直接跳过不产生任何文件操作。ApplyPatchExecutor安全执行器的源码级剖析补丁的真正落地由 code_agent/executors/apply_patch_executor.py 完成。从类注释可以看到它声明的安全特性MVPrepo_root 路径限制、临时文件 os.replace原子写入、自动备份到.helloagents/backups/timestamp/、文件数与变更行数限制、Update File 的冲突检测。构造参数与默认白名单def __init__(self, repo_root, max_files10, max_total_changed_lines800, allowed_write_suffixesNone):max_files10单个补丁最多触碰 10 个文件max_total_changed_lines800单个补丁变更总行数上限allowed_write_suffixes默认为.py/.md/.toml/.json/.yml/.yaml/.txt/.html/.htm/.css/.js防止误改二进制或敏感文件。执行主流程apply解析补丁_parse_patch将文本拆成(kind, path, payload)操作列表支持add/update/delete三种类型规模校验触碰文件数超过max_files或估算变更行数超过max_total_changed_lines时抛出PatchApplyError创建备份目录按datetime.now().strftime(%Y%m%d_%H%M%S)生成时间戳目录逐操作执行每个操作先做安全校验再先备份、后写入。三层安全校验路径安全_safe_path拒绝以/或~开头的绝对路径将相对路径resolve()后必须位于 repo_root 前缀之下否则视为路径逃逸Path Traversal拒绝修改符号链接apply_patch_executor.py。后缀白名单_enforce_suffix目标文件后缀不在允许列表即拒绝写入。原子写入_atomic_write先在目标同目录创建临时文件并写入、flush、fsync再用os.replace原子替换目标文件保证写入中断不会损坏文件apply_patch_executor.py。备份机制_backup_file将目标文件按相对路径结构复制到repo/.helloagents/backups/timestamp/下后缀追加.bak。仓库中真实存在的备份证据——.helloagents/backups/20251219_192206/testDemo/我讨厌java.txt.bak——正是 delete 补丁执行前自动生成的备份。Update File 的冲突检测与宽容兜底更新操作先读入原文件将 payload 按分隔符或空行切分为多个 hunk再在当前文件中查找上下文删除行的精确子序列匹配失败则抛出带recheck_targets提示的PatchApplyError提示形如file:search:context_line。_find_subsequence在精确匹配失败后会忽略行尾空白再试一次缓解缩进/换行偏差_apply_update_payload还提供宽松兜底当 payload 完全没有/-/空格前缀时视为整文件替换。高风险补丁的人工确认机制CLI 通过_patch_requires_confirmation判断补丁是否需要人工确认hello_code_cli.py触发条件为补丁中包含*** Delete File:删除操作文件操作数 ≥ 6变更行数 ≥ 400统计/-前缀行。命中任一条件即打印⚠️ 检测到高风险补丁删除/大规模变更。是否应用(y/n)并二次询问。这与 system.md 中高风险必须说明风险并征求确认最终执行由 CLI 裁决的准则一一对应。配套的另一条真实笔记 note_20251219_192206_23.md 记录了用户输入确认后delete 补丁*** Delete File: testDemo/我讨厌java.txt被放行执行的完整过程。全生命周期联动成功应用补丁后CLI 自动调用 NoteTool 写入Patch applied笔记记录 User input、补丁原文、变更文件列表失败则写入Patch failed的blocker类型笔记便于后续排查。这一机制由 code_agent/agentic/code_agent.py 中的NoteTool与ReActAgent协作完成笔记按repo/.helloagents/notes/持久化可通过context_fetch工具跨会话检索。完整案例复盘一次文件创建的端到端链路将上文串联起来笔记 note_20251219_191656_22 背后是一条完整的工程链路用户输入在 testDem 新建一个文档 写上 我讨厌javaReAct 推理模型判定需要写盘按 system.md 约束产出*** Add File: testDemo/我讨厌java.txt补丁CLI 提取_extract_patch从回复中含text围栏提取补丁主体风险评估纯Add File操作、单文件、2 行内容未触发确认条件执行器落盘_safe_path校验路径 →_enforce_suffix校验.txt白名单 → 创建父目录 →_atomic_write原子写入笔记归档生成Patch appliedaction 笔记路径与文件列表入库。随后的删除操作note_20251219_192206_23则走高风险确认路径*** Delete File:触发二次确认用户回复确认后执行删除前自动生成.bak备份到时间戳目录。运行与验证如需在本地复现该机制可参考 README.md 的快速开始git clone https://gitcode.com/datawhalechina/hello-agents cd Co-creation-projects/YYHDBL-HelloCodeAgentCli python -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 配置 .envLLM_BASE_URL / LLM_MODEL / DEEPSEEK_API_KEY python -m code_agent.hello_code_cli --repo .进入交互界面后输入文件创建类需求即可观察补丁生成、确认如涉及删除与落盘全过程落盘后检查.helloagents/notes/下的行动笔记与.helloagents/backups/下的备份即可验证安全机制。环境要求为 Python 3.10跨 macOS / Linux / Windows。小结从一份寥寥数行的Patch applied笔记出发可以完整还原 HelloAgents Code Agent CLI 的补丁安全体系格式层面的写盘唯一通道约束、CLI 层的宽容提取与风险评估、执行器层的路径防护/后缀白名单/原子写入/自动备份/冲突检测以及贯穿始终的先确认、后落盘人机协作原则。对于想要构建自己的本地代码智能助手的开发者这套补丁即接口的设计——让 LLM 输出结构化、可审计、可回滚的变更描述而非直接执行任意终端命令——是极具参考价值的工程范式。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/datawhalechina/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考