1. 从一次模板渲染失败说起SWE-agent 的 Prompt 到底怎么组织如果你正在做 SWE-agent 的二次开发或者打算把它的 Prompt 体系迁移到自己的 Agent 项目里大概率会遇到一个很具体的问题模板文件改完之后Agent 的行为突然变得莫名其妙——要么变量没注入进去要么条件分支走了意料之外的路要么干脆在渲染阶段就抛出一个 Jinja2 的语法错误。SWE-agent 的 Prompt 不是散落在代码里的字符串拼接而是一套基于 Jinja2 的模板系统。它的核心思路是把「角色定义」「任务上下文」「执行反馈」拆成不同的模板层再通过一个统一的变量字典在运行时注入。理解这套组织方式比单纯复制某一段 Prompt 文本重要得多。这篇文章面向需要二次开发或迁移 Prompt 体系的工程师。我会先拆解 SWE-agent 代码库里 Jinja2 模板的分层结构和变量注入规律然后给出一份可复制的config.toml与settings.json骨架最后演示如何通过 TaoToken 的统一 Key/API 通道完成一次模板渲染验证。整个过程你可以跟着操作不需要改动 SWE-agent 的核心逻辑。2. TaoToken 前置统一 Key 与 API 通道的准备在开始拆模板之前先把调用通道准备好。SWE-agent 在运行时会调用大模型接口如果你在本地反复调试模板直接对接多个模型供应商的 Key 会很麻烦。TaoToken 的作用是提供一个统一的 API 入口你只需要维护一套 Key就能在模板验证阶段切换不同的模型。你需要先拿到一个可用的 API Key。访问 TaoToken 的 API Keys 管理页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite在控制台里创建一个新的 Key复制出来备用。注意不要把它硬编码进提交到 Git 的配置文件里建议用环境变量管理。TaoToken 的 API 基础地址是https://taotoken.net/api这个地址在后续的config.toml和settings.json里都会用到。如果你对接入方式还有疑问可以查阅接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite准备好 Key 和 API 地址之后我们就可以进入模板本身的拆解了。3. SWE-agent 的 Jinja2 模板分层与变量注入规律3.1 三层模板结构system / instance / next_stepSWE-agent 的模板配置类TemplateConfig里最核心的是三个字段它们对应 Agent 交互的三个阶段模板字段作用渲染时机system_template定义 AI 助手的角色和行为边界每次请求的系统消息instance_template描述具体任务、仓库路径、问题陈述任务初始化时next_step_template格式化上一步的执行观察结果每轮工具调用之后这种分层的好处是职责清晰。系统模板保持稳定实例模板随任务变化观察模板随执行结果变化。你在二次开发时如果只想调整 Agent 的「性格」改system_template就够了如果要改变任务描述的格式动instance_template。3.2 变量注入_get_format_dict是唯一入口SWE-agent 不会在每个模板里单独传参而是通过一个统一的格式化字典把所有变量收集起来。核心逻辑在_get_format_dict方法里def _get_format_dict(self, **kwargs) - dict[str, Any]: return dict( command_docsself.tools.config.command_docs, **self.tools.config.env_variables, **kwargs, problem_statementself._problem_statement.get_problem_statement(), repoself._env.repo.repo_name if self._env.repo is not None else , **self._problem_statement.get_extra_fields(), )这段代码揭示了几个关键规律。第一变量来源是多元的工具配置、环境变量、运行时 kwargs、问题陈述、仓库信息都会汇入同一个字典。第二**kwargs的位置很关键它允许调用方覆盖前面的默认值。第三get_extra_fields()提供了扩展点你可以在问题陈述里附加自定义字段它们会自动变成模板变量。这意味着你在模板里写{{problem_statement}}、{{working_dir}}、{{command_docs}}、{{repo}}时不需要关心它们从哪来只要确保_get_format_dict里有对应的键就行。3.3 条件分支与截断处理SWE-agent 的模板里大量使用了 Jinja2 的条件语法。最典型的是观察结果的截断处理Observation: {{observation[:max_observation_length]}}response clipped NOTE Observations should not exceed {{max_observation_length}} characters. {{elided_chars}} characters were elided. Please try a different command that produces less output. /NOTE这里用到了切片语法observation[:max_observation_length]以及配套的elided_chars变量。这种设计把「截断逻辑」和「提示逻辑」放在同一个模板里避免了在 Python 代码里做字符串拼接。另一个常见模式是错误处理模板。比如shell_check_error_template会在 bash 语法错误时渲染把bash_stdout和bash_stderr注入进去。这类模板的特点是变量名和触发条件强绑定你在迁移时需要一并把触发逻辑带过去。3.4 模板语法校验validate_template_jinja_syntaxSWE-agent 用 Pydantic 的model_validator做模板语法检查model_validator(modeafter) def validate_template_jinja_syntax(self) - Self: template_fields [ field for field in self.model_fields.keys() if field.endswith(_template) ] for field in template_fields: value getattr(self, field) _warn_probably_wrong_jinja_syntax(value) return self这个校验器会扫描所有以_template结尾的字段检查是否有明显的 Jinja2 语法错误比如把{{var}}写成了{var}。你在自定义模板时如果发现变量没被替换先检查是不是漏了一层花括号。4. 可复制的 config.toml 与 settings.json 骨架4.1 config.toml模型与 API 通道配置下面这份config.toml骨架可以直接复制使用重点是把 API 地址指向 TaoToken 的统一入口[agent] model_name claude-3-5-sonnet temperature 0.0 max_tokens 4096 [model] api_base https://taotoken.net/api api_key_env TAOTOKEN_API_KEY provider anthropic [environment] working_dir /tmp/swe-agent-test timeout 120 [tools] command_docs config/commands/default.yaml注意api_key_env指向的是环境变量名不是 Key 本身。你需要在 shell 里设置export TAOTOKEN_API_KEY你的Key4.2 settings.json模板与变量配置settings.json负责模板相关的配置。下面这份骨架保留了 SWE-agent 的三层模板结构同时把变量注入点标出来{ templates: { system_template: You are a helpful assistant that can interact with a computer to solve tasks., instance_template: uploaded_files\n{{working_dir}}\n/uploaded_files\nIve uploaded a repository in {{working_dir}}. Consider the following PR description:\npr_description\n{{problem_statement}}\n/pr_description\nCan you help me implement the necessary changes?, next_step_template: OBSERVATION:\n{{observation}}, next_step_truncated_observation_template: Observation: {{observation[:max_observation_length]}}response clipped\nNOTE{{elided_chars}} characters were elided./NOTE }, variables: { max_observation_length: 4096, working_dir: /tmp/swe-agent-test } }这份配置的关键在于variables块。你可以把max_observation_length、working_dir这类运行时参数放在这里它们会通过_get_format_dict的**kwargs注入到模板里。4.3 模板渲染的最小验证脚本为了确认模板能正确渲染写一个最小脚本from jinja2 import Template format_dict { working_dir: /tmp/swe-agent-test, problem_statement: Fix the null pointer in parser.py, observation: File parser.py updated successfully., max_observation_length: 4096, elided_chars: 0, } instance_tpl Template( uploaded_files\n{{working_dir}}\n/uploaded_files\n Consider the following PR description:\n pr_description\n{{problem_statement}}\n/pr_description ) print(instance_tpl.render(**format_dict))运行后你应该看到working_dir和problem_statement都被正确替换。如果输出里还残留{{...}}说明变量名拼写和format_dict的键不一致。5. 验证请求通过 TaoToken 完成一次模板渲染验证模板本身渲染通过之后下一步是把它接到真实的模型调用上。这里用 TaoToken 的模型对话通道做一次端到端验证。先确认你的环境变量已经设置echo $TAOTOKEN_API_KEY然后用 curl 发一个最小请求把渲染后的模板作为消息内容curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-3-5-sonnet, max_tokens: 256, system: You are a helpful assistant that can interact with a computer to solve tasks., messages: [ { role: user, content: uploaded_files\n/tmp/swe-agent-test\n/uploaded_files\nConsider the following PR description:\npr_description\nFix the null pointer in parser.py\n/pr_description } ] }如果返回结果里模型正确理解了任务上下文说明你的模板渲染和 API 通道都通了。如果你想在网页端快速对比不同模型对同一段模板的响应可以用模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite把渲染后的 Prompt 贴进去切换模型观察输出差异。这一步在调试system_template的措辞时特别有用。如果你打算长期跑 SWE-agent 做代码任务反复手动调用会比较累。Coding Plan 提供了更适合持续编码场景的通道https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite6. 本篇常见错排查6.1 变量没被替换输出里还有{{...}}最常见的原因是变量名拼写不一致。SWE-agent 的变量命名用下划线法比如problem_statement不是problemStatement。另一个原因是_get_format_dict里没有对应的键检查你的settings.json的variables块是否包含了该变量。6.2 Jinja2 语法报错unexpected {这通常是把{{var}}写成了{var}。SWE-agent 的validate_template_jinja_syntax会给出警告但不会阻止运行。如果你在日志里看到probably wrong jinja syntax回去检查模板字段的花括号层数。6.3 API 返回 401 或 403先确认TAOTOKEN_API_KEY环境变量在当前 shell 里可见。如果你用的是config.toml里的api_key_env注意它读的是环境变量名不是 Key 值。另外检查api_base是否写成了https://taotoken.net/api不要多加或漏掉路径段。6.4 模板渲染通过但模型行为异常这种情况多半是system_template和instance_template的职责混淆了。系统模板应该只定义角色任务上下文放在实例模板里。如果你把任务描述写进了系统模板模型可能会在后续轮次里重复执行同一个任务。6.5 观察结果被截断但提示信息不完整检查next_step_truncated_observation_template里的elided_chars变量是否被正确注入。这个值通常由 Python 侧计算如果你在迁移时只复制了模板没复制计算逻辑截断提示就会显示为 0 或空。7. 继续接入与排障的入口模板体系跑通之后你可能会遇到更细的接入问题比如自定义工具后command_docs没有更新或者切换模型后thought_action解析器不兼容。这类问题建议直接对照接入文档排查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你需要重新生成或管理 KeyAPI Keys 页面在这里https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite我自己的习惯是每次改完模板先跑一遍最小渲染脚本确认变量替换无误再发真实请求。这样能把「模板问题」和「模型问题」分开排查起来快很多。
