企业官网建设流程全解析

如何自定义Zap的系统提示词：minijinja模板编辑完整教程

【免费下载链接】zapZap is an open, local-first terminal with first-class AI and agent support.项目地址: https://gitcode.com/gh_mirrors/warp50/zap

Zap 是一款开放、本地优先的 AI 终端，其 AI 代理的行为由**系统提示词（system prompt）**驱动。本文带你快速掌握 Zap 系统提示词的 minijinja 模板体系：模板放在哪里、如何按模型自动分发、Jinja2 语法怎么改、改完后如何验证——让你能精确"调教"Zap 代理的语气、工具策略与全局规则。

系统提示词在 Zap 中如何生成？

当你使用 BYOP（自带模型）与 Zap 代理对话时，发送内容会经历 4 步流水线：

1. 收集上下文：Zap 把当前工作目录、Shell、操作系统、Git 分支、可用技能（Skills）、项目规则等信息打包成AIAgentContext；
2. 拍平成模板变量：prompt_renderer.rs中的collect_prompt_context把这些信息转成扁平的PromptContext结构（含cwd、shell、git、skills、user_rules、available_tools等字段）；
3. 按模型选模板：pick_template根据模型 id 子串匹配，从 9 个系统模板中挑一个；
4. minijinja 渲染：最终生成发给上游模型的 system 字符串。

💡 所有模板通过include_str!在编译期打进二进制，修改模板需要重新编译才能生效。

9个系统模板：你的模型命中哪一份？

模板文件位于 app/src/ai/agent_providers/prompts/system/，按模型家族分发：

匹配逻辑（见 prompt_renderer.rs 的pick_template_by_model）大小写不敏感，OpenRouter 的provider/model形式也能正确命中，自定义模型名会安全落回default.j2。

模板结构：用 partials 组合系统提示词

各家族模板只写"个性"部分，公共片段全部抽成 partials，位于 prompts/partials/，由 footer.j2 统一拼装：

• env.j2：工作目录、Shell、平台、Git 分支、日期
• skills.j2：可用技能清单（含skill_path，供模型调用read_skill）
• user_rules.j2：用户在设置中创建的全局规则
• project_rules.j2：项目级规则文件
• tool_aliases.j2：本轮实际可用的工具白名单（动态渲染，不硬编码）
• thinking_language.j2：内部思考语言约束
• plan_mode.j2：/plan只读研究模式注入的约束块

以 env.j2 为例，你能直观看到 minijinja 的三大语法：变量插值{{ cwd | default("(unknown)") }}、条件{% if shell %}、过滤器default。改模板时只需熟悉这三个即可覆盖 90% 的场景。

动手改模板：3个实用场景

场景 1：调整回复风格。打开 default.j2，在# Tone and style一节中，默认要求"少于 4 行"的极简回答。你可以把它改成"回答控制在 10 行以内并给出示例"，适合教学场景。

场景 2：为特定模型定制开场白。比如 anthropic.j2 第一句是 "You are Zap, the best coding agent on the planet."，各家族模板的"人设"不同——想统一人设，就只改对应家族文件的第一段。

场景 3：新增一段全局约束。在任意 system 模板末尾追加一个# Your rules小节即可，因为 footer 会把它渲染在环境信息之后。若只想免编译生效，推荐下一条"零代码"方案。

零代码方案：全局 Rules 注入

不想碰模板？Zap 支持在设置 → Agents → Rules创建全局规则，内容会经 user_rules.j2 自动渲染进 system prompt，且对所有模型家族生效。每条规则可带名称（渲染为## 名称二级标题），例如"Rust 代码一律使用 snake_case"。这是日常调教最轻量的入口。

改完怎么验证？

• 单元测试：prompt_renderer.rs 内置了 20+ 个测试，覆盖模板分发、环境块渲染、Plan Mode 注入、Rules 渲染与空块省略，改模板后跑一遍cargo test即可回归；
• 兜底机制：任何模板加载或渲染失败都会自动降级为内置的fallback_system短提示（见 prompt_renderer.rs 中的fallback_system），不会让对话中断；
• 缓存提示：模板中避免加入"每请求都变"的动态内容（如精确到秒的时间），否则会击穿上游供应商的 prompt cache。Zap 因此把current_time只保留到"日"粒度。

常见问题

Q：改了模板为什么没生效？模板是编译期嵌入的，需重新编译并重启应用。

Q：我接的模型不在上表里，走哪个模板？走 default.j2 兜底；Ollama 本地模型固定走 local.j2 短模板，避免长系统提示淹没小模型上下文。

Q：能自己新增一个模型家族的模板吗？可以：在 system/ 下新建.j2文件，在build_env注册、在pick_template_by_model加一条子串匹配，最后补一条分发测试即可。

Q：/plan命令和系统提示词什么关系？/plan触发的只读研究模式由 plan_mode.j2 条件注入，模板中的"Stop and wait"引导语即来自这里。

小结

掌握 minijinja 模板后，Zap 的 AI 代理就不再是"出厂设置"，而是真正贴合你工作流的专属助手。

【免费下载链接】zapZap is an open, local-first terminal with first-class AI and agent support.项目地址: https://gitcode.com/gh_mirrors/warp50/zap