仓库内编程助手的系统提示词设计HelloAgents Code Agent CLI 的角色边界、安全准则与补丁协议全解析【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents导读本文以 HelloAgents Code Agent CLI 的全局系统提示词 system.md 为主线逐条拆解这个类似 Claude Code/Codex 的仓库内编程助手如何通过提示词定义「角色定位、路径安全边界、按需探索策略、补丁写盘协议与对话历史隔离规则」并结合 code_agent.py、hello_code_cli.py 与 apply_patch_executor.py 的源码实现说明这些「纸面规则」如何在运行时被真正执行。读完本文你将理解如何为一个在真实代码仓库中自主工作的 Agent 设计系统提示词并掌握一套可复制的安全落盘patch-only write协议。一、system.md 在 Code Agent CLI 中的角色定位HelloAgents Code Agent CLI 是一个基于 HelloAgents 框架组件HelloAgentsLLM/ContextBuilder/ReActAgent/TerminalTool/NoteTool/MemoryTool搭建的命令行智能体目标体验对标 Claude Code/Codex支持多轮对话、按需探索代码库、生成补丁并在用户确认后落盘见 code_agent/README.md。提示词统一存放在 prompts 目录 下各文件分工明确文件职责system.md全局行为与安全边界按需探索 / 敏感操作确认 / 补丁格式react.mdReAct 回合格式Thought/Action与工具输入约定plan.md规划工具plan[...]专用提示词summarize_observation.md工具输出摘要提示词tools.md六个内置工具的详细使用指南其中system.md是「总纲」它定义了 Agent 是谁、能在哪里活动、能做什么、不能做什么、以什么格式产出修改。在源码中它由 code_agent.py 在初始化时读取并作为system_prompt注入上下文构建器base_system (self.paths.prompts_dir / system.md).read_text(encodingutf-8) self.tools_reference_path self.paths.prompts_dir / tools.md self.system_prompt base_system也就是说每次run_turn构建上下文时这份提示词都会与对话历史、上次工具摘要一起拼入最终 Promptcode_agent.py。因此它本质上是一份「持续生效的宪法」——不随单轮对话消失。二、角色定位仓库内工作的 CLI 编程助手而非闲聊机器人system.md 的第一句话就划定了身份你是一个在仓库内工作的 CLI 编程助手类似 Claude Code/Codex不是闲聊机器人。这一定位直接决定了后续所有行为约束的取向Agent 的所有动作都以「在指定仓库内完成任务」为唯一目标回复追求简短直接。提示词末尾进一步规定了输出风格非代码/非工具回复尽量 ≤4 行直接给结论避免 Here is... 等冗余开场除非用户要求不使用 emoji事实性问题直接给结果。这一「轻量输出」策略在源码层有配套的闲聊兜底CodeAgent._is_chitchat会识别hi/hello/你好/在吗等问候词直接返回固定引导语而不进入 ReAct 循环code_agent.py避免无谓的工具调用与解析失败。三、工作区与路径安全边界杜绝路径逃逸system.md 规定「工作区固定为仓库根目录.」并给出核心准则第一条边界所有路径必须在 repo_root 内resolve 后校验前缀拒绝逃逸。这条规则并非停留在提示词层面。在初始化时CodeAgent.__init__会对repo_root执行resolve()code_agent.py把所有状态目录notes / memory / sessions / logs都收敛到repo/.helloagents/之下由 CodeAgentPaths 统一管理。真正的硬校验在补丁执行器ApplyPatchExecutor._safe_path中apply_patch_executor.py拒绝绝对路径以/或~开头用(repo_root / rel_path).resolve()解析出最终路径校验解析结果必须以repo_root前缀开头否则抛出Path escapes repo_root拒绝修改符号链接symlink。这意味着即使模型在补丁中写出../../etc/passwd这类路径执行器也会在落盘前拦截形成「提示词约束 代码硬校验」的双保险。四、按需探索先证据后结论避免无端全库扫描system.md 第二条准则强调按需探索只有确实需要证据时才调用终端优先小范围命令ls/rg --files/rg pat path/sed -n rangep file/cat file避免无端全库扫描。这是 Code Agent 与「一次把整个仓库塞进上下文」的传统 RAG 方案的关键区别。配合源码中的lazy_fetchTrue模式code_agent.py上下文构建只注入保底内容系统提示 最近对话max_history_turns10 上次工具摘要最近 3 条上下文预算控制max_tokens8000、reserve_ratio0.15、enable_compressionTrue扩展上下文不再自动注入而是由模型通过context_fetch[...]工具按需获取。为了进一步控制上下文膨胀工具输出会经过 LLM 摘要_summarize_observation会先截断超过 8000 字符的输出再用summarize_observation.md提示词压缩成 120~200 字左右的摘要code_agent.py并在输出超过 1800 字符时触发摘要summarize_threshold_chars1800。这套「先推理 → 证据不足再取证 → 取证即摘要」的节奏正是 system.md 与 react.md 中反复强调的「避免过度收集」。五、写盘唯一通道补丁协议system.md 中最具实操价值的一条是写盘唯一通道补丁 apply_patch。严禁cat /tee/ Here-Doc / 重定向等终端写法。也就是说模型想要修改任何文件都不能借助 shell 的重定向技巧只能输出结构化的补丁文本由 CLI 侧解析并执行。这条规则从提示词到执行层形成了完整的闭环我们分三层来看。5.1 提示词层补丁格式规范system.md 原文产出补丁时必须严格遵守以下格式*** 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关键规则六条第一行必须是*** Begin Patch前面不要有任何文字最后一行必须是*** End Patch操作行格式*** Add File: path/*** Update File: path/*** Delete File: pathAdd/Update 后面跟完整文件内容Delete 后面不需要内容不要在补丁外包裹 markdown 代码块不要用 路径相对于仓库根目录。提示词还专门给出了错误与正确示例防止模型把说明文字和补丁挤在同一行——例如*** Begin Patch前出现「这是一个补丁」即视为错误。在 react.md 中补丁必须放在Finish[...]内、与说明文字之间用空行分隔、*** Begin Patch独占一行否则会因解析失败而无法落盘。5.2 CLI 层补丁提取、规范化与人工确认hello_code_cli.py 负责从 LLM 回复中把补丁「抠」出来并决定是否需要人工确认提取_extract_patch先用正则优先匹配代码围栏patch/diff/text内的补丁再退回宽松的*** Begin Patch ... *** End Patch全局匹配hello_code_cli.py对模型偶尔用围栏包裹补丁的行为做了容错规范化_normalize_patch会把缺失***前缀的操作行如Update File: xxx自动补全为规范格式hello_code_cli.py确认策略_patch_requires_confirmation规定三类高风险补丁必须征求用户y/nhello_code_cli.py——包含*** Delete File:操作、涉及文件操作数 ≥ 6、变更行数/-开头行≥ 400。这与 system.md 中「高风险删除/覆盖大量/危险命令 rm/chmod/git reset --hard必须说明风险并征求确认最终执行由 CLI 裁决」的表述完全对应——「裁决权」在 CLI而不是模型。5.3 执行器层原子写、备份、冲突检测与规模限制最终落盘由ApplyPatchExecutor完成apply_patch_executor.py它实现了 system.md 规则背后的全部安全工程细节规模限制单个补丁最多修改max_files10个文件、max_total_changed_lines800行超出即拒绝后缀白名单默认只允许.py/.md/.toml/.json/.yml/.yaml/.txt/.html/.htm/.css/.js等文本文件防止误改二进制或敏感文件_enforce_suffixapply_patch_executor.py自动备份每次应用前把将被修改的文件备份到repo/.helloagents/backups/timestamp/_backup_fileapply_patch_executor.py原子写入先写临时文件并fsync再用os.replace原子替换目标避免写盘中断导致文件损坏_atomic_writeapply_patch_executor.py冲突检测Update 操作按 hunk 在原文中做精确子序列匹配找不到上下文时抛出PatchApplyError并给出path:search:关键字形式的复查提示同时提供「整文件替换」与「宽松匹配忽略行尾空白」两级容错_apply_update_payload/_find_subsequenceapply_patch_executor.py宽容解析_parse_patch会跳过前置/结尾的空行与代码围栏容忍模型常见的格式漂移apply_patch_executor.py。此外补丁应用成功或失败后CLI 都会通过NoteTool写入结构化笔记note_type分别为action与blocker把「发生过什么」沉淀下来供后续轮次检索hello_code_cli.py。六、对话历史边界系统规则不是对话内容system.md 专门用一段说明「对话历史的重要边界」[Role Policies]是系统角色定义和工作规则不是用户对话内容当用户询问「我们之前聊了什么/说了什么/总结对话」时只总结[Context]区块中的[user]/[assistant]交互记录不要把系统规则、工具定义、角色描述当作「对话内容」来总结总结对话时直接根据[Context]回答不需要调用 memory 或 note 工具。这条规则防止了两种典型事故一是模型把「系统提示词」当成用户说过的话复述出来造成信息泄漏二是为了回答「刚才聊了什么」这类元问题却去触发无谓的工具调用。源码层提供了双重保障_is_history_query识别「说了什么 / 之前说了什么 / what did i say / recap」等模式code_agent.py命中后直接由_reply_with_recent_history从内存中的history取出最近用户/助手消息生成回顾code_agent.py完全绕过 ReAct 循环与工具系统。七、工具体系context_fetch 优先其余按需system.md 列出了六种 ReAct Action 可用的工具并特别强调「优先使用聚合搜索工具」7.1 context_fetch[...]优先推荐按需获取扩展上下文单次可查多源自动控制预算约 800 tokens/源{sources: [files,notes,memory,tests], query: 关键词, paths: src/**/*.py}使用策略先用保底上下文对话历史 上次工具结果推理证据不足再调用。它优于单独调用 note/memory search——一次调用可搜索多个数据源避免多次工具调用导致上下文爆炸。在 prompts/tools.md 中context_fetch的使用场景被进一步明确搜索类名/函数名/错误栈、需要相关笔记/记忆时用已经拿到足够证据、或用户仅问对话历史时不用。7.2 其他工具工具用途关键约束terminal[...]只读检索ls/rg/cat/sed/head/tail/grep/git status/diff支持管道重定向/子命令替换/危险命令需确认写文件一律用补丁note[...]记录关键结论/阻塞/行动Markdown 持久化补丁成功/失败总结、阶段小结时使用memory[...]跨会话情景记忆SQLite需显式 add默认不自动写入plan[...]多步/模糊任务生成计划5~12 条步骤含 Risks 与 Validation 段落见 plan.mdtodo[...]多步骤任务跟踪状态 pending/in_progress/completed同时仅允许 1 个 in_progress这些工具在CodeAgent.__init__中被逐一注册到ToolRegistrycode_agent.py其中TerminalTool以confirm_dangerousTrue、default_shell_modeTrue初始化与提示词「默认允许 shell 语义、危险操作需确认」一致。tools.md 还给出了每个工具的 JSON 调用示例例如terminal[{command:rg -n \foo\ context/**/*.py,allow_dangerous:false}] note[{action:create,title:Patch applied,content:...,note_type:action,tags:[patch]}] memory[{action:add,memory_type:episodic,content:完成 hello.html 样式改造,importance:0.7}] todo[{action:add,title:设计简介页布局,desc:头部/简介/技能,status:pending}]八、复杂任务的执行节奏计划 → 取证 → 补丁 → 确认 → 落盘 → 验证system.md 将复杂任务总结为一条工作流复杂任务遵循计划 → 取证 → 补丁 → 确认 → 落盘 → 验证节奏最小改动满足需求。在 react.md 中这一节奏被细化为可执行规则每次回复必须同时包含Thought和Action缺一不可已有足够信息时必须用Finish[答案]结束不要为了「更全面」反复调用工具一旦证据足够rg 命中、关键文件片段、错误栈、配置项必须Finish如果发现自己准备重复执行相同工具调用说明没有新信息应立即Finish给出结论 最小化下一步建议多步骤任务≥2 个子步骤、需用户确认、跨回合先todo add再行动结尾todo list汇总。CodeAgent.run_turn还在用户输入命中「分步/步骤/计划/改造/完成后/多步」等词汇时向系统提示追加一行轻量提示引导模型先用 todo 跟踪code_agent.py。该提示不强制只提高倾向。九、实际运行环境配置与 CLI 命令要让上述全部规则生效需要按 code_agent/README.md 的快速开始配置并启动安装依赖根目录requirements-mvp.txt并在仓库根目录创建.env可参考.env.example至少包含DEEPSEEK_API_KEY...或其他 OpenAI 兼容 provider 的 key可选LLM_MODEL_IDdeepseek-chat、LLM_BASE_URLhttps://api.deepseek.com启动 CLI工作区默认.python3 -m code_agent.hello_code_cli --repo .内置命令:quit退出:plan 目标强制生成计划平时由模型按需调用plan[...]工具见 hello_code_cli.py。启动时 CLI 会打印 workspace、LLM provider/model/base_url 与 state 目录并做一次ping预检提前暴露 API key / base_url / model 配置问题hello_code_cli.py。可调环境变量变量默认值作用HELLOAGENTS_DIR.helloagents状态目录notes/memory/sessions/logs根路径CODE_AGENT_MAX_STEPS8ReAct 最大推理步数十、小结一份「提示词 代码」双闭环的 Agent 安全范式回顾 system.md它的设计价值可以归纳为四个层次身份层明确「仓库内编程助手」而非闲聊机器人输出风格极简边界层路径必须留在 repo_root 内写盘只能走补丁通道危险操作必须确认效率层按需探索、先保底上下文后取证、工具输出即时摘要控制上下文预算可审计层补丁应用有备份、有冲突检测、有成功/失败笔记每一次修改都可追溯。更重要的是这些提示词规则并非「纸上谈兵」——ApplyPatchExecutor的路径校验与原子写、hello_code_cli.py的补丁提取与确认策略、CodeAgent的闲聊/历史查询拦截共同保证了提示词约束在代码层的强制执行。对于任何想构建「在真实仓库里安全自主工作」的 Agent 的开发者这份 system.md 连同 react.md、tools.md 与执行器源码是一套可以直接对照复用的完整参考实现。【免费下载链接】hello-agents 《从零开始构建智能体》——从零开始的智能体原理与实践教程项目地址: https://gitcode.com/GitHub_Trending/he/hello-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考