03. 让 Agent 更聪明System Prompt 的分层设计从零到一实现一个 AI Agent 框架 · 第三篇1. 为什么 System Prompt 需要设计先看一个最天真的 System Prompt你是一个 AI 助手可以调用工具。效果怎么样模型会试图用cat读文件而不是已有的read_file工具修一个 bug 顺便改了三处无关代码为可能存在 null的地方加 try-catch实际上永远不会 null回答长得像论文摘要问题的本质LLM 的训练数据让它有很强的默认行为。它见过海量的 shell 脚本所以倾向于用 bash 而不是专用工具。它在代码库训练语料里看过无数防御性编程所以觉得加 try-catch 是好习惯。不给规则它就回退到训练数据中的默认模式。2. 第一招反模式接种与其说要怎么做不如先说明不要怎么做。Axon 参考了 Claude Code 的 System Prompt 设计引入了三条反模式规则规则一不要扩大范围- 用户修一下这个函数里的 bug - AI好我修了 bug顺便重构了周围的模块、加了注释、优化了命名……修 bug 就修 bug。不要顺手重构、加注释、或者顺带优化。你的任务边界由用户的问题定义不是由你发现的可以改进的地方定义。用户这个计算不对 你的回答应该是修复计算不是重构整个文件。规则二不要防御性编程// ❌ 不要functionparseUserId(input:string):number{try{returnparseInt(input);}catch{return0;// 这个永远不会触发parseInt 不抛异常}}// ✅ 要functionparseUserId(input:string):number{returnparseInt(input);}不为不可能发生的场景加 try-catch、null 检查或兜底逻辑。如果某个值理论上一定存在、某个操作理论上一定成功就不要为假设的失败写代码。规则三不要过早抽象一次用法 → 保持内联 两次用法 → 可以观望 三次及以上 → 考虑抽象“Three similar lines premature abstraction.”3. 第二招爆炸半径框架反模式规则再多也列不完。更好的方法给模型一个风险评估框架让它自己判断。爆炸半径 可逆性 × 影响范围等级特征例子 低风险可逆仅影响当前上下文读文件、查数据、写分析 中风险可逆但影响共享环境创建文件、npm install、git commit 高风险不可逆或影响大范围git push、rm -rf、修改生产配置高风险操作 不可逆 影响共享环境规则很简单 低风险直接做 中风险做完告知用户 高风险先说风险和替代方案等用户确认这比列一个禁止做的事情清单要实用得多。清单永远列不完但框架可以推广到任何场景。4. 第三招工具偏好映射表模型在训练数据中看到最多的文件操作方式是 shell 命令cat、sed、echo 。但你的 Agent 有专用工具。需要明确告诉模型用哪个否则它会回退到知识中最高频的模式。- 读文件 → cat 读文件 → read_file不要用 cat - 改文件 → sed 改文件 → edit_file不要用 sed - 写新文件 → tee / heredoc 写新文件 → write_file不要用 tee - 搜索 → grep 搜索 → search_files / list_files - 长时间任务 → 阻塞等待 长时间任务 → background_run check_background这不是教条——这些专用工具在框架层面做了错误处理、上下文管理、权限检查。用 shell 绕过它们等于白装了这些功能。5. 如何组织到一起7 层递进结构把这些内容按从抽象到具体的顺序组织层内容作用1️⃣ Identity你是谁定位是什么建立角色认知2️⃣ System核心行为法则反模式 爆炸半径设定行为边界3️⃣ Doing Tasks任务管理系统DAG 模型拆解复杂目标4️⃣ Actions工具偏好映射表选择正确工具5️⃣ Using Tools各工具的用途和限制具体操作指引6️⃣ Tone输出风格要求统一表达方式7️⃣ Output Efficiency输出精简要求减少废话这个顺序的逻辑先定义身份再划边界然后教工作流最后规范输出。前两层的 token 消耗是固定的后几层可以动态按需加载。6. 代码实现在 Axon 中落地Axon 的 System Prompt 拼装在agent.ts中核心逻辑很简单// 将所有部分拼装成最终的 system promptconstsystemPrompt[BASE_SYSTEM_PROMPT,// 1-3 层身份 行为法则 任务管理permissionsSection,// 权限与安全补充第 2 层memoryContext,// 记忆系统memoryPromptSection,// 结构化记忆指引agentsContext,// 项目上下文AGENTS.mdskillsSection,// Skill 列表toolsSummarySection,// 工具摘要teamsSection,// 协作信息].filter(Boolean).join(\n\n);关键点BASE_SYSTEM_PROMPT是硬编码的核心包含 7 层的第 1-3 层 工具偏好映射表动态部分记忆、Skills、工具列表在运行期拼装放在末尾利用近因效应权限部分单独成段因为涉及敏感操作需要突出显示7. 效果对比修改前 VS 修改后同一个场景的典型表现场景用户说帮我看看这个函数的 bug修改前“好的我读了文件发现函数calculateTotal有几个问题首先它没有做 null 检查其次变量命名不够清晰另外周围的模块也可以优化一下我一起改了……” 扩大了范围、做了防御性判断、还顺手重构。修改后“问题在第 42 行total被除 100 而不是 1000。”然后只修改那一行 精确、克制、只解决问题。总结手法解决什么问题Token 成本反模式接种模型默认行为不符合预期~150 tokens爆炸半径框架穷举禁止清单不可扩展~100 tokens工具偏好映射表模型倾向于用 shell 而非专用工具~80 tokens7 层递进结构组织方式影响模型遵循程度0重新组织而已成本不到 400 tokens买来的是模型行为质的提升。下一篇权限与安全系统——别让 Agent 乱跑。