1. 从“指令”到“角色”重新理解Trae-Agent中的system_prompt最近在折腾Trae-Agent这类智能体框架时我发现很多朋友对system_prompt的理解还停留在“给AI下指令”的层面。这其实是一个巨大的误区。如果你只是把它当成一个简单的“开场白”或者“任务描述”那很可能你只发挥了它10%的威力。在我深度使用和调试了多个基于大模型的Agent项目后我越来越觉得system_prompt的本质不是“指令”而是“角色定义”和“世界观构建”。它决定了你的Agent将以何种身份、何种认知框架、何种行为模式来与你互动处理user_prompt。想想看当你对同一个大模型说“写一份产品分析报告”如果system_prompt是“你是一位严谨的数据分析师”那么生成的报告会充满图表、数据对比和理性推论如果system_prompt是“你是一位富有洞察力的市场战略专家”报告可能更侧重于趋势判断、竞争格局和机会挖掘。输入user_prompt相同输出却可能天差地别这中间的“魔法”就来自于system_prompt所塑造的“角色灵魂”。在Trae-Agent这类需要完成复杂、多步骤任务的框架中一个精心设计的system_prompt更是智能体能否稳定、可靠、高质量工作的基石。它不仅仅是告诉模型“要做什么”更是定义了“你是谁”、“你如何看待这个世界”以及“你如何思考问题”。本文将结合我在Trae-Agent项目中的实践抛开那些泛泛而谈的“提示词技巧”深入到system_prompt的设计哲学、核心结构、避坑指南以及高级玩法。无论你是刚接触Agent开发的新手还是希望优化现有智能体表现的老手相信都能从中获得一些可以直接落地的思路。我们不止步于“怎么写”更要深究“为什么这么写”以及“这么写之后模型内部到底发生了什么变化”。2. system_prompt的四大核心支柱超越基础指令一个强大的system_prompt绝不仅仅是任务描述的堆砌。经过反复试验和总结我认为一个能支撑Trae-Agent完成复杂任务的system_prompt必须构建在四大核心支柱之上角色与身份、能力与边界、思维与流程、风格与格式。这四者共同作用为智能体构建了一个完整的“认知操作系统”。2.1 角色与身份为智能体注入“人格”这是system_prompt的基石也是最容易被忽视的部分。一个模糊的身份会导致模型行为的不稳定。具体化而非抽象化不要说“你是一个助手”而要说“你是一名拥有十年经验的资深全栈开发工程师尤其擅长Python后端与React前端架构”。前者让模型调用的是通用的“助手”人格后者则激活了其知识库中与“资深开发者”相关的专业模式、术语体系和问题解决思路。赋予背景与目标身份需要上下文。例如“你是‘CodeReviewGPT’一家快速发展的科技公司的内部代码质量守护者。你的核心目标是提升团队代码的可维护性、性能与安全性而非一味追求代码风格的统一。” 这个背景赋予了智能体行动的“意义”和优先级。实践心得在Trae-Agent中如果你设计的Agent需要与数据库交互将其身份定义为“一名谨慎的数据库管理员”会比“一个数据处理工具”有效得多。前者在生成SQL语句时会天然地考虑WHERE条件是否完备、是否避免SELECT *、是否想到备份这些隐性约束来自于角色自带的“职业素养”。2.2 能力与边界明确“能做什么”与“绝不能做什么”这是控制智能体行为范围、保障安全性与可靠性的关键。大模型存在“幻觉”即生成看似合理但实际错误或超出范围的内容清晰的边界能有效抑制这一点。能力声明明确列出智能体的核心技能。例如“你的能力包括1解析自然语言需求并转化为精准的Git命令2理解代码变更内容并生成符合规范的提交信息3识别简单的代码冲突提示。” 这相当于给模型一个“技能清单”引导它调用相关知识。硬性边界这是安全阀。必须用清晰、无歧义的语言陈述。例如“你绝不能1执行任何未明确声明的、具有破坏性的系统命令如rm -rf /,format等。2在未经验证的情况下直接修改生产环境配置文件。3对无法确认的问题提供肯定性答案对于不确定的部分必须明确声明‘此部分信息未经核实建议……’。”输入输出规范定义交互的“协议”。例如“用户将提供代码变更的文件路径或git diff输出。你必须首先确认变更摘要然后提供建议的提交信息。你的输出必须严格遵循以下JSON格式{\summary\: \变更摘要\, \message\: \提交信息\}。” 这极大方便了Trae-Agent对智能体输出进行后续的程序化处理。2.3 思维与流程定义解决问题的“算法”对于复杂任务单次响应往往不够。我们需要在system_prompt中植入一个“思维链”或“工作流程”引导模型进行分步、结构化的思考。这是提升Trae-Agent处理复杂任务可靠性的核心。强制思考步骤要求模型在输出最终答案前必须显式地经历几个思考阶段。例如“面对任何问题请严格按以下顺序思考并可在内部推理中体现第一步澄清与确认——复述问题确认关键约束条件。第二步分解与规划——将大问题拆解为可执行的子任务序列。第三步执行与核查——针对每个子任务进行处理并检查其结果是否符合预期。第四步整合与输出——汇总所有结果形成最终答案。”提供决策框架对于分析、评估类任务给出分析维度。例如“在评估一个技术方案时请始终从以下四个维度进行考量1可行性技术实现难度、资源需求2可维护性代码复杂度、文档需求3性能时间复杂度、空间开销、扩展性4安全性潜在风险点、数据隐私。请在你的分析中明确提及对这四点的判断。”实操技巧在Trae-Agent中你可以利用这个特性来实现“自检”机制。例如在代码生成Agent的system_prompt中加入“在输出代码后你必须自动增加一个‘自检环节’用几句话简要说明1这段代码的核心逻辑是什么2潜在的性能瓶颈或边界条件在哪里3假设需要扩展功能应从何处入手。” 这能显著减少生成代码中隐藏的严重逻辑错误。2.4 风格与格式控制输出的“样子”这是最终呈现层决定了信息的可用性和可读性。语言风格是严谨学术风还是简洁商务风或是活泼易懂的科普风例如“请使用清晰、直白、无歧义的技术文档语言避免使用比喻和抒情性文字。面向的读者是具备基础知识的开发人员。”结构化输出强烈建议要求固定格式。对于Trae-AgentJSON、YAML、Markdown表格是最友好的格式便于后续的自动化解析。例如“你的所有输出都必须是一个有效的JSON对象。对于分析报告使用{\结论\: \\, \论据\: [\\, \\], \建议\: [\\, \\]}格式。对于操作指令使用{\动作\: \\, \参数\: {}, \说明\: \\}格式。”负面风格约束明确禁止不希望出现的形式。例如“禁止在输出中使用‘我认为’、‘可能’、‘大概’等模糊性词语对于事实性内容要么肯定陈述要么明确表示‘未知’。禁止输出任何与任务无关的客套话或开场白。”将这四大支柱组合起来一个Trae-Agent的system_prompt骨架就清晰了。它从一个模糊的“指令接收器”变成了一个目标明确、能力清晰、思维有序、输出规范的“虚拟专家”。3. 从理论到实践一个Trae-Agent智能体的system_prompt构建实录让我们脱离理论直接看一个为Trae-Agent设计的、用于“自动化代码审查与优化建议”的智能体system_prompt完整示例并拆解其每一部分的设计意图。# 角色CodeGuard - 智能代码审查专家 你是一名代号为CodeGuard的顶尖代码审查专家受聘于一个对代码质量和安全有极高要求的快速迭代开发团队。你的使命不是吹毛求疵而是成为开发者的“第二双眼睛”专注于发现那些容易引发线上故障、安全漏洞或长期维护噩梦的关键问题。 ## 你的核心能力与工作边界 **你能做的** 1. **深度分析**理解提供的代码片段支持Python, JavaScript, Java, Go的上下文和意图。 2. **问题识别**精准定位代码中的以下类别问题 * **致命缺陷**空指针引用、资源未释放、死锁风险、SQL注入等安全漏洞。 * **性能瓶颈**时间复杂度高的循环、重复计算、低效的数据结构使用。 * **可维护性陷阱**过深的嵌套、超长的函数、魔法数字、含糊的命名。 * **规范偏离**严重违反项目既定编码规范如PEP 8, Airbnb JS规范的行为。 3. **提供解决方案**针对每个识别出的问题提供**具体的、可直接使用的**代码修改建议并简要解释修改为何能解决问题。 4. **风险评估**对识别出的问题标注优先级高/中/低高优先级意味着必须立即修复。 **你绝不能做的** 1. 对代码风格上无关紧要的差异如单引号与双引号提出批评除非项目规范有明确强制要求。 2. 在未明确指出的情况下假设或修改代码的业务逻辑。 3. 输出任何无法在提供的代码片段中找到依据的批评。 4. 提供模糊的建议如“这里可以优化”必须附上具体代码。 ## 你的审查工作流程 面对每一份提交的代码请严格遵循以下思维流程你可以在最终输出前进行内部推理 1. **理解意图**这段代码试图完成什么功能它的输入和输出是什么 2. **逐行扫描**结合你的能力清单像静态分析工具一样检查每一行标记可疑模式。 3. **上下文关联**发现的问题是否在函数/模块的其他部分有牵连是否与常见的反模式匹配 4. **归类与评级**将确认的问题归入“致命缺陷”等类别并赋予优先级。 5. **构思方案**为每个高/中优先级问题思考至少一种修复方案确保方案本身不引入新问题。 ## 你的输出格式 你必须且只能以如下JSON格式输出。这是与调用你的自动化系统Trae-Agent的约定协议。 json { overall_status: PASS | FAIL | WARNING, issues: [ { type: SECURITY | PERFORMANCE | MAINTAINABILITY | CONVENTION, priority: HIGH | MEDIUM | LOW, location: 文件路径:行号如 main.py:15, description: 清晰描述问题现象及潜在风险, suggestion: 具体的代码修改建议可多行, reason: 简要说明为何这个修改更好 } ], summary: 本次审查的简要总结突出最关键的风险点。 }记住你的输出将被另一个程序直接解析。格式错误意味着任务失败。**设计意图拆解** 1. **角色塑造CodeGuard**赋予了专家身份和具体使命“第二双眼睛”设定了积极的工作基调“不是吹毛求疵”这能引导模型以建设性而非批判性的态度工作。 2. **能力清单化**将“代码审查”这个模糊任务拆解为“深度分析”、“问题识别”等具体动作并给出了问题的详细分类和例子。这极大地缩小了模型的思考范围提高了识别精度。 3. **负面清单绝不能做**这是防止Agent“滥权”或“跑偏”的关键。明确禁止了对风格细微差别的纠缠、对业务逻辑的假设以及模糊输出这直接针对了大模型在代码审查中常见的几种“不良行为”。 4. **内置工作流程**将专业的代码审查思路理解意图-逐行扫描-上下文关联-归类评级-构思方案固化到提示词中。即使模型内部是一步到位的这个流程要求也强制它进行更结构化的“思考”输出更可靠的结果。 5. **严格的格式化输出**定义了与Trae-Agent集成的契约。overall_status给出了直观的结果判断issues数组结构化地承载所有细节方便后续的自动化报告生成、任务分发如高优先级问题自动创建工单。最后的强调句“你的输出将被另一个程序直接解析”是给模型的重要上下文让它明白严格遵守格式的极端重要性。 这个system_prompt不再是一个简单的命令而是一份完整的“岗位说明书”和“工作手册”。当Trae-Agent将代码作为user_prompt传递给这个智能体时它就知道自己该以何种方式、遵循何种流程、产出何种结果。 ## 4. 高级技巧与避坑指南让system_prompt真正发挥作用 有了好的设计还需要正确的使用方法和对潜在问题的预见。以下是几个在Trae-Agent项目中实践得出的关键技巧和常见陷阱。 ### 4.1 技巧一使用“占位符”与“环境变量”实现动态化 静态的system_prompt缺乏灵活性。在Trae-Agent中我们经常需要根据运行时的上下文来调整智能体的行为。这时可以使用占位符。 * **示例**在system_prompt中写入“你是负责处理{{project_name}}项目的部署专家。当前部署环境是{{env}}你的操作必须符合{{security_level}}安全等级的要求。” * **实现**在Trae-Agent调用该智能体前通过模板渲染引擎如Jinja2或用字符串替换的方式将{{project_name}}等占位符替换为实际的值。这使得同一个智能体模板能复用于不同项目和环境极大提升了灵活性。 * **心得**占位符特别适用于需要注入时间、用户信息、项目配置等动态数据的场景。这相当于为智能体提供了“实时上下文”。 ### 4.2 技巧二设计“分层”或“模块化”的system_prompt 对于超级复杂的智能体一个巨长无比的system_prompt效果可能反而下降。可以考虑分层设计。 * **核心层**一个非常精简、稳定的核心system_prompt只定义最根本的角色、目标和输出格式。例如“你是决策协调中心负责将任务分发给专业子智能体并整合结果。你只输出JSON格式的调度指令。” * **配置层**将具体的“能力清单”、“工作流程”、“风格要求”等作为外部配置文件或数据库记录。在Trae-Agent初始化智能体时动态地将核心层与对应的配置层拼接起来。 * **好处**便于管理、复用和A/B测试。你可以轻松切换不同的“审查流程配置”或“风格配置”而无需改动核心角色定义。 ### 4.3 避坑一避免冗长与信息过载 虽然我们强调要详细但“详细”不等于“啰嗦”。大模型有上下文窗口限制过长的system_prompt会挤占处理user_prompt和生成响应的空间也可能导致模型忽略尾部的重要指令。 * **黄金法则**优先确保“边界”和“格式”指令清晰且位置靠前或靠后模型对开头和结尾的内容通常更敏感。中间的能力描述可以适当精简用列表和分类提高可读性。 * **测试方法**设计一个边缘案例或一个故意违反规则的user_prompt测试智能体是否能严格遵守system_prompt中的禁令。如果不能可能需要强化禁令的表述或调整其位置。 ### 4.4 避坑二警惕指令冲突与歧义 system_prompt内部的指令必须自洽。例如如果你既要求“输出尽可能详细”又要求“回答必须简洁”模型就会陷入困惑结果可能不可预测。 * **检查清单**在完成system_prompt撰写后通读一遍检查是否存在 * **矛盾点**例如既要求“创造性思考”又要求“严格遵循范例”。 * **模糊词**例如“尽快”、“高质量”、“适当”等应替换为具体标准如“在3秒内响应”、“无语法错误”、“遵循XX规范”。 * **开放漏洞**例如“不要做有害的事”这过于宽泛应具体化为“不得生成恶意代码、虚假信息、人身攻击内容”。 ### 4.5 避坑三忽略模型本身的“固有倾向” 不同的底层大模型如GPT-4、Claude、GLM对同一段system_prompt的理解和服从程度可能有差异。有的模型更“听话”有的则更“有主见”。 * **对策**为你的Trae-Agent项目选定主模型后需要针对该模型对你的system_prompt进行微调。例如某些模型可能需要更强烈的语气如“你必须”、“严禁”来约束行为而另一些模型对温和的引导如“请最好”、“我们建议”反应更好。这需要通过多次实验来找到最佳表达方式。 * **一个真实踩坑案例**我曾用一个在GPT-4上运行良好的“代码审查专家”system_prompt去跑另一个开源模型结果该模型频繁地对我代码中的注释语法提出“修改建议”因为它过度放大了“规范偏离”这个类别而忽略了“对无关紧要的差异提出批评”的禁令。后来我在禁令中加入了更极端的例子“即使看到注释符是#而不是//只要不影响理解就绝对不要提及”才解决了问题。 ## 5. 与user_prompt的协同构建高效对话的基石 system_prompt定义了智能体的“人设”而user_prompt则是每次交互的具体“剧本”。二者需要默契配合。在Trae-Agent的上下文中user_prompt往往不是一句简单的聊天而是一个结构化的任务请求或一段待处理的数据。 ### 5.1 user_prompt的设计原则清晰、结构化、无歧义 * **提供充足上下文**不要假设智能体能记住之前的所有对话除非你使用了对话历史功能。在user_prompt中应包含当前任务所需的所有信息。例如对于代码审查Agentuser_prompt就应该是完整的代码片段或diff输出而不是只说“请审查这段代码”。 * **明确任务指令**即使system_prompt已经定义了能力在user_prompt中再次明确本次的具体动作也是好习惯。例如“请根据你的审查流程对以下Python函数进行安全性扫描并按照指定JSON格式输出。” * **结构化输入**如果可能将user_prompt也结构化。例如使用类似“代码{code}”或“问题{question}”的格式这有助于模型快速解析意图。 ### 5.2 协同工作模式举例 假设我们有一个基于前述CodeGuard的Trae-Agent智能体。 * **低效的user_prompt**“看看这段代码有没有问题” * **问题**过于模糊。代码在哪是什么语言system_prompt中定义的能力无法被有效触发。 * **高效的user_prompt** 语言Python 代码功能用户登录验证 代码片段 python def login(username, password): query fSELECT * FROM users WHERE username{username} AND password{password} result db.execute(query) return result is not None 任务执行完整代码审查重点关注安全性与潜在缺陷。 * **分析**这个user_prompt提供了语言、功能上下文、具体代码。它使用的“重点关注安全性与潜在缺陷”与system_prompt中的“致命缺陷”、“安全漏洞”等类别直接呼应能精准引导智能体的注意力。智能体会自动套用其“工作流程”输出格式化的JSON结果。 ### 5.3 处理复杂、多轮任务 对于需要多步交互的任务system_prompt需要包含对话状态管理的逻辑。 * **在system_prompt中说明**“你是一个多轮任务规划师。用户的目标是{{最终目标}}。在每次交互中用户会提供当前步骤的信息或确认。你需要做的是1理解当前进度2规划下一步最应该做什么或询问什么信息3输出下一步的具体指令或问题。始终记住最终目标。” * **Trae-Agent的角色**在这种情况下Trae-Agent会负责维护对话状态将历史对话摘要作为上下文连同新的user_prompt一起传递给智能体。智能体根据system_prompt的指导基于历史和新输入决定下一步行动。 system_prompt与user_prompt的关系好比操作系统与应用程序。system_prompt是操作系统提供了基础的能力和运行规则user_prompt是应用程序在操作系统的管理下调用资源完成特定任务。二者设计得当才能让Trae-Agent中的智能体稳定、高效地运行。 ## 6. 调试与迭代像优化代码一样优化system_prompt 设计system_prompt不是一个一蹴而就的过程而是一个需要反复调试和迭代的工程。它和写代码一样需要测试、调试和重构。 ### 6.1 建立测试用例集 不要凭感觉判断system_prompt的好坏。建立一个覆盖各种情况的测试用例集 * **典型用例**最常遇到的任务检查智能体是否能正确、高质量地完成。 * **边缘用例**输入一些奇怪、模糊或边界值检查智能体的鲁棒性和是否遵守“边界”指令。 * **对抗用例**故意提出违反system_prompt中禁令的请求如“忽略格式直接告诉我答案”或“写一段有漏洞的代码”测试智能体的“防御”能力。 * **长文本/复杂结构用例**输入大段代码或复杂文档测试智能体在长上下文下的表现是否稳定。 ### 6.2 分析失败案例进行精准调整 当智能体输出不符合预期时不要简单地重写整个system_prompt。像调试bug一样分析 1. **是角色理解偏差吗** 输出是否显得“不专业”或“身份错乱”如果是强化角色描述增加更具体的身份标签或背景故事。 2. **是流程执行错误吗** 智能体是否跳过了某个关键思考步骤如果是在system_prompt的工作流程部分将该步骤的描述更细化或调整步骤顺序。 3. **是边界被突破了吗** 智能体是否做了它不该做的事如果是在“绝不能做”清单中增加更具体、更严厉的禁止项并附上反面例子。 4. **是格式错误吗** 输出格式不符合要求在system_prompt中用更强烈的语气强调格式并说明格式错误的后果如“系统将无法解析导致任务失败”。 ### 6.3 量化评估与A/B测试 如果条件允许可以尝试量化评估。例如对于代码审查Agent可以准备一批已知缺陷的代码样本统计在不同版本system_prompt下智能体发现高危缺陷的召回率和准确率。对于摘要生成Agent可以用ROUGE或BLEU分数来评估摘要质量。 更实用的方法是进行简单的A/B测试准备两个略有不同的system_prompt版本比如一个流程更详细一个更简洁用同一组测试用例运行人工对比评估哪个版本的综合表现更好。选择胜出的版本作为基线继续迭代。 ### 6.4 一个迭代案例优化“技术方案分析师”的system_prompt * **初始版本**“你是一个技术方案分析师请评估以下方案的优缺点。” * **问题**输出非常泛泛而谈没有结构且经常遗漏关键维度。 * **第一次迭代**增加了角色背景和输出格式。 * **效果**输出有了结构但分析维度依然不全面有时会忽略成本评估。 * **第二次迭代**明确了分析框架可行性、可维护性、性能、安全性、成本并强制要求按此框架输出。 * **效果**分析全面了很多但有时对“可行性”的判断过于乐观缺乏依据。 * **第三次迭代**在“思维流程”中增加了一步“对于可行性判断必须列举出需要的关键技术、潜在的技术风险点以及大致的人力/时间估算。” * **效果**输出的可行性分析变得有据可依质量显著提升。 这个过程清晰地展示了如何通过观察缺陷、定位问题、修改system_prompt的特定部分来逐步提升智能体的表现。记住system_prompt是你与模型沟通的“代码”也需要遵循良好的工程实践。